跳转至

Docker

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

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

托管互不信任的用户?请为每个信任边界运行独立的 Gateway,理想情况下使用不同的 OS 用户或主机。参见 安全信任模型。

先决条件

  • 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 浏览器面板 显示一个 由 Gateway 控制的浏览器。它与在笔记本电脑或手机上打开仪表盘的浏览器是分开的。对于使用 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 环境重新运行设置来仅更改镜像:设置会根据当前 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 修复规则。请将这些文件与升级前备份一起保留;回滚必须恢复匹配的状态以及旧镜像。参见 回滚。

Retries with the same candidate build, database files, and target schemas verify and reuse the first completed backup group for the full database inventory, including after a partially completed migration. A temporary .bak.capturing file records an unfinished capture and is durably removed before migration starts. An interrupted capture is recaptured; a missing or damaged member of a completed group stops migration and preserves the surviving snapshots for recovery. Repeated failed attempts therefore do not create another full backup group each time. Older backup groups remain available for operator-managed rollback. Doctor records these originals for openclaw update cleanup --dry-run. They stay protected until Doctor verifies that the migration completed and a later update finishes successfully. Cleanup can then retire the recorded group after your confirmation. Older unrecorded .bak files are listed as protected. Keep these files with your pre-upgrade backups while you still need the matching rollback.

On FUSE filesystems such as Unraid's shfs, a missing native no-replace rename does not require an operator step in native auto mode when same-directory hardlinks are supported. fs-safe preserves the source inode and bytes through exclusive hardlink publication and unlink. Native require mode still refuses the unsupported primitive. Doctor recovers interrupted source/claim pairs without replacing another file. Its separate missing-addon/native-off compatibility path syncs the source and directory before removing the old name; native moves do not promise per-move crash durability. Archive hardening and durable recovery checkpoints remain owned by Doctor. SQLite backup verification rechecks snapshot bytes when FUSE modification or change timestamps drift, while still rejecting changed contents or file identities.

Readiness remains false while the default or system agent database is refused, and the readiness response includes the admission reason. A refused optional agent remains isolated while healthy agents can serve requests.

Missing or drifted canonical SQLite indexes are rebuilt by the schema migration owner before session startup completes. Repair warnings identify the agent, database path, rebuilt indexes, and elapsed time. Current-schema shape refusal reports list all affected databases in stable path order. Missing required tables, incompatible columns, and other changes that cannot be reconstructed safely still require Doctor; startup does not recreate a missing data table as an empty one.

On Linux hosts without file creation timestamps, normal SQLite writes and permission repairs can change the reported file birth time. These changes do not invalidate the open database; actual file replacement still stops admission.

Startup exits with code 78 when required state cannot be migrated safely: for example, source identities conflict, data is unreadable, another writer owns the state, or the filesystem provides no safe, durable way to publish a claim. The retained source, claim, and backups are recovery inputs; do not delete them to silence the error. If the filesystem lacks the required primitives, stop the Gateway and expose the same data through its native backing filesystem before retrying (for example, an Unraid pool path instead of the shfs share).

With a restart policy, Docker, Podman, or Kubernetes may show the Gateway container restarting. Keep the mounted state volume, then run the same image once with openclaw doctor --fix as the container command, using the same state/config mounts the Gateway uses:

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

After doctor finishes, restart the Gateway container with its default command. In Kubernetes, run the same command in a one-off Job or debug pod mounted to the same PVC, then restart the Deployment or StatefulSet.

After the container is running again, run the read-only deployment preflight against the same mounted state:

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 产物继续将其排除。所选插件必须成功编译;未选择的外部插件源码和运行时输出会被修剪。

安装层会暂存每个工作区的 package.json,以便 frozen-lockfile 验证可以检查完整工作区。构建阶段安装编译插件资产所需的工作区依赖;生产阶段仅安装核心、共享包以及必需或所选插件。暂存插件清单不会在运行时镜像中选择该插件。

例如,这些命令会为 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 端口。要在本地构建的镜像中包含捆绑的导出器:

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,这样某个失败的通道账户不会将原本健康的 Gateway 和 Control UI 从服务中移除。对于有意将硬性通道故障视为未就绪的监控,请使用 /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 — Docker 的 Podman 替代方案
  • Kubernetes — 在集群上运行 Gateway 的最小 Kustomize 起点
  • Ansible — 使用 Tailscale VPN 和防火墙隔离的自动化服务器部署
  • Cloudflare Containers — 实验性的 Worker 加容器部署,使用 Litestream 备份到 R2
  • 更新 — 保持 OpenClaw 为最新
  • 配置 — 安装后的 Gateway 配置

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