Docker（選用）

使用 Docker 部署 OpenClaw 的完整指南，涵蓋容器化 Gateway 和代理沙箱隔離功能。

Docker 是選用的。僅在您需要容器化 Gateway 或驗證 Docker 流程時使用。

Docker 適合我嗎？

• 是：您需要隔離的、可拋棄的 Gateway 環境，或在沒有本地安裝的主機上執行 OpenClaw。
• 否：您在自己的機器上執行，只需要最快的開發迴圈。請改用一般安裝流程。
• 沙箱注意事項：代理沙箱也使用 Docker，但不需要整個 Gateway 在 Docker 中執行。請參閱沙箱機制。

本指南涵蓋：

• 容器化 Gateway（完整 OpenClaw 在 Docker 中）
• 逐次會話代理沙箱（主機 Gateway + Docker 隔離代理工具）

需求

• Docker Desktop（或 Docker Engine）+ Docker Compose v2
• 至少 2 GB RAM 用於映像檔建置（pnpm install 在 1 GB 主機上可能因 OOM 被終止，退出碼 137）
• 足夠的磁碟空間存放映像檔和日誌

容器化 Gateway（Docker Compose）

快速開始（建議方式）

從儲存庫根目錄執行：

./docker-setup.sh

此腳本會：

• 建置 Gateway 映像檔
• 執行初始設定精靈
• 列印選用的供應商設定提示
• 透過 Docker Compose 啟動 Gateway
• 產生 Gateway token 並寫入 .env

選用的環境變數：

• OPENCLAW_DOCKER_APT_PACKAGES — 在建置期間安裝額外的 apt 套件
• OPENCLAW_EXTRA_MOUNTS — 新增額外的主機綁定掛載
• OPENCLAW_HOME_VOLUME — 以命名磁碟區持久化 /home/node

完成後：

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

設定/工作區寫入主機：

• ~/.openclaw/
• ~/.openclaw/workspace

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

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 輔助工具 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>

控制介面 token + 配對（Docker）

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

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>

更多詳情：儀表板、裝置管理。

額外掛載（選用）

若要將額外的主機目錄掛載至容器，請在執行 docker-setup.sh 之前設定 OPENCLAW_EXTRA_MOUNTS。此變數接受以逗號分隔的 Docker 綁定掛載清單，會套用至 openclaw-gateway 和 openclaw-cli，並產生 docker-compose.extra.yml。

範例：

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 以重新產生額外的 compose 檔案。
• docker-compose.extra.yml 是自動產生的，請勿手動編輯。

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

若要讓 /home/node 在容器重建後仍然保留，請透過 OPENCLAW_HOME_VOLUME 設定命名磁碟區。這會建立一個 Docker 磁碟區並掛載至 /home/node，同時保留標準的設定/工作區綁定掛載。請在此使用命名磁碟區（非綁定路徑）；如需綁定掛載，請使用 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 以重新產生額外的 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 以重新建置映像檔。

進階使用者 / 完整功能容器（選擇啟用）

預設 Docker 映像檔以安全優先設計，以非 root 的 node 使用者執行。這保持了較小的攻擊面，但意味著：

• 執行時無法安裝系統套件
• 預設不含 Homebrew
• 不含 Chromium/Playwright 瀏覽器

若您需要更完整的容器功能，使用以下選擇啟用選項：

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

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

2. 將系統相依套件內建至映像檔（可重複且持久）：

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

3. 不使用 npx 安裝 Playwright 瀏覽器（避免 npm 覆寫衝突）：

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

若您需要 Playwright 安裝系統相依套件，請使用 OPENCLAW_DOCKER_APT_PACKAGES 重新建置映像檔，而非在執行時使用 --with-deps。

4. 持久化 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 上看到權限錯誤，請確保主機綁定掛載由 uid 1000 擁有。

範例（Linux 主機）：

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

若您選擇以 root 執行以求方便，請接受安全上的取捨。

加速重建（建議方式）

為加速重建，安排 Dockerfile 使相依層被快取。這避免了在鎖定檔未變更時重新執行 pnpm install：

FROM node:22-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 容器設定頻道，必要時重新啟動 Gateway。

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（無頭 Docker）

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

健康檢查

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

端對端煙霧測試（Docker）

scripts/e2e/onboard-docker.sh

QR 匯入煙霧測試（Docker）

pnpm test:docker:qr

注意事項

• Gateway 綁定預設為 lan 以供容器使用。
• Dockerfile CMD 使用 --allow-unconfigured；掛載的設定中若 gateway.mode 不是 local 仍會啟動。覆寫 CMD 以強制執行防護。
• Gateway 容器是會話的唯一來源（~/.openclaw/agents/<agentId>/sessions/）。

代理沙箱（主機 Gateway + Docker 工具）

詳細資訊：沙箱機制

功能說明

當啟用 agents.defaults.sandbox 時，非主要會話的工具會在 Docker 容器中執行。Gateway 保留在主機上，但工具執行是隔離的：

• 範圍：預設為 "agent"（每個代理一個容器 + 工作區）
• 範圍："session" 用於逐次會話隔離
• 每個範圍的工作區資料夾掛載於 /workspace
• 選用的代理工作區存取（agents.defaults.sandbox.workspaceAccess）
• 允許/拒絕工具策略（拒絕優先）
• 入站媒體複製至活動沙箱工作區（media/inbound/*），工具可讀取（使用 workspaceAccess: "rw" 時，落入代理工作區）

注意：scope: "shared" 會停用跨會話隔離。所有會話共享一個容器和一個工作區。

每代理沙箱設定檔（多代理）

若您使用多代理路由，每個代理可覆寫沙箱 + 工具設定：agents.list[].sandbox 和 agents.list[].tools（以及 agents.list[].tools.sandbox.tools）。這讓您在單一 Gateway 中執行混合存取層級：

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

詳見多代理沙箱與工具。

預設行為

• 映像檔：openclaw-sandbox:bookworm-slim
• 每個代理一個容器
• 代理工作區存取：workspaceAccess: "none"（預設）使用 ~/.openclaw/sandboxes
  • "ro" 保留沙箱工作區於 /workspace 並以唯讀方式掛載代理工作區於 /agent（停用 write/edit/apply_patch）
  • "rw" 以讀寫方式掛載代理工作區於 /workspace
• 自動清理：閒置 > 24 小時 或 存在時間 > 7 天
• 網路：預設為 none（需要出站流量時需明確選擇啟用）
  • host 被封鎖。
  • container:<id> 預設被封鎖（命名空間加入風險）。
• 預設允許：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 會封鎖套件安裝。
• user 必須是 root 才能執行 apt-get（省略 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（僅限緊急使用）。

多代理：透過 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 實現有頭模式）。

注意事項：

• 有頭模式（Xvfb）比無頭模式減少機器人偵測封鎖。
• 設定 agents.defaults.sandbox.browser.headless=true 仍可使用無頭模式。
• 不需要完整桌面環境（GNOME）；Xvfb 提供顯示。
• 瀏覽器容器預設使用專用 Docker 網路（openclaw-sandbox-browser）而非全域 bridge。
• 選用的 agents.defaults.sandbox.browser.cdpSourceRange 透過 CIDR 限制容器邊界的 CDP 入站流量（例如 172.21.0.1/32）。
• noVNC 觀察者存取預設受密碼保護；OpenClaw 提供短期觀察者 token URL，而非在 URL 中分享原始密碼。

使用設定：

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

自訂瀏覽器映像檔：

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

啟用後，代理會收到：

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

記住：若您使用工具允許清單，請加入 browser（並從拒絕清單移除），否則該工具仍會被封鎖。清理規則（agents.defaults.sandbox.prune）也適用於瀏覽器容器。

自訂沙箱映像檔

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

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

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

工具策略（允許/拒絕）

• 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（登入 shell）執行指令，它會讀取 /etc/profile 且可能重設 PATH。設定 docker.env.PATH 以前置您的自訂工具路徑（例如 /custom/bin:/usr/local/share/npm-global/bin），或在 Dockerfile 中的 /etc/profile.d/ 下新增腳本。