---
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="/zh-Hant/docs/openclaw/official/00-getting-started/quickstart" title="快速上手 OpenClaw" description="用 onboarding 跑通 Gateway、Dashboard 和第一條訊息。" />
  <Card href="/zh-Hant/docs/openclaw/official/00-getting-started/configuration" title="理解配置結構" description="安裝完成後，繼續理解 openclaw.json、schema、熱載入和金鑰邊界。" />
  <Card href="/zh-Hant/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)
