Skip to content
OpenClaw 书稿预览

第3章 5分钟安装：照着点就行

🎯 本章目标：学完这章，你能完成OpenClaw安装并发出第一条消息

⏱️ 预计时间：5分钟

📋 前置要求：已完成第2章（准备工作）

本章你将学会什么

Section titled “本章你将学会什么”
  • 检查并安装Node.js环境
  • 用一行命令安装OpenClaw
  • 运行向导完成初始化配置
  • 理解QuickStart和Manual的区别
  • 配置国内三家Coding Plan
  • 验证安装成功并发出第一条消息

3.1 环境检查：Node.js是什么？

Section titled “3.1 环境检查：Node.js是什么？”

3.1.1 Node.js简介

Section titled “3.1.1 Node.js简介”

Node.js是一个让JavaScript能在电脑本地运行的环境。简单说：

Node.js就像JavaScript的“运行底座”，让它能在浏览器之外的地方工作。

你不需要深入理解它，只需要确认电脑上已经安装了。

3.1.2 检查Node.js版本

Section titled “3.1.2 检查Node.js版本”

打开你的终端（Terminal），输入：

Terminal window
node --version

期望看到的结果：

v22.x.x

判断标准：

  • ✅ 版本 >= v22：可以继续
  • ❌ 版本 < v22：需要升级
  • ❌ 提示”command not found”：需要安装

3.1.3 如果Node.js不符合要求

Section titled “3.1.3 如果Node.js不符合要求”

macOS安装/升级

Section titled “macOS安装/升级”
Terminal window
# 使用Homebrew安装（推荐）
brew install node


# 如果已安装但版本低，升级
brew upgrade node

Windows安装/升级

Section titled “Windows安装/升级”

推荐方式：使用winget

Terminal window
winget install OpenJS.NodeJS.LTS

或者手动下载：

  1. 访问 https://nodejs.org
  2. 下载LTS版本（长期支持版）
  3. 按向导安装

💡 Windows用户注意：官方推荐在WSL2中运行OpenClaw，能避免很多奇怪问题。WSL2安装指南：https://docs.microsoft.com/zh-cn/windows/wsl/install

Linux安装/升级

Section titled “Linux安装/升级”

Ubuntu/Debian：

Terminal window
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

CentOS/RHEL/Fedora：

Terminal window
sudo dnf install nodejs

3.1.4 验证安装

Section titled “3.1.4 验证安装”

安装完成后，再次检查：

Terminal window
node --version
npm --version

两个命令都应该返回版本号。

⚠️ 常见问题：如果安装后还是提示”command not found”，尝试重启终端或重新登录系统。

3.2 安装命令：就一行，复制粘贴

Section titled “3.2 安装命令：就一行，复制粘贴”

确认Node.js >= v22后，执行安装命令：

Terminal window
npm install -g openclaw@latest

这行命令在做什么？（人话版）

  • npm：Node.js的包管理器
  • install：安装
  • -g：全局安装（在任何目录都能用openclaw命令）
  • openclaw@latest：安装 npm 上当前发布版（本书核验冻结点为 v2026.2.17）

等待时间：取决于你的网络，通常30秒到2分钟。

3.2.1 验证安装成功

Section titled “3.2.1 验证安装成功”
Terminal window
openclaw --version

期望看到类似输出：

2026.2.17

❌ 如果提示”command not found”

可能原因：npm全局路径未加入系统PATH

解决方法：

  1. 重启终端
  2. 如果还不行，检查npm全局路径：npm prefix -g
  3. 把返回的路径加入PATH环境变量

3.3 运行向导：openclaw onboard

Section titled “3.3 运行向导：openclaw onboard”

安装完成后，运行初始化向导：

Terminal window
openclaw onboard --install-daemon

参数说明：

  • onboard：运行初始化向导
  • --install-daemon：同时安装后台服务（推荐）

3.3.1 向导第一步：风险确认 + 已有配置处理

Section titled “3.3.1 向导第一步：风险确认 + 已有配置处理”

启动向导后，通常会先看到：

? I understand this is powerful and inherently risky. Continue?
❯ Yes
  No

这里选 Yes 继续。

如果你之前装过 OpenClaw，还会看到：

Existing config detected
...
? Config handling
❯ Use existing values
  Update values
  Reset

怎么选：

  • 首次安装：通常不会出现这一段，直接进入下一步。
  • 复装/换模型：选 Update values（推荐，保留其余稳定配置）。
  • 完全重来：选 Reset（谨慎）。

3.3.2 向导第二步：选择模式（Onboarding mode）

Section titled “3.3.2 向导第二步：选择模式（Onboarding mode）”

向导会问你：

? Onboarding mode
❯ QuickStart - Minimal setup, get running fast
  Manual - Full control over all settings

怎么选？

选项适合谁结果
QuickStart新手，想快速跑起来自动配置推荐设置
Manual想完全掌控配置逐个配置每个选项

我的建议：第一次选 QuickStart，后面可以随时改配置。

操作提醒：向导里的每一步都是“当前终端会话生效”，完成后建议直接在同一终端继续验证，不要中途切到别的机器。

3.3.3 向导第三步：先选模型厂商（Provider）

Section titled “3.3.3 向导第三步：先选模型厂商（Provider）”

向导会提示你选择模型提供商：

? Which model provider would you like to use?
  OpenAI
  ...
❯ KIMI
  MiniMax
  GLM
  Other (custom endpoint)

先选你在第2章申请的厂商（KIMI / MiniMax / GLM）。

3.3.4 向导第四步：再选鉴权方式（Auth method，容易漏）

Section titled “3.3.4 向导第四步：再选鉴权方式（Auth method，容易漏）”

在你选完厂商后，通常不会立刻要 Key，而是先进入该厂商的鉴权方式选择。

常见会看到类似：

? <Provider> auth method
❯ Coding Plan / OAuth
  API Key

国内读者建议：优先选 Coding Plan 对应项。

  • KIMI：优先 Kimi Code API key (subscription) 路径
  • MiniMax：优先 MiniMax OAuth（CN）路径
  • GLM（Z.AI）：优先 Coding-Plan-CN 路径

3.3.5 向导第五步：输入API Key并选模型

Section titled “3.3.5 向导第五步：输入API Key并选模型”

如果选择KIMI

Section titled “如果选择KIMI”
? Enter your KIMI API Key: [粘贴你的Key]
? Select model: ❯ kimi-k2.5

如果选择MiniMax

Section titled “如果选择MiniMax”
? Enter your MiniMax API Key: [粘贴你的Key]
? Select model: ❯ MiniMax-M2.5

如果选择GLM

Section titled “如果选择GLM”
? Enter your GLM API Key: [粘贴你的Key]
? Select model: ❯ glm-5

💡 提示：粘贴API Key时，终端不会显示任何字符（为了安全），这是正常的。直接粘贴后按回车即可。

3.3.6 向导第六步：配置Channel（先Skip！）

Section titled “3.3.6 向导第六步：配置Channel（先Skip！）”

在 QuickStart 路径下，向导会直接进入渠道单选列表：

? Select channel (QuickStart)
  ...
  Feishu/Lark (飞书)
  ...
❯ Skip for now (You can add channels later via `openclaw channels add`)

首次建议直接选 Skip for now。

为什么先Skip？

这是多轮实测验证出的最佳实践：

  1. 先把”TUI里能稳定对话”跑通
  2. 确认模型、鉴权、Gateway都正常
  3. 再接入渠道，出错时能明确判断是”渠道配置问题”还是”基础环境问题”

放心，第5章会详细讲飞书接入。

3.3.7 向导第七步：配置 Skills（建议开）

Section titled “3.3.7 向导第七步：配置 Skills（建议开）”

Channel 之后，向导会进入 Skills 检查与可选安装：

Skills status
Eligible: ...
Missing requirements: ...
...


? Configure skills now? (recommended)
❯ Yes
  No

首次建议选 Yes，原因很简单：
现在就把“能自动装的依赖”装掉，后面少踩坑。

接下来常见会看到：

? Install missing skill dependencies
❯ Skip for now
  <某个 skill 依赖项...>


? Preferred node manager for skill installs
❯ npm
  pnpm
  bun

给新手的默认建议：

  1. 如果你只想先跑通主线：可先 Skip for now；
  2. 如果你准备立刻玩 Skills：按需勾选安装项；
  3. node manager 选你本机已经在用的那个（不确定就用 npm）。

3.3.8 向导第八步：配置 Hooks（建议最小开启）

Section titled “3.3.8 向导第八步：配置 Hooks（建议最小开启）”

Skills 后会进入 Hooks 配置：

Hooks
...
? Enable hooks?
❯ Skip for now
  <hook 列表...>

官方说明里，Hooks 用来“在某些命令触发时自动执行动作”（例如 /new 时做会话记忆整理）。

本书建议的最小策略：

  1. 首次可先启用 1 个最核心 hook（最小可用，优先 session-memory，若列表里有）；
  2. 如果你现在还分不清 hook 的作用，也可以先 Skip for now；
  3. 先跑通主线，后面在第10章再系统化管理 hooks。

3.3.9 向导第九步：选择 Hatch 方式（关键）

Section titled “3.3.9 向导第九步：选择 Hatch 方式（关键）”

在收尾阶段，向导会给你一个启动入口选择：

? How do you want to hatch your bot?
❯ Hatch in TUI (recommended)
  Open the Web UI
  Do this later

怎么选：

  • Hatch in TUI (recommended)：在终端里直接进入交互（最稳，推荐默认选这个）
  • Open the Web UI：打开浏览器控制台（图形化）
  • Do this later：先结束向导，稍后再进

为什么默认选 TUI：

  1. 我们无法假设你一定在本机操作；很多读者是在云主机/VPS 上跑。
  2. 如果是 VPS，Open the Web UI 往往还要做端口转发，对新手不友好。
  3. 选 Hatch in TUI 可以立刻开始对话，不被网络与端口问题卡住。

3.3.10 向导第十步：记录 Dashboard 链接与 Gateway 状态

Section titled “3.3.10 向导第十步：记录 Dashboard 链接与 Gateway 状态”

在你完成 Hatch 选择后，向导会输出控制台访问信息与网关状态（如 Web UI、Gateway WS、Gateway: reachable）。

如果你选了 Open the Web UI，一般会直接给出带 token 的 Dashboard 链接并尝试自动打开浏览器。

如果你选了 Do this later，后续可用：

Terminal window
openclaw dashboard --no-open

再次获取控制台入口。

3.4 首次对话：先完成 bootstrap（真正初始化）

Section titled “3.4 首次对话：先完成 bootstrap（真正初始化）”

onboard 完成后，建议先在 TUI 里完成第一轮 bootstrap 对话。

官方流程会把它当成“把 Agent 变成你的 Agent”的关键动作（源码里有 Wake up, my friend! 引导）。

这一步建议你主动讲清楚下面 5 件事：

  1. 你是谁：怎么称呼你、你的时区和工作语言。
  2. 你要它扮演什么角色：比如“我的技术写作助手”。
  3. 你平时的工作场景：常用工具、文件目录、沟通方式（飞书/邮件等）。
  4. 你的偏好：回答风格、长度、是否先给结论。
  5. 你的边界：哪些操作必须先确认、哪些内容不要碰。

这一步做得越清楚，后续它越像“你自己的实例”，而不是“一个通用聊天机器人”。

💡 你也可以把这些信息落盘到工作区里的 BOOTSTRAP.md / IDENTITY.md / USER.md / SOUL.md，让后续会话更稳定。

3.5 Bootstrap 后，再发第一条“低上下文”消息

Section titled “3.5 Bootstrap 后，再发第一条“低上下文”消息”

完成 bootstrap 后，建议先发一条不依赖你工作背景的消息做冒烟测试。

推荐你先用这条：

请给我一个“今天就能执行”的 5 条待办清单（每条不超过 18 个字），并按优先级排序。

如果你想测“查询能力”，可再补一条：

请告诉我北京今天的天气，并给出穿衣建议（1 句话）。

按回车发送。

期望的回复：

它应该直接给出结构化结果（清单或天气建议），而不是继续做泛泛自我介绍。

如果看到回复，恭喜你！安装成功！

3.6 如果出错了怎么办

Section titled “3.6 如果出错了怎么办”

3.6.1 问题一：Gateway启动失败

Section titled “3.6.1 问题一：Gateway启动失败”

症状：向导提示Gateway failed to start

可能原因：

  1. 端口18789被占用
  2. 权限不足
  3. 配置文件错误

解决方法：

Terminal window
# 查看端口占用
lsof -i :18789


# 或者换端口启动
openclaw gateway start --port 18790

3.6.2 问题二：发送消息无回复

Section titled “3.6.2 问题二：发送消息无回复”

症状：消息发送后，一直显示”正在输入”但没有回复

可能原因：

  1. API Key错误
  2. 网络不通
  3. 模型服务异常

解决方法：

Terminal window
# 检查配置
openclaw config get


# 检查模型连接
openclaw doctor


# 查看日志
openclaw logs

3.6.3 问题三：Web UI打不开

Section titled “3.6.3 问题三：Web UI打不开”

症状：浏览器访问127.0.0.1:18789显示无法连接

可能原因：

  1. Gateway没启动
  2. 防火墙阻挡
  3. 地址输错

解决方法：

Terminal window
# 确认Gateway在运行
openclaw status


# 如果未运行，手动启动
openclaw gateway start

本章小结

Section titled “本章小结”

来，回顾一下今天的成果：

  1. ✅ 检查了Node.js环境（>= v22）
  2. ✅ 安装了OpenClaw（npm install -g openclaw@latest）
  3. ✅ 运行了初始化向导（openclaw onboard --install-daemon）
  4. ✅ 配置了国内Coding Plan（KIMI/MiniMax/GLM）
  5. ✅ 在收尾阶段选择了 Hatch in TUI (recommended)（默认推荐）
  6. ✅ 完成了首次 bootstrap（把实例初始化成“你的实例”）
  7. ✅ 发出了第一条业务消息！

下一步：第4章，学习解决安装阶段最常见的问题。或者如果你迫不及待想接入飞书，可以直接跳到第5章。

动手试试

Section titled “动手试试”
  1. 在 TUI 里继续对话，补充你的工作边界、偏好与禁区（完成 bootstrap）
  2. 让它基于你的真实场景给出一个可执行清单（例如今天待办）
  3. 如果你在本机环境，再额外打开 Dashboard/Web UI 对照体验一次
  4. 如果安装过程中遇到问题，记录错误信息，对照第4章排查