跳转至

Docker

Docker 是可选的。将其用于隔离的、一次性的 Gateway 环境，或没有本地安装的主机。如果你已经在自己的机器上开发，请改用常规安装流程。

默认 Docker 沙箱后端仅使用 docker CLI。将后端设置为 "podman" 可直接选择原生 Podman。沙箱默认关闭，并且不要求 Gateway 本身运行在容器中。也可用 SSH 和 OpenShell 沙箱后端；参见 沙箱。

托管多个用户？参见 多租户托管 了解每租户一个 cell 的模型。

先决条件

  • Docker Desktop（或 Docker Engine）+ Docker Compose v2
  • 本地源码镜像构建至少需要 6 GB RAM；预构建镜像可避免此构建要求
  • 为镜像和日志预留足够磁盘空间
  • 在 VPS/公共主机上，请查看 网络暴露的安全加固，尤其是 Docker DOCKER-USER 防火墙链

容器化 Gateway

1. 构建镜像

从仓库根目录执行：

./scripts/docker/setup.sh

这会在本地将 Gateway 镜像构建为 openclaw:local。若要改用预构建镜像：

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

预构建镜像首先发布到 GitHub Container Registry。GHCR 是发布自动化、固定部署和来源检查的主要注册表。同一版本还会在 openclaw/openclaw 发布 Docker Hub 镜像：

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

请使用 ghcr.io/openclaw/openclaw 或 openclaw/openclaw，避免使用非官方镜像，因为它们不共享 OpenClaw 的发布节奏或保留策略。特定版本标签包括诸如 2026.9.3 的正式版本和诸如 2026.9.1-beta.1 的预发布版本。稳定版本会更新 latest 和 main；月末 Gateway 版本只会更新 extended-stable。变体包括 slim、main-slim、extended-stable-slim、latest-browser、main-browser 和 extended-stable-browser。默认镜像捆绑了 codex 和 diagnostics-otel 插件。-browser 变体还内置了 Chromium，用于 Gateway 控制的浏览器。代理沙箱浏览器使用单独的镜像。

2. 离线重跑

在离线主机上，先传输并加载镜像：

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

--offline 会验证 OPENCLAW_IMAGE 已存在于本地，禁用隐式 Compose 拉取/构建，然后运行常规流程：.env 同步、权限修复、引导配置、Gateway 配置同步、Compose 启动。

如果 OPENCLAW_SANDBOX=1，离线设置还会检查 OPENCLAW_DOCKER_SOCKET 后守护进程上配置的默认和每个代理的沙箱镜像，包括 Docker 支持的浏览器镜像上的 browser-contract 标签。如果所需镜像缺失或过期，设置会退出而不更改沙箱配置，而不是报告一个损坏的成功状态。

3. 完成引导配置

设置脚本会自动运行引导配置：

  • 提示输入提供商 API 密钥
  • 生成 Gateway Token 并将其写入 .env
  • 创建旧版 auth-profile 密钥目录
  • 通过 Docker Compose 启动 Gateway

启动前的引导配置和配置写入会直接通过 openclaw-gateway 运行（使用 --no-deps --entrypoint node），因为 openclaw-cli 共享 Gateway 的网络命名空间，并且只有在 Gateway 容器存在后才能工作。

4. 打开 Control UI

打开 http://127.0.0.1:18789/，并将写入 .env 的 Token 粘贴到设置中。如果你已将容器切换为密码认证，请改用该密码。

需要再次获取 URL？

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

如果使用自定义 OPENCLAW_GATEWAY_PORT，请在浏览器中打开之前，将打印 URL 中的端口 18789 替换为你的主机端口；保持 URL 其余部分不变。任一容器内的 Dashboard 命令都使用内部监听端口。

5. 配置频道（可选）

# WhatsApp (QR)
docker compose run --rm openclaw-cli channels login

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

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

文档：WhatsApp、Telegram、Discord

使用 Control UI 浏览器

Control UI Browser 面板 显示一个 由 Gateway 控制的浏览器。它与打开 Dashboard 的笔记本电脑或手机上的浏览器是分开的。对于使用 Docker Gateway 的本地托管浏览器，Chromium 必须在 Gateway 容器内部 可用。

对于新安装，请使用官方带浏览器的镜像和常规 Compose 设置；无需自定义 Dockerfile：

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

对于固定部署，请选择某个版本的 -browser 标签，而不是会移动的 latest-browser 标签。对于现有 Compose 安装，请将其 .env 中的 OPENCLAW_IMAGE 改为浏览器变体，然后使用与当前部署相同的 Compose 文件和覆盖层拉取并重建 Gateway：

docker compose pull openclaw-gateway openclaw-cli
docker compose up -d openclaw-gateway

保留现有卷、端口和其他设置。不要使用空 shell 环境重新运行 setup 来仅更改镜像：setup 会从 当前 shell 和默认值重写 .env。

覆盖 /home/node/.cache/ms-playwright 的现有 home 卷或绑定挂载 可能会隐藏镜像捆绑的 Chromium。如果切换镜像后浏览器发现仍然失败，请检查这些挂载。保留数据，然后在挂载的 home 中 配置 Chromium，或调整挂载以使镜像的浏览器 缓存可见；重建容器不会刷新已填充的 home 卷。

对于从本地源码构建进行的新安装，请将 Chromium 烘焙到镜像中：

OPENCLAW_IMAGE=openclaw:local OPENCLAW_INSTALL_BROWSER=1 ./scripts/docker/setup.sh

此构建时选项会安装 Chromium 和 Xvfb；在已构建的容器上设置它不会安装浏览器。

镜像提供 Chromium，而不是替代你的浏览器配置：

  • 保持浏览器控制启用（browser.enabled）。为容器中的 Chromium 使用本地托管配置文件，例如 openclaw，不要使用面向其他浏览器的扩展、仅附加或远程 CDP 配置文件。
  • OpenClaw 在 Linux 上会自动检测镜像中由 Playwright 管理的 Chromium。显式指定的 browser.executablePath 或配置文件可执行路径必须指向容器内的二进制文件；来自你笔记本电脑的路径在那里无法使用。
  • 无头容器需要无头浏览器运行。如果启动时报告缺少显示，请检查显式的 browser.headless、配置文件无头设置以及 OPENCLAW_BROWSER_HEADLESS 覆盖项。参见浏览器配置。
  • 使用 operator.admin 访问权限连接到提供 browser.request 的 Gateway。在 Chat 侧边面板中打开 + → Browser，导航到一个页面，并确认其快照能够加载且导航可用。仅加载仪表盘并不能验证 Chromium 可以启动。

这不是沙箱代理会话所使用的独立沙箱浏览器 容器。选择 Gateway 的 -browser 镜像 不会构建或配置该沙箱镜像。

无头引导

对于无人值守的容器主机，请将提供商、Gateway 和通道凭据放入 Compose 的 .env 文件中，以便一次性引导容器和长期运行的 Gateway 都接收到相同的值：

OPENAI_API_KEY=<provider-key>
OPENCLAW_GATEWAY_TOKEN=<gateway-token>
TELEGRAM_BOT_TOKEN=<bot-token>

在不使用伪 TTY 的情况下运行引导配置和通道配置，然后启动 Gateway：

docker compose run -T --rm --no-deps --entrypoint node openclaw-gateway \
  dist/index.js onboard --non-interactive --accept-risk --skip-health \
  --mode local \
  --auth-choice openai-api-key \
  --secret-input-mode ref \
  --gateway-auth token \
  --gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN \
  --skip-channels \
  --no-install-daemon
docker compose run -T --rm --no-deps --entrypoint node openclaw-gateway \
  dist/index.js channels add --channel telegram --use-env
docker compose up -d openclaw-gateway

如果缺少插件声明的环境变量，通道命令会在更改配置之前失败。引导完成后，请将 TELEGRAM_BOT_TOKEN 保留在 .env 中：--use-env 会将凭据查找交给环境，而不会将令牌复制到 openclaw.json，并且正在运行的 Gateway 也需要相同的变量。启动后通道配置发生变化时，Gateway 的配置监视器会自动热重载受影响的通道。

有关凭据标志替代方案和其他通道插件，请参见openclaw channels。

手动流程

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-daemon
docker 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 会自动解析并传递这两个值。

Note

请从仓库根目录运行 docker compose。如果你启用了 OPENCLAW_EXTRA_MOUNTS 或 OPENCLAW_HOME_VOLUME，设置脚本会写入 docker-compose.extra.yml；请在你自行维护的任何 docker-compose.override.yml 之后包含它，例如 -f docker-compose.yml -f docker-compose.override.yml -f docker-compose.extra.yml。

升级容器镜像

当你替换 OpenClaw 镜像但保留相同的已挂载状态/配置时， 镜像入口点会在启动 Gateway 之前，以独占维护所有权运行 openclaw doctor --fix --non-interactive。这涵盖默认镜像命令 和 Compose 的前台 Gateway 命令，包括其选定的配置文件。 常规镜像升级不需要单独的 Doctor 步骤。

在 Synology DSM 等较旧的 Linux 主机上，不可用的 openat2 系统调用 可能导致旧镜像报告另一个 Gateway 拥有状态卷，即使该状态卷是空的。 当前镜像使用受保护的文件系统回退；请保持启用原生文件系统检查。Doctor 会报告底层锁失败和恢复操作， 而不是将每个获取错误都视为活动 Gateway。权限错误要求为容器用户提供可写的状态挂载。如果文件系统 无法为状态所有权提供独占文件创建，请停止 OpenClaw，备份其状态，并将状态卷迁移到支持该功能的本地文件系统。 普通数据库事务在该卷上使用 SQLite 锁。不要删除状态文件或锁文件以绕过所有权。

其他 CLI 命令和帮助会原样传递。如果你替换了镜像的入口点，请在启动 Gateway 之前针对相同的已挂载状态/配置运行 Doctor；自定义入口点会绕过此激活步骤。

这包括代理数据库架构升级、共享状态审计迁移和旧版工作区设置导入。在推进数据库架构之前，Doctor 会在原始文件旁边保存经过验证的 SQLite 副本，命名为 <database>.pre-startup-migration-<id>.bak。共享数据库和受影响的代理数据库使用相同的备份 ID。配置备份和已退役的工作区文件归档遵循正常的 Doctor 修复规则。请将这些文件与升级前备份一起保留；回滚必须恢复匹配的状态以及旧镜像。参见回滚。

在 Unraid 的 shfs 等 FUSE 文件系统中，缺少原生不替换重命名不需要操作员步骤。迁移所有者会发布一个完整的、独占的硬链接，在移除旧名称之前同步它，并且可以在不替换另一个文件的情况下恢复被中断的 source/claim 对。这会保留源 inode 和精确字节。当原生不替换重命名不可用时，文件系统必须支持同目录硬链接和目录同步。

在默认或系统代理数据库被拒绝期间，就绪状态保持为 false，并且就绪响应包含准入原因。被拒绝的可选代理保持隔离，同时健康代理可以处理请求。

缺失或漂移的规范 SQLite 索引会在会话启动完成前由架构迁移所有者重建。修复警告会标识代理、数据库路径、重建的索引和耗时。当前架构形状拒绝报告会按稳定的路径顺序列出所有受影响的数据库。缺失必需表、不兼容列以及其他无法安全重建的更改仍需要 Doctor；启动过程不会将缺失的数据表重新创建为空表。

当必需状态无法安全迁移时，启动会以代码 78 退出：例如，源标识冲突、数据不可读、另一个写入者拥有该状态，或文件系统没有提供安全且持久发布 claim 的方式。保留的 source、claim 和备份是恢复输入；不要删除它们以消除错误。如果文件系统缺少所需原语，请停止 Gateway，并在重试前通过其原生底层文件系统公开相同数据（例如，使用 Unraid 池路径而不是 shfs 共享）。

在具有重启策略时，Docker、Podman 或 Kubernetes 可能显示 Gateway 容器正在重启。保留已挂载的状态卷，然后使用 Gateway 使用的相同状态/配置挂载，将 openclaw doctor --fix 作为容器命令运行一次相同镜像：

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

doctor 完成后，使用默认命令重启 Gateway 容器。在 Kubernetes 中，在挂载到相同 PVC 的一次性 Job 或调试 pod 中运行相同命令，然后重启 Deployment 或 StatefulSet。

容器再次运行后，针对相同挂载状态运行只读部署预检：

docker compose run --rm openclaw-cli doctor --json

使用所选插件的源码构建镜像

OPENCLAW_EXTENSIONS 从源码检出中选择插件清单 id；当现有源目录名称不同时，也会被接受。Docker 构建会将选择解析为源目录一次，安装生产依赖，将每个所选插件自身的运行时依赖链接到其在 /app/dist/extensions/<id> 下的打包根目录，并将所选插件运行时包含在镜像中。源码检出还会编译以 openclaw.build.bundledDist: false 单独发布的第一方插件；该标记仍保留插件的外部 npm 或 ClawHub 所有权，并且不更改任一产物契约。未知、无效或歧义的 id 会导致镜像构建失败。这包括 WhatsApp：OPENCLAW_EXTENSIONS=whatsapp 会编译并打包其运行时。普通源码构建通过独立的外部插件构建路径生成其运行时；根 npm 产物继续排除它。所选插件必须成功编译；未选择的外部插件源码和运行时输出会被清理。

例如，这些命令会为 ClickClack、Slack 和 Microsoft Teams 构建独立的、多架构的独立 FakeCo Gateway 镜像。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 clickclack
build_gateway_image slack slack
build_gateway_image teams msteams

对于单个原生本地构建，请使用 --platform linux/arm64 --load 或 --platform linux/amd64 --load。多平台输出以及附带的 SBOM/来源证明需要注册表或另一个保留证明的 Buildx 输出。推送后，检查 manifest 并部署不可变摘要，而不是可变的 source-SHA 标签：

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

这些镜像适用于独立的基于 OCI 的 Gateway 和通用 Docker 用户。由 Crabhelm 管理的 Gateway 不会使用它们：该交付路径会构建一个独立的 x86_64 设备归档，其中包含 OpenClaw npm tarball，并固定 Node、归档和 manifest 摘要。请从相同的已落地 OpenClaw 源码独立构建该设备。

要在打包镜像上测试捆绑插件源码，请将一个插件源目录挂载到其打包源路径之上，例如 OPENCLAW_EXTRA_MOUNTS=/path/to/fork/extensions/synology-chat:/app/extensions/synology-chat:ro。这会覆盖相同插件 id 对应的已编译 /app/dist/extensions/synology-chat 捆绑包。添加或更改挂载后，请重启 Gateway；运行时加载和设置将使用挂载的源码。

可观测性

OpenTelemetry 导出是从 Gateway 容器发往你的 OTLP 收集器的出站流量；无需发布 Docker 端口。要在本地构建的镜像中包含内置 exporter：

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 指标复用已发布的 Gateway 端口。安装 clawhub:@openclaw/diagnostics-prometheus，启用 diagnostics-prometheus 插件，然后抓取：

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

该路由受 Gateway 身份验证保护；不要暴露单独的公共 /metrics 端口或未经身份验证的反向代理路径。参见 Prometheus 指标。

健康检查

容器探测端点（无需身份验证）：

curl -fsS http://127.0.0.1:18789/healthz   # liveness
curl -fsS http://127.0.0.1:18789/startupz  # startup and traffic admission
curl -fsS http://127.0.0.1:18789/readyz    # deep, channel-aware readiness

镜像内置的 HEALTHCHECK 会 ping /healthz；连续失败会将容器标记为 unhealthy，以便编排器可以重启或替换它。 对于编排器的启动或就绪探测，请使用 /startupz，以免某个失败的 channel 账户将原本健康的 Gateway 和 Control UI 从服务中移除。对于有意将硬性 channel 故障视为未就绪的监控，请使用 /readyz。响应详情见 健康检查。

经过身份验证的深度健康快照：

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

详细主题

环境变量

完整的变量表、apt/pip 构建附加项以及构建内存调优。

网络与存储

LAN 与 loopback、host.docker.internal、Claude CLI、Bonjour 以及挂载状态。

Compose 操作

Compose 命令表、sandbox/CI/DNS/EACCES 折叠面板以及镜像刷新。

沙箱与故障排查

启用 agent 沙箱，以及 Docker 故障排查折叠面板。

  • 安装概览 — 所有安装方法
  • Podman — Podman 作为 Docker 的替代方案
  • Kubernetes — 在集群上运行 Gateway 的极简 Kustomize 起点
  • Ansible — 使用 Tailscale VPN 和防火墙隔离的自动化服务器部署
  • Cloudflare Containers — 实验性 Worker 加容器部署，并支持 Litestream 备份到 R2
  • 更新 — 保持 OpenClaw 最新
  • 配置 — 安装后的 Gateway 配置

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw