在多Agent网关中，你可以为每个智能体单独设置沙箱模式和工具访问策略。配置优先级是Agent级覆盖全局，工具过滤按8层顺序逐级限制，每层只能进一步收窄。关键操作：用openclaw agents list --bindings验证绑定；日志搜索[tools] filtering tools检查限制；注意non-main模式基于会话主键而非Agent ID。如果某个Agent显式allowlist导致无可用工具，OpenClaw会停止提交prompt而非降级为纯文本。

OpenClaw 多Agent沙箱和工具策略配置指南

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

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

WARNING

认证是Agent级别的：每个Agent从自己的agentDir认证存储（~/.openclaw/agents/<agentId>/agent/auth-profiles.json）读取数据。无本地配置时，Agent可以回退读取默认/main Agent的认证配置，但OAuth刷新令牌不会克隆到次要Agent的存储中。如果手动复制凭据，只复制可移植的静态api_key或token配置文件。切勿跨Agent复用agentDir。

配置示例

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

```json
{
  "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", "message"],
          "deny": ["exec", "write", "edit", "apply_patch", "process", "browser"],
          "message": {
            "crossContext": {
              "allowWithinProvider": false,
              "allowAcrossProviders": false
            }
          }
        }
      }
    ]
  },
  "bindings": [
    {
      "agentId": "family",
      "match": {
        "provider": "whatsapp",
        "accountId": "*",
        "peer": {
          "kind": "group",
          "id": "120363424282127706@g.us"
        }
      }
    }
  ]
}
```

**效果：**
- `main` Agent：在主机上运行，完整工具访问。
- `family` Agent：在Docker中运行（每个Agent一个容器），只能`read`和发送当前会话消息。

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

```json
{
  "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

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

**效果：**
- 默认Agent获得编码工具。
- `support` Agent仅限消息功能（+ Slack工具）。

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

```json
{
  "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.*

INFO

agents.list[].sandbox.{docker,browser,prune}.* 覆盖该Agent的 agents.defaults.sandbox.{docker,browser,prune}.*（当沙箱scope解析为"shared"时忽略）。

工具限制

过滤顺序如下：

工具配置文件

`tools.profile` 或 `agents.list[].tools.profile`。

Provider工具配置文件

`tools.byProvider[provider].profile` 或 `agents.list[].tools.byProvider[provider].profile`。

全局工具策略

`tools.allow` / `tools.deny`。

Provider工具策略

`tools.byProvider[provider].allow/deny`。

Agent级工具策略

`agents.list[].tools.allow/deny`。

Agent Provider策略

`agents.list[].tools.byProvider[provider].allow/deny`。

沙箱工具策略

`tools.sandbox.tools` 或 `agents.list[].tools.sandbox.tools`。

子Agent工具策略

`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.4`）。

空允许列表行为

如果链条中任何显式allowlist导致运行后无可调用的工具，OpenClaw会在提交prompt给模型之前停止。这是有意设计的：配置了缺少工具（例如`agents.list[].tools.allow: ["query_db"]`）但注册该工具的插件未启用时，Agent应明确失败，而不是降级为纯文本Agent继续运行。

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

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

从单Agent迁移

迁移前（单Agent）

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

迁移后（多Agent）

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

INFO

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

工具限制示例

只读Agent

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

可执行Shell但禁用文件系统工具

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

WARNING

此策略禁用了OpenClaw文件系统工具，但`exec`仍然是一个Shell，可以在主机或沙箱文件系统允许的位置写文件。如需只读Agent，请再拒绝`exec`和`process`，或结合沙箱文件系统控制如`agents.defaults.sandbox.workspaceAccess: "ro"`或`"none"`。

仅通信Agent

```json
{
  "tools": {
    "sessions": { "visibility": "tree" },
    "allow": ["sessions_list", "sessions_send", "sessions_history", "session_status"],
    "deny": ["exec", "write", "edit", "apply_patch", "read", "browser"]
  }
}
```

此配置中的 `sessions_history` 返回有界、经清理的回忆视图，而非原始转储。助手回忆会剥离thinking标签、`&lt;relevant-memories&gt;`脚手架、纯文本工具调用XML载荷（包括`&lt;tool_call&gt;...&lt;/tool_call&gt;`、`&lt;function_call&gt;...&lt;/function_call&gt;`、`&lt;tool_calls&gt;...&lt;/tool_calls&gt;`、`&lt;function_calls&gt;...&lt;/function_calls&gt;`和截断的工具调用块）、降级后的工具调用脚手架、泄露的ASCII/全宽模型控制令牌以及畸形MiniMax工具调用XML。

常见陷阱："non-main"模式

WARNING

agents.defaults.sandbox.mode: "non-main" 基于 session.mainKey（默认 "main"），而不是Agent ID。群组/频道会话始终获得自己的key，因此被视为non-main并会被沙箱化。如果你希望某个Agent永远不被沙箱化，请设置 agents.list[].sandbox.mode: "off"。

测试验证

配置多Agent沙箱和工具后：

检查Agent解析

```bash
openclaw agents list --bindings
```

验证沙箱容器

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

测试工具限制

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

监控日志

```bash
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 → 沙箱 → 子Agent。
- 每一层只能进一步限制，不能恢复权限。
- 通过日志验证：`[tools] filtering tools for agent:${agentId}`。

容器没有按Agent隔离

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

常见问题

为什么配置了 `mode: all` 但Agent依然没有进入沙箱？

可能被全局 agents.defaults.sandbox.mode 覆盖，Agent级配置优先于全局，请显式在 agents.list[].sandbox 中设置 mode: "all"，同时检查全局默认是否也为"all"或更高优先级配置。也可用 openclaw doctor 检测配置冲突。

工具拒绝列表不生效怎么办？

按过滤顺序（profile → provider profile → allow/deny → agent allow/deny → ...）逐层检查，确保Agent级的deny位于正确层级。日志中搜索 [tools] filtering tools for agent:${agentId} 可以定位阻断点。如果上层（如profile或全局policy）已经allow了某工具，下层deny无法收回。

如何让家庭Agent只读？

参考示例1：设置 tools.allow: ["read"], tools.deny: ["exec", "write", "edit", "apply_patch", "process", "browser"]，并启用沙箱 mode: "all"。注意 exec 是Shell，禁止exec后仍可限制文件写入；如需完全只读，还应结合沙箱的 workspaceAccess: "ro"。

参见

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

OpenClaw 多Agent沙箱和工具策略配置指南 ​

配置示例 ​

配置优先级 ​

沙箱配置 ​

工具限制 ​

从单Agent迁移 ​

工具限制示例 ​

常见陷阱："non-main"模式 ​

测试验证 ​

故障排查 ​

常见问题 ​

为什么配置了 mode: all 但Agent依然没有进入沙箱？ ​

工具拒绝列表不生效怎么办？ ​

如何让家庭Agent只读？ ​

参见 ​

OpenClaw 多Agent沙箱和工具策略配置指南

配置示例

配置优先级

沙箱配置

工具限制

从单Agent迁移

工具限制示例

常见陷阱："non-main"模式

测试验证

故障排查

常见问题

为什么配置了 `mode: all` 但Agent依然没有进入沙箱？

工具拒绝列表不生效怎么办？

如何让家庭Agent只读？

参见