安装器内部机制 - OpenClaw 中文文档

OpenClaw 提供三个安装脚本，托管在 openclaw.ai 上。

Script	Platform	What it does
`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，并且可以运行入门引导。

快速命令

install.sh
install-cli.sh
install.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

如果安装成功但在新的终端中找不到 openclaw，请参阅 Node.js 故障排查。

install.sh

适用于 macOS/Linux/WSL 上大多数交互式安装，推荐使用。

Flow (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 方式：克隆/更新仓库，用 pnpm 安装依赖、构建，然后在 ~/.local/bin/openclaw 安装包装器

Post-install tasks

尽力刷新已加载的 gateway 服务（openclaw gateway install --force，然后重启）
在升级和 git 安装时运行 openclaw doctor --non-interactive（尽力而为）
在适当情况下尝试进行入门引导（TTY 可用、未禁用引导，且 bootstrap/config 检查通过）

Source checkout detection

如果在 OpenClaw 检出版本中运行（package.json + pnpm-workspace.yaml），脚本会提供：

使用检出版本（git），或
使用全局安装（npm）

如果没有可用的 TTY 且未设置安装方式，则默认使用 npm 并发出警告。如果方法选择无效或 --install-method 值无效，脚本会以退出码 2 退出。

Examples (install.sh)

Default
Skip onboarding
Git install
GitHub main checkout
Dry run

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

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 -- --install-method git --version main

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

Flags reference

Flag	Description
`--install-method npm\|git`	选择安装方式（默认：`npm`）。别名：`--method`
`--npm`	npm 方式快捷选项
`--git`	git 方式快捷选项。别名：`--github`
`--version <version\|dist-tag\|spec>`	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-level 日志）
`--help`	显示用法（`-h`）

Environment variables reference

Variable	Description
`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_NO_ONBOARD=1`	跳过入门引导
`OPENCLAW_DRY_RUN=1`	试运行模式
`OPENCLAW_VERBOSE=1`	调试模式
`OPENCLAW_NPM_LOGLEVEL=error\|warn\|notice`	npm 日志级别

install-cli.sh

专为希望将所有内容都放在本地前缀（默认 ~/.openclaw）下、且不依赖系统 Node 的环境而设计。默认支持 npm 安装，也支持在相同前缀流程下进行 git 检出安装。

Flow (install-cli.sh)

Install local Node runtime

下载一个固定版本、受支持的 Node LTS tarball（版本内嵌在脚本中，并独立更新）到 <prefix>/tools/node-v<version>，并验证 SHA-256。在 Alpine/musl Linux 上，由于 Node 不会为该固定运行时发布兼容的 tarball，因此会使用 apk 安装 nodejs 和 npm，并将该运行时链接到前缀包装器路径中。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 安装到前缀下，然后将包装器写入 <prefix>/bin/openclaw
git 方式：克隆/更新一个检出目录（默认 ~/openclaw），并仍然将包装器写入 <prefix>/bin/openclaw

Refresh loaded gateway service

如果已有网关服务从同一前缀加载，脚本会运行 openclaw gateway install --force，然后运行 openclaw gateway restart，并尽力探测网关健康状态。

Examples (install-cli.sh)

Default
Custom prefix + version
Git install
Automation JSON output
Run onboarding

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

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

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

Flags reference

Flag	Description
`--prefix <path>`	安装前缀（默认：`~/.openclaw`）
`--install-method npm\|git`	选择安装方式（默认：`npm`）。别名：`--method`
`--npm`	npm 方式快捷选项
`--git`, `--github`	git 方式快捷选项
`--git-dir <path>`	Git 检出目录（默认：`~/openclaw`）。别名：`--dir`
`--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 前缀设为 `~/.npm-global`
`--help`	显示用法（`-h`）

Environment variables reference

Variable	Description
`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 日志级别

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 方法：克隆/更新仓库，使用 pnpm 安装/构建，并将包装器安装到 %USERPROFILE%\.local\bin\openclaw.cmd。如果缺少 Git，脚本会在 %LOCALAPPDATA%\OpenClaw\deps\portable-git 下引导安装用户本地 MinGit，并将其添加到当前进程和用户 PATH。

安装后任务

在可能的情况下，将所需的 bin 目录添加到用户 PATH
最佳努力刷新已加载的 gateway 服务（openclaw gateway install --force，然后重启）
在升级和 git 安装时运行 openclaw doctor --non-interactive（最佳努力）

处理失败

iwr ... | iex 和 scriptblock 安装会报告终止性错误，但不会关闭当前 PowerShell 会话。直接通过 powershell -File / pwsh -File 安装时仍会以非零状态退出，便于自动化处理。

示例（install.ps1）

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

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

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

& ([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

标志参考

Flag	Description
`-InstallMethod npm\|git`	安装方法（默认：`npm`）
`-Tag <tag\|version\|spec>`	npm dist-tag、版本或包规范（默认：`latest`）
`-GitDir <path>`	检出目录（默认：`%USERPROFILE%\openclaw`）
`-NoOnboard`	跳过引导流程
`-NoGitUpdate`	跳过 `git pull`
`-DryRun`	仅打印操作

环境变量参考

Variable	Description
`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，脚本会先尝试引导安装用户本地 MinGit，然后再打印 Git for Windows 链接。

CI 和自动化

使用非交互标志/环境变量以获得可预测的运行结果。

install.sh（非交互 npm）
install.sh（非交互 git）
install-cli.sh（JSON）
install.ps1（跳过引导）

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

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

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

& ([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 is not recognized"

运行 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 故障排查。

​快速命令

​install.sh

​Flow (install.sh)

​Source checkout detection

​Examples (install.sh)

​install-cli.sh

​Flow (install-cli.sh)

​Examples (install-cli.sh)

​install.ps1

​流程（install.ps1）

​示例（install.ps1）

​CI 和自动化

​故障排查

​相关内容

快速命令

install.sh

Flow (install.sh)

Source checkout detection

Examples (install.sh)

install-cli.sh

Flow (install-cli.sh)

Examples (install-cli.sh)

install.ps1

流程（install.ps1）

示例（install.ps1）

CI 和自动化

故障排查

相关内容