跳转至

多代理沙箱和工具

多智能体设置中的每个智能体都可以覆盖全局沙箱和工具策略。本页介绍按智能体配置、优先级规则和示例。

沙箱

后端与模式——完整的沙箱参考。

沙箱 vs 工具策略 vs 提权模式

调试“为什么被阻止?”

提权模式

为可信发件人提供提权 exec。

Warning

认证按智能体划分范围:每个智能体都有自己的 <agentDir>/openclaw-agent.sqlite 认证存储(默认位于 ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite)。切勿在多个智能体之间复用 agentDir。当智能体没有本地配置文件时,它们可以读取默认/主智能体的认证配置文件,但 OAuth 刷新令牌不会被克隆到次级智能体的存储中。如果手动复制凭据,请只复制可移植的静态 api_key 或 token 配置文件。


配置示例

示例 1:个人 + 受限的家庭智能体
{
  "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": "120363424282127706@g.us"
        }
      }
    },
    {
      "agentId": "main",
      "match": { "channel": "whatsapp", "accountId": "*" }
    }
  ],
  "talk": { "agentId": "main" }
}

结果:

  • main 智能体:在主机上运行,拥有完整工具访问权限。
  • family 智能体:在配置的容器沙箱后端中运行(每个智能体一个容器),仅可执行 read 和当前会话的消息发送。
示例 2:使用共享沙箱的工作智能体
{
  "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:全局编码配置文件 + 仅消息智能体
{
  "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:不同智能体使用不同的沙箱模式
{
  "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.*.*)同时存在时:

沙箱配置

智能体特定设置会覆盖全局设置:

agents.entries.*.sandbox.mode > agents.defaults.sandbox.mode
agents.entries.*.sandbox.scope > agents.defaults.sandbox.scope
agents.entries.*.sandbox.workspaceRoot > agents.defaults.sandbox.workspaceRoot
agents.entries.*.sandbox.workspaceAccess > agents.defaults.sandbox.workspaceAccess
agents.entries.*.sandbox.docker.* > agents.defaults.sandbox.docker.*
agents.entries.*.sandbox.browser.* > agents.defaults.sandbox.browser.*
agents.entries.*.sandbox.prune.* > agents.defaults.sandbox.prune.*

Note

对于该智能体,agents.entries.*.sandbox.{docker,browser,prune}.* 会覆盖 agents.defaults.sandbox.{docker,browser,prune}.*(当沙箱作用域解析为 "shared" 时忽略)。docker 块同时配置两个内置容器后端。

工具限制

过滤顺序如下:

1. 工具配置档

tools.profile 或 agents.entries.*.tools.profile。

2. 提供商工具配置档

tools.byProvider[provider].profile 或 agents.entries.*.tools.byProvider[provider].profile。

3. 全局工具策略

tools.allow / tools.deny。

4. 提供商工具策略

tools.byProvider[provider].allow/deny。

5. 代理特定工具策略

agents.entries.*.tools.allow/deny。

6. 代理提供商策略

agents.entries.*.tools.byProvider[provider].allow/deny。

7. 沙箱工具策略

tools.sandbox.tools 或 agents.entries.*.tools.sandbox.tools。

8. 子代理工具策略

tools.subagents.tools(如适用)。

优先级规则
  • 每一层都可以进一步限制工具,但不能重新授予更早层级已拒绝的工具。
  • 如果设置了 agents.entries.*.tools.sandbox.tools,则会替换该代理的 tools.sandbox.tools。
  • 如果设置了 agents.entries.*.tools.profile,则会覆盖该代理的 tools.profile。
  • 提供商工具键接受 provider(例如 anthropic)或 provider/model(例如 openai/gpt-5.4)。
空白名单行为

如果该链路中的任何显式白名单使运行不再有可调用的工具,OpenClaw 会在向模型提交提示词之前停止。这是有意为之:配置了缺失工具(如 agents.entries.*.tools.allow: ["query_db"])的代理应当大声失败,直到注册 query_db 的插件被启用,而不是继续作为纯文本代理运行。

工具策略支持扩展为多个工具的 group:* 简写。完整列表请参阅 工具组。

已配置的 MCP 工具使用相同的策略面。其规范名称为 <safe-server>__<safe-tool>;通配符可以针对服务器命名空间。例如:

{
  agents: {
    entries: {
      research: {
        tools: {
          allow: ["docs__read_docs"],
          deny: ["docs__delete_*"],
        },
      },
    },
  },
}

每个限制层都与更早的层取交集,且拒绝(deny)始终生效。OpenClaw 会在其首次模型轮次之前,将最终得到的原始工具集投射到原生 Claude、Codex 和 Gemini MCP 过滤器中。后端原生的名称和设置是实现细节,而非第二套运维策略面。没有任何允许工具的 MCP 服务器会被省略。限制性目录失败也会省略该服务器,并记录诊断信息,而不是在失败时开放。

代理级提权覆盖(agents.entries.*.tools.elevated)可以进一步限制特定代理的提权执行。详见 提权模式。


从单个代理迁移

{
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace",
      "sandbox": {
        "mode": "non-main"
      }
    }
  },
  "tools": {
    "sandbox": {
      "tools": {
        "allow": ["read", "write", "apply_patch", "exec"],
        "deny": []
      }
    }
  }
}
{
  "agents": {
    "entries": {
      "main": {
        "workspace": "~/.openclaw/workspace",
        "sandbox": { "mode": "off" }
      }
    }
  }
}

Note

Doctor 命令会将旧的 agents.list 名单和 default 标记迁移到带显式策略面所有者的 agents.entries。直接替换二进制后,在启动 Gateway 之前运行 openclaw doctor --fix。针对 6 月之前键(如 sandbox.perSession、embeddedPi 和 embeddedHarness)的迁移已退役;请使用 sandbox.scope、embeddedAgent 以及 provider/model 运行时策略。对于较旧的安装,请先升级到 2026.9.5,再安装最新版本。


工具限制示例

{
  "tools": {
    "allow": ["read"],
    "deny": ["exec", "write", "edit", "apply_patch", "process"]
  }
}
```json
{
  "tools": {
    "allow": ["read", "exec", "process"],
    "deny": ["write", "edit", "apply_patch", "browser", "gateway"]
  }
}
```

Warning

此策略禁用了 OpenClaw 文件系统工具,但 exec 仍然是一个 shell,可以在所选主机或沙箱文件系统允许的任何位置写入文件。对于只读代理,请拒绝 exec 和 process,或者将 shell 访问与沙箱文件系统控制(如 agents.defaults.sandbox.workspaceAccess: "ro" 或 "none")结合使用。

此完整配置将工具 allow/deny 策略应用于 communication 代理,并为 Gateway 上的每个代理设置会话可见性:

{
  "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 是 Gateway 全局设置,不能按代理设置。会话工具默认使用 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/全角模型控制令牌,以及格式错误的 MiniMax 工具调用 XML。


常见陷阱:“non-main”

Warning

agents.defaults.sandbox.mode: "non-main" 会将会话键与主会话键(始终为 "main";session.mainKey 不可由用户配置,OpenClaw 会警告并忽略其他任何值)进行比较,而不是与智能体 ID 比较。群组/频道会话始终会获得自己的键,因此它们被视为非主会话并会被沙箱化。如果你希望某个智能体永不沙箱化,请设置 agents.entries.*.sandbox.mode: "off"。


测试

配置多智能体沙箱和工具后:

1. 检查智能体解析

openclaw agents list --bindings

2. 验证沙箱容器

docker ps --filter "name=openclaw-sbx-"

3. 测试工具限制

  • 发送一条需要受限工具的消息。
  • 验证智能体无法使用被拒绝的工具。

4. 监控日志

openclaw logs --follow | grep -E "routing|sandbox|tools"

故障排查

尽管 mode: 'all',智能体未被沙箱化
  • 检查是否存在全局 agents.defaults.sandbox.mode 覆盖了它。
  • 智能体特定配置优先,因此设置 agents.entries.*.sandbox.mode: "all"。
尽管有拒绝列表,工具仍可用
  • 检查完整过滤顺序:配置 → 提供商配置 → 全局策略 → 提供商策略 → 智能体策略 → 智能体提供商策略 → 沙箱 → 子智能体。
  • 每一层只能进一步限制,不能重新授予权限。
  • 参见沙箱与工具策略与提升模式以进行逐步调试。
  • 对于 MCP 工具,请使用 OpenClaw 显示的提供商安全名称,例如 docs__read_docs 或 docs__*;不要使用后端的原始配置字段名称。
容器未按智能体隔离
  • 默认 scope 为 "agent"(每个智能体 ID 一个容器)。
  • 设置 scope: "session" 可为每个会话使用一个容器,或设置 scope: "shared" 以在多个智能体之间复用一个容器。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw