代理协作
多 Agent 沙盒和工具
多智能体设置中的每个智能体都可以覆盖全局沙箱和工具策略。本页介绍按 Agent 配置、优先级规则和示例。
配置示例
示例 1：个人智能体 + 受限的家庭智能体
{ "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和向当前对话发送消息的功能。
示例 2：使用共享沙箱的工作智能体
{ "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"] } } ] }}示例 2b：全局编码配置文件 + 仅消息智能体
{ "tools": { "profile": "coding" }, "agents": { "list": [ { "id": "support", "tools": { "profile": "messaging", "allow": ["slack"] } } ] }}结果：
- 默认智能体获得编码工具。
support智能体仅能收发消息（另加 Slack 工具）。
示例 3：为每个智能体设置不同的沙箱模式
{ "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.*）和 Agent 专属配置（agents.entries.*.*）同时存在时：
沙箱配置
Agent 专属设置覆盖全局设置：
agents.entries.*.sandbox.mode > agents.defaults.sandbox.modeagents.entries.*.sandbox.scope > agents.defaults.sandbox.scopeagents.entries.*.sandbox.workspaceRoot > agents.defaults.sandbox.workspaceRootagents.entries.*.sandbox.workspaceAccess > agents.defaults.sandbox.workspaceAccessagents.entries.*.sandbox.docker.* > agents.defaults.sandbox.docker.*agents.entries.*.sandbox.browser.* > agents.defaults.sandbox.browser.*agents.entries.*.sandbox.prune.* > agents.defaults.sandbox.prune.*工具限制
过滤顺序如下：
工具配置文件
tools.profile 或 agents.entries.*.tools.profile。
提供商工具配置文件
tools.byProvider[provider].profile 或 agents.entries.*.tools.byProvider[provider].profile。
全局工具策略
tools.allow / tools.deny。
提供商工具策略
tools.byProvider[provider].allow/deny。
Agent 专属工具策略
agents.entries.*.tools.allow/deny。
Agent 提供商策略
agents.entries.*.tools.byProvider[provider].allow/deny。
沙箱工具策略
tools.sandbox.tools 或 agents.entries.*.tools.sandbox.tools。
子智能体工具策略
tools.subagents.tools（如适用）。
优先级规则
- 每一级都可以进一步限制工具，但无法重新授予在前面级别中被拒绝的工具。
- 如果设置了
agents.entries.*.tools.sandbox.tools，它会替换该智能体的tools.sandbox.tools。 - 如果设置了
agents.entries.*.tools.profile，它会覆盖该智能体的tools.profile。 - 提供商工具键既可以使用
provider（例如google-antigravity），也可以使用provider/model（例如openai/gpt-5.4）。
空允许列表行为
如果该链中的任何显式允许列表导致本次运行没有可调用的工具，OpenClaw 会在向模型提交提示词之前停止。这是有意设计的行为：如果某个智能体配置了不存在的工具（例如 agents.entries.*.tools.allow: ["query_db"]），它应明确失败，直到启用注册 query_db 的插件，而不是继续作为纯文本智能体运行。
工具策略支持可展开为多个工具的 group:* 简写。完整列表请参阅工具组。
按 Agent 配置的提升权限覆盖项（agents.entries.*.tools.elevated）可以进一步限制特定智能体的提升权限 Exec。详情请参阅提升权限模式。
从单智能体迁移
之前（单智能体）
{ "agents": { "defaults": { "workspace": "~/.openclaw/workspace", "sandbox": { "mode": "non-main" } } }, "tools": { "sandbox": { "tools": { "allow": ["read", "write", "apply_patch", "exec"], "deny": [] } } }}之后（多智能体）
{ "agents": { "list": [ { "id": "main", "default": true, "workspace": "~/.openclaw/workspace", "sandbox": { "mode": "off" } } ] }}工具限制示例
只读智能体
{ "tools": { "allow": ["read"], "deny": ["exec", "write", "edit", "apply_patch", "process"] }}禁用文件系统工具的 Shell 执行
{ "tools": { "allow": ["read", "exec", "process"], "deny": ["write", "edit", "apply_patch", "browser", "gateway"] }}仅通信
{ "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 沙盒和工具后：
检查智能体解析
openclaw agents list --bindings验证沙箱容器
docker ps --filter "name=openclaw-sbx-"测试工具限制
- 发送一条需要使用受限工具的消息。
- 验证智能体无法使用被拒绝的工具。
监控日志
openclaw logs --follow | grep -E "routing|sandbox|tools"故障排查
尽管设置了 `mode: 'all'`，智能体仍未被沙箱隔离
- 检查是否存在覆盖它的全局
agents.defaults.sandbox.mode。 - Agent 专属配置优先，因此请设置
agents.entries.*.sandbox.mode: "all"。
尽管有拒绝列表，工具仍然可用
- 检查完整的筛选顺序：配置文件 → 提供商配置文件 → 全局策略 → 提供商策略 → 智能体策略 → 智能体提供商策略 → 沙箱 → 子智能体。
- 每一层都只能进一步限制，不能重新授予权限。
- 有关逐步调试方法，请参阅沙箱、工具策略和提升权限。
容器未按智能体隔离
- 默认
scope为"agent"（每个智能体 ID 使用一个容器）。 - 设置
scope: "session"可让每个会话使用一个容器，或设置scope: "shared"以在多个智能体之间复用一个容器。
