多代理沙箱和工具配置

概述

多代理设置中的每个代理现在可以有自己的：

  • 沙箱配置（agents.list[].sandbox 覆盖 agents.defaults.sandbox）
  • 工具限制（tools.allow / tools.deny，加上 agents.list[].tools）

这允许你以不同的安全配置文件运行多个代理：

  • 具有完全访问权限的个人助手
  • 具有受限工具的家庭/工作代理
  • 在沙箱中的面向公众的代理

setupCommand 属于 sandbox.docker（全局或每个代理），在容器创建时运行一次。

每个代理 auth：每个代理从自己的 agentDir auth 存储读取。

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

凭证不会在代理之间共享。永远不要跨代理重用 agentDir? 如果你想共享凭证，将 auth-profiles.json 复制到另一个代理的 agentDir?

关于沙箱在运行时的行为，见沙箱? 关于调试”为什么被阻止?，见沙箱 vs 工具策略 vs 提权 ?openclaw sandbox explain?

配置示例

示例 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"],
          "deny": ["exec", "write", "edit", "apply_patch", "process", "browser"]
        }
      }
    ]
  },
  "bindings": [
    {
      "agentId": "family",
      "match": {
        "provider": "whatsapp",
        "accountId": "*",
        "peer": {
          "kind": "group",
          "id": "[email protected]"
        }
      }
    }
  ]
}

*结果?

  • main 代理：在主机上运行，完全工具访问
  • family 代理：在 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" // 覆盖：main 永不离上沙箱
        }
      },
      {
        "id": "public",
        "workspace": "~/.openclaw/workspace-public",
        "sandbox": {
          "mode": "all", // 覆盖：public 始终沙箱?
          "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.*

*注意?

  • agents.list[].sandbox.{docker,browser,prune}.* 为该代理覆盖 agents.defaults.sandbox.{docker,browser,prune}.*（当沙箱作用域解析为 "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. 代理特定工具策略（agents.list[].tools.allow/deny?
  6. 代理 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，它会替换该代理?tools.sandbox.tools? 如果设置?agents.list[].tools.profile，它会覆盖该代理?tools.profile? Provider 工具键接?provider（例?google-antigravity）或 provider/model（例?openai/gpt-5.2）?

工具组（简写）

工具策略（全局、代理、沙箱）支持扩展为多个具体工具的 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 插件?

提权模式

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

缓解模式?

  • 拒绝不受信任代理?exec（agents.list[].tools.deny: ["exec"]?
  • 避免白名单路由到受限代理的发送?
  • 如果你只想要沙箱执行，全局禁用提权（tools.elevated.enabled: false?
  • 为敏感配置文件禁用每个代理的提权（agents.list[].tools.elevated.enabled: false?

从单代理迁移

之前（单代理）：

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

旧版 agent.* 配置?openclaw doctor 迁移；优先使?agents.defaults + agents.list?

工具限制示例

仅读取代?

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

常见陷阱?non-main”

agents.defaults.sandbox.mode: "non-main" 基于 session.mainKey（默?"main"），而不是代?id。群?频道会话总是获得自己的键，因此它们被视为?main 将被沙箱化。如果你想让代理永远不离上沙箱，设置 agents.list[].sandbox.mode: "off"?

测试

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

  1. 检查代理解析：

    openclaw agents list --bindings

  2. *验证沙箱容器?

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

  3. *测试工具限制?

    • 发送需要受限工具的消息
    • 验证代理不能使用被拒绝的工具

  4. *监控日志?

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

故障排除

代理尽管设置?mode: "all" 但未被沙箱化

  • 检查是否有覆盖它的全局 agents.defaults.sandbox.mode
  • 代理特定配置优先，所以设?agents.list[].sandbox.mode: "all"

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

  • 检查工具过滤顺序：全局 ?代理 ?沙箱 ?子代?
  • 每个级别只能进一步限制，不能授予?
  • 用日志验证：[tools] filtering tools for agent:${agentId}

容器未按代理隔离

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

另见