Docker

Docker 是選用的。你可以用它建立隔離、用完即棄的閘道環境，或用於未在本機安裝所需項目的主機。如果你已在自己的機器上進行開發，請改用一般安裝流程。

啟用 agents.defaults.sandbox 時，預設沙箱後端會使用 Docker，但沙箱預設為停用，且閘道本身不需要在 Docker 中執行。也可使用 SSH 與 OpenShell 沙箱後端；請參閱沙箱。

要託管多位使用者嗎？請參閱多租戶託管，以瞭解每個租戶各自使用一個單元的模型。

先決條件

• Docker Desktop（或 Docker Engine）+ Docker Compose v2
• 建置映像至少需要 2 GB RAM（在 1 GB 主機上執行 pnpm install 可能會因記憶體不足而遭終止，並以結束碼 137 離開）
• 足夠儲存映像與日誌的磁碟空間
• 在 VPS／公用主機上，請檢閱網路公開存取的安全強化，尤其是 Docker 的 DOCKER-USER 防火牆鏈

容器化閘道

./scripts/docker/setup.sh

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

export OPENCLAW_IMAGE="openclaw/openclaw:latest"./scripts/docker/setup.sh

docker load -i openclaw-image.tarexport OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"./scripts/docker/setup.sh --offline

docker compose run --rm openclaw-cli dashboard --no-open

# WhatsApp（QR）docker compose run --rm openclaw-cli channels login # Telegramdocker compose run --rm openclaw-cli channels add --channel telegram --token "<token>" # Discorddocker compose run --rm openclaw-cli channels add --channel discord --token "<token>"

手動流程

BUILD_GIT_COMMIT="$(git rev-parse HEAD)"BUILD_TIMESTAMP="$(date -u +%Y-%m-%dT%H:%M:%SZ)"docker build \  --build-arg "GIT_COMMIT=${BUILD_GIT_COMMIT}" \  --build-arg "OPENCLAW_BUILD_TIMESTAMP=${BUILD_TIMESTAMP}" \  -t openclaw:local -f Dockerfile .docker compose run --rm --no-deps --entrypoint node openclaw-gateway \  dist/index.js onboard --mode local --no-install-daemondocker compose run --rm --no-deps --entrypoint node openclaw-gateway \  dist/index.js config set --batch-json '[{"path":"gateway.mode","value":"local"},{"path":"gateway.bind","value":"lan"},{"path":"gateway.controlUi.allowedOrigins","value":["http://localhost:18789","http://127.0.0.1:18789"]}]'docker compose up -d openclaw-gateway

Docker 建置內容不包含 .git。請如上所示將原始碼識別資訊以建置引數傳入，讓映像的「關於」畫面顯示目前簽出的提交與單一建置時間戳記。scripts/docker/setup.sh 會自動解析並傳入這兩個值。

升級容器映像

當你替換 OpenClaw 映像，但保留相同的掛載狀態／組態時，新閘道會在進入就緒狀態前，執行可安全啟動的升級遷移與外掛收斂作業。例行映像升級應不需要另外執行一次 openclaw doctor --fix。

如果啟動程序無法安全完成這些修復，閘道會結束，而不會回報為健康狀態。若設有重新啟動政策，Docker、Podman 或 Kubernetes 可能會顯示閘道容器持續重新啟動。請保留掛載的狀態磁碟區，然後使用相同映像執行一次 openclaw doctor --fix 作為容器命令，並使用閘道所用的相同狀態／組態掛載：

docker run --rm -v <openclaw-state>:/home/node/.openclaw <image> openclaw doctor --fixpodman run --rm -v <openclaw-state>:/home/node/.openclaw <image> openclaw doctor --fix

doctor 完成後，請使用預設命令重新啟動閘道容器。在 Kubernetes 中，請在掛載至相同 PVC 的一次性 Job 或偵錯 Pod 中執行相同命令，然後重新啟動 Deployment 或 StatefulSet。

環境變數

scripts/docker/setup.sh 接受的選用變數（閘道容器也可直接透過 docker-compose.yml 接受）：

官方映像未隨附 Homebrew。在初始設定期間，如果 Linux 容器中沒有 brew，OpenClaw 會隱藏僅支援 brew 的 Skills 相依套件安裝程式；請透過自訂映像提供這些相依套件，或手動安裝。針對 Debian 套件形式的相依套件，請使用 OPENCLAW_IMAGE_APT_PACKAGES；針對 Python 相依套件，請使用 OPENCLAW_IMAGE_PIP_PACKAGES（建置時會執行 python3 -m pip install --break-system-packages，因此請固定版本，且僅使用你信任的套件索引）。

如果 Docker 回報 ResourceExhausted、cannot allocate memory，或在執行 tsdown 期間中止，請提高 Docker 建置器的記憶體限制，或使用較小且明確指定的堆積記憶體大小重試：

OPENCLAW_DOCKER_BUILD_NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_DOCKER_BUILD_TSDOWN_MAX_OLD_SPACE_MB=4096

包含所選外掛、從原始碼建置的映像

OPENCLAW_EXTENSIONS 會從原始碼簽出中選取外掛資訊清單 ID； 當現有的原始碼目錄名稱與其不同時，也接受這些名稱。Docker 建置會將選取項目一次解析為原始碼目錄、安裝正式環境 相依套件，並在選取的外掛以 openclaw.build.bundledDist: false 單獨發布時，將其執行階段編譯至根目錄的綑綁 dist。這項僅限 Docker 的封裝不會變更外掛的 npm 或 ClawHub 成品合約。未知、無效或不明確的 ID 會導致映像檔建置失敗。 已知的僅相依套件／原始碼 ID 會維持現有的原始碼與相依套件 暫存方式，而不會新增已編譯的根目錄 dist 項目。具有 統一建置進入點的所選外掛必須成功編譯；未選取的外部外掛 原始碼與執行階段輸出則會被移除。

例如，下列命令會分別建置多架構、獨立運作的 FakeCo ClickClack、Slack 與 Microsoft Teams 閘道映像檔。ClawRouter 已是 OpenClaw 根執行階段的一部分，因此 ClickClack 映像檔只選取 clickclack。明確傳入空白的瀏覽器引數，可讓預設映像檔不包含 Chromium：

SOURCE_SHA="$(git rev-parse HEAD)"BUILD_TIMESTAMP="$(date -u +%Y-%m-%dT%H:%M:%SZ)"REGISTRY="registry.example.com/fakeco" build_gateway_image() {  gateway="$1"  selected_plugin="$2"  docker buildx build \    --platform linux/amd64,linux/arm64 \    --build-arg "GIT_COMMIT=${SOURCE_SHA}" \    --build-arg "OPENCLAW_BUILD_TIMESTAMP=${BUILD_TIMESTAMP}" \    --build-arg "OPENCLAW_EXTENSIONS=${selected_plugin}" \    --build-arg OPENCLAW_INSTALL_BROWSER= \    --provenance=mode=max \    --sbom=true \    --tag "${REGISTRY}/openclaw-${gateway}:${SOURCE_SHA}" \    --push \    .} build_gateway_image clickclack clickclackbuild_gateway_image slack slackbuild_gateway_image teams msteams

若要進行單一原生本機建置，請使用 --platform linux/arm64 --load 或 --platform linux/amd64 --load。多平台輸出及附加的 SBOM／來源證明 需要登錄檔，或其他能保留證明資料的 Buildx 輸出。推送後， 請檢查資訊清單並部署不可變的摘要，而非 可變的原始碼 SHA 標籤：

docker buildx imagetools inspect \  "${REGISTRY}/openclaw-clickclack:${SOURCE_SHA}"# 部署：registry.example.com/fakeco/openclaw-clickclack@sha256:<manifest-digest>

這些映像檔供獨立的 OCI 型閘道與一般 Docker 使用者使用。 由 Crabhelm 管理的閘道不會使用它們：該交付路徑會建置 獨立的 x86_64 裝置封存檔，其中包含 OpenClaw npm tarball，並固定 Node、封存檔與資訊清單摘要。請從相同的已落地 OpenClaw 原始碼 獨立建置該裝置。

若要針對已封裝的映像檔測試綑綁外掛原始碼，請將一個外掛原始碼目錄掛載至其封裝後的原始碼路徑，例如 OPENCLAW_EXTRA_MOUNTS=/path/to/fork/extensions/synology-chat:/app/extensions/synology-chat:ro。這會覆寫相同外掛 ID 對應的已編譯 /app/dist/extensions/synology-chat 綑綁套件。

可觀測性

OpenTelemetry 匯出會從閘道容器向外傳送至你的 OTLP 收集器；不需要發布任何 Docker 連接埠。若要在本機建置的映像檔中包含綑綁的匯出器：

export OPENCLAW_EXTENSIONS="diagnostics-otel"export OTEL_EXPORTER_OTLP_ENDPOINT="http://otel-collector:4318"export OTEL_SERVICE_NAME="openclaw-gateway"./scripts/docker/setup.sh

官方預建映像檔已綑綁 diagnostics-otel；只有在你已移除它時，才需要自行安裝 clawhub:@openclaw/diagnostics-otel。若要啟用匯出，請在設定中允許並啟用 diagnostics-otel 外掛，然後設定 diagnostics.otel.enabled=true（完整範例請參閱 OpenTelemetry 匯出）。收集器驗證標頭應透過 diagnostics.otel.headers 傳遞，而非 Docker 環境變數。

Prometheus 指標會重複使用已發布的閘道連接埠。安裝 clawhub:@openclaw/diagnostics-prometheus、啟用 diagnostics-prometheus 外掛，然後抓取：

http://<gateway-host>:18789/api/diagnostics/prometheus

此路由受閘道驗證保護；請勿公開獨立的公用 /metrics 連接埠或未經驗證的反向代理路徑。請參閱 Prometheus 指標。

健康狀態檢查

容器探查端點（不需要驗證）：

curl -fsS http://127.0.0.1:18789/healthz   # 存活狀態curl -fsS http://127.0.0.1:18789/readyz     # 就緒狀態

映像檔內建的 HEALTHCHECK 會偵測 /healthz；重複失敗會將容器標記為 unhealthy，讓協調器可以重新啟動或替換它。

經過驗證的深度健康狀態快照：

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

區域網路與回送介面

scripts/docker/setup.sh 預設使用 OPENCLAW_GATEWAY_BIND=lan，因此主機上的 http://127.0.0.1:18789 可透過 Docker 連接埠發布運作。

• lan（預設）：主機瀏覽器與主機命令列介面可以連線至已發布的閘道連接埠。
• loopback：只有容器網路命名空間內的程序可以直接連線至閘道。

主機本機供應商

在容器內，127.0.0.1 指的是容器本身，而不是主機。對於在主機上執行的供應商，請使用 host.docker.internal：

綑綁的設定流程會使用這些 URL 作為 LM Studio／Ollama 的導入預設值，而 docker-compose.yml 會在 Linux Docker Engine 上將 host.docker.internal 對應至主機閘道（Docker Desktop 在 macOS／Windows 上提供相同別名）。主機服務必須監聽 Docker 可以連線的位址：

lms server start --port 1234 --bind 0.0.0.0OLLAMA_HOST=0.0.0.0:11434 ollama serve

使用你自己的 Compose 檔案或 docker run？請自行新增相同的對應，例如 --add-host=host.docker.internal:host-gateway。

Docker 中的 Claude 命令列介面後端

官方映像檔不會預先安裝 Claude Code。請以容器內的 node 使用者進行安裝並登入，然後保存該容器的家目錄，避免映像檔升級清除二進位檔或驗證狀態。

若為全新安裝，請先啟用持久化的 /home/node 磁碟區，再執行設定：

export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"export OPENCLAW_HOME_VOLUME="openclaw_home"./scripts/docker/setup.sh

若為現有安裝，請先停止堆疊並重新載入目前的 .env 值——設定指令碼一律會根據目前的 shell 與預設值重寫 .env，不會自行讀取該檔案：

set -a. ./.envset +aexport OPENCLAW_HOME_VOLUME="${OPENCLAW_HOME_VOLUME:-openclaw_home}"./scripts/docker/setup.sh

如果 .env 包含 shell 無法載入的值，請先手動重新匯出你依賴的項目（OPENCLAW_IMAGE、連接埠、繫結模式、自訂路徑、OPENCLAW_EXTRA_MOUNTS、沙箱、略過導入）。產生的疊加檔會為 openclaw-gateway 與 openclaw-cli 掛載家目錄磁碟區；請使用該疊加檔執行其餘命令（若你使用 docker-compose.override.yml，請先加入它）：

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  --entrypoint sh openclaw-cli -lc \  'curl -fsSL https://claude.ai/install.sh | bash'

原生安裝程式會將 claude 寫入 /home/node/.local/bin/claude。請將 OpenClaw 指向該路徑：

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  openclaw-cli config set \  agents.defaults.cliBackends.claude-cli.command \  /home/node/.local/bin/claude

請從同一個持久化家目錄登入並驗證：

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  --entrypoint /home/node/.local/bin/claude openclaw-cli auth logindocker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  --entrypoint /home/node/.local/bin/claude openclaw-cli auth status --textdocker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  openclaw-cli models auth login \  --provider anthropic --method cli --set-defaultdocker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  openclaw-cli models list --provider anthropic

接著使用綑綁的 claude-cli 後端：

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  openclaw-cli agent \  --agent main \  --model claude-cli/claude-sonnet-4-6 \  --message "從 Docker Claude 命令列介面打聲招呼"

OPENCLAW_HOME_VOLUME 會保存 /home/node/.local/bin 與 /home/node/.local/share/claude 下的原生安裝，以及 /home/node/.claude 和 /home/node/.claude.json 下的 Claude Code 設定／驗證狀態。只保存 /home/node/.openclaw 並不足夠；如果你使用 OPENCLAW_EXTRA_MOUNTS 而非家目錄磁碟區，請將所有這些 Claude 路徑掛載至兩個服務。

Bonjour／mDNS

Docker 橋接網路通常無法可靠地轉送 Bonjour／mDNS 多點傳送（224.0.0.251:5353）。當未設定 OPENCLAW_DISABLE_BONJOUR 時，綑綁的 Bonjour 外掛偵測到自身在容器中執行後，會自動停用區域網路廣播，因此不會因持續重試橋接網路所丟棄的多點傳送而陷入當機循環。設定 OPENCLAW_DISABLE_BONJOUR=1 可不論偵測結果都強制停用，設定為 0 則強制啟用（僅適用於主機網路、macvlan，或其他已知 mDNS 多點傳送可正常運作的網路）。

否則，Docker 主機請使用已發布的閘道 URL、Tailscale 或廣域 DNS-SD。注意事項與疑難排解請參閱 Bonjour 探索。

儲存與持久化

Docker Compose 會將 OPENCLAW_CONFIG_DIR 繫結掛載至 /home/node/.openclaw、將 OPENCLAW_WORKSPACE_DIR 繫結掛載至 /home/node/.openclaw/workspace，並將 OPENCLAW_AUTH_PROFILE_SECRET_DIR 繫結掛載至 /home/node/.config/openclaw，因此替換容器後這些路徑仍會保留。當變數未設定時，docker-compose.yml 會回退至 ${HOME} 下的路徑；若連 HOME 本身都不存在，則回退至 /tmp，因此在最小環境中執行 docker compose up 時，絕不會產生來源為空的磁碟區規格。

該掛載的設定目錄包含：

• 用於行為設定的 openclaw.json
• 用於儲存供應商 OAuth／API 金鑰驗證資訊的 agents/<agentId>/agent/auth-profiles.json
• 用於以環境變數提供之執行階段祕密（例如 OPENCLAW_GATEWAY_TOKEN）的 .env

驗證設定檔祕密目錄會儲存用於加密 OAuth 型驗證設定檔權杖資料的本機加密金鑰。請將其與 Docker 主機狀態一同保存，但應與 OPENCLAW_CONFIG_DIR 分開。

已安裝的可下載外掛會將套件狀態儲存在已掛載的 OpenClaw 家目錄下，因此替換容器後，安裝記錄與套件根目錄仍會保留；閘道啟動時不會重新產生綑綁外掛的相依套件樹。

完整的 VM 持久化詳細資訊，請參閱 Docker VM 執行階段－各項資料的持久化位置。

磁碟用量成長熱點： media/、各代理程式的 SQLite 資料庫、舊版工作階段 JSONL 逐字記錄、共用 SQLite 狀態資料庫、已安裝的外掛套件根目錄，以及 /tmp/openclaw/ 下的輪替檔案記錄。

Shell 輔助工具（選用）

若要簡化日常命令，請安裝 ClawDock：

mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/clawdock/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.shecho 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc

如果你是從較舊的 scripts/shell-helpers/clawdock-helpers.sh 路徑安裝，請重新執行上方命令，讓本機輔助工具指向目前的位置。接著使用 clawdock-start、clawdock-stop、clawdock-dashboard 等命令（執行 clawdock-help 可查看完整清單）。

export OPENCLAW_SANDBOX=1./scripts/docker/setup.sh

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

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

printf '%s\n' \  'services:' \  '  openclaw-cli:' \  '    cap_drop: !reset []' \  > docker-compose.cli-no-dropped-caps.local.yml docker compose -f docker-compose.yml -f docker-compose.cli-no-dropped-caps.local.yml run --rm openclaw-cli plugins install <package>

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

FROM node:24-bookwormRUN curl -fsSL https://bun.sh/install | bashENV PATH="/root/.bun/bin:${PATH}"RUN corepack enableWORKDIR /appCOPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./COPY ui/package.json ./ui/package.jsonCOPY scripts ./scriptsRUN pnpm install --frozen-lockfileCOPY . .RUN pnpm buildRUN pnpm ui:installRUN pnpm ui:buildENV NODE_ENV=productionCMD ["node","dist/index.js"]

在 VPS 上執行？

請參閱 Hetzner（Docker VPS）和 Docker VM 執行階段，瞭解共用 VM 部署步驟，包括內建二進位檔、持久化和更新。

代理程式沙箱

使用 Docker 後端啟用 agents.defaults.sandbox 時，閘道會在隔離的 Docker 容器中執行代理程式工具（Shell、檔案讀寫等），而閘道本身仍留在主機上——這會在不將整個閘道容器化的情況下，為不受信任或多租戶代理程式工作階段建立一道堅固的隔離牆。

沙箱範圍可以是每個代理程式（預設）、每個工作階段或共用；每個範圍都有各自掛載於 /workspace 的工作區。你也可以設定工具允許/拒絕政策、網路隔離、資源限制和瀏覽器容器。

如需完整設定、映像檔、安全性注意事項和多代理程式設定檔，請參閱：

• 沙箱機制 -- 完整的沙箱參考資料
• OpenShell -- 以互動式 Shell 存取沙箱容器
• 多代理程式沙箱與工具 -- 每個代理程式的覆寫設定

快速啟用

{  agents: {    defaults: {      sandbox: {        mode: "non-main", // off | non-main | all        scope: "agent", // session | agent | shared      },    },  },}

建置預設沙箱映像檔（從原始碼簽出目錄）：

scripts/sandbox-setup.sh

如果透過 npm 安裝且沒有原始碼簽出目錄，請參閱沙箱機制 § 映像檔與設定，取得內嵌的 docker build 命令。

疑難排解

docker compose run --rm openclaw-cli dashboard --no-opendocker compose run --rm openclaw-cli devices listdocker compose run --rm openclaw-cli devices approve <requestId>

docker compose run --rm openclaw-cli config set --batch-json '[{"path":"gateway.mode","value":"local"},{"path":"gateway.bind","value":"lan"}]'docker compose run --rm openclaw-cli devices list --url ws://127.0.0.1:18789

相關內容

• 安裝概覽 — 所有安裝方式
• Podman — Docker 的 Podman 替代方案
• ClawDock — Docker Compose 社群設定
• 更新 — 讓 OpenClaw 保持最新狀態
• 設定 — 安裝後的閘道設定