Docker（選用）

Docker 是選用的。只有在你需要容器化閘道或想驗證 Docker 流程時才使用。

Docker 適合我嗎？

是：你需要一個隔離的、即用即丟的閘道環境，或想在沒有本機安裝的主機上執行 OpenClaw。
否：你在自己的機器上跑，只想要最快的開發迴圈。請改用一般安裝流程。
沙箱注意：agent 沙箱也會用到 Docker，但不需要整個閘道在 Docker 裡跑。參閱 Sandboxing。

本指南涵蓋：

容器化閘道（完整的 OpenClaw Docker 部署）
單次工作階段 Agent 沙箱（主機閘道 + Docker 隔離的 agent 工具）

沙箱詳情：Sandboxing

需求

Docker Desktop（或 Docker Engine）+ Docker Compose v2
建置映像至少需要 2 GB RAM（在 1 GB 主機上 pnpm install 可能被 OOM-killed，exit 137）
足夠的磁碟空間存放映像和日誌
若在 VPS/公開主機上執行，請參閱網路暴露的安全強化，特別是 Docker DOCKER-USER 防火牆策略。

容器化閘道（Docker Compose）

快速開始（建議）

注意： 此處 Docker 預設使用綁定模式（lan/loopback），而非主機別名。在 gateway.bind 中使用綁定模式值（例如 lan 或 loopback），不要使用主機別名如 0.0.0.0 或 localhost。

從儲存庫根目錄執行：

./docker-setup.sh

此腳本會：

在本機建置閘道映像（若設定了 OPENCLAW_IMAGE 則拉取遠端映像）
執行入門精靈
印出選用的供應商設定提示
透過 Docker Compose 啟動閘道
產生閘道 token 並寫入 .env

選用環境變數：

OPENCLAW_IMAGE — 使用遠端映像而非本機建置（例如 ghcr.io/openclaw/openclaw:latest）
OPENCLAW_DOCKER_APT_PACKAGES — 在建置時安裝額外的 apt 套件
OPENCLAW_EXTENSIONS — 在建置時預先安裝擴充功能依賴（以空格分隔的擴充功能名稱，例如 diagnostics-otel matrix）
OPENCLAW_EXTRA_MOUNTS — 新增額外的主機 bind mount
OPENCLAW_HOME_VOLUME — 用具名卷持久化 /home/node
OPENCLAW_SANDBOX — 啟用 Docker 閘道沙箱引導。僅明確的真值會啟用：1、true、yes、on
OPENCLAW_INSTALL_DOCKER_CLI — 本機映像建置的 build arg 透傳（1 會在映像中安裝 Docker CLI）。docker-setup.sh 在 OPENCLAW_SANDBOX=1 用於本機建置時會自動設定。
OPENCLAW_DOCKER_SOCKET — 覆寫 Docker socket 路徑（預設：DOCKER_HOST=unix://... 路徑，否則 /var/run/docker.sock）
OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 — 緊急開關：允許信任的私有網路 ws:// 目標用於 CLI/入門客戶端路徑（預設僅限 loopback）
OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0 — 當你需要 WebGL/3D 相容性時，停用容器瀏覽器強化旗標 --disable-3d-apis、--disable-software-rasterizer、--disable-gpu。
OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0 — 當瀏覽器流程需要擴充功能時保持啟用（預設在沙箱瀏覽器中停用擴充功能）。
OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N> — 設定 Chromium 渲染器行程上限；設為 0 則跳過此旗標，使用 Chromium 預設行為。

完成後：

在瀏覽器中開啟 http://127.0.0.1:18789/。
將 token 貼入 Control UI（Settings → token）。
需要再次取得 URL？執行 docker compose run --rm openclaw-cli dashboard --no-open。

為 Docker 閘道啟用 agent 沙箱（需主動啟用）

docker-setup.sh 也能為 Docker 部署引導 agents.defaults.sandbox.*。

啟用方式：

export OPENCLAW_SANDBOX=1
./docker-setup.sh

自訂 socket 路徑（例如 rootless Docker）：

export OPENCLAW_SANDBOX=1
export OPENCLAW_DOCKER_SOCKET=/run/user/1000/docker.sock
./docker-setup.sh

注意事項：

腳本僅在沙箱前置條件通過後才掛載 docker.sock。
若沙箱設定無法完成，腳本會將 agents.defaults.sandbox.mode 重設為 off，避免重新執行時留下過期/損壞的沙箱設定。
若 Dockerfile.sandbox 不存在，腳本會印出警告並繼續；如有需要，用 scripts/sandbox-setup.sh 建置 openclaw-sandbox:bookworm-slim。
若使用非本機的 OPENCLAW_IMAGE 值，該映像必須已包含 Docker CLI 以支援沙箱執行。

自動化/CI（非互動式，無 TTY 雜訊）

在腳本和 CI 中，用 -T 停用 Compose pseudo-TTY 配置：

docker compose run -T --rm openclaw-cli gateway probe
docker compose run -T --rm openclaw-cli devices list --json

若你的自動化未匯出 Claude session 變數，現在未設定的變數會在 docker-compose.yml 中解析為空值，避免重複出現「variable is not set」警告。

共享網路安全注意事項（CLI + 閘道）

openclaw-cli 使用 network_mode: "service:openclaw-gateway"，讓 CLI 指令能在 Docker 中透過 127.0.0.1 可靠地連線到閘道。

請將此視為共享信任邊界：loopback 綁定並不等於這兩個容器之間的隔離。若需要更強的分離，請從獨立的容器/主機網路路徑執行指令，而非使用內建的 openclaw-cli 服務。

為降低 CLI 行程被入侵時的影響，compose 設定移除了 NET_RAW/NET_ADMIN 並在 openclaw-cli 上啟用 no-new-privileges。

它會在主機上寫入設定/工作區：

~/.openclaw/
~/.openclaw/workspace

在 VPS 上執行？參閱 Hetzner（Docker VPS）。

使用遠端映像（跳過本機建置）

官方預建映像發布於：

GitHub Container Registry package

使用映像名稱 ghcr.io/openclaw/openclaw（而非名稱類似的 Docker Hub 映像）。

常用標籤：

main — 從 main 分支建置的最新版
<version> — release 標籤建置（例如 2026.2.26）
latest — 最新的穩定 release 標籤

基底映像資訊

主要 Docker 映像目前使用：

node:24-bookworm

docker 映像現在發布 OCI 基底映像標註（sha256 僅為範例，指向該標籤的固定多架構 manifest 清單）：

org.opencontainers.image.base.name=docker.io/library/node:24-bookworm
org.opencontainers.image.base.digest=sha256:3a09aa6354567619221ef6c45a5051b671f953f0a1924d1f819ffb236e520e6b
org.opencontainers.image.source=https://github.com/openclaw/openclaw
org.opencontainers.image.url=https://openclaw.ai
org.opencontainers.image.documentation=https://docs.openclaw.ai/install/docker
org.opencontainers.image.licenses=MIT
org.opencontainers.image.title=OpenClaw
org.opencontainers.image.description=OpenClaw gateway and CLI runtime container image
org.opencontainers.image.revision=<git-sha>
org.opencontainers.image.version=<tag-or-main>
org.opencontainers.image.created=<rfc3339 timestamp>

參考：OCI image annotations

版本脈絡：此儲存庫的標籤歷史在 v2026.2.22 和更早的 2026 標籤（例如 v2026.2.21、v2026.2.9）中已使用 Bookworm。

預設情況下，設定腳本會從原始碼建置映像。若要改為拉取預建映像，在執行腳本前設定 OPENCLAW_IMAGE：

export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./docker-setup.sh

腳本偵測到 OPENCLAW_IMAGE 不是預設的 openclaw:local 後，會執行 docker pull 而非 docker build。其餘流程（入門設定、閘道啟動、token 產生）完全相同。

docker-setup.sh 仍需從儲存庫根目錄執行，因為它會使用本機的 docker-compose.yml 和輔助檔案。OPENCLAW_IMAGE 跳過本機映像建置時間，但不會取代 compose/設定工作流程。

Shell 輔助工具（選用）

若想更輕鬆地管理日常 Docker 操作，安裝 ClawDock：

mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/shell-helpers/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.sh

加入你的 shell 設定檔（zsh）：

echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc

接著使用 clawdock-start、clawdock-stop、clawdock-dashboard 等指令。執行 clawdock-help 查看所有指令。

詳情參閱 ClawDock Helper README。

手動流程（compose）

docker build -t openclaw:local -f Dockerfile .
docker compose run --rm openclaw-cli onboard
docker compose up -d openclaw-gateway

注意：從儲存庫根目錄執行 docker compose ...。若你啟用了 OPENCLAW_EXTRA_MOUNTS 或 OPENCLAW_HOME_VOLUME，設定腳本會寫入 docker-compose.extra.yml；在其他地方執行 Compose 時需要包含它：

docker compose -f docker-compose.yml -f docker-compose.extra.yml <command>

Control UI token + 配對（Docker）

若看到「unauthorized」或「disconnected (1008): pairing required」，取得全新的 dashboard 連結並核准瀏覽器裝置：

docker compose run --rm openclaw-cli dashboard --no-open
docker compose run --rm openclaw-cli devices list
docker compose run --rm openclaw-cli devices approve <requestId>

更多資訊：Dashboard、Devices。

額外掛載（選用）

若想將額外的主機目錄掛載到容器中，在執行 docker-setup.sh 前設定 OPENCLAW_EXTRA_MOUNTS。此參數接受以逗號分隔的 Docker bind mount 清單，並透過產生 docker-compose.extra.yml 同時套用到 openclaw-gateway 和 openclaw-cli。

範例：

export OPENCLAW_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro,$HOME/github:/home/node/github:rw"
./docker-setup.sh

注意事項：

路徑必須在 macOS/Windows 上與 Docker Desktop 共用。
每個項目必須是 source:target[:options] 格式，不含空格、tab 或換行。
若修改了 OPENCLAW_EXTRA_MOUNTS，需重新執行 docker-setup.sh 以重新產生 extra compose 檔案。
docker-compose.extra.yml 是自動產生的，請勿手動編輯。

持久化整個容器 home（選用）

若想讓 /home/node 在容器重建後仍然保留，透過 OPENCLAW_HOME_VOLUME 設定具名卷。這會建立 Docker 卷並掛載到 /home/node，同時保留標準的設定/工作區 bind mount。此處使用具名卷（非 bind 路徑）；若要使用 bind mount，請用 OPENCLAW_EXTRA_MOUNTS。

範例：

export OPENCLAW_HOME_VOLUME="openclaw_home"
./docker-setup.sh

可以與額外掛載組合使用：

export OPENCLAW_HOME_VOLUME="openclaw_home"
export OPENCLAW_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro,$HOME/github:/home/node/github:rw"
./docker-setup.sh

注意事項：

具名卷必須符合 ^[A-Za-z0-9][A-Za-z0-9_.-]*$。
若修改了 OPENCLAW_HOME_VOLUME，需重新執行 docker-setup.sh 以重新產生 extra compose 檔案。
具名卷在用 docker volume rm <name> 移除前會一直保留。

安裝額外 apt 套件（選用）

若需要映像中的系統套件（例如建置工具或媒體函式庫），在執行 docker-setup.sh 前設定 OPENCLAW_DOCKER_APT_PACKAGES。這會在映像建置時安裝套件，即使容器被刪除也會保留。

範例：

export OPENCLAW_DOCKER_APT_PACKAGES="ffmpeg build-essential"
./docker-setup.sh

注意事項：

接受以空格分隔的 apt 套件名稱清單。
若修改了 OPENCLAW_DOCKER_APT_PACKAGES，需重新執行 docker-setup.sh 以重建映像。

預先安裝擴充功能依賴（選用）

擁有自己 package.json 的擴充功能（例如 diagnostics-otel、matrix、 msteams）會在首次載入時安裝 npm 依賴。若要將這些依賴寫入映像，在執行 docker-setup.sh 前設定 OPENCLAW_EXTENSIONS：

export OPENCLAW_EXTENSIONS="diagnostics-otel matrix"
./docker-setup.sh

或直接建置時指定：

docker build --build-arg OPENCLAW_EXTENSIONS="diagnostics-otel matrix" .

注意事項：

接受以空格分隔的擴充功能目錄名稱（位於 extensions/ 下）。
僅影響有 package.json 的擴充功能；無 package.json 的輕量外掛不受影響。
若修改了 OPENCLAW_EXTENSIONS，需重新執行 docker-setup.sh 以重建映像。

進階使用者/功能完整容器（需主動啟用）

預設 Docker 映像以安全優先為原則，以非 root 的 node 使用者執行。這讓攻擊面最小化，但也意味著：

執行時無法安裝系統套件
預設沒有 Homebrew
沒有內建 Chromium/Playwright 瀏覽器

若想要功能更完整的容器，使用這些選用開關：

持久化 /home/node，讓瀏覽器下載和工具快取得以保留：

export OPENCLAW_HOME_VOLUME="openclaw_home"
./docker-setup.sh

將系統依賴寫入映像（可重複且持久）：

export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq"
./docker-setup.sh

不使用 npx 安裝 Playwright 瀏覽器（避免 npm override 衝突）：

docker compose run --rm openclaw-cli \
  node /app/node_modules/playwright-core/cli.js install chromium

若需要 Playwright 安裝系統依賴，請用 OPENCLAW_DOCKER_APT_PACKAGES 重建映像，而非在 runtime 使用 --with-deps。

持久化 Playwright 瀏覽器下載：

在 docker-compose.yml 中設定 PLAYWRIGHT_BROWSERS_PATH=/home/node/.cache/ms-playwright。
確保 /home/node 透過 OPENCLAW_HOME_VOLUME 持久化，或透過 OPENCLAW_EXTRA_MOUNTS 掛載 /home/node/.cache/ms-playwright。

權限 + EACCES

映像以 node（uid 1000）執行。若在 /home/node/.openclaw 看到權限錯誤，請確認主機 bind mount 的擁有者是 uid 1000。

範例（Linux 主機）：

sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace

若為了方便而選擇以 root 執行，你需自行承擔安全風險。

加速重建（建議）

為加速重建，調整 Dockerfile 順序讓依賴層能被快取。這樣除非 lockfile 變更，否則不會重新執行 pnpm install：

FROM node:24-bookworm

# Install Bun (required for build scripts)
RUN curl -fsSL https://bun.sh/install | bash
ENV PATH="/root/.bun/bin:${PATH}"

RUN corepack enable

WORKDIR /app

# Cache dependencies unless package metadata changes
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
COPY ui/package.json ./ui/package.json
COPY scripts ./scripts

RUN pnpm install --frozen-lockfile

COPY . .
RUN pnpm build
RUN pnpm ui:install
RUN pnpm ui:build

ENV NODE_ENV=production

CMD ["node","dist/index.js"]

頻道設定（選用）

使用 CLI 容器設定頻道，如有需要再重啟閘道。

WhatsApp（QR）：

docker compose run --rm openclaw-cli channels login

Telegram（bot token）：

docker compose run --rm openclaw-cli channels add --channel telegram --token "<token>"

Discord（bot token）：

docker compose run --rm openclaw-cli channels add --channel discord --token "<token>"

文件：WhatsApp、Telegram、Discord

OpenAI Codex OAuth（headless Docker）

若在精靈中選擇 OpenAI Codex OAuth，它會開啟瀏覽器 URL 並嘗試在 http://127.0.0.1:1455/auth/callback 捕捉回呼。在 Docker 或 headless 環境中，該回呼可能顯示瀏覽器錯誤。複製你到達的完整重新導向 URL，然後貼回精靈以完成認證。

健康檢查

容器探測端點（不需認證）：

curl -fsS http://127.0.0.1:18789/healthz
curl -fsS http://127.0.0.1:18789/readyz

別名：/health 和 /ready。

/healthz 是淺層存活探測，表示「閘道行程已啟動」。 /readyz 在啟動寬限期內保持就緒，之後僅在必要的受管頻道在寬限期後仍未連線或後來斷線時回傳 503。

Docker 映像包含內建的 HEALTHCHECK，會在背景 ping /healthz。簡單來說：Docker 持續檢查 OpenClaw 是否仍有回應。若檢查持續失敗，Docker 會將容器標記為 unhealthy，編排系統（Docker Compose restart policy、Swarm、Kubernetes 等）可以自動重啟或替換它。

需認證的深層健康快照（閘道 + 頻道）：

docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLAW_GATEWAY_TOKEN"

E2E 煙霧測試（Docker）

scripts/e2e/onboard-docker.sh

QR 匯入煙霧測試（Docker）

pnpm test:docker:qr

LAN 與 loopback（Docker Compose）

docker-setup.sh 預設 OPENCLAW_GATEWAY_BIND=lan，讓主機透過 Docker 連接埠發布存取 http://127.0.0.1:18789。

lan（預設）：主機瀏覽器 + 主機 CLI 可連線到發布的閘道連接埠。
loopback：僅容器網路命名空間內的行程能直接連線閘道；主機發布的連接埠存取可能失敗。

設定腳本也會在入門設定後固定 gateway.mode=local，讓 Docker CLI 指令預設使用本機 loopback 目標。

舊版設定注意：在 gateway.bind 中使用綁定模式值（lan / loopback / custom / tailnet / auto），而非主機別名（0.0.0.0、127.0.0.1、 localhost、::、::1）。

若看到 Gateway target: ws://172.x.x.x:18789 或 Docker CLI 指令重複出現 pairing required 錯誤，執行：

docker compose run --rm openclaw-cli config set gateway.mode local
docker compose run --rm openclaw-cli config set gateway.bind lan
docker compose run --rm openclaw-cli devices list --url ws://127.0.0.1:18789

注意事項

閘道綁定在容器中預設為 lan（OPENCLAW_GATEWAY_BIND）。
Dockerfile CMD 使用 --allow-unconfigured；掛載的設定檔若 gateway.mode 非 local 仍會啟動。覆寫 CMD 以強制守護。
閘道容器是工作階段的唯一真實來源（~/.openclaw/agents/<agentId>/sessions/）。

儲存模型

持久性主機資料： Docker Compose 將 OPENCLAW_CONFIG_DIR bind-mount 到 /home/node/.openclaw，將 OPENCLAW_WORKSPACE_DIR bind-mount 到 /home/node/.openclaw/workspace，因此這些路徑在容器替換後仍然保留。
暫時性沙箱 tmpfs： 當 agents.defaults.sandbox 啟用時，沙箱容器對 /tmp、/var/tmp 和 /run 使用 tmpfs。這些掛載獨立於頂層 Compose stack，會隨沙箱容器消失。
磁碟增長熱點： 注意 media/、agents/<agentId>/sessions/sessions.json、transcript JSONL 檔案、cron/runs/*.jsonl，以及 /tmp/openclaw/（或你設定的 logging.file）下的滾動式檔案日誌。若你也在 Docker 外執行 macOS app，其服務日誌是獨立的：~/.openclaw/logs/gateway.log、~/.openclaw/logs/gateway.err.log 和 /tmp/openclaw/openclaw-gateway.log。

Agent 沙箱（主機閘道 + Docker 工具）

深入了解：Sandboxing

功能說明

當 agents.defaults.sandbox 啟用時，非主要工作階段會在 Docker 容器內執行工具。閘道仍在你的主機上，但工具執行是隔離的：

scope：預設為 "agent"（每個 agent 一個容器 + 工作區）
scope："session" 為每次工作階段隔離
每個 scope 的工作區資料夾掛載在 /workspace
選用的 agent 工作區存取（agents.defaults.sandbox.workspaceAccess）
allow/deny 工具策略（deny 優先）
入站媒體會被複製到啟用中的沙箱工作區（media/inbound/*），讓工具可以讀取（使用 workspaceAccess: "rw" 時會放在 agent 工作區）

警告： scope: "shared" 會停用跨工作階段隔離。所有工作階段共用一個容器和一個工作區。

多 Agent 沙箱設定檔

若你使用多 agent 路由，每個 agent 可以覆寫沙箱 + 工具設定： agents.list[].sandbox 和 agents.list[].tools（加上 agents.list[].tools.sandbox.tools）。這讓你在同一個閘道中混合不同存取等級：

完全存取（個人 agent）
唯讀工具 + 唯讀工作區（家庭/工作 agent）
無檔案系統/shell 工具（公開 agent）

參閱 Multi-Agent Sandbox & Tools 取得範例、優先順序和疑難排解。

預設行為

映像：openclaw-sandbox:bookworm-slim
每個 agent 一個容器
Agent 工作區存取：workspaceAccess: "none"（預設）使用 ~/.openclaw/sandboxes
- "ro" 沙箱工作區保持在 /workspace，agent 工作區以唯讀掛載在 /agent（停用 write/edit/apply_patch）
- "rw" 以讀寫方式將 agent 工作區掛載在 /workspace
自動清理：閒置 > 24 小時或存在 > 7 天
網路：預設為 none（需要外連時需明確啟用）
- host 被封鎖。
- container:<id> 預設被封鎖（namespace-join 風險）。
預設允許：exec、process、read、write、edit、sessions_list、sessions_history、sessions_send、sessions_spawn、session_status
預設拒絕：browser、canvas、nodes、cron、discord、gateway

啟用沙箱

若你打算在 setupCommand 中安裝套件，注意：

預設 docker.network 為 "none"（無外連）。
docker.network: "host" 被封鎖。
docker.network: "container:<id>" 預設被封鎖。
緊急覆寫：agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true。
readOnlyRoot: true 會阻止套件安裝。
apt-get 需要 root 的 user（省略 user 或設定 user: "0:0"）。 OpenClaw 在 setupCommand（或 docker 設定）變更時會自動重建容器，除非容器最近使用過（約 5 分鐘內）。熱容器會記錄警告並附上精確的 openclaw sandbox recreate ... 指令。

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        scope: "agent", // session | agent | shared (agent is default)
        workspaceAccess: "none", // none | ro | rw
        workspaceRoot: "~/.openclaw/sandboxes",
        docker: {
          image: "openclaw-sandbox:bookworm-slim",
          workdir: "/workspace",
          readOnlyRoot: true,
          tmpfs: ["/tmp", "/var/tmp", "/run"],
          network: "none",
          user: "1000:1000",
          capDrop: ["ALL"],
          env: { LANG: "C.UTF-8" },
          setupCommand: "apt-get update && apt-get install -y git curl jq",
          pidsLimit: 256,
          memory: "1g",
          memorySwap: "2g",
          cpus: 1,
          ulimits: {
            nofile: { soft: 1024, hard: 2048 },
            nproc: 256,
          },
          seccompProfile: "/path/to/seccomp.json",
          apparmorProfile: "openclaw-sandbox",
          dns: ["1.1.1.1", "8.8.8.8"],
          extraHosts: ["internal.service:10.0.0.5"],
        },
        prune: {
          idleHours: 24, // 0 disables idle pruning
          maxAgeDays: 7, // 0 disables max-age pruning
        },
      },
    },
  },
  tools: {
    sandbox: {
      tools: {
        allow: [
          "exec",
          "process",
          "read",
          "write",
          "edit",
          "sessions_list",
          "sessions_history",
          "sessions_send",
          "sessions_spawn",
          "session_status",
        ],
        deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"],
      },
    },
  },
}

強化設定位於 agents.defaults.sandbox.docker 下： network、user、pidsLimit、memory、memorySwap、cpus、ulimits、 seccompProfile、apparmorProfile、dns、extraHosts、 dangerouslyAllowContainerNamespaceJoin（僅限緊急使用）。

多 agent：透過 agents.list[].sandbox.{docker,browser,prune}.* 覆寫 agents.defaults.sandbox.{docker,browser,prune}.* （當 agents.defaults.sandbox.scope / agents.list[].sandbox.scope 為 "shared" 時忽略）。

建置預設沙箱映像

scripts/sandbox-setup.sh

使用 Dockerfile.sandbox 建置 openclaw-sandbox:bookworm-slim。

沙箱通用映像（選用）

若想要包含常見建置工具（Node、Go、Rust 等）的沙箱映像，建置通用映像：

scripts/sandbox-common-setup.sh

建置 openclaw-sandbox-common:bookworm-slim。使用方式：

{
  agents: {
    defaults: {
      sandbox: { docker: { image: "openclaw-sandbox-common:bookworm-slim" } },
    },
  },
}

沙箱瀏覽器映像

若要在沙箱中執行瀏覽器工具，建置瀏覽器映像：

scripts/sandbox-browser-setup.sh

使用 Dockerfile.sandbox-browser 建置 openclaw-sandbox-browser:bookworm-slim。容器執行 Chromium 並啟用 CDP，以及選用的 noVNC 觀察者（透過 Xvfb 執行 headful 模式）。

注意事項：

Headful（Xvfb）相比 headless 能減少被偵測為機器人的機率。
仍可透過設定 agents.defaults.sandbox.browser.headless=true 使用 headless。
不需要完整桌面環境（GNOME）；Xvfb 提供顯示。
瀏覽器容器預設使用專用 Docker 網路（openclaw-sandbox-browser）而非全域 bridge。
選用的 agents.defaults.sandbox.browser.cdpSourceRange 以 CIDR 限制容器邊緣 CDP 入站流量（例如 172.21.0.1/32）。
noVNC 觀察者存取預設有密碼保護；OpenClaw 提供短期觀察者 token URL，配合本機引導頁面並將密碼放在 URL fragment（而非 URL query）。
瀏覽器容器啟動預設對共享/容器工作負載保守，包括：
- --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-software-rasterizer
- --disable-gpu
- --disable-dev-shm-usage
- --disable-background-networking
- --disable-features=TranslateUI
- --disable-breakpad
- --disable-crash-reporter
- --metrics-recording-only
- --renderer-process-limit=2
- --no-zygote
- --disable-extensions
- 若設定了 agents.defaults.sandbox.browser.noSandbox，還會附加 --no-sandbox 和 --disable-setuid-sandbox。
- 以上三個圖形強化旗標是選用的。若你的工作負載需要 WebGL/3D，設定 OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0 以跳過 --disable-3d-apis、--disable-software-rasterizer 和 --disable-gpu。
- 擴充功能行為由 --disable-extensions 控制，可透過 OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0 停用（啟用擴充功能），適用於依賴擴充功能的頁面或密集使用擴充功能的工作流程。
- --renderer-process-limit=2 也可透過 OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT 設定；設為 0 讓 Chromium 使用預設行程限制，適用於需要調整瀏覽器並行性的場景。

預設旗標在內建映像中自動套用。若需要不同的 Chromium 旗標，使用自訂瀏覽器映像並提供你自己的 entrypoint。

使用設定：

{
  agents: {
    defaults: {
      sandbox: {
        browser: { enabled: true },
      },
    },
  },
}

自訂瀏覽器映像：

{
  agents: {
    defaults: {
      sandbox: { browser: { image: "my-openclaw-browser" } },
    },
  },
}

啟用後，agent 會收到：

沙箱瀏覽器控制 URL（用於 browser 工具）
noVNC URL（若啟用且 headless=false）

請記住：若你對工具使用允許清單，需新增 browser（並從 deny 中移除），否則該工具仍被封鎖。清理規則（agents.defaults.sandbox.prune）也適用於瀏覽器容器。

自訂沙箱映像

建置你自己的映像並在設定中指向它：

docker build -t my-openclaw-sbx -f Dockerfile.sandbox .

{
  agents: {
    defaults: {
      sandbox: { docker: { image: "my-openclaw-sbx" } },
    },
  },
}

工具策略（allow/deny）

deny 優先於 allow。
若 allow 為空：所有工具（除了 deny 中的）都可用。
若 allow 非空：僅 allow 中的工具可用（減去 deny）。

清理策略

兩個設定：

prune.idleHours：移除閒置超過 X 小時的容器（0 = 停用）
prune.maxAgeDays：移除存在超過 X 天的容器（0 = 停用）

範例：

保留忙碌工作階段但限制存活時間： idleHours: 24、maxAgeDays: 7
永不清理： idleHours: 0、maxAgeDays: 0

安全注意事項

硬隔離僅適用於工具（exec/read/write/edit/apply_patch）。
僅限主機的工具如 browser/camera/canvas 預設被封鎖。
在沙箱中允許 browser 會破壞隔離（瀏覽器在主機上執行）。

疑難排解

映像不存在：用 scripts/sandbox-setup.sh 建置或設定 agents.defaults.sandbox.docker.image。
容器未執行：它會在每次工作階段按需自動建立。
沙箱中的權限錯誤：將 docker.user 設為符合你掛載工作區擁有權的 UID:GID（或 chown 工作區資料夾）。
找不到自訂工具：OpenClaw 使用 sh -lc（login shell）執行指令，這會 source /etc/profile 且可能重設 PATH。設定 docker.env.PATH 以前綴你的自訂工具路徑（例如 /custom/bin:/usr/local/share/npm-global/bin），或在 Dockerfile 中加入 /etc/profile.d/ 下的腳本。