安装

使用一行安装命令，两分钟内即可启动并运行 AigenLabs Agent。

快速安装

一行安装命令（Linux / macOS / WSL2）

基于 git 的安装方式，跟踪 main 分支，可立即获取最新变更：

curl -fsSL https://docs.aigenlabs.vn/install.sh | bash

Windows（原生，PowerShell）

原生 Windows 无需 WSL 即可运行 AigenLabs——CLI、gateway、TUI 和工具均可原生运行。（原生安装与 WSL2 安装可干净共存；唯一仅限 WSL2 的功能见下方功能说明。）遇到 bug 请提交 issue。

打开 PowerShell 并运行：

iex (irm https://docs.aigenlabs.vn/install.ps1)

安装程序处理一切：uv、Python 3.11、Node.js 22、ripgrep、ffmpeg，以及一个便携式 Git Bash（PortableGit——一个自包含的 Git-for-Windows 发行版，附带 bash.exe 和 AigenLabs 用于 shell 命令的完整 POSIX 工具链；在 32 位 Windows 上安装程序会回退到 MinGit，后者缺少 bash，终端工具和 agent 浏览器功能将被禁用）。它将仓库克隆到 %LOCALAPPDATA%\aigenlabs\aigenlabs-agent，创建虚拟环境，并将 aigenlabs 添加到用户 PATH。安装完成后请重启终端（或打开新的 PowerShell 窗口）以使 PATH 生效。

Git 的处理方式：

如果 git 已在你的 PATH 中，安装程序将使用现有安装。
否则，它会下载便携式 PortableGit（约 50MB，来自官方 git-for-windows GitHub 发布页）并解压到 %LOCALAPPDATA%\aigenlabs\git。无需管理员权限，完全隔离——不会干扰任何系统 Git 安装，无论其状态如何。（在 32 位 Windows 上会回退到 MinGit，因为 PortableGit 仅提供 64 位和 ARM64 资产；依赖 bash 的 AigenLabs 功能在 32 位主机上无法使用。）

为什么不使用 winget？ 早期设计通过 winget install Git.Git 自动安装 Git，但当系统 Git 安装处于部分损坏状态时，winget 会严重失败（而这恰恰是用户最需要安装程序正常工作的时候）。便携式 Git 方案绕过了 winget、Windows 安装程序注册表以及任何现有系统 Git。如果 AigenLabs 的 Git 安装本身出现问题，执行 Remove-Item %LOCALAPPDATA%\aigenlabs\git 并重新运行安装程序即可——对系统无影响，无需卸载操作。

安装程序还会将 AIGENLABS_GIT_BASH_PATH 设置为找到的 bash.exe 路径，以便 AigenLabs 在新 shell 中确定性地解析它。

如果你偏好 WSL2，上方的 Linux 安装程序可在其中运行；原生安装和 WSL 安装可以共存而不冲突（原生数据位于 %LOCALAPPDATA%\aigenlabs，WSL 数据位于 ~/.aigenlabs）。

桌面安装程序（替代方案）： 也提供一个轻量 GUI 安装程序——下载 AigenLabs Desktop，运行 .exe，首次启动时它会在后台调用 install.ps1 来配置 Python（通过 uv）、Node、PortableGit 及其余依赖。桌面应用和 PowerShell 安装的 CLI 共享相同的安装目录和数据目录，可以单独或同时使用。详见 Windows（原生）指南。

Android / Termux

AigenLabs 现在也提供 Termux 感知的安装路径：

curl -fsSL https://docs.aigenlabs.vn/install.sh | bash

安装程序会自动检测 Termux 并切换到经过测试的 Android 流程：

使用 Termux pkg 安装系统依赖（git、python、nodejs、ripgrep、ffmpeg、构建工具）
使用 python -m venv 创建虚拟环境
自动导出 ANDROID_API_LEVEL 以用于 Android wheel 构建
优先使用较宽泛的 .[termux-all] extra，若首次编译失败则回退到较小的 .[termux] extra（最终回退到基础安装）
默认跳过未经测试的浏览器 / WhatsApp 引导

如需完整的显式步骤，请参阅专门的 Termux 指南。

Windows 功能对等性

除基于浏览器的 dashboard 聊天终端外，其余功能均可在 Windows 上原生运行：

CLI（aigenlabs chat、aigenlabs setup、aigenlabs gateway 等） — 原生，使用默认终端
Gateway（Telegram、Discord、Slack 等） — 原生，作为后台 PowerShell 进程运行
Cron 调度器 — 原生
浏览器工具 — 原生（通过 Node.js 使用 Chromium）
MCP 服务器 — 原生（stdio 和 HTTP 传输均支持）
Dashboard /chat 终端面板 — 仅限 WSL2（使用 POSIX PTY（伪终端），原生 Windows 无等效实现）。Dashboard 的其余部分（会话、任务、指标）可原生运行——仅嵌入式 PTY 终端标签页受限。

如果遇到编码相关的 bug 并希望回退到旧版 cp1252 stdio 路径（用于问题定位），请在环境中设置 AIGENLABS_DISABLE_WINDOWS_UTF8=1。

安装程序做了什么

安装程序自动处理一切——所有依赖（Python、Node.js、ripgrep、ffmpeg）、仓库克隆、虚拟环境、全局 aigenlabs 命令配置以及 LLM 提供商配置。完成后即可开始聊天。

安装目录结构

安装程序的存放位置取决于你是以普通用户还是 root 身份安装：

安装方式	代码位置	`aigenlabs` 二进制	数据目录
pip install	Python site-packages	`~/.local/bin/aigenlabs`（console_scripts）	`~/.aigenlabs/`
用户级（git 安装程序）	`~/.aigenlabs/aigenlabs-agent/`	`~/.local/bin/aigenlabs`（符号链接）	`~/.aigenlabs/`
Root 模式（`sudo curl … \| sudo bash`）	`/usr/local/lib/aigenlabs-agent/`	`/usr/local/bin/aigenlabs`	`/root/.aigenlabs/`（或 `$AIGENLABS_HOME`）

Root 模式的 FHS 布局（/usr/local/lib/…、/usr/local/bin/aigenlabs）与其他系统级开发工具在 Linux 上的安装位置一致。适用于共享机器部署场景，一次系统安装可服务所有用户。每个用户的个人配置（认证、技能、会话）仍位于各自的 ~/.aigenlabs/ 或显式指定的 AIGENLABS_HOME 下。

安装后

重新加载 shell 并开始聊天：

source ~/.bashrc   # 或：source ~/.zshrc
aigenlabs             # 开始聊天！

如需稍后重新配置单项设置，使用以下专用命令：

aigenlabs model          # 选择 LLM 提供商和模型
aigenlabs tools          # 配置启用的工具
aigenlabs gateway setup  # 配置消息平台
aigenlabs config set     # 设置单个配置项
aigenlabs setup          # 或运行完整的设置向导一次性配置所有内容

最快路径：Nous Portal

一个订阅涵盖 300+ 个模型以及 Tool Gateway（网络搜索、图像生成、TTS、云端浏览器）。无需逐一管理各工具的密钥：

aigenlabs setup --portal

该命令一次性完成登录、设置 Nous 为提供商并开启 Tool Gateway。

前置条件

pip install： 除 Python 3.11+ 外无其他前置条件，其余均自动处理。

Git 安装程序： 唯一的前置条件是 Git。安装程序自动处理其余一切：

uv（快速 Python 包管理器）
Python 3.11（通过 uv，无需 sudo）
Node.js v22（用于浏览器自动化和 WhatsApp 桥接）
ripgrep（快速文件搜索）
ffmpeg（TTS 的音频格式转换）

信息

你无需手动安装 Python、Node.js、ripgrep 或 ffmpeg。安装程序会检测缺失的依赖并自动安装。只需确保 git 可用（git --version）。

Nix 用户

如果你使用 Nix（在 NixOS、macOS 或 Linux 上），有专门的配置路径，包含 Nix flake、声明式 NixOS 模块和可选容器模式。请参阅 Nix & NixOS 配置 指南。

手动 / 开发者安装

如果你想克隆仓库并从源码安装——用于贡献代码、从特定分支运行或完全控制虚拟环境——请参阅贡献指南中的开发环境配置章节。

非 Sudo / 系统服务用户安装

支持以专用非特权用户身份运行 AigenLabs（例如 aigenlabs systemd 服务账户，或任何没有 sudo 权限的用户）。安装路径中真正需要 root 权限的只有 Playwright 的 --with-deps 步骤，该步骤通过 apt 安装 Chromium 所需的共享库（libnss3、libxkbcommon 等）。安装程序会检测 sudo 是否可用，并在不可用时优雅降级——它会将 Chromium 二进制安装到服务用户自己的 Playwright 缓存中，并打印管理员需要单独运行的确切命令。

推荐的分步方式（Debian/Ubuntu）：

一次性操作，以具有 sudo 权限的管理员用户身份，安装 Chromium 所需的系统库：
```
sudo npx playwright install-deps chromium
```
（可在任意位置运行——npx 会自动获取 Playwright。）
以非特权服务用户身份，运行常规安装程序。它会检测到缺少 sudo，跳过 --with-deps，并将 Chromium 安装到用户本地的 Playwright 缓存中：
```
curl -fsSL https://docs.aigenlabs.vn/install.sh | bash
```
如果想完全跳过 Playwright 步骤——例如在无头环境中运行且不需要浏览器自动化——传入 --skip-browser：
```
curl -fsSL https://docs.aigenlabs.vn/install.sh | bash -s -- --skip-browser
```

使 aigenlabs 对服务用户的 shell 可用。 安装程序将启动器写入 ~/.local/bin/aigenlabs。系统服务账户通常具有不包含 ~/.local/bin 的最小 PATH。可以将其添加到用户环境，或将启动器符号链接到系统位置：

# 方案 A — 添加到服务用户的 profile
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

# 方案 B — 系统级符号链接（以管理员身份运行）
sudo ln -s /home/aigenlabs/.aigenlabs/aigenlabs-agent/venv/bin/aigenlabs /usr/local/bin/aigenlabs

验证： aigenlabs doctor 现在应能正常运行。如果出现 ModuleNotFoundError: No module named 'dotenv'，说明你在用系统 Python 调用仓库源码中的 aigenlabs 文件（~/.aigenlabs/aigenlabs-agent/aigenlabs），而非 venv 启动器（~/.aigenlabs/aigenlabs-agent/venv/bin/aigenlabs）——请修正步骤 3。

同样的方式适用于 Arch（安装程序使用 pacman，具有相同的 sudo 检测逻辑）、Fedora/RHEL 和 openSUSE——这些发行版完全不支持 --with-deps，因此管理员始终需要单独安装系统库。安装程序会打印相应的 dnf/zypper 命令。

故障排查

问题	解决方案
`aigenlabs: command not found`	重新加载 shell（`source ~/.bashrc`）或检查 PATH
`API key not set`	运行 `aigenlabs model` 配置提供商，或 `aigenlabs config set OPENROUTER_API_KEY your_key`
更新后配置丢失	运行 `aigenlabs config check`，然后运行 `aigenlabs config migrate`

如需更多诊断信息，运行 aigenlabs doctor——它会告诉你确切缺少什么以及如何修复。

安装方式自动检测

AigenLabs 会自动检测安装方式（pip、git 安装程序、Homebrew 或 NixOS），aigenlabs update 会打印对应路径的更新命令。无需设置任何环境变量——检测基于安装目录结构（Python site-packages、~/.aigenlabs/aigenlabs-agent/、Homebrew 前缀或 Nix store 路径）。aigenlabs doctor 也会在其环境摘要中显示检测到的安装方式。

快速安装​

一行安装命令（Linux / macOS / WSL2）​

Windows（原生，PowerShell）​

Android / Termux​

安装程序做了什么​

安装目录结构​

安装后​

前置条件​

手动 / 开发者安装​

非 Sudo / 系统服务用户安装​

故障排查​

安装方式自动检测​