多代理沙箱和工具

在多代理设置中，每个代理都可以覆盖全局沙箱和工具策略。本页面涵盖每个代理的配置、优先级规则和示例。

沙箱隔离

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

沙箱与工具策略与提升权限模式

调试“为什么被阻止？”

提升权限模式

针对可信发送者的提升执行。

配置示例

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

{
  "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": "[email protected]"
        }
      }
    }
  ]
}

结果：

main 代理：在主机上运行，拥有完整工具访问权限。
familyDocker 代理：在 Docker 中运行（每个代理一个容器），仅 read 和当前对话的消息发送。

示例 2：具有共享沙箱的工作代理

{
  "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：全局编码配置文件 + 仅消息代理

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

结果：

默认代理获取编码工具。
support 代理仅用于消息传递（+ Slack 工具）。

示例 3：每个代理不同的沙箱模式

{
  "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.*) 和特定于代理 (agents.list[].*) 的配置时：

沙箱配置

特定于代理的设置会覆盖全局设置：

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.*

工具限制

过滤顺序为：

工具配置文件
tools.profile 或 agents.list[].tools.profile。
提供商工具配置文件
tools.byProvider[provider].profile 或 agents.list[].tools.byProvider[provider].profile。
全局工具策略
tools.allow / tools.deny。
提供商工具策略
tools.byProvider[provider].allow/deny。
特定于代理的工具策略
agents.list[].tools.allow/deny。
代理提供商策略
agents.list[].tools.byProvider[provider].allow/deny。
沙箱工具策略
tools.sandbox.tools 或 agents.list[].tools.sandbox.tools。
子代理工具策略
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）。

空允许列表行为

如果该链中的任何显式允许列表导致运行时没有可调用的工具，OpenClaw 将在向模型提交提示之前停止。这是有意的：配置了缺失工具（例如 agents.list[].tools.allow: ["query_db"]）的代理应该明确报错，直到注册 query_db 的插件被启用，而不是作为仅文本代理继续运行。

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

按 Agent 覆盖的 Elevated 配置 (agents.list[].tools.elevated) 可以进一步限制特定 Agent 的 elevated exec。有关详细信息，请参阅 Elevated 模式。

从单一代理迁移

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

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

工具限制示例

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

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

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

此配置文件中的 sessions_history 仍然返回有界的、经过清理的召回视图，而不是原始的对话记录转储。助手召回会去除思考标签、`

脚手架、纯文本工具调用 XML 载荷（包括

…

、

…

、

…

、

…

`MiniMax 以及被截断的工具调用块）、降级的工具调用脚手架、泄露的 ASCII/全角模型控制令牌，以及在编辑/截断之前格式错误的 MiniMax 工具调用 XML。

常见误区：“非主”

测试

配置多代理沙箱和工具后：

Check agent resolution
Terminal window
```
openclaw agents list --bindings
```
Verify sandbox containers
Terminal window
```
docker ps --filter "name=openclaw-sbx-"
```
Test 工具 restrictions
- 发送一条需要受限工具的消息。
- 验证代理无法使用被拒绝的工具。

Monitor logs

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

故障排除

Agent not 沙箱隔离 despite `mode: 'all'`

检查是否存在覆盖该设置的全局 agents.defaults.sandbox.mode。
特定于代理的配置优先级更高，因此请设置 agents.list[].sandbox.mode: "all"。

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

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

容器未按代理隔离

在代理特定的沙箱配置中设置 scope: "agent"。
默认值为 "session"，即每个会话创建一个容器。