OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Agent coordination

多代理沙箱與工具

Status: active

多代理設定中的每個代理都可以覆寫全域沙箱與工具原則。本頁說明各代理的設定、優先順序規則及範例。

沙箱

後端與模式——完整的沙箱參考資料。
沙箱、工具原則與提升權限的比較

偵錯「為什麼這會被封鎖？」
提升權限模式

允許受信任傳送者以提升權限執行命令。

設定範例

範例 1：個人代理與受限的家庭代理
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 代理：在主機上執行，擁有完整的工具存取權。
  • family 代理：在 Docker 中執行（每個代理使用一個容器），僅能使用 read，以及在目前對話中傳送訊息。
範例 2：使用共用沙箱的工作代理
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：全域程式設計設定檔與僅限通訊的代理
json
{  "tools": { "profile": "coding" },  "agents": {    "list": [      {        "id": "support",        "tools": { "profile": "messaging", "allow": ["slack"] }      }    ]  }}

結果：

  • 預設代理會取得程式設計工具。
  • support 代理僅能使用通訊工具（外加 Slack 工具）。
範例 3：各代理使用不同的沙箱模式
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.*）與代理專屬設定（agents.list[].*）同時存在時：

沙箱設定

代理專屬設定會覆寫全域設定：

text
agents.list[].sandbox.mode > agents.defaults.sandbox.modeagents.list[].sandbox.scope > agents.defaults.sandbox.scopeagents.list[].sandbox.workspaceRoot > agents.defaults.sandbox.workspaceRootagents.list[].sandbox.workspaceAccess > agents.defaults.sandbox.workspaceAccessagents.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，它會為該代理取代 tools.sandbox.tools。
    • 如果設定了 agents.list[].tools.profile，它會為該代理覆寫 tools.profile。
    • 供應商工具鍵可接受 provider（例如 google-antigravity）或 provider/model（例如 openai/gpt-5.4）。
    空白允許清單的行為

    如果該鏈中的任何明確允許清單導致此次執行沒有可呼叫的工具，OpenClaw 會在將提示提交給模型之前停止。這是刻意設計的行為：若代理設定了尚不存在的工具，例如 agents.list[].tools.allow: ["query_db"]，就應在註冊 query_db 的外掛啟用前明確失敗，而不是繼續作為純文字代理執行。

    工具原則支援 group:* 簡寫，可展開為多個工具。完整清單請參閱工具群組。

    各代理的提升權限覆寫設定（agents.list[].tools.elevated）可以進一步限制特定代理的提升權限命令執行。詳細資訊請參閱提升權限模式。

    從單一代理移轉

    之前（單一代理）

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

    之後（多代理）

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

    工具限制範例

    唯讀代理

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

    僅限通訊

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

    此設定檔中的 sessions_history 仍會傳回有界且經過清理的回憶檢視，而非原始逐字記錄傾印。代理回憶會先移除思考標籤、<relevant-memories> 鷹架、純文字工具呼叫 XML 承載資料（包括 <tool_call>...</tool_call>、<function_call>...</function_call>、<tool_calls>...</tool_calls>、<function_calls>...</function_calls> 及遭截斷的工具呼叫區塊）、降級的工具呼叫鷹架、洩漏的 ASCII／全形模型控制權杖，以及格式錯誤的 MiniMax 工具呼叫 XML，之後才進行遮蔽與截斷。

    常見陷阱："non-main"

    測試

    設定多代理沙箱與工具後：

  • 檢查代理解析結果

    bash
    openclaw agents list --bindings

  • 驗證沙箱容器

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

  • 測試工具限制

    • 傳送需要受限工具的訊息。
    • 驗證代理無法使用被拒絕的工具。

  • 監控記錄

    bash
    openclaw logs --follow | grep -E "routing|sandbox|tools"

    • 疑難排解

    儘管設定了 `mode: 'all'`，代理仍未進入沙箱
    • 檢查是否存在會覆寫它的全域 agents.defaults.sandbox.mode。
    • 代理專屬設定的優先順序較高，因此請設定 agents.list[].sandbox.mode: "all"。
    儘管有拒絕清單，工具仍可使用
    • 檢查完整的篩選順序：設定檔 → 提供者設定檔 → 全域政策 → 提供者政策 → 代理程式政策 → 代理程式提供者政策 → 沙箱 → 子代理程式。
    • 每一層都只能進一步限制，無法重新授予權限。
    • 如需逐步偵錯，請參閱沙箱與工具政策及提升權限的比較。
    容器未按代理程式隔離
    • 預設 scope 為 "agent"（每個代理程式 ID 使用一個容器）。
    • 設定 scope: "session" 可讓每個工作階段使用一個容器，或設定 scope: "shared" 讓多個代理程式共用一個容器。

    相關內容

    Was this useful?
    On this page

    On this page