安装脚本详解

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：

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

注意： 安装成功但新终端中找不到 openclaw，参见 Node.js 故障排查。

install.sh

提示： 推荐用于 macOS/Linux/WSL 的交互式安装。

执行流程（install.sh）

第一步：检测操作系统

支持 macOS 和 Linux（含 WSL）。检测到 macOS 时，若未安装 Homebrew 则自动安装。

第二步：确保 Node.js 24（默认）

检查 Node 版本，按需安装 Node 24（macOS 用 Homebrew，Linux apt/dnf/yum 用 NodeSource 脚本）。OpenClaw 同时支持 Node 22 LTS（当前 22.14+）以保持兼容性。

第三步：确保 Git 可用

若未安装 Git 则自动安装。

第四步：安装 OpenClaw

npm 方式（默认）：全局 npm 安装
git 方式：克隆/更新仓库，用 pnpm 安装依赖并构建，然后在 ~/.local/bin/openclaw 安装包装脚本

第五步：安装后处理

升级和 git 安装时运行 openclaw doctor --non-interactive（尽力而为）
在合适条件下（有 TTY、未禁用引导、bootstrap/config 检查通过）启动引导流程
默认设置 SHARP_IGNORE_GLOBAL_LIBVIPS=1

源码检出检测

在 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 -- --version main

演练模式：

bash

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\|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 级日志）
`--help`	显示用法（`-h`）

环境变量说明：

变量	说明
`OPENCLAW_INSTALL_METHOD=git\|npm`	安装方式
`OPENCLAW_VERSION=latest\|next\|main\|<semver>\|<spec>`	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 LTS 压缩包（版本号内嵌于脚本中独立更新）到 <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）

默认安装：

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

自动化 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`）
`--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 24（默认）

若未安装，依次尝试通过 winget、Chocolatey、Scoop 安装。Node 22 LTS（当前 22.14+）仍支持以保持兼容性。

第三步：安装 OpenClaw

npm 方式（默认）：使用选定的 -Tag 全局 npm 安装
git 方式：克隆/更新仓库，用 pnpm 安装/构建，在 %USERPROFILE%\.local\bin\openclaw.cmd 安装包装脚本

第四步：安装后处理

尽可能将所需 bin 目录添加到用户 PATH，然后在升级和 git 安装时运行 openclaw doctor --non-interactive（尽力而为）。

使用示例（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))) -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 暂无专用 -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\|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`	演练模式

注意： 使用 -InstallMethod git 但 Git 未安装时，脚本会退出并打印 Git for Windows 的下载链接。

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 错误。

Linux 上为什么 npm 报 EACCES？

某些 Linux 配置的 npm 全局前缀指向 root 所有的路径。install.sh 可将前缀切换到 ~/.npm-global，并在存在的 shell rc 文件中追加 PATH 导出。

sharp/libvips 问题：

脚本默认设置 SHARP_IGNORE_GLOBAL_LIBVIPS=1 以避免 sharp 链接系统 libvips。如需覆盖：

bash

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，将该目录添加到用户 PATH（Windows 不需要 \bin 后缀），然后重开 PowerShell。

Windows：如何获取详细安装日志：

install.ps1 目前没有 -Verbose 参数。使用 PowerShell 追踪获取脚本级诊断：

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 ​

执行流程（install.sh） ​

源码检出检测 ​

使用示例（install.sh） ​

install-cli.sh ​

执行流程（install-cli.sh） ​

使用示例（install-cli.sh） ​

install.ps1 ​

执行流程（install.ps1） ​

使用示例（install.ps1） ​

CI 和自动化 ​

故障排查 ​

安装脚本详解

快速命令

install.sh

执行流程（install.sh）

源码检出检测

使用示例（install.sh）

install-cli.sh

执行流程（install-cli.sh）

使用示例（install-cli.sh）

install.ps1

执行流程（install.ps1）

使用示例（install.ps1）

CI 和自动化

故障排查