Compose 操作

export OPENCLAW_SANDBOX=1
./scripts/docker/setup.sh

自定义 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 沙箱容器中。

使用 -T 禁用 Compose 的伪 TTY 分配：

docker compose run -T --rm openclaw-cli gateway probe
docker compose run -T --rm openclaw-cli devices list --json

openclaw-cli 使用 network_mode: "service:openclaw-gateway"，因此 CLI 命令可以通过 127.0.0.1 访问网关。请将此视为共享信任边界。compose 配置会丢弃 NET_RAW/NET_ADMIN，并在 openclaw-gateway 和 openclaw-cli 上都启用 no-new-privileges。

某些 Docker Desktop 设置在丢弃 NET_RAW 后，从共享网络的 openclaw-cli sidecar 执行 DNS 查找会失败，表现为在类似 openclaw plugins install 这类由 npm 支撑的命令期间出现 EAI_AGAIN。正常操作时请保留默认的加固 compose 文件。下面的 override 仅恢复 openclaw-cli 容器的默认 capabilities——请将其用于需要访问 registry 的一次性命令，而不是作为默认调用方式：

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 容器，请使用相同的 override 重新创建它——docker compose exec/docker exec 无法更改已创建容器上的 Linux capabilities。

镜像以 node（uid 1000）身份运行。如果你在 /home/node/.openclaw 上看到权限错误，请确保你的宿主机 bind mount 由 uid 1000 拥有：

sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace

同样的不匹配可能表现为 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/* 或其他必需的工作区元数据。

runtime-assets 阶段继承 production-deps，并从 runtime-build-output（一份移除了依赖树的 build 副本）叠加 /app。这样既复用了全新生产安装的层，又保留了已编译的工作区包和原生插件输出。它不会对从镜像层继承的依赖运行 pnpm prune；在 OverlayFS 上，pnpm 12 可能因 EXDEV 而失败。build 目标保留开发依赖，用于实时测试容器。

同一个 Dockerfile 保留了生产运行时契约：基于摘要固定的 Node 和 Bun 基础镜像、非 root 用户 uid 1000、tini、内置健康检查，以及 /usr/local/bin/openclaw 符号链接。Dependabot 会刷新已审查的基础镜像摘要；请勿用浮动的 FROM node:24-bookworm 标签替换它们。

默认镜像以安全为先，并以非 root 用户 node 运行。若要获得功能更完整的容器：

1. 持久化 /home/node：export OPENCLAW_HOME_VOLUME="openclaw_home"
2. 预置系统依赖：export OPENCLAW_IMAGE_APT_PACKAGES="git curl jq"
3. 预置 Python 依赖：export OPENCLAW_IMAGE_PIP_PACKAGES="requests==2.32.5 humanize==4.14.0"
4. 预置 Playwright Chromium：export OPENCLAW_INSTALL_BROWSER=1，或使用官方 -browser 镜像标签
5. 持久化浏览器下载与缓存：使用 OPENCLAW_HOME_VOLUME 或 OPENCLAW_EXTRA_MOUNTS。OpenClaw 在 Linux 上会自动检测镜像中由 Playwright 管理的 Chromium。

如果在向导中选择 OpenAI Codex OAuth，它会打开一个浏览器 URL。在 Docker 或无头（headless）环境中，请复制你最终跳转到的完整重定向 URL，然后粘贴回向导中以完成身份验证。

运行时镜像使用 node:24-bookworm-slim，并以 PID 1 运行 tini，从而在长时间运行的容器中正确回收僵尸进程并处理信号。它发布 OCI 基础镜像注解，包括 org.opencontainers.image.base.name 和 org.opencontainers.image.source。Dependabot 会刷新固定的 Node 基础镜像摘要，每次构建还会应用当前的 Debian 小版本更新。参见 OCI 镜像注解。