Docker 部署 OpenClaw：从安装到日常使用的完整指南

OpenClaw 是一个开源、自托管的个人 AI 助手框架，可以接入模型、消息渠道、浏览器控制、自动化任务和自定义技能。相比直接在宿主机安装，Docker 部署最大的好处是环境隔离、迁移方便、升级可控，尤其适合 VPS、家用服务器、NAS、实验环境，或者你想把 OpenClaw 跑在一个更容易清理和重建的容器里。

根据 OpenClaw 官方文档，Docker 并不是唯一安装方式，但如果你希望运行一个容器化 Gateway，或者想验证 Docker 流程，它是很合适的选择。官方 Docker 文档也提醒：至少准备 Docker Engine 或 Docker Desktop、Docker Compose v2、足够磁盘空间，以及建议 2GB 以上内存。

参考来源：

一、为什么选择 Docker 部署 OpenClaw

Docker 部署 OpenClaw 主要有几个优势。

第一，环境更干净。OpenClaw 依赖 Node.js、包管理器、构建产物和运行配置。使用 Docker 后，这些依赖都被封装在镜像或容器中，不会污染宿主机环境。

第二，迁移更简单。只要保留配置目录、工作区目录和 .env 文件，就可以比较容易地把服务迁移到另一台机器。

第三，更新和回滚更可控。你可以使用固定版本镜像，例如 ghcr.io/openclaw/openclaw:<version>，而不是永远追 latest。

第四，更适合服务器场景。OpenClaw Gateway 可以作为长期运行的服务，通过 Docker Compose 配置自动重启、健康检查、端口映射和持久化目录。

二、部署前准备

建议准备以下环境：

bash 复制代码

docker --version
docker compose version
git --version

服务器建议配置：

text 复制代码

CPU：2 核以上
内存：至少 2GB，推荐 4GB+
磁盘：至少预留数 GB，用于镜像、日志、配置和工作区
系统：Linux VPS、macOS、Windows WSL2 或支持 Docker 的 NAS

如果部署在公网 VPS 上，要格外注意安全。OpenClaw 具备自动化和工具调用能力，不建议裸露在公网中。更推荐使用反向代理、访问控制、VPN、Tailscale、SSH Tunnel，或者至少设置强 token 和防火墙规则。

三、方式一：使用官方 Docker Setup 脚本

官方推荐的 Docker 流程是从 OpenClaw 仓库根目录运行 setup 脚本。

先克隆仓库：

bash 复制代码

git clone https://github.com/openclaw/openclaw.git
cd openclaw

如果你希望本地构建镜像，直接运行：

bash 复制代码

./scripts/docker/setup.sh

如果你希望使用官方预构建镜像，可以先指定镜像：

bash 复制代码

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

脚本会完成几件事：

text 复制代码

1. 构建或拉取 OpenClaw Docker 镜像
2. 引导你完成 onboarding 配置
3. 生成 Gateway token 并写入 .env
4. 通过 Docker Compose 启动 openclaw-gateway

启动完成后，访问：

text 复制代码

http://127.0.0.1:18789/

进入页面后，根据提示填写共享密钥或 token。默认情况下，setup 脚本会把 token 写入 .env。

如果忘记 dashboard 地址，可以运行：

bash 复制代码

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

四、方式二：手动 Docker Compose 部署

如果你想自己控制每一步，可以使用 Docker Compose。

官方 Compose 文件中主要包含两个服务：

text 复制代码

openclaw-gateway：实际运行 Gateway
openclaw-cli：用于执行配置、渠道登录、健康检查等 CLI 操作

常见启动方式：

bash 复制代码

docker compose up -d openclaw-gateway

查看容器状态：

bash 复制代码

docker compose ps

查看日志：

bash 复制代码

docker compose logs -f openclaw-gateway

停止服务：

bash 复制代码

docker compose down

重启服务：

bash 复制代码

docker compose restart openclaw-gateway

五、常用环境变量

官方 Docker 流程支持一些常见环境变量：

bash 复制代码

export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
export OPENCLAW_GATEWAY_PORT="18789"
export OPENCLAW_BRIDGE_PORT="18790"
export OPENCLAW_TZ="Asia/Shanghai"

如果你希望挂载额外目录，可以使用：

bash 复制代码

export OPENCLAW_EXTRA_MOUNTS="/host/path:/container/path"

如果希望持久化 /home/node：

bash 复制代码

export OPENCLAW_HOME_VOLUME="openclaw_home"

如果要启用 Docker 沙箱能力：

bash 复制代码

export OPENCLAW_SANDBOX=1

然后重新运行：

bash 复制代码

./scripts/docker/setup.sh

六、持久化目录说明

Docker 部署时，一定要关注数据持久化。OpenClaw 的配置、凭据、工作区和 token 不应该只存在容器内部，否则容器重建后会丢失。

官方 Compose 流程会把配置目录挂载到：

text 复制代码

/home/node/.openclaw

其中常见文件包括：

text 复制代码

openclaw.json
.env
agents/<agentId>/agent/auth-profiles.json
workspace/

如果遇到权限问题，可以检查宿主机目录所有者。官方文档中提到，镜像默认以 node 用户运行，uid 通常是 1000。可以按需调整：

bash 复制代码

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

七、初始化和模型配置

首次运行时，OpenClaw 会进入 onboarding 流程。你通常需要配置：

text 复制代码

模型服务商 API Key
Gateway token 或访问密码
默认 Agent 设置
是否启用沙箱
消息渠道

模型服务商可以根据你的使用习惯选择，例如 OpenAI、Anthropic、OpenRouter、Google Gemini，或者本地模型服务。Docker 部署本身并不限制模型来源，关键是容器能访问到对应 API 或本地模型地址。

如果模型服务跑在宿主机上，例如 Ollama、LM Studio 或其他本地服务，要注意容器访问宿主机的地址。在 Docker Desktop 环境中常见写法是：

text 复制代码

http://host.docker.internal:11434

Linux 上可能需要额外配置 host gateway，或者直接使用宿主机局域网 IP。

八、添加消息渠道

OpenClaw 可以接入不同消息渠道。Docker 部署时，建议使用 openclaw-cli 容器执行相关命令。

WhatsApp 登录：

bash 复制代码

docker compose run --rm openclaw-cli channels login

Telegram：

bash 复制代码

docker compose run --rm openclaw-cli channels add --channel telegram --token "<你的 Telegram Bot Token>"

Discord：

bash 复制代码

docker compose run --rm openclaw-cli channels add --channel discord --token "<你的 Discord Bot Token>"

这些命令会把凭据写入持久化配置目录，因此容器重启后仍然可用。

九、健康检查和运行状态

OpenClaw Gateway 提供健康检查端点：

bash 复制代码

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

如果返回正常，说明 Gateway 至少处于可访问状态。

也可以运行更深层的健康检查：

bash 复制代码

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

查看实时日志：

bash 复制代码

docker compose logs -f openclaw-gateway

如果容器不断重启，优先检查：

text 复制代码

.env 是否存在
token 是否正确
端口是否被占用
配置目录权限是否正确
内存是否不足
Docker Compose 版本是否过旧

十、更新 OpenClaw

如果使用预构建镜像，更新流程一般是：

bash 复制代码

docker compose pull
docker compose up -d

如果你是从源码构建镜像：

bash 复制代码

git pull
./scripts/docker/setup.sh
docker compose up -d

生产环境建议固定版本，而不是一直使用 latest。例如：

bash 复制代码

export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:2026.4.14"

这样升级时更可控，出现问题也方便回滚。

十一、安全建议

OpenClaw 是一个具备自动化能力的 AI 助手，不应该把它当作普通网页应用随意暴露。

建议至少做到：

text 复制代码

不要无鉴权暴露到公网
使用强 token 或密码
通过 VPN、Tailscale 或 SSH Tunnel 访问
限制防火墙入站端口
定期更新镜像
不要给 Agent 不必要的系统权限
对群聊、外部渠道或多人场景启用沙箱
谨慎安装第三方技能
定期备份配置目录

如果启用沙箱，可以将非主会话或多用户场景隔离到 Docker 容器中，降低工具调用对宿主机的影响。

十二、常见问题

1. 页面打不开

先确认容器是否运行：

bash 复制代码

docker compose ps

再看端口：

bash 复制代码

docker compose logs -f openclaw-gateway

默认访问地址是：

text 复制代码

http://127.0.0.1:18789/

如果你改过 OPENCLAW_GATEWAY_PORT，访问端口也要同步变化。

2. 提示 Unauthorized

通常是 token 或访问密钥不一致。检查 .env 中的 OPENCLAW_GATEWAY_TOKEN，然后重新获取 dashboard 地址：

bash 复制代码

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

3. 配置无法保存

大概率是挂载目录权限问题。检查宿主机配置目录是否可由 uid 1000 写入。

bash 复制代码

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

4. 构建时内存不足

如果构建过程中出现 exit 137，通常是内存不足。可以换更大机器、增加 swap，或者直接使用预构建镜像：

bash 复制代码

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

结语

Docker 是部署 OpenClaw 的一种稳妥方式。它牺牲了一点点初始配置复杂度，换来了隔离、可迁移、易维护和更适合服务器长期运行的部署形态。

如果只是本机快速体验，直接安装 OpenClaw 可能更快；如果你打算把它长期跑在 VPS、NAS、家庭服务器或团队环境中，Docker Compose 会是更清晰、更可靠的选择。