English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisहिन्दीالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiРусскийفارسیไทย
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk 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 checkout 模式，將 Node + OpenClaw 安裝到本機前置目錄（~/.openclaw）。不需要 root 權限。
install.ps1 Windows (PowerShell) 視需要安裝 Node，透過 npm（預設）或 git 安裝 OpenClaw，並可執行初始設定。

快速命令

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）

  • Detect OS

    支援 macOS 和 Linux（包含 WSL）。

  • Ensure Node.js 24 by default

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

  • Ensure Git

    如果缺少 Git，會使用偵測到的套件管理器安裝，包含 macOS 上的 Homebrew 和 Alpine 上的 apk。

  • Install OpenClaw

    • npm 方法（預設）：全域 npm 安裝
    • git 方法：clone/update repo、使用 pnpm 安裝相依套件、建置，然後在 ~/.local/bin/openclaw 安裝 wrapper

  • Post-install tasks

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

    • 原始碼 checkout 偵測

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

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

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

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

    範例（install.sh）

    Default

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

    Skip onboarding

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

    Git install

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

    GitHub main checkout

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

    Dry run

    bash
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --dry-run
    Flags reference
    旗標 說明
    --install-method npm|git 選擇安裝方法（預設：npm）。別名：--method
    --npm npm 方法的捷徑
    --git git 方法的捷徑。別名：--github
    --version <version|dist-tag|spec> npm 版本、dist-tag，或套件 spec（預設：latest）
    --beta 如果可用則使用 beta dist-tag，否則 fallback 到 latest
    --git-dir <path> 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）
    Environment variables reference
    變數 說明
    OPENCLAW_INSTALL_METHOD=git|npm 安裝方法
    OPENCLAW_VERSION=latest|next|<semver>|<spec> npm 版本、dist-tag，或套件 spec
    OPENCLAW_BETA=0|1 如果可用則使用 beta
    OPENCLAW_HOME=<path> OpenClaw 狀態與預設 git/初始設定路徑的基底目錄
    OPENCLAW_GIT_DIR=<path> Checkout 目錄
    OPENCLAW_GIT_UPDATE=0|1 切換 git 更新
    OPENCLAW_NO_PROMPT=1 停用提示
    OPENCLAW_NO_ONBOARD=1 略過初始設定
    OPENCLAW_DRY_RUN=1 Dry run 模式
    OPENCLAW_VERBOSE=1 偵錯模式
    OPENCLAW_NPM_LOGLEVEL=error|warn|notice npm 記錄層級

    install-cli.sh

    流程（install-cli.sh）

  • Install local Node runtime

    下載釘選的受支援 Node LTS tarball（版本嵌入在指令碼中並獨立更新）到 <prefix>/tools/node-v<version>，並驗證 SHA-256。 在 Alpine/musl Linux 上，由於 Node 不發布與釘選 runtime 相容的 tarball，會使用 apk 安裝 nodejs 和 npm，並將該 runtime 連結到前置目錄 wrapper 路徑。Alpine 儲存庫必須提供 Node 22.19+；如果較舊的儲存庫只提供 Node 20 或 21，請使用 Alpine 3.21 或更新版本。

  • Ensure Git

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

  • Install OpenClaw under prefix

    • npm 方法（預設）：使用 npm 安裝到前置目錄下，然後將 wrapper 寫入 <prefix>/bin/openclaw
    • git 方法：clones/updates checkout（預設 ~/openclaw），並且仍將 wrapper 寫入 <prefix>/bin/openclaw

  • Refresh loaded gateway service

    如果同一前置目錄中已載入閘道服務，指令碼會執行 openclaw gateway install --force，接著執行 openclaw gateway restart，並 盡力探測閘道健康狀態。

    • 範例（install-cli.sh）

    Default

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

    Custom prefix + version

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

    Git install

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

    Automation JSON output

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

    Run onboarding

    bash
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --onboard
    Flags reference
    旗標 說明
    --prefix <path> 安裝前綴（預設：~/.openclaw）
    --install-method npm|git 選擇安裝方法（預設：npm）。別名：--method
    --npm npm 方法的捷徑
    --git, --github git 方法的捷徑
    --git-dir <path> Git checkout 目錄（預設：~/openclaw）。別名：--dir
    --version <ver> OpenClaw 版本或 dist-tag（預設：latest）
    --node-version <ver> 節點版本（預設：22.22.0）
    --json 輸出 NDJSON 事件
    --onboard 安裝後執行 openclaw onboard
    --no-onboard 略過 onboarding（預設）
    --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> 節點版本
    OPENCLAW_HOME=<path> OpenClaw 狀態與預設 git/onboarding 路徑的基底目錄
    OPENCLAW_GIT_DIR=<path> git 安裝的 Git checkout 目錄
    OPENCLAW_GIT_UPDATE=0|1 切換既有 checkout 的 git 更新
    OPENCLAW_NO_ONBOARD=1 略過 onboarding
    OPENCLAW_NPM_LOGLEVEL=error|warn|notice npm 記錄層級

    install.ps1

    流程（install.ps1）

  • 確認 PowerShell + Windows 環境

    需要 PowerShell 5+。

  • 預設確認 Node.js 24

    如果缺少，會嘗試透過 winget 安裝，接著 Chocolatey，再接著 Scoop。如果沒有可用的套件管理器，指令碼會將官方 Node.js Windows zip 下載到 %LOCALAPPDATA%\OpenClaw\deps\portable-node，並將其加入目前程序與使用者 PATH。Node 22 LTS，目前為 22.19+，仍支援相容性。

  • 安裝 OpenClaw

    • npm 方法（預設）：使用所選 -Tag 進行全域 npm 安裝，從可寫入的安裝程式暫存目錄啟動，因此在受保護資料夾（例如 C:\）中開啟的 shell 仍可運作
    • git 方法：clone/update repo、使用 pnpm install/build，並在 %USERPROFILE%\.local\bin\openclaw.cmd 安裝 wrapper。如果缺少 Git，指令碼會在 %LOCALAPPDATA%\OpenClaw\deps\portable-git 下引導安裝使用者本機 MinGit，並將其加入目前程序與使用者 PATH。

  • 安裝後工作

    • 盡可能將所需的 bin 目錄加入使用者 PATH
    • 以最佳努力重新整理已載入的閘道服務（openclaw gateway install --force，然後重新啟動）
    • 在升級與 git 安裝時執行 openclaw doctor --non-interactive（最佳努力）

  • 處理失敗

    iwr ... | iex 與 scriptblock 安裝會回報終止錯誤，但不會關閉目前 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 checkout

    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

    偵錯追蹤

    powershell
    # install.ps1 has no dedicated -Verbose flag yet.Set-PSDebug -Trace 1& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboardSet-PSDebug -Trace 0
    旗標參考
    旗標 說明
    -InstallMethod npm|git 安裝方法（預設：npm）
    -Tag <tag|version|spec> npm dist-tag、版本或套件規格（預設：latest）
    -GitDir <path> checkout 目錄（預設：%USERPROFILE%\openclaw）
    -NoOnboard 略過 onboarding
    -NoGitUpdate 略過 git pull
    -DryRun 僅列印動作
    環境變數參考
    變數 說明
    OPENCLAW_INSTALL_METHOD=git|npm 安裝方法
    OPENCLAW_GIT_DIR=<path> checkout 目錄
    OPENCLAW_NO_ONBOARD=1 略過 onboarding
    OPENCLAW_GIT_UPDATE=0 停用 git pull
    OPENCLAW_DRY_RUN=1 試執行模式

    CI 與自動化

    使用非互動式旗標/env vars 以取得可預測的執行。

    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（略過 onboarding）

    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 exports 附加到 shell rc 檔案（當這些檔案存在時）。

    Windows："npm error spawn git / ENOENT"

    重新執行安裝程式，讓它可以引導安裝使用者本機 MinGit，或安裝 Git for Windows 並重新開啟 PowerShell。

    Windows："openclaw is not recognized"

    執行 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