Multi-agent sandbox and tools

기준일: 2026-07-26
난이도: 중급
공식 기준: Multi-agent sandbox and tools

개요

이 페이지는 OpenClaw Multi-agent sandbox and tools 도구(파라미터, 권한, 설정, CLI)를 공식 문서 기준으로 정리합니다.

공식 요약: Per-agent sandbox + tool restrictions, precedence, and examples

도구 가시성은 profile / allow·deny policy / sandbox / channel 권한에 따라 달라집니다. 최신 스키마는 항상 공식 문서를 우선합니다.

공식 문서 기반 상세

아래는 공식 tools/multi-agent-sandbox-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.

Backends and modes — full sandbox reference.


Debug "why is this blocked?"


Elevated exec for trusted senders.

Auth is scoped by agent: each agent has its own agentDir auth store in ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite. 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

Example 1: Personal + restricted family agent

```json
{
  "agents": {
    "list": [
      {
        "id": "main",
        "default": true,
        "name": "Personal Assistant",
        "workspace": "~/.openclaw/workspace",
        "sandbox": { "mode": "off" }
      },
      {
        "id": "family",
        "name": "Family Bot",
        "workspace": "~/.openclaw/workspace-family",
        "sandbox": {
          "mode": "all",
          "scope": "agent"
        },
        "tools": {
          "allow": ["read", "message"],
          "deny": ["exec", "write", "edit", "apply_patch", "process", "browser"],
          "message": {
            "crossContext": {
              "allowWithinProvider": false,
              "allowAcrossProviders": false
            }
          }
        }
      }
    ]
  },
  "bindings": [
    {
      "agentId": "family",
      "match": {
        "provider": "whatsapp",
        "accountId": "*",
        "peer": {
          "kind": "group",
          "id": "120363424282127706@g.us"
        }
      }
    }
  ]
}
```

**Result:**

- `main` agent: runs on host, full tool access.
- `family` agent: runs in Docker (one container per agent), only `read` and current-conversation message sends.

Example 2: Work agent with shared sandbox

```json
{
  "agents": {
    "list": [
      {
        "id": "personal",
        "workspace": "~/.openclaw/workspace-personal",
        "sandbox": { "mode": "off" }
      },
      {
        "id": "work",
        "workspace": "~/.openclaw/workspace-work",
        "sandbox": {
          "mode": "all",
          "scope": "shared",
          "workspaceRoot": "/tmp/work-sandboxes"
        },
        "tools": {
          "allow": ["read", "write", "apply_patch", "exec"],
          "deny": ["browser", "gateway", "discord"]
        }
      }
    ]
  }
}
```

Example 2b: Global coding profile + messaging-only agent

```json
{
  "tools": { "profile": "coding" },
  "agents": {
    "list": [
      {
        "id": "support",
        "tools": { "profile": "messaging", "allow": ["slack"] }
      }
    ]
  }
}
```

**Result:**

- default agents get coding tools.
- `support` agent is messaging-only (+ Slack tool).

Example 3: Different sandbox modes per agent

```json
{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",
        "scope": "session"
      }
    },
    "list": [
      {
        "id": "main",
        "workspace": "~/.openclaw/workspace",
        "sandbox": {
          "mode": "off"
        }
      },
      {
        "id": "public",
        "workspace": "~/.openclaw/workspace-public",
        "sandbox": {
          "mode": "all",
          "scope": "agent"
        },
        "tools": {
          "allow": ["read"],
          "deny": ["exec", "write", "edit", "apply_patch"]
        }
      }
    ]
  }
}
```

Configuration precedence

When both global (agents.defaults.*) and agent-specific (agents.entries.*.*) configs exist:

Sandbox config

Agent-specific settings override global:

agents.entries.*.sandbox.mode > agents.defaults.sandbox.mode
agents.entries.*.sandbox.scope > agents.defaults.sandbox.scope
agents.entries.*.sandbox.workspaceRoot > agents.defaults.sandbox.workspaceRoot
agents.entries.*.sandbox.workspaceAccess > agents.defaults.sandbox.workspaceAccess
agents.entries.*.sandbox.docker.* > agents.defaults.sandbox.docker.*
agents.entries.*.sandbox.browser.* > agents.defaults.sandbox.browser.*
agents.entries.*.sandbox.prune.* > agents.defaults.sandbox.prune.*

agents.entries.*.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.entries.*.tools.profile`.

Provider tool profile

`tools.byProvider[provider].profile` or `agents.entries.*.tools.byProvider[provider].profile`.

Global tool policy

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

Provider tool policy

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

Agent-specific tool policy

`agents.entries.*.tools.allow/deny`.

Agent provider policy

`agents.entries.*.tools.byProvider[provider].allow/deny`.

Sandbox tool policy

`tools.sandbox.tools` or `agents.entries.*.tools.sandbox.tools`.

Subagent tool policy

`tools.subagents.tools`, if applicable.

Precedence rules

- Each level can further restrict tools, but cannot grant back denied tools from earlier levels.
- If `agents.entries.*.tools.sandbox.tools` is set, it replaces `tools.sandbox.tools` for that agent.
- If `agents.entries.*.tools.profile` is set, it overrides `tools.profile` for that agent.
- Provider tool keys accept either `provider` (e.g. `google-antigravity`) or `provider/model` (e.g. `openai/gpt-5.4`).

Empty allowlist behavior

If any explicit allowlist in that chain leaves the run with no callable tools, OpenClaw stops before submitting the prompt to the model. This is intentional: an agent configured with a missing tool such as `agents.entries.*.tools.allow: ["query_db"]` should fail loudly until the plugin that registers `query_db` is enabled, not continue as a text-only agent.

Tool policies support group:* shorthands that expand to multiple tools. See Tool groups for the full list.

Per-agent elevated overrides (agents.entries.*.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" }
      }
    ]
  }
}
```

Legacy agents.defaults.*/agents.entries.*.* config keys (such as sandbox.perSession, agentRuntime, embeddedPi) are migrated by openclaw doctor; prefer agents.defaults + agents.entries 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"]
  }
}
```

This policy disables OpenClaw filesystem tools, but exec is still a shell and can write files wherever the selected host or sandbox filesystem allows. For a read-only agent, deny exec and process, or combine shell access with sandbox filesystem controls such as agents.defaults.sandbox.workspaceAccess: "ro" or "none".

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

`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"

agents.defaults.sandbox.mode: "non-main" checks the session key against the main session key (always "main"; session.mainKey is not user-configurable, and OpenClaw warns and ignores any other value), 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.entries.*.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
openclaw logs --follow | grep -E "routing|sandbox|tools"
```

문제 해결

Agent not sandboxed despite `mode: 'all'`

- Check if there's a global `agents.defaults.sandbox.mode` that overrides it.
- Agent-specific config takes precedence, so set `agents.entries.*.sandbox.mode: "all"`.

Tools still available despite deny list

- Check the [full filtering order](#tool-restrictions): profile → provider profile → global policy → provider policy → agent policy → agent provider policy → sandbox → subagent.
- Each level can only further restrict, not grant back.
- See [Sandbox vs tool policy vs elevated](https://docs.openclaw.ai/gateway/sandbox-vs-tool-policy-vs-elevated) for step-by-step debugging.

Container not isolated per agent

- Default `scope` is `"agent"` (one container per agent id).
- Set `scope: "session"` for one container per session, or `scope: "shared"` to reuse one container across agents.

검증 체크리스트

해당 tool이 활성 profile/policy에서 허용되는지 확인
sandbox / elevated / host 실행 경로 정책을 이해했는지 확인
채널·에이전트 권한과 충돌하지 않는지 확인
공식 CLI/--help와 문서 옵션이 버전과 맞는지 확인

Multi-agent sandbox and tools

기준일: 2026-07-26
난이도: 중급
공식 기준: Multi-agent sandbox and tools

개요

이 페이지는 OpenClaw Multi-agent sandbox and tools 도구(파라미터, 권한, 설정, CLI)를 공식 문서 기준으로 정리합니다.

공식 요약: Per-agent sandbox + tool restrictions, precedence, and examples

도구 가시성은 profile / allow·deny policy / sandbox / channel 권한에 따라 달라집니다. 최신 스키마는 항상 공식 문서를 우선합니다.

공식 문서 기반 상세

아래는 공식 tools/multi-agent-sandbox-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.

Backends and modes — full sandbox reference.


Debug "why is this blocked?"


Elevated exec for trusted senders.

Auth is scoped by agent: each agent has its own agentDir auth store in ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite. 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

Example 1: Personal + restricted family agent

```json
{
  "agents": {
    "list": [
      {
        "id": "main",
        "default": true,
        "name": "Personal Assistant",
        "workspace": "~/.openclaw/workspace",
        "sandbox": { "mode": "off" }
      },
      {
        "id": "family",
        "name": "Family Bot",
        "workspace": "~/.openclaw/workspace-family",
        "sandbox": {
          "mode": "all",
          "scope": "agent"
        },
        "tools": {
          "allow": ["read", "message"],
          "deny": ["exec", "write", "edit", "apply_patch", "process", "browser"],
          "message": {
            "crossContext": {
              "allowWithinProvider": false,
              "allowAcrossProviders": false
            }
          }
        }
      }
    ]
  },
  "bindings": [
    {
      "agentId": "family",
      "match": {
        "provider": "whatsapp",
        "accountId": "*",
        "peer": {
          "kind": "group",
          "id": "120363424282127706@g.us"
        }
      }
    }
  ]
}
```

**Result:**

- `main` agent: runs on host, full tool access.
- `family` agent: runs in Docker (one container per agent), only `read` and current-conversation message sends.

Example 2: Work agent with shared sandbox

```json
{
  "agents": {
    "list": [
      {
        "id": "personal",
        "workspace": "~/.openclaw/workspace-personal",
        "sandbox": { "mode": "off" }
      },
      {
        "id": "work",
        "workspace": "~/.openclaw/workspace-work",
        "sandbox": {
          "mode": "all",
          "scope": "shared",
          "workspaceRoot": "/tmp/work-sandboxes"
        },
        "tools": {
          "allow": ["read", "write", "apply_patch", "exec"],
          "deny": ["browser", "gateway", "discord"]
        }
      }
    ]
  }
}
```

Example 2b: Global coding profile + messaging-only agent

```json
{
  "tools": { "profile": "coding" },
  "agents": {
    "list": [
      {
        "id": "support",
        "tools": { "profile": "messaging", "allow": ["slack"] }
      }
    ]
  }
}
```

**Result:**

- default agents get coding tools.
- `support` agent is messaging-only (+ Slack tool).

Example 3: Different sandbox modes per agent

```json
{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",
        "scope": "session"
      }
    },
    "list": [
      {
        "id": "main",
        "workspace": "~/.openclaw/workspace",
        "sandbox": {
          "mode": "off"
        }
      },
      {
        "id": "public",
        "workspace": "~/.openclaw/workspace-public",
        "sandbox": {
          "mode": "all",
          "scope": "agent"
        },
        "tools": {
          "allow": ["read"],
          "deny": ["exec", "write", "edit", "apply_patch"]
        }
      }
    ]
  }
}
```

Configuration precedence

When both global (agents.defaults.*) and agent-specific (agents.entries.*.*) configs exist:

Sandbox config

Agent-specific settings override global:

agents.entries.*.sandbox.mode > agents.defaults.sandbox.mode
agents.entries.*.sandbox.scope > agents.defaults.sandbox.scope
agents.entries.*.sandbox.workspaceRoot > agents.defaults.sandbox.workspaceRoot
agents.entries.*.sandbox.workspaceAccess > agents.defaults.sandbox.workspaceAccess
agents.entries.*.sandbox.docker.* > agents.defaults.sandbox.docker.*
agents.entries.*.sandbox.browser.* > agents.defaults.sandbox.browser.*
agents.entries.*.sandbox.prune.* > agents.defaults.sandbox.prune.*

agents.entries.*.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.entries.*.tools.profile`.

Provider tool profile

`tools.byProvider[provider].profile` or `agents.entries.*.tools.byProvider[provider].profile`.

Global tool policy

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

Provider tool policy

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

Agent-specific tool policy

`agents.entries.*.tools.allow/deny`.

Agent provider policy

`agents.entries.*.tools.byProvider[provider].allow/deny`.

Sandbox tool policy

`tools.sandbox.tools` or `agents.entries.*.tools.sandbox.tools`.

Subagent tool policy

`tools.subagents.tools`, if applicable.

Precedence rules

- Each level can further restrict tools, but cannot grant back denied tools from earlier levels.
- If `agents.entries.*.tools.sandbox.tools` is set, it replaces `tools.sandbox.tools` for that agent.
- If `agents.entries.*.tools.profile` is set, it overrides `tools.profile` for that agent.
- Provider tool keys accept either `provider` (e.g. `google-antigravity`) or `provider/model` (e.g. `openai/gpt-5.4`).

Empty allowlist behavior

If any explicit allowlist in that chain leaves the run with no callable tools, OpenClaw stops before submitting the prompt to the model. This is intentional: an agent configured with a missing tool such as `agents.entries.*.tools.allow: ["query_db"]` should fail loudly until the plugin that registers `query_db` is enabled, not continue as a text-only agent.

Tool policies support group:* shorthands that expand to multiple tools. See Tool groups for the full list.

Per-agent elevated overrides (agents.entries.*.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" }
      }
    ]
  }
}
```

Legacy agents.defaults.*/agents.entries.*.* config keys (such as sandbox.perSession, agentRuntime, embeddedPi) are migrated by openclaw doctor; prefer agents.defaults + agents.entries 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"]
  }
}
```

This policy disables OpenClaw filesystem tools, but exec is still a shell and can write files wherever the selected host or sandbox filesystem allows. For a read-only agent, deny exec and process, or combine shell access with sandbox filesystem controls such as agents.defaults.sandbox.workspaceAccess: "ro" or "none".

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

`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"

agents.defaults.sandbox.mode: "non-main" checks the session key against the main session key (always "main"; session.mainKey is not user-configurable, and OpenClaw warns and ignores any other value), 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.entries.*.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
openclaw logs --follow | grep -E "routing|sandbox|tools"
```

문제 해결

Agent not sandboxed despite `mode: 'all'`

- Check if there's a global `agents.defaults.sandbox.mode` that overrides it.
- Agent-specific config takes precedence, so set `agents.entries.*.sandbox.mode: "all"`.

Tools still available despite deny list

- Check the [full filtering order](#tool-restrictions): profile → provider profile → global policy → provider policy → agent policy → agent provider policy → sandbox → subagent.
- Each level can only further restrict, not grant back.
- See [Sandbox vs tool policy vs elevated](https://docs.openclaw.ai/gateway/sandbox-vs-tool-policy-vs-elevated) for step-by-step debugging.

Container not isolated per agent

- Default `scope` is `"agent"` (one container per agent id).
- Set `scope: "session"` for one container per session, or `scope: "shared"` to reuse one container across agents.

검증 체크리스트

해당 tool이 활성 profile/policy에서 허용되는지 확인
sandbox / elevated / host 실행 경로 정책을 이해했는지 확인
채널·에이전트 권한과 충돌하지 않는지 확인
공식 CLI/--help와 문서 옵션이 버전과 맞는지 확인

Multi-agent sandbox and tools

개요

공식 문서 기반 상세

Configuration examples

Example 1: Personal + restricted family agent

Example 2: Work agent with shared sandbox

Example 2b: Global coding profile + messaging-only agent

Example 3: Different sandbox modes per agent

Configuration precedence

Sandbox config

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

Precedence rules

Empty allowlist behavior

Migration from single agent

Tool restriction examples

Common pitfall: "non-main"

Testing

Check agent resolution

Verify sandbox containers

Test tool restrictions

Monitor logs

문제 해결

Agent not sandboxed despite mode: 'all'

Tools still available despite deny list

Container not isolated per agent

관련 문서

검증 체크리스트

관련

관련 가이드

Multi-agent sandbox and tools

개요

공식 문서 기반 상세

Configuration examples

Example 1: Personal + restricted family agent

Example 2: Work agent with shared sandbox

Example 2b: Global coding profile + messaging-only agent

Example 3: Different sandbox modes per agent

Configuration precedence

Sandbox config

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

Precedence rules

Empty allowlist behavior

Migration from single agent

Tool restriction examples

Common pitfall: "non-main"

Testing

Check agent resolution

Verify sandbox containers

Test tool restrictions

Monitor logs

문제 해결

Agent not sandboxed despite mode: 'all'

Tools still available despite deny list

Container not isolated per agent

관련 문서

검증 체크리스트

관련

관련 가이드

Agent not sandboxed despite `mode: 'all'`

Agent not sandboxed despite `mode: 'all'`