# 安装程序内部机制

> 安装脚本（install.sh、install-cli.sh、install.ps1）的工作原理、标志和自动化

- 网址：https://funcoding.ai/agents/openclaw/install/installer/
- 来源：OpenClaw 官方文档原文（中文），MIT 许可，同步于 2026-10-11
- 官方原文：https://docs.openclaw.ai/zh-CN/install/installer

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

| 脚本                             | 平台             | 功能                                                                                   |
| ---------------------------------- | -------------------- | ---------------------------------------------------------------------------------------------- |
| [`install.sh`](#installsh)         | macOS / Linux / WSL  | 按需安装 Node，通过 npm（默认）或 git 安装 OpenClaw，并可运行新手引导。       |
| [`install-cli.sh`](#install-clish) | macOS / Linux / WSL  | 通过 npm 或 git 将 Node + OpenClaw 安装到本地前缀 (`~/.openclaw`)。无需 root 权限。 |
| [`install.ps1`](#installps1)       | Windows (PowerShell) | 按需安装 Node，通过 npm（默认）或 git 安装 OpenClaw，并可运行新手引导。       |

这三个脚本均支持 Node **22.22.3+、24.15+ 或 25.9+**；全新安装默认以 Node 24 为目标版本。

## 快速命令

**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
```

<div class="callout callout-note">

如果安装成功，但在新终端中找不到 `openclaw`，请参阅 [Node.js 故障排除](https://funcoding.ai/agents/openclaw/install/node/#troubleshooting)。

</div>

---

<a id="installsh"></a>

## install.sh

<div class="callout callout-tip">

建议用于 macOS/Linux/WSL 上的大多数交互式安装。

</div>

### 流程 (install.sh)

**检测操作系统**

支持 macOS 和 Linux（包括 WSL）。

**默认确保使用 Node.js 24**

检查 Node 版本，并在需要时安装 Node 24（macOS 使用 Homebrew，Linux 使用 NodeSource 的 apt/dnf/yum 设置脚本）。在 macOS 上，仅当安装程序需要用它安装 Node 或 Git 时才会安装 Homebrew。支持 Node 22.22.3+、Node 24.15+ 和 Node 25.9+；不支持 Node 23。
在 Alpine/musl Linux 上，安装程序使用 apk 软件包而非 NodeSource，并验证实际链接的 SQLite 版本。当前稳定版 Alpine 软件包源可能提供版本足够新的 Node，但其系统 SQLite 存在漏洞；出现这种情况时，请改用官方 `node:24-alpine` 容器或基于 glibc 的主机。

**确保 Git 可用**

如果缺少 Git，则使用检测到的软件包管理器进行安装，包括 macOS 上的 Homebrew 和 Alpine 上的 apk。

**安装 OpenClaw**

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

**安装后任务**

- 解析刚安装的 `openclaw` 二进制文件，以便运行后续命令
- 对于尚未配置的安装，会先启动新手引导，然后再运行 Doctor 或 Gateway 网关探测。使用 `--no-onboard` 或无 TTY 时，它会输出稍后完成设置所需的命令。
- 对于已配置的安装，会尽力刷新并重启已加载的 Gateway 网关服务，然后运行 Doctor。升级时会尽可能更新插件；如果是在无界面但启用提示的运行中，则输出手动命令。
- 运行 `--verify` 时，它会检查已安装的版本，并且仅在配置存在后检查 Gateway 健康。

### 源码检出检测

如果脚本在 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 -- --install-method git --version main
```

**试运行**

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

**安装后验证**

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

<details>
<summary>标志参考</summary>

| 标志                                    | 描述                                                             |
| --------------------------------------- | ----------------------------------------------------------------------- |
| `--install-method \| --method npm\|git` | 选择安装方式（默认：`npm`）                                  |
| `--npm`                                 | npm 方式的快捷选项                                                 |
| `--git \| --github`                     | git 方式的快捷选项                                                 |
| `--version <version\|dist-tag\|spec>`   | npm 版本、dist-tag 或软件包规范（默认：`latest`）              |
| `--beta`                                | 使用 beta dist-tag（如果可用），否则回退到 `latest`              |
| `--git-dir \| --dir <path>`             | 检出目录（默认：`~/openclaw`）                              |
| `--no-git-update`                       | 对现有检出目录跳过 `git pull`                                   |
| `--no-prompt`                           | 禁用提示                                                         |
| `--no-onboard`                          | 跳过新手引导                                                         |
| `--onboard`                             | 启用新手引导                                                       |
| `--verify`                              | 运行安装后冒烟验证（`--version`，如果 Gateway 网关已加载则检查其健康状态） |
| `--dry-run`                             | 输出操作但不应用更改                                  |
| `--verbose`                             | 启用调试输出（`set -x`、npm notice 级别日志）                   |
| `--help \| -h`                          | 显示用法                                                              |

</details>

<details>
<summary>环境变量参考</summary>

| 变量                                          | 描述                                                        |
| ------------------------------------------------- | ------------------------------------------------------------------ |
| `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_VERIFY_INSTALL=1`                       | 运行安装后冒烟验证                                  |
| `OPENCLAW_NO_ONBOARD=1`                           | 跳过新手引导                                                    |
| `OPENCLAW_DRY_RUN=1`                              | 试运行模式                                                       |
| `OPENCLAW_VERBOSE=1`                              | 调试模式                                                         |
| `OPENCLAW_NPM_LOGLEVEL=error\|warn\|notice`       | npm 日志级别（默认：`error`，隐藏 npm 弃用提示干扰）      |

</details>

---

<a id="install-clish"></a>

## install-cli.sh

<div class="callout callout-note">

适用于希望将所有内容置于本地前缀下
（默认 `~/.openclaw`）且不依赖系统 Node 的环境。默认支持 npm 安装，
也支持在同一前缀流程下进行 git 检出安装。

</div>

### 流程 (install-cli.sh)

**安装本地 Node 运行时**

将固定版本且受支持的 Node LTS tarball（版本嵌入脚本中并独立更新，默认 `24.15.0`）下载到 `<prefix>/tools/node-v<version>`，并验证 SHA-256。
Linux ARMv7 使用 Node `22.22.3`，因为没有官方 Node 24+ ARMv7 二进制文件。
在 Alpine/musl Linux 上，由于 Node 不为固定版本的运行时发布兼容 tarball，因此使用 `apk` 安装 `nodejs` 和 `npm`，然后验证 Node 和实际链接的 SQLite 库。当前稳定版 Alpine 软件包源即使提供版本足够新的 Node，仍可能链接存在漏洞的 SQLite；当安全检查拒绝该软件包时，请使用官方 `node:24-alpine` 容器或基于 glibc 的主机。

**确保 Git 可用**

如果缺少 Git，则尝试通过 Linux 上的 apt/dnf/yum/apk 或 macOS 上的 Homebrew 安装。

**在前缀下安装 OpenClaw**

- `npm` 方式（默认）：使用 npm 安装到该前缀下，然后将包装器写入 `<prefix>/bin/openclaw`
- `git` 方式：克隆/更新检出目录（默认 `~/openclaw`），并仍将包装器写入 `<prefix>/bin/openclaw`

**刷新已加载的 Gateway 网关服务**

如果已从同一前缀加载 Gateway 网关服务，脚本会运行
`openclaw gateway install --force`，从而激活替换后的服务，
然后尽力探测 Gateway 健康。

### 示例 (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
```

**Git 安装**

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

**自动化 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
```

<details>
<summary>标志参考</summary>

| 标志                                    | 说明                                                                     |
| --------------------------------------- | ------------------------------------------------------------------------------- |
| `--prefix <path>`                       | 安装前缀（默认值：`~/.openclaw`）                                         |
| `--install-method \| --method npm\|git` | 选择安装方式（默认值：`npm`）                                          |
| `--npm`                                 | npm 方式的快捷选项                                                         |
| `--git \| --github`                     | git 方式的快捷选项                                                         |
| `--git-dir \| --dir <path>`             | Git 检出目录（默认值：`~/openclaw`）                                  |
| `--version <ver>`                       | OpenClaw 版本或 dist-tag（默认值：`latest`）                                |
| `--node-version <ver>`                  | Node 版本（默认值：`24.15.0`；Linux ARMv7 上为 `22.22.3`）                     |
| `--json`                                | 输出 NDJSON 事件                                                              |
| `--onboard`                             | 安装后运行 `openclaw onboard`                                            |
| `--no-onboard`                          | 跳过新手引导（默认）                                                       |
| `--set-npm-prefix`                      | 在 Linux 上，如果当前前缀不可写，则强制将 npm 前缀设为 `~/.npm-global` |
| `--help \| -h`                          | 显示用法                                                                      |

</details>

<details>
<summary>环境变量参考</summary>

| 变量                                    | 说明                                                        |
| ------------------------------------------- | ------------------------------------------------------------------ |
| `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 日志级别（默认值：`error`）                                   |

</details>

<div class="callout callout-note">

`openclaw@main` 和其他 GitHub 源规范不能作为 npm 安装的有效 `--version` 目标。请改用 `--install-method git --version main`。

</div>

---

<a id="installps1"></a>

## install.ps1

### 流程（install.ps1）

**确保 PowerShell + Windows 环境**

需要 PowerShell 5+。

**确保默认使用 Node.js 24**

如果缺失，将依次尝试通过 winget、Chocolatey、Scoop 安装。如果没有可用的包管理器，脚本会将官方 Node.js 24 Windows zip 下载到 `%LOCALAPPDATA%\OpenClaw\deps\portable-node`，并将其添加到当前进程和用户 PATH。支持 Node 22.22.3+、Node 24.15+ 和 Node 25.9+；不支持 Node 23。

**安装 OpenClaw**

- `npm` 方式（默认）：使用选定的 `-Tag` 执行全局 npm 安装；安装从可写的安装程序临时目录启动，因此即使 shell 在 `C:\` 等受保护文件夹中打开，也能正常工作
- `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` 和脚本块安装会报告终止错误，但不会关闭当前 PowerShell 会话。直接使用 `powershell -File` / `pwsh -File` 安装时，仍会以非零状态退出，以便自动化流程检测。

### 示例（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))) -InstallMethod git -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
```

<details>
<summary>标志参考</summary>

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

</details>

<details>
<summary>环境变量参考</summary>

| 变量                           | 说明        |
| ---------------------------------- | ------------------ |
| `OPENCLAW_INSTALL_METHOD=git\|npm` | 安装方式     |
| `OPENCLAW_GIT_DIR=<path>`          | 检出目录 |
| `OPENCLAW_NO_ONBOARD=1`            | 跳过新手引导    |
| `OPENCLAW_GIT_UPDATE=0`            | 禁用 git pull   |
| `OPENCLAW_DRY_RUN=1`               | 试运行模式       |

</details>

<div class="callout callout-note">

如果使用 `-InstallMethod git` 且缺少 Git，脚本会先尝试引导安装用户本地 MinGit，然后再显示 Git for Windows 链接。

</div>

---

## 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
```

---

## 故障排查

<details>
<summary>为什么需要 Git？</summary>

`git` 安装方式需要 Git。对于 `npm` 安装，仍会检查/安装 Git，以避免依赖项使用 git URL 时发生 `spawn git ENOENT` 失败。

</details>

<details>
<summary>为什么 npm 在 Linux 上遇到 EACCES？</summary>

某些 Linux 配置会将 npm 的全局前缀指向 root 所有的路径。`install.sh` 可以将前缀切换到 `~/.npm-global`，并将 PATH 导出语句附加到 shell rc 文件（如果这些文件存在）。

</details>

<details>
<summary>Windows：“npm error spawn git / ENOENT”</summary>

重新运行安装程序，让它引导安装用户本地 MinGit；或者安装 Git for Windows 后重新打开 PowerShell。

</details>

<details>
<summary>Windows：“openclaw is not recognized”</summary>

运行 `npm config get prefix`，并将该目录添加到你的用户 PATH（Windows 上不需要 `\bin` 后缀），然后重新打开 PowerShell。

</details>

<details>
<summary>Windows：如何获取详细的安装程序输出</summary>

`install.ps1` 不提供 `-Verbose` 开关。
使用 PowerShell 跟踪进行脚本级诊断：

```powershell
Set-PSDebug -Trace 1
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
Set-PSDebug -Trace 0
```

</details>

<details>
<summary>安装后找不到 openclaw</summary>

通常是 PATH 问题。请参阅 [Node.js 故障排查](https://funcoding.ai/agents/openclaw/install/node/#troubleshooting)。

</details>

## 相关内容

- [安装概览](https://funcoding.ai/agents/openclaw/install/)
- [更新](https://funcoding.ai/agents/openclaw/install/updating/)
- [卸载](https://funcoding.ai/agents/openclaw/install/uninstall/)