Docker

Docker 是可选的。你可以用它创建隔离的临时 Gateway 网关环境，或在没有本地安装的主机上运行。如果你已经在自己的机器上进行开发，请改用常规安装流程。

启用 agents.defaults.sandbox 后，默认沙箱后端会使用 Docker，但沙箱隔离默认关闭，且不要求 Gateway 网关本身在 Docker 中运行。你也可以使用 SSH 和 OpenShell 沙箱后端；请参阅沙箱隔离。

要托管多个用户？有关每租户一个单元的模型，请参阅多租户托管。

前置要求

• Docker Desktop（或 Docker Engine）+ Docker Compose v2
• 构建镜像至少需要 2 GB RAM（在 1 GB 主机上，pnpm install 可能因内存不足而被终止，退出码为 137）
• 有足够空间存储镜像和日志
• 在 VPS/公共主机上，请查看网络暴露安全加固，尤其是 Docker DOCKER-USER 防火墙链

容器化 Gateway 网关

./scripts/docker/setup.sh

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

export OPENCLAW_IMAGE="openclaw/openclaw:latest"./scripts/docker/setup.sh

docker load -i openclaw-image.tarexport OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"./scripts/docker/setup.sh --offline

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

# WhatsApp（二维码）docker compose run --rm openclaw-cli channels login # Telegramdocker compose run --rm openclaw-cli channels add --channel telegram --token "<token>" # Discorddocker compose run --rm openclaw-cli channels add --channel discord --token "<token>"

手动流程

BUILD_GIT_COMMIT="$(git rev-parse HEAD)"BUILD_TIMESTAMP="$(date -u +%Y-%m-%dT%H:%M:%SZ)"docker build \  --build-arg "GIT_COMMIT=${BUILD_GIT_COMMIT}" \  --build-arg "OPENCLAW_BUILD_TIMESTAMP=${BUILD_TIMESTAMP}" \  -t openclaw:local -f Dockerfile .docker compose run --rm --no-deps --entrypoint node openclaw-gateway \  dist/index.js onboard --mode local --no-install-daemondocker 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

Docker 构建上下文不包含 .git。请像上面所示，将源代码标识作为构建参数传入，使镜像的“关于”界面能够显示当前检出的提交和一个构建时间戳。scripts/docker/setup.sh 会自动解析并传递这两个值。

升级容器镜像

替换 OpenClaw 镜像但保留相同的挂载状态和配置后，新的 Gateway 网关会在就绪前运行可安全启动的升级迁移和插件收敛。常规镜像升级不应需要单独运行一次 openclaw doctor --fix。

如果无法在启动时安全完成这些修复，Gateway 网关会退出，而不会报告为健康状态。如果配置了重启策略，Docker、Podman 或 Kubernetes 可能会显示 Gateway 网关容器不断重启。请保留挂载的状态卷，然后使用与 Gateway 网关相同的状态和配置挂载，将 openclaw doctor --fix 作为容器命令，使用同一镜像运行一次：

docker run --rm -v <openclaw-state>:/home/node/.openclaw <image> openclaw doctor --fixpodman run --rm -v <openclaw-state>:/home/node/.openclaw <image> openclaw doctor --fix

Doctor 完成后，使用默认命令重新启动 Gateway 网关容器。在 Kubernetes 中，请在挂载同一 PVC 的一次性 Job 或调试 Pod 中运行相同命令，然后重新启动 Deployment 或 StatefulSet。

环境变量

scripts/docker/setup.sh 接受的可选变量（对于 Gateway 网关容器，docker-compose.yml 也直接接受这些变量）：

官方镜像不包含 Homebrew。在新手引导期间，如果 Linux 容器中没有 brew，OpenClaw 会隐藏仅支持 brew 的 Skills 依赖安装程序；请通过自定义镜像提供这些依赖项，或手动安装。对于 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_DOCKER_BUILD_NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_DOCKER_BUILD_TSDOWN_MAX_OLD_SPACE_MB=4096

包含选定插件的源代码构建镜像

OPENCLAW_EXTENSIONS 用于从源代码检出中选择插件清单 ID； 当源目录名称与 ID 不同时，也接受现有的源目录名称。Docker 构建会一次性将所选项解析为源目录，安装生产依赖，并且当所选插件以 openclaw.build.bundledDist: false 单独发布时，将其运行时编译到根级内置 dist 中。这种仅适用于 Docker 的打包方式不会改变插件的 npm 或 ClawHub 工件契约。未知、无效或有歧义的 ID 会导致镜像构建失败。 已知的仅依赖项/源代码 ID 会保持现有的源代码和依赖项 暂存方式，不会新增编译后的根级 dist 条目。具有 统一构建入口的所选插件必须成功编译；未选择的外部插件 源代码和运行时输出会被移除。

例如，以下命令会分别为 ClickClack、Slack 和 Microsoft Teams 构建独立的多架构 FakeCo Gateway 网关镜像。ClawRouter 已经是 OpenClaw 根运行时的一部分，因此 ClickClack 镜像仅选择 clickclack。显式传入空的浏览器参数，可使默认镜像不包含 Chromium：

SOURCE_SHA="$(git rev-parse HEAD)"BUILD_TIMESTAMP="$(date -u +%Y-%m-%dT%H:%M:%SZ)"REGISTRY="registry.example.com/fakeco" build_gateway_image() {  gateway="$1"  selected_plugin="$2"  docker buildx build \    --platform linux/amd64,linux/arm64 \    --build-arg "GIT_COMMIT=${SOURCE_SHA}" \    --build-arg "OPENCLAW_BUILD_TIMESTAMP=${BUILD_TIMESTAMP}" \    --build-arg "OPENCLAW_EXTENSIONS=${selected_plugin}" \    --build-arg OPENCLAW_INSTALL_BROWSER= \    --provenance=mode=max \    --sbom=true \    --tag "${REGISTRY}/openclaw-${gateway}:${SOURCE_SHA}" \    --push \    .} build_gateway_image clickclack clickclackbuild_gateway_image slack slackbuild_gateway_image teams msteams

对于单个原生本地构建，请使用 --platform linux/arm64 --load 或 --platform linux/amd64 --load。多平台输出以及附加的 SBOM/来源证明 需要使用镜像仓库，或其他能够保留证明材料的 Buildx 输出。推送后， 检查清单并部署不可变摘要，而不是可变的源 SHA 标签：

docker buildx imagetools inspect \  "${REGISTRY}/openclaw-clickclack:${SOURCE_SHA}"# 部署：registry.example.com/fakeco/openclaw-clickclack@sha256:<manifest-digest>

这些镜像适用于独立的基于 OCI 的 Gateway 网关和普通 Docker 用户。 由 Crabhelm 管理的 Gateway 网关不会使用这些镜像：该交付路径会构建一个 单独的 x86_64 设备归档，其中包含 OpenClaw npm tarball，并固定 Node、归档和清单摘要。请基于同一份已合入的 OpenClaw 源代码单独 构建该设备。

要针对打包镜像测试内置插件源代码，请将一个插件源目录挂载到其打包后的源路径上，例如 OPENCLAW_EXTRA_MOUNTS=/path/to/fork/extensions/synology-chat:/app/extensions/synology-chat:ro。这会覆盖同一插件 ID 对应的已编译 /app/dist/extensions/synology-chat 包。

可观测性

OpenTelemetry 导出是从 Gateway 网关容器向你的 OTLP 收集器发出的出站流量；无需发布 Docker 端口。要在本地构建的镜像中包含内置导出器：

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

官方预构建镜像已内置 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 插件，然后抓取：

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

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

健康检查

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

curl -fsS http://127.0.0.1:18789/healthz   # 存活状态curl -fsS http://127.0.0.1:18789/readyz     # 就绪状态

镜像内置的 HEALTHCHECK 会探测 /healthz；连续失败会将容器标记为 unhealthy，以便编排器重启或替换容器。

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

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

LAN 与 loopback

scripts/docker/setup.sh 默认设置 OPENCLAW_GATEWAY_BIND=lan，因此通过 Docker 端口发布，可从主机访问 http://127.0.0.1:18789。

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

主机本地提供商

在容器内部，127.0.0.1 指向容器本身，而不是主机。对于在主机上运行的提供商，请使用 host.docker.internal：

内置设置会将这些 URL 用作 LM Studio/Ollama 新手引导默认值，并且 docker-compose.yml 会在 Linux Docker Engine 上将 host.docker.internal 映射到主机 Gateway 网关（Docker Desktop 在 macOS/Windows 上提供相同的别名）。主机服务必须监听 Docker 能够访问的地址：

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

使用你自己的 Compose 文件或 docker run？请自行添加相同的映射，例如 --add-host=host.docker.internal:host-gateway。

Docker 中的 Claude CLI 后端

官方镜像不会预安装 Claude Code。请在容器的 node 用户下安装并登录，然后持久化该容器的主目录，以免镜像升级清除二进制文件或身份验证状态。

对于全新安装，请在运行设置之前启用持久化 /home/node 卷：

export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"export OPENCLAW_HOME_VOLUME="openclaw_home"./scripts/docker/setup.sh

对于现有安装，请先停止栈并重新加载当前 .env 值——设置脚本始终根据当前 shell 和默认值重写 .env，不会自行读取该文件：

set -a. ./.envset +aexport OPENCLAW_HOME_VOLUME="${OPENCLAW_HOME_VOLUME:-openclaw_home}"./scripts/docker/setup.sh

如果 .env 包含 shell 无法加载的值，请先手动重新导出你依赖的值（OPENCLAW_IMAGE、端口、绑定模式、自定义路径、OPENCLAW_EXTRA_MOUNTS、沙箱、跳过新手引导）。生成的叠加配置会为 openclaw-gateway 和 openclaw-cli 挂载主目录卷；请使用该叠加配置运行其余命令（如果你使用 docker-compose.override.yml，请先加入该文件）：

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  --entrypoint sh openclaw-cli -lc \  'curl -fsSL https://claude.ai/install.sh | bash'

原生安装程序会将 claude 写入 /home/node/.local/bin/claude。将 OpenClaw 指向该路径：

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  openclaw-cli config set \  agents.defaults.cliBackends.claude-cli.command \  /home/node/.local/bin/claude

使用同一个持久化主目录登录并验证：

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  --entrypoint /home/node/.local/bin/claude openclaw-cli auth logindocker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  --entrypoint /home/node/.local/bin/claude openclaw-cli auth status --textdocker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  openclaw-cli models auth login \  --provider anthropic --method cli --set-defaultdocker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  openclaw-cli models list --provider anthropic

然后使用内置的 claude-cli 后端：

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \  openclaw-cli agent \  --agent main \  --model claude-cli/claude-sonnet-4-6 \  --message "从 Docker Claude CLI 问好"

OPENCLAW_HOME_VOLUME 会持久化 /home/node/.local/bin 和 /home/node/.local/share/claude 下的原生安装，以及 /home/node/.claude 和 /home/node/.claude.json 下的 Claude Code 设置/身份验证信息。仅持久化 /home/node/.openclaw 并不足够；如果使用 OPENCLAW_EXTRA_MOUNTS 而不是主目录卷，请将所有这些 Claude 路径挂载到两个服务中。

Bonjour / mDNS

Docker 桥接网络通常无法可靠转发 Bonjour/mDNS 多播（224.0.0.251:5353）。当未设置 OPENCLAW_DISABLE_BONJOUR 时，内置 Bonjour 插件一旦检测到自身运行在容器中，就会自动禁用 LAN 广播，避免因桥接网络丢弃多播而不断重试并陷入崩溃循环。设置 OPENCLAW_DISABLE_BONJOUR=1 可无视检测结果强制关闭，设置为 0 可强制开启（仅适用于主机网络、macvlan 或其他已知支持 mDNS 多播的网络）。

对于 Docker 主机，请改用已发布的 Gateway 网关 URL、Tailscale 或广域 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

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

已安装的可下载插件会将包状态存储在已挂载的 OpenClaw 主目录下，因此安装记录和包根目录在容器被替换后仍会保留；Gateway 网关启动时不会重新生成内置插件的依赖树。

有关完整的虚拟机持久化详情，请参阅 Docker 虚拟机运行时——各项内容的持久化位置。

磁盘增长热点： media/、每个智能体的 SQLite 数据库、旧版会话 JSONL 记录、共享 SQLite 状态数据库、已安装插件的包根目录，以及 /tmp/openclaw/ 下的滚动文件日志。

Shell 辅助工具（可选）

要简化日常命令，请安装 ClawDock：

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

如果你之前是从旧的 scripts/shell-helpers/clawdock-helpers.sh 路径安装的，请重新运行上面的命令，使本地辅助脚本跟踪当前位置。然后使用 clawdock-start、clawdock-stop、clawdock-dashboard 等命令（运行 clawdock-help 查看完整列表）。

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

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

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

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>

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

FROM node:24-bookwormRUN curl -fsSL https://bun.sh/install | bashENV PATH="/root/.bun/bin:${PATH}"RUN corepack enableWORKDIR /appCOPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./COPY ui/package.json ./ui/package.jsonCOPY scripts ./scriptsRUN pnpm install --frozen-lockfileCOPY . .RUN pnpm buildRUN pnpm ui:installRUN pnpm ui:buildENV NODE_ENV=productionCMD ["node","dist/index.js"]

在 VPS 上运行？

有关共享 VM 部署步骤，包括二进制文件预装、持久化和更新，请参阅 Hetzner（Docker VPS）和 Docker VM 运行时。

智能体沙箱

通过 Docker 后端启用 agents.defaults.sandbox 后，Gateway 网关会在隔离的 Docker 容器内运行智能体工具（shell、文件读写等），而 Gateway 网关本身仍留在主机上——这为不受信任或多租户的智能体会话建立了一道坚固的隔离墙，同时无需将整个 Gateway 网关容器化。

沙箱范围可以是每个智能体（默认）、每个会话或共享；每个范围都有自己的工作区，并挂载到 /workspace。你还可以配置工具允许/拒绝策略、网络隔离、资源限制和浏览器容器。

有关完整配置、镜像、安全注意事项和多智能体配置文件，请参阅：

• 沙箱隔离 -- 完整沙箱参考
• OpenShell -- 以交互方式访问沙箱容器的 shell
• 多 Agent 沙盒和工具 -- 按智能体覆盖配置

快速启用

{  agents: {    defaults: {      sandbox: {        mode: "non-main", // 关闭 | 非主会话 | 全部        scope: "agent", // 会话 | 智能体 | 共享      },    },  },}

构建默认沙箱镜像（从源代码检出目录）：

scripts/sandbox-setup.sh

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

故障排查

docker compose run --rm openclaw-cli dashboard --no-opendocker compose run --rm openclaw-cli devices listdocker compose run --rm openclaw-cli devices approve <requestId>

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

相关内容

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