安装 OpenClaw

安装 OpenClaw 最容易犯的错，不是命令输错，而是从一开始就选了不适合自己的安装通道。官方当前推荐安装脚本：它会识别系统、处理 Node 环境、安装 OpenClaw，并进入 onboarding。

1. 先选安装通道，不要先折腾 Node

新手的目标是让 OpenClaw 跑起来，而不是先设计 Node、pnpm、全局包路径和源码 checkout。

官方安装脚本是默认路径，适合 macOS、Linux、WSL2 和 Windows PowerShell。只有这几类情况，才考虑替代安装方式：

• 你已经自己管理 Node 和全局包路径。
• 你只想安装 CLI，不想立刻跑 onboarding。
• 你想把 OpenClaw 和 Node 放在本地 prefix，例如 ~/.openclaw。
• 你要贡献 OpenClaw 源码，需要本地 checkout。

flowchart TD
    Start["你要安装 OpenClaw"]
    Default["只是想先跑起来？"]
    Skip["想跳过 onboarding？"]
    Prefix["不想用系统全局 Node？"]
    Managed["已经有自己的 Node 管理方案？"]
    Contrib["要改 OpenClaw 源码？"]
    Script["用官方安装脚本"]
    NoOnboard["官方脚本加 no-onboard"]
    LocalPrefix["用 install-cli.sh"]
    Package["用 npm / pnpm / bun"]
    Source["从源码安装"]

    Start --> Default
    Default -->|是| Script
    Default -->|否| Skip
    Skip -->|是| NoOnboard
    Skip -->|否| Prefix
    Prefix -->|是| LocalPrefix
    Prefix -->|否| Managed
    Managed -->|是| Package
    Managed -->|否| Contrib
    Contrib -->|是| Source
    Contrib -->|否| Script

    style Script fill:#dcfce7,stroke:#22c55e,stroke-width:2px
    style NoOnboard fill:#e0f2fe,stroke:#0284c7,stroke-width:2px
    style Source fill:#fef3c7,stroke:#f59e0b,stroke-width:2px

2. 先看系统要求

官方安装页当前给出的基础要求可以压成这张表：

两个细节别忽略：

• 官方安装脚本会自动处理 Node 要求，所以普通用户不需要先手动搭完整 Node 开发环境。
• Bun 支持全局 CLI 安装路径，但 Gateway runtime 仍推荐 Node。

3. 官方脚本：默认首选

macOS / Linux / WSL2：

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

Windows PowerShell：

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

安装脚本默认会进入 onboarding。如果你只想先装 CLI，不想立刻配置：

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

Windows PowerShell 跳过 onboarding：

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

4. 替代安装路径怎么选

如果你想把 OpenClaw 和 Node 放在本地 prefix，例如 ~/.openclaw，可以用：

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

如果你已经自己管理 Node 环境，也可以用包管理器：

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

pnpm add -g openclaw@latest
pnpm approve-builds -g
openclaw onboard --install-daemon

bun add -g openclaw@latest
openclaw onboard --install-daemon

pnpm 有一个额外动作：全局安装带 build scripts 的包后，需要运行 pnpm approve-builds -g。

如果 npm 安装遇到 sharp / libvips 相关 build 错误，再按官方排障处理：

SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

5. 源码安装只适合贡献者

源码安装会引入 git clone、pnpm install、build、UI build、全局 link 等步骤。它比普通安装多很多失败点，不适合作为第一路径。

贡献者可以走：

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install && pnpm ui:build && pnpm build
pnpm link --global
openclaw onboard --install-daemon

也可以不 link，在仓库内用 pnpm openclaw ...。但如果你的目标只是使用 OpenClaw，不要从这里开始。

6. 安装后怎么验证

安装完成后按三步验证。

第一步，看 CLI 是否能找到：

openclaw --version

第二步，跑诊断：

openclaw doctor

第三步，确认 Gateway 状态：

openclaw gateway status

如果你希望登录或开机后自动启动，再看对应平台的托管启动方式：

7. 常见报错怎么判断

如果安装成功但当前终端找不到命令，先重开终端。很多时候不是安装失败，而是当前 shell 还没重新加载 PATH。

8. 本章自检

1. 不确定安装方式时，为什么先用官方脚本？
2. Node 24、Node 22.14+、pnpm 分别对应什么要求？
3. 安装后必须跑哪三条验证命令？

9. 接下来去哪

10. 官方资料

• Install
• Getting started
• Gateway CLI
• Doctor CLI