OpenClaw从入门到应用——安装：Docker

米落枫 · 发表于昨天 07:41

作者：von Neumann
通过OpenClaw实现副业收入：《OpenClaw赚钱实录：从“养龙虾“到可持续变现的实践指南》
Docker 适合我吗？

是的

否

沙箱说明

不要求

本指南涵盖：

沙箱详情：沙箱
要求

容器化网关 (Docker Compose)

快速启动（推荐）

这里的 Docker 默认值假定使用绑定模式 (lan/loopback)，而不是主机别名。在 gateway.bind 中使用绑定模式值（例如 lan 或 loopback），而不是像 0.0.0.0 或 localhost 这样的主机别名。

从仓库根目录运行：

./docker-setup.sh

复制代码

此脚本将：

可选的环境变量：

完成后：

为 Docker 网关启用代理沙箱（选择加入）

docker-setup.sh 也可以为 Docker 部署引导 agents.defaults.sandbox.*。
启用方法：

exportOPENCLAW_SANDBOX=1
./docker-setup.sh

复制代码

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

exportOPENCLAW_SANDBOX=1exportOPENCLAW_DOCKER_SOCKET=/run/user/1000/docker.sock
./docker-setup.sh

复制代码

注意：

自动化/CI（非交互式，无 TTY 噪音）

对于脚本和 CI，使用 -T 禁用 Compose 伪终端分配：

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

复制代码

如果您的自动化没有导出 Claude 会话变量，现在它们在 docker-compose.yml 中默认保持未设置状态，将解析为空值，以避免重复的“变量未设置”警告。
共享网络安全说明（CLI + 网关）

openclaw-cli 使用 network_mode: "service:openclaw-gateway"，以便 CLI 命令可以可靠地通过 Docker 内的 127.0.0.1 访问网关。
将此视为一个共享的信任边界：回环绑定不是这两个容器之间的隔离。如果您需要更强的分离，请从单独的容器/主机网络路径运行命令，而不是使用捆绑的 openclaw-cli 服务。
为了在 CLI 进程被攻破时减少影响，compose 配置删除了 NET_RAW/NET_ADMIN 并在 openclaw-cli 上启用了 no-new-privileges。
它将配置/工作区写入主机：

在 VPS 上运行？请参阅 Hetzner (Docker VPS)。
使用远程镜像（跳过本地构建）

官方预构建镜像发布在：

使用镜像名称 ghcr.io/openclaw/openclaw（不要使用名称相似的 Docker Hub 镜像）。
常见标签：

基础镜像元数据

主 Docker 镜像当前使用：

docker 镜像现在发布 OCI 基础镜像注解（sha256 是示例，指向该标签的固定多架构清单列表）：

参考：OCI 镜像注解
发布上下文：此仓库的标记历史已在 v2026.2.22 及更早的 2026 标签（例如 v2026.2.21、v2026.2.9）中使用 Bookworm。
默认情况下，设置脚本从源代码构建镜像。要改为拉取预构建镜像，请在运行脚本前设置 OPENCLAW_IMAGE：

exportOPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./docker-setup.sh

复制代码

脚本检测到 OPENCLAW_IMAGE 不是默认的 openclaw:local，并运行 docker pull 而不是 docker build。其他所有操作（入门、网关启动、令牌生成）都以相同方式工作。
docker-setup.sh 仍然从仓库根目录运行，因为它使用本地的 docker-compose.yml 和辅助文件。OPENCLAW_IMAGE 跳过本地镜像构建时间；它不会取代 compose/设置工作流。
Shell 助手（可选）

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

mkdir-p ~/.clawdock &&curl-sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/shell-helpers/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.sh

复制代码

添加到您的 shell 配置 (zsh)：

echo'source ~/.clawdock/clawdock-helpers.sh'>> ~/.zshrc &&source ~/.zshrc

复制代码

然后使用 clawdock-start、clawdock-stop、clawdock-dashboard 等。运行 clawdock-help 查看所有命令。
有关详细信息，请参阅 ClawDock 助手自述文件。
手动流程（compose）

docker build -t openclaw:local -f Dockerfile .docker compose run --rm openclaw-cli onboard
docker compose up -d openclaw-gateway

复制代码

注意：从仓库根目录运行 docker compose ...。如果您启用了 OPENCLAW_EXTRA_MOUNTS 或 OPENCLAW_HOME_VOLUME，设置脚本会写入 docker-compose.extra.yml；在其他地方运行 Compose 时请包含它：

docker compose -f docker-compose.yml -f docker-compose.extra.yml

复制代码

控制 UI 令牌 + 配对（Docker）

如果您看到“未授权”或“已断开连接 (1008): 需要配对”，请获取新的仪表板链接并批准浏览器设备：

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

复制代码

更多详情：仪表板、设备。
额外挂载（可选）

如果您想将额外的主机目录挂载到容器中，请在运行 docker-setup.sh 之前设置 OPENCLAW_EXTRA_MOUNTS。它接受一个逗号分隔的 Docker 绑定挂载列表，并通过生成 docker-compose.extra.yml 将它们同时应用于 openclaw-gateway 和 openclaw-cli。
示例：

exportOPENCLAW_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro,$HOME/github:/home/node/github:rw"
./docker-setup.sh

复制代码

注意：

持久化整个容器的主目录（可选）

如果您希望 /home/node 在容器重新创建后仍然存在，请通过 OPENCLAW_HOME_VOLUME 设置一个命名卷。这将创建一个 Docker 卷并将其挂载到 /home/node，同时保留标准的配置/工作区绑定挂载。此处使用命名卷（而不是绑定路径）；对于绑定挂载，请使用 OPENCLAW_EXTRA_MOUNTS。
示例：

exportOPENCLAW_HOME_VOLUME="openclaw_home"
./docker-setup.sh

复制代码

您可以将其与额外挂载结合使用：

exportOPENCLAW_HOME_VOLUME="openclaw_home"exportOPENCLAW_EXTRA_MOUNTS="$HOME/.codex:/home/node/.codex:ro,$HOME/github:/home/node/github:rw"
./docker-setup.sh

复制代码

注意：

安装额外的 apt 软件包（可选）

如果您在镜像中需要系统软件包（例如，构建工具或媒体库），请在运行 docker-setup.sh 之前设置 OPENCLAW_DOCKER_APT_PACKAGES。这会在镜像构建期间安装这些软件包，因此即使容器被删除，它们也会保留。
示例：

exportOPENCLAW_DOCKER_APT_PACKAGES="ffmpeg build-essential"
./docker-setup.sh

复制代码

注意：

预安装扩展依赖项（可选）

具有自己 package.json 的扩展（例如 diagnostics-otel、matrix、msteams）会在首次加载时安装它们的 npm 依赖项。要将这些依赖项预先构建到镜像中，请在运行 docker-setup.sh 之前设置 OPENCLAW_EXTENSIONS：

exportOPENCLAW_EXTENSIONS="diagnostics-otel matrix"
./docker-setup.sh

复制代码

或者直接构建时：

docker build --build-arg OPENCLAW_EXTENSIONS="diagnostics-otel matrix".

复制代码

注意：

高级用户/功能齐全的容器（选择加入）

默认的 Docker 镜像是安全优先的，以非 root 用户 node 运行。这保持了较小的攻击面，但意味着：

如果您想要一个功能更齐全的容器，请使用这些选择加入的选项：

持久化 /home/node

exportOPENCLAW_HOME_VOLUME="openclaw_home"
./docker-setup.sh

复制代码

将系统依赖项内置到镜像中

exportOPENCLAW_DOCKER_APT_PACKAGES="git curl jq"
./docker-setup.sh

复制代码

无需 npx 安装 Playwright 浏览器

docker compose run --rm openclaw-cli \node /app/node_modules/playwright-core/cli.js install chromium

复制代码

如果您需要 Playwright 安装系统依赖项，请使用 OPENCLAW_DOCKER_APT_PACKAGES 重建镜像，而不是在运行时使用 --with-deps。

持久化 Playwright 浏览器下载

权限 + EACCES

镜像以 node 用户（uid 1000）运行。如果您在 /home/node/.openclaw 上看到权限错误，请确保您的主机绑定挂载由 uid 1000 拥有。
示例（Linux 主机）：

sudochown-R1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace

复制代码

如果您为了方便而选择以 root 身份运行，则需接受相应的安全权衡。
更快的重建（推荐）

为了加快重建速度，请安排您的 Dockerfile 顺序，以便缓存依赖层。这可以避免重新运行 pnpm install，除非锁文件发生更改：

FROM node:24-bookworm
# 安装 Bun（构建脚本所需）
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"]

复制代码

渠道设置（可选）

使用 CLI 容器配置渠道，然后根据需要重启网关。
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、Telegram、Discord
OpenAI Codex OAuth（无头 Docker）

如果您在向导中选择 OpenAI Codex OAuth，它会打开一个浏览器 URL 并尝试捕获 http://127.0.0.1:1455/auth/callback 上的回调。在 Docker 或无头设置中，该回调可能会显示浏览器错误。将您进入的完整重定向 URL 复制并粘贴回向导中以完成身份验证。
健康检查

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

curl-fsS http://127.0.0.1:18789/healthz
curl-fsS http://127.0.0.1:18789/readyz

复制代码

别名：/health 和 /ready。
/healthz 是一个浅层的存活探针，用于检测“网关进程是否正在运行”。
/readyz 在启动宽限期内保持就绪状态，然后仅在必需的托管渠道在宽限期后仍未连接或稍后断开连接时才变为 503。
Docker 镜像包含一个内置的 HEALTHCHECK，它在后台 ping /healthz。简单来说：Docker 会持续检查 OpenClaw 是否仍有响应。如果检查持续失败，Docker 会将容器标记为 unhealthy，编排系统（Docker Compose 重启策略、Swarm、Kubernetes 等）可以自动重启或替换它。
经过身份验证的深度健康快照（网关 + 渠道）：

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

复制代码

E2E 冒烟测试（Docker）

scripts/e2e/onboard-docker.sh

复制代码

QR 导入冒烟测试（Docker）

pnpm test:docker:qr

复制代码

LAN 与回环（Docker Compose）

docker-setup.sh 默认 OPENCLAW_GATEWAY_BIND=lan，以便主机访问 http://127.0.0.1:18789 能够与 Docker 端口发布配合使用。

设置脚本还在入门后固定 gateway.mode=local，以便 Docker CLI 命令默认以本地回环为目标。
遗留配置说明：在 gateway.bind 中使用绑定模式值（lan / loopback / custom / tailnet / auto），而不是主机别名（0.0.0.0、127.0.0.1、localhost、::、::1）。
如果您从 Docker CLI 命令中看到 Gateway target: ws://172.x.x.x:18789 或重复出现的 pairing required 错误，请运行：

docker compose run --rm openclaw-cli config set gateway.mode localdocker 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

复制代码

注意事项

存储模型

持久化主机数据：

临时沙箱 tmpfs：

磁盘增长热点：

代理沙箱（主机网关 + Docker 工具）

深入了解：沙箱
它的作用

当启用 agents.defaults.sandbox 时，非主会话将在 Docker 容器内运行工具。网关保留在您的主机上，但工具执行是隔离的：

警告：scope: "shared" 会禁用跨会话隔离。所有会话共享一个容器和一个工作区。
按代理的沙箱配置文件（多代理）

如果您使用多代理路由，每个代理可以覆盖沙箱和工具设置：agents.list[].sandbox 和 agents.list[].tools（加上 agents.list[].tools.sandbox.tools）。这允许您在一个网关中运行混合访问级别：

有关示例、优先级和故障排除，请参阅多代理沙箱和工具。
默认行为

网络：默认 none（如果需要出站流量，显式选择加入）
默认允许：exec、process、read、write、edit、sessions_list、sessions_history、sessions_send、sessions_spawn、session_status默认拒绝：browser、canvas、nodes、cron、discord、gateway

启用沙箱

如果您计划在 setupCommand 中安装软件包，请注意：

最近使用过

{
agents: {
defaults: {
sandbox: {
mode: "non-main", // off | non-main | all
scope: "agent", // session | agent | shared (agent 是默认值)
workspaceAccess: "none", // none | ro | rw
workspaceRoot: "~/.openclaw/sandboxes",
docker: {
image: "openclaw-sandbox:bookworm-slim",
workdir: "/workspace",
readOnlyRoot: true,
tmpfs: ["/tmp", "/var/tmp", "/run"],
network: "none",
user: "1000:1000",
capDrop: ["ALL"],
env: { LANG: "C.UTF-8" },
setupCommand: "apt-get update && apt-get install -y git curl jq",
pidsLimit: 256,
memory: "1g",
memorySwap: "2g",
cpus: 1,
ulimits: {
nofile: { soft: 1024, hard: 2048 },
nproc: 256,
},
seccompProfile: "/path/to/seccomp.json",
apparmorProfile: "openclaw-sandbox",
dns: ["1.1.1.1", "8.8.8.8"],
extraHosts: ["internal.service:10.0.0.5"],
},
prune: {
idleHours: 24, // 0 禁用空闲清理
maxAgeDays: 7, // 0 禁用最大存在时间清理
},
},
},
},
tools: {
sandbox: {
tools: {
allow: [
"exec",
"process",
"read",
"write",
"edit",
"sessions_list",
"sessions_history",
"sessions_send",
"sessions_spawn",
"session_status",
],
deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"],
},
},
},
}

复制代码

加固选项位于 agents.defaults.sandbox.docker 下：
network、user、pidsLimit、memory、memorySwap、cpus、ulimits、
seccompProfile、apparmorProfile、dns、extraHosts、
dangerouslyAllowContainerNamespaceJoin（仅限紧急使用）。
多代理：通过 agents.list[].sandbox.{docker,browser,prune}.* 覆盖每个代理的 agents.defaults.sandbox.{docker,browser,prune}.*
（当 agents.defaults.sandbox.scope / agents.list[].sandbox.scope 为 "shared" 时忽略）。
构建默认沙箱镜像

scripts/sandbox-setup.sh

复制代码

这将使用 Dockerfile.sandbox 构建 openclaw-sandbox:bookworm-slim。
沙箱通用镜像（可选）

如果您想要一个包含常见构建工具（Node、Go、Rust 等）的沙箱镜像，请构建通用镜像：

scripts/sandbox-common-setup.sh

复制代码

这将构建 openclaw-sandbox-common:bookworm-slim。要使用它：

{
agents: {
defaults: {
sandbox: { docker: { image: "openclaw-sandbox-common:bookworm-slim" } },
},
},
}

复制代码

沙箱浏览器镜像

要在沙箱内运行浏览器工具，请构建浏览器镜像：

scripts/sandbox-browser-setup.sh

复制代码

这将使用 Dockerfile.sandbox-browser 构建 openclaw-sandbox-browser:bookworm-slim。容器运行启用了 CDP 的 Chromium 和一个可选的 noVNC 观察器（通过 Xvfb 实现有头模式）。
注意：

浏览器容器启动默认值对于共享/容器工作负载来说是保守的，包括：

默认值在捆绑的镜像中默认应用。如果您需要不同的 Chromium 标志，请使用自定义浏览器镜像并提供您自己的入口点。
使用配置：

{
agents: {
defaults: {
sandbox: {
browser: { enabled: true },
},
},
},
}

复制代码

自定义浏览器镜像：

{
agents: {
defaults: {
sandbox: { browser: { image: "my-openclaw-browser" } },
},
},
}

复制代码

启用后，代理将接收：

请记住：如果您对工具使用允许列表，请添加 browser（并将其从拒绝列表中移除），否则该工具仍会被阻止。
清理规则（agents.defaults.sandbox.prune）也适用于浏览器容器。
自定义沙箱镜像

构建您自己的镜像并将配置指向它：

docker build -t my-openclaw-sbx -f Dockerfile.sandbox .

复制代码

{
agents: {
defaults: {
sandbox: { docker: { image: "my-openclaw-sbx" } },
},
},
}

复制代码

工具策略（允许/拒绝）

清理策略

两个控制旋钮：

示例：

安全说明

工具

会破坏隔离

故障排除

原文地址：https://blog.csdn.net/hy592070616/article/details/159514267

25位大厂高管转战生成式AI创业！吸金猛，不

OpenClaw从入门到应用——安装：Docker

浏览过的版块

优雅地在Windows下安装Openclaw

关于我们

产品与服务

解决方案

产品与服务