多 Agent 沙箱与工具策略

概述

多 Agent 设置中，每个 Agent 可以覆盖全局沙箱和工具策略。本页面覆盖 per-agent 配置、优先级规则和示例。

核心功能

• 每个 Agent 独立的沙箱模式（off/all/non-main）和范围（session/agent/shared）
• 工具过滤优先级链（8 层，从宽到严）
• 支持 group:* 工具组简写
• 每个 Agent 有独立的 agentDir auth 存储

工具过滤优先级

1. 工具 profile（tools.profile 或 agents.list[].tools.profile）
2. Provider 工具 profile
3. 全局工具策略（tools.allow/tools.deny）
4. Provider 工具策略
5. Agent 特定工具策略（agents.list[].tools.allow/deny）
6. Agent Provider 策略
7. 沙箱工具策略
8. Sub-agent 工具策略

每层只能进一步限制，不能恢复已被上层拒绝的工具。

配置示例

个人 + 受限家庭 Agent：

{
  "agents": {
    "list": [
      {
        "id": "main",
        "sandbox": { "mode": "off" }
      },
      {
        "id": "family",
        "sandbox": { "mode": "all", "scope": "agent" },
        "tools": {
          "allow": ["read", "message"],
          "deny": ["exec", "write", "browser"]
        }
      }
    ]
  }
}

注意事项

• agents.defaults.sandbox.mode: "non-main" 基于 session.mainKey（默认 "main"），不是 Agent ID
• 每个 Agent 的 auth 存储在 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json，不要跨 Agent 复用
• 空 allowlist 会导致 OpenClaw 在提交 prompt 前停止（有意为之）
• exec 工具即使禁用了 OpenClaw 文件系统工具，仍可通过 shell 写文件

相关页面

• concepts/tool-subagents — Sub-agents 工具策略
• concepts/tool-acp-agents — ACP agents 沙箱兼容性
• multi-agent — 多 Agent 路由配置