沙箱 vs 工具策略 vs 提權

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

1. 沙箱（agents.defaults.sandbox.* / agents.list[].sandbox.*）決定工具在哪裡執行（Docker 或主機）。
2. 工具策略（tools.*、tools.sandbox.tools.*、agents.list[].tools.*）決定哪些工具可用/允許使用。
3. 提權（tools.elevated.*、agents.list[].tools.elevated.*）是專用於 exec 的逃脫機制，讓你在沙箱環境中也能在主機上執行。

快速除錯

用檢查工具看看 OpenClaw _實際上_在做什麼：

openclaw sandbox explain
openclaw sandbox explain --session agent:main:main
openclaw sandbox explain --agent work
openclaw sandbox explain --json

輸出內容包括：

• 生效的沙箱模式/範圍/工作區存取
• 目前 session 是否處於沙箱中（main 與非 main）
• 生效的沙箱工具 allow/deny（以及設定來源是 agent/全域/預設）
• 提權閘門及修正用的 key path

沙箱：工具在哪裡執行

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

• "off"：所有工具都在主機上執行。
• "non-main"：只有非 main session 會被沙箱化（群組/頻道常見的「意外驚喜」來源）。
• "all"：所有工具都在沙箱中執行。

詳見 沙箱 的完整對照表（範圍、工作區掛載、映像檔）。

Bind mount（安全快速檢查）

• docker.binds 會_穿透_沙箱檔案系統：你掛載的目錄在容器內可見，權限取決於你設定的模式（:ro 或 :rw）。
• 如果省略模式，預設是讀寫；原始碼/機密資料建議用 :ro。
• scope: "shared" 會忽略各代理的 bind（只有全域 bind 生效）。
• 掛載 /var/run/docker.sock 等於把主機控制權交給沙箱，除非你有明確意圖，否則不要這麼做。
• 工作區存取（workspaceAccess: "ro"/"rw"）與 bind 模式是獨立的。

工具策略：哪些工具存在/可呼叫

有兩層需要注意：

• 工具 profile：tools.profile 和 agents.list[].tools.profile（基礎白名單）
• Provider 工具 profile：tools.byProvider[provider].profile 和 agents.list[].tools.byProvider[provider].profile
• 全域/各代理工具策略：tools.allow/tools.deny 和 agents.list[].tools.allow/agents.list[].tools.deny
• Provider 工具策略：tools.byProvider[provider].allow/deny 和 agents.list[].tools.byProvider[provider].allow/deny
• 沙箱工具策略（僅在沙箱中生效）：tools.sandbox.tools.allow/tools.sandbox.tools.deny 和 agents.list[].tools.sandbox.tools.*

基本原則：

• deny 永遠優先。
• 如果 allow 不為空，其他未列入的工具都會被封鎖。
• 工具策略是硬性限制：/exec 無法覆寫已被 deny 的 exec 工具。
• /exec 只針對已授權的發送者調整 session 預設值，不會授予工具存取權。 Provider 工具 key 接受 provider（例如 google-antigravity）或 provider/model（例如 openai/gpt-5.2）。

工具群組（速記）

工具策略（全域、代理、沙箱）支援 group:* 項目，會展開成多個工具：

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

可用的群組：

• group:runtime：exec、bash、process
• group:fs：read、write、edit、apply_patch
• group:sessions：sessions_list、sessions_history、sessions_send、sessions_spawn、session_status
• group:memory：memory_search、memory_get
• group:ui：browser、canvas
• group:automation：cron、gateway
• group:messaging：message
• group:nodes：nodes
• group:openclaw：所有內建 OpenClaw 工具（不含 provider 外掛）

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

提權不會授予額外工具，只影響 exec。

• 在沙箱中，/elevated on（或 exec 加上 elevated: true）會在主機上執行（可能仍需核准）。
• 使用 /elevated full 可在該 session 中跳過 exec 核准。
• 如果已經在主機上直接執行，提權基本上沒有效果（仍受閘門控制）。
• 提權不是按技能區分的，也不會覆寫工具 allow/deny。
• /exec 與提權是分開的。它只針對已授權的發送者調整各 session 的 exec 預設值。

閘門：

• 啟用：tools.elevated.enabled（以及可選的 agents.list[].tools.elevated.enabled）
• 發送者白名單：tools.elevated.allowFrom.<provider>（以及可選的 agents.list[].tools.elevated.allowFrom.<provider>）

詳見 提權模式。

常見的「沙箱牢籠」解法

「工具 X 被沙箱工具策略封鎖」

修正用 key（擇一）：

• 停用沙箱：agents.defaults.sandbox.mode=off（或各代理 agents.list[].sandbox.mode=off）
• 在沙箱內允許該工具：
  • 從 tools.sandbox.tools.deny 中移除它（或各代理的 agents.list[].tools.sandbox.tools.deny）
  • 或將它加入 tools.sandbox.tools.allow（或各代理的 allow）

「我以為這是 main，為什麼被沙箱化了？」

在 "non-main" 模式下，群組/頻道的 key 不算 main。使用 main session key（可透過 sandbox explain 查看），或把模式切到 "off"。