OpenClaw 本地部署指南

OpenClaw 需要 Node.js 18+ 和 Git。建议使用 Linux 或 macOS 系统，Windows 用户请使用 WSL2。

检查现有环境：

node --version
npm --version
git --version

使用 nvm 安装推荐的 Node.js 版本：

# 安装 nvm（如果尚未安装）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# 重新加载 shell 配置
source ~/.bashrc   # 或 source ~/.zshrc

# 安装并切换到 LTS 版本
nvm install --lts
nvm use --lts
node --version

从 GitHub 仓库克隆 OpenClaw 项目到本地：

# 克隆主仓库
git clone https://github.com/your-org/openclaw.git
cd openclaw

# 查看分支结构，切换到稳定分支
git branch -a
git checkout main

OpenClaw 采用 monorepo 结构，使用 npm workspaces 管理多包依赖：

# 安装所有依赖（包括工作区子包）
npm install

# 如遇 node-gyp 编译错误，需安装构建工具
# macOS
xcode-select --install

# Ubuntu / Debian
sudo apt-get install build-essential python3

# 安装完成后验证
npm ls --depth=0

复制环境变量模板并根据你的环境修改：

# 创建环境变量文件
cp .env.example .env

# 编辑配置
vim .env   # 或使用任意编辑器

核心配置项说明：

# 服务端口
PORT=3000

# 数据库连接（如使用 PostgreSQL）
DATABASE_URL=postgresql://user:password@localhost:5432/openclaw

# JWT 密钥（生产环境请使用强随机字符串）
JWT_SECRET=your-super-secret-key-change-in-production

# Redis 缓存（可选）
REDIS_URL=redis://localhost:6379

# 日志级别
LOG_LEVEL=info

执行构建脚本并启动开发服务器：

# 构建项目
npm run build

# 启动开发模式（热重载）
npm run dev

# 或启动生产模式
npm start

常用 npm 脚本一览：

启动后执行以下检查确认服务正常运行：

1. 检查服务进程

# 确认端口已被监听
lsof -i :3000
# 或 Windows
netstat -ano | findstr :3000

2. 测试 API 健康检查

curl http://localhost:3000/health
# 期望响应：{"status":"ok","version":"1.0.0","uptime":12345}

3. 查看日志输出

# 确认无 ERROR 级别日志
npm run dev 2>&1 | grep -i error

4. 运行内置测试

npm test

将 OpenClaw 部署到生产环境，推荐使用进程管理器确保服务高可用：

# 使用 PM2 管理进程
npm install -g pm2

# 启动服务
pm2 start npm --name "openclaw" -- start

# 设置开机自启
pm2 startup
pm2 save

# 查看状态
pm2 status

使用 Nginx 反向代理（可选，推荐）：

# /etc/nginx/sites-available/openclaw
server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_cache_bypass $http_upgrade;
    }
}