功能代理协调
多代理设置中的每个代理都可以覆盖全局沙箱和工具策略。本页介绍按代理配置、优先级规则和示例。
配置示例
示例1:个人+受限家庭智能体
json{ "agents": { "ownership": "explicit", "defaults": { "heartbeat": { "agentId": "main" }, "systemAgent": { "agentId": "main" } }, "entries": { "main": { "name": "Personal Assistant", "workspace": "~/.openclaw/workspace", "sandbox": { "mode": "off" } }, "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": { "channel": "whatsapp", "accountId": "*", "peer": { "kind": "group", "id": "[email protected]" } } }, { "agentId": "main", "match": { "channel": "whatsapp", "accountId": "*" } } ], "talk": { "agentId": "main" }}
结果:
main 代理:在主机上运行,拥有完整的工具访问权限。
family 代理:在配置的容器沙箱后端中运行(每个代理使用一个容器),仅可使用 read 和发送当前对话消息。
示例 2:具有共享沙箱的工作代理
json{ "agents": { "ownership": "explicit", "defaults": { "heartbeat": { "agentId": "personal" }, "systemAgent": { "agentId": "personal" }, "authInheritance": { "agentId": "personal" } }, "entries": { "personal": { "workspace": "~/.openclaw/workspace-personal", "sandbox": { "mode": "off" } }, "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"] } } } }, "talk": { "agentId": "personal" }}
示例 2b:全局编码配置文件 + 仅消息传递代理
json{ "tools": { "profile": "coding" }, "agents": { "ownership": "explicit", "defaults": { "heartbeat": { "agentId": "main" }, "systemAgent": { "agentId": "main" } }, "entries": { "main": { "workspace": "~/.openclaw/workspace" }, "support": { "tools": { "profile": "messaging", "allow": ["slack"] } } } }, "talk": { "agentId": "main" }}
结果:
main继承了全局编码工具配置文件。
support 代理仅限消息功能(加上 Slack 工具)。
示例 3:每个代理有不同的沙箱模式
json{ "agents": { "ownership": "explicit", "defaults": { "heartbeat": { "agentId": "main" }, "systemAgent": { "agentId": "main" }, "sandbox": { "mode": "non-main", "scope": "session" } }, "entries": { "main": { "workspace": "~/.openclaw/workspace", "sandbox": { "mode": "off" } }, "public": { "workspace": "~/.openclaw/workspace-public", "sandbox": { "mode": "all", "scope": "agent" }, "tools": { "allow": ["read"], "deny": ["exec", "write", "edit", "apply_patch"] } } } }, "talk": { "agentId": "main" }}
配置优先级
当全局(agents.defaults.*)和特定代理(agents.entries.*.*)配置同时存在时:
沙箱配置
特定代理设置会覆盖全局设置:
textagents.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.
特定于代理的工具策略
agents.entries.*.tools.allow/deny.
代理提供商政策
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 工具密钥接受
provider (e.g. anthropic) 或 provider/model (e.g. openai/gpt-5.4)。
空白名单行为
如果该链中的任何显式允许列表导致运行时没有可调用工具,OpenClaw 会在将提示提交给模型之前停止。这是有意为之:若某个代理配置了缺失的工具,例如 agents.entries.*.tools.allow: ["query_db"],那么在注册 query_db 的插件启用之前,它应当明确失败,而不是继续作为仅文本代理运行。
工具策略支持会展开为多个工具的 group:* 简写。完整列表请参见 工具组。
配置的 MCP 工具使用相同的策略表面。他们的全名是<safe-server>__<safe-tool>; glob 可以针对服务器名称空间。例如:
json5{ agents: { entries: { research: { tools: { allow: ["docs__read_docs"], deny: ["docs__delete_*"], }, }, }, },}
每个限制层都与前面的层相交,并且否认总是获胜。 OpenClaw 在首次模型转动之前将生成的原始工具集投影到本机 Claude、Codex 和 Gemini MCP 滤波器中。后端本地名称和设置是实现细节,而不是第二个运营商策略表面。省略了没有允许的工具的 MCP 服务器。限制性目录故障还会忽略该服务器并记录诊断,而不是打开失败。
每个代理的 elevated 覆盖(agents.entries.*.tools.elevated)可以进一步限制特定代理的 elevated exec。详情请参见 Elevated 模式。
从单代理迁移
之前(单一智能体)
json{ "agents": { "defaults": { "workspace": "~/.openclaw/workspace", "sandbox": { "mode": "non-main" } } }, "tools": { "sandbox": { "tools": { "allow": ["read", "write", "apply_patch", "exec"], "deny": [] } } }}
之后(显式代理)
json{ "agents": { "entries": { "main": { "workspace": "~/.openclaw/workspace", "sandbox": { "mode": "off" } } } }}
工具限制示例
只读代理
json{ "tools": { "allow": ["read"], "deny": ["exec", "write", "edit", "apply_patch", "process"] }}
仅限通讯
此完整配置将工具 allow/deny 策略应用于 communication 代理,并为网关上的每个代理设置会话可见性:
json{ "tools": { "sessions": { "visibility": "tree" } }, "agents": { "entries": { "communication": { "tools": { "allow": ["sessions_list", "sessions_send", "sessions_history", "session_status"], "deny": ["exec", "write", "edit", "apply_patch", "read", "browser"] } } } }}
tools.sessions.visibility 是网关范围的,不能为每个代理设置。会话工具默认为 all,并开启代理间消息传递。通过 tree,调用者可以访问他们当前的会话以及他们生成的会话;主会话仍然可以访问属于其代理的每个会话。隐身限制和沙箱生成会话限制仍然适用。请参见 tools.sessions 和 tools.agentToAgent。
此配置文件中的 sessions_history 仍然返回有界的、经过清理的召回视图,而不是原始转录本转储。助手召回剥离了思维标签、<relevant-memories> 包装器、纯文本工具调用 XML 有效负载(包括 <tool_call>...</tool_call>、<function_call>...</function_call>、<tool_calls>...</tool_calls>、<function_calls>...</function_calls> 和截断的工具调用块)、降级的工具调用包装器、泄露ASCII/full-width 模型控制令牌,以及畸形的 MiniMax 工具 - 在截断之前调用 XML。
常见陷阱:“non-main”
测试
在配置多智能体沙箱和工具之后:
检查代理解析
bashopenclaw agents list --bindings
验证沙箱容器
bashdocker ps --filter "name=openclaw-sbx-"
测试工具限制
- 发送一条需要受限工具的消息。
- 验证智能体无法使用被拒绝的工具。
监控日志
bashopenclaw logs --follow | grep -E "routing|sandbox|tools"
故障排查
尽管 `mode: 'all'`,代理并未沙箱化
- 检查是否存在全局的
agents.defaults.sandbox.mode 覆盖了它。
- 智能体特定配置具有优先级,因此请设置
agents.entries.*.sandbox.mode: "all"。
尽管列入拒绝名单,工具仍然可用
- 检查 完整的过滤顺序:配置档案 → 提供商配置档案 → 全局策略 → 提供商策略 → 智能体策略 → 智能体提供商策略 → 沙箱 → 子智能体。
- 每一层只能进一步限制,不能重新授予权限。
- 参见 沙箱 vs 工具策略 vs 提权 进行逐步调试。
- 对于MCP工具,使用OpenClaw显示的提供者安全名称,例如
docs__read_docs或docs__*;不要使用后端的原始配置字段名称。
每个代理未隔离容器
- 默认
scope 为 "agent"(每个代理 ID 一个容器)。
- 将
scope: "session" 设置为每个会话一个容器,或将 scope: "shared" 设置为在多个智能体之间复用一个容器。
相关内容