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； 当现有源目录名称不同时，也接受这些名称。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"

局域网与 local loopback

scripts/docker/setup.sh 默认使用 OPENCLAW_GATEWAY_BIND=lan，因此主机上的 http://127.0.0.1:18789 可与 Docker 端口发布配合使用。

• 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 镜像在 PATH 中包含 /home/node/.local/bin，因此内置的 Anthropic 插件无需覆盖适配器配置即可解析它。

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

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 插件一旦检测到自己正在容器中运行，就会自动禁用局域网广播，因此不会因反复尝试桥接网络丢弃的多播而陷入崩溃循环。设置 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：行为配置
• agents/<agentId>/agent/auth-profiles.json：存储的提供商 OAuth/API 密钥身份验证
• .env：由环境变量提供的运行时密钥，例如 OPENCLAW_GATEWAY_TOKEN

身份验证配置文件密钥目录存储用于 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 网关配置