Documentation Index
Fetch the complete documentation index at: https://openclaw.zhcndoc.com/llms.txt
Use this file to discover all available pages before exploring further.
多代理设置中的每个代理都可以覆盖全局沙箱和工具策略。本页介绍按代理配置、优先级规则和示例。
沙箱 vs 工具策略 vs 提权
调试“为什么这被阻止了？”
认证按代理隔离：每个代理在 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json 中都有自己的 agentDir 认证存储。绝不要在代理之间重复使用 agentDir。当代理没有本地配置文件时，它们可以读取默认/主代理的认证配置文件，但 OAuth 刷新令牌不会被克隆到次级代理存储中。如果你手动复制凭据，只能复制可移植的静态 api_key 或 token 配置文件。
配置示例
{
"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": "120363424282127706@g.us"
}
}
}
]
}
main 代理：在主机上运行，拥有完整工具访问权限。family 代理：在 Docker 中运行（每个代理一个容器），仅有 read 工具。
{
"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"]
}
}
]
}
}
{
"tools": { "profile": "coding" },
"agents": {
"list": [
{
"id": "support",
"tools": { "profile": "messaging", "allow": ["slack"] }
}
]
}
}
- 默认代理使用编码工具。
support 代理仅限消息功能（加上 Slack 工具）。
{
"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[].*）配置同时存在时：
沙箱配置
特定代理设置会覆盖全局设置：
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}.*（当沙箱 scope 解析为 "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，如适用。
如果该链中的任何显式允许列表使运行最终没有可调用工具，OpenClaw 会在将提示提交给模型之前停止。这是有意为之：如果某个代理配置了缺失的工具，例如 agents.list[].tools.allow: ["query_db"]，它应该在注册 query_db 的插件未启用时明确失败，而不是继续作为纯文本代理运行。
group:* 简写。完整列表请参见 工具组。
按代理的提权覆盖（agents.list[].tools.elevated）可以进一步限制特定代理的提权执行。详情请参见 提权模式。
从单代理迁移
{
"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.defaults + agents.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"]
}
}
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”
agents.defaults.sandbox.mode: "non-main" 是基于 session.mainKey（默认 "main"），而不是代理 id。群组/频道会话总是有自己的 key，因此会被视为 non-main 并被沙箱化。如果你希望某个代理永远不进入沙箱，请将 agents.list[].sandbox.mode 设为 "off"。
在配置多智能体沙箱和工具之后：
检查智能体解析
openclaw agents list --bindings
验证沙箱容器
docker ps --filter "name=openclaw-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"。
- 在智能体特定的沙箱配置中设置
scope: "agent"。
- 默认值是
"session"，它会为每个会话创建一个容器。
相关内容
