安装脚本内部机制

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

脚本平台功能
install.shmacOS / Linux / WSL按需安装 Node，通过 npm（默认）或 git 安装 OpenClaw，可运行引导流程。
install-cli.shmacOS / Linux / WSL将 Node + OpenClaw 安装到本地前缀（~/.openclaw）下。无需 root。
install.ps1Windows (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）

第 1 步：检测操作系统

支持 macOS 和 Linux（包括 WSL）。如果检测到 macOS，会在缺失时安装 Homebrew。

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

检查 Node 版本，按需安装 Node 24（macOS 用 Homebrew，Linux 用 NodeSource 安装脚本，支持 apt/dnf/yum）。OpenClaw 仍兼容 Node 22 LTS，目前 `22.16+`。

第 3 步：确保 Git

如果缺失则安装 Git。

第 4 步：安装 OpenClaw

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

第 5 步：安装后任务

- 升级和 git 安装时运行 `openclaw doctor --non-interactive`（尽力而为）
- 在条件满足时尝试引导流程（有 TTY、未禁用引导、引导/配置检查通过）
- 默认设置 `SHARP_IGNORE_GLOBAL_LIBVIPS=1`

源码 checkout 检测

如果在 OpenClaw checkout 目录中运行（有 package.json + pnpm-workspace.yaml），脚本会提供选择：

  • 使用 checkout（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
```

试运行

```bash
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --dry-run
```
参数参考
参数说明
--install-method npm|git选择安装方式（默认：npm）。别名：--method
--npmnpm 方式的快捷方式
--gitgit 方式的快捷方式。别名：--github
--version <version|dist-tag>npm 版本或 dist-tag（默认：latest）
--beta使用 beta dist-tag（如可用），否则回退到 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 级别日志）
--help显示用法（-h）
环境变量参考
变量说明
OPENCLAW_INSTALL_METHOD=git|npm安装方式
OPENCLAW_VERSION=latest|next|<semver>npm 版本或 dist-tag
OPENCLAW_BETA=0|1使用 beta（如可用）
OPENCLAW_GIT_DIR=<path>checkout 目录
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|noticenpm 日志级别
SHARP_IGNORE_GLOBAL_LIBVIPS=0|1控制 sharp/libvips 行为（默认：1）

install-cli.sh

信息： 专为希望将所有内容放在本地前缀（默认 ~/.openclaw）下、不依赖系统 Node 的环境设计。

流程（install-cli.sh）

第 1 步：安装本地 Node 运行时

下载固定版本的 Node 压缩包（当前默认 `22.22.0`）到 `<prefix>/tools/node-v<version>` 并验证 SHA-256。

第 2 步：确保 Git

如果缺失，在 Linux 上尝试通过 apt/dnf/yum 安装，macOS 上通过 Homebrew 安装。

第 3 步：在前缀下安装 OpenClaw

使用 `--prefix <prefix>` 通过 npm 安装，然后将包装脚本写入 `<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 prefix 不可写时，强制设为 ~/.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|noticenpm 日志级别
OPENCLAW_GIT_DIR=<path>旧版清理查找路径（用于移除旧的 Peekaboo 子模块 checkout）
SHARP_IGNORE_GLOBAL_LIBVIPS=0|1控制 sharp/libvips 行为（默认：1）

install.ps1

流程（install.ps1）

第 1 步：确保 PowerShell + Windows 环境

要求 PowerShell 5+。

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

如果缺失，依次尝试通过 winget、Chocolatey、Scoop 安装。Node 22 LTS，目前 `22.16+`，仍兼容支持。

第 3 步：安装 OpenClaw

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

第 4 步：安装后任务

尽可能将所需 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
```

自定义 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>npm dist-tag（默认：latest）
-GitDir <path>checkout 目录（默认：%USERPROFILE%\openclaw）
-NoOnboard跳过引导流程
-NoGitUpdate跳过 git pull
-DryRun仅打印操作
环境变量参考
变量说明
OPENCLAW_INSTALL_METHOD=git|npm安装方式
OPENCLAW_GIT_DIR=<path>checkout 目录
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 排错](/docs/install/node#troubleshooting)。
arrow_back
上一页
Install
下一页
Docker
arrow_forward