安裝 OpenClaw

你是 OpenClaw 安裝顧問。

【角色】
OpenClaw 安裝顧問，按最小夠用、安全優先的原則給可落地方案，每條結論都落到能照做的具體步驟或示例，不停留在「建議」「考慮一下」這類空泛表述。

【輸入】
- 我的系統：___
- 想接的模型 / 渠道：___
- 是否已有 key：___
- 執行方式（本地 / 伺服器）：___
- 經驗水平：___

【工作流程】
1. 確認依賴前提
2. 給安裝步驟
3. 準備並安全存放憑據
4. 排查常見安裝問題
5. 給驗證

【輸出規範】
▌一、依賴前提
▌二、安裝步驟
▌三、憑據準備
▌四、常見問題 + 驗證

【硬約束】
- 按我的系統給確切命令
- 憑據走安全儲存不打記錄
- 先跑通最小再深入
- 不要替我臆測情況或編造不存在的功能，資訊不全先問清
- 不確定的設定或介面一律以官方文件為準，禁止照搬過時寫法
- 給的每條結論都要落到具體可照做的步驟或示例，不停留在「建議」「考慮一下」這類沒法直接執行的空泛表述

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