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

# 安装

# 安装

已经按照 [入门指南](https://agdiai-597e782f.mintlify.site/start/getting-started.md) 操作过了吗？那你已经准备好了 —— 本页适用于其他安装方法、特定平台说明以及维护操作。

## 系统要求

* **[Node 24（推荐）](https://agdiai-597e782f.mintlify.site/install/node.md)**（出于兼容性考虑，仍支持 Node 22 LTS，目前为 `22.16+`；如果缺失，[安装脚本](#install-methods) 会安装 Node 24）
* macOS、Linux 或 Windows
* 仅当你从源码构建时需要 `pnpm`

> [!NOTE]
>
> 在 Windows 上，我们强烈建议你在 [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) 下运行 Agdi。

## 安装方法

> [!TIP]
>
> **安装脚本** 是安装 Agdi 的推荐方式。它会一步完成 Node 检测、安装和新手引导。

> [!WARNING]
>
> 对于 VPS/云主机，尽量避免使用第三方“一键式”市场镜像。优先选择干净的基础 OS 镜像（例如 Ubuntu LTS），然后使用安装脚本自行安装 Agdi。

> [accordion] 安装脚本
>
> 下载 CLI，通过 npm 全局安装，并启动设置向导。
>
> > [tab] macOS / Linux / WSL2
> >
> > ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> > curl -fsSL https://agdi.ai/install.sh | bash
> > ```
>
> > [tab] Windows (PowerShell)
> >
> > ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
> > iwr -useb https://agdi.ai/install.ps1 | iex
> > ```
>
> 就这样 —— 脚本会处理 Node 检测、安装和新手引导。
>
> 如果要跳过新手引导，只安装二进制文件：
>
> > [tab] macOS / Linux / WSL2
> >
> > ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> > curl -fsSL https://agdi.ai/install.sh | bash -s -- --no-onboard
> > ```
>
> > [tab] Windows (PowerShell)
> >
> > ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
> > & ([scriptblock]::Create((iwr -useb https://agdi.ai/install.ps1))) -NoOnboard
> > ```
>
> 所有标志、环境变量以及 CI/自动化选项，请参阅 [Installer internals](https://agdiai-597e782f.mintlify.site/install/installer.md)。

> [accordion] npm / pnpm
>
> 如果你已经自行管理 Node，我们推荐使用 Node 24。出于兼容性考虑，Agdi 仍支持 Node 22 LTS，目前为 `22.16+`：
>
> > [tab] npm
> >
> > ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> > npm install -g agdi@latest
> > agdi onboard --install-daemon
> > ```
> >
> > > [accordion] sharp 构建错误？
> > >
> > > 如果你全局安装了 libvips（在 macOS 上通过 Homebrew 很常见），并且 `sharp` 失败，请强制使用预构建二进制文件：
> > >
> > > ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> > > SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g agdi@latest
> > > ```
> > >
> > > 如果你看到 `sharp: Please add node-gyp to your dependencies`，请安装构建工具链（macOS：Xcode CLT + `npm install -g node-gyp`），或者使用上面的环境变量。
>
> > [tab] pnpm
> >
> > ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> > pnpm add -g agdi@latest
> > pnpm approve-builds -g        # 批准 agdi、node-llama-cpp、sharp 等
> > agdi onboard --install-daemon
> > ```
> >
> > > [!NOTE]
> > >
> > > `pnpm` 要求对带有构建脚本的包进行显式批准。首次安装出现 “Ignored build scripts” 警告后，运行 `pnpm approve-builds -g` 并选择列出的包。
>
> 想通过包管理器安装当前 GitHub `main` 分支最新版本？
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> npm install -g github:agdi/agdi#main
> ```
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> pnpm add -g github:agdi/agdi#main
> ```

> [accordion] 从源码
>
> 适用于贡献者或任何想从本地检出运行的人。
>
> **1. 克隆并构建**
>
> 克隆 [Agdi 仓库](https://github.com/agdi/agdi) 并构建：
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> git clone https://github.com/agdi/agdi.git
> cd agdi
> pnpm install
> pnpm ui:build
> pnpm build
> ```
>
> **2. 链接 CLI**
>
> 让 `agdi` 命令在全局可用：
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> pnpm link --global
> ```
>
> 或者，你也可以跳过链接，直接在仓库内通过 `pnpm agdi ...` 运行命令。
>
> **3. 运行新手引导**
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> agdi onboard --install-daemon
> ```
>
> 更深入的开发工作流请参阅 [Setup](https://agdiai-597e782f.mintlify.site/start/setup.md)。

## 其他安装方法

> [card] [Docker](https://agdiai-597e782f.mintlify.site/install/docker.md)
>
> 容器化或无头部署。

> [card] [Podman](https://agdiai-597e782f.mintlify.site/install/podman.md)
>
> 无 root 容器：先运行一次 `setup-podman.sh`，然后运行启动脚本。

> [card] [Nix](https://agdiai-597e782f.mintlify.site/install/nix.md)
>
> 通过 Nix 进行声明式安装。

> [card] [Ansible](https://agdiai-597e782f.mintlify.site/install/ansible.md)
>
> 自动化批量配置。

> [card] [Bun](https://agdiai-597e782f.mintlify.site/install/bun.md)
>
> 通过 Bun 运行时进行仅 CLI 使用。

## 安装后

验证一切是否正常工作：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
agdi doctor         # 检查配置问题
agdi status         # Gateway 网关状态
agdi dashboard      # 打开浏览器 UI
```

如果你需要自定义运行时路径，请使用：

* `OPENCLAW_HOME` 用于基于主目录的内部路径
* `OPENCLAW_STATE_DIR` 用于可变状态位置
* `OPENCLAW_CONFIG_PATH` 用于配置文件位置

有关优先级和完整细节，请参阅 [Environment vars](https://agdiai-597e782f.mintlify.site/help/environment.md)。

## 故障排除：找不到 `agdi`

> [accordion] PATH 诊断与修复
>
> 快速诊断：
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> node -v
> npm -v
> npm prefix -g
> echo "$PATH"
> ```
>
> 如果 `$(npm prefix -g)/bin`（macOS/Linux）或 `$(npm prefix -g)`（Windows）**不在**你的 `$PATH` 中，那么你的 shell 就找不到全局 npm 二进制文件（包括 `agdi`）。
>
> 修复方法 —— 将其添加到你的 shell 启动文件（`~/.zshrc` 或 `~/.bashrc`）中：
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> export PATH="$(npm prefix -g)/bin:$PATH"
> ```
>
> 在 Windows 上，将 `npm prefix -g` 的输出添加到你的 PATH 中。
>
> 然后打开一个新的终端（或者在 zsh 中运行 `rehash`，在 bash 中运行 `hash -r`）。

## 更新 / 卸载

> [card] [更新](https://agdiai-597e782f.mintlify.site/install/updating.md)
>
> 让 Agdi 保持最新。

> [card] [迁移](https://agdiai-597e782f.mintlify.site/install/migrating.md)
>
> 迁移到新机器。

> [card] [卸载](https://agdiai-597e782f.mintlify.site/install/uninstall.md)
>
> 完全移除 Agdi。


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