安裝程式內部機制

OpenClaw 三個安裝腳本的詳細說明，包含 install.sh、install-cli.sh 和 install.ps1 的流程、旗標和環境變數參考。

OpenClaw 提供三個安裝腳本，託管於 openclaw.ai。

腳本	平台	功能說明
`install.sh`	macOS / Linux / WSL	自動偵測並安裝 Node，透過 npm（預設）或 git 安裝 OpenClaw，可執行初始設定。
`install-cli.sh`	macOS / Linux / WSL	將 Node 和 OpenClaw 安裝到本地前綴路徑（`~/.openclaw`），無需 root 權限。
`install.ps1`	Windows (PowerShell)	自動偵測並安裝 Node，透過 npm（預設）或 git 安裝 OpenClaw，可執行初始設定。

快速指令

install.sh：

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

查看說明：

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

install.ps1：

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

如果安裝成功但在新終端機中找不到 openclaw，請參閱 Node.js 疑難排解。

install.sh

建議大多數 macOS/Linux/WSL 使用者採用此互動式安裝方式。

流程（install.sh）

偵測作業系統 — 支援 macOS 和 Linux（包含 WSL）。若偵測到 macOS，會在缺少 Homebrew 時自動安裝。
確保 Node.js 22+ — 檢查 Node 版本，必要時安裝 Node 22（macOS 使用 Homebrew，Linux 使用 NodeSource 設定腳本搭配 apt/dnf/yum）。
確保 Git — 若缺少 Git 則自動安裝。
安裝 OpenClaw — npm 方法（預設）：全域 npm 安裝；git 方法：複製/更新儲存庫，使用 pnpm 安裝相依套件並建置，然後將包裝器安裝至 ~/.local/bin/openclaw。
安裝後任務 — 在升級和 git 安裝時執行 openclaw doctor --non-interactive（盡力而為）；在適當情況下嘗試初始設定引導；預設設定 SHARP_IGNORE_GLOBAL_LIBVIPS=1。

原始碼目錄偵測

若在 OpenClaw 原始碼目錄（包含 package.json + pnpm-workspace.yaml）中執行，腳本會提供選擇：

使用原始碼目錄（git），或
使用全域安裝（npm）

若沒有 TTY 且未設定安裝方法，預設使用 npm 並顯示警告。

腳本在方法選擇無效或 --install-method 值無效時，會以退出碼 2 結束。

範例（install.sh）

預設安裝：

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

跳過初始設定：

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

模擬執行：

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

旗標參考

旗標	說明
`--install-method npm\|git`	選擇安裝方法（預設：`npm`）。別名：`--method`
`--npm`	npm 方法的快捷方式
`--git`	git 方法的快捷方式。別名：`--github`
`--version <version\|dist-tag>`	npm 版本或 dist-tag（預設：`latest`）
`--beta`	使用 beta dist-tag（若可用），否則回退至 `latest`
`--git-dir <path>`	原始碼目錄路徑（預設：`~/openclaw`）。別名：`--dir`
`--no-git-update`	跳過現有原始碼的 `git pull`
`--no-prompt`	停用提示
`--no-onboard`	跳過初始設定
`--onboard`	啟用初始設定
`--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>`	原始碼目錄路徑
`OPENCLAW_GIT_UPDATE=0\|1`	切換 git 更新
`OPENCLAW_NO_PROMPT=1`	停用提示
`OPENCLAW_NO_ONBOARD=1`	跳過初始設定
`OPENCLAW_DRY_RUN=1`	模擬執行模式
`OPENCLAW_VERBOSE=1`	除錯模式
`OPENCLAW_NPM_LOGLEVEL=error\|warn\|notice`	npm 日誌層級
`SHARP_IGNORE_GLOBAL_LIBVIPS=0\|1`	控制 sharp/libvips 行為（預設：`1`）

install-cli.sh

專為需要將所有元件安裝在本地前綴路徑（預設 ~/.openclaw）且不需要系統級 Node 相依的環境設計。

流程（install-cli.sh）

安裝本地 Node 執行環境 — 下載 Node 壓縮檔（預設 22.22.0）至 <prefix>/tools/node-v<version> 並驗證 SHA-256。
確保 Git — 若缺少 Git，嘗試透過 Linux 上的 apt/dnf/yum 或 macOS 上的 Homebrew 安裝。
在前綴路徑下安裝 OpenClaw — 使用 npm 搭配 --prefix <prefix> 安裝，然後將包裝器寫入 <prefix>/bin/openclaw。

範例（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 -- --prefix /opt/openclaw --version latest

自動化 JSON 輸出：

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

執行初始設定：

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

旗標參考

旗標	說明
`--prefix <path>`	安裝前綴路徑（預設：`~/.openclaw`）
`--version <ver>`	OpenClaw 版本或 dist-tag（預設：`latest`）
`--node-version <ver>`	Node 版本（預設：`22.22.0`）
`--json`	輸出 NDJSON 事件
`--onboard`	安裝後執行 `openclaw onboard`
`--no-onboard`	跳過初始設定（預設）
`--set-npm-prefix`	在 Linux 上，若當前前綴不可寫入，強制將 npm 前綴設為 `~/.npm-global`
`--help`	顯示用法（`-h`）

環境變數參考

變數	說明
`OPENCLAW_PREFIX=<path>`	安裝前綴路徑
`OPENCLAW_VERSION=<ver>`	OpenClaw 版本或 dist-tag
`OPENCLAW_NODE_VERSION=<ver>`	Node 版本
`OPENCLAW_NO_ONBOARD=1`	跳過初始設定
`OPENCLAW_NPM_LOGLEVEL=error\|warn\|notice`	npm 日誌層級
`OPENCLAW_GIT_DIR=<path>`	舊版清理查詢路徑（用於移除舊的 `Peekaboo` 子模組）
`SHARP_IGNORE_GLOBAL_LIBVIPS=0\|1`	控制 sharp/libvips 行為（預設：`1`）

install.ps1

流程（install.ps1）

確保 PowerShell + Windows 環境 — 需要 PowerShell 5+。
確保 Node.js 22+ — 若缺少，依序嘗試透過 winget、Chocolatey、Scoop 安裝。
安裝 OpenClaw — npm 方法（預設）：使用選定的 -Tag 進行全域 npm 安裝；git 方法：複製/更新儲存庫，使用 pnpm 安裝/建置，並將包裝器安裝至 %USERPROFILE%\.local\bin\openclaw.cmd。
安裝後任務 — 在可能的情況下將所需的 bin 目錄加入使用者 PATH，然後在升級和 git 安裝時執行 openclaw doctor --non-interactive（盡力而為）。

範例（install.ps1）

預設安裝：

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"

模擬執行：

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

除錯追蹤：

# install.ps1 尚未提供專用的 -Verbose 旗標。
Set-PSDebug -Trace 1
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
Set-PSDebug -Trace 0

旗標參考

旗標	說明
`-InstallMethod npm\|git`	安裝方法（預設：`npm`）
`-Tag <tag>`	npm dist-tag（預設：`latest`）
`-GitDir <path>`	原始碼目錄路徑（預設：`%USERPROFILE%\openclaw`）
`-NoOnboard`	跳過初始設定
`-NoGitUpdate`	跳過 `git pull`
`-DryRun`	僅列印操作

環境變數參考

變數	說明
`OPENCLAW_INSTALL_METHOD=git\|npm`	安裝方法
`OPENCLAW_GIT_DIR=<path>`	原始碼目錄路徑
`OPENCLAW_NO_ONBOARD=1`	跳過初始設定
`OPENCLAW_GIT_UPDATE=0`	停用 git pull
`OPENCLAW_DRY_RUN=1`	模擬執行模式

若使用 -InstallMethod git 且缺少 Git，腳本會結束並列印 Git for Windows 的連結。

CI 和自動化

使用非互動式旗標/環境變數以確保可預測的執行結果。

install.sh（非互動式 npm）：

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

install.sh（非互動式 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

install.ps1（跳過初始設定）：

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

疑難排解

為什麼需要 Git？

git 安裝方法需要 Git。即使是 npm 安裝，也會檢查/安裝 Git，以避免相依套件使用 git URL 時出現 spawn git ENOENT 錯誤。

為什麼 npm 在 Linux 上出現 EACCES？

某些 Linux 設定會將 npm 全域前綴指向 root 擁有的路徑。install.sh 可以將前綴切換為 ~/.npm-global 並在 shell rc 檔案中附加 PATH 匯出（當這些檔案存在時）。

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。

Windows：如何取得詳細的安裝程式輸出

install.ps1 目前未提供 -Verbose 開關。使用 PowerShell 追蹤進行腳本層級的診斷：

Set-PSDebug -Trace 1
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
Set-PSDebug -Trace 0

安裝後找不到 openclaw

通常是 PATH 問題。請參閱 Node.js 疑難排解。