如何快速安裝 OpenClaw：安裝腳本運作機制詳解

每次想試用新工具，最煩的就是要先搞定環境。你要嘛發現電腦缺了 Node.js，要嘛就是遇到權限噴錯，最後花在設定環境的時間比實際使用的時間還多。

我們都遇過這種情況：看著一長串的安裝文件，心裡只想著能不能一行指令就搞定。這就是為什麼 OpenClaw 準備了自動化腳本，幫你處理掉這些瑣事，讓你直接進入重點。

需要準備的東西

在開始之前，請確認你的環境符合以下條件：

使用 macOS、Linux、WSL 或 Windows 系統
穩定的網路連線以從 openclaw.ai 下載檔案

快速開始

OpenClaw 提供了三種主要的安裝腳本，你可以根據你的作業系統和需求來選擇。

腳本	平台	功能說明
`install.sh`	macOS / Linux / WSL	必要時安裝 Node.js，透過 npm 或 git 安裝 OpenClaw，並執行 onboarding。
`install-cli.sh`	macOS / Linux / WSL	將 Node.js 與 OpenClaw 安裝到本地路徑 (`~/.openclaw`)，不需要 root 權限。
`install.ps1`	Windows (PowerShell)	必要時安裝 Node.js，透過 npm 或 git 安裝 OpenClaw，並執行 onboarding。

快速執行指令

你可以直接在終端機貼上對應的指令：

install.sh:

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash

如果你需要查看可用的參數，可以使用 help 指令：

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --help

install-cli.sh:

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash

查看更多選項：

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --help

install.ps1:

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

進階用法（例如安裝 beta 版本且不執行 onboarding）：

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

疑難排解

找不到 openclaw 指令

如果你看到安裝成功的訊息，但在新的終端機視窗輸入 openclaw 時，系統卻說找不到這個指令，這通常跟 Node.js 的路徑設定有關。

解決方案： 請參考 Node.js troubleshooting 文件的詳細說明來修正你的環境變數。

如果安裝過程還有其他問題，可以詢問我們的 AI Setup Assistant 獲取即時幫助。

下一步

Node.js troubleshooting

每次拿到一個新專案，最煩的就是要手動檢查環境。Node.js 版本對不對？Git 裝了沒？還要處理一堆相依性問題。如果能一行指令搞定這一切，開發生活會輕鬆很多。

我們提供的 install.sh 腳本就是為了幫你省下這些瑣事，自動幫你把開發環境調整到定位。

需要準備的東西

在開始之前，請確保你的環境符合以下條件：

使用 macOS、Linux 或 WSL (Windows Subsystem for Linux)
具備穩定的網路連線

快速開始

如果你想用最快的方式安裝 OpenClaw，直接執行這行指令就對了：

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash

安裝流程

當你執行該腳本時，它會自動完成以下動作：

1. 偵測作業系統

支援 macOS 與 Linux（包含 WSL）。如果偵測到 macOS，腳本會檢查並在必要時安裝 Homebrew。

2. 確保 Node.js 22+ 版本

檢查當前的 Node 版本，如有需要會自動安裝 Node 22（macOS 使用 Homebrew，Linux 則透過 NodeSource 設定腳本）。

3. 檢查 Git

如果系統中找不到 Git，腳本會自動幫你安裝。

4. 安裝 OpenClaw

npm 模式（預設）：執行全域 npm install。
- git 模式：複製或更新 Repo，使用 pnpm 安裝相依項並編譯，最後在 ~/.local/bin/openclaw 建立 wrapper。
5. 後續任務
Section titled “5. 後續任務”
升級或使用 git 安裝時，會執行 openclaw doctor --non-interactive。
- 在適當情況下（有 TTY、未停用 onboarding 且通過配置檢查）啟動 onboarding 流程。
- 預設設定 SHARP_IGNORE_GLOBAL_LIBVIPS=1。

本地開發偵測

如果你在已經包含 package.json 與 pnpm-workspace.yaml 的 OpenClaw 目錄中執行此腳本，它會詢問你：

使用當前目錄進行安裝 (git)
進行全域安裝 (npm)

使用範例

你可以根據需求在指令後方加上不同的參數：

預設安裝:

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash

跳過 Onboarding:

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --no-onboard

Git 安裝模式:

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git

測試執行 (Dry run):

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --dry-run

完整參數參考

Flags 列表

Flag	說明
`--install-method npm\|git`	選擇安裝方式 (預設: `npm`)。別名: `--method`
`--npm`	使用 npm 方式安裝的捷徑
`--git`	使用 git 方式安裝的捷徑。別名: `--github`
`--version <version\|dist-tag>`	指定 npm 版本或 dist-tag (預設: `latest`)
`--beta`	使用 beta 版本（若有），否則回退至 `latest`
`--git-dir <path>`	Git 複製目錄 (預設: `~/openclaw`)。別名: `--dir`
`--no-git-update`	針對現有的 git 目錄跳過 `git pull`
`--no-prompt`	停用互動式提示
`--no-onboard`	跳過 onboarding 流程
`--onboard`	強制啟用 onboarding 流程
`--dry-run`	僅列印執行動作而不套用變更
`--verbose`	啟用偵錯輸出 (`set -x` 與 npm notice 層級日誌)
`--help`	顯示幫助訊息 (`-h`)

環境變數參考

變數	說明
`OPENCLAW_INSTALL_METHOD=git\|npm`	安裝方式
`OPENCLAW_VERSION=latest\|next\|<semver>`	npm 版本或 dist-tag
`OPENCLAW_BETA=0\|1`	是否使用 beta 版本
`OPENCLAW_GIT_DIR=<path>`	Git 複製路徑
`OPENCLAW_GIT_UPDATE=0\|1`	是否更新 git
`OPENCLAW_NO_PROMPT=1`	停用提示
`OPENCLAW_NO_ONBOARD=1`	跳過 onboarding
`OPENCLAW_DRY_RUN=1`	啟動測試模式
`OPENCLAW_VERBOSE=1`	啟動偵錯模式
`OPENCLAW_NPM_LOGLEVEL=error\|warn\|notice`	設定 npm 日誌層級
`SHARP_IGNORE_GLOBAL_LIBVIPS=0\|1`	控制 sharp/libvips 行為 (預設: `1`)

疑難排解

如果你在安裝過程中遇到問題，請參考以下常見狀況：

無效的安裝方式：如果你在 --install-method 傳入了不支援的值，腳本會以結束碼 2 退出。
非互動式環境 (No TTY)：如果在沒有 TTY 且未指定安裝方式的環境執行，腳本會發出警告並預設使用 npm 模式。
權限問題：在某些 Linux 發行版上，安裝 NodeSource 或系統套件可能需要 sudo 權限。

還有疑問嗎？試試我們的 AI Setup Assistant 來獲取即時協助。

下一步

安裝完成後，你可以參考以下文件繼續配置：

每次要在新環境跑工具，最煩的就是處理 Node.js 版本相依性，或是擔心全域安裝會弄亂你原本的系統設定。如果你希望一切都乖乖待在指定的資料夾，且不需要手動去喬 Node.js 環境，install-cli.sh 就是幫你省時間的神器。

這個腳本專為「乾淨安裝」設計，預設會把所有東西塞進 ~/.openclaw，完全不會動到你系統原本的 Node.js 或是全域套件。

需要準備的東西

Linux 或 macOS 作業系統
curl 工具
基礎的終端機操作能力

快速開始

如果你想用最快的方式跑起來，直接貼上這行指令：

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash

腳本執行流程

當你執行腳本時，它會自動完成這四個動作：

安裝本地 Node.js runtime：下載 Node.js tarball（預設 22.22.0）到 <prefix>/tools/node-v<version> 並驗證 SHA-256 安全性。
確保 Git 環境：檢查系統是否有 Git，如果缺少的語，會嘗試透過 Linux 的 apt/dnf/yum 或 macOS 的 Homebrew 幫你裝好。
在指定路徑安裝 OpenClaw：使用 npm 的 --prefix 參數進行安裝。
建立執行檔：寫入一個 wrapper 到 <prefix>/bin/openclaw，讓你方便呼叫。

參數參考

CLI Flags

Flag	說明
`--prefix <path>`	安裝路徑 (預設: `~/.openclaw`)
`--version <ver>`	OpenClaw 版本或 dist-tag (預設: `latest`)
`--node-version <ver>`	Node.js 版本 (預設: `22.22.0`)
`--json`	輸出 NDJSON 事件
`--onboard`	安裝後立即執行 `openclaw onboard`
`--no-onboard`	跳過 onboarding (預設)
`--set-npm-prefix`	在 Linux 上，如果當前 prefix 不可寫入，強制將 npm prefix 設為 `~/.npm-global`
`--help`	顯示說明 (`-h`)

環境變數 (Environment variables)

變數	說明
`OPENCLAW_PREFIX=<path>`	安裝路徑
`OPENCLAW_VERSION=<ver>`	OpenClaw 版本或 dist-tag
`OPENCLAW_NODE_VERSION=<ver>`	Node.js 版本
`OPENCLAW_NO_ONBOARD=1`	跳過 onboarding
`OPENCLAW_NPM_LOGLEVEL=error\|warn\|notice`	npm 日誌層級
`OPENCLAW_GIT_DIR=<path>`	舊版清理路徑 (用於移除舊的 `Peekaboo` submodule)
`SHARP_IGNORE_GLOBAL_LIBVIPS=0\|1`	控制 sharp/libvips 行為 (預設: `1`)

疑難排解

Git 缺失：腳本會嘗試自動安裝，但如果你的環境限制較多（例如沒有 sudo 權限），建議先聯絡管理員裝好 Git。
權限問題：如果在 Linux 上遇到 prefix 無法寫入，可以加上 --set-npm-prefix 參數，腳本會嘗試改用 ~/.npm-global 來解決。

如果你在安裝過程遇到任何奇怪的問題，或是想了解更進階的配置，可以詢問我們的 AI Setup Assistant。

下一步

在 Windows 上開發最煩人的就是搞定環境。手動下載 Node.js、設定環境變數 PATH、處理各種相依性，光是準備好開發環境就耗掉大半天。如果你想在 Windows 上快速跑起 OpenClaw，這個 install.ps1 腳本就是為了幫你省下這些瑣事而設計的，它會自動處理大部分的繁瑣步驟。

需要準備的東西

在開始之前，請確保你的系統符合以下基本要求：

PowerShell 5 或更高版本
Node.js 22 或更高版本（如果你的電腦沒有安裝，腳本會嘗試幫你裝好）

快速開始

這個安裝腳本非常聰明，它會按照以下流程自動執行：

檢查環境：確認你的 PowerShell 版本與 Windows 環境。
檢查 Node.js：如果找不到 Node.js 22+，它會依序嘗試透過 winget、Chocolatey 或 Scoop 來安裝。
安裝 OpenClaw：
- npm 模式（預設）：直接透過 npm 全域安裝。
- git 模式：複製 Repo、使用 pnpm 編譯，並在 %USERPROFILE%\.local\bin\openclaw.cmd 建立捷徑。
後續處理：自動將路徑加入你的 PATH，並在升級或 git 安裝時執行 openclaw doctor 檢查狀態。

你可以根據需求選擇不同的安裝方式：

預設安裝:

這是最簡單的方式，直接執行：

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

Git 安裝:

如果你需要從原始碼安裝：

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

自定義 Git 目錄:

指定你要存放原始碼的位置：

& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -InstallMethod git -GitDir "C:\openclaw"

測試運行 (Dry run):

只想看看腳本會做什麼，而不實際更動系統：

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

進階配置

如果你有特殊需求，可以使用以下 Flags 或環境變數來調整安裝行為。

Flags 參考

Flag	描述
`-InstallMethod npm\|git`	安裝方式（預設：`npm`）
`-Tag <tag>`	npm 標籤（預設：`latest`）
`-GitDir <path>`	Repo 存放目錄（預設：`%USERPROFILE%\openclaw`）
`-NoOnboard`	跳過引導流程
`-NoGitUpdate`	跳過 `git pull`
`-DryRun`	僅印出執行動作，不實際安裝

環境變數參考

變數	描述
`OPENCLAW_INSTALL_METHOD=git\|npm`	安裝方式
`OPENCLAW_GIT_DIR=<path>`	Repo 存放目錄
`OPENCLAW_NO_ONBOARD=1`	跳過引導流程
`OPENCLAW_GIT_UPDATE=0`	禁用 git pull
`OPENCLAW_DRY_RUN=1`	開啟 Dry run 模式

疑難排解

在安裝過程中，你可能會遇到以下狀況：

找不到 Git：如果你使用了 -InstallMethod git 但系統沒裝 Git，腳本會直接停止執行。
解決方案：請先點擊腳本提供的 Git for Windows 連結進行安裝，完成後再重新執行腳本。

如果你在安裝過程中遇到任何奇怪的問題，可以隨時詢問我們的 AI Setup Assistant。

下一步

在跑 CI/CD 流程時，最怕遇到那種會突然停下來問你問題的安裝腳本。原本想說放著讓它自動跑完，結果回來發現它卡在一個「Do you want to continue? [Y/n]」的提示符號，這對自動化流程來說簡直是場災難。

要讓安裝過程在沒有人為干預的情況下順利完成，你需要學會使用非互動式旗標（non-interactive flags）與環境變數，確保每次執行的結果都符合預期。

需要準備的東西

curl (用於下載安裝腳本)
bash 或 PowerShell 環境
Git (如果你選擇 git 安裝方式)
Node.js 與 npm 環境

快速開始

這裡提供幾種在 5 分鐘內就能搞定的最小路徑，你可以根據你的環境選擇適合的指令。

使用 install.sh (非互動式 npm)

如果你想透過 npm 安裝並跳過所有引導詢問：

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --no-prompt --no-onboard

使用 install.sh (非互動式 git)

如果你偏好使用 git 安裝方式，可以透過環境變數來控制：

OPENCLAW_INSTALL_METHOD=git OPENCLAW_NO_PROMPT=1 \
  curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash

使用 install-cli.sh (JSON 格式)

如果你需要機器可讀的輸出結果，並指定安裝路徑：

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --json --prefix /opt/openclaw

Windows 環境 (PowerShell)

在 Windows 上你可以使用這行指令來跳過上線引導 (onboarding)：

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

疑難排解

如果你在自動化過程中撞牆了，這裡有幾個常見問題與對策：

為什麼一定要安裝 Git？ 如果你選用 git 安裝方式，Git 當然是必備的。但即使你用 npm 安裝，腳本還是會檢查或安裝 Git，這是為了避免當某些依賴項使用 git URLs 時，出現 spawn git ENOENT 的錯誤。

在 Linux 上 npm 遇到 EACCES 權限問題？ 有些 Linux 配置會將 npm global prefix 指向 root 擁有的路徑。install.sh 會嘗試將 prefix 切換到 ~/.npm-global 並把 PATH 匯出到你的 shell rc 檔案中。

關於 sharp/libvips 的編譯問題 腳本預設會設定 SHARP_IGNORE_GLOBAL_LIBVIPS=1，這是為了避免 sharp 直接拿系統的 libvips 來編譯而導致不相容。如果你想覆蓋這個設定：

SHARP_IGNORE_GLOBAL_LIBVIPS=0 curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash

Windows 報錯 “npm error spawn git / ENOENT” 請先安裝 Git for Windows，重新開啟 PowerShell 後再執行一次安裝程式。

Windows 報錯 “openclaw is not recognized” 請執行 npm config get prefix，在輸出的路徑後面加上 \bin，並將該目錄手動加入你的使用者 PATH 中，最後重開 PowerShell。

安裝完後找不到 openclaw 指令 這通常是 PATH 路徑沒設對的問題。你可以參考 Node.js troubleshooting 獲取更多細節。

如果遇到更棘手的環境問題，可以直接詢問我們的 AI Setup Assistant。

下一步

OpenClaw Expert

還是卡住了？

如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。

如何快速安裝 OpenClaw：安裝腳本運作機制詳解

需要準備的東西

快速開始

快速執行指令

疑難排解

找不到 openclaw 指令

下一步

需要準備的東西

快速開始

安裝流程

1. 偵測作業系統

2. 確保 Node.js 22+ 版本

3. 檢查 Git

4. 安裝 OpenClaw

5. 後續任務

本地開發偵測

使用範例

完整參數參考

Flags 列表

環境變數參考

疑難排解

下一步

需要準備的東西

快速開始

腳本執行流程

更多使用範例

參數參考

CLI Flags

環境變數 (Environment variables)

疑難排解

下一步

需要準備的東西

快速開始

進階配置

Flags 參考

環境變數參考

疑難排解

下一步

需要準備的東西

快速開始

使用 install.sh (非互動式 npm)

使用 install.sh (非互動式 git)

使用 install-cli.sh (JSON 格式)

Windows 環境 (PowerShell)

疑難排解

下一步

還是卡住了？