多代理沙箱與工具設定

概觀

在多代理架構中，每個代理可以擁有獨立的：

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

這讓你能以不同的安全設定檔運行多個代理：

  • 擁有完整權限的個人助理
  • 工具受限的家庭/工作代理
  • 在沙箱中運行的公開代理

setupCommand 放在 sandbox.docker 下（全域或每個代理），在容器建立時執行一次。

認證是每個代理獨立的：每個代理從其專屬的 agentDir 認證儲存讀取，位於：

~/.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：全域 coding 設定檔 + messaging 專屬代理

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

結果：

  • 預設代理取得 coding 工具
  • support 代理僅限 messaging（加上 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. 供應商工具設定檔（tools.byProvider[provider].profile 或 agents.list[].tools.byProvider[provider].profile）
  3. 全域工具策略（tools.allow / tools.deny）
  4. 供應商工具策略（tools.byProvider[provider].allow/deny）
  5. 代理專屬工具策略（agents.list[].tools.allow/deny）
  6. 代理供應商策略（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（例如 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 工具（不含供應商外掛）

提升模式

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。群組/頻道工作階段總是有自己的鍵值，因此會被視為 non-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"

工具儘管在 deny 清單中仍可使用

  • 檢查工具篩選順序：全域 → 代理 → 沙箱 → 子代理
  • 每一層只能進一步限制，無法恢復
  • 透過日誌驗證：[tools] filtering tools for agent:${agentId}

容器未按代理隔離

  • 在代理專屬沙箱設定中設定 scope: "agent"
  • 預設為 "session"，每個工作階段建立一個容器

另請參閱

arrow_back
上一頁
ACP Agents
下一頁
Creating Skills
arrow_forward