Principle:Openclaw Openclaw Tool Execution Policy
| Knowledge Sources | |
|---|---|
| Domains | Agent_Runtime, Security |
| Last Updated | 2026-02-06 12:00 GMT |
Overview
Tool execution policy is the governance framework that controls which tools an agent may invoke during inference, enforcing allow/deny lists at multiple scopes, sandbox isolation rules, and per-provider or per-group restrictions before any tool call reaches execution.
Description
OpenClaw agents have access to a rich set of tools: shell execution, file operations, web browsing, messaging across channels, session management, memory, scheduling, and more. Unrestricted tool access would be a security and operational risk, especially in multi-tenant or group-chat environments where different users and contexts warrant different capabilities.
Tool execution policy addresses this by applying a layered filtering model that evaluates tool permissions at multiple scopes before a tool is made available to the LLM or before a tool call is executed:
Global policy: Defined at the top-level tools configuration key. Specifies baseline allow/deny lists that apply to all agents unless overridden. Also supports alsoAllow for additive grants on top of an implicit allow-all.
Agent policy: Defined per-agent in agents.list[].tools. Narrows or extends the global policy for a specific agent. Agent policies take precedence over global policies.
Provider policy: Defined per-provider (or per-model) via tools.byProvider at global or agent scope. Allows restricting tools when using specific LLM providers (e.g., denying shell access when using a less-trusted model).
Group policy: Resolved per-channel and per-group, allowing group-specific tool restrictions. This is critical for multi-user group chats where the agent should have limited capabilities compared to a private DM session.
Subagent policy: A hardcoded deny list prevents subagents (spawned child agents) from accessing session management, system admin, interactive setup, and scheduling tools that should remain under the orchestrating parent agent's control.
Profile system: Tool profiles provide named presets (e.g., "safe", "full") that bundle common allow/deny configurations, reducing duplication across agents.
The policy model follows a deny-first evaluation: if a tool matches any deny pattern at any scope, it is blocked. Within the allow dimension, an empty allow list means "allow all" (no restriction), while a populated allow list acts as a whitelist. The alsoAllow mechanism enables additive grants without replacing the base allowlist.
Usage
Apply this principle whenever:
- Adding a new tool that should be restricted by default in certain contexts.
- Configuring agents for multi-tenant or group-chat deployments where tool access must differ by context.
- Debugging why a tool is unavailable to a particular agent or in a particular group.
- Implementing per-provider restrictions (e.g., limiting capabilities when using third-party models).
- Extending the subagent deny list when new sensitive tools are added.
Theoretical Basis
The policy system implements a multi-layer access control list (ACL) with the following evaluation order:
- Pattern compilation: Allow and deny lists are expanded (tool groups are resolved) and compiled into exact-match, wildcard, or regex patterns.
- Deny-first evaluation: For each policy layer, if the tool name matches any deny pattern, the tool is blocked.
- Allow evaluation: If an allow list exists and the tool does not match any allow pattern, the tool is blocked. Special case:
apply_patchis implicitly allowed whenexecis in the allow list. - Multi-policy intersection:
isToolAllowedByPoliciesrequires the tool to pass every active policy layer (global, provider, agent, group).
The pattern language supports:
- Exact match:
"exec"matches only the tool namedexec. - Wildcard:
"sessions_*"matches any tool starting withsessions_. - Universal:
"*"matches all tools.
Tool group expansion (via expandToolGroups) translates semantic group names into their constituent tool names, providing a higher-level abstraction for policy authors.
The layered model ensures defense in depth: even if one policy layer is misconfigured, other layers provide additional protection. The subagent deny list provides a capability reduction guarantee for child agents, following the principle of least privilege.