Last updated: March 2026
Policy Enforcement
OpenClaw governs what agents can do through three distinct control layers: sandbox (where tools run), tool policy (which tools are callable), and elevated (an exec-only escape hatch). All configuration lives in ~/.openclaw/openclaw.json.
The Three Control Layers
1. Sandbox β where tools run
Controls whether tool execution happens in a Docker container or directly on the host. Configured via agents.defaults.sandbox.mode:
| "off" | All tools run on the host (default for personal setups) |
| "non-main" | Only non-main sessions (groups, channels) are sandboxed |
| "all" | All sessions run in Docker containers |
2. Tool Policy β which tools are callable
Defines which built-in OpenClaw tools an agent can call. Configured with tools.allow and tools.deny at the global level, or agents.list[].tools.allow/deny per-agent. deny always wins. If allow is non-empty, everything else is blocked.
3. Elevated β exec-only escape hatch
When an agent is sandboxed, elevated lets specific exec calls run on the host instead. It does not grant extra tools and does not override tool allow/deny β it only affects where exec runs. Gated by tools.elevated.enabled and tools.elevated.allowFrom.
Tool Groups
Allow/deny lists accept group:* shorthands that expand to multiple tools:
| Group | Expands to |
|---|---|
| group:runtime | exec, bash, process |
| group:fs | read, write, edit, apply_patch |
| group:sessions | sessions_list, sessions_history, sessions_send, sessions_spawn, session_status |
| group:memory | memory_search, memory_get |
| group:ui | browser, canvas |
| group:automation | cron, gateway |
| group:messaging | message |
| group:openclaw | All built-in OpenClaw tools (excludes provider plugins) |
Per-Agent Configuration
Each entry in agents.list can override global tool policy. Here is a real example β the meeting agent has a restricted tool allowlist so it can only read files and query memory:
// ~/.openclaw/openclaw.json (excerpt)
{
"agents": {
"list": [
{
"id": "meeting",
"workspace": "/Users/you/.openclaw/workspace-meeting",
"model": "anthropic/claude-sonnet-4-6",
"tools": {
"allow": ["read", "memory_search", "memory_get", "session_status"]
}
},
{
"id": "redteam",
"workspace": "/Users/you/.openclaw/workspace-redteam",
"model": "anthropic/claude-opus-4-6",
"subagents": {
"allowAgents": ["operator", "librarian"]
}
}
]
}
}
Agents and Their Real Access Patterns
Behavioral constraints on how an agent acts are defined in the workspace AGENTS.md file β separate from the technical tool policy in openclaw.json. Together they form the practical access model:
| Agent | Model | Constraints (AGENTS.md) |
|---|---|---|
| main (Orange) | Opus | Can spawn any subagent; financial ops require human confirmation |
| coding | Sonnet | Full shell in project dirs; blocked command patterns (curl to external, rm -rf /) |
| researcher | Sonnet | Web search, web fetch, file read/write in workspace; can spawn coding + content |
| redteam (CIPHER Commander) | Opus | CTF only; can spawn operator + librarian; no external system attacks |
| operator (GRUNT) | Sonnet | Shell exec for CTF tasks; no subagents |
| meeting | Sonnet | tools.allow: [read, memory_search, memory_get, session_status] only |
Security Audit
OpenClaw ships a built-in security audit command that flags common misconfigurations:
openclaw security audit
openclaw security audit --deep
openclaw security audit --fix
openclaw security audit --json
It checks: gateway auth exposure, browser control exposure, elevated allowlists, and filesystem permissions. Run it after any config change.
Debugging Policy
To see exactly what sandbox and tool policy is active for a given session:
# Check effective policy for the default agent
openclaw sandbox explain
# Check for a specific agent
openclaw sandbox explain --agent coding
# Machine-readable output
openclaw sandbox explain --json
The output shows the effective sandbox mode, whether the session is sandboxed, effective tool allow/deny (with the source: agent config, global config, or default), and elevated gates.
Frequently Asked Questions
What is the difference between AGENTS.md and tool policy in openclaw.json?
AGENTS.md is a Markdown file loaded into the agent's context window β it describes behavioral rules the agent is expected to follow (routing, communication style, what requires human confirmation). Tool policy in openclaw.json is a hard technical constraint enforced by the gateway β the agent cannot call a denied tool regardless of what AGENTS.md says.
Does deny always take precedence over allow?
Yes. Per the OpenClaw docs: "deny always wins." If a tool appears in both allow and deny, it is denied. If allow is non-empty, any tool not in the allow list is implicitly denied.
What security model does OpenClaw assume?
OpenClaw is designed for a personal assistant model: one trusted operator per gateway. It is not a multi-tenant security boundary for adversarial users. If multiple untrusted users can message one tool-enabled agent, they effectively share the same delegated tool authority. For separate trust boundaries, run separate gateway instances.
Authors: Qiushi Wu & Orange π