安裝程式內部機制

OpenClaw 提供三個安裝程式腳本，由 openclaw.ai 提供。

腳本	平台	功能說明
install.sh	macOS / Linux / WSL	視需要安裝 Node，透過 npm (預設) 或 git 安裝 OpenClaw，並可執行上手引導。
install-cli.sh	macOS / Linux / WSL	使用 npm 或 git checkout 模式，將 Node + OpenClaw 安裝到本地前綴 (~/.openclaw)。不需要 root 權限。
install.ps1	Windows (PowerShell)	視需要安裝 Node，透過 npm (預設) 或 git 安裝 OpenClaw，並可執行上手引導。

快速指令

install.shinstall-cli.shinstall.ps1

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

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

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

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

Note

如果安裝成功但在新終端機中找不到

openclaw

，請參閱

Node.js 疑難排解

。

---

install.sh

Tip

推薦用於 macOS/Linux/WSL 上的大多數互動式安裝。

流程 (install.sh)

1. 偵測作業系統

   支援 macOS 和 Linux (包括 WSL)。

2. 預設確保使用 Node.js 24

   檢查 Node 版本並在需要時安裝 Node 24 (macOS 上使用 Homebrew，Linux apt/dnf/yum 上使用 NodeSource 設定腳本)。在 macOS 上，僅當安裝程式需要 Homebrew 來安裝 Node 或 Git 時才會安裝它。為了相容性，OpenClaw 目前仍支援 Node 22 LTS，目前為 22.19+。 在 Alpine/musl Linux 上，安裝程式使用 apk 套件而非 NodeSource；設定的 Alpine 來源必須提供 Node 22.19+ (撰寫時為 Alpine 3.21 或更新版本)。

3. 確保已安裝 Git

   如果缺少 Git，則使用偵測到的套件管理員進行安裝，包括 macOS 上的 Homebrew 和 Alpine 上的 apk。

4. 安裝 OpenClaw

   • npm 方法 (預設)：全域 npm 安裝
   • git 方法：複製/更新儲存庫，使用 pnpm 安裝相依項，建構，然後在 ~/.local/bin/openclaw 安裝包裝程式

5. 安裝後任務

   • 盡力重新整理已載入的 gateway 服務（openclaw gateway install --force，然後重新啟動）
   • 在升級和 git 安裝時執行 openclaw doctor --non-interactive（盡力而為）
   • 在適當時嘗試入門（TTY 可用、未停用入門、且 bootstrap/config 檢查通過）

原始碼結帳偵測

如果在 OpenClaw checkout 內執行（package.json + pnpm-workspace.yaml），腳本會提供：

• 使用 checkout（git），或
• 使用全域安裝（npm）

如果沒有 TTY 可用且未設定安裝方法，它會預設為 npm 並發出警告。

對於無效的方法選擇或無效的 --install-method 值，腳本會以代碼 2 退出。

範例 (install.sh)

預設跳過入門Git 安裝GitHub main checkout試執行

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

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

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

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

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

參數旗標參考

Flag	Description
--install-method npm|git	選擇安裝方式 (預設: npm)。別名: --method
--npm	npm 方式的捷徑
--git	git 方式的捷徑。別名: --github
`—version

| npm 版本、dist-tag 或 package spec (預設:latest) | | —beta | 如果有可用的 beta dist-tag 則使用，否則回退至latest| |—git-dir

| Checkout 目錄 (預設:~/openclaw)。別名: —dir | |—no-git-update | 針對現有的 checkout 跳過git pull | |—no-prompt | 停用提示 | |—no-onboard | 跳過入門引導 | |—onboard | 啟用入門引導 | |—dry-run | 列印操作但不套用變更 | |—verbose | 啟用除錯輸出 (set -x，npm notice-level logs) | | —help | 顯示使用說明 (-h`) |

環境變數參考

變數	描述
OPENCLAW_INSTALL_METHOD=git|npm	安裝方法
`OPENCLAW_VERSION=latest|next|

|

| npm 版本、dist-tag 或 package spec | |OPENCLAW_BETA=0|1 | 如果有可用的 beta 版本則使用 | |OPENCLAW_HOME=

| OpenClaw 狀態和預設 git/onboarding 路徑的基礎目錄 | |OPENCLAW_GIT_DIR=

| 簽出目錄 | |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 日誌層級 |

---

install-cli.sh

Info

專為希望將所有內容都放在本地前綴 （預設

~/.openclaw

）下且無系統 Node 相依性的環境設計。預設支援 npm 安裝， 以及在相同前綴流程下的 git-checkout 安裝。

Flow (install-cli.sh)

1. 安裝本機 Node 執行環境

   下載一個固定的受支援 Node LTS tarball（版本嵌入在腳本中並獨立更新）到 `

   /tools/node-v

   並驗證 SHA-256。 在 Alpine/musl Linux 上，由於 Node 不會針對固定的執行環境發布相容的 tarball，因此會使用apk安裝nodejs和npm，並將該執行環境連結到前綴包裝程式路徑。Alpine 軟體庫必須提供 Node 22.19+`；如果較舊的軟體庫僅提供 Node 20 或 21，請使用 Alpine 3.21 或更新版本。

2. 確保 Git

   如果缺少 Git，會嘗試透過 Linux 上的 apt/dnf/yum/apk 或 macOS 上的 Homebrew 進行安裝。

3. 在前綴下安裝 OpenClaw

   • npm 方法（預設）：使用 npm 在前綴下安裝，然後將包裝器寫入 `

   /bin/openclaw -git方法：克隆/更新檢出（預設~/openclaw），並仍將包裝器寫入

   /bin/openclaw`

4. 重新整理已載入的閘道服務

   如果已經從相同的前綴載入了閘道服務，腳本會執行 openclaw gateway install --force，然後執行 openclaw gateway restart，並 盡力探測閘道健康狀態。

範例 (install-cli.sh)

預設自訂前綴 + 版本Git 安裝自動化 JSON 輸出執行入門引導

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

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

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

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

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

旗標參考

旗標	描述
`—prefix

| 安裝前綴（預設：~/.openclaw） | | —install-method npm|git | 選擇安裝方式（預設：npm）。別名：—method | |—npm | npm 方式的捷徑 | |—git, —github | git 方式的捷徑 | |—git-dir

| Git checkout 目錄（預設：~/openclaw）。別名：—dir | |—version

| OpenClaw 版本或 dist-tag（預設：latest） | | —node-version

| Node 版本（預設：22.22.0） | | —json | 發出 NDJSON 事件 | |—onboard | 安裝後執行openclaw onboard | |—no-onboard | 跳過引導（預設） | |—set-npm-prefix | 在 Linux 上，若當前前綴不可寫，強制 npm 前綴為~/.npm-global| |—help | 顯示用法（-h`） |

環境變數參考

變數	描述
`OPENCLAW_PREFIX=

| 安裝前綴 | |OPENCLAW_INSTALL_METHOD=git|npm | 安裝方式 | |OPENCLAW_VERSION=

| OpenClaw 版本或發行標籤 | |OPENCLAW_NODE_VERSION=

| Node 版本 | |OPENCLAW_HOME=

| OpenClaw 狀態及預設 git/onboarding 路徑的基礎目錄 | |OPENCLAW_GIT_DIR=

| git 安裝的 Git checkout 目錄 | |OPENCLAW_GIT_UPDATE=0|1 | 切換既有 checkouts 的 git 更新 | |OPENCLAW_NO_ONBOARD=1 | 跳過 onboarding | |OPENCLAW_NPM_LOGLEVEL=error|warn|notice` | npm 日誌層級 |

---

install.ps1

Flow (install.ps1)

1. 確保 PowerShell + Windows 環境

   需要 PowerShell 5+。

2. 預設確保 Node.js 24

   若缺失，將嘗試透過 winget、接著 Chocolatey、再來 Scoop 進行安裝。若無可用的套件管理器，腳本會將官方 Node.js Windows zip 下載至 %LOCALAPPDATA%\OpenClaw\deps\portable-node 並將其加入目前程序及使用者的 PATH。為相容性，Node 22 LTS（目前為 22.19+）仍持續支援。

3. 安裝 OpenClaw

   • npm 方式（預設）：使用選定的 -Tag 進行全域 npm 安裝，從可寫入的安裝程式暫存目錄啟動，因此在受保護資料夾（例如 C:\）中開啟的 shell 仍能正常運作
   • git 方式：clone/更新 repo，使用 pnpm 安裝/建置，並在 %USERPROFILE%\.local\bin\openclaw.cmd 安裝包裝器。若缺少 Git，腳本會在 %LOCALAPPDATA%\OpenClaw\deps\portable-git 下引導使用者本地的 MinGit 並將其加入目前程序及使用者的 PATH。

4. 安裝後任務

   • 盡可能將所需的 bin 目錄新增至使用者的 PATH
   • 盡力重新整理已載入的 gateway 服務（openclaw gateway install --force，然後重新啟動）
   • 在升級和 git 安裝時執行 openclaw doctor --non-interactive（盡力而為）

5. 處理失敗

   iwr ... | iex 和 scriptblock 安裝會回報終止錯誤，而不會關閉目前的 PowerShell 會話。直接 powershell -File / pwsh -File 安裝仍會以非零程式碼退出，以利自動化。

Examples (install.ps1)

預設Git 安裝GitHub main checkout自訂 git 目錄試執行除錯追蹤

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

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

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

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

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

powershell # install.ps1 has no dedicated -Verbose flag yet. Set-PSDebug -Trace 1 & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard Set-PSDebug -Trace 0

旗標參考

Flag	Description
-InstallMethod npm|git	安裝方式（預設：npm）
`-Tag

| npm dist-tag、版本或套件規格（預設：latest） | | -GitDir

| Checkout 目錄（預設：%USERPROFILE%\openclaw） | | -NoOnboard | 跳過 onboarding | |-NoGitUpdate | 跳過git pull | |-DryRun` | 僅列印動作 |

環境變數參考

變數	描述
OPENCLAW_INSTALL_METHOD=git|npm	安裝方法
`OPENCLAW_GIT_DIR=

| 簽出目錄 | |OPENCLAW_NO_ONBOARD=1 | 略過入門引導 | |OPENCLAW_GIT_UPDATE=0 | 停用 git pull | |OPENCLAW_DRY_RUN=1` | 試執行模式 |

Note

如果使用了

-InstallMethod git

且系統缺少 Git，該腳本會在列印 Git for Windows 連結之前，嘗試引導安裝使用者本地的 MinGit。

---

CI 與自動化

請使用非互動式 flags/env vars 以確保可預測的執行結果。

install.sh (非互動式 npm)install.sh (非互動式 git)install-cli.sh (JSON)install.ps1 (略過入門引導)

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

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

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

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

---

疑難排解

為什麼需要 Git？

git 安裝方法需要 Git。對於 npm 安裝，仍然會檢查/安裝 Git，以避免當相依套件使用 git URLs 時發生 spawn git ENOENT 失敗。

為什麼 npm 在 Linux 上會遇到 EACCES？

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

Windows：「npm error spawn git / ENOENT」

重新執行安裝程式以便其引導安裝使用者本地的 MinGit，或是安裝 Git for Windows 並重新開啟 PowerShell。

Windows: "無法辨識 openclaw"

執行 npm config get prefix 並將該目錄新增至您的使用者 PATH (Windows 上不需要 \bin 後綴)，然後重新開啟 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 疑難排解。

相關

• 安裝概觀
• 更新
• 解除安裝