---
title: "安装 OpenClaw"
description: "基于官方 OpenClaw 安装教程，面向新手讲清推荐安装、Node 要求、替代路径、源码安装和安装后验证。"
verifiedAt: "2026-05-06"
---

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

> [!NOTE]
> **这一章用 12 分钟换什么**：你会知道 Node 要求、该用哪条安装命令、什么时候用 npm / pnpm / bun / source，以及安装后怎么确认 Gateway 真的能跑。

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

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

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

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

| 安装通道 | 适合谁 | 新手建议 |
|------|------|------|
| 官方安装脚本 | 大多数个人用户 | 首选 |
| 官方脚本加 `--no-onboard` | 只先装 CLI，稍后再配置 | 可用 |
| `install-cli.sh` 本地 prefix | 不想依赖系统全局 Node | 谨慎用 |
| npm / pnpm / bun | 已经管理好 Node 环境的人 | 不作为首选 |
| source 安装 | 贡献者或必须跑本地 checkout | 新手跳过 |

```mermaid
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
```

> [!IMPORTANT]
> **一句话选择**：不知道选什么，就用官方安装脚本。已经装好后，再用 `openclaw doctor` 判断环境哪里需要修。

## 2. 先看系统要求

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

| 类型 | 要求 |
|------|------|
| Node | Node 24 推荐；Node 22.14+ 支持 |
| 系统 | macOS、Linux、Windows 原生、WSL2 |
| Windows | 原生可用；WSL2 更稳定 |
| pnpm | 只有从源码构建时才需要 |
| Gateway runtime | 推荐使用 Node |

两个细节别忽略：

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

> [!WARNING]
> **不要跨环境安装**：项目主要在 WSL2 里，就在 WSL2 终端里安装和运行 OpenClaw；项目在 Windows 原生路径里，就用 Windows 原生入口。不要一半在 PowerShell，一半在 WSL2。

## 3. 官方脚本：默认首选

macOS / Linux / WSL2：

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

Windows PowerShell：

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

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

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

Windows PowerShell 跳过 onboarding：

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

> [!TIP]
> **跳过 onboarding 不是跳过配置**：后面仍然要运行 `openclaw onboard --install-daemon`，否则 Gateway、模型认证和 workspace 都不会完整准备好。

## 4. 替代安装路径怎么选

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

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

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

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

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

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

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

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

```bash
SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest
```

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

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

贡献者可以走：

```bash
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 是否能找到：

```bash
openclaw --version
```

第二步，跑诊断：

```bash
openclaw doctor
```

第三步，确认 Gateway 状态：

```bash
openclaw gateway status
```

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

| 平台 | 管理方式 |
|------|------|
| macOS | LaunchAgent，可通过 `openclaw onboard --install-daemon` 或 `openclaw gateway install` 配置 |
| Linux / WSL2 | systemd user service，可用同一组命令配置 |
| Windows 原生 | 优先 Scheduled Task；失败时退到用户 Startup-folder 登录项 |

> [!CAUTION]
> **安装没验收前不要继续接 channel**：`openclaw --version`、`openclaw doctor`、`openclaw gateway status` 三步没过，就先别配置 Telegram、Discord、Slack 或远程访问。

## 7. 常见报错怎么判断

| 现象 | 大概率原因 | 先看什么 |
|------|------|------|
| `openclaw: command not found` | 全局 bin 没进 `PATH` | `npm prefix -g`、`echo "$PATH"` |
| Node 版本过低 | 旧 Node 仍在当前 shell 优先级前面 | `node -v`、shell 启动文件 |
| Windows 下行为不稳定 | 原生环境和 WSL2 混用 | 统一到一个环境 |
| `pnpm` 安装后不能用 | build scripts 未批准 | `pnpm approve-builds -g` |
| Gateway 状态异常 | onboarding 或 daemon 没完成 | `openclaw doctor`、`openclaw logs` |

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

> [!TIP]
> **安装排障先分三层**：命令找不到先看 `PATH`，Node 版本不对先看当前 shell 的 Node 优先级，Gateway 不健康再看 onboarding、daemon 和日志。

## 8. 本章自检

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

> [!IMPORTANT]
> **过关标准**：你能用一句话说清 —— “安装完成不等于可用，只有 CLI、doctor 和 Gateway 状态都能验证，才算 OpenClaw 入门环境准备好。”

## 9. 接下来去哪

<Cards>
  <Card href="/docs/openclaw/official/00-getting-started/quickstart" title="快速上手 OpenClaw" description="用 onboarding 跑通 Gateway、Dashboard 和第一条消息。" />
  <Card href="/docs/openclaw/official/00-getting-started/configuration" title="理解配置结构" description="安装完成后，继续理解 openclaw.json、schema、热加载和密钥边界。" />
  <Card href="/docs/openclaw/official/01-gateway-runtime/gateway-configuration" title="Gateway 配置" description="继续看 Gateway 启动、health、doctor、reload 和安全重启。" />
</Cards>

## 10. 官方资料

- [Install](https://docs.openclaw.ai/install)
- [Getting started](https://docs.openclaw.ai/start/getting-started)
- [Gateway CLI](https://docs.openclaw.ai/cli/gateway)
- [Doctor CLI](https://docs.openclaw.ai/cli/doctor)
