【OpenClaw -01】OpenClaw 安装部署指南：npm、Docker 与源码三种模式详解

OpenClaw 安装部署指南：npm、Docker 与源码三种模式详解

在生产环境部署 AI Agent 网关，选择合适的交付模式远比单纯的"能跑起来"更重要。本文从资源隔离性、运维复杂度、安全边界三个维度，深度解析 OpenClaw 的三种官方部署方案。

一、环境要求与前置检查

在正式部署前，需要确认目标机器满足以下基线配置。OpenClaw 采用 Node.js 运行时架构，网关进程本身轻量，但沙箱执行环境与向量内存操作对资源有特定要求。

1.1 基础硬件配置

部署场景	CPU	内存	存储	网络
开发测试	4核+	2GB（最低） 4GB（建议）	20GB SSD	出站 443 端口开放
生产单节点	6核+	8GB~16GB	100GB+ NVMe	稳定公网/IP白名单
高可用集群	8核+	32GB	持久化卷（PVC）	内网 10Gbps+

关键提示：若启用浏览器自动化（Playwright）或本地模型推理（Ollama/Llama.cpp），内存需求需额外增加 4GB~8GB 缓冲。

1.2 软件依赖清单

Node.js：版本 22.x LTS（强制要求，V8 引擎特性依赖）
包管理器：npm 10+ 或 pnpm 8+
容器运行时（Docker 方案）：Docker Engine 24+ 或 Docker Desktop 4.25+
可选组件：FFmpeg（语音处理）、Chromium（浏览器自动化）

执行前置检查命令：

bash 复制代码

# 验证 Node 版本
node -v  # 需输出 v22.x.x

# 验证 ulimit（Docker 方案需关注）
ulimit -n  # 建议 > 65535，避免高并发句柄耗尽

二、部署方案选型决策树

OpenClaw 提供三种官方支持的部署路径，分别对应不同的运维哲学：

md 复制代码

+---------------------------------------------------+
|               OpenClaw 部署选型决策               |
+---------------------------------------------------+
                          |
          +---------------+---------------+
          |                               |
   追求极简快速？                  需要长期运维？
          |                               |
    一键脚本安装                   Docker 部署
   (install.sh)                   (Compose)
          |                               |
   +------+------+            +-----------+-----------+
   |             |            |                       |
本地开发    快速验证     全容器化模式      Host+Sandbox 混合模式
(npm)       (npm)       (推荐生产)           (进阶隔离)

选型建议：

个人开发者/本地调试：npm 全局安装，热重载友好，调试信息完整
中小团队生产环境：Docker Compose 全容器化，一次构建，多环境一致
金融/医疗等高敏感场景：Host Gateway + Sandbox 容器混合模式，实现网关与执行环境的强隔离

三、方案一：一键脚本安装（极速体验）

官方提供的自动化脚本适用于绝大多数 Linux 发行版（Ubuntu 22.04/Debian 12/RHEL 9），封装了 Node 环境检测、依赖安装与初始化引导。

3.1 执行流程拆解

脚本执行逻辑并非简单的"下载-解压"，而是包含环境探测与自适应修复：

bash 复制代码

curl -fsSL https://openclaw.ai/install.sh | bash

脚本内部执行阶段：

md 复制代码

+----------------+
|  阶段1: 环境探测  |
|  - 检查 Node 版本 |
|  - 检测包管理器   |
|  - 验证权限      |
+--------+-------+
         |
         v
+--------+-------+
|  阶段2: 依赖安装  |
|  - 若缺 Node 22 |
|    自动调用 n 或  |
|    nvm 安装     |
+--------+-------+
         |
         v
+--------+-------+
|  阶段3: 二进制安装 |
|  - npm install  |
|  - 生成 CLI 包装器|
+--------+-------+
         |
         v
+--------+-------+
|  阶段4: 初始化引导 |
|  - 提示 onboard  |
|  - 创建 systemd   |
|    服务（可选）   |
+----------------+

3.2 安装后验证

bash 复制代码

# 检查 CLI 可用性
openclaw --version

# 查看网关守护进程状态（若启用）
systemctl status openclaw-gateway

版本升级策略：

OpenClaw 采用语义化版本（Semver），但注意 0.x 版本期间可能存在破坏性变更。生产环境建议锁定 minor 版本：

bash 复制代码

# 安全升级（仅 patch 版本）
npm update -g openclaw

# 大版本迁移（需查阅 Migration Guide）
npm install -g openclaw@0.4.0

4.2 进程保活配置

npm 模式默认前台运行，生产环境需配合进程管理器：

PM2 方案（推荐）：

bash 复制代码

npm install -g pm2
pm2 start "openclaw gateway" --name openclaw-gw
pm2 startup
pm2 save

Systemd 方案：

手动创建服务单元文件 /etc/systemd/system/openclaw.service，指定 User 与 WorkingDirectory，避免 root 运行风险。

五、方案三：Docker Compose 部署（生产级）

Docker 方案是生产环境的首选，核心优势在于环境一致性与安全沙箱的原生支持。官方提供两种 Compose 配置模式，对应不同的隔离级别。

5.1 架构模式对比

模式 A：全容器化（Full Containerization）

所有组件（Gateway、CLI、Sandbox）运行于容器网络内部。

md 复制代码

+--------------------------------------------------+
|                   Docker Host                    |
|  +---------------------------------------------+ |
|  |           Docker Network: openclaw          | |
|  |  +----------------+    +------------------+ | |
|  |  | openclaw-cli   |    | openclaw-gateway | | |
|  |  | (配置管理)      |    | (核心网关)        | | |
|  |  +----------------+    +------------------+ | |
|  |           |                    |            | |
|  |           v                    v            | |
|  |  +----------------------------------------+ | |
|  |  |   Sandbox 容器（代码执行隔离）            | | |
|  |  |   - 无网络访问（可选）                    | | |
|  |  |   - 只读文件系统（除 /tmp）               | | |
|  |  +----------------------------------------+ | |
|  +---------------------------------------------+ |
+--------------------------------------------------+

适用场景：公有云 VPS、团队共享开发机、CI/CD 流水线。

模式 B：Host Gateway + Sandbox 容器（混合隔离）

网关进程直接运行于宿主机（或主容器），仅将危险操作（代码执行、浏览器自动化）放入临时沙箱容器。

md 复制代码

+--------------------------------------------------+
|                   Docker Host                    |
|                                                  |
|  +------------------+      +------------------+  |
|  | openclaw-gateway |      |   Sandbox Pool   |  |
|  | (Host Network)   |<---->|  +------------+  |  |
|  | PID 1 (宿主机)    |      |  | Sandbox #1 |  |  |
|  +------------------+      |  +------------+  |  |
|           |                |  +------------+  |  |
|           v                |  | Sandbox #2 |  |  |
|  +------------------+      |  +------------+  |  |
|  |   Control UI     |      +------------------+  |
|  |   (Port 18789)   |                            |
|  +------------------+                            |
+--------------------------------------------------+

架构优势：

性能：网关直接绑定宿主机端口，避免 NAT 转发延迟
安全：敏感操作（如 rm -rf /）被限制在一次性容器中，退出即焚毁

5.2 部署实操步骤

官方提供自动化设置脚本 docker-setup.sh，建议先 clone 仓库再执行，便于后续调优：

bash 复制代码

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

# 执行自动化构建与配置
./docker-setup.sh

脚本执行关键动作：

构建本地镜像（基于 node:22-bookworm）
创建数据卷映射：~/.openclaw（配置/记忆）与 ~/openclaw/workspace（工作区）
触发交互式初始化向导（onboard）
生成 docker-compose.yml 与可选的 docker-compose.extra.yml（持久化挂载）
手动 Compose 启动（若需自定义）：

yml 复制代码

version: '3.8'
services:
  openclaw-gateway:
    build: .
    ports:
      - "18789:18789"
    volumes:
      - ~/.openclaw:/home/node/.openclaw
      - ~/openclaw/workspace:/home/node/workspace
    environment:
      - NODE_ENV=production
      - SANDBOX_ENABLED=true
    restart: unless-stopped

启动命令：

bash 复制代码

# 初始化（仅需一次）
docker compose run --rm openclaw-cli onboard

# 后台启动网关
docker compose up -d openclaw-gateway

# 查看实时日志
docker compose logs -f gateway

5.3 权限与持久化注意事项

官方镜像以非 root 用户 node（UID 1000）运行，若宿主机挂载目录权限不符，会导致配置写入失败：

bash 复制代码

# Linux 宿主机需调整目录归属
sudo chown -R 1000:1000 ~/.openclaw ~/openclaw/workspace

# 或设置 ACL（若多用户共享）
setfacl -R -m u:1000:rwx ~/.openclaw

六、初始化向导与配置生成

无论采用哪种部署方式，首次运行都需执行 openclaw onboard，这是一个交互式配置流程，生成核心配置文件 ~/.openclaw/config.json。

6.1 向导流程解析

md 复制代码

+-------------------+
|   openclaw onboard |
+---------+---------+
          |
          v
+---------+---------+
| 1. 选择 AI 提供商  |
|    - OpenAI       |
|    - Anthropic    |
|    - OpenRouter   |
|    - 本地模型      |
+---------+---------+
          |
          v
+---------+---------+
| 2. 配置 API 密钥   |
|    (加密存储)       |
+---------+---------+
          |
          v
+---------+---------+
| 3. 设置网关凭证    |
|    - Admin Token  |
|    - 端口 (18789) |
+---------+---------+
          |
          v
+---------+---------+
| 4. 选择通信通道    |
|    - Telegram     |
|    - WhatsApp     |
|    - Discord      |
|    - Webhook      |
+---------+---------+
          |
          v
+---------+---------+
| 5. 生成配置文件    |
|    与系统服务      |
+-------------------+

6.2 关键配置项说明

模型路由配置（config.json 节选）：

json 复制代码

{
  "models": {
    "default": "gpt-4",
    "providers": [
      {
        "name": "openai",
        "apiKey": "${OPENAI_API_KEY}",
        "baseURL": "https://api.openai.com/v1"
      },
      {
        "name": "local-llama",
        "apiKey": "sk-no-key",
        "baseURL": "http://host.docker.internal:11434/v1"
      }
    ]
  },
  "gateway": {
    "port": 18789,
    "sandbox": {
      "enabled": true,
      "image": "openclaw/sandbox:latest"
    }
  }
}

环境变量覆盖：生产环境建议通过 .env 或 Docker Secrets 注入敏感信息，避免硬编码于 JSON 文件。

七、生产环境加固建议

从架构安全角度，部署完成后建议实施以下加固措施：

7.1 网络层安全

防火墙：仅开放 18789 端口（或自定义端口），限制源 IP 白名单
SSH 隧道：管理后台建议通过本地端口转发访问，避免直接暴露公网：
bash
复制
ssh -N -L 18789:127.0.0.1:18789 user@

7.2 运行时安全

非特权用户：确保 OpenClaw 进程以非 root 运行（Docker 模式已默认实现）
沙箱限制：启用 SANDBOX_ENABLED=true，禁止 Agent 直接访问宿主机文件系统
命令白名单：在 config.json 中配置 allowed_commands 与 denied_commands，限制危险 Shell 操作

7.3 监控与备份

状态备份：~/.openclaw 目录包含 Agent 记忆与配置，建议每日增量备份至对象存储
日志聚合：Docker 模式可配置日志驱动至 Loki 或 ELK 栈，便于审计 Agent 行为

八、故障排查速查表

现象	可能原因	排查命令
`onboard` 卡住	API Key 验证失败	`curl -I https://api.openai.com` 检查出站网络
Docker 启动后 1008 错误	远程访问配置未启用	检查 `config.json` 中 `allowInsecureAuth`（仅内网可临时开启）
权限被拒绝 (EACCES)	UID 1000 无权访问挂载卷	`ls -n ~/.openclaw` 确认归属
内存溢出 (OOM)	Sandbox 未限制内存	Docker 中设置 `deploy.resources.limits.memory`
端口冲突	18789 被占用	`netstat -tulnp	grep 18789`

九、总结

OpenClaw 的三级部署体系覆盖了从个人极客到企业级生产的全场景：

一键脚本降低了体验门槛，适合快速验证概念
npm 模式提供了开发灵活性，适合需要深度定制的场景
Docker Compose 则是生产环境的稳健之选，特别是 Host+Sandbox 混合模式，在性能与隔离性之间取得了最佳平衡

本文章基于openclaw官方文档。仅供学习参考，请勿用于商业用途。