OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Install overview

安裝程式內部機制

OpenClaw 提供三個安裝程式指令碼，由 openclaw.ai 提供。

指令碼 平台 功能
install.sh macOS / Linux / WSL 視需要安裝 Node，透過 npm（預設）或 git 安裝 OpenClaw，並可執行初始設定。
install-cli.sh macOS / Linux / WSL 透過 npm 或 git 將 Node + OpenClaw 安裝至本機前綴路徑（~/.openclaw）。不需要 root 權限。
install.ps1 Windows (PowerShell) 視需要安裝 Node，透過 npm（預設）或 git 安裝 OpenClaw，並可執行初始設定。

這三者皆支援 Node 22.22.3+、24.15+ 或 25.9+；全新安裝預設以 Node 24 為目標版本。

快速指令

install.sh

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 -- --help

install-cli.sh

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 -- --help

install.ps1

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

install.sh

流程（install.sh）

  • 偵測作業系統

    支援 macOS 和 Linux（包括 WSL）。

  • 預設確保使用 Node.js 24

    檢查 Node 版本，並視需要安裝 Node 24（macOS 使用 Homebrew，Linux 則使用適用於 apt/dnf/yum 的 NodeSource 設定指令碼）。在 macOS 上，僅當安裝程式需要 Homebrew 來安裝 Node 或 Git 時才會安裝它。支援 Node 22.22.3+、Node 24.15+ 和 Node 25.9+；不支援 Node 23。 在 Alpine/musl Linux 上，安裝程式會使用 apk 套件而非 NodeSource，並驗證實際連結的 SQLite 版本。目前穩定版 Alpine 套件來源可能會提供版本夠新的 Node，但其系統 SQLite 存在漏洞；遇到此情況時，請改用官方 node:24-alpine 容器或以 glibc 為基礎的主機。

  • 確保已安裝 Git

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

  • 安裝 OpenClaw

    • npm 方法（預設）：全域 npm 安裝
    • git 方法：複製或更新儲存庫、使用 pnpm 安裝相依套件、建置，然後在 ~/.local/bin/openclaw 安裝包裝程式

  • 安裝後工作

    • 解析剛安裝的 openclaw 執行檔，以供後續指令使用
    • 對於尚未設定的安裝，會在 doctor 或閘道探測之前啟動初始設定。使用 --no-onboard 或沒有 TTY 時，會列印稍後完成設定所需的指令。
    • 對於已設定的安裝，會以盡力而為的方式重新整理並重新啟動已載入的閘道服務，然後執行 doctor。升級時會盡可能更新外掛；若在無頭但已啟用提示的執行環境中，則會列印手動指令。
    • 執行 --verify 時，會檢查已安裝的版本，且僅在設定存在後才檢查閘道健康狀態。

    • 原始碼簽出偵測

    如果在 OpenClaw 簽出目錄（package.json + pnpm-workspace.yaml）中執行，指令碼會提供以下選項：

    • 使用簽出目錄（git），或
    • 使用全域安裝（npm）

    如果沒有可用的 TTY 且未設定安裝方法，則預設使用 npm 並顯示警告。

    若選擇了無效的安裝方法或 --install-method 值無效，指令碼會以代碼 2 結束。

    範例（install.sh）

    預設

    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

    Git 安裝

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

    GitHub main 簽出

    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

    安裝後驗證

    bash
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --no-onboard --verify
    旗標參考
    旗標 說明
    --install-method | --method npm|git 選擇安裝方法（預設：npm）
    --npm npm 方法的捷徑
    --git | --github git 方法的捷徑
    --version <version|dist-tag|spec> npm 版本、dist-tag 或套件規格（預設：latest）
    --beta 若 beta dist-tag 可用則使用，否則退回 latest
    --git-dir | --dir <path> 簽出目錄（預設：~/openclaw）
    --no-git-update 對現有簽出目錄略過 git pull
    --no-prompt 停用提示
    --no-onboard 略過初始設定
    --onboard 啟用初始設定
    --verify 執行安裝後冒煙驗證（--version，若已載入則檢查閘道健康狀態）
    --dry-run 僅列印動作而不套用變更
    --verbose 啟用偵錯輸出（set -x、npm notice 層級記錄）
    --help | -h 顯示用法
    環境變數參考
    變數 說明
    OPENCLAW_INSTALL_METHOD=git|npm 安裝方法
    OPENCLAW_VERSION=latest|next|<semver>|<spec> npm 版本、dist-tag 或套件規格
    OPENCLAW_BETA=0|1 若 beta 可用則使用
    OPENCLAW_HOME=<path> OpenClaw 狀態及預設 git/初始設定路徑的基礎目錄
    OPENCLAW_GIT_DIR=<path> 簽出目錄
    OPENCLAW_GIT_UPDATE=0|1 切換 git 更新
    OPENCLAW_NO_PROMPT=1 停用提示
    OPENCLAW_VERIFY_INSTALL=1 執行安裝後冒煙驗證
    OPENCLAW_NO_ONBOARD=1 略過初始設定
    OPENCLAW_DRY_RUN=1 試執行模式
    OPENCLAW_VERBOSE=1 偵錯模式
    OPENCLAW_NPM_LOGLEVEL=error|warn|notice npm 記錄層級（預設：error，隱藏 npm 棄用雜訊）

    install-cli.sh

    流程（install-cli.sh）

  • 安裝本機 Node 執行環境

    將固定版本且受支援的 Node LTS tarball（版本內嵌於指令碼中並獨立更新，預設為 24.15.0）下載至 <prefix>/tools/node-v<version>，並驗證 SHA-256。 Linux ARMv7 使用 Node 22.22.3，因為官方未提供 Node 24+ ARMv7 執行檔。 在 Alpine/musl Linux 上，由於 Node 未針對固定執行環境發布相容的 tarball，因此會使用 apk 安裝 nodejs 和 npm，然後驗證 Node 和實際連結的 SQLite 程式庫。目前穩定版 Alpine 套件來源即使提供版本夠新的 Node，仍可能連結至有漏洞的 SQLite；若安全檢查拒絕該套件，請使用官方 node:24-alpine 容器或以 glibc 為基礎的主機。

  • 確保已安裝 Git

    若缺少 Git，則嘗試透過 Linux 上的 apt/dnf/yum/apk 或 macOS 上的 Homebrew 安裝。

  • 在前綴路徑下安裝 OpenClaw

    • npm 方法（預設）：使用 npm 安裝至前綴路徑下，然後將包裝程式寫入 <prefix>/bin/openclaw
    • git 方法：複製或更新簽出目錄（預設為 ~/openclaw），並仍將包裝程式寫入 <prefix>/bin/openclaw

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

    如果已從相同前綴路徑載入閘道服務，指令碼會執行 openclaw gateway install --force，接著執行 openclaw gateway restart，並 以盡力而為的方式探測閘道健康狀態。

    • 範例（install-cli.sh）

    預設

    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

    Git 安裝

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

    自動化 JSON 輸出

    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 <path> 安裝前綴（預設：~/.openclaw）
    --install-method | --method npm|git 選擇安裝方式（預設：npm）
    --npm npm 方式的捷徑
    --git | --github git 方式的捷徑
    --git-dir | --dir <path> Git 簽出目錄（預設：~/openclaw）
    --version <ver> OpenClaw 版本或 dist-tag（預設：latest）
    --node-version <ver> Node 版本（預設：24.15.0；Linux ARMv7 上為 22.22.3）
    --json 輸出 NDJSON 事件
    --onboard 安裝後執行 openclaw onboard
    --no-onboard 略過初始設定（預設）
    --set-npm-prefix 在 Linux 上，如果目前的前綴不可寫入，強制將 npm 前綴設為 ~/.npm-global
    --help | -h 顯示用法
    環境變數參考
    變數 說明
    OPENCLAW_PREFIX=<path> 安裝前綴
    OPENCLAW_INSTALL_METHOD=git|npm 安裝方式
    OPENCLAW_VERSION=<ver> OpenClaw 版本或 dist-tag
    OPENCLAW_NODE_VERSION=<ver> Node 版本
    OPENCLAW_HOME=<path> OpenClaw 狀態及預設 git／初始設定路徑的基礎目錄
    OPENCLAW_GIT_DIR=<path> git 安裝的 Git 簽出目錄
    OPENCLAW_GIT_UPDATE=0|1 切換現有簽出目錄的 git 更新
    OPENCLAW_NO_ONBOARD=1 略過初始設定
    OPENCLAW_NPM_LOGLEVEL=error|warn|notice npm 記錄層級（預設：error）

    install.ps1

    流程（install.ps1）

  • 確認 PowerShell 與 Windows 環境

    需要 PowerShell 5+。

  • 確認預設使用 Node.js 24

    如果缺少，會依序嘗試透過 winget、Chocolatey、Scoop 安裝。如果沒有可用的套件管理工具，指令碼會將官方 Node.js 24 Windows zip 下載至 %LOCALAPPDATA%\OpenClaw\deps\portable-node，並將其加入目前處理程序及使用者 PATH。支援 Node 22.22.3+、Node 24.15+ 和 Node 25.9+；不支援 Node 23。

  • 安裝 OpenClaw

    • npm 方式（預設）：使用所選的 -Tag 執行全域 npm 安裝，並從可寫入的安裝程式暫存目錄啟動，因此即使在 C:\ 等受保護資料夾中開啟的 shell 仍可正常運作
    • git 方式：複製／更新儲存庫、使用 pnpm 安裝／建置，並在 %USERPROFILE%\.local\bin\openclaw.cmd 安裝包裝程式。如果缺少 Git，指令碼會在 %LOCALAPPDATA%\OpenClaw\deps\portable-git 下啟動使用者本機的 MinGit，並將其加入目前處理程序及使用者 PATH。

  • 安裝後工作

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

  • 處理失敗

    iwr ... | iex 和指令碼區塊安裝會回報終止錯誤，但不會關閉目前的 PowerShell 工作階段。直接執行 powershell -File／pwsh -File 安裝時，仍會以非零狀態結束，以便自動化處理。

    • 範例（install.ps1）

    預設

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

    Git 安裝

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

    GitHub main 簽出

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

    自訂 git 目錄

    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
    旗標參考
    旗標 說明
    -InstallMethod npm|git 安裝方式（預設：npm）
    -Tag <tag|version|spec> 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 試執行模式

    CI 與自動化

    使用非互動式旗標／環境變數，以確保執行結果可預期。

    install.sh（非互動式 npm）

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

    install.sh（非互動式 git）

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

    install-cli.sh（JSON）

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

    install.ps1（略過初始設定）

    powershell
    & ([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，並將 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 追蹤進行指令碼層級的診斷：

    powershell
    Set-PSDebug -Trace 1& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboardSet-PSDebug -Trace 0
    安裝後找不到 openclaw

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

    相關內容

    Was this useful?
    On this page

    On this page