Agent coordination
多代理沙箱與工具
多代理設定中的每個代理都可以覆寫全域沙箱與工具原則。本頁說明各代理設定、優先順序規則及範例。
設定範例
範例 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": "120363424282127706@g.us" } } } ]}結果：
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" } }, { "id": "public", "workspace": "~/.openclaw/workspace-public", "sandbox": { "mode": "all", "scope": "agent" }, "tools": { "allow": ["read"], "deny": ["exec", "write", "edit", "apply_patch"] } } ] }}設定優先順序
同時存在全域（agents.defaults.*）與代理專屬（agents.entries.*.*）設定時：
沙箱設定
代理專屬設定會覆寫全域設定：
agents.entries.*.sandbox.mode > agents.defaults.sandbox.modeagents.entries.*.sandbox.scope > agents.defaults.sandbox.scopeagents.entries.*.sandbox.workspaceRoot > agents.defaults.sandbox.workspaceRootagents.entries.*.sandbox.workspaceAccess > agents.defaults.sandbox.workspaceAccessagents.entries.*.sandbox.docker.* > agents.defaults.sandbox.docker.*agents.entries.*.sandbox.browser.* > agents.defaults.sandbox.browser.*agents.entries.*.sandbox.prune.* > agents.defaults.sandbox.prune.*工具限制
篩選順序如下：
工具設定檔
tools.profile 或 agents.entries.*.tools.profile。
供應商工具設定檔
tools.byProvider[provider].profile 或 agents.entries.*.tools.byProvider[provider].profile。
全域工具原則
tools.allow / tools.deny。
供應商工具原則
tools.byProvider[provider].allow/deny。
代理專屬工具原則
agents.entries.*.tools.allow/deny。
代理供應商原則
agents.entries.*.tools.byProvider[provider].allow/deny。
沙箱工具原則
tools.sandbox.tools 或 agents.entries.*.tools.sandbox.tools。
子代理工具原則
tools.subagents.tools（如適用）。
優先順序規則
- 每個層級都可以進一步限制工具，但無法重新授予先前層級已拒絕的工具。
- 如果已設定
agents.entries.*.tools.sandbox.tools，它會針對該代理取代tools.sandbox.tools。 - 如果已設定
agents.entries.*.tools.profile，它會針對該代理覆寫tools.profile。 - 供應商工具鍵可接受
provider（例如google-antigravity）或provider/model（例如openai/gpt-5.4）。
空白允許清單的行為
如果該鏈中的任何明確允許清單導致執行時沒有可呼叫的工具，OpenClaw 會在將提示提交給模型之前停止。這是刻意設計的行為：設定了缺少工具（例如 agents.entries.*.tools.allow: ["query_db"]）的代理，應明確失敗，直到啟用註冊 query_db 的外掛為止，而不是繼續作為純文字代理執行。
工具原則支援可展開為多個工具的 group:* 簡寫。完整清單請參閱工具群組。
各代理的提升權限覆寫（agents.entries.*.tools.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"] }}停用檔案系統工具的 Shell 執行
{ "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 仍會傳回有界限且經過清理的回憶檢視，而不是原始逐字稿傾印。代理助理回憶會先移除思考標籤、<relevant-memories> 鷹架、純文字工具呼叫 XML 承載資料（包括 <tool_call>...</tool_call>、<function_call>...</function_call>、<tool_calls>...</tool_calls>、<function_calls>...</function_calls> 及遭截斷的工具呼叫區塊）、降級的工具呼叫鷹架、洩漏的 ASCII／全形模型控制權杖，以及格式錯誤的 MiniMax 工具呼叫 XML，再進行遮蔽／截斷。
常見陷阱：「non-main」
測試
設定多代理沙箱與工具後：
檢查代理解析結果
openclaw agents list --bindings驗證沙箱容器
docker ps --filter "name=openclaw-sbx-"測試工具限制
- 傳送需要受限制工具的訊息。
- 確認代理無法使用被拒絕的工具。
監控記錄
openclaw logs --follow | grep -E "routing|sandbox|tools"疑難排解
即使設定 `mode: 'all'`，代理仍未套用沙箱
- 檢查是否有全域
agents.defaults.sandbox.mode覆寫該設定。 - 代理專屬設定的優先順序較高，因此請設定
agents.entries.*.sandbox.mode: "all"。
即使有拒絕清單仍可使用的工具
- 檢查完整的篩選順序：設定檔 → 提供者設定檔 → 全域政策 → 提供者政策 → 代理程式政策 → 代理程式提供者政策 → 沙箱 → 子代理程式。
- 每一層只能進一步限制，無法重新授予權限。
- 請參閱沙箱、工具政策與提升權限的比較，以進行逐步偵錯。
容器未依每個代理程式隔離
- 預設的
scope是"agent"（每個代理程式 ID 使用一個容器）。 - 設定
scope: "session"可讓每個工作階段使用一個容器，或設定scope: "shared"以在多個代理程式之間重複使用同一個容器。
