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

七夜zippoe2026-03-16 8:05

目 录

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

摘要：本文将手把手教你从零开始部署 OpenClaw，涵盖环境准备、安装配置、首次运行、常见问题排查，让你在 5 分钟内拥有自己的 AI 智能体。

一、部署前准备

1.1 系统要求详解

在开始部署之前，我们需要确保系统满足 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.2 部署流程概览

整个部署过程可以分为六个步骤，从环境检查到最终验证：
环境检查
安装Node.js
安装OpenClaw
初始化配置
启动Gateway
验证运行

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

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

1.3 检查现有环境

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

bash 复制代码 
# 检查 Node.js 版本
node --version
# 期望输出: v22.x.x 或更高

# 检查 npm 版本
npm --version
# 期望输出: 10.x.x 或更高

# 检查操作系统
uname -a  # Linux/macOS
# 或
ver       # Windows

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

二、安装 Node.js

2.1 方式一：官方安装包（推荐新手）

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

macOS / Windows 步骤：

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

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

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

2.2 方式二：nvm 安装（推荐开发者）

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

bash 复制代码 
# 安装 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

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

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

2.3 方式三：包管理器安装

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

macOS (Homebrew)：

bash 复制代码 
# 安装 Homebrew（如果还没有）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装 Node.js
brew install node@24

Ubuntu/Debian：

bash 复制代码 
# 添加 NodeSource 仓库
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -

# 安装 Node.js
sudo apt-get install -y nodejs

CentOS/RHEL：

bash 复制代码 
# 添加 NodeSource 仓库
curl -fsSL https://rpm.nodesource.com/setup_24.x | sudo bash -

# 安装 Node.js
sudo yum install -y nodejs

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

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

三、安装 OpenClaw

3.1 全局安装（推荐）

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

bash 复制代码 
# 使用 npm 安装
npm install -g openclaw@latest

# 或使用 pnpm（更快更省空间）
npm install -g pnpm
pnpm add -g openclaw@latest

# 验证安装
openclaw --version
# 期望输出: 1.x.x

3.2 安装时间参考

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

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

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

bash 复制代码 
# 配置淘宝镜像
npm config set registry https://registry.npmmirror.com

# 或使用 pnpm
pnpm config set registry https://registry.npmmirror.com

3.3 常见安装问题

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

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

bash 复制代码 
# 创建 npm 全局目录
mkdir ~/.npm-global

# 配置 npm 使用新目录
npm config set prefix '~/.npm-global'

# 添加到 PATH
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

四、初始化配置

4.1 运行引导向导

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

bash 复制代码 
openclaw onboard

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

4.2 配置文件说明

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

json 复制代码 
{
  "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
  }
}

4.3 配置项详解

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

4.4 手动配置（高级用户）

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

bash 复制代码 
# 创建配置目录
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

五、启动 Gateway

5.1 前台运行（调试模式）

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

bash 复制代码 
# 前台运行，显示详细日志
openclaw gateway --verbose

# 输出示例
# [INFO] Gateway starting on port 18789...
# [INFO] Loaded 5 skills
# [INFO] Connected to model: gpt-4o-mini
# [INFO] Gateway ready

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

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

5.2 后台运行（生产模式）

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

bash 复制代码 
# 安装为系统服务
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

5.3 Docker 部署（可选）

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

yaml 复制代码 
# 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
bash 复制代码 
# 启动
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止
docker-compose down

六、验证部署

6.1 健康检查

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

bash 复制代码 
# 检查 Gateway 状态
openclaw gateway status

# 期望输出
# Gateway is running on port 18789
# Uptime: 2 minutes
# Active sessions: 0
# Model: gpt-4o-mini

6.2 发送测试消息

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

bash 复制代码 
# 方式一：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": "你好"}'

6.3 检查日志

查看日志确认一切正常：

bash 复制代码 
# 查看实时日志
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

七、常见问题排查

7.1 端口被占用

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

解决方案：

bash 复制代码 
# 查找占用端口的进程
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

7.2 认证失败

症状：HTTP 请求返回 401 Unauthorized

解决方案：

bash 复制代码 
# 检查当前令牌
openclaw config get gateway.authToken

# 重新生成令牌
openclaw config set gateway.authToken $(openssl rand -hex 32)

# 重启 Gateway
openclaw gateway restart

7.3 API Key 无效

症状 ：AI 响应报错 Invalid API key

解决方案：

bash 复制代码 
# 验证 API Key 配置
openclaw config get models.default.apiKey

# 更新 API Key
openclaw config set models.default.apiKey "sk-xxx"

# 测试 API 连接
openclaw agent --message "test" --verbose

7.4 网络连接问题

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

7.5 内存不足

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

解决方案：

bash 复制代码 
# 增加 Node.js 内存限制
export NODE_OPTIONS="--max-old-space-size=4096"

# 或在启动命令中指定
node --max-old-space-size=4096 $(which openclaw) gateway

八、部署方案对比

8.1 四种部署方案

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

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

8.2 推荐选择

个人体验
长期运行
团队协作
企业生产
选择部署方案
使用场景?
本地开发机
Mac Mini
云服务器
Docker/K8s

九、下一步

部署完成后，你可以：

  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> 设置配置

参考资料：

相关推荐
wscats3 小时前
用 OpenClaw 生成了团队体检报告，把摸鱼的同事扒出来了😅
openclaw
AlfredZhao10 小时前
在群晖NAS上配置OpenClaw：一次踩坑后的保姆级教程（完整修订版）
nas·openclaw·feishu
深巷wls15 小时前
Openclaw部署+飞书接入（windows环境）
windows·飞书·openclaw
utmhikari15 小时前
【测试人生】变更规则校验Agent研发的一些思路
大数据·人工智能·llm·agent·变更风险·openclaw
奋斗中的小猩猩15 小时前
OpenClaw不安全，Rust写的ZeroClaw给出满意答案
安全·rust·openclaw·小龙虾
孟郎郎16 小时前
OpenClaw 如何更换本地模型基础教程
windows·ai·机器人·ollama·openclaw·小龙虾
cxr82817 小时前
创建专业虚拟一人公司的 Skills 深度对比分析
人工智能·ai智能体·openclaw
love530love17 小时前
OpenClaw搭配LM Studio VS Ollama：Windows CUDA实战深度对比与完全配置指南
人工智能·windows·vllm·ollama·llama.cpp·lm studio·openclaw
全都是泡饃18 小时前
OpenClaw 配置教程：在 macOS 上搭建 AI 助手并与飞书集成
ai·openclaw
热门推荐
01GitHub 镜像站点02Qwen3.5 开源全解析：从 0.8B 到 397B，代际升级 + 全场景选型指南03OpenClaw 使用和管理 MCP 完全指南04OpenClaw macOS 完整安装与本地模型配置教程（实战版）05本地部署 OpenClaw + DeepSeek-R1 完全指南06UV安装并设置国内源07Openclow安装保姆级教程08OpenClaw 飞书机器人不回复消息？3 小时踩坑总结09OpenClaw Control UI安全上下文访问配置10在 Windows 上配置 Claude Code从安装到解决网络问题