跳转到内容
OpenClaw Docs

DockerDocker

Docker 是可选的。仅当您想要容器化网关或验证 Docker 流程时才使用它。

Docker 适合我吗？

Section titled “Docker 适合我吗？”
  • 适合：您想要一个隔离的、用完即弃的网关环境，或者希望在无需本地安装的主机上运行 OpenClaw。
  • 不适合：您在您自己的机器上运行，只想要最快的开发循环。请改用常规安装流程。
  • 沙箱注意事项：启用沙箱时，默认的沙箱后端使用 Docker，但沙箱默认处于关闭状态，并且不要求整个网关在 Docker 中运行。此外也提供 SSH 和 OpenShell 沙箱后端。请参阅 沙箱隔离。

先决条件

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

容器化网关

Section titled “容器化网关”

  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
    • 创建 auth-profile 密钥目录
    • 通过 Docker Compose 启动网关

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

  3. 打开控制 UI

    在浏览器中打开 http://127.0.0.1:18789/ 并将配置的 共享密钥粘贴到设置中。安装脚本默认会将令牌写入 .env； 如果将容器配置切换为密码验证，请改用该密码。

    需要再次获取 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](/zh/channels/whatsapp)、[Telegram](/zh/channels/telegram)、[Discord](/zh/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 --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

环境变量

Section titled “环境变量”

安装脚本接受这些可选的环境变量：

变量用途
OPENCLAW_IMAGE使用远程镜像而不是在本地构建
OPENCLAW_IMAGE_APT_PACKAGES在构建期间安装额外的 apt 软件包（以空格分隔）
OPENCLAW_IMAGE_PIP_PACKAGES在构建期间安装额外的 Python 包（空格分隔）
OPENCLAW_EXTENSIONS在构建时预安装插件依赖项（空格分隔的名称）
OPENCLAW_EXTRA_MOUNTS额外的主机绑定挂载（逗号分隔的 source:target[:opts]）
OPENCLAW_HOME_VOLUME将 /home/node 持久化在命名的 Docker 卷中
OPENCLAW_SANDBOX选择加入沙箱引导（1、true、yes、on）
OPENCLAW_SKIP_ONBOARDING跳过交互式新手引导步骤（1、true、yes、on）
OPENCLAW_DOCKER_SOCKET覆盖 Docker 套接字路径
OPENCLAW_DISABLE_BONJOUR禁用 Bonjour/mDNS 广播（对于 Docker 默认为 1）
OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS禁用捆绑插件源绑定挂载覆盖
OTEL_EXPORTER_OTLP_ENDPOINT用于 OpenTelemetry 导出的共享 OTLP/HTTP 收集器端点
OTEL_EXPORTER_OTLP_*_ENDPOINT用于跟踪、指标或日志的特定 Signal OTLP 端点
OTEL_EXPORTER_OTLP_PROTOCOL覆盖 OTLP 协议。目前仅支持 http/protobuf
OTEL_SERVICE_NAME用于 OpenTelemetry 资源的服务名称
OTEL_SEMCONV_STABILITY_OPT_IN选择启用最新的实验性 GenAI 语义属性
OPENCLAW_OTEL_PRELOADED如果已预加载一个 OpenTelemetry SDK，则跳过启动第二个 SDK

官方 Docker 镜像不附带 Homebrew。在 OpenClaw 新手引导期间，当它在没有 brew 的 Linux 容器中运行时，会隐藏仅限 brew 的技能依赖安装程序；这些依赖项必须由自定义镜像提供或手动安装。对于 Debian 软件包中可用的依赖项，请在镜像构建期间使用 OPENCLAW_IMAGE_APT_PACKAGES。旧的 OPENCLAW_DOCKER_APT_PACKAGES 名称仍然被接受。 对于 Python 依赖项，请使用 OPENCLAW_IMAGE_PIP_PACKAGES。这会在镜像构建期间运行 python3 -m pip install --break-system-packages，因此请固定软件包版本并仅使用您信任的软件包索引。

维护人员可以通过将一个插件源目录挂载到其打包的源路径（例如 OPENCLAW_EXTRA_MOUNTS=/path/to/fork/extensions/synology-chat:/app/extensions/synology-chat:ro），来针对打包镜像测试捆绑插件源。 该挂载的源目录会覆盖同一插件 ID 的匹配编译 /app/dist/extensions/synology-chat 包。

可观测性

Section titled “可观测性”

OpenTelemetry 导出是从 Gateway(网关) 容器出站到您的 OTLP 收集器的。它不需要已发布的 Docker 端口。如果您在本地构建镜像并希望镜像内部可使用捆绑的 OpenTelemetry 导出器，请包含其运行时依赖项：

Terminal window
export OPENCLAW_EXTENSIONS="diagnostics-otel"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://otel-collector:4318"
export OTEL_SERVICE_NAME="openclaw-gateway"
./scripts/docker/setup.sh

在启用导出之前，请从 ClawHub 在打包的 Docker 安装中安装官方 @openclaw/diagnostics-otelClawHubDocker 插件。自定义源构建的镜像仍可以通过 OPENCLAW_EXTENSIONS=diagnostics-otel 包含本地插件源。要启用导出，请在配置中允许并启用 diagnostics-otel 插件，然后设置 diagnostics.otel.enabled=true 或使用 OpenTelemetry 导出 中的配置示例。Collector 认证标头通过 diagnostics.otel.headersDocker 配置，而不是通过 Docker 环境变量。

Prometheus 指标使用已发布的 Gateway(网关) 端口。安装 Gateway(网关)clawhub:@openclaw/diagnostics-prometheus，启用 diagnostics-prometheus 插件，然后抓取：

http://<gateway-host>:18789/api/diagnostics/prometheus

该路由受 Gateway(网关) 身份验证保护。不要公开单独的公共 Gateway(网关)/metrics 端口或未经身份验证的反向代理路径。请参阅 Prometheus 指标。

健康检查

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 镜像包含一个内置的 DockerHEALTHCHECK，用于 ping /healthzDocker。如果检查持续失败，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:18789Docker 的访问可以通过 Docker 端口发布正常工作。

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

主机本地提供商

Section titled “主机本地提供商”

当 OpenClaw 在 Docker 中运行时，容器内的 127.0.0.1 是容器 本身，而不是您的主机。对于在主机上运行的 AI 提供商，请使用 host.docker.internal：

提供商主机默认 URLDocker 设置 URL
LM Studiohttp://127.0.0.1:1234http://host.docker.internal:1234
Ollamahttp://127.0.0.1:11434http://host.docker.internal:11434

附带的 Docker 设置使用这些主机 URL 作为 LM Studio 和 Ollama 新手引导的默认值，并且 docker-compose.yml 将 host.docker.internal 映射到 Linux Docker 引擎的 LinuxDocker 主机网关。Docker Desktop 已在 macOS 和 Windows 上提供了相同的主机名。

主机服务还必须监听可从 Docker 访问的地址：

Terminal window
lms server start --port 1234 --bind 0.0.0.0
OLLAMA_HOST=0.0.0.0:11434 ollama serve

如果您使用自己的 Compose 文件或 docker run 命令，请自行添加相同的主机 映射，例如 --add-host=host.docker.internal:host-gateway。

Bonjour / mDNS

Section titled “Bonjour / mDNS”

Docker 桥接网络通常无法可靠地转发 Bonjour/mDNS 多播 （224.0.0.251:5353）。因此，附带的 Compose 设置默认 OPENCLAW_DISABLE_BONJOUR=1，以防止当桥接丢弃多播流量时 Gateway(网关) 发生崩溃循环或重复 重启广告。

对 Docker 主机使用已发布的 Gateway(网关) URL、Tailscale 或广域 DNS-SD。 仅在运行主机网络、macvlan 或已知 mDNS 组播有效的其他网络时设置 Gateway(网关)TailscaleDockerOPENCLAW_DISABLE_BONJOUR=0。

有关注意事项和故障排除，请参阅 Bonjour 发现。

存储和持久性

Section titled “存储和持久性”

Docker Compose 将 DockerOPENCLAW_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 存放以下内容的位置：

  • openclaw.json 用于行为配置
  • agents/<agentId>/agent/auth-profiles.jsonOAuthAPI 用于存储提供商 OAuth/API 密钥的身份验证
  • .env 用于环境变量支持的运行时密钥（例如 OPENCLAW_GATEWAY_TOKEN）

身份配置文件密钥目录存储用于 OAuth 支持的身份配置文件令牌材料的本地加密密钥。请将其与 Docker 主机状态一起保存，但与 OAuthDockerOPENCLAW_CONFIG_DIR 分开存放。

已安装的可下载插件将其包状态存储在挂载的 OpenClaw 主目录下，因此插件安装记录和包根目录在容器替换后得以保留。Gateway(网关) 启动不会生成捆绑插件的依赖树。

有关 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。当 OpenClaw 沙箱处于活动状态时，Codex 代码模式轮次仍受限于 Codex workspace-write；请勿将主机 Docker 套接字挂载到代理沙箱容器中。

自动化 / 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-gateway 和 openclaw-cli 上启用 no-new-privileges。

Docker%PH:GLOSSARY:338:da7a16c0%% Desktop 中 openclaw-cli 的 DNS 故障

某些 Docker Desktop 设置在丢弃 NET_RAW 后，无法从共享网络 openclaw-cli 边车进行 DNS 查找，这会在 npm 支持的命令（例如 openclaw plugins install）中显示为 EAI_AGAIN。 对于正常的网关操作，请保留默认的加固 compose 文件。下面的本地覆盖通过恢复 CLI 的默认功能来放宽 Docker 容器的安全姿态，因此请仅在需要包注册表访问的一次性 CLI 命令中使用它，而不要将其作为默认的 Compose 调用方式：

Terminal window
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
如果您已经创建了长时间运行的 `openclaw-cli` 容器，请使用相同的覆盖重新创建它。`docker compose exec` 和 `docker exec` 无法
在已创建的容器上更改 Linux 功能。
Permissions and EACCES

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

Terminal window
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 运行容器并修复绑定挂载的所有权。仅在您打算长期以 root 身份运行 OpenClaw 时，才将 /path/to/openclaw-config/npm chown 给 root:root。

Faster rebuilds

请对您的 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"]
Power-user container options

默认镜像以安全为优先，并以非 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
  5. 或将 Playwright 浏览器安装到持久化卷中：
    Terminal window
    docker compose run --rm openclaw-cli \
      node /app/node_modules/playwright-core/cli.js install chromium
  6. 持久化浏览器下载：使用 OPENCLAW_HOME_VOLUME 或 OPENCLAW_EXTRA_MOUNTS。OpenClaw 会自动检测 Docker 镜像在 Linux 上 由 Playwright 管理的 Chromium。
OpenAIOAuthDockerOpenAI Codex OAuth (无头 Docker)

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

基础镜像元数据

主 Docker 运行时镜像使用 node:24-bookworm-slim 并包含 tini 作为入口点初始化进程 (PID 1)，以确保回收僵尸进程并在长时间运行的容器中正确处理信号。它发布 OCI 基础镜像注解，包括 org.opencontainers.image.base.name、 org.opencontainers.image.sourceDocker 等。Node 基础摘要 通过 Dependabot Docker 基础镜像 PR 刷新；发布构建不运行 发行版升级层。请参阅 OCI image annotations。

在 VPS 上运行？

Section titled “在 VPS 上运行？”

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

Agent 沙箱

Section titled “Agent 沙箱”

当使用 Docker 后端启用 agents.defaults.sandboxDockerDocker 时，网关 在独立的 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

对于没有源代码检出的 npm 安装，请参阅 沙箱隔离 § 镜像和设置 中的内联 docker build 命令。

故障排除

Section titled “故障排除”
镜像缺失或沙箱容器无法启动

使用 scripts/sandbox-setup.sh （源代码检出）或 沙箱隔离 § 镜像和设置 （npm 安装）中的内联 docker build 命令构建沙箱镜像， 或者将 agents.defaults.sandbox.docker.image 设置为您的自定义镜像。 容器会根据需要按会话自动创建。

沙箱中的权限错误

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

在沙箱中找不到自定义工具

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

镜像构建期间因内存不足被杀死 (exit 137)

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

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

重置 Gateway 模式和绑定：

Terminal window
docker compose run --rm openclaw-cli config set --batch-json '[{"path":"gateway.mode","value":"local"},{"path":"gateway.bind","value":"lan"}]'
docker compose run --rm openclaw-cli devices list --url ws://127.0.0.1:18789

相关

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