5分钟部署 OpenClaw从零到运行的完整流程

目录

• 一、部署前准备
• 1.1 系统要求详解
• 1.2 部署流程概览
• 1.3 检查现有环境
• 二、安装 Node.js
• 2.1 方式一：官方安装包（推荐新手）
• 2.2 方式二：nvm 安装（推荐开发者）
• 2.3 方式三：包管理器安装
• 三、安装 OpenClaw
• 3.1 全局安装（推荐）
• 3.2 安装时间参考
• 3.3 常见安装问题
• 四、初始化配置
• 4.1 运行引导向导
• 4.2 配置文件说明
• 4.3 配置项详解
• 4.4 手动配置（高级用户）
• 五、启动 Gateway
• 5.1 前台运行（调试模式）
• 5.2 后台运行（生产模式）
• 5.3 Docker 部署（可选）
• 六、验证部署
• 6.1 健康检查
• 6.2 发送测试消息
• 6.3 检查日志
• 七、常见问题排查
• 7.1 端口被占用
• 7.2 认证失败
• 7.3 API Key 无效
• 7.4 网络连接问题
• 7.5 内存不足
• 八、部署方案对比
• 8.1 四种部署方案
• 8.2 推荐选择
• 九、下一步
• 十、总结
• 部署检查清单
• 关键命令速查

在开始部署之前，我们需要确保系统满足 OpenClaw 的运行要求。OpenClaw 基于 Node.js 开发，对系统资源的要求相对较低，但为了保证流畅运行，建议满足以下配置：

环境	最低要求	推荐配置	说明
Node.js	≥ 22 LTS	24+	OpenClaw 使用了较新的 JavaScript 特性
操作系统	macOS / Linux / Windows (WSL2)	macOS / Linux	Linux 服务器部署体验最佳
内存	2GB	4GB+	运行本地模型需要更多内存
磁盘	500MB	1GB+	包含日志、缓存、本地模型
网络	稳定网络	宽带	用于下载依赖和调用云端 API

为什么需要 Node.js 22+？

OpenClaw 使用了 Node.js 22 引入的新特性，包括更强大的异步处理能力和改进的模块系统。如果你使用的是旧版本 Node.js，可能会遇到语法错误或功能异常。

整个部署过程可以分为六个步骤，从环境检查到最终验证：

每个步骤的预计时间如下：

步骤	预计时间	主要操作
环境检查	1 分钟	检查 Node.js 版本
安装 Node.js	2-5 分钟	下载安装或使用包管理器
安装 OpenClaw	1-2 分钟	npm 全局安装
初始化配置	2-3 分钟	运行引导向导
启动 Gateway	30 秒	启动服务
验证运行	30 秒	发送测试消息

在开始安装之前，先检查系统是否已经安装了 Node.js：

# 检查 Node.js 版本
node --version
# 期望输出: v22.x.x 或更高
# 检查 npm 版本
npm --version
# 期望输出: 10.x.x 或更高
# 检查操作系统
uname -a  # Linux/macOS
# 或
ver       # Windows

如果 Node.js 版本低于 22，或者根本没有安装 Node.js，请继续下一步进行安装。

这是最简单的安装方式，适合不熟悉命令行的用户。

macOS / Windows 步骤：

1. 访问 Node.js 官网：https://nodejs.org
2. 下载 LTS（长期支持）版本，当前推荐 v24.x
3. 双击安装包，按照提示完成安装
4. 打开终端，运行 node --version 验证安装

优点：简单直观，无需命令行操作。

缺点：版本管理不便，升级需要重新下载。

nvm（Node Version Manager）允许你在同一台机器上安装和管理多个 Node.js 版本，非常适合开发者。

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
# 重新加载终端配置
source ~/.bashrc  # 或 source ~/.zshrc
# 安装 Node.js 24
nvm install 24
nvm use 24
# 设置默认版本
nvm alias default 24
# 验证安装
node --version

优点：可以轻松切换版本，适合需要测试不同版本的开发者。

缺点：需要命令行操作，对新手有一定门槛。

不同操作系统有不同的包管理器，可以快速安装 Node.js。

macOS (Homebrew)：

# 安装 Homebrew（如果还没有）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# 安装 Node.js
brew install node@24

Ubuntu/Debian：

# 添加 NodeSource 仓库
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
# 安装 Node.js
sudo apt-get install -y nodejs

CentOS/RHEL：

# 添加 NodeSource 仓库
curl -fsSL https://rpm.nodesource.com/setup_24.x | sudo bash -
# 安装 Node.js
sudo yum install -y nodejs

优点：系统级安装，适合服务器部署。

缺点：版本可能不是最新的，需要等待包管理器更新。

使用 npm 或 pnpm 全局安装 OpenClaw，这样可以在任何目录下使用 openclaw 命令。

# 使用 npm 安装
npm install -g openclaw@latest
# 或使用 pnpm（更快更省空间）
npm install -g pnpm
pnpm add -g openclaw@latest
# 验证安装
openclaw --version
# 期望输出: 1.x.x

安装时间取决于网络环境和包管理器：

网络环境	npm	pnpm
国内镜像	1-2 分钟	30秒-1分钟
国外直连	30秒-1分钟	10-30秒
慢速网络	3-5 分钟	2-3 分钟

加速技巧：配置国内镜像源

# 配置淘宝镜像
npm config set registry https://registry.npmmirror.com
# 或使用 pnpm
pnpm config set registry https://registry.npmmirror.com

问题	原因	解决方案
EACCES 权限错误	npm 全局目录权限不足	sudo npm install -g openclaw 或配置 npm 用户目录
网络超时	网络连接问题	配置国内镜像源
Node 版本过低	Node.js 版本不满足要求	升级到 Node.js 22+
找不到命令	PATH 未包含 npm 全局目录	将 npm 全局目录添加到 PATH

配置 npm 用户目录（解决权限问题）：

# 创建 npm 全局目录
mkdir ~/.npm-global
# 配置 npm 使用新目录
npm config set prefix '~/.npm-global'
# 添加到 PATH
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

安装完成后，运行引导向导进行初始化配置：

openclaw onboard

向导会引导你完成以下配置步骤：

Gateway CLI 用户 Gateway CLI 用户 openclaw onboard 选择配置方式 选择交互式 输入 Gateway 端口 18789 (默认) 设置认证令牌 输入或自动生成 选择 AI 模型 选择 OpenAI/Claude/DeepSeek 输入 API Key 粘贴密钥 保存配置 配置完成 显示成功信息

配置文件位于 ~/.openclaw/openclaw.json，包含所有 OpenClaw 的设置：

{
  "gateway": {
    "port": 18789,
    "authToken": "your-secret-token",    "verbose": false
  },
  "models": {
    "default": {
      "provider": "openai",
      "model": "gpt-4o-mini",
      "apiKey": "sk-xxx"
    }
  },
  "channels": {
    "telegram": {
      "enabled": false,
      "botToken": ""
    },
    "whatsapp": {
      "enabled": false
    }
  },
  "sessions": {
    "maxContextTokens": 4000,
    "timeout": 3600
  }
}

配置项	说明	默认值	建议值
gateway.port	Gateway 监听端口	18789	保持默认或改为其他未占用端口
gateway.authToken	认证令牌	自动生成	使用强密码或自动生成
models.default.provider	默认 AI 提供商	openai	根据需求选择
models.default.model	默认模型	gpt-4o-mini	平衡成本和性能
sessions.maxContextTokens	最大上下文 Token	4000	2000-8000 之间

如果你更喜欢手动编辑配置文件，可以直接创建 ~/.openclaw/openclaw.json：

# 创建配置目录
mkdir -p ~/.openclaw
# 创建配置文件
cat > ~/.openclaw/openclaw.json << 'EOF'
{
  "gateway": {
    "port": 18789,
    "authToken": "your-strong-password-here"
  },
  "models": {
    "default": {
      "provider": "openai",
      "model": "gpt-4o-mini",
      "apiKey": "sk-your-api-key"
    }
  }
}
EOF

前台运行模式可以看到详细的日志输出，适合调试和问题排查：

# 前台运行，显示详细日志
openclaw gateway --verbose
# 输出示例
# [INFO] Gateway starting on port 18789...
# [INFO] Loaded 5 skills
# [INFO] Connected to model: gpt-4o-mini
# [INFO] Gateway ready

优点：可以实时看到日志，便于调试。

缺点：关闭终端后服务停止。

对于生产环境，建议使用守护进程模式：

# 安装为系统服务
openclaw onboard --install-daemon
# 启动服务
openclaw gateway start
# 查看状态
openclaw gateway status
# 停止服务
openclaw gateway stop
# 重启服务
openclaw gateway restart

系统服务管理：

安装为系统服务后，OpenClaw 会随系统启动自动运行。服务配置文件位于：

• Linux: /etc/systemd/system/openclaw.service
• macOS: ~/Library/LaunchAgents/com.openclaw.gateway.plist

如果你熟悉 Docker，可以使用容器化部署：

# docker-compose.yml
version: '3.8'
services:
  openclaw:
    image: openclaw/gateway:latest
    container_name: openclaw-gateway
    ports:
      - "18789:18789"
    volumes:
      - ./config:/root/.openclaw
      - ./workspace:/workspace
    environment:
      - OPENCLAW_AUTH_TOKEN=${AUTH_TOKEN}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
    restart: unless-stopped
    # 安全加固
    read_only: true
    user: "1000:1000"
    security_opt:
      - no-new-privileges:true

# 启动
docker-compose up -d
# 查看日志
docker-compose logs -f
# 停止
docker-compose down

首先检查 Gateway 是否正常运行：

# 检查 Gateway 状态
openclaw gateway status
# 期望输出
# Gateway is running on port 18789
# Uptime: 2 minutes
# Active sessions: 0
# Model: gpt-4o-mini

发送一条测试消息验证 AI 是否正常响应：

# 方式一：CLI 发送
openclaw agent --message "你好，请介绍一下你自己"
# 方式二：HTTP 请求
curl -X POST http://localhost:18789/api/chat 
  -H "Authorization: Bearer your-token" 
  -H "Content-Type: application/json" 
  -d '{"message": "你好"}'

查看日志确认一切正常：

# 查看实时日志
openclaw logs --follow
# 查看最近 100 行
openclaw logs --lines 100
# 日志文件位置
cat ~/.openclaw/logs/gateway.log

正常日志示例：

[2026-03-15 22:30:00] INFO  Gateway started on port 18789
[2026-03-15 22:30:01] INFO  Loaded 5 skills from ~/.openclaw/skills
[2026-03-15 22:30:02] INFO  Connected to OpenAI API
[2026-03-15 22:30:15] INFO  Session created: session_abc123
[2026-03-15 22:30:16] INFO  Message received, processing...
[2026-03-15 22:30:18] INFO  Response sent successfully

症状：启动时报错 Error: listen EADDRINUSE: address already in use :::18789

解决方案：

# 查找占用端口的进程
lsof -i :18789
# 输出示例
# COMMAND   PID USER   FD   TYPE DEVICE SIZE/OFF NODE NAME
# node     12345 user   22u  IPv6 123456      0t0  TCP *:18789 (LISTEN)
# 终止进程
kill -9 12345
# 或更换端口
openclaw gateway --port 18888

症状：HTTP 请求返回 401 Unauthorized

解决方案：

# 检查当前令牌
openclaw config get gateway.authToken
# 重新生成令牌
openclaw config set gateway.authToken $(openssl rand -hex 32)
# 重启 Gateway
openclaw gateway restart

症状：AI 响应报错 Invalid API key

解决方案：

# 验证 API Key 配置
openclaw config get models.default.apiKey
# 更新 API Key
openclaw config set models.default.apiKey "sk-xxx"
# 测试 API 连接
openclaw agent --message "test" --verbose

错误信息	原因	解决方案
ETIMEDOUT	网络超时	检查网络代理设置
ENOTFOUND	DNS 解析失败	检查 DNS 配置
ECONNREFUSED	连接被拒绝	检查防火墙规则
UNABLE_TO_VERIFY_LEAF_SIGNATURE	SSL 证书问题	检查系统时间或代理设置

症状：进程被系统终止，日志中出现 JavaScript heap out of memory

解决方案：

# 增加 Node.js 内存限制
export NODE_OPTIONS="--max-old-space-size=4096"
# 或在启动命令中指定
node --max-old-space-size=4096 $(which openclaw) gateway

根据不同的使用场景，选择合适的部署方案：

方案	适用场景	成本	复杂度	推荐指数
本地开发机	个人体验、开发调试	零成本	⭐	⭐⭐⭐
Mac Mini	长期运行、隐私优先	$599-$1999	⭐⭐	⭐⭐⭐⭐⭐
云服务器	远程访问、团队协作	68-99元/年	⭐	Docker

部署完成后，你可以：

1. 接入消息平台 – 飞书、Discord、Telegram 等
2. 安装技能 – 从 ClawHub 安装现成技能
3. 开发技能 – 创建自己的 AI 能力
4. 配置定时任务 – 自动化日常工作

• Node.js 22+ 已安装
• OpenClaw 已全局安装
• 配置文件已生成
• API Key 已配置
• Gateway 已启动
• 测试消息已成功

命令	说明
openclaw onboard	初始化配置
openclaw gateway start	启动服务
openclaw gateway status	查看状态
openclaw gateway stop	停止服务
openclaw gateway restart	重启服务
openclaw agent --message "xxx"	发送消息
openclaw logs --follow	查看日志
openclaw config get <key>	获取配置
openclaw config set <key> <value>	设置配置

参考资料：

• 官方文档：https://docs.openclaw.ai
• GitHub：https://github.com/openclaw/openclaw
• 社区：https://discord.com/invite/clawd

到此这篇关于5分钟部署 OpenClaw从零到运行的完整流程的文章就介绍到这了,更多相关OpenClaw部署内容请搜索风君子博客以前的文章或继续浏览下面的相关文章，希望大家以后多多支持风君子博客！