安装：5 分钟跑通 OpenClaw

这节课是整套教程的动手起点，也是 OpenClaw 安装的主路径：一条官方安装命令 + 引导式 onboarding，从敲下命令到在浏览器里收到第一句 AI 回复，官方口径约 5 分钟——前提是你手上已经有 Claude Code / Codex CLI 登录或某家模型的 API Key，从零申请 Key 的时间另算（第 3 步会给出去处）。

桌面应用、Docker、npm 直装等备用方式在下一课单独讲；装不上、跑不通直接去装不上怎么办对照排查。本教程基于 v2026.10.9（已是「OpenClaw 2.0」之后的版本）。

学完你能做什么

在 macOS、Linux、Windows 上用一条命令完成 OpenClaw 安装
用 npx openclaw@latest 先试用一轮完整体验，再决定要不要正式安装
让 onboarding 自动复用你已有的 Claude Code / Codex 登录或 API Key，跳过手动配置
把 Gateway 装成后台服务，并用 openclaw gateway status 确认它监听 18789 端口
在 Control UI 里发出第一条消息，收到 AI 回复——完成从安装到对话的全程跑通

你现在的困境

搜「OpenClaw 安装」出来的教程版本不明，不少还是 Clawdbot / Moltbot 时代的旧命令，照抄就报错
想先试试这个工具再决定装不装，但很多工具连试用都要先注册一堆东西
好不容易跑起来了，一关终端进程就没了；第二天想接着用，又得从头查「它到底起没起来」

什么时候用这一招

当你需要：

在自己电脑上把 OpenClaw 正式跑起来——后面所有课程（接模型、接渠道、自动化）都建立在这一步上
走最快的安装路径：不挑环境、缺 Node 自动补、装完自动进引导

而且不想：

对着版本不明的旧教程踩坑
先去折腾桌面应用、Docker、源码编译这些备用路径
装完之后还一头雾水：Gateway 到底起没起来、去哪发消息

🎒 开始前的准备

读完 OpenClaw 是什么，知道 Gateway、onboarding、Control UI 这几个词指什么
（可后补）OpenClaw 2.0 新变化不是本课前提——想尽快跑通可以先跳过，回头再补版本背景
一台 macOS / Linux / Windows 电脑，一个能上网的终端
一张「模型通行证」：已有的 Claude Code 或 Codex CLI 登录，或任一模型 provider 的 API Key——没有也不拦路，第 3 步给出去处

系统要求

项目	要求	说明
操作系统	macOS / Linux / Windows	Windows 有三条路：Windows Hub 应用、PowerShell 安装器、WSL2 Gateway（本页走 PowerShell 安装器）
Node.js	24.16.0+（24.x）或 26.1.0+	官方强烈建议 24.22.1+ / 26.12.1+（安全修复）；Node 26 为推荐版本
没有 Node？	可以不提前装	官方安装器缺 Node 时会自动补：macOS 装 Node 26，Linux 装 Node 24 LTS

Node 版本细节与兼容性排查见官方 Node.js compatibility 文档。

核心思路

OpenClaw 安装到底装了什么？ 三样东西：

CLI——openclaw 命令，你与 OpenClaw 的入口
一份配置——onboarding 引导写入的「用哪家模型、拿什么凭据」
一个常驻 Gateway 进程——本机控制平面，会话、工具、渠道连接都归它管；Control UI、CLI、TUI 都是它的客户端

为什么能 5 分钟跑通？ 因为 onboarding 会自动检测你已有的 Claude Code / Codex CLI 登录或 API Key，用一次真实的模型调用（completion）验证通过后直接存进配置——已有可用凭据时，引导基本不需要你做什么。

起步路径不止一条，本页带你走前两条，第三条在下一课：

方式	适合谁	一句话
官方安装器（推荐）	想正式装好、长期用	检测系统、缺 Node 自动装、装完自动进 onboarding
`npx openclaw@latest`	先跑一圈再决定	一条命令拉起完整体验，Gateway 跑在当前终端
npm / pnpm / Bun 直装、桌面应用、Docker	自己管 Node、不想碰终端、要上服务器	见安装备用方式

还有一点先记住：刚装好时 Gateway 在终端前台运行——Ctrl+C 停止它，配置会保留；想让它开机常驻、不怕关终端，就用第 4 步装成后台服务。

跟我做

第 1 步：确认 Node 版本——OpenClaw 安装的环境前提

为什么：OpenClaw 是 Node.js 应用，Node 太旧会在后面每一步连环报错。先花 10 秒核对，省掉一小时排错。

bash

node --version

你应该看到：终端打印版本号。v24.16.0 以上的 24.x，或 v26.1.0 以上的 26.x 才合格（官方强烈建议 24.22.1+ / 26.12.1+ 的安全修复版本）。

对照三种情况：

打印出合格的 v24 / v26 → 直接进第 2 步
打印出 v20 / v22 或更旧 → 不在支持范围，先升级（见下方踩坑提醒第 1 条）
提示 command not found——没装也不怕：官方安装器缺 Node 时会自动补（macOS 装 Node 26，Linux 装 Node 24 LTS），可以直接进第 2 步
node --version 输出 ≥ 24.16.0 的 24.x 或 ≥ 26.1.0 的 26.x（或者确认交给安装器自动装）

第 2 步：一条命令完成 OpenClaw 安装

为什么：官方安装器是最快的主路径——它检测操作系统、需要时装 Node、安装 OpenClaw，然后自动启动 onboarding 引导。

方式 A（推荐）：官方安装器

macOS / Linux 用户（WSL2 里也是这条；macOS 安装和 Linux 安装用同一条命令）：

bash

curl -fsSL https://openclaw.ai/install.sh | bash

Windows 用户（PowerShell）：

powershell

iwr -useb https://openclaw.ai/install.ps1 | iex

你应该看到：安装器开始干活——检测系统 →（需要时）装 Node → 安装 OpenClaw → 自动进入 onboarding 向导，引导开头有一行指向官方安全指南的提示。

💡 只装、不进引导？

自动化批量安装可以跳过 onboarding：

bash

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard

powershell

& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard

安装器的全部参数见官方 Installer internals。

⚠️ 国内网络

官方文档没有提供国内镜像或下载加速方案，本文不猜测镜像地址。如果下载安装脚本或依赖时超时，先检查网络环境再重试；持续失败去装不上怎么办对照排查。

方式 B：`npx openclaw@latest` 先试用

不想先装？一条命令直接拉起完整的 OpenClaw：

bash

npx openclaw@latest

体验和方式 A 一样：照常进 onboarding、照常打开 web dashboard，Gateway 跑在当前这个终端里，Ctrl+C 停止后配置同样保留。跑完觉得喜欢，再走方式 A 正式安装。

终端里出现了 onboarding 向导（方式 A / 方式 B 都算）

第 3 步：完成 onboarding——复用你已有的模型凭据

为什么：OpenClaw 本体不带模型。onboarding 把「用哪家模型、拿什么凭据」一次配好——配好这一步，后面才有 AI 回复。

向导开始后选一个：

Quick start（推荐）：当你已有 Claude Code / Codex CLI 登录或某家 provider 的 API Key——OpenClaw 自动检测，用一次真实 completion 验证可用后保存配置，并打开 web dashboard。官方文档明确：已有可用 AI 访问时，除了开头那行安全提示，引导不会再问别的。
Custom setup：走一遍全部引导选项；当自动检测的路都不通时，向导会打开手动 provider 设置。

你应该看到：选 Quick start 后一路绿灯——检测到凭据 → 验证 → 保存配置 → 浏览器打开 dashboard，同时 Gateway 在当前终端前台运行起来。

💡 想反悔重新配？

openclaw configure 随时改设置；openclaw onboard --classic 打开经典逐步向导，重走一遍引导。

手上一张「通行证」都没有？两个出路：

去拿一家国产模型的 Key——DeepSeek、通义千问、智谱 GLM、Kimi、MiniMax、豆包/火山引擎、混元、千帆都有官方 provider 插件，连接模型总览之后 1.6–1.12 逐家讲配置
预算有限？本地模型教你用 Ollama、vLLM 把模型跑在自己机器上
onboarding 走完：终端里 Gateway 已启动，浏览器 dashboard 已打开（或已进入手动配置页）

第 4 步：把 Gateway 装成后台服务

为什么：Quick start 之后 Gateway 在终端前台跑——关掉终端它就停了。装成系统服务才能常驻后台，之后接渠道、定时任务、手机远程才有基础。

先按 Ctrl+C 停掉前台 Gateway（配置保留，不用重新 onboarding），然后：

bash

openclaw gateway install

你应该看到：服务安装完成的提示。它在这三个系统上分别落地为：macOS 的 LaunchAgent、Linux / WSL2 的 systemd 用户单元、原生 Windows 的计划任务（创建被拒时回退为用户级 Startup 启动项）。

openclaw gateway install 执行成功，没有报错

第 5 步：验证 Gateway 正在运行

为什么：后台服务看不见摸不着，一条命令确认它活着，再往下走。

bash

openclaw gateway status

你应该看到：Gateway 正在运行，监听默认端口 18789。

顺手做两件体检（可选）：

bash

openclaw --version   # 确认 CLI 可用
openclaw doctor      # 检查配置问题

你应该看到：--version 打印出版本号（本教程基准 v2026.10.9）；doctor 给出配置检查结果。

openclaw gateway status 显示 Gateway 监听 18789 端口

第 6 步：打开 Control UI，发出第一条消息

为什么：Control UI 是浏览器里的控制台，第一次对话就在这里完成——收到 AI 回复，「5 分钟跑通」才算真正达成。

bash

openclaw dashboard

你应该看到：浏览器打开 Control UI（默认地址 http://<host>:18789/）。在聊天框输入一条消息，比如「你好，介绍一下你自己」——几秒后收到 AI 回复。

到这里，「5 分钟跑通」完成：Gateway 常驻、凭据配好、第一句回复到手。Control UI 的完整用法见 Control UI：浏览器里的控制台。

💡 Gateway 默认只监听本机

装好后 Gateway 默认监听本机回环地址（loopback），端口 18789，外部机器访问不到——这是有意的安全默认。要远程访问必须配置认证，规则见安全加固（一）。

Control UI 里发出消息并收到了 AI 回复

检查点 ✅

openclaw --version 能打印版本号（本教程基准 v2026.10.9）
onboarding 复用了已有凭据，或手动配置好了一家 provider
openclaw gateway status 显示 Gateway 正在运行、监听 18789
openclaw dashboard 打开 Control UI，发出的消息收到了 AI 回复
Gateway 已装成后台服务——关掉终端不再影响它

踩坑提醒

❌ Node 版本过低（v20 / v22 都不行）

原因：OpenClaw 要求 Node 24.16.0+（24.x）或 26.1.0+，推荐 Node 26，强烈建议 24.22.1+ / 26.12.1+。v20、v22 不在支持范围。

bash

node --version
# v20.x.x、v22.x.x → 太旧
# v24.16.0+（24.x）或 v26.1.0+ → 合格

正确做法：先升级再装，或者干脆直接跑第 2 步的官方安装器——缺 Node 时它会自动补（macOS 装 Node 26，Linux 装 Node 24 LTS）。版本兼容的细账见装不上怎么办。

❌ `openclaw: command not found`

原因：官方安装文档的原话是「几乎总是 PATH 问题」——npm 全局 bin 目录不在你 shell 的 PATH 里。

三行自查：

bash

node -v           # Node 装了吗
npm prefix -g     # 全局包装在哪
echo "$PATH"      # 全局 bin 目录在 PATH 里吗

正确做法：对照装不上怎么办里的 PATH 修复步骤走；改过 PATH 记得重开终端让它生效。

❌ 关掉终端，以为 OpenClaw「坏了」

原因：Quick start 之后 Gateway 在终端前台运行——Ctrl+C 会停止它，关终端同理；但配置全都保留，你装的东西一点没少。

正确做法：想长期用就执行第 4 步的 openclaw gateway install 装成后台服务；临时用完 Ctrl+C 即可，不用重新 onboarding。

❌ 把「5 分钟」当成无条件的承诺

原因：官方的「约 5 分钟」有前提——手上已有 Claude Code / Codex CLI 登录或 provider API Key。从零注册账号、申请 Key、选模型的时间不算在内。

正确做法：先去连接模型总览选一家、把 Key 备好，再回来跑安装；onboarding 里选 Custom setup 可以手动配置。

进阶技巧（可选）

卡住了？一条命令自查。 openclaw triage：只读体检 → 生成一份脱敏的诊断提示（secrets、token、原始聊天内容、原始日志都不在内）→ 交给你机器上检测到的编码 agent（Claude Code、Codex CLI 或 OpenClaw 内置 agent）带着诊断接着修。

在你选中 agent 之前，任何数据都不离开你的机器；想自己动手，选 "just print the commands"。想直接读诊断结果，用 openclaw doctor。

自定义数据位置。 想把 OpenClaw 的目录指到别处，三个环境变量：

OPENCLAW_HOME——内部路径解析的主目录
OPENCLAW_STATE_DIR——覆盖状态目录
OPENCLAW_CONFIG_PATH——覆盖配置文件路径

Windows 三条路。 桌面用户官方最推荐 Windows Hub 应用（带安装界面、托盘状态、聊天），本页的 PowerShell 安装器是 CLI 路线，WSL2 适合把 Gateway 放进 Linux 子系统。三者的细节对比见安装备用方式。

npm 直装一句话。 自己管 Node 的开发者（Node 24.22.1+ / 26.12.1+）可以绕过安装脚本：

bash

npm install -g openclaw@latest --allow-scripts=openclaw
openclaw onboard --install-daemon

npm 12 或 11.16+ 照抄；npm 11.15 及更早去掉 --allow-scripts=openclaw。pnpm / Bun / Docker / 源码编译的完整对照见安装备用方式；想在服务器上 7×24 跑，见服务器部署。

本课小结

✅ OpenClaw 安装主路径跑通：macOS / Linux 一条 curl、Windows 一条 PowerShell，onboarding 自动复用已有凭据，Gateway 装成后台服务，Control UI 里收到第一句回复。

✅ 三种起步方式会选了：官方安装器（推荐，缺 Node 自动补）、npx openclaw@latest（先试用再决定）、npm 直装（自己管 Node 的人，细节在下一课）。

✅ 「5 分钟」的边界清楚了：前提是已有 Claude Code / Codex 登录或 API Key；从零拿 Key 的时间另算。

✅ 装完的默认状态心里有数：Gateway 监听 18789、默认只听本机；前台运行的 Gateway 关终端会停，装成服务后常驻。

命令	作用	说明
`curl -fsSL https://openclaw.ai/install.sh \| bash`	macOS / Linux / WSL2 安装	官方安装器，缺 Node 自动补
`iwr -useb https://openclaw.ai/install.ps1 \| iex`	Windows 安装	PowerShell 版官方安装器
`npx openclaw@latest`	一条命令试用	不正式安装也能跑完整流程
`openclaw onboard --install-daemon`	直装后 onboarding	npm / pnpm / Bun 直装用它
`openclaw gateway install`	装成后台服务	macOS LaunchAgent / Linux systemd / Windows 计划任务
`openclaw gateway status`	确认 Gateway 活着	应看到监听 18789
`openclaw dashboard`	打开 Control UI	第一次对话在这里
`openclaw triage`	卡住时一键诊断	只读体检 + 脱敏诊断

命令速查的完整清单见 CLI 命令与配置速查。

下一课预告

主路径跑通了，但它不是人人能走：公司电脑不让跑脚本、有人想要桌面 App、服务器上要的是 Docker。下一课安装备用方式：桌面应用、Docker 与 npm 把其余的路铺好。

你会学到：

Windows Hub 与 macOS 菜单栏应用怎么装——全程不碰终端
Docker / Podman 容器化部署的完整流程
npm / pnpm / Bun 直装的参数与各自的小坑
对照表：哪种场景选哪种安装方式

安装：5 分钟跑通 OpenClaw ​

学完你能做什么 ​

你现在的困境 ​

什么时候用这一招 ​

🎒 开始前的准备 ​

系统要求 ​

核心思路 ​

跟我做 ​

第 1 步：确认 Node 版本——OpenClaw 安装的环境前提 ​

第 2 步：一条命令完成 OpenClaw 安装 ​

方式 A（推荐）：官方安装器 ​

方式 B：npx openclaw@latest 先试用 ​

第 3 步：完成 onboarding——复用你已有的模型凭据 ​

第 4 步：把 Gateway 装成后台服务 ​

第 5 步：验证 Gateway 正在运行 ​

第 6 步：打开 Control UI，发出第一条消息 ​

检查点 ✅ ​

踩坑提醒 ​

❌ Node 版本过低（v20 / v22 都不行） ​

❌ openclaw: command not found ​

❌ 关掉终端，以为 OpenClaw「坏了」 ​

❌ 把「5 分钟」当成无条件的承诺 ​

进阶技巧（可选） ​

本课小结 ​

下一课预告 ​

安装：5 分钟跑通 OpenClaw

学完你能做什么

你现在的困境

什么时候用这一招

🎒 开始前的准备

系统要求

核心思路

跟我做

第 1 步：确认 Node 版本——OpenClaw 安装的环境前提

第 2 步：一条命令完成 OpenClaw 安装

方式 A（推荐）：官方安装器

方式 B：`npx openclaw@latest` 先试用

第 3 步：完成 onboarding——复用你已有的模型凭据

第 4 步：把 Gateway 装成后台服务

第 5 步：验证 Gateway 正在运行

第 6 步：打开 Control UI，发出第一条消息

检查点 ✅

踩坑提醒

❌ Node 版本过低（v20 / v22 都不行）

❌ `openclaw: command not found`

❌ 关掉终端，以为 OpenClaw「坏了」

❌ 把「5 分钟」当成无条件的承诺

进阶技巧（可选）

本课小结

下一课预告