OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

代理协作

多 Agent 沙盒和工具

Status: active

多智能体设置中的每个智能体都可以覆盖全局沙箱和工具策略。本页介绍按智能体配置、优先级规则和示例。

Sandboxing

后端和模式——完整的沙箱参考。
Sandbox vs tool policy vs elevated

调试“为什么这被阻止了？”
Elevated mode

面向可信发送者的提升权限 Exec。

配置示例

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"        }      }    }  ]}

结果：

  • main 智能体：在主机上运行，可使用全部工具。
  • family 智能体：在 Docker 中运行（每个智能体一个容器），只能使用 read 并向当前对话发送消息。
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"] }      }    ]  }}

结果：

  • 默认智能体可使用编程工具。
  • support 智能体只能收发消息（外加 Slack 工具）。
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"]        }      }    ]  }}

配置优先级

当全局配置（agents.defaults.*）和智能体专属配置（agents.list[].*）同时存在时：

沙箱配置

智能体专属设置会覆盖全局设置：

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

工具限制

筛选顺序如下：

  • Tool profile

    tools.profile 或 agents.list[].tools.profile。

  • Provider tool profile

    tools.byProvider[provider].profile 或 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 或 agents.list[].tools.sandbox.tools。

  • Subagent tool policy

    tools.subagents.tools（如适用）。

    • Precedence rules
    • 每一级都可以进一步限制工具，但不能重新授予此前级别已拒绝的工具。
    • 如果设置了 agents.list[].tools.sandbox.tools，它会替换该智能体的 tools.sandbox.tools。
    • 如果设置了 agents.list[].tools.profile，它会覆盖该智能体的 tools.profile。
    • 提供商工具键可以是 provider（例如 google-antigravity），也可以是 provider/model（例如 openai/gpt-5.4）。
    Empty allowlist behavior

    如果该链中的任何显式允许列表导致本次运行没有可调用的工具，OpenClaw 会在向模型提交提示词之前停止。这是有意设计的：如果智能体配置了缺失的工具，例如 agents.list[].tools.allow: ["query_db"]，那么在启用注册 query_db 的插件之前，它应明确失败，而不是作为纯文本智能体继续运行。

    工具策略支持 group:* 简写形式，可展开为多个工具。完整列表请参阅工具组。

    按智能体配置的提升权限覆盖项（agents.list[].tools.elevated）可以进一步限制特定智能体的提升权限 Exec。详情请参阅提升权限模式。

    从单智能体迁移

    Before (single agent)

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

    After (multi-agent)

    json
    {  "agents": {    "list": [      {        "id": "main",        "default": true,        "workspace": "~/.openclaw/workspace",        "sandbox": { "mode": "off" }      }    ]  }}

    工具限制示例

    Read-only agent

    json
    {  "tools": {    "allow": ["read"],    "deny": ["exec", "write", "edit", "apply_patch", "process"]  }}

    Shell execution with filesystem tools disabled

    json
    {  "tools": {    "allow": ["read", "exec", "process"],    "deny": ["write", "edit", "apply_patch", "browser", "gateway"]  }}

    Communication-only

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

    此配置资料中的 sessions_history 仍返回有界且经过净化的回忆视图，而不是原始记录转储。智能体回忆会在脱敏/截断前移除思考标签、<relevant-memories> 框架、纯文本工具调用 XML 载荷（包括 <tool_call>...</tool_call>、<function_call>...</function_call>、<tool_calls>...</tool_calls>、<function_calls>...</function_calls> 以及截断的工具调用块）、降级的工具调用框架、泄漏的 ASCII/全角模型控制令牌，以及格式错误的 MiniMax 工具调用 XML。

    常见陷阱："non-main"

    测试

    配置多 Agent 沙盒和工具后：

  • Check agent resolution

    bash
    openclaw agents list --bindings

  • Verify sandbox containers

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

  • Test tool restrictions

    • 发送一条需要受限工具的消息。
    • 验证智能体无法使用被拒绝的工具。

  • Monitor logs

    bash
    openclaw logs --follow | grep -E "routing|sandbox|tools"

    • 故障排查

    Agent not sandboxed despite `mode: 'all'`
    • 检查是否存在会覆盖它的全局 agents.defaults.sandbox.mode。
    • 智能体专属配置优先，因此请设置 agents.list[].sandbox.mode: "all"。
    尽管存在拒绝列表，工具仍然可用
    • 检查完整过滤顺序：配置文件 → 提供商配置文件 → 全局策略 → 提供商策略 → Agent 策略 → Agent 提供商策略 → 沙箱 → 子智能体。
    • 每一级只能进一步限制，不能恢复授权。
    • 有关逐步调试方法，请参阅沙箱、工具策略和提升权限。
    容器未按 Agent 隔离
    • 默认 scope 为 "agent"（每个 Agent ID 使用一个容器）。
    • 设置 scope: "session" 可让每个会话使用一个容器，设置 scope: "shared" 可让多个 Agent 共用一个容器。

    相关内容

    Was this useful?
    On this page

    On this page