Use this file to discover all available pages before exploring further.

Multi-agent sandbox and tools

Each agent in a multi-agent setup can override the global sandbox and tool policy. This page covers per-agent configuration, precedence rules, and examples.

Sandboxing

Backends and modes — full sandbox reference.

Sandbox vs tool policy vs elevated

Debug "why is this blocked?"

Elevated mode

Elevated exec for trusted senders.

warning

Auth is scoped by agent: each agent has its own `agentDir` auth store at `~/.openclaw/agents//agent/auth-profiles.json`. Never reuse `agentDir` across agents. Agents can read through to the default/main agent's auth profiles when they do not have a local profile, but OAuth refresh tokens are not cloned into secondary agent stores. If you copy credentials manually, copy only portable static `api_key` or `token` profiles.

Configuration examples

Configuration precedence

When both global (

text

agents.defaults.*

) and agent-specific (

text

agents.list[].*

) configs exist:

Sandbox config

Agent-specific settings override global:


text
agents.list[].sandbox.mode > agents.defaults.sandbox.mode
agents.list[].sandbox.scope > agents.defaults.sandbox.scope
agents.list[].sandbox.workspaceRoot > agents.defaults.sandbox.workspaceRoot
agents.list[].sandbox.workspaceAccess > agents.defaults.sandbox.workspaceAccess
agents.list[].sandbox.docker.* > agents.defaults.sandbox.docker.*
agents.list[].sandbox.browser.* > agents.defaults.sandbox.browser.*
agents.list[].sandbox.prune.* > agents.defaults.sandbox.prune.*

note

`agents.list[].sandbox.{docker,browser,prune}.*` overrides `agents.defaults.sandbox.{docker,browser,prune}.*` for that agent (ignored when sandbox scope resolves to `"shared"`).

Tool restrictions

The filtering order is:

Tool profile

`tools.profile` or `agents.list[].tools.profile`.

Provider tool profile

`tools.byProvider[provider].profile` or `agents.list[].tools.byProvider[provider].profile`.

Global tool policy

`tools.allow` / `tools.deny`.

Provider tool policy

`tools.byProvider[provider].allow/deny`.

Agent-specific tool policy

`agents.list[].tools.allow/deny`.

Agent provider policy

`agents.list[].tools.byProvider[provider].allow/deny`.

Sandbox tool policy

`tools.sandbox.tools` or `agents.list[].tools.sandbox.tools`.

Subagent tool policy

`tools.subagents.tools`, if applicable.

Tool policies support

text

group:*

shorthands that expand to multiple tools. See Tool groups for the full list.

Per-agent elevated overrides (

text

agents.list[].tools.elevated

) can further restrict elevated exec for specific agents. See Elevated mode for details.

Migration from single agent

```json} { "agents": { "defaults": { "workspace": "~/.openclaw/workspace", "sandbox": { "mode": "non-main" } } }, "tools": { "sandbox": { "tools": { "allow": ["read", "write", "apply_patch", "exec"], "deny": [] } } } } ``` ```json} { "agents": { "list": [ { "id": "main", "default": true, "workspace": "~/.openclaw/workspace", "sandbox": { "mode": "off" } } ] } } ```

note

Legacy `agent.*` configs are migrated by `openclaw doctor`; prefer `agents.defaults` + `agents.list` going forward.

Tool restriction examples

```json} { "tools": { "allow": ["read"], "deny": ["exec", "write", "edit", "apply_patch", "process"] } } ``` ```json} { "tools": { "allow": ["read", "exec", "process"], "deny": ["write", "edit", "apply_patch", "browser", "gateway"] } } ``` ```json} { "tools": { "sessions": { "visibility": "tree" }, "allow": ["sessions_list", "sessions_send", "sessions_history", "session_status"], "deny": ["exec", "write", "edit", "apply_patch", "read", "browser"] } } ```


text
`sessions_history` in this profile still returns a bounded, sanitized recall view rather than a raw transcript dump. Assistant recall strips thinking tags, `<relevant-memories>` scaffolding, plain-text tool-call XML payloads (including `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>`, and truncated tool-call blocks), downgraded tool-call scaffolding, leaked ASCII/full-width model control tokens, and malformed MiniMax tool-call XML before redaction/truncation.

Common pitfall: "non-main"

warning

`agents.defaults.sandbox.mode: "non-main"` is based on `session.mainKey` (default `"main"`), not the agent id. Group/channel sessions always get their own keys, so they are treated as non-main and will be sandboxed. If you want an agent to never sandbox, set `agents.list[].sandbox.mode: "off"`.

Testing

After configuring multi-agent sandbox and tools:

Check agent resolution

```bash} openclaw agents list --bindings ```

Verify sandbox containers

```bash} docker ps --filter "name=openclaw-sbx-" ```

Test tool restrictions

* Send a message requiring restricted tools. * Verify the agent cannot use denied tools.

Monitor logs

```bash} tail -f "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/logs/gateway.log" | grep -E "routing|sandbox|tools" ```

Troubleshooting

Elevated mode
Multi-agent routing
Sandbox configuration
Sandbox vs tool policy vs elevated — debugging "why is this blocked?"
Sandboxing — full sandbox reference (modes, scopes, backends, images)
Session management

OpenClaw Docs

Multi-agent sandbox and tools

Sandboxing

Sandbox vs tool policy vs elevated

Elevated mode

warning

Configuration examples

Configuration precedence

Sandbox config

note

Tool restrictions

Tool profile

Provider tool profile

Global tool policy

Provider tool policy

Agent-specific tool policy

Agent provider policy

Sandbox tool policy

Subagent tool policy

Migration from single agent

note

Tool restriction examples

Common pitfall: "non-main"

warning

Testing

Check agent resolution

Verify sandbox containers

Test tool restrictions

Monitor logs

Troubleshooting

Related