多代理沙箱與工具

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

沙箱隔離

後端與模式 — 完整的沙箱參考資料。

沙箱、工具原則與提升權限的比較

偵錯「為什麼會被封鎖？」

提升權限模式

供受信任傳送者使用的提升權限執行功能。

驗證以代理為範圍：每個代理在 ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite 中都有自己的 agentDir 驗證儲存區。絕不可跨代理重複使用 agentDir。代理沒有本機設定檔時，可以讀取預設／主要代理的驗證設定檔，但 OAuth 重新整理權杖不會複製到次要代理儲存區。如果手動複製認證資訊，請僅複製可攜式靜態 api_key 或 token 設定檔。

---

​

設定範例

範例 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": "[e-mail]"
        }
      }
    }
  ]
}

結果：

• 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.mode
agents.entries.*.sandbox.scope > agents.defaults.sandbox.scope
agents.entries.*.sandbox.workspaceRoot > agents.defaults.sandbox.workspaceRoot
agents.entries.*.sandbox.workspaceAccess > agents.defaults.sandbox.workspaceAccess
agents.entries.*.sandbox.docker.* > agents.defaults.sandbox.docker.*
agents.entries.*.sandbox.browser.* > agents.defaults.sandbox.browser.*
agents.entries.*.sandbox.prune.* > agents.defaults.sandbox.prune.*

agents.entries.*.sandbox.{docker,browser,prune}.* 會針對該代理覆寫 agents.defaults.sandbox.{docker,browser,prune}.*（當沙箱範圍解析為 "shared" 時會忽略）。

​

工具限制

篩選順序如下：

1. 工具設定檔

   tools.profile 或 agents.entries.*.tools.profile。

2. 供應商工具設定檔

   tools.byProvider[provider].profile 或 agents.entries.*.tools.byProvider[provider].profile。

3. 全域工具原則

   tools.allow / tools.deny。

4. 供應商工具原則

   tools.byProvider[provider].allow/deny。

5. 代理專屬工具原則

   agents.entries.*.tools.allow/deny。

6. 代理供應商原則

   agents.entries.*.tools.byProvider[provider].allow/deny。

7. 沙箱工具原則

   tools.sandbox.tools 或 agents.entries.*.tools.sandbox.tools。

8. 子代理工具原則

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

舊版 agents.defaults.*/agents.entries.*.* 設定鍵（例如 sandbox.perSession、agentRuntime、embeddedPi）會由 openclaw doctor 遷移；之後請優先使用 agents.defaults + agents.entries。

---

​

工具限制範例

唯讀代理

{
  "tools": {
    "allow": ["read"],
    "deny": ["exec", "write", "edit", "apply_patch", "process"]
  }
}

停用檔案系統工具的 Shell 執行

{
  "tools": {
    "allow": ["read", "exec", "process"],
    "deny": ["write", "edit", "apply_patch", "browser", "gateway"]
  }
}

此原則會停用 OpenClaw 檔案系統工具，但 exec 仍是 Shell，且可以在所選主機或沙箱檔案系統允許的任何位置寫入檔案。若要建立唯讀代理，請拒絕 exec 與 process，或將 Shell 存取權與 agents.defaults.sandbox.workspaceAccess: "ro" 或 "none" 等沙箱檔案系統控制搭配使用。

僅限通訊

{
  "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」

agents.defaults.sandbox.mode: "non-main" 會比對工作階段鍵與主要工作階段鍵（固定為 "main"；session.mainKey 不可由使用者設定，而且 OpenClaw 會針對任何其他值發出警告並予以忽略），而不是比對代理 ID。群組／頻道工作階段一律擁有自己的鍵，因此會被視為非主要工作階段並套用沙箱。如果希望代理永遠不使用沙箱，請設定 agents.entries.*.sandbox.mode: "off"。

---

​

測試

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

1. 檢查代理解析結果

   openclaw agents list --bindings
   
2. 驗證沙箱容器

   docker ps --filter "name=openclaw-sbx-"
   
3. 測試工具限制

   • 傳送需要受限制工具的訊息。
   • 確認代理無法使用被拒絕的工具。
4. 監控記錄

   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" 以在多個代理程式之間重複使用同一個容器。

---

​

相關內容

• 提升權限模式
• 多代理程式路由
• 沙箱設定
• 沙箱、工具政策與提升權限的比較 — 偵錯「為什麼這會遭到封鎖？」
• 沙箱隔離 — 完整的沙箱參考資料（模式、範圍、後端、映像檔）
• 工作階段管理