docker CLI。将后端设置为 "podman" 可直接选择原生 Podman。沙箱默认处于关闭状态,网关本身无需运行在容器中。SSH 和 OpenShell 沙箱后端也可用;请参阅 沙箱。
要托管多个用户?请参阅 多租户托管,了解每个租户一个单元格的模式。
先决条件
- Docker Desktop(或 Docker Engine)+ Docker Compose v2
- 用于镜像构建的内存至少 2 GB(在 1 GB 的主机上,
pnpm install可能会因 OOM 被杀死并返回 exit 137) - 为镜像和日志预留足够的磁盘空间
- 在 VPS/公网主机上,请查看网络暴露的安全加固,尤其是 Docker 的
DOCKER-USER防火墙链。
容器化网关
1
构建镜像
从仓库根目录执行:这会在本地构建网关镜像为 预构建镜像会首先发布到 GitHub Container Registry。GHCR 是发布自动化、固定部署和来源检查的主仓库。相同的发布也会在 Docker Hub 镜像仓库 使用
openclaw:local。若要改用预构建镜像:openclaw/openclaw 上提供镜像:ghcr.io/openclaw/openclaw 或 openclaw/openclaw,避免使用非官方镜像,因为它们不遵循 OpenClaw 的发布时间或保留策略。特定版本的标签包括 2026.2.26 等正式版本,以及 2026.2.26-beta.1 等预发布版本。稳定版本会更新 latest 和 main;月度末尾的网关版本只会更新 extended-stable。变体包括 slim、main-slim、extended-stable-slim、latest-browser、main-browser 和 extended-stable-browser。默认镜像包含 codex 和 diagnostics-otel 插件。-browser 变体还预装了 Chromium,可用于沙箱浏览器工具,无需首次运行时安装 Playwright。2
离线重运行
在离线主机上,请先传输并加载镜像:
--offline 会验证 OPENCLAW_IMAGE 已经存在于本地,禁用隐式的 Compose 拉取/构建,然后执行正常流程:.env 同步、权限修复、引导、网关配置同步、Compose 启动。如果 OPENCLAW_SANDBOX=1,离线设置还会检查通过 OPENCLAW_DOCKER_SOCKET 连接的守护进程上已配置的默认沙箱镜像和每个代理的沙箱镜像,包括基于 Docker 的浏览器镜像上的 browser-contract 标签。如果所需镜像缺失或已过期,设置会在不更改沙箱配置的情况下退出,而不是报告一个有问题的成功结果。3
完成引导
设置脚本会自动运行引导:
- 提示输入提供方 API 密钥
- 生成网关令牌并写入
.env - 创建 auth-profile 密钥目录
- 通过 Docker Compose 启动网关
openclaw-gateway 运行(使用 --no-deps --entrypoint node),因为 openclaw-cli 共享网关的网络命名空间,只有在网关容器存在后才能工作。4
打开控制界面
打开
http://127.0.0.1:18789/,并将写入 .env 的令牌粘贴到“设置”中。如果你把容器切换为密码认证,则改用该密码。需要再次获取 URL?无头引导
对于无人值守的容器主机,请将提供方、Gateway 和通道凭据放入 Compose.env 文件中,这样一次性引导容器和长期运行的 Gateway 都能接收相同的值:
TELEGRAM_BOT_TOKEN 保留在 .env 中:--use-env 会将凭据查找留给环境,而不会将令牌复制到 openclaw.json 中,运行中的 Gateway 也需要相同的变量。启动后通道配置发生变化时,Gateway 的配置监视器会自动热重载受影响的通道。
请参阅 openclaw channels,了解凭据标志替代方案和其他通道插件。
手动流程
.git。请像上面所示一样,将源代码身份作为构建参数传入,这样镜像的 About 页面就会显示检出的提交和一个构建时间戳。scripts/docker/setup.sh 会自动解析并传入这两个值。
从仓库根目录运行
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 镜像但保留相同的挂载状态/配置时,新的网关会在就绪前执行启动时安全的升级迁移和插件收敛。常规的镜像升级通常不需要额外执行一次openclaw doctor --fix。
如果启动无法安全完成这些修复,网关会直接退出,而不是报告为健康状态。使用重启策略时,Docker、Podman 或 Kubernetes 可能会显示网关容器正在重启。请保留挂载的状态卷,然后使用相同的状态/配置挂载,以网关使用的相同镜像运行一次 openclaw doctor --fix 作为容器命令:
环境变量
scripts/docker/setup.sh 接受的可选变量(对于网关容器,也可直接由 docker-compose.yml 接受):
官方镜像不包含 Homebrew。在入门过程中,OpenClaw 会在一个没有
brew 的 Linux 容器中隐藏仅适用于 brew 的技能依赖安装器;请通过自定义镜像提供这些依赖,或手动安装。对于 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_EXTENSIONS 从源码检出中选择插件清单 id;
当现有源码目录名称不同的时候,也同样接受这些名称。Docker
构建会将所选内容一次性解析为源码目录,安装生产依赖,并且当某个所选插件以单独形式发布且
openclaw.build.bundledDist: false 时,会将其运行时编译进根目录的 bundled
dist 中。这种仅限 Docker 的打包方式不会改变插件的 npm 或 ClawHub
工件契约。未知、无效或歧义的 id 会导致镜像构建失败。已知的仅依赖/仅源码 id 会保留其现有的源码与依赖
分层,不会获得编译后的根 dist 条目。带有统一构建条目的所选插件必须成功编译;未选中的外部插件
源码和运行时输出会被裁剪掉。
例如,下面这些命令为 ClickClack、Slack 和 Microsoft Teams 构建独立的、多架构的
FakeCo 网关镜像。ClawRouter 已经是根 OpenClaw 运行时的一部分,因此 ClickClack 镜像只选择
clickclack。显式传入空的 browser 参数可使默认镜像不包含 Chromium:
--platform linux/arm64 --load 或 --platform linux/amd64 --load 进行
单个本地原生构建。多平台输出以及附带的 SBOM/溯源信息需要镜像仓库或其他能够保留证明材料的 Buildx 输出。推送后,请检查 manifest,并部署不可变的 digest,而不是可变的 source-SHA tag:
OPENCLAW_EXTRA_MOUNTS=/path/to/fork/extensions/synology-chat:/app/extensions/synology-chat:ro。这会覆盖同一插件 id 对应的已编译 /app/dist/extensions/synology-chat bundle。
可观测性
OpenTelemetry 导出是从 Gateway 容器向你的 OTLP 收集器发出的;它不需要发布 Docker 端口。要在本地构建的镜像中包含捆绑的导出器: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 插件,然后抓取:
/metrics 端口或未认证的反向代理路径。参见 Prometheus 指标。
健康检查
容器探针端点(无需认证):HEALTHCHECK 会请求 /healthz;重复失败会将容器标记为 unhealthy,以便编排器重启或替换容器。使用 /startupz 作为编排器的启动或就绪探针,这样通道账户失败不会使原本健康的 Gateway 和控制界面从服务中移除。使用 /readyz 进行监控时,会有意将严重的通道故障视为未就绪。有关响应详情,请参阅健康检查。
已认证的深度健康快照:
LAN 与回环
scripts/docker/setup.sh 默认将 OPENCLAW_GATEWAY_BIND=lan,因此主机上的 http://127.0.0.1:18789 可以通过 Docker 端口发布正常访问。
lan(默认):主机浏览器和主机 CLI 都可以访问已发布的网关端口。loopback:只有容器网络命名空间内的进程可以直接访问网关。
在
gateway.bind 中使用绑定模式值(lan / loopback / custom / tailnet / auto),不要使用诸如 0.0.0.0 或 127.0.0.1 之类的主机别名。本地主机提供商
在容器内部,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 可以访问的地址:
docker run?请自行添加相同的映射,例如 --add-host=host.docker.internal:host-gateway。
Docker 中的 Claude CLI 后端
官方镜像不会预装 Claude Code。请在容器内以node 用户身份安装并登录,然后持久化该容器的 home 目录,这样镜像升级时就不会擦除二进制文件或认证状态。
对于新安装,请在运行设置之前启用一个持久化的 /home/node 卷:
.env 值——设置脚本总是会根据当前 shell 和默认值重写 .env,它不会自行读取该文件:
.env 包含你的 shell 无法直接 source 的值,请先手动重新导出你依赖的内容(OPENCLAW_IMAGE、端口、绑定模式、自定义路径、OPENCLAW_EXTRA_MOUNTS、sandbox、skip-onboarding)。生成的 overlay 会为 openclaw-gateway 和 openclaw-cli 两个服务挂载 home 卷;后续命令请使用该 overlay 运行(如果你使用了 docker-compose.override.yml,请先加上它):
claude 写入 /home/node/.local/bin/claude。OpenClaw 镜像已将 /home/node/.local/bin 加入 PATH,因此内置的 Anthropic 插件无需适配器配置覆盖即可找到它。
使用同一个已持久化的 home 目录登录并验证:
claude-cli 后端:
OPENCLAW_HOME_VOLUME 会将原生安装持久化到 /home/node/.local/bin 和 /home/node/.local/share/claude,以及 Claude Code 的设置/认证数据持久化到 /home/node/.claude 和 /home/node/.claude.json。仅持久化 /home/node/.openclaw 还不够;如果你使用 OPENCLAW_EXTRA_MOUNTS 而不是 home 卷,请将所有这些 Claude 路径都挂载到两个服务中。
对于共享生产自动化或可预测的 Anthropic 计费,建议优先使用 Anthropic API key 方案。Claude CLI 的复用会跟随 Claude Code 已安装的版本、账户登录、计费和更新行为。
Bonjour / mDNS
Docker 桥接网络通常不会可靠地转发 Bonjour/mDNS 组播(224.0.0.251:5353)。当 OPENCLAW_DISABLE_BONJOUR 未设置时,内置的 Bonjour 插件在检测到自己运行于容器中后,会自动禁用局域网广播,因此不会因为桥接网络丢弃组播而陷入崩溃重试循环。将 OPENCLAW_DISABLE_BONJOUR=1 设为强制关闭,无论检测结果如何;或设为 0 强制开启(仅适用于主机网络、macvlan,或其他已知 mDNS 组播可正常工作的网络)。
否则,请改用已发布的 Gateway URL、Tailscale,或适用于 Docker 主机的广域 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
OPENCLAW_CONFIG_DIR 分开。
已安装的可下载插件会在挂载的 OpenClaw 主目录下存储包状态,因此安装记录和包根目录会在容器替换后保留;网关启动不会重新生成内置插件的依赖树。
有关完整的 VM 持久化细节,请参见 Docker VM Runtime - What persists where。
磁盘增长热点: media/、每个 agent 的 SQLite 数据库、旧版 session JSONL 转录、共享的 SQLite 状态数据库、已安装插件的包根目录,以及 /tmp/openclaw/ 下的滚动文件日志。
Shell 助手(可选)
对于较短的日常命令,请安装 ClawDock:scripts/shell-helpers/clawdock-helpers.sh 路径安装的,请重新运行上面的命令,这样你的本地助手就会跟踪当前的位置。然后使用 clawdock-start、clawdock-stop、clawdock-dashboard 等命令(运行 clawdock-help 查看完整列表)。
为 Docker 网关启用代理沙箱
为 Docker 网关启用代理沙箱
docker.sock。如果沙箱设置无法完成,它会将 agents.defaults.sandbox.mode 重置为 off。在 OpenClaw 沙箱处于活动状态的轮次中,Codex 代码模式会被禁用(参见 Sandboxing § Docker backend);绝不要将宿主机 Docker socket 挂载到代理沙箱容器中。自动化 / CI(非交互式)
自动化 / CI(非交互式)
使用
-T 禁用 Compose 的伪 TTY 分配:共享网络安全说明
共享网络安全说明
openclaw-cli 使用 network_mode: "service:openclaw-gateway",因此 CLI 命令可以通过 127.0.0.1 访问网关。请将其视为共享信任边界。compose 配置会移除 NET_RAW/NET_ADMIN,并在 openclaw-gateway 和 openclaw-cli 上启用 no-new-privileges。openclaw-cli 中的 Docker Desktop DNS 故障
openclaw-cli 中的 Docker Desktop DNS 故障
某些 Docker Desktop 配置在共享网络的 如果你已经创建了一个长期运行的
openclaw-cli sidecar 上移除 NET_RAW 后,会导致 DNS 查询失败,在基于 npm 的命令(如 openclaw plugins install)期间表现为 EAI_AGAIN。正常运行时请保留默认的加固 compose 文件。下面的覆盖配置仅为 openclaw-cli 容器恢复默认 capabilities——请将其用于需要 registry 访问的一次性命令,而不要作为默认调用方式:openclaw-cli 容器,请使用相同的覆盖配置重新创建它——docker compose exec/docker exec 无法更改已创建容器的 Linux capabilities。权限和 EACCES
权限和 EACCES
该镜像以 同样的不匹配也可能表现为
node(uid 1000)运行。如果你在 /home/node/.openclaw 上看到权限错误,请确保宿主机的 bind mount 归属 uid 1000:blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root),随后出现 plugin present but blocked——这是进程 uid 与挂载的插件目录所有者不一致。建议使用默认的 uid 1000 运行,并修复 bind mount 的所有权。只有在你有意长期以 root 运行 OpenClaw 时,才将 /path/to/openclaw-config/npm chown 为 root:root。更快的重建
更快的重建
安排你的 Dockerfile,使依赖层能够被缓存,从而避免除非 lockfile 变化否则重复运行
pnpm install:高级用户容器选项
高级用户容器选项
默认镜像以安全优先方式运行,并以非 root 的
node 用户运行。若要使用功能更完整的容器:- 持久化
/home/node:export OPENCLAW_HOME_VOLUME="openclaw_home" - 预装系统依赖:
export OPENCLAW_IMAGE_APT_PACKAGES="git curl jq" - 预装 Python 依赖:
export OPENCLAW_IMAGE_PIP_PACKAGES="requests==2.32.5 humanize==4.14.0" - 预装 Playwright Chromium:
export OPENCLAW_INSTALL_BROWSER=1,或使用官方的-browser镜像标签 - 持久化浏览器下载内容和缓存: 使用
OPENCLAW_HOME_VOLUME或OPENCLAW_EXTRA_MOUNTS。在 Linux 上,OpenClaw 会自动检测镜像中由 Playwright 管理的 Chromium。
OpenAI Codex OAuth(无头 Docker)
OpenAI Codex OAuth(无头 Docker)
如果你在向导中选择 OpenAI Codex OAuth,它会打开一个浏览器 URL。在 Docker 或无头环境中,请复制你最终落地到的完整重定向 URL,并将其粘贴回向导中以完成认证。
基础镜像元数据
基础镜像元数据
运行时镜像使用
node:24-bookworm-slim,并以 tini 作为 PID 1 运行,因此在长期运行的容器中,僵尸进程会被回收,信号也能被正确处理。它会发布 OCI 基础镜像注解,包括 org.opencontainers.image.base.name 和 org.opencontainers.image.source。Dependabot 会刷新固定的 Node 基础镜像摘要;发布构建不会运行单独的发行版升级层。参见 OCI 镜像注解。在 VPS 上运行?
请参见 Hetzner(Docker VPS) 和 Docker VM Runtime,了解共享虚拟机部署步骤,包括二进制文件烘焙、持久化和更新。Agent 沙箱
当使用 Docker backend 启用agents.defaults.sandbox 时,gateway 会将代理工具执行(shell、文件读写等)运行在隔离的 Docker 容器中,而 gateway 本身仍留在宿主机上——这在不将整个 gateway 容器化的情况下,为不受信任或多租户的代理会话提供了一道硬隔离墙。
沙箱作用域可以是按代理(默认)、按会话或共享;每个作用域都会获得自己挂载在 /workspace 的工作区。你还可以配置允许/拒绝的工具策略、网络隔离、资源限制以及浏览器容器。
完整配置、镜像、安全说明和多代理配置文件请参见:
快速启用
docker build 命令。
故障排查
镜像缺失或沙箱容器未启动
镜像缺失或沙箱容器未启动
使用
scripts/sandbox-setup.sh(源码检出)或 沙箱 § 镜像和设置 中的内联 docker build 命令(npm install)构建沙箱镜像,或者将 agents.defaults.sandbox.docker.image 设置为你的自定义镜像。容器会按需为每个会话自动创建。沙箱中的权限错误
沙箱中的权限错误
将
docker.user 设置为与你挂载的工作区所有权匹配的 UID:GID,或者将工作区文件夹的所有者改为当前用户。在沙箱中找不到自定义工具
在沙箱中找不到自定义工具
OpenClaw 使用
sh -lc(登录 shell)运行命令,这会加载 /etc/profile 并可能重置 PATH。将 docker.env.PATH 设置为在前面追加你的自定义工具路径,或者在你的 Dockerfile 中于 /etc/profile.d/ 下添加一个脚本。构建镜像时因 OOM 被杀死(exit 137)
构建镜像时因 OOM 被杀死(exit 137)
虚拟机至少需要 2 GB 内存。请使用更大的机器规格并重试。
网关目标显示 ws://172.x.x.x 或 Docker CLI 出现配对错误
网关目标显示 ws://172.x.x.x 或 Docker CLI 出现配对错误
重置网关模式和绑定: