Compose 操作
本页介绍取代 ClawDock 的 Compose 命令表、操作折叠区块,以及已发布镜像的刷新方式。属于 Docker 指南的一部分。
ClawDock 迁移¶
ClawDock 已被移除。日常操作请直接使用 Docker Compose。通过 curl 下载的现有副本不会自动卸载。请从您的 shell 启动文件(~/.zshrc 或 ~/.bashrc)中删除 source ~/.clawdock/clawdock-helpers.sh 这一行,然后启动一个新的 shell。如果您加载的是来自 scripts/clawdock/ 或旧版 scripts/shell-helpers/ 路径的检出副本,请改为删除相应的 source 行。请保留您的 OpenClaw 状态、凭据、工作区、项目 .env 和卷。
请在包含 docker-compose.yml 的目录中运行命令。在每条命令中保持相同的 Compose 文件集合与顺序,以确保挂载和设置保持不变。使用默认文件发现机制时,Compose 会在存在 docker-compose.override.yml 时自动加载它。额外的文件和 sandbox 文件需要显式使用 -f 选项;使用 -f 时,如果您使用了标准 override 文件,也请一并包含。例如,如果您的部署使用全部四个文件:
docker compose -f docker-compose.yml -f docker-compose.override.yml \
-f docker-compose.extra.yml -f docker-compose.sandbox.yml ps
仅使用您的部署已经使用的文件。下面的命令展示的是默认文件集合;需要时,请在 docker compose 之后插入您现有的 -f 选项。有关设置和额外挂载,请参阅 手动流程。
| 任务 | 命令 |
|---|---|
| 启动 | docker compose up -d openclaw-gateway |
| 停止整个栈 | docker compose down |
| 重启 | docker compose restart openclaw-gateway |
| 容器状态 | docker compose ps |
| 跟踪日志 | docker compose logs -f openclaw-gateway |
| 进入网关 shell | docker compose exec openclaw-gateway bash |
| CLI | docker compose run --rm openclaw-cli <command> |
| 仪表盘 URL | docker compose run --rm openclaw-cli dashboard --no-open |
| 列出设备 | docker compose run --rm openclaw-cli devices list |
| 批准设备 | docker compose run --rm openclaw-cli devices approve <requestId> |
| 检查配置 | docker compose run --rm openclaw-cli config get <path> |
使用 shell 或 CLI 命令之前,请先启动网关。如需自定义主机端口,请按照 容器化网关 中的说明调整打印出的仪表盘 URL。使用 健康检查 验证网关,并参阅 更新 OpenClaw 以获取镜像更新。
当 CLI 共享 Gateway 状态时,请在您的 Compose override 中为 openclaw-cli 服务添加 pid: "service:openclaw-gateway",以便所有权检查可以看到网关的进程;仅共享网络并不会共享 PID 命名空间。或者,在网关容器内通过 docker compose exec openclaw-gateway openclaw tui 运行 TUI。现在,不同的 PID 命名空间会拒绝无法验证的所有权,而不是回收正在运行的网关的锁。tui --local 会启动一个嵌入式 agent,并且不是针对共享状态的 PID 命名空间变通方案。较旧的锁会保留其先前的恢复行为,直到网关下次启动并写入命名空间标识。
即使 Docker 分配了不同的主机名,在约 90 秒没有所有者心跳后,替代网关也会收回已崩溃容器的状态锁和 SQLite 所有者租约。启动时会等待最多 95 秒,让新的所有权证据过期。Doctor 会立即拒绝新的、无法验证的所有者;停止先前的网关后,请在其最后一次心跳后等待最多 90 秒,然后重试。来自旧镜像的现有租约会使用其记录的主机名和心跳,直到替代者发布启动信息和 PID 命名空间标识。即使租约截止日期已过,经过验证的活跃所有者仍会阻止接管。镜像更新不需要模式迁移或手动删除租约。
令牌设置属于 Docker 设置流程 的一部分。如果您需要 Control UI 令牌,请私下从项目 .env 中读取 OPENCLAW_GATEWAY_TOKEN。config get <path> 会遮蔽敏感值;它不会显示完整的令牌。
为 Docker 网关启用 agent 沙箱
自定义 socket 路径(例如 rootless Docker):
export OPENCLAW_SANDBOX=1
export OPENCLAW_DOCKER_SOCKET=/run/user/1000/docker.sock
./scripts/docker/setup.sh
脚本仅在沙箱先决条件通过后才挂载 docker.sock。如果沙箱设置无法完成,它会将 agents.defaults.sandbox.mode 重置为 off。在 OpenClaw 沙箱处于活动状态的轮次中,Codex 代码模式会被禁用(参见 沙箱 § Docker 后端);切勿将主机 Docker socket 挂载到 agent 沙箱容器中。
自动化 / CI(非交互式)
使用 -T 禁用 Compose 的伪 TTY 分配:
共享网络安全说明
openclaw-cli 使用 network_mode: "service:openclaw-gateway",以便 CLI 命令可以通过 127.0.0.1 访问网关。请将此视为共享信任边界。compose 配置会在 openclaw-gateway 和 openclaw-cli 上丢弃 NET_RAW/NET_ADMIN,并启用 no-new-privileges。
openclaw-cli 中的 Docker Desktop DNS 故障
某些 Docker Desktop 配置在丢弃 NET_RAW 后,共享网络中的 openclaw-cli sidecar 会 DNS 查找失败,并在 openclaw plugins install 等基于 npm 的命令中显示为 EAI_AGAIN。日常操作请继续使用默认加固的 compose 文件。下面的覆盖配置仅为 openclaw-cli 容器恢复默认 capabilities——请仅将其用于需要访问 registry 的一次性命令,不要作为默认调用方式:
```bash
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>
```
如果你已经创建了长期运行的 openclaw-cli 容器,请使用相同的覆盖配置重新创建它——docker compose exec/docker exec 无法更改已创建容器的 Linux capabilities。
权限与 EACCES
镜像以 node(uid 1000)运行。如果在 /home/node/.openclaw 上看到权限错误,请确保主机 bind mounts 的所有者为 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,而不是用缩短的单阶段示例替换它。其 workspace-deps 阶段会提取 pnpm-workspace.yaml 所需的包清单。构建和生产依赖阶段共享这些输入,并分别运行 frozen-lockfile 安装。这样可以在不省略 packages/*、选定的 extensions/* 或其他必需 workspace 元数据的情况下,使两个依赖层均可缓存。
runtime-assets 阶段继承 production-deps,并从 runtime-build-output 覆盖 /app;后者是 build 的副本,已移除依赖树。这样可以在保留已编译的 workspace 包和 native addon 输出的同时,复用全新生产安装的层。它不会对从镜像层继承的依赖运行 pnpm prune;在 OverlayFS 上,pnpm 12 可能使该操作以 EXDEV 失败。build 目标会保留开发依赖,供 live-test 容器使用。
同一个 Dockerfile 保留了生产运行时约定:digest 固定的 Node 和 Bun 基础镜像、非 root uid 1000、tini、内置健康检查,以及 /usr/local/bin/openclaw 符号链接。Dependabot 会刷新已审核的基础镜像 digest;不要将其替换为浮动的 FROM node:24-bookworm 标签。
高级用户容器选项
默认镜像以安全为先,并以非 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。OpenClaw 会在 Linux 上自动检测镜像中由 Playwright 管理的 Chromium。
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 基础镜像 digest,每次构建都会应用当前 Debian point-release 更新。参见 OCI 镜像注解。
镜像内容与安全扫描¶
运行时镜像仅包含生产 Node.js 依赖。发布构建通过 digest 固定基础镜像,并使用 apt-get dist-upgrade 应用当前 Debian 安全更新;-browser 变体会安装其 Playwright 发布版本固定的 Chromium 版本。
扫描器总计可能包含发行版标记为 wont-fix 的 Debian 发现。若要针对当前基础镜像和包元数据在本地重新构建,请运行 docker build --pull -t openclaw:local .。
每周镜像刷新¶
latest*、main* 和 extended-stable* 移动标签每周从相同的带标签发布源重新构建,以便在 OpenClaw 发布之间获取当前操作系统安全更新。Stable 和 extended-stable 刷新保持独立,beta 镜像不会按此计划重新构建。
每次刷新还会发布带日期的标签,例如 2026.8.1-r20260820(以及 -slim 和 -browser 变体)。普通版本标签和带日期的 -rYYYYMMDD 标签是不可变的;如果你不希望部署跟随移动标签,请固定其中任一形式。
在 VPS 上运行?¶
参见 Hetzner (Docker VPS) 和 Docker VM Runtime,了解共享 VM 部署步骤,包括二进制内置、持久化和更新。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw