> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 多代理沙箱與工具

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

<CardGroup cols={3}>
  <Card title="沙箱化" href="/zh-TW/gateway/sandboxing">
    後端與模式 — 完整沙箱參考。
  </Card>

  <Card title="沙箱 vs 工具政策 vs 提權" href="/zh-TW/gateway/sandbox-vs-tool-policy-vs-elevated">
    除錯「為什麼這被封鎖？」
  </Card>

  <Card title="提權模式" href="/zh-TW/tools/elevated">
    供受信任傳送者使用的提權 exec。
  </Card>
</CardGroup>

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

***

## 設定範例

<AccordionGroup>
  <Accordion title="範例 1：個人代理 + 受限制的家庭代理">
    ```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
    {
      "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` 與目前對話的訊息傳送。
  </Accordion>

  <Accordion title="範例 2：使用共享沙箱的工作代理">
    ```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
    {
      "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"]
            }
          }
        ]
      }
    }
    ```
  </Accordion>

  <Accordion title="範例 2b：全域寫程式設定檔 + 僅訊息代理">
    ```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
    {
      "tools": { "profile": "coding" },
      "agents": {
        "list": [
          {
            "id": "support",
            "tools": { "profile": "messaging", "allow": ["slack"] }
          }
        ]
      }
    }
    ```

    **結果：**

    * 預設代理會取得寫程式工具。
    * `support` 代理僅能處理訊息（+ Slack 工具）。
  </Accordion>

  <Accordion title="範例 3：每個代理使用不同沙箱模式">
    ```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
    {
      "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"]
            }
          }
        ]
      }
    }
    ```
  </Accordion>
</AccordionGroup>

***

## 設定優先順序

當全域（`agents.defaults.*`）與代理專屬（`agents.list[].*`）設定同時存在時：

### 沙箱設定

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

```text theme={"theme":{"light":"min-light","dark":"min-dark"}}
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.*
```

<Note>
  `agents.list[].sandbox.{docker,browser,prune}.*` 會為該代理覆寫 `agents.defaults.sandbox.{docker,browser,prune}.*`（當沙箱範圍解析為 `"shared"` 時會被忽略）。
</Note>

### 工具限制

篩選順序如下：

<Steps>
  <Step title="工具設定檔">
    `tools.profile` 或 `agents.list[].tools.profile`。
  </Step>

  <Step title="提供者工具設定檔">
    `tools.byProvider[provider].profile` 或 `agents.list[].tools.byProvider[provider].profile`。
  </Step>

  <Step title="全域工具政策">
    `tools.allow` / `tools.deny`。
  </Step>

  <Step title="提供者工具政策">
    `tools.byProvider[provider].allow/deny`。
  </Step>

  <Step title="代理專屬工具政策">
    `agents.list[].tools.allow/deny`。
  </Step>

  <Step title="代理提供者政策">
    `agents.list[].tools.byProvider[provider].allow/deny`。
  </Step>

  <Step title="沙箱工具政策">
    `tools.sandbox.tools` 或 `agents.list[].tools.sandbox.tools`。
  </Step>

  <Step title="子代理工具政策">
    `tools.subagents.tools`，如果適用。
  </Step>
</Steps>

<AccordionGroup>
  <Accordion title="優先順序規則">
    * 每一層都可以進一步限制工具，但不能重新授予先前層級已拒絕的工具。
    * 如果設定了 `agents.list[].tools.sandbox.tools`，它會取代該代理的 `tools.sandbox.tools`。
    * 如果設定了 `agents.list[].tools.profile`，它會覆寫該代理的 `tools.profile`。
    * 提供者工具鍵可接受 `provider`（例如 `google-antigravity`）或 `provider/model`（例如 `openai/gpt-5.4`）。
  </Accordion>

  <Accordion title="空白允許清單行為">
    如果該鏈中的任何明確允許清單讓執行沒有任何可呼叫工具，OpenClaw 會在將提示提交給模型之前停止。這是刻意設計：設定了缺少工具（例如 `agents.list[].tools.allow: ["query_db"]`）的代理，應該在註冊 `query_db` 的外掛啟用之前明確失敗，而不是以純文字代理繼續執行。
  </Accordion>
</AccordionGroup>

工具政策支援會展開為多個工具的 `group:*` 簡寫。完整清單請參閱[工具群組](/zh-TW/gateway/sandbox-vs-tool-policy-vs-elevated#tool-groups-shorthands)。

每代理提權覆寫（`agents.list[].tools.elevated`）可以進一步限制特定代理的提權 exec。詳細資訊請參閱[提權模式](/zh-TW/tools/elevated)。

***

## 從單一代理遷移

<Tabs>
  <Tab title="之前（單一代理）">
    ```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
    {
      "agents": {
        "defaults": {
          "workspace": "~/.openclaw/workspace",
          "sandbox": {
            "mode": "non-main"
          }
        }
      },
      "tools": {
        "sandbox": {
          "tools": {
            "allow": ["read", "write", "apply_patch", "exec"],
            "deny": []
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="之後（多代理）">
    ```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
    {
      "agents": {
        "list": [
          {
            "id": "main",
            "default": true,
            "workspace": "~/.openclaw/workspace",
            "sandbox": { "mode": "off" }
          }
        ]
      }
    }
    ```
  </Tab>
</Tabs>

<Note>
  舊版 `agents.defaults.*`/`agents.list[].*` 設定鍵（例如 `sandbox.perSession`、`agentRuntime`、`embeddedPi`）會由 `openclaw doctor` 遷移；往後請優先使用 `agents.defaults` + `agents.list`。
</Note>

***

## 工具限制範例

<Tabs>
  <Tab title="唯讀代理">
    ```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
    {
      "tools": {
        "allow": ["read"],
        "deny": ["exec", "write", "edit", "apply_patch", "process"]
      }
    }
    ```
  </Tab>

  <Tab title="停用檔案系統工具的 Shell 執行">
    ```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
    {
      "tools": {
        "allow": ["read", "exec", "process"],
        "deny": ["write", "edit", "apply_patch", "browser", "gateway"]
      }
    }
    ```

    <Warning>
      此政策會停用 OpenClaw 檔案系統工具，但 `exec` 仍然是 shell，且可在所選主機或沙箱檔案系統允許的任何位置寫入檔案。若要建立唯讀代理，請拒絕 `exec` 與 `process`，或將 shell 存取與沙箱檔案系統控制結合，例如 `agents.defaults.sandbox.workspaceAccess: "ro"` 或 `"none"`。
    </Warning>
  </Tab>

  <Tab title="僅通訊">
    ```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
    {
      "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。
  </Tab>
</Tabs>

***

## 常見陷阱：「non-main」

<Warning>
  `agents.defaults.sandbox.mode: "non-main"` 會將工作階段鍵與主要工作階段鍵比對（永遠是 `"main"`；`session.mainKey` 不可由使用者設定，OpenClaw 會警告並忽略任何其他值），而不是比對代理 ID。群組/頻道工作階段永遠會取得自己的鍵，因此會被視為非主要並進入沙箱。如果你希望某個代理永不進入沙箱，請設定 `agents.list[].sandbox.mode: "off"`。
</Warning>

***

## 測試

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

<Steps>
  <Step title="檢查代理解析">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    openclaw agents list --bindings
    ```
  </Step>

  <Step title="驗證沙箱容器">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    docker ps --filter "name=openclaw-sbx-"
    ```
  </Step>

  <Step title="測試工具限制">
    * 傳送一則需要受限制工具的訊息。
    * 驗證代理無法使用被拒絕的工具。
  </Step>

  <Step title="監控記錄">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    openclaw logs --follow | grep -E "routing|sandbox|tools"
    ```
  </Step>
</Steps>

***

## 疑難排解

<AccordionGroup>
  <Accordion title="儘管 `mode: 'all'`，代理仍未進入沙箱">
    * 檢查是否有全域 `agents.defaults.sandbox.mode` 覆寫它。
    * 代理專屬設定優先，因此請設定 `agents.list[].sandbox.mode: "all"`。
  </Accordion>

  <Accordion title="即使有拒絕清單，工具仍可用">
    * 查看[完整篩選順序](#tool-restrictions)：設定檔 → 供應商設定檔 → 全域政策 → 供應商政策 → 代理政策 → 代理供應商政策 → 沙盒 → 子代理。
    * 每一層只能進一步限制，不能重新授權。
    * 請參閱[沙盒與工具政策與提權](/zh-TW/gateway/sandbox-vs-tool-policy-vs-elevated)，取得逐步除錯說明。
  </Accordion>

  <Accordion title="容器未依每個代理隔離">
    * 預設 `scope` 是 `"agent"`（每個代理 ID 一個容器）。
    * 設定 `scope: "session"` 以讓每個工作階段使用一個容器，或設定 `scope: "shared"` 以在多個代理之間重用同一個容器。
  </Accordion>
</AccordionGroup>

***

## 相關

* [提權模式](/zh-TW/tools/elevated)
* [多代理路由](/zh-TW/concepts/multi-agent)
* [沙盒設定](/zh-TW/gateway/config-agents#agentsdefaultssandbox)
* [沙盒與工具政策與提權](/zh-TW/gateway/sandbox-vs-tool-policy-vs-elevated) — 除錯「為什麼這被封鎖？」
* [沙盒化](/zh-TW/gateway/sandboxing) — 完整沙盒參考（模式、範圍、後端、映像檔）
* [工作階段管理](/zh-TW/concepts/session)