多智能体沙箱和工具

在 multi-agent 设置中，每个 agent 都可以覆盖全局沙箱和工具策略。本页介绍每个 agent 的配置、优先级规则和示例。

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

调试“为什么这个被阻止了？”

为受信任的发送者提供提权 exec。

Warning

认证（Auth）按 agent 隔离：每个 agent 都有自己独立的 <agentDir>/openclaw-agent.sqlite 认证存储（默认路径为 ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite）。切勿在多个 agent 之间复用 agentDir。当 agent 没有本地 profile 时，它们可以读取到默认/主 agent 的认证 profile，但 OAuth 刷新令牌不会被克隆到次要 agent 的存储中。如果你手动复制凭据，请只复制可移植的静态 api_key 或 token profile。

配置示例¶

示例 1：个人 + 受限的家庭 agent

{
  "agents": {
    "entries": {
      "main": {
        "default": true,
        "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"
        }
      }
    }
  ]
}

结果：

main agent：在主机上运行，拥有完整工具访问权限。
family agent：在配置的容器沙箱后端中运行（每个 agent 一个容器），仅允许 read 和当前会话的消息发送。

示例 2：使用共享沙箱的工作 agent

{
  "agents": {
    "entries": {
      "personal": {
        "default": true,
        "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"]
        }
      }
    }
  }
}

示例 2b：全局 coding profile + 仅消息发送的 agent

{
  "tools": { "profile": "coding" },
  "agents": {
    "entries": {
      "main": {
        "default": true
      },
      "support": {
        "tools": { "profile": "messaging", "allow": ["slack"] }
      }
    }
  }
}

结果：

默认 agent 获得 coding 工具。
support agent 仅限消息发送（+ Slack 工具）。

示例 3：每个 agent 使用不同的沙箱模式

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",
        "scope": "session"
      }
    },
    "entries": {
      "main": {
        "default": true,
        "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"]
        }
      }
    }
  }
}

配置优先级¶

当全局（agents.defaults.*）和 agent 特定（agents.entries.*.*）配置同时存在时：

沙箱配置¶

agent 特定的设置会覆盖全局设置：

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}.* 会覆盖该 agent 的 agents.defaults.sandbox.{docker,browser,prune}.*（当沙箱作用域解析为 "shared" 时忽略）。docker 块用于配置两个内置容器后端。

工具限制¶

过滤顺序如下：

工具 profile

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

提供方工具 profile

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

全局工具策略

tools.allow / tools.deny。

提供方工具策略

tools.byProvider[provider].allow/deny。

agent 特定工具策略

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

agent 提供方策略

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

沙箱工具策略

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

子 agent 工具策略

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": {
        "default": true,
        "workspace": "~/.openclaw/workspace",
        "sandbox": { "mode": "off" }
      }
    }
  }
}

Note

Doctor 将旧版 agents.list 名册迁移到 agents.entries。针对六月之前的键（例如 sandbox.perSession、embeddedPi 和 embeddedHarness）的迁移已弃用；请使用 sandbox.scope、embeddedAgent 以及提供商/模型运行时策略。对于较旧的安装，请先通过 2026.9.5 升级，再安装最新版本。

工具限制示例¶

只读智能体启用 Shell 执行但禁用文件系统工具仅通信

{
  "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"。

此完整配置将工具允许/拒绝策略应用于 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" 以在多个代理之间复用一个容器。

提升模式
多代理路由
沙箱配置
沙箱、工具策略与提升模式 — 调试“为什么被阻止？”
沙箱 — 完整沙箱参考（模式、范围、后端、镜像）
会话管理
OpenShell — 一种托管沙箱后端，每个代理的沙箱可委托给它
ACP 代理 — 一个独立边界：OpenClaw 沙箱策略不会包裹 ACP 执行框架的执行
子代理 — 这些限制所约束的派生会话

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

多智能体沙箱和工具

配置示例¶

配置优先级¶

沙箱配置¶

工具限制¶

从单智能体迁移¶

工具限制示例¶

常见陷阱：“non-main”¶

测试¶

故障排除¶

相关¶