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

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

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

一、环境要求与前置检查

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

1.1 基础硬件配置

关键提示：若启用浏览器自动化（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（浏览器自动化）

执行前置检查命令：

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

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

二、部署方案选型决策树

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

+—————————————————+
| 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 执行流程拆解

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

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

脚本内部执行阶段：

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

3.2 安装后验证

# 检查 CLI 可用性
openclaw –version

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

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

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

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

4.2 进程保活配置

npm 模式默认前台运行，生产环境需配合进程管理器：
PM2 方案（推荐）：

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）运行于容器网络内部。

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

适用场景：公有云 VPS、团队共享开发机、CI/CD 流水线。
模式 B：Host Gateway + Sandbox 容器（混合隔离）
网关进程直接运行于宿主机（或主容器），仅将危险操作（代码执行、浏览器自动化）放入临时沙箱容器。

+————————————————–+
| 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 仓库再执行，便于后续调优：

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 启动（若需自定义）：

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

启动命令：

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

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

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

5.3 权限与持久化注意事项

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

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

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

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

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

6.1 向导流程解析

+——————-+
| 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 节选）：

{
"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 行为

八、故障排查速查表

九、总结

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

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

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