安裝 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