![1777434455050.jpg#center](https://developer.qcloudimg.com/http-save/yehe-11154201/51b2b7edbf832e8e9ffc6ea9581d7954.png)

> **摘要**：本文将手把手教你从零开始部署 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 部署流程概览

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

![image.png#center](https://developer.qcloudimg.com/http-save/yehe-11154201/56798933b6e2fc2866b6c37dcc3eb481.png)

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

| 步骤 | 预计时间 | 主要操作 |
|------|----------|----------|
| 环境检查 | 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
```

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

![image.png#center](https://developer.qcloudimg.com/http-save/yehe-11154201/3289a78c168c5aa45da5a0ff5f0d11de.png)

### 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 推荐选择

![image.png#center](https://developer.qcloudimg.com/http-save/yehe-11154201/b4e8233a511af6a9e729215f34c1a133.png)

---

## 九、下一步

部署完成后，你可以：

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


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

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

项目经理

人工智能

5分钟快速部署OpenClaw AI智能体指南：详解Node.js环境配置、安装步骤、初始化设置及常见问题解决方案，提供CLI/HTTP两种测试方式，适合本地开发、云服务器及Docker部署，包含端口占用、认证失败等故障排查技巧。

日志文件

云服务器

包管理器

SSL 证书

服务器

智能体

防火墙

Windows

容器

Ubuntu

Debian

Docker

CentOS

Linux

JSON

2026采购季 | AI焕新·智启新局

4核4G3M云服务器 新用户低至38元/年！

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云AI代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

功能1上新10个字符

功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符。

功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符。

功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符

功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符

功能4上新

文章&问答评论现已支持表情

全新交互，全新视觉，新增快捷键、悬浮工具栏、高亮块等功能并同时优化现有功能，全面提升创作效率和体验

社区富文本编辑器全新改版！诚邀体验～ 

精选全网热门MCP server，让你的AI更好用 🚀

💥开发者 MCP广场重磅上线！

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

5分钟部署 OpenClaw：从零到运行的完整流程-腾讯云开发者社区-腾讯云

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

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

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐