| read_when |
summary |
title |
x-i18n |
| 你想了解 `openclaw.ai/install.sh` |
| 你想自动化安装（CI / 无头） |
| 你想从 GitHub 检出安装 |
|
安装脚本的工作原理（install.sh、install-cli.sh、install.ps1）、标志和自动化 |
安装器内部机制 |
| generated_at |
model |
provider |
source_hash |
source_path |
workflow |
| 2026-03-16T06:24:11Z |
gpt-5.4 |
openai |
e389fa04140ecc98b7e83330d0d467165b23bd22e31807bbd36963c87394ddc4 |
install/installer.md |
15 |
|
安装器内部机制
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
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
```
```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
```
```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/node#troubleshooting)。
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
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
```
```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 -- --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 tarball
（当前默认 `22.22.0`）下载到 `/tools/node-v`，并验证 SHA-256。
如果缺少 Git
，则尝试在 Linux 上通过 apt/dnf/yum 安装，或在 macOS 上通过 Homebrew 安装。
使用 `--prefix ` 通过 npm 安装，然后将包装器写入 `/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
```
```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 5+。
如果缺少，则依次尝试通过 winget、Chocolatey、Scoop 安装。为了兼容性
，Node 22 LTS
（当前为 `22.16+`）仍然受支持。
- `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
```
```powershell
& ([scriptblock]::Create((iwr -useb
https://openclaw.ai/install.ps1))) -InstallMethod git
```
```powershell
& ([scriptblock]::Create((iwr -useb
https://openclaw.ai/install.ps1))) -Tag main
```
```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 和自动化
使用非交互式标志/环境变量以实现可预测的运行。
```bash
curl -fsSL --proto '=https' --tlsv1.2
https://openclaw.ai/install.sh | bash -s -- --no-prompt --no-onboard
```
```bash
OPENCLAW_INSTALL_METHOD=git OPENCLAW_NO_PROMPT=1 \
curl -fsSL --proto '=https' --tlsv1.2
https://openclaw.ai/install.sh | bash
```
```bash
curl -fsSL --proto '=https' --tlsv1.2
https://openclaw.ai/install-cli.sh | bash -s -- --json --prefix /opt/openclaw
```
```powershell
& ([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
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
Set-PSDebug -Trace 1
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
Set-PSDebug -Trace 0
```
通常是 PATH 问题。请参见 [Node.js 故障排除](/install/node#troubleshooting)。