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 Code）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。初始設定期間，在不含 brew 的 Linux 容器中，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 項目。具有 統一建置項目的選取外掛必須成功編譯；未選取的外部外掛 原始碼與執行階段輸出會遭到裁剪。

例如，以下命令會為 ClickClack、Slack 和 Microsoft Teams 建置各自獨立、 多架構的 FakeCo 閘道映像檔。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 連接埠或未經驗證的反向 Proxy 路徑。請參閱 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 映像檔已將 /home/node/.local/bin 納入 PATH，因此隨附的 Anthropic 外掛無須覆寫轉接器設定即可解析它。

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

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：行為設定
• agents/<agentId>/agent/auth-profiles.json：已儲存的提供者 OAuth／API 金鑰驗證資訊
• .env：由環境變數提供的執行階段密鑰，例如 OPENCLAW_GATEWAY_TOKEN

驗證設定檔密鑰目錄會儲存 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", // 關閉 | 非主要 | 全部        scope: "agent", // 工作階段 | 代理程式 | 共用      },    },  },}

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

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 保持最新狀態
• 設定 — 安裝後的閘道設定