Agent Permissions

Why agent permissions matter

AI agents are powerful — but in an enterprise setting, they must be constrained. An agent that can read any file on the server or execute arbitrary commands is a liability. Pinchy enforces per-agent permissions so each agent can only use the tools an admin explicitly enables.

Allow-list approach

Pinchy uses an allow-list model: agents have no tools by default. An admin must explicitly enable each tool an agent is allowed to use. This is the opposite of a deny-list approach where everything is allowed unless blocked — with Pinchy, nothing is allowed unless granted.

This means a newly created agent cannot access files, run commands, or browse the web until an admin configures its permissions.

Tool categories

Pinchy organizes tools into two categories:

Safe Tools

Safe tools provide sandboxed access to approved directories and the agent's own workspace. The agent cannot access anything outside those boundaries.

Every agent can always list and read files from its own workspace — any text-based file you upload in a chat is immediately accessible. This includes Markdown, CSV, JSON, source code, and more, in addition to PDF text extraction and image analysis.

| Tool | Always on? | What it does | | ------------------ | ---------- | ------------------------------------------------------------------------------------------------------------- | | Read workspace | ✓ always | List and read any file in the agent's workspace (both uploads/ and workbench/), including PDFs and images |

The workspace has two subdirectories: uploads/ holds files the user attached in chat, and workbench/ is the agent's own writable area for notes, exports, and drafts. See Agent Workspaces for the full three-zone model.

The Knowledge Base section below the tools lets you select which directories under /data/ this agent can also read. These are admin-curated directories mounted into the container — separate from the agent's own workspace. Every access request is validated at runtime against the configured paths.

Web Search Tools

Web search tools give the agent access to live web information via the Brave Search API. These require a Brave Search API key configured in Settings → Integrations.

| Tool | What it does | | ------------------- | --------------------------------------------------------------------- | | Search the web | Query Brave Search and return ranked results (pinchy_web_search) | | Fetch web pages | Download and extract readable content from a URL (pinchy_web_fetch) |

When web search tools are enabled, additional per-agent filters appear: Domain restrictions (with Include/Exclude modes per domain), Freshness, Language, and Region. See Set Up Web Search for details.

Data exfiltration risk

If an agent has Fetch web pages enabled alongside access to sensitive data (files or Odoo records), Pinchy shows a security warning. A malicious web page could contain instructions that trick the agent into encoding private data into a URL. Mitigate this by adding Include domain restrictions that limit the agent to known, trusted sites.

Powerful Tools

Powerful tools let the agent change state outside the conversation — write files to disk, mutate records in connected systems, send email. Only enable them if you understand the consequences.

| Tool | Tool ID | What it does | | --------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Write files | pinchy_write | Save files into the agent's own workbench/ directory (and the user-facing uploads/, kept writable for compatibility). Agents must explicitly request overwrite on existing files. |

Powerful integration tools (Odoo write/delete, email draft/send) are covered in their own sections below.

Pinchy does not expose a shell-execution tool or an unrestricted "read any file" tool. OpenClaw's native filesystem and shell tools are never added to an agent's allow-list, so they stay unreachable — see How permissions reach OpenClaw below. If you need shell-style automation, do it through a custom OpenClaw plugin so the actions are bounded by the plugin's contract.

The Permissions tab

Admins configure tool permissions in the Permissions tab of a shared agent's settings page. To access it:

1. Open a shared agent's chat
2. Click the settings icon (gear) to open Agent Settings
3. Select the Permissions tab

The Permissions tab shows all available tools grouped by category. Check or uncheck tools to control what the agent can do, then click Save.

Note

The Permissions tab is only visible to admins and only for shared agents. Personal agents (the auto-created Smithers each user gets) don't have this tab — they run with default tools only.

For the full list of tabs in Agent Settings and who sees which, see Agent Settings.

Configuring directory access

The Allowed Directories picker appears in the Knowledge Base section of the Permissions tab. Select which directories under /data/ this agent should be able to read — these are in addition to the agent's own workspace files.

For example, if you mounted your HR policies at /data/hr-policies, select that directory to let the agent read those documents — and nothing else.

See the Mount Data Directories guide for instructions on making directories available.

How permissions reach OpenClaw

Pinchy controls what tools an agent can use. OpenClaw's native tools (shell, file system, raw web, the built-in browser) are not exposed directly — Pinchy replaces them with its own sandboxed and integration tools. This gives Pinchy full control over what each agent can do.

Under the hood, Pinchy emits a fail-closed allow-list into each agent's OpenClaw config. The computeAllowedTools() function returns exactly the Pinchy plugin tools plus a small set of read-only built-ins (memory search and retrieval, PDF and image reading, session status), and Pinchy writes that set into the agent's tools.allow array — with no tool profile set, so OpenClaw treats it as an absolute allow-list. Every other built-in is therefore denied by default, including tools added in future OpenClaw versions: shell execution, raw file access, the native web and browser tools, scheduling (cron), gateway control, cross-session spawning, outbound messaging, and the media generators.

This is the same fail-closed principle as the per-agent allow-list above, applied one layer down at the runtime boundary: rather than chasing a deny-list that must be revisited on every OpenClaw upgrade, Pinchy lists only what it trusts and denies the rest by default. It runs automatically whenever the OpenClaw config is regenerated — admins never interact with it directly. Per-agent tool gating still happens inside each Pinchy plugin, which only registers the tools an agent is permitted to use; the allow-list is the outer boundary that keeps everything else out.

Integration tools

Odoo tools

When you connect Odoo and grant an agent access to it, Pinchy automatically enables the appropriate tools based on the access level you choose. You don't need to enable these tools manually — they're managed through the Permissions tab.

| Tool | Tool ID | What it does | Access level required | | ------------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------- | --------------------- | | List models | odoo_list_models | List all available Odoo models on the connection | Read-only | | Describe model | odoo_describe_model | Discover fields and types for a specific model | Read-only | | Read data | odoo_read | Query records with filters and field selection | Read-only | | Count records | odoo_count | Count matching records without transferring data | Read-only | | Aggregate data | odoo_aggregate | Server-side sums, averages, and grouping | Read-only | | Create records | odoo_create | Create new records | Read & Write | | Schedule activity | odoo_schedule_activity | Schedule a follow-up activity (planned to-do) on a record so it surfaces in Odoo's activity views | Read & Write | | Complete activity | odoo_complete_activity | Mark a scheduled activity as done — posts a completion note and clears it from the to-do list | Read & Write | | Reschedule activity | odoo_reschedule_activity | Change a scheduled activity's due date and/or assignee without closing it | Read & Write | | Confirm sale order | odoo_confirm_order | Confirm a quotation (Odoo's action_confirm — creates deliveries/procurement; not a raw state write) | Read & Write | | Apply inventory count | odoo_apply_inventory | Post a counted inventory adjustment on a stock.quant (action_apply_inventory) | Read & Write | | Validate picking | odoo_validate_picking | Validate a stock transfer (button_validate); hands off if Odoo needs a backorder decision | Read & Write | | Mark MO done | odoo_mark_mo_done | Mark a manufacturing order done (button_mark_done); hands off if Odoo needs a backorder/consumption decision | Read & Write | | Set approval decision | odoo_set_approval | Approve/refuse an expense report, purchase order, leave request, or approval request via its blessed method | Read & Write | | Update records | odoo_write | Modify existing records | Read & Write | | Attach file | odoo_attach_file | Attach an uploaded file to an existing record as ir.attachment | Read & Write | | Delete records | odoo_delete | Delete records | Full |

For example, setting an agent to "Read-only" enables the five read-shaped tools. "Read & Write" adds create, the three activity tools (schedule / complete / reschedule), the governed action tools (confirm order, apply inventory, validate picking, mark MO done, set approval), write, and attach-file. "Full" adds delete.

Cross-company write protection

For multi-company Odoo databases, the pinchy-odoo plugin refuses to write a record whose embedded _pinchy_ref company tag disagrees with the company implied by the relation chain (top-level field only). This prevents a class of silent cross-company mistakes — for example, applying a Company A fiscal position to a partner that lives under Company B. See Connect Odoo → Multi-company databases for the full story.

Pinchy keeps the deprecated alias odoo_schema (collapsed into odoo_list_models + odoo_describe_model during the v0.5.4 split) recognised in stored allowed_tools arrays so older agents keep working, but the permissions UI hides it.

Web Search tools

Web search tools are enabled individually per agent via checkboxes in the Permissions tab. Unlike Odoo tools, there are no access levels — you simply check the tools you want.

| Tool | Tool ID | What it does | | ------------------- | ------------------- | --------------------------------------- | | Search the web | pinchy_web_search | Query Brave Search for relevant results | | Fetch web pages | pinchy_web_fetch | Download and read content from a URL |

Each agent can also have per-agent filters (Domain restrictions with Include/Exclude modes, Freshness, Language, Region) that control what the agent can access. See Set Up Web Search for configuration details.

Email tools

When you connect a Gmail or Microsoft 365 mailbox and grant an agent access to it, Pinchy enables email tools based on which operations you check. Each operation is an independent checkbox that grants its own toolset — check every operation the agent needs.

| Permission | Tools enabled | What the agent can do | | ----------------- | ------------------------------------------------------------------ | ------------------------------------------------------- | | Read messages | email_list, email_read, email_search, email_get_attachment | List, read, and search emails, and download attachments | | Create drafts | email_draft | Create draft emails, including reply drafts | | Send messages | email_send | Send emails immediately — cannot be undone |

Each permission is selected per-agent and does not imply the others — granting Send does not also grant Read or Draft. Check every operation the agent needs: for example, an agent that both reads and sends mail needs Read messages and Send messages both checked. You can have one agent that only reads email and another that can send on your behalf. email_get_attachment downloads an attachment into the agent's workspace for other tools to use (for example reading a PDF or attaching it to an Odoo record) — it's part of the Read messages permission, not a separate one.

Send is powerful

Send messages lets the agent send email from the connected account without human review. Prefer Create drafts when a human can review before sending — it's safer by default.

For the full setup walkthrough, see Connect Email. For details on setting up connections in general, see Integrations.

Agent templates and default permissions

When you create an agent, you pick a template. Each template comes with different default tool permissions. Every new agent also starts with Write files (pinchy_write) enabled by default — reading the workspace is always on, and the create flow adds write so the agent can save notes and exports out of the box. You can toggle it off later in the Permissions tab.

| Template | Default tools | Use case | | ------------------ | --------------- | -------------------------------------------------- | | Knowledge Base | Write files | Answer questions from selected documents | | Custom Agent | Write files | Start from scratch, configure permissions manually |

After creating an agent, you can change its permissions at any time via the Permissions tab.

Defense in depth

Pinchy does not rely on any single layer for security. Five layers work together:

1. Docker volumes — only directories explicitly mounted into the container are accessible at all
2. Allow-list enforcement — only tools an admin explicitly enables are available to the agent
3. Runtime tool allow-list — Pinchy emits an absolute tools.allow to OpenClaw, so built-ins Pinchy never surfaces (shell, raw file access, cron, gateway control, the native browser, …) are unreachable even if a plugin or future OpenClaw version would otherwise expose them
4. Plugin path validation — the pinchy-files plugin checks every requested path against the agent's allowed directories
5. Symlink resolution — paths are resolved to their real location before validation, preventing symlink-based escapes

If any one layer fails, the others still prevent unauthorized access.

Agent access control

Not every user can see every agent. Pinchy enforces access rules:

• Admins can access all agents — personal and shared
• Users can access shared agents (created by anyone) and their own personal agent
• Users cannot see or access other users' personal agents

Only admins can view and modify the Permissions tab. Regular users can chat with agents they have access to, but cannot change what tools those agents use.

Note

All permission changes are logged in the audit trail. When an admin enables or disables tools for an agent, the change is recorded with the admin's identity, the affected agent, and the old and new permissions.

The /data/ convention

All agent-accessible files live under /data/ inside the Pinchy container. This is mounted as a Docker volume, and you can bind-mount host directories into subdirectories of /data/.

For example, if you mount your company's HR policies at /data/hr-policies, an agent configured to access that directory can read those documents — and nothing else.

See the Mount Data Directories guide for setup instructions.