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

Gateway

沙箱、工具政策與提升權限的比較

Status: active

OpenClaw 有三種彼此相關但不同的控制機制：

  1. 沙箱（agents.defaults.sandbox.* / agents.entries.*.sandbox.*）決定工具在哪裡執行（沙箱後端或主機）。
  2. 工具政策（tools.*、tools.sandbox.tools.*、agents.entries.*.tools.*）決定哪些工具可用／允許使用。
  3. 提升權限（tools.elevated.*、agents.entries.*.tools.elevated.*）是僅限執行的逃生機制，讓你在沙箱環境中能於沙箱外執行（預設為 gateway，或在執行目標設定為 node 時使用 node）。

快速偵錯

使用檢查器查看 OpenClaw _實際上_正在做什麼：

bash
openclaw sandbox explainopenclaw sandbox explain --session agent:main:mainopenclaw sandbox explain --agent workopenclaw sandbox explain --json

它會輸出：

  • 有效的沙箱模式／範圍／工作區存取權限
  • 工作階段目前是否在沙箱中（主要或非主要）
  • 有效的沙箱工具允許／拒絕設定（以及其來源是代理程式／全域／預設）
  • 提升權限閘門與修正用的設定鍵路徑

沙箱：工具在哪裡執行

沙箱由 agents.defaults.sandbox.mode 控制：

  • "off"：所有項目都在主機上執行。
  • "non-main"：只有非主要工作階段會在沙箱中執行（群組／頻道常見的「意外」情況）。
  • "all"：所有項目都在沙箱中執行。

agents.defaults.sandbox.workspaceAccess 控制沙箱可看見的內容："none"、"ro" 或 "rw"。

如需完整矩陣（範圍、工作區掛載、映像檔），請參閱沙箱化。

繫結掛載（安全性快速檢查）

  • docker.binds 會_穿透_沙箱檔案系統：無論掛載什麼，都會以你設定的模式（:ro 或 :rw）顯示在容器內。
  • 如果省略模式，預設為可讀寫；來源檔案／祕密建議使用 :ro。
  • scope: "shared" 會忽略個別代理程式的繫結（僅套用全域繫結）。
  • OpenClaw 會驗證繫結來源兩次：第一次驗證正規化後的來源路徑，接著在透過最深層的現有祖先目錄解析後再次驗證。透過符號連結父目錄逸出，無法規避封鎖路徑或允許根目錄檢查。
  • 不存在的葉節點路徑仍會受到安全檢查。如果 /workspace/alias-out/new-file 透過符號連結父目錄解析到封鎖路徑，或解析至設定的允許根目錄之外，該繫結會遭到拒絕。
  • 繫結 /var/run/docker.sock 實際上等同將主機控制權交給沙箱；只有在你有意這麼做時才使用。
  • 工作區存取權限（workspaceAccess）與繫結模式彼此獨立。

如需包含多個主機資料夾、存取模式，以及外部來源安全性選擇加入設定的個別代理程式組態，請參閱單一代理程式使用多個資料夾。

工具政策：哪些工具存在／可呼叫

有兩個重要層級：

  • 工具設定檔：tools.profile 和 agents.entries.*.tools.profile（基本允許清單）
  • 提供者工具設定檔：tools.byProvider[provider].profile 和 agents.entries.*.tools.byProvider[provider].profile
  • 全域／個別代理程式工具政策：tools.allow/tools.deny 和 agents.entries.*.tools.allow/agents.entries.*.tools.deny
  • 提供者工具政策：tools.byProvider[provider].allow/deny 和 agents.entries.*.tools.byProvider[provider].allow/deny
  • 沙箱工具政策（僅在沙箱環境中套用）：tools.sandbox.tools.allow/tools.sandbox.tools.deny 和 agents.entries.*.tools.sandbox.tools.*

經驗法則：

  • deny 一律優先。
  • 如果 allow 非空，其他所有項目都會被視為已封鎖。
  • 工具政策是不可跨越的限制：/exec 無法覆寫遭拒絕的 exec 工具。
  • 工具政策會依名稱篩選工具可用性；它不會檢查 exec 內部的副作用。如果允許 exec，拒絕 write、edit 或 apply_patch 並不會讓殼層命令變成唯讀。
  • /exec 只會變更已授權傳送者的工作階段預設值；不會授予工具存取權限。
  • 提供者工具鍵可接受 provider（例如 google-antigravity）或 provider/model（例如 openai/gpt-5.4）。
  • 當工具政策步驟移除工具，或沙箱工具政策封鎖呼叫時，閘道記錄會包含 agents/tool-policy 稽核項目。使用 openclaw logs 查看規則標籤、設定鍵和受影響的工具名稱。

工具群組（簡寫）

工具政策（全域、代理程式、沙箱）支援可展開成多個工具的 group:* 項目：

json5
{  tools: {    sandbox: {      tools: {        allow: ["group:runtime", "group:fs", "group:sessions", "group:memory"],      },    },  },}

可用群組：

群組 工具
group:runtime exec、process、code_execution（接受以 bash 作為 exec 的別名）
group:fs read、write、edit、apply_patch
group:sessions sessions、sessions_list、sessions_history、sessions_search、conversations_list、conversations_send、conversations_turn、sessions_send、sessions_spawn、sessions_yield、subagents、session_status、spawn_task、dismiss_task
group:memory memory_search、memory_get
group:web web_search、x_search、web_fetch
group:ui browser、screen、terminal、canvas、show_widget
group:automation heartbeat_respond、cron、gateway
group:messaging message
group:nodes nodes、computer
group:agents agents_list、get_goal、create_goal、update_goal、update_plan、ask_user、skill_workshop
group:media image、image_generate、music_generate、video_generate、tts
group:openclaw 大多數內建 OpenClaw 工具（不包含 read/write/edit/apply_patch/exec/process 檔案系統與執行階段基本功能、canvas，以及提供者外掛）
group:plugins 所有已載入且由外掛擁有的工具，包括透過 bundle-mcp 公開的已設定 MCP 伺服器

對於唯讀代理程式，除非沙箱檔案系統政策或另一個主機邊界會強制執行唯讀限制，否則除了會變更檔案系統的工具，也應拒絕 group:runtime。

對於沙箱化的 MCP 伺服器，沙箱工具政策是第二道允許閘門。如果已設定 mcp.servers，但沙箱化回合只顯示內建工具，請將 bundle-mcp、group:plugins，或以伺服器為前綴的 MCP 工具名稱／glob（例如 outlook__send_mail 或 outlook__*）新增至 tools.sandbox.tools.alsoAllow，然後重新啟動／重新載入閘道並再次擷取工具清單。伺服器 glob 使用提供者安全的 MCP 伺服器前綴：非 [A-Za-z0-9_-] 字元會變成 -，名稱若不是以字母開頭，會加上 mcp- 前綴，而過長或重複的前綴可能會被截短或加上後綴。

openclaw doctor 目前會針對 mcp.servers 中由 OpenClaw 管理的伺服器檢查此結構。從內建外掛資訊清單或 Claude .mcp.json 載入的 MCP 伺服器使用相同的沙箱閘門，但此診斷功能目前尚未列舉這些來源；如果其工具在沙箱化回合中消失，請使用相同的允許清單項目。

提升權限：僅限執行的「在主機上執行」

提升權限不會授予額外工具；它只會影響 exec。

  • 如果你在沙箱中，/elevated on（或搭配 elevated: true 的 exec）會在沙箱外執行（可能仍須經過核准）。
  • 使用 /elevated full 跳過該工作階段的執行核准。
  • 如果你已經直接執行，提升權限實際上不會產生作用（仍受閘門限制）。
  • 提升權限不會限定於特定 Skill，也不會覆寫工具允許／拒絕設定。
  • 提升權限不會從 host=auto 授予任意跨主機覆寫能力；它會遵循一般執行目標規則，而且只有在已設定／工作階段目標原本就是 node 時，才會保留 node。
  • /exec 與提升權限分開。它只會調整已授權傳送者的個別工作階段執行預設值。

閘門：

  • 啟用：tools.elevated.enabled（以及選用的 agents.entries.*.tools.elevated.enabled）
  • 傳送者允許清單：tools.elevated.allowFrom.<provider>（以及選用的 agents.entries.*.tools.elevated.allowFrom.<provider>）

請參閱提升權限模式。

常見的「沙箱牢籠」修正方式

「工具 X 遭沙箱工具政策封鎖」

修正用設定鍵（擇一）：

  • 停用沙箱：agents.defaults.sandbox.mode=off（或每個代理的 agents.entries.*.sandbox.mode=off）
  • 允許在沙箱內使用該工具：
    • 將它從 tools.sandbox.tools.deny 中移除（或每個代理的 agents.entries.*.tools.sandbox.tools.deny）
    • 或將它加入 tools.sandbox.tools.allow（或每個代理的允許清單）
  • 檢查 openclaw logs 中的 agents/tool-policy 項目。它會記錄沙箱模式，以及工具是否遭允許或拒絕規則封鎖。

“我以為這是主工作階段，為什麼會在沙箱中？”

在 "non-main" 模式下，群組／頻道金鑰並非主工作階段。請使用主工作階段金鑰（由 sandbox explain 顯示），或將模式切換為 "off"。

相關內容

Was this useful?
On this page

On this page