> ## Documentation Index
> Fetch the complete documentation index at: https://agdiai-597e782f.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 安装器内部机制

# 安装器内部机制

Agdi 提供三个安装脚本，由 `agdi.ai` 提供。

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

## 快速命令

> [tab] install.sh
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> curl -fsSL --proto '=https' --tlsv1.2 https://agdi.ai/install.sh | bash
> ```
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> curl -fsSL --proto '=https' --tlsv1.2 https://agdi.ai/install.sh | bash -s -- --help
> ```

> [tab] install-cli.sh
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> curl -fsSL --proto '=https' --tlsv1.2 https://agdi.ai/install-cli.sh | bash
> ```
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> curl -fsSL --proto '=https' --tlsv1.2 https://agdi.ai/install-cli.sh | bash -s -- --help
> ```

> [tab] install.ps1
>
> ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
> iwr -useb https://agdi.ai/install.ps1 | iex
> ```
>
> ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
> & ([scriptblock]::Create((iwr -useb https://agdi.ai/install.ps1))) -Tag beta -NoOnboard -DryRun
> ```

> [!NOTE]
>
> 如果安装成功但在新终端中找不到 `agdi`，请参见 [Node.js 故障排除](https://agdiai-597e782f.mintlify.site/install/node.md#troubleshooting)。

***

## install.sh

> [!TIP]
>
> 推荐用于大多数 macOS/Linux/WSL 上的交互式安装。

### 流程（install.sh）

**1. 检测操作系统**

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

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

检查 Node 版本，并在需要时安装 Node 24（macOS 上使用 Homebrew，Linux apt/dnf/yum 上使用 NodeSource 设置脚本）。为了兼容性，Agdi 仍支持 Node 22 LTS，目前为 `22.16+`。

**3. 确保安装 Git**

如果缺少 Git，则安装它。

**4. 安装 Agdi**

* `npm` 方法（默认）：全局 npm 安装
* `git` 方法：克隆/更新仓库，使用 pnpm 安装依赖，构建，然后将包装器安装到 `~/.local/bin/agdi`

**5. 安装后任务**

* 在升级和 git 安装时运行 `agdi doctor --non-interactive`（尽力而为）
* 在适当情况下尝试运行新手引导（有 TTY、未禁用新手引导，并且 bootstrap/配置检查通过）
* 默认设置 `SHARP_IGNORE_GLOBAL_LIBVIPS=1`

### 源码检出检测

如果在 Agdi 检出目录中运行（`package.json` + `pnpm-workspace.yaml`），脚本会提供：

* 使用检出目录（`git`），或
* 使用全局安装（`npm`）

如果没有可用 TTY 且未设置安装方法，它将默认使用 `npm` 并发出警告。

对于无效的方法选择或无效的 `--install-method` 值，脚本会以退出码 `2` 退出。

### 示例（install.sh）

> [tab] 默认
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> curl -fsSL --proto '=https' --tlsv1.2 https://agdi.ai/install.sh | bash
> ```

> [tab] 跳过新手引导
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> curl -fsSL --proto '=https' --tlsv1.2 https://agdi.ai/install.sh | bash -s -- --no-onboard
> ```

> [tab] Git 安装
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> curl -fsSL --proto '=https' --tlsv1.2 https://agdi.ai/install.sh | bash -s -- --install-method git
> ```

> [tab] 通过 npm 安装 GitHub main
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> curl -fsSL --proto '=https' --tlsv1.2 https://agdi.ai/install.sh | bash -s -- --version main
> ```

> [tab] 试运行
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> curl -fsSL --proto '=https' --tlsv1.2 https://agdi.ai/install.sh | bash -s -- --dry-run
> ```

> [accordion] 标志参考
>
> | 标志 | 说明 |
> | - | - |
> | `--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>` | 检出目录（默认：`~/agdi`）。别名：`--dir` |
> | `--no-git-update` | 对现有检出跳过 `git pull` |
> | `--no-prompt` | 禁用提示 |
> | `--no-onboard` | 跳过新手引导 |
> | `--onboard` | 启用新手引导 |
> | `--dry-run` | 打印操作但不应用更改 |
> | `--verbose` | 启用调试输出（`set -x`、npm notice 级别日志） |
> | `--help` | 显示用法（`-h`） |

> [accordion] 环境变量参考
>
> | 变量 | 说明 |
> | - | - |
> | `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

> [!NOTE]
>
> 适用于你希望所有内容都放在本地前缀（默认 `~/.agdi`）下，并且不依赖系统 Node 的环境。

### 流程（install-cli.sh）

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

将固定的受支持 Node tarball（当前默认 `22.22.0`）下载到 `<prefix>/tools/node-v<version>`，并验证 SHA-256。

**2. 确保安装 Git**

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

**3. 在前缀下安装 Agdi**

使用 `--prefix <prefix>` 通过 npm 安装，然后将包装器写入 `<prefix>/bin/agdi`。

### 示例（install-cli.sh）

> [tab] 默认
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> curl -fsSL --proto '=https' --tlsv1.2 https://agdi.ai/install-cli.sh | bash
> ```

> [tab] 自定义前缀 + 版本
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> curl -fsSL --proto '=https' --tlsv1.2 https://agdi.ai/install-cli.sh | bash -s -- --prefix /opt/agdi --version latest
> ```

> [tab] 自动化 JSON 输出
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> curl -fsSL --proto '=https' --tlsv1.2 https://agdi.ai/install-cli.sh | bash -s -- --json --prefix /opt/agdi
> ```

> [tab] 运行新手引导
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> curl -fsSL --proto '=https' --tlsv1.2 https://agdi.ai/install-cli.sh | bash -s -- --onboard
> ```

> [accordion] 标志参考
>
> | 标志 | 说明 |
> | - | - |
> | `--prefix <path>` | 安装前缀（默认：`~/.agdi`） |
> | `--version <ver>` | Agdi 版本或 dist-tag（默认：`latest`） |
> | `--node-version <ver>` | Node 版本（默认：`22.22.0`） |
> | `--json` | 输出 NDJSON 事件 |
> | `--onboard` | 安装后运行 `agdi onboard` |
> | `--no-onboard` | 跳过新手引导（默认） |
> | `--set-npm-prefix` | 在 Linux 上，如果当前前缀不可写，则强制将 npm 前缀设为 `~/.npm-global` |
> | `--help` | 显示用法（`-h`） |

> [accordion] 环境变量参考
>
> | 变量 | 说明 |
> | - | - |
> | `OPENCLAW_PREFIX=<path>` | 安装前缀 |
> | `OPENCLAW_VERSION=<ver>` | Agdi 版本或 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）

**1. 确保 PowerShell + Windows 环境**

需要 PowerShell 5+。

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

如果缺少，则依次尝试通过 winget、Chocolatey、Scoop 安装。为了兼容性，Node 22 LTS（当前为 `22.16+`）仍然受支持。

**3. 安装 Agdi**

* `npm` 方法（默认）：使用所选 `-Tag` 进行全局 npm 安装
* `git` 方法：克隆/更新仓库，使用 pnpm 安装/构建，并将包装器安装到 `%USERPROFILE%\.local\bin\agdi.cmd`

**4. 安装后任务**

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

### 示例（install.ps1）

> [tab] 默认
>
> ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
> iwr -useb https://agdi.ai/install.ps1 | iex
> ```

> [tab] Git 安装
>
> ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
> & ([scriptblock]::Create((iwr -useb https://agdi.ai/install.ps1))) -InstallMethod git
> ```

> [tab] 通过 npm 安装 GitHub main
>
> ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
> & ([scriptblock]::Create((iwr -useb https://agdi.ai/install.ps1))) -Tag main
> ```

> [tab] 自定义 git 目录
>
> ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
> & ([scriptblock]::Create((iwr -useb https://agdi.ai/install.ps1))) -InstallMethod git -GitDir "C:\agdi"
> ```

> [tab] 试运行
>
> ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
> & ([scriptblock]::Create((iwr -useb https://agdi.ai/install.ps1))) -DryRun
> ```

> [tab] 调试跟踪
>
> ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
> # install.ps1 目前还没有专门的 -Verbose 标志。
> Set-PSDebug -Trace 1
> & ([scriptblock]::Create((iwr -useb https://agdi.ai/install.ps1))) -NoOnboard
> Set-PSDebug -Trace 0
> ```

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

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

> [!NOTE]
>
> 如果使用 `-InstallMethod git` 且缺少 Git，脚本会退出并打印 Git for Windows 链接。

***

## CI 和自动化

使用非交互式标志/环境变量以实现可预测的运行。

> [tab] install.sh（非交互式 npm）
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> curl -fsSL --proto '=https' --tlsv1.2 https://agdi.ai/install.sh | bash -s -- --no-prompt --no-onboard
> ```

> [tab] install.sh（非交互式 git）
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> OPENCLAW_INSTALL_METHOD=git OPENCLAW_NO_PROMPT=1 \
>   curl -fsSL --proto '=https' --tlsv1.2 https://agdi.ai/install.sh | bash
> ```

> [tab] install-cli.sh（JSON）
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> curl -fsSL --proto '=https' --tlsv1.2 https://agdi.ai/install-cli.sh | bash -s -- --json --prefix /opt/agdi
> ```

> [tab] install.ps1（跳过新手引导）
>
> ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
> & ([scriptblock]::Create((iwr -useb https://agdi.ai/install.ps1))) -NoOnboard
> ```

***

## 故障排除

> [accordion] 为什么需要 Git？
>
> `git` 安装方法需要 Git。对于 `npm` 安装，仍然会检查/安装 Git，以避免当依赖使用 git URL 时出现 `spawn git ENOENT` 失败。

> [accordion] 为什么 npm 在 Linux 上会遇到 EACCES？
>
> 某些 Linux 设置会将 npm 全局前缀指向 root 拥有的路径。`install.sh` 可以将前缀切换到 `~/.npm-global`，并将 PATH 导出追加到 shell rc 文件中（如果这些文件存在）。

> [accordion] sharp/libvips 问题
>
> 这些脚本默认设置 `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://agdi.ai/install.sh | bash
> ```

> [accordion] Windows：“npm error spawn git / ENOENT”
>
> 安装 Git for Windows，重新打开 PowerShell，然后重新运行安装器。

> [accordion] Windows：“agdi is not recognized”
>
> 运行 `npm config get prefix`，并将该目录添加到你的用户 PATH（Windows 上不需要 `\bin` 后缀），然后重新打开 PowerShell。

> [accordion] Windows：如何获取详细安装器输出
>
> `install.ps1` 目前没有提供 `-Verbose` 开关。
> 对于脚本级诊断，请使用 PowerShell 跟踪：
>
> ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
> Set-PSDebug -Trace 1
> & ([scriptblock]::Create((iwr -useb https://agdi.ai/install.ps1))) -NoOnboard
> Set-PSDebug -Trace 0
> ```

> [accordion] 安装后找不到 agdi
>
> 通常是 PATH 问题。请参见 [Node.js 故障排除](https://agdiai-597e782f.mintlify.site/install/node.md#troubleshooting)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.