OpenClaw Linux 部署手册：常规安装、Docker 与 Docker Compose

标签： OpenClaw、Linux、Docker、Docker Compose、AI Agent、部署

OpenClaw 是 AI Agent Gateway，支持 CLI、常驻 Gateway、Control UI 和多渠道接入。Linux 是 官方推荐的生产部署平台，支持三种主流方式：

1. 常规安装 — curl 脚本 / npm 全局安装
2. Docker 部署 — 单容器或预构建镜像
3. 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
      - ${OPENCLAW_WORKSPACE_DIR:-~/.openclaw/workspace}:/home/node/.openclaw/workspace
    ports:
      - "${OPENCLAW_GATEWAY_PORT:-18789}:18789"
      - "${OPENCLAW_BRIDGE_PORT:-18790}:18790"
    restart: unless-stopped
    command:
      ["node", "dist/index.js", "gateway", "--bind", "lan", "--port", "18