多 Agent 沙箱与工具配置

在多 Agent 部署中，每个 Agent 都可以覆盖全局沙箱和工具策略。本页介绍单 Agent 配置、优先级规则和示例。

• 沙箱后端与模式：参见 Sandboxing。
• 调试被阻断的工具：参见 Sandbox vs Tool Policy vs Elevated 和 openclaw sandbox explain。
• 提升权限执行：参见 Elevated Mode。

认证是 Agent 级别的：每个 Agent 从自己的 agentDir 认证存储（~/.openclaw/agents/<agentId>/agent/auth-profiles.json）读取数据。凭据不在 Agent 之间共享。切勿跨 Agent 复用 agentDir。如需共享凭据，请将 auth-profiles.json 复制到另一个 Agent 的 agentDir。

---

配置示例

示例 1：个人 Agent + 受限家庭 Agent

{
  "agents": {
    "list": [
      {
        "id": "main",
        "default": true,
        "name": "Personal Assistant",
        "workspace": "~/.openclaw/workspace",
        "sandbox": { "mode": "off" }
      },
      {
        "id": "family",
        "name": "Family Bot",
        "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 Agent：在主机上运行，拥有完整工具权限
• family Agent：在 Docker 中运行（每个 Agent 一个容器），仅能使用 read 工具

---

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

{
  "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"]
        }
      }
    ]
  }
}

---

示例 2b：全局编码配置 + 仅消息 Agent

{
  "tools": { "profile": "coding" },
  "agents": {
    "list": [
      {
        "id": "support",
        "tools": { "profile": "messaging", "allow": ["slack"] }
      }
    ]
  }
}

效果：

• 默认 Agent 获得编码工具
• support Agent 仅限消息功能（+ Slack 工具）

---

示例 3：不同 Agent 使用不同沙箱模式

{
  "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.*）和单 Agent（agents.list[].*）配置同时存在时：

沙箱配置

Agent 级设置覆盖全局：

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}.* 覆盖该 Agent 的 agents.defaults.sandbox.{docker,browser,prune}.*（当沙箱 scope 解析为 "shared" 时忽略）。

工具限制

过滤顺序：

1. 工具配置文件（tools.profile 或 agents.list[].tools.profile）
2. Provider 工具配置文件（tools.byProvider[provider].profile 或 agents.list[].tools.byProvider[provider].profile）
3. 全局工具策略（tools.allow / tools.deny）
4. Provider 工具策略（tools.byProvider[provider].allow/deny）
5. Agent 级工具策略（agents.list[].tools.allow/deny）
6. Agent Provider 策略（agents.list[].tools.byProvider[provider].allow/deny）
7. 沙箱工具策略（tools.sandbox.tools 或 agents.list[].tools.sandbox.tools）
8. 子代理工具策略（tools.subagents.tools，如适用）

每一层可以进一步限制工具，但不能恢复被更高层拒绝的工具。 若设置了 agents.list[].tools.sandbox.tools，它会替换该 Agent 的 tools.sandbox.tools。 若设置了 agents.list[].tools.profile，它会覆盖该 Agent 的 tools.profile。 Provider 工具键接受 provider（如 google-antigravity）或 provider/model（如 openai/gpt-5.2）两种格式。

工具策略支持 group:* 简写，会展开为多个工具。详见 Tool groups。

单 Agent 的提升权限覆盖（agents.list[].tools.elevated）可进一步限制特定 Agent 的提升执行权限。详见 Elevated Mode。

---

从单 Agent 迁移

迁移前（单 Agent）：

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

迁移后（多 Agent，不同配置）：

{
  "agents": {
    "list": [
      {
        "id": "main",
        "default": true,
        "workspace": "~/.openclaw/workspace",
        "sandbox": { "mode": "off" }
      }
    ]
  }
}

旧版 agent.* 配置可通过 openclaw doctor 迁移；建议今后使用 agents.defaults + agents.list。

---

工具限制示例

只读 Agent

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

安全执行 Agent（不允许修改文件）

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

仅通信 Agent

{
  "tools": {
    "sessions": { "visibility": "tree" },
    "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"），而不是 Agent ID。群组/频道会话始终获得自己的 key，因此被视为 non-main 并会被沙箱化。如果你希望某个 Agent 永远不被沙箱化，请设置 agents.list[].sandbox.mode: "off"。

---

测试验证

配置多 Agent 沙箱和工具后：

1. 检查 Agent 解析：

   openclaw agents list --bindings

2. 验证沙箱容器：

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

3. 测试工具限制：

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

4. 监控日志：

   tail -f "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/logs/gateway.log" | grep -E "routing|sandbox|tools"

---

故障排查

Agent 没有被沙箱化，尽管设置了 mode: "all"

• 检查是否有全局 agents.defaults.sandbox.mode 覆盖了它
• Agent 级配置优先，请设置 agents.list[].sandbox.mode: "all"

工具仍然可用，尽管在拒绝列表中

• 检查工具过滤顺序：全局 → Agent → 沙箱 → 子代理
• 每一层只能进一步限制，不能恢复权限
• 通过日志验证：[tools] filtering tools for agent:${agentId}

容器没有按 Agent 隔离

• 在 Agent 级沙箱配置中设置 scope: "agent"
• 默认是 "session"，即每个会话创建一个容器

---

参见

• Sandboxing — 完整沙箱参考（模式、范围、后端、镜像）
• Sandbox vs Tool Policy vs Elevated — 调试"为什么被阻断？"
• Elevated Mode
• Multi-Agent Routing
• Sandbox Configuration
• Session Management