沙箱

OpenClaw 可以在 Docker 容器內執行工具以降低影響範圍。 這是選用的功能，由設定控制（agents.defaults.sandbox 或 agents.list[].sandbox）。如果沙箱關閉，工具直接在主機上執行。 Gateway 始終在主機上執行；只有工具執行會在啟用時被隔離到沙箱中。

這不是完美的安全邊界，但在模型做出蠢事時，確實能有效限制檔案系統和程序的存取範圍。

什麼會被沙箱化

  • 工具執行（exec、read、write、edit、apply_patch、process 等）。
  • 可選的沙箱瀏覽器（agents.defaults.sandbox.browser）。
    • 沙箱瀏覽器預設會在瀏覽器工具需要時自動啟動（確保 CDP 可連線）。 可透過 agents.defaults.sandbox.browser.autoStart 和 agents.defaults.sandbox.browser.autoStartTimeoutMs 設定。
    • 沙箱瀏覽器容器預設使用專用的 Docker 網路（openclaw-sandbox-browser），而非全域 bridge 網路。 可透過 agents.defaults.sandbox.browser.network 設定。
    • 可選的 agents.defaults.sandbox.browser.cdpSourceRange 用 CIDR 白名單限制容器端 CDP 入口（例如 172.21.0.1/32）。
    • noVNC 觀察者存取預設受密碼保護；OpenClaw 會產生一個短效 token URL，透過本機引導頁面開啟 noVNC，密碼放在 URL fragment 中（不是 query/header 日誌）。
    • agents.defaults.sandbox.browser.allowHostControl 允許沙箱 session 明確指定使用主機瀏覽器。
    • 可選的白名單控制 target: "custom"：allowedControlUrls、allowedControlHosts、allowedControlPorts。

不會被沙箱化的：

  • Gateway 程序本身。
  • 任何明確允許在主機上執行的工具（例如 tools.elevated）。
    • 提權 exec 在主機上執行，繞過沙箱。
    • 如果沙箱關閉，tools.elevated 不改變執行方式（本來就在主機上）。詳見 提權模式。

模式

agents.defaults.sandbox.mode 控制何時使用沙箱：

  • "off"：不使用沙箱。
  • "non-main"：只沙箱化非 main session（適合希望一般聊天在主機上執行的情境）。
  • "all"：每個 session 都在沙箱中執行。 注意："non-main" 是基於 session.mainKey（預設 "main"），不是代理 ID。 群組/頻道 session 使用自己的 key，所以算作非 main，會被沙箱化。

範圍

agents.defaults.sandbox.scope 控制建立多少容器：

  • "session"（預設）：每個 session 一個容器。
  • "agent"：每個代理一個容器。
  • "shared"：所有沙箱化 session 共用一個容器。

工作區存取

agents.defaults.sandbox.workspaceAccess 控制沙箱能看到什麼：

  • "none"（預設）：工具看到的是 ~/.openclaw/sandboxes 下的沙箱工作區。
  • "ro"：以唯讀方式掛載代理工作區到 /agent（停用 write/edit/apply_patch）。
  • "rw"：以讀寫方式掛載代理工作區到 /workspace。

入站媒體會被複製到活動中的沙箱工作區（media/inbound/*）。 技能注意事項：read 工具以沙箱為根目錄。使用 workspaceAccess: "none" 時， OpenClaw 會把符合條件的技能映射到沙箱工作區（.../skills）以便讀取。使用 "rw" 時，工作區技能可從 /workspace/skills 讀取。

自訂 bind mount

agents.defaults.sandbox.docker.binds 將額外的主機目錄掛載到容器中。 格式：host:container:mode（例如 "/home/user/source:/source:rw"）。

全域和各代理的 bind 會合併（不是取代）。在 scope: "shared" 下，各代理的 bind 會被忽略。

agents.defaults.sandbox.browser.binds 將額外的主機目錄掛載到沙箱瀏覽器容器中。

  • 設定後（包括設為 []），會取代瀏覽器容器的 agents.defaults.sandbox.docker.binds。
  • 未設定時，瀏覽器容器會 fallback 使用 agents.defaults.sandbox.docker.binds（向後相容）。

範例（唯讀原始碼 + 額外的資料目錄）：

{
  agents: {
    defaults: {
      sandbox: {
        docker: {
          binds: ["/home/user/source:/source:ro", "/var/data/myapp:/data:ro"],
        },
      },
    },
    list: [
      {
        id: "build",
        sandbox: {
          docker: {
            binds: ["/mnt/cache:/cache:rw"],
          },
        },
      },
    ],
  },
}

安全注意事項：

  • Bind 會穿透沙箱檔案系統，以你設定的模式（:ro 或 :rw）暴露主機路徑。
  • OpenClaw 會封鎖危險的 bind 來源（例如：docker.sock、/etc、/proc、/sys、/dev，以及會暴露它們的上層掛載）。
  • 敏感掛載（機密、SSH 金鑰、服務憑證）應該用 :ro，除非確實需要寫入。
  • 搭配 workspaceAccess: "ro" 只需讀取工作區時使用；bind 模式獨立運作。
  • 詳見 沙箱 vs 工具策略 vs 提權 了解 bind 與工具策略、提權 exec 的互動方式。

映像檔 + 設定

預設映像檔：openclaw-sandbox:bookworm-slim

建構一次：

scripts/sandbox-setup.sh

注意：預設映像檔不包含 Node。如果技能需要 Node（或其他執行環境），請自訂映像檔，或透過 sandbox.docker.setupCommand 安裝（需要網路出口 + 可寫入的根目錄 + root 使用者）。

如果你需要一個功能更齊全的沙箱映像檔，包含常用工具（例如 curl、jq、nodejs、python3、git），可以建構：

scripts/sandbox-common-setup.sh

然後將 agents.defaults.sandbox.docker.image 設為 openclaw-sandbox-common:bookworm-slim。

沙箱瀏覽器映像檔：

scripts/sandbox-browser-setup.sh

沙箱容器預設沒有網路。 可透過 agents.defaults.sandbox.docker.network 覆寫。

內建的沙箱瀏覽器映像檔也會套用保守的 Chromium 啟動預設值， 適用於容器化的工作負載。目前的容器預設值包括：

  • --remote-debugging-address=127.0.0.1
  • --remote-debugging-port=<derived from OPENCLAW_BROWSER_CDP_PORT>
  • --user-data-dir=${HOME}/.chrome
  • --no-first-run
  • --no-default-browser-check
  • --disable-3d-apis
  • --disable-gpu
  • --disable-dev-shm-usage
  • --disable-background-networking
  • --disable-extensions
  • --disable-features=TranslateUI
  • --disable-breakpad
  • --disable-crash-reporter
  • --disable-software-rasterizer
  • --no-zygote
  • --metrics-recording-only
  • --renderer-process-limit=2
  • 啟用 noSandbox 時加上 --no-sandbox 和 --disable-setuid-sandbox。
  • 三個圖形強化旗標（--disable-3d-apis、--disable-software-rasterizer、--disable-gpu）為可選，在容器缺少 GPU 支援時適用。如果你的工作負載需要 WebGL 或其他 3D/瀏覽器功能，設定 OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0。
  • --disable-extensions 預設啟用，可透過 OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0 停用，用於需要擴充功能的流程。
  • --renderer-process-limit=2 由 OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N> 控制，0 保持 Chromium 預設值。

如果你需要不同的執行時期 profile，請使用自訂瀏覽器映像檔並提供自己的進入點。本機（非容器）Chromium profile 可使用 browser.extraArgs 附加額外的啟動旗標。

安全預設值：

  • network: "host" 被封鎖。
  • network: "container:<id>" 預設被封鎖（namespace join 繞過風險）。
  • 緊急覆寫：agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true。

Docker 安裝和容器化 gateway 詳見： Docker

對於 Docker gateway 部署，docker-setup.sh 可以引導沙箱設定。 設定 OPENCLAW_SANDBOX=1（或 true/yes/on）來啟用該路徑。可透過 OPENCLAW_DOCKER_SOCKET 覆寫 socket 位置。完整設定和環境變數參考：Docker。

setupCommand（一次性容器設定）

setupCommand 在沙箱容器建立後執行一次（不是每次執行都跑）。 它在容器內透過 sh -lc 執行。

路徑：

  • 全域：agents.defaults.sandbox.docker.setupCommand
  • 各代理：agents.list[].sandbox.docker.setupCommand

常見問題：

  • 預設 docker.network 是 "none"（無出口），套件安裝會失敗。
  • docker.network: "container:<id>" 需要 dangerouslyAllowContainerNamespaceJoin: true，僅作為緊急措施。
  • readOnlyRoot: true 阻止寫入；設定 readOnlyRoot: false 或自訂映像檔。
  • user 必須是 root 才能安裝套件（省略 user 或設定 user: "0:0"）。
  • 沙箱 exec 不會繼承主機的 process.env。使用 agents.defaults.sandbox.docker.env（或自訂映像檔）來設定技能 API key。

工具策略 + 逃脫機制

工具 allow/deny 策略在沙箱規則之前生效。如果工具在全域或各代理層級被 deny，沙箱不會讓它復活。

tools.elevated 是明確的逃脫機制，讓 exec 在主機上執行。 /exec 指令只對已授權的發送者生效，且僅在該 session 內持續；如果要硬性停用 exec，使用工具策略的 deny（詳見 沙箱 vs 工具策略 vs 提權）。

除錯：

  • 使用 openclaw sandbox explain 檢查生效的沙箱模式、工具策略和修正用的設定 key。
  • 詳見 沙箱 vs 工具策略 vs 提權 了解「為什麼被封鎖？」的思考模型。 保持嚴格的設定。

多代理覆寫

每個代理可以覆寫沙箱 + 工具設定： agents.list[].sandbox 和 agents.list[].tools（加上 agents.list[].tools.sandbox.tools 用於沙箱工具策略）。 詳見 多代理沙箱與工具 的優先順序說明。

最小啟用範例

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        scope: "session",
        workspaceAccess: "none",
      },
    },
  },
}

相關文件

arrow_back
上一頁
Security
下一頁
Sandbox Vs Tool Policy Vs Elevated
arrow_forward