文档
安装器内部机制
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，并可运行新手引导。 |
快速命令
bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash
```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --help
```
bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash
```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --help
```
powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
iwr -useb https://openclaw.ai/install.ps1 | iex
```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
& ([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 版本，并在需要时安装 Node 24（macOS 上使用 Homebrew，Linux apt/dnf/yum 上使用 NodeSource 设置脚本）。为了兼容性，OpenClaw 仍支持 Node 22 LTS，目前为 22.16+。
如果缺少 Git，则安装它。
* npm 方法（默认）：全局 npm 安装
* git 方法：克隆/更新仓库，使用 pnpm 安装依赖，构建，然后将包装器安装到 ~/.local/bin/openclaw
* 在升级和 git 安装时运行 openclaw doctor --non-interactive（尽力而为）
* 在适当情况下尝试运行新手引导（有 TTY、未禁用新手引导，并且 bootstrap/配置检查通过）
* 默认设置 SHARP_IGNORE_GLOBAL_LIBVIPS=1
源码检出检测
如果在 OpenClaw 检出目录中运行（package.json + pnpm-workspace.yaml），脚本会提供：
- 使用检出目录（
git），或 - 使用全局安装（
npm）
如果没有可用 TTY 且未设置安装方法，它将默认使用 npm 并发出警告。
对于无效的方法选择或无效的 --install-method 值，脚本会以退出码 2 退出。
示例（install.sh）
bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash
bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --no-onboard
bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git
bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --version main
bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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 tarball（当前默认 22.22.0）下载到 <prefix>/tools/node-v<version>，并验证 SHA-256。
如果缺少 Git，则尝试在 Linux 上通过 apt/dnf/yum 安装，或在 macOS 上通过 Homebrew 安装。
使用 --prefix <prefix> 通过 npm 安装，然后将包装器写入 <prefix>/bin/openclaw。
示例（install-cli.sh）
bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash
bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --prefix /opt/openclaw --version latest
bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --json --prefix /opt/openclaw
bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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 5+。
如果缺少，则依次尝试通过 winget、Chocolatey、Scoop 安装。为了兼容性，Node 22 LTS（当前为 22.16+）仍然受支持。
* npm 方法（默认）：使用所选 -Tag 进行全局 npm 安装
* git 方法：克隆/更新仓库，使用 pnpm 安装/构建，并将包装器安装到 %USERPROFILE%.localbinopenclaw.cmd
在可能情况下将所需 bin 目录添加到用户 PATH，然后在升级和 git 安装时运行 openclaw doctor --non-interactive（尽力而为）。
示例（install.ps1）
powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
iwr -useb https://openclaw.ai/install.ps1 | iex
powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -InstallMethod git
powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -Tag main
powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -InstallMethod git -GitDir "C:openclaw"
powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -DryRun
powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
# 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 和自动化
使用非交互式标志/环境变量以实现可预测的运行。
bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --no-prompt --no-onboard
bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
OPENCLAW_INSTALL_METHOD=git OPENCLAW_NO_PROMPT=1
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash
bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --json --prefix /opt/openclaw
powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
故障排除
git 安装方法需要 Git。对于 npm 安装，仍然会检查/安装 Git，以避免当依赖使用 git URL 时出现 spawn git ENOENT 失败。
某些 Linux 设置会将 npm 全局前缀指向 root 拥有的路径。install.sh 可以将前缀切换到 ~/.npm-global，并将 PATH 导出追加到 shell rc 文件中（如果这些文件存在）。
这些脚本默认设置 SHARP_IGNORE_GLOBAL_LIBVIPS=1，以避免 sharp 针对系统 libvips 进行构建。若要覆盖：
```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
SHARP_IGNORE_GLOBAL_LIBVIPS=0 curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash
```
安装 Git for Windows，重新打开 PowerShell，然后重新运行安装器。
运行 npm config get prefix，并将该目录添加到你的用户 PATH（Windows 上不需要 bin 后缀），然后重新打开 PowerShell。
install.ps1 目前没有提供 -Verbose 开关。
对于脚本级诊断，请使用 PowerShell 跟踪：
```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
Set-PSDebug -Trace 1
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
Set-PSDebug -Trace 0
```
通常是 PATH 问题。请参见 Node.js 故障排除。