OpenClaw从入门到应用——工具（Tools）：多智能体沙箱与工具配置

通过OpenClaw实现副业收入《OpenClaw赚钱实录从“养龙虾“到可持续变现的实践指南》概述在多智能体设置中每个智能体现在可以拥有自己的沙箱配置agents.list[].sandbox会覆盖agents.defaults.sandbox工具限制tools.allow/tools.deny以及agents.list[].tools这允许你使用不同的安全配置文件运行多个智能体拥有完全访问权限的个人助理工具受限的家庭/工作智能体运行在沙箱中的面向公众的智能体setupCommand属于sandbox.docker全局或针对每个智能体并在容器创建时运行一次。认证是针对每个智能体的每个智能体从自己的agentDir认证存储中读取路径如下~/.openclaw/agents/agentId/agent/auth-profiles.json凭据不会在智能体之间共享。切勿在不同智能体之间重用agentDir。如果你想共享凭据请将auth-profiles.json复制到另一个智能体的agentDir中。关于沙箱在运行时的行为方式请参阅沙箱功能。有关“为什么会被阻止”的调试请参阅沙箱与工具策略与提升模式以及openclaw sandbox explain命令。配置示例示例 1个人 受限的家庭智能体{agents:{list:[{id:main,default:true,name:个人助理,workspace:~/.openclaw/workspace,sandbox:{mode:off}},{id:family,name:家庭机器人,workspace:~/.openclaw/workspace-family,sandbox:{mode:all,scope:agent},tools:{allow:[read],deny:[exec,write,edit,apply_patch,process,browser]}}]},bindings:[{agentId:family,match:{provider:whatsapp,accountId:*,peer:{kind:group,id:120363424282127706g.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// 覆盖main 智能体永不沙箱化}},{id:public,workspace:~/.openclaw/workspace-public,sandbox:{mode:all,// 覆盖public 智能体始终沙箱化scope:agent},tools:{allow:[read],deny:[exec,write,edit,apply_patch]}}]}}配置优先级当全局配置agents.defaults.*和特定于智能体的配置agents.list[].*同时存在时沙箱配置特定于智能体的设置会覆盖全局设置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.*注意agents.list[].sandbox.{docker,browser,prune}.*会为该智能体覆盖agents.defaults.sandbox.{docker,browser,prune}.*当沙箱作用域解析为shared时忽略。工具限制筛选顺序如下工具配置文件tools.profile或agents.list[].tools.profile提供商工具配置文件tools.byProvider[provider].profile或agents.list[].tools.byProvider[provider].profile全局工具策略tools.allow/tools.deny提供商工具策略tools.byProvider[provider].allow/deny特定于智能体的工具策略agents.list[].tools.allow/deny特定于智能体的提供商策略agents.list[].tools.byProvider[provider].allow/deny沙箱工具策略tools.sandbox.tools或agents.list[].tools.sandbox.tools子智能体工具策略tools.subagents.tools如果适用每个级别都可以进一步限制工具但不能重新授予被较早级别拒绝的工具。如果设置了agents.list[].tools.sandbox.tools它将为该智能体替换tools.sandbox.tools。如果设置了agents.list[].tools.profile它将为该智能体覆盖tools.profile。提供商工具键接受provider例如google-antigravity或provider/model例如openai/gpt-5.2。工具组简写形式工具策略全局、智能体、沙箱支持group:*条目这些条目会展开为多个具体工具group:runtimeexec、bash、processgroup:fsread、write、edit、apply_patchgroup:sessionssessions_list、sessions_history、sessions_send、sessions_spawn、session_statusgroup:memorymemory_search、memory_getgroup:uibrowser、canvasgroup:automationcron、gatewaygroup:messagingmessagegroup:nodesnodesgroup:openclaw所有内置的 OpenClaw 工具不包括提供商插件提升模式tools.elevated是全局基准基于发送者的允许列表。agents.list[].tools.elevated可以进一步限制特定智能体的提升权限两者都必须允许。缓解模式为不受信任的智能体拒绝exec权限agents.list[].tools.deny: [exec]避免将发送者列入允许列表而这些发送者会路由到受限制的智能体如果你只想沙箱化执行则在全局禁用提升模式tools.elevated.enabled: false为敏感配置文件在每个智能体上禁用提升模式agents.list[].tools.elevated.enabled: false从单智能体迁移之前单智能体{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}}]}}旧的agent.*配置会通过openclaw doctor命令进行迁移今后优先使用agents.defaultsagents.list。工具限制示例只读智能体{tools:{allow:[read],deny:[exec,write,edit,apply_patch,process]}}安全执行智能体无文件修改{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]}}常见陷阱“non-main”agents.defaults.sandbox.mode: non-main基于session.mainKey默认值为main而不是智能体 ID。群组/频道会话始终获得自己的密钥因此它们被视为 non-main 并会被沙箱化。如果你希望某个智能体永远不被沙箱化请设置agents.list[].sandbox.mode: off。测试在配置多智能体沙箱和工具之后检查智能体解析openclaw agents list --bindings验证沙箱容器docker ps --filter nameopenclaw-sbx-测试工具限制发送一条需要使用受限工具的消息验证智能体无法使用被拒绝的工具监控日志tail -f ${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/logs/gateway.log | grep -E routing|sandbox|tools故障排除尽管设置mode: all智能体仍未被沙箱化检查是否存在覆盖它的全局agents.defaults.sandbox.mode特定于智能体的配置优先级更高因此请设置agents.list[].sandbox.mode: all尽管存在拒绝列表工具仍然可用检查工具筛选顺序全局 → 智能体 → 沙箱 → 子智能体每个级别只能进一步限制不能重新授予通过日志验证[tools] filtering tools for agent:${agentId}每个智能体的容器未隔离在特定于智能体的沙箱配置中设置scope: agent默认值是session它会为每个会话创建一个容器另请参阅多智能体路由沙箱配置会话管理