跳轉到主要內容

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.

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

沙盒化

後端與模式 — 完整沙盒參考。

沙盒 vs 工具政策 vs 提權

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

提權模式

受信任傳送者的提權執行。
驗證依代理限定範圍：每個代理都有自己的 agentDir 驗證儲存區，位於 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json。切勿在代理之間重複使用 agentDir。代理在沒有本機設定檔時，可以讀取預設/主要代理的驗證設定檔，但 OAuth 重新整理權杖不會複製到次要代理儲存區。如果你手動複製憑證，請只複製可攜式靜態 api_key 或 token 設定檔。

​
設定範例

{
  "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 和目前對話訊息傳送。
{
  "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"]
        }
      }
    ]
  }
}

{
  "tools": { "profile": "coding" },
  "agents": {
    "list": [
      {
        "id": "support",
        "tools": { "profile": "messaging", "allow": ["slack"] }
      }
    ]
  }
}
結果：
  • 預設代理會取得程式碼工具。
  • support 代理僅限訊息（+ Slack 工具）。
{
  "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[].*）設定同時存在時：

​
沙盒設定

代理特定設定會覆寫全域設定： 
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.4）。
如果該鏈中的任何明確允許清單使該次執行沒有可呼叫的工具，OpenClaw 會在將提示提交給模型前停止。這是刻意設計：設定了遺失工具（例如 agents.list[].tools.allow: ["query_db"]）的代理應該明確失敗，直到註冊 query_db 的 Plugin 啟用為止，而不是繼續作為純文字代理。
工具政策支援會展開為多個工具的 group:* 簡寫。完整清單請參閱工具群組。 每代理提權覆寫（agents.list[].tools.elevated）可以進一步限制特定代理的提權執行。詳情請參閱提權模式。

​
從單一代理遷移

{
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace",
      "sandbox": {
        "mode": "non-main"
      }
    }
  },
  "tools": {
    "sandbox": {
      "tools": {
        "allow": ["read", "write", "apply_patch", "exec"],
        "deny": []
      }
    }
  }
}
舊版 agent.* 設定會由 openclaw doctor 遷移；往後請優先使用 agents.defaults + agents.list。

​
工具限制範例

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

​
常見陷阱：“non-main”

agents.defaults.sandbox.mode: "non-main" 是以 session.mainKey（預設為 "main"）為基礎，而不是代理 id。群組/頻道工作階段一律會取得自己的金鑰，因此會被視為非 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"

​
疑難排解

  • 檢查是否有全域 agents.defaults.sandbox.mode 覆寫它。
  • 代理專屬設定優先，因此請設定 agents.list[].sandbox.mode: "all"。
  • 檢查工具篩選順序：全域 → 代理 → 沙盒 → 子代理。
  • 每個層級只能進一步限制，不能重新授權。
  • 使用日誌驗證：[tools] filtering tools for agent:${agentId}。
  • 在代理專屬沙盒設定中設定 scope: "agent"。
  • 預設為 "session"，會為每個工作階段建立一個容器。

​
相關