跳转到内容
OpenClaw Docs

Docker

Docker（可选）

Section titled “Docker（可选）”

Docker 是可选的。仅在您需要容器化网关或验证 Docker 流程时使用。

Docker 适合我吗？

Section titled “Docker 适合我吗？”
  • 是：您需要一个隔离的、可丢弃的网关环境，或者希望在未进行本地安装的主机上运行 OpenClaw。
  • 否：你在自己的机器上运行，并且只想要最快的开发循环。请改用常规安装流程。
  • 沙箱注意事项：agent 沙箱隔离也使用 Docker，但它不要求整个网关在 Docker 中运行。请参阅 沙箱隔离。

先决条件

Section titled “先决条件”
  • Docker Desktop（或 Docker Engine）+ Docker Compose v2
  • 至少 2 GB RAM 用于镜像构建（在 1 GB 主机上 pnpm install 可能会因 OOM 被终止并退出代码 137）
  • 足够的磁盘空间用于存储镜像和日志
  • 如果在 VPS/公共主机上运行，请查阅 网络安全加固， 特别是 Docker DOCKER-USER 防火墙策略。

容器化 Gateway(网关)

Section titled “容器化 Gateway(网关)”

  1. 构建镜像

    在仓库根目录下，运行设置脚本：

    Terminal window
    ./scripts/docker/setup.sh

    这会在本地构建网关镜像。如果要使用预构建的镜像：

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

    预构建的镜像发布在 GitHub Container Registry。 常用标签：main、latest、`

    （例如 2026.2.26`）。

  2. 完成新手引导

    设置脚本会自动运行新手引导。它将：

    • 提示输入提供商 API 密钥
    • 生成网关令牌并将其写入 .env
    • 通过 Docker Compose 启动网关

    在设置期间，预启动的新手引导和配置写入直接通过 openclaw-gateway 运行。openclaw-cli 用于在 网关容器已存在后运行的命令。

  3. 打开控制界面

    在浏览器中打开 http://127.0.0.1:18789/ 并将令牌粘贴到 设置中。

    再次需要该 URL？

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

  4. 配置渠道（可选）

    使用 CLI 容器添加消息传递渠道：

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

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

    ”

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

    ” ```

    文档：[WhatsApp](/en/channels/whatsapp)、[Telegram](/en/channels/telegram)、[Discord](/en/channels/discord)

手动流程

Section titled “手动流程”

如果您希望自己运行每个步骤而不是使用设置脚本：

Terminal window
docker build -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 gateway.mode local
docker compose run --rm --no-deps --entrypoint node openclaw-gateway \
  dist/index.js config set gateway.bind lan
docker compose run --rm --no-deps --entrypoint node openclaw-gateway \
  dist/index.js config set gateway.controlUi.allowedOrigins \
  '["http://localhost:18789","http://127.0.0.1:18789"]' --strict-json
docker compose up -d openclaw-gateway

环境变量

Section titled “环境变量”

设置脚本接受以下可选环境变量：

变量用途
OPENCLAW_IMAGE使用远程镜像而不是在本地构建
OPENCLAW_DOCKER_APT_PACKAGES在构建期间安装额外的 apt 软件包（以空格分隔）
OPENCLAW_EXTENSIONS在构建时预安装扩展依赖（以空格分隔的名称）
OPENCLAW_EXTRA_MOUNTS额外的主机绑定挂载（逗号分隔的 source:target[:opts]）
OPENCLAW_HOME_VOLUME将 /home/node 持久化在命名的 Docker 卷中
OPENCLAW_SANDBOX选择加入沙箱引导（1、true、yes、on）
OPENCLAW_DOCKER_SOCKET覆盖 Docker 套接字路径

健康检查

Section titled “健康检查”

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

Terminal window
curl -fsS http://127.0.0.1:18789/healthz   # liveness
curl -fsS http://127.0.0.1:18789/readyz     # readiness

Docker 镜像包含一个内置的 HEALTHCHECK，用于 ping /healthz。 如果检查持续失败，Docker 会将容器标记为 unhealthy， 编排系统可以重启或替换它。

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

Terminal window
docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLAW_GATEWAY_TOKEN"

局域网 vs 回环

Section titled “局域网 vs 回环”

scripts/docker/setup.sh 默认为 OPENCLAW_GATEWAY_BIND=lan，以便主机对 http://127.0.0.1:18789 的访问可以配合 Docker 端口发布使用。

  • lan（默认值）：主机浏览器和主机 CLI 可以访问已发布的网关端口。
  • loopback：只有容器网络命名空间内的进程可以直接访问 网关。

存储和持久化

Section titled “存储和持久化”

Docker Compose 将 OPENCLAW_CONFIG_DIR 绑定挂载到 /home/node/.openclaw，并将 OPENCLAW_WORKSPACE_DIR 绑定挂载到 /home/node/.openclaw/workspace，因此这些路径 在容器替换后仍然保留。

有关 VM 部署的完整持久性详细信息，请参阅 Docker VM Runtime - 什么持久化在哪里。

磁盘增长热点： 关注 media/、会话 JSONL 文件、cron/runs/*.jsonl 以及 /tmp/openclaw/ 下的滚动文件日志。

Shell 辅助脚本（可选）

Section titled “Shell 辅助脚本（可选）”

为了更轻松地进行日常 Docker 管理，请安装 ClawDock：

Terminal window
mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/clawdock/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.sh
echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc

如果您通过较旧的 scripts/shell-helpers/clawdock-helpers.sh 原始路径安装了 ClawDock，请重新运行上述安装命令，以便您的本地帮助文件跟踪新位置。

然后使用 clawdock-start、clawdock-stop、clawdock-dashboard 等。运行 clawdock-help 查看所有命令。 查看 ClawDock 获取完整的帮助指南。

为 Docker 网关启用代理沙箱
Terminal window
export OPENCLAW_SANDBOX=1
./scripts/docker/setup.sh

自定义套接字路径（例如无根 Docker）：

Terminal window
export OPENCLAW_SANDBOX=1
export OPENCLAW_DOCKER_SOCKET=/run/user/1000/docker.sock
./scripts/docker/setup.sh

该脚本仅在沙箱先决条件通过后才会挂载 docker.sock。如果 沙箱设置无法完成，脚本会将 agents.defaults.sandbox.mode 重置为 off。

自动化 / CI（非交互式）

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

Terminal window
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-cli 上启用 no-new-privileges。

权限与 EACCES

镜像以 node (uid 1000) 身份运行。如果在 /home/node/.openclaw 上看到权限错误，请确保您的主机绑定挂载归 uid 1000 所有：

Terminal window
sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace
更快的重建

请对您的 Dockerfile 进行排序，以便缓存依赖层。这样可以避免在锁定文件未更改时重新运行 pnpm install：

FROM node:24-bookworm
RUN curl -fsSL https://bun.sh/install | bash
ENV PATH="/root/.bun/bin:${PATH}"
RUN corepack enable
WORKDIR /app
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
COPY ui/package.json ./ui/package.json
COPY scripts ./scripts
RUN pnpm install --frozen-lockfile
COPY . .
RUN pnpm build
RUN pnpm ui:install
RUN pnpm ui:build
ENV NODE_ENV=production
CMD ["node","dist/index.js"]
高级用户容器选项

默认镜像以安全为优先，并以非 root node 身份运行。若要使用功能更全面的容器：

  1. 持久化 /home/node：export OPENCLAW_HOME_VOLUME="openclaw_home"
  2. 预构建系统依赖：export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq"
  3. 安装 Playwright 浏览器：
    Terminal window
    docker compose run --rm openclaw-cli \
      node /app/node_modules/playwright-core/cli.js install chromium
  4. 持久化浏览器下载：设置 PLAYWRIGHT_BROWSERS_PATH=/home/node/.cache/ms-playwright 并使用 OPENCLAW_HOME_VOLUME 或 OPENCLAW_EXTRA_MOUNTS。
OpenAI Codex OAuth (无头 Docker)

如果您在向导中选择 OpenAI Codex OAuth，它会打开一个浏览器 URL。在 Docker 或无头环境中，复制您跳转到的完整重定向 URL 并将其粘贴回向导中以完成身份验证。

基础镜像元数据

主要的 Docker 镜像使用 node:24-bookworm 并发布 OCI 基础镜像注解，包括 org.opencontainers.image.base.name、 org.opencontainers.image.source 等。请参阅 OCI image annotations。

在 VPS 上运行？

Section titled “在 VPS 上运行？”

请参阅 Hetzner (Docker VPS) 和 Docker VM Runtime 以了解共享 VM 部署步骤， 包括二进制文件构建、持久化和更新。

Agent 沙箱

Section titled “Agent 沙箱”

当启用 agents.defaults.sandbox 时，网关会在隔离的 Docker 容器内运行代理工具执行 （Shell、文件读/写等），而 网关本身则保留在主机上。这为不受信任或 多租户代理会话提供了一道坚实的屏障，而无需将整个网关容器化。

沙箱作用域可以是每个代理（默认）、每个会话或共享的。每个作用域 都会获得挂载在 /workspace 的自己的工作区。您还可以配置 允许/拒绝工具策略、网络隔离、资源限制和浏览器 容器。

有关完整的配置、镜像、安全说明和多代理配置文件，请参阅：

快速启用

Section titled “快速启用”
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        scope: "agent", // session | agent | shared
      },
    },
  },
}

构建默认沙箱镜像：

Terminal window
scripts/sandbox-setup.sh

故障排除

Section titled “故障排除”
镜像丢失或沙箱容器未启动

使用 scripts/sandbox-setup.sh 构建沙箱镜像，或者将 agents.defaults.sandbox.docker.image 设置为您的自定义镜像。 容器会根据需要按会话自动创建。

沙箱中的权限错误

将 docker.user 设置为与您挂载的工作区所有权相匹配的 UID:GID， 或者对工作区文件夹执行 chown。

沙箱中找不到自定义工具

OpenClaw 使用 sh -lc（登录 Shell）运行命令，该 Shell 会导入 /etc/profile 并可能会重置 PATH。设置 docker.env.PATH 以在前面添加您的 自定义工具路径，或者在 Dockerfile 中的 /etc/profile.d/ 下添加脚本。

镜像构建期间 OOM-killed（退出代码 137）

虚拟机至少需要 2 GB RAM。使用更大规格的机器并重试。

控制 UI 中显示未授权或需要配对

获取一个新的仪表板链接并批准浏览器设备：

Terminal window
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
更多详情：[仪表板](/en/web/dashboard)，[设备](/en/cli/devices)。
Gateway(网关) 目标显示 ws://172.x.x.x 或来自 Docker CLI 的配对错误

重置网关模式和绑定：

Terminal window
docker compose run --rm openclaw-cli config set gateway.mode local
docker compose run --rm openclaw-cli config set gateway.bind lan
docker compose run --rm openclaw-cli devices list --url ws://127.0.0.1:18789

相关

Section titled “相关”
  • 安装概览 — 所有安装方法
  • Podman — Docker 的 Podman 替代方案
  • ClawDock — Docker Compose 社区设置
  • 更新 — 保持 OpenClaw 最新
  • 配置 — 安装后的网关配置