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 groups are denied by default at config-generation time — 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, web) are not exposed directly — Pinchy replaces them with its own sandboxed tools and integration tools. This gives Pinchy full control over what each agent can do.

Under the hood, Pinchy converts its allow-list into a deny-list at config generation time using computeDeniedGroups(). This function takes the list of tool IDs an admin has enabled and returns all tool groups that should be blocked. The result is written into each agent’s tools.deny array in the OpenClaw config.

This conversion runs automatically whenever the OpenClaw config is regenerated — admins never interact with the deny-list directly.

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
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, 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 account and grant an agent access to it, Pinchy enables email tools based on which operations you check. Each permission maps to a specific set of tools.

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

Permissions are additive — granting Send automatically includes Read and Draft. Each permission is selected per-agent, so you can have one agent that only reads email and another that can send on your behalf.

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:

Template	Default tools	Use case
Knowledge Base	pinchy_ls, pinchy_read (safe tools)	Answer questions from selected documents
Custom Agent	None	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. Four 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. Plugin path validation — the pinchy-files plugin checks every requested path against the agent’s allowed directories
4. 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.