多 Agent Sandbox 与工具配置

概述

在多 Agent 设置中,每个 Agent 现在可以有自己的:

  • Sandbox 配置（agents.list[].sandbox 会覆盖 agents.defaults.sandbox）
  • 工具限制（tools.allow / tools.deny,以及 agents.list[].tools）

这让你可以运行多个具有不同安全配置的 Agent:

  • 个人助手拥有完全访问权限
  • 家庭/工作 Agent 使用受限工具
  • 面向公众的 Agent 运行在沙箱中

setupCommand 属于 sandbox.docker（全局或单个 Agent）配置,在容器创建时运行一次。

认证是按 Agent 隔离的:每个 Agent 从自己的 agentDir 认证存储读取:

~/.openclaw/agents/<agentId>/agent/auth-profiles.json

凭据不会在 Agent 之间共享。永远不要在多个 Agent 之间重用 agentDir。 如果你想共享凭据,把 auth-profiles.json 复制到另一个 Agent 的 agentDir 中。

关于 Sandbox 运行时行为,参见 Sandboxing。 关于调试”为什么被阻止了?“,参见 Sandbox vs Tool Policy vs Elevated 和 openclaw sandbox explain。

配置示例

示例 1: 个人 + 受限家庭 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": "[email protected]"
        }
      }
    }
  ]
}

结果:

  • main Agent: 在宿主机上运行,拥有完整工具访问权限
  • family Agent: 在 Docker 中运行（每个 Agent 一个容器）,只能使用 read 工具

示例 2: 使用共享 Sandbox 的工作 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 使用不同的 Sandbox 模式

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main", // 全局默认
        "scope": "session"
      }
    },
    "list": [
      {
        "id": "main",
        "workspace": "~/.openclaw/workspace",
        "sandbox": {
          "mode": "off" // 覆盖: main 永不沙箱化
        }
      },
      {
        "id": "public",
        "workspace": "~/.openclaw/workspace-public",
        "sandbox": {
          "mode": "all", // 覆盖: public 始终沙箱化
          "scope": "agent"
        },
        "tools": {
          "allow": ["read"],
          "deny": ["exec", "write", "edit", "apply_patch"]
        }
      }
    ]
  }
}

配置优先级

当全局（agents.defaults.*）和 Agent 专属（agents.list[].*）配置同时存在时:

Sandbox 配置

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}.*（当 Sandbox 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. Sandbox 工具策略（tools.sandbox.tools 或 agents.list[].tools.sandbox.tools）
  8. Subagent 工具策略（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）格式。

工具组（简写）

工具策略（全局、Agent、Sandbox）支持 group:* 条目,可以展开为多个具体工具:

  • group:runtime: exec、bash、process
  • group:fs: read、write、edit、apply_patch
  • group:sessions: sessions_list、sessions_history、sessions_send、sessions_spawn、session_status
  • group:memory: memory_search、memory_get
  • group:ui: browser、canvas
  • group:automation: cron、gateway
  • group:messaging: message
  • group:nodes: nodes
  • group:openclaw: 所有内置 OpenClaw 工具（不包括 Provider Plugin）

Elevated 模式

tools.elevated 是全局基线（基于发送者的白名单）。agents.list[].tools.elevated 可以进一步限制特定 Agent 的 elevated 权限（两者都必须允许）。

缓解模式:

  • 为不受信任的 Agent 拒绝 exec（agents.list[].tools.deny: ["exec"]）
  • 避免将路由到受限 Agent 的发送者加入白名单
  • 如果你只想要沙箱化执行,全局禁用 elevated（tools.elevated.enabled: false）
  • 为敏感配置文件禁用单个 Agent 的 elevated（agents.list[].tools.elevated.enabled: false）

从单 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": {
    "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。群组/频道 Session 总是获得自己的键,所以它们 被视为 non-main 并会被沙箱化。如果你想让某个 Agent 永不沙箱化, 设置 agents.list[].sandbox.mode: "off"。

测试

配置多 Agent Sandbox 和工具后:

  1. 检查 Agent 解析:

    openclaw agents list --bindings

  2. 验证 Sandbox 容器:

    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 → Sandbox → Subagent
  • 每一层只能进一步限制,不能恢复
  • 通过日志验证: [tools] filtering tools for agent:${agentId}

容器未按 Agent 隔离

  • 在 Agent 专属 Sandbox 配置中设置 scope: "agent"
  • 默认是 "session",会为每个 Session 创建一个容器

另请参阅