常规安装 — curl 脚本 / npm 全局安装
Docker 部署 — 单容器或预构建镜像
Docker Compose 部署 — 官方推荐的生产方式
本文按上述三种方式分别说明，含验收命令与常见问题。

一、系统要求
项目 要求
操作系统 Ubuntu 20.04+、Debian 11+、CentOS/RHEL 等主流 Linux
Node.js（常规安装） 24（推荐）或 22.19+
Docker（容器部署） Docker Engine + Compose v2
内存 常规安装 ≥ 1 GB；Docker 本地构建镜像 ≥ 2 GB
磁盘 预留镜像、日志、配置目录空间
默认端口：

Gateway：18789
Bridge：18790
二、方式一：常规安装
2.1 一键安装脚本（推荐）
curl -fsSL https://openclaw.ai/install.sh | bash
跳过 onboarding：

curl -fsSL https://openclaw.ai/install.sh | bash -s – --no-onboard
2.2 本地 prefix 安装（不依赖系统 Node）
curl -fsSL https://openclaw.ai/install-cli.sh | bash
OpenClaw 和 Node 安装在 ~/.openclaw 前缀下。

2.3 npm / pnpm / bun 全局安装

npm

npm install -g openclaw@latest
openclaw onboard --install-daemon

pnpm

pnpm add -g openclaw@latest
pnpm approve-builds -g
openclaw onboard --install-daemon

bun

bun add -g openclaw@latest
openclaw onboard --install-daemon
2.4 配置与守护进程
openclaw onboard --install-daemon
Linux/WSL2 会创建 systemd user service，实现 Gateway 开机自启。

2.5 验证
openclaw --version
openclaw doctor
openclaw gateway status
curl -fsS http://127.0.0.1:18789/healthz
浏览器打开 http://127.0.0.1:18789/，在 Settings 粘贴 Gateway Token。

2.6 从源码安装
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install && pnpm build && pnpm ui:build
pnpm link --global
openclaw onboard --install-daemon
三、方式二：Docker 部署
适合 不想污染宿主机环境 或 VPS 隔离运行 的场景。

3.1 前置条件

确认 Docker 与 Compose v2

docker --version
docker compose version
3.2 使用官方 setup 脚本（推荐）
克隆仓库后执行：

git clone https://github.com/openclaw/openclaw.git
cd openclaw
./scripts/docker/setup.sh
使用 预构建镜像（小内存 VPS 推荐，避免 OOM）：

export OPENCLAW_IMAGE=“ghcr.io/openclaw/openclaw:latest”
./scripts/docker/setup.sh
脚本会自动：

构建或拉取镜像
交互式 onboarding（API Key 等）
生成 .env 和 Gateway Token
通过 Docker Compose 启动 Gateway
3.3 手动 Docker 流程
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
3.4 打开 Control UI
http://127.0.0.1:18789/
获取 dashboard 链接：

docker compose run --rm openclaw-cli dashboard --no-open
3.5 健康检查
curl -fsS http://127.0.0.1:18789/healthz # liveness
curl -fsS http://127.0.0.1:18789/readyz # readiness
四、方式三：Docker Compose 部署（生产推荐）
官方 docker-compose.yml 包含两个服务：

服务 作用
openclaw-gateway 常驻 Gateway，对外暴露 18789/18790
openclaw-cli 一次性 CLI 容器，执行管理命令
4.1 标准 Compose 结构
services:
openclaw-gateway:
image: ${OPENCLAW_IMAGE:-openclaw:local}
environment:
HOME: /home/node
OPENCLAW_GATEWAY_TOKEN: ${OPENCLAW_GATEWAY_TOKEN}
volumes:
- ${OPENCLAW_CONFIG_DIR:-~/.openclaw}:/home/node/.openclaw
- $OPENCLA{W}_{W}ORKSPAC{E}_{D}IR:-/.openclaw/workspace:/home/node/.openclaw/workspaceports:-"${OPENCLAW_GATEWAY_PORT:-18789}:18789"
- “${OPENCLAW_BRIDGE_PORT:-18790}:18790”
restart: unless-stopped
command:
[“node”, “dist/index.js”, “gateway”, “–bind”, “lan”, “–port”, “18789”]

openclaw-cli:
image: ${OPENCLAW_IMAGE:-openclaw:local}
network_mode: “service:openclaw-gateway”
volumes:
- ${OPENCLAW_CONFIG_DIR:-~/.openclaw}:/home/node/.openclaw
- ${OPENCLAW_WORKSPACE_DIR:-~/.openclaw/workspace}:/home/node/.openclaw/workspace
entrypoint: [“node”, “dist/index.js”]
完整文件以官方仓库 docker-compose.yml 为准。

4.2 一键启动（setup 脚本）
cd openclaw
export OPENCLAW_IMAGE=“ghcr.io/openclaw/openclaw:latest”
./scripts/docker/setup.sh
4.3 常用 Compose 命令

启动 Gateway

docker compose up -d openclaw-gateway

查看日志

docker compose logs -f openclaw-gateway

停止

docker compose down

CLI：添加 Telegram 渠道

docker compose run --rm openclaw-cli channels add --channel telegram --token “”

CLI：WhatsApp 扫码登录

docker compose run --rm openclaw-cli channels login

设备审批

docker compose run --rm openclaw-cli devices list
docker compose run --rm openclaw-cli devices approve
4.4 环境变量（常用）
变量 用途
OPENCLAW_IMAGE 使用远程预构建镜像
OPENCLAW_GATEWAY_TOKEN Gateway 认证 Token
OPENCLAW_CONFIG_DIR 配置目录挂载路径
OPENCLAW_WORKSPACE_DIR 工作区挂载路径
OPENCLAW_SANDBOX 启用 Agent Sandbox（1/true）
OPENCLAW_SKIP_ONBOARDING 跳过交互式 onboarding
4.5 持久化目录
容器 bind-mount 以下路径，替换容器后数据保留：

~/.openclaw — 配置、openclaw.json、.env
~/.openclaw/workspace — Agent 工作区
权限注意： 容器以 uid 1000（node）运行，宿主机挂载目录需：

sudo chown -R 1000:1000 ~/.openclaw
4.6 启用 Agent Sandbox
export OPENCLAW_SANDBOX=1
./scripts/docker/setup.sh
Sandbox 在独立 Docker 容器中执行 Agent 工具，Gateway 仍在宿主机/主容器中运行。

五、三种方式对比
维度 常规安装 Docker Docker Compose
上手速度 ★★★ 最快 ★★ ★★
环境隔离 低 高 高
适合场景 个人本机/dev 单容器验证 VPS/生产
依赖 Node.js Docker Engine Docker + Compose v2
升级 openclaw update 拉取新镜像 compose pull + up
六、常见问题
1）构建镜像 OOM（exit 137）
1 GB 内存 VPS 构建会失败。改用预构建镜像：

export OPENCLAW_IMAGE=“ghcr.io/openclaw/openclaw:latest”
./scripts/docker/setup.sh
2）EACCES 权限错误
sudo chown -R 1000:1000 ~/.openclaw
3）Gateway 重启循环
检查 gateway.bind 是否使用了 lan 或 loopback，不要写 0.0.0.0 作为 bind 值。

4）Docker 内访问宿主机 Ollama/LM Studio
容器内用 host.docker.internal 替代 127.0.0.1：

Provider Docker 内 URL
Ollama http://host.docker.internal:11434
LM Studio http://host.docker.internal:1234
宿主机服务需监听 0.0.0.0。

5）openclaw 命令找不到（常规安装）
export PATH=“$(npmprefix-g)/bin:$PATH”
echo ‘export PATH=“$(npmprefix-g)/bin:$PATH”’ >> ~/.bashrc
七、结语
Linux 部署 OpenClaw 的推荐路径：

本机开发 → curl install.sh 或 npm 全局安装
VPS/生产 → Docker Compose + 预构建 GHCR 镜像
安全隔离 → 启用 OPENCLAW_SANDBOX