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", "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 "<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 <requestId>

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="$(npm prefix -g)/bin:$PATH"
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.bashrc

---

七、结语

Linux 部署 OpenClaw 的推荐路径：

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

官方文档：https://docs.openclaw.ai/install

---

如果这篇文章对你有帮助，欢迎点赞、收藏、关注，有问题可以在评论区交流。