Sandbox vs Tool Policy vs Elevated

OpenClaw ships three controls that overlap in purpose but behave differently:

Sandbox (agents.defaults.sandbox.* / agents.entries.*.sandbox.*) determines where tool execution happens (sandbox backend versus host).
Tool policy (tools.*, tools.sandbox.tools.*, agents.entries.*.tools.*) determines which tools are permitted or denied.
Elevated (tools.elevated.*, agents.entries.*.tools.elevated.*) serves as an exec-only escape hatch for running outside the sandbox while sandboxed (gateway by default, or node when the exec target is set to node).

Quick debug

To see what OpenClaw is really doing, check the inspector:

openclaw sandbox explain
openclaw sandbox explain --session agent:main:main
openclaw sandbox explain --agent work
openclaw sandbox explain --json

Its output includes:

the active sandbox mode, scope, and workspace access
whether the session is sandboxed at the moment (main versus non-main)
the effective sandbox tool allow/deny list (including whether it came from agent, global, or default)
elevated gates and fix-it key paths

Sandbox: where tools run

Sandboxing is governed by agents.defaults.sandbox.mode:

"off": the host runs everything.
"non-main": only non-main sessions get sandboxed (a frequent surprise for groups and channels).
"all": sandboxing applies to everything.

What the sandbox can see is set by agents.defaults.sandbox.workspaceAccess: "none", "ro", or "rw".

The complete matrix (scope, workspace mounts, images) is in Sandboxing.

Bind mounts (security quick check)

docker.binds cuts through the sandbox filesystem: whatever you mount shows up inside the container with the mode you specify (:ro or :rw).
Leaving the mode out defaults to read-write; :ro is the safer pick for source and secrets.
scope: "shared" skips per-agent binds (only global binds take effect).
OpenClaw checks bind sources twice: once against the normalized source path, then again after resolving through the deepest existing ancestor. Symlink-parent escapes cannot get around blocked-path or allowed-root checks.
Leaf paths that do not exist are still checked safely. If /workspace/alias-out/new-file resolves through a symlinked parent to a blocked path or outside the configured allowed roots, the bind gets rejected.
Mounting /var/run/docker.sock basically hands host control to the sandbox; do it only on purpose.
Workspace access (workspaceAccess) works independently of bind modes.

For a per-agent setup with multiple host folders, access modes, and the external-source safety opt-in, see Multiple folders for one agent.

Tool policy: which tools exist/are callable

Two layers are relevant:

Tool profile: tools.profile and agents.entries.*.tools.profile (the base allowlist)
Provider tool profile: tools.byProvider[provider].profile and agents.entries.*.tools.byProvider[provider].profile
Global/per-agent tool policy: tools.allow/tools.deny and agents.entries.*.tools.allow/agents.entries.*.tools.deny
Provider tool policy: tools.byProvider[provider].allow/deny and agents.entries.*.tools.byProvider[provider].allow/deny
Sandbox tool policy (active only while sandboxed): tools.sandbox.tools.allow/tools.sandbox.tools.deny and agents.entries.*.tools.sandbox.tools.*

General guidelines:

deny takes precedence in every case.
When allow contains any value, all other rules are considered blocked.
Tool policy acts as the final barrier: /exec is powerless to reverse a refusal of an exec tool.
Tool policy restricts which tools are available based on their names; it never examines the effects of operations inside exec. Even when exec is permitted, rejecting write, edit, or apply_patch fails to make shell commands read-only.
/exec merely adjusts session defaults for approved senders; it grants no tool permissions.
Provider tool keys accept either provider (for instance, anthropic) or provider/model (for instance, openai/gpt-5.4).
Gateway logs record agents/tool-policy audit entries whenever a tool policy step removes tools or a sandbox tool policy denies a call. Run openclaw logs to view the rule label, config key, and names of affected tools.

Tool groups (shorthands)

Tool policies at the global, agent, and sandbox levels accept group:* entries that expand into multiple tools:

{
  tools: {
    sandbox: {
      tools: {
        allow: ["group:runtime", "group:fs", "group:sessions", "group:memory"],
      },
    },
  },
}

Available groups:

Group	Tools
`group:runtime`	`exec`, `process`, `code_execution` (`bash` works as an alias for `exec`)
`group:fs`	`read`, `write`, `edit`, `apply_patch`
`group:sessions`	`sessions`, `sessions_list`, `sessions_history`, `sessions_search`, `conversations_list`, `conversations_send`, `conversations_turn`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status`, `suggest_task`, `dismiss_task`
`group:memory`	`memory_search`, `memory_get`
`group:web`	`web_search`, `x_search`, `web_fetch`
`group:ui`	`browser`, `screen`, `terminal`, `canvas`, `progress_card`, `show_widget`
`group:automation`	`heartbeat_respond`, `cron`, `gateway`
`group:messaging`	`message`
`group:nodes`	`nodes`, `computer`
`group:agents`	`agents_list`, `get_goal`, `create_goal`, `update_goal`, `progress_card`, `ask_user`, `skill_workshop`
`group:media`	`image`, `image_generate`, `music_generate`, `video_generate`, `tts`
`group:openclaw`	most built-in OpenClaw tools (excludes the `read`/`write`/`edit`/`apply_patch`/`exec`/`process` fs and runtime primitives, `canvas`, and provider plugins)
`group:plugins`	all loaded plugin-owned tools, including configured MCP servers exposed through `bundle-mcp`

For agents that only read, block group:runtime and any filesystem tools that modify data, unless the sandbox filesystem policy or a separate host boundary already enforces read-only access.

When MCP servers run inside the sandbox, the sandbox tool policy acts as a second approval layer. If mcp.servers is set but sandboxed turns reveal only built-in tools, append bundle-mcp, group:plugins, or a server-prefixed MCP tool name/glob such as outlook__send_mail or outlook__* to tools.sandbox.tools.alsoAllow, then restart/reload the gateway and recapture the tool list. Server globs rely on the provider-safe MCP server prefix: non-[A-Za-z0-9_-] characters map to -, names lacking a leading letter receive an mcp- prefix, and long or duplicate prefixes may be truncated or suffixed.

openclaw doctor currently validates this shape for OpenClaw-managed servers in mcp.servers. MCP servers loaded from bundled plugin manifests or Claude .mcp.json pass through the same sandbox gate, but this diagnostic does not yet list those sources; apply the same allowlist entries if their tools vanish in sandboxed turns.

Elevated: exec-only "run on host"

Elevated mode adds no tools; it only changes exec.

While sandboxed, /elevated on (or exec with elevated: true) executes outside the sandbox (approvals may still apply).
Use /elevated full to bypass exec approvals for the session.
If you are already running direct, elevated does nothing meaningful (still gated).
Elevated is not skill-scoped and does not override tool allow/deny.
Elevated does not grant arbitrary cross-host overrides from host=auto; it follows the normal exec target rules and only preserves node when the configured/session target is already node.
/exec is distinct from elevated. It only changes per-session exec defaults for authorized senders.

Gates:

Enablement: tools.elevated.enabled (and optionally agents.entries.*.tools.elevated.enabled)
Sender allowlists: tools.elevated.allowFrom.<provider> (and optionally agents.entries.*.tools.elevated.allowFrom.<provider>)

See Elevated Mode.

Common "sandbox jail" fixes

"Tool X blocked by sandbox tool policy"

Fix-it keys (pick one):

Disable sandbox: agents.defaults.sandbox.mode=off (or per-agent agents.entries.*.sandbox.mode=off)
Allow the tool inside sandbox:
- remove it from tools.sandbox.tools.deny (or per-agent agents.entries.*.tools.sandbox.tools.deny)
- or add it to tools.sandbox.tools.allow (or per-agent allow)
Check openclaw logs for the agents/tool-policy entry. It records the sandbox mode and whether the allow or deny rule blocked the tool.

"I thought this was main, why is it sandboxed?"

In "non-main" mode, group/channel keys are not main. Use the main session key (shown by sandbox explain) or switch mode to "off".

Session permission modes: session roots and escalation reviewers
Sandboxing: complete sandbox reference covering modes, scopes, backends, and images
Multi-Agent Sandbox & Tools: per-agent overrides and their precedence
Elevated Mode