多智能体沙箱和工具配置
多智能体沙箱和工具配置
概述
多智能体设置中的每个智能体现在都可以拥有自己的：
- 沙箱配置（
agents.list[].sandbox覆盖agents.defaults.sandbox） - 工具限制（
tools.allow/tools.deny，加上agents.list[].tools）
这允许你运行具有不同安全配置文件的多个智能体：
- 具有完全访问权限的个人助手
- 具有受限工具的家庭/工作智能体
- 沙箱中的面向公众的智能体
setupCommand 属于 sandbox.docker（全局或每个智能体），并在创建容器时运行一次。
认证是每个智能体的：每个智能体从自己的 agentDir 认证存储中读取：
~/.clawdbot/agents/<agentId>/agent/auth-profiles.json凭据在智能体之间不共享。永远不要跨智能体重用 agentDir。
如果你想共享凭据，请将 auth-profiles.json 复制到另一个智能体的 agentDir 中。
有关沙箱在运行时的行为方式，请参阅沙箱。
有关调试"为什么被阻止？"，请参阅沙箱与工具策略与提升和 clawdbot sandbox explain。
配置示例
示例 1：个人 + 受限的家庭智能体
{
"agents": {
"list": [
{
"id": "main",
"default": true,
"name": "Personal Assistant",
"workspace": "~/clawd",
"sandbox": { "mode": "off" }
},
{
"id": "family",
"name": "Family Bot",
"workspace": "~/clawd-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": "[email protected]"
}
}
}
]
}结果：
main智能体：在主机上运行，完全工具访问family智能体：在 Docker 中运行（每个智能体一个容器），只有read工具
示例 2：具有共享沙箱的工作智能体
{
"agents": {
"list": [
{
"id": "personal",
"workspace": "~/clawd-personal",
"sandbox": { "mode": "off" }
},
{
"id": "work",
"workspace": "~/clawd-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": "~/clawd",
"sandbox": {
"mode": "off" // 覆盖：main 从不被沙箱化
}
},
{
"id": "public",
"workspace": "~/clawd-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:runtime：exec、bash、processgroup:fs：read、write、edit、apply_patchgroup:sessions：sessions_list、sessions_history、sessions_send、sessions_spawn、session_statusgroup:memory：memory_search、memory_getgroup:ui：browser、canvasgroup:automation：cron、gatewaygroup:messaging：messagegroup:nodes：nodesgroup:clawdbot：所有内置的 Clawdbot 工具（不包括提供商插件）
提升模式
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": "~/clawd",
"sandbox": {
"mode": "non-main"
}
}
},
"tools": {
"sandbox": {
"tools": {
"allow": ["read", "write", "apply_patch", "exec"],
"deny": []
}
}
}
}之后（具有不同配置文件的多智能体）：
{
"agents": {
"list": [
{
"id": "main",
"default": true,
"workspace": "~/clawd",
"sandbox": { "mode": "off" }
}
]
}
}旧的 agent.* 配置由 clawdbot 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": {
"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。群组/渠道会话总是获得自己的键，因此它们被视为非 main 并且将被沙箱化。如果你希望智能体从不沙箱化，请设置 agents.list[].sandbox.mode: "off"。
测试
配置多智能体沙箱和工具后：
检查智能体解析：
clawdbot agents list --bindings验证沙箱容器：
docker ps --filter "label=clawdbot.sandbox=1"测试工具限制：
- 发送需要受限工具的消息
- 验证智能体无法使用被拒绝的工具
监控日志：
tail -f "${CLAWDBOT_STATE_DIR:-$HOME/.clawdbot}/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"，它为每个会话创建一个容器