02. 安装部署指南

课程信息
难度等级：🟢 入门
阅读时间：20 分钟
前置知识：会用命令行（终端）
本篇你将学会： 在 macOS/Linux/Windows 上安装 OpenClaw，配置运行环境，完成首次启动
小白速通： 直接跳到"快速安装"章节（第 3 节），跟着复制粘贴命令就行。遇到问题看第 12-13 节的故障排查

概述

这篇指南覆盖 OpenClaw 在所有主流平台上的安装、配置、升级和故障排查。不管你是 macOS 用户、Linux 服务器管理员还是 Windows 开发者，都能找到适合自己的安装方式。

安装 OpenClaw 的核心流程就三步：

1. 官方推荐：运行安装脚本（必要时自动安装 Node）
2. 或者手动安装 OpenClaw CLI（npm / pnpm / bun）
3. 运行引导向导（openclaw onboard）

1. 系统要求

1.1 硬件要求

项目	最低要求	推荐配置	说明
CPU	1 核	2 核+	Gateway 守护进程常驻运行
内存	512 MB	2 GB+	多平台连接时内存消耗线性增长
磁盘	500 MB 可用空间	2 GB+	包含 node_modules 和日志文件
网络	能访问 AI 模型 API	稳定的宽带连接	WebSocket 长连接需要稳定网络

名词解释：Gateway（OpenClaw 的核心服务进程）以守护进程（daemon，在后台持续运行的服务）方式运行，负责管理所有消息平台连接和 Agent 调度。

说明：OpenClaw 本身很轻量，主要资源消耗来自 Gateway 守护进程和消息平台连接。如果你同时连接多个平台（WhatsApp + Telegram + Discord），建议至少 2 GB 内存。

如果使用本地模型（Ollama），硬件要求会大幅提升：

模型规模	最低内存	推荐 GPU	推荐磁盘空间
7B 参数	8 GB RAM	6 GB VRAM	10 GB
13B 参数	16 GB RAM	12 GB VRAM	20 GB
70B 参数	64 GB RAM	24 GB+ VRAM	50 GB

提示：如果你只用云端 API（OpenAI、Anthropic、Google），不需要 GPU，一台普通的云服务器就够了。

1.2 操作系统要求

操作系统	支持版本	备注
macOS	12 (Monterey) 及以上	Intel 和 Apple Silicon 均支持
Ubuntu/Debian	20.04 LTS 及以上	推荐 22.04 LTS
CentOS/RHEL	8 及以上	需要 EPEL 仓库
Arch Linux	Rolling Release	社区维护 AUR 包
Windows	10 (1903+) / 11	强烈推荐通过 WSL2 安装
Alpine Linux	3.18+	Docker 镜像常用基础系统

1.3 软件依赖

软件	最低版本	推荐版本	用途
Node.js	22.14+ 兼容	24.x	运行时环境
npm（Node Package Manager，Node.js 的包管理器）	10.0.0	10.x（随 Node.js 附带）	包管理器
Git	2.30+	最新版	克隆仓库、本地构建、版本管理
Python	3.10+（可选）	3.12	部分 Agent 工具依赖
Docker	24.0+（可选）	最新版	容器化部署

检查当前环境是否满足要求：

2. Node.js 环境安装

OpenClaw 当前的官方口径是：Node.js 24.x 推荐，22.14+ 兼容。如果你已经满足这个基线，可以跳过这一节。

💡 阅读提示：下面部分命令示例仍保留 Node 22 写法，因为它仍然在兼容范围内；如果你是新装环境，直接把示例里的 22 换成 24 会更符合当前官方推荐。

2.1 使用 nvm 安装（推荐）

nvm（Node Version Manager）是管理 Node.js 版本的最佳方式，可以在多个版本之间自由切换。

macOS / Linux：

Windows：

Windows 用户使用 nvm-windows：

从 nvm-windows releases 下载最新安装包

运行安装程序

打开新的命令行窗口：

nvm install 24
nvm use 24
node --version

2.2 使用官方安装包

直接从 Node.js 官网下载 LTS 版本安装包：

macOS：下载 .pkg 文件，双击安装

Windows：下载 .msi 文件，双击安装

Linux：使用 NodeSource 仓库

2.3 使用 Homebrew（macOS）

2.4 安装方式对比

方式	优点	缺点	适用场景
nvm	多版本管理、不需要 sudo	需要额外安装	开发环境（推荐）
官方安装包	简单直接	升级麻烦、可能需要 sudo	新手、单版本需求
Homebrew	macOS 生态集成好	仅限 macOS	macOS 用户
NodeSource	系统包管理器集成	版本更新可能滞后	服务器部署

3. 安装 OpenClaw CLI

3.1 npm 全局安装（推荐）

3.2 使用 yarn

3.3 使用 pnpm（高性能的 npm 替代品）

3.4 使用 npx（免安装体验）

如果你只是想试试，不想全局安装：

注意：npx 每次运行都会检查最新版本，适合体验，不适合生产环境。

3.5 安装方式对比

方式	命令	优点	缺点
npm	`npm i -g openclaw@latest`	最通用、文档最多	全局安装可能需要权限
yarn	`yarn global add openclaw`	速度快、缓存好	需要额外安装 yarn
pnpm	`pnpm add -g openclaw`	磁盘占用小	需要额外安装 pnpm
npx	`npx openclaw`	免安装	每次启动慢

4. 引导向导（openclaw onboard）

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

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

4.1 选择 AI 模型提供商

? 选择你的 AI 模型提供商:
  ❯ DeepSeek (V4 Flash — 引导默认, V4 Pro)
    OpenAI (GPT-5.4, GPT-5.2-mini)
    Anthropic (Claude Opus 4.6, Claude Sonnet 4.6)
    Google (Gemini 3.1 Pro, Gemini 2.5 Flash)
    本地模型 (Ollama)
    自定义 API (OpenAI 兼容)

4.2 配置 API Key

? 输入你的 OpenAI API Key: sk-proj-xxxxxxxxxxxxx
✓ API Key 验证成功！
✓ 可用模型: gpt-5.4, gpt-5.2-mini

4.3 选择消息平台

? 你想连接哪些消息平台？（可多选）
  ❯ ◉ Telegram
    ◉ WhatsApp
    ◯ Discord
    ◯ Slack
    ◯ 微信（企业微信）
    ◯ 飞书
    ◯ Web Chat（内置网页界面）

4.4 配置 Gateway

? Gateway 监听端口: (18789)
? 启用 Control UI 控制面板？ (Y/n)
? Control UI 访问密码: ********

4.5 完成配置

✓ 配置文件已生成: ~/.openclaw/openclaw.json
✓ Gateway 守护进程已安装（launchd/systemd user service）
✓ Gateway 已启动: http://localhost:18789

OpenClaw 安装完成！

下一步：
  openclaw gateway          启动 Gateway
  openclaw channels list    查看频道
  openclaw models list      查看可用模型

提示：引导向导生成的配置文件在 ~/.openclaw/openclaw.json（JSON5 格式），你可以随时手动编辑。

5. macOS 安装完整流程

5.1 使用 Homebrew（最简单）

5.2 使用 nvm

5.3 Apple Silicon 注意事项

M1/M2/M3/M4 芯片的 Mac 完全支持，不需要 Rosetta。如果遇到原生模块编译问题：

6. Linux 安装完整流程

6.1 Ubuntu / Debian

6.2 CentOS / RHEL

6.3 Arch Linux

6.4 权限问题处理

Linux 上全局安装 npm 包可能遇到权限问题。推荐方案：

方案一：使用 nvm（推荐）

nvm 安装的 Node.js 在用户目录下，不需要 sudo：

方案二：修改 npm 全局目录

方案三：修改目录权限（不推荐）

7. Windows 安装完整流程

7.1 WSL2 安装（强烈推荐）

Windows 上运行 OpenClaw 最稳定的方式是通过 WSL2：

# 1. 安装 WSL2（管理员 PowerShell）
wsl --install

# 2. 重启电脑后，打开 Ubuntu 终端

# 3. 在 WSL2 Ubuntu 中安装
sudo apt update && sudo apt upgrade -y
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
npm install -g openclaw@latest
openclaw onboard --install-daemon

7.2 原生 Windows 安装

如果不想用 WSL2，也可以原生安装：

从 Node.js 官网下载 Windows 安装包

运行安装程序，勾选 "Automatically install the necessary tools"

打开新的 PowerShell 或 CMD：

node --version
npm install -g openclaw@latest
openclaw onboard --install-daemon

7.3 WSL2 vs 原生安装对比

特性	WSL2	原生 Windows
稳定性	⭐⭐⭐⭐⭐	⭐⭐⭐
性能	⭐⭐⭐⭐	⭐⭐⭐⭐⭐
兼容性	完全兼容 Linux 生态	部分原生模块可能有问题
文件系统	Linux 文件系统	NTFS
网络	需要端口转发	直接访问
推荐度	✅ 强烈推荐	⚠️ 可用但可能遇到问题

8. Docker 快速安装

如果你只想快速体验，Docker 是最简单的方式：

使用 docker-compose：

详细的 Docker 部署指南请参考 09-Docker部署指南，包含生产环境配置、多服务编排、SSL/TLS、备份恢复等内容。

⏭️ 小白可跳过 — 这部分面向高级用户，新手用默认配置就够了

9. 从 Git 仓库克隆并编译安装

适合需要自定义修改或参与开发的用户：

开发模式运行：

10. 升级和版本管理

10.1 升级到最新版

10.2 版本通道说明

通道	说明	npm dist-tag
stable	标签发布（vYYYY.M.D）	`latest`
beta	预发布（vYYYY.M.D-beta.N）	`beta`
dev	main 分支头	`dev`

10.3 版本锁定

如果你需要锁定特定版本（比如生产环境）：

10.4 回滚到旧版本

10.5 升级注意事项

升级前建议：

备份配置文件：cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak

查看 Changelog：了解新版本的破坏性变更

升级：openclaw update --channel stable

验证：openclaw status

⏭️ 小白可跳过 — 这部分面向高级用户，新手用默认配置就够了

11. 多环境部署

11.1 开发环境

// ~/.openclaw/openclaw.json（开发环境示例）
{
  gateway: {
    port: 18789,
  },
  agents: {
    defaults: {
      model: "openai/gpt-5.2-mini",  // 开发用便宜模型
    },
  },
  logging: {
    level: "debug",
  },
}

11.2 测试环境

{
  gateway: {
    port: 18789,
  },
  agents: {
    defaults: {
      model: "openai/gpt-5.4",
    },
  },
  logging: {
    level: "info",
  },
}

⏭️ 小白可跳过 — 这部分面向高级用户，新手用默认配置就够了

11.3 生产环境

{
  gateway: {
    port: 18789,
    auth: {
      token: "${OPENCLAW_GATEWAY_TOKEN}",
    },
  },
  agents: {
    defaults: {
      model: "openai/gpt-5.4",
    },
  },
  logging: {
    level: "warn",
  },
}

注意： environment、debug、logLevel（在 gateway 下）、rateLimit、security 等字段并非 OpenClaw 配置模式中的真实字段。Gateway 认证通过 gateway.auth.token 配置，日志级别通过顶层 logging 配置。

11.4 使用不同配置文件

12. 安装验证和健康检查

12.1 基本验证

12.2 启动 Gateway 并验证

12.3 API 连通性测试

12.4 Control UI 访问

Gateway 启动后，Control UI 通过 Gateway WebSocket 提供，访问 http://localhost:18789，你应该能看到：

Gateway 运行状态

已连接的消息平台列表

Agent 列表和状态

消息统计和日志

💡 遇到问题？ 直接来这里找答案，大部分安装问题都能在这里解决

13. 常见安装问题排查

13.1 权限问题

症状：EACCES: permission denied

13.2 网络问题

症状：npm ERR! network timeout

13.3 Node.js 版本过低

症状：Error: OpenClaw requires Node.js 22 or higher

13.4 原生模块编译失败

症状：node-gyp rebuild failed

13.5 端口被占用

症状：Error: listen EADDRINUSE: address already in use :::18789

13.6 API Key 无效

症状：Error: Invalid API key

13.7 WSL2 网络问题

症状：WSL2 中无法访问外部网络

14. 卸载

14.1 卸载 CLI

14.2 清理配置和数据

14.3 Docker 卸载

下一步

安装完成后，建议按以下顺序继续：

下一步	文档	说明
快速体验	03-快速开始指南	5 分钟上手
配置模型	04-模型配置指南	详细的模型配置
接入平台	05-消息平台接入指南	连接 Telegram、WhatsApp 等
Docker 部署	09-Docker部署指南	生产环境容器化部署
安全配置	10-安全配置指南	API Key 安全、网络安全

02-安装部署指南

02. 安装部署指南#

概述#

1. 系统要求#

1.1 硬件要求#

1.2 操作系统要求#

1.3 软件依赖#

2. Node.js 环境安装#

2.1 使用 nvm 安装（推荐）#

2.2 使用官方安装包#

2.3 使用 Homebrew（macOS）#

2.4 安装方式对比#

3. 安装 OpenClaw CLI#

3.1 npm 全局安装（推荐）#

3.2 使用 yarn#

3.3 使用 pnpm（高性能的 npm 替代品）#

3.4 使用 npx（免安装体验）#

3.5 安装方式对比#

4. 引导向导（openclaw onboard）#

4.1 选择 AI 模型提供商#

4.2 配置 API Key#

4.3 选择消息平台#

4.4 配置 Gateway#

4.5 完成配置#

5. macOS 安装完整流程#

5.1 使用 Homebrew（最简单）#

5.2 使用 nvm#

5.3 Apple Silicon 注意事项#

6. Linux 安装完整流程#

6.1 Ubuntu / Debian#

6.2 CentOS / RHEL#

6.3 Arch Linux#

6.4 权限问题处理#

7. Windows 安装完整流程#

7.1 WSL2 安装（强烈推荐）#

7.2 原生 Windows 安装#

7.3 WSL2 vs 原生安装对比#

8. Docker 快速安装#

9. 从 Git 仓库克隆并编译安装#

10. 升级和版本管理#

10.1 升级到最新版#

10.2 版本通道说明#

10.3 版本锁定#

10.4 回滚到旧版本#

10.5 升级注意事项#

11. 多环境部署#

11.1 开发环境#

11.2 测试环境#

11.3 生产环境#

11.4 使用不同配置文件#

12. 安装验证和健康检查#

12.1 基本验证#

12.2 启动 Gateway 并验证#

12.3 API 连通性测试#

12.4 Control UI 访问#

13. 常见安装问题排查#

13.1 权限问题#

13.2 网络问题#

13.3 Node.js 版本过低#

13.4 原生模块编译失败#

13.5 端口被占用#

13.6 API Key 无效#

13.7 WSL2 网络问题#

14. 卸载#

14.1 卸载 CLI#

14.2 清理配置和数据#

14.3 Docker 卸载#

下一步#

02. 安装部署指南

概述

1. 系统要求

1.1 硬件要求

1.2 操作系统要求

1.3 软件依赖

2. Node.js 环境安装

2.1 使用 nvm 安装（推荐）

2.2 使用官方安装包

2.3 使用 Homebrew（macOS）

2.4 安装方式对比

3. 安装 OpenClaw CLI

3.1 npm 全局安装（推荐）

3.2 使用 yarn

3.3 使用 pnpm（高性能的 npm 替代品）

3.4 使用 npx（免安装体验）

3.5 安装方式对比

4. 引导向导（openclaw onboard）

4.1 选择 AI 模型提供商

4.2 配置 API Key

4.3 选择消息平台

4.4 配置 Gateway

4.5 完成配置

5. macOS 安装完整流程

5.1 使用 Homebrew（最简单）

5.2 使用 nvm

5.3 Apple Silicon 注意事项

6. Linux 安装完整流程

6.1 Ubuntu / Debian

6.2 CentOS / RHEL

6.3 Arch Linux

6.4 权限问题处理

7. Windows 安装完整流程

7.1 WSL2 安装（强烈推荐）

7.2 原生 Windows 安装

7.3 WSL2 vs 原生安装对比

8. Docker 快速安装

9. 从 Git 仓库克隆并编译安装

10. 升级和版本管理

10.1 升级到最新版

10.2 版本通道说明

10.3 版本锁定

10.4 回滚到旧版本

10.5 升级注意事项

11. 多环境部署

11.1 开发环境

11.2 测试环境

11.3 生产环境

11.4 使用不同配置文件

12. 安装验证和健康检查

12.1 基本验证

12.2 启动 Gateway 并验证

12.3 API 连通性测试

12.4 Control UI 访问

13. 常见安装问题排查

13.1 权限问题

13.2 网络问题

13.3 Node.js 版本过低

13.4 原生模块编译失败

13.5 端口被占用

13.6 API Key 无效

13.7 WSL2 网络问题

14. 卸载

14.1 卸载 CLI

14.2 清理配置和数据

14.3 Docker 卸载

下一步