写在前面
这一页先把“安装前检查”直接做完，再带你走完后面的安装路径。
顺序固定就是 4 步：
- 先在这里检查前提；
- 再执行安装；
- 装完立刻验证；
- 如果失败，先分诊再决定下一跳。
如果你是第一次安装 OpenClaw，不要同时做安装、复杂配置、平台接入和排错。先把安装这条线走通。
适合谁
- 第一次准备安装 OpenClaw，需要先确认环境、版本和安装方式的人；
- 已经执行过安装命令，但不确定“算不算成功”的人；
- 装到一半卡住，分不清是 Node、权限、依赖还是版本资料混用导致的问题的人；
- 准备从首页直接进入实操，不想先翻完整 docs 的人。
你会完成什么
- 知道安装前必须确认哪些前提；
- 知道安装这一步应该真正做什么；
- 知道安装完成后应该怎么验证；
- 知道安装失败后第一轮该怎么分诊。
先在这里完成安装前检查
1. 先确认 Node.js 版本
先在终端执行：
node -v你应该看到 v22.x 或更高版本。
如果提示 command not found，或者版本低于 22，先不要继续装 OpenClaw，先把 Node.js 装好或升级到当前要求版本。
如果你不确定当前终端里到底在用哪个 Node，也可以继续执行：
which node
npm -v这一轮主要是确认：
- 当前终端确实能找到
node； npm也能正常使用；- 你操作的是预期环境，而不是另一个 shell、另一个 Node 管理器或旧路径。
2. 确认可用的模型 API Key
OpenClaw 装完以后，通常很快就会进入引导或配置阶段。这个时候如果你没有 API Key，流程很容易中断。
安装前至少先明确两件事：
- 你准备用哪个模型提供方；
- 你已经拿到了对应的 API Key。
如果你习惯先把 Key 放到环境变量里，可以先检查当前 shell 里有没有值：
printenv | rg 'OPENAI|ANTHROPIC|GEMINI|DEEPSEEK'如果没有输出也没关系，但你至少要知道稍后准备填哪一个 Key，而不是装到一半才开始找凭据。
3. 确认一个可写的工作目录
第一次安装时，不要把目标放在一个你自己都不确定权限的目录里。
先在终端确认当前目录和写入能力：
pwd
mkdir -p ~/openclaw-test
cd ~/openclaw-test
pwd如果你想进一步确认当前目录可写，可以执行：
touch .write-test && rm .write-test这样至少能排除一类很常见的问题：命令执行了，但后续配置文件、日志或状态目录根本写不进去。
4. 把第一次安装目标收小
第一次安装的目标只需要是下面这条线：
- 装好 OpenClaw；
- 跑完第一次引导；
- 能看到版本、状态或日志；
- 知道下一步去配置，不在安装阶段反复打转。
先不要同时追这些目标：
- 一次接多个聊天平台；
- 同时改很多配置字段；
- 一上来就折腾复杂代理、本地模型或插件；
- 还没验证成功就来回切换安装方式。
一个够用的最小检查流程
如果你只想快速确认“我现在能不能开始装”，按这个顺序做就够了：
node -v
which node
npm -v
mkdir -p ~/openclaw-test
cd ~/openclaw-test
touch .write-test && rm .write-test然后再问自己两个问题：
- API Key 是否已经准备好；
- 这次是否只追求先完成一次最小安装。
如果答案是“是”，就可以继续进入安装动作。
检查完成后按这个顺序继续
1. 直接进入安装动作
继续看 OpenClaw 怎么安装。
这一页会直接告诉你：
- CLI 怎么安装；
- 图形界面怎么安装；
- 什么是守护进程；
- 第一次安装时要不要顺手装守护进程。
这里不要继续做太多路径分析，按你的设备条件先完成一次安装。
2. 安装后立刻做成功验证
装完以后，马上进入 安装完成如何验证。
最少要建立这几类信号：
- 版本可读；
- 状态可读；
- 日志可读；
- 你知道下一步该去配置，而不是继续停留在安装阶段。
3. 如果已经报错，先做第一轮分诊
如果你当前已经报错，不要直接重装，先看 安装失败先看什么。
第一次安装失败，优先分成这几类：
- 环境前提问题；
- 安装路径混用；
- 资料版本混用；
- 最小启动没建立起来。
关键判断点
你只想最快看到第一次成功启动
那就把目标收敛成：完成安装、完成引导、完成状态验证。不要同时接多个通道或一口气改大量配置。
你已经执行过命令，但不知道为什么还是不稳
这通常不是继续重装的信号，而是说明你还没有建立“成功基线”。先看状态、日志和验证动作，再判断要不要继续。
你卡住的位置已经不再是安装，而是字段或通道问题
如果程序已经能启动，但行为不符合预期，就不要继续停留在安装阶段，应该转去配置页、平台接入页或故障排查页。
常见错误或风险
- 没查 Node 版本就直接执行安装命令；
- 还没准备好 API Key，就提前进入引导；
- 目录权限没确认，导致配置或状态文件落不下去；
- 不要把 install.sh、npm 全局安装、旧版教程和不同版本 release 说明混在一起执行；
- 第一次安装时不要同时修改模型、通道、插件和复杂权限设置；
- 如果你还没有建立版本、状态和日志这三类验证动作，就不算真正完成安装。
下一步
如果当前安装已经稳定，继续看 配置优先级怎么排。
如果当前安装还不稳定，先回 安装失败先看什么。
FAQ
第一次安装时最少要准备什么？
最少准备四样：支持的系统环境、Node.js 22+、一个可用的模型 API Key，以及一个你能稳定读写的目录。没有这四样，后面的命令很容易变成“看起来执行了，但其实没有落地”。
安装成功应该怎么判断？
至少满足两类信号：一类是 CLI 和向导信号，例如 openclaw --version 能正常返回；另一类是运行信号，例如状态可读、日志没有持续阻塞性报错、你知道如何继续到配置页。
安装时卡住了，第一反应应该做什么？
先停下重装冲动，记录当前报错位置，再去看安装失败分诊页。如果你连问题属于安装、启动还是配置都还没分清，直接去故障排查页。
安装阶段需要马上接 Telegram 或 Discord 吗？
不需要。第一次安装更稳妥的做法是先建立可启动、可诊断、可回退的基线。等这条基线成立，再去平台接入页接第一个通道。