Linux / macOS / WSL2
Section titled “Linux / macOS / WSL2”curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bashWindows (原生 PowerShell) — 早期测试版
Section titled “Windows (原生 PowerShell) — 早期测试版”打开 PowerShell 并运行：
irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex该安装程序会自动处理 所有事项：uv、Python 3.11、Node.js 22、ripgrep、ffmpeg 以及一个便携式 Git Bash（PortableGit —— 一个独立的 Windows 版 Git 发行版，包含 bash.exe 和 Hermes 执行 Shell 命令所需的完整 POSIX 工具链；在 32 位 Windows 上，安装程序会回退到不含 bash 的 MinGit，这将禁用终端工具和浏览器功能）。
它会将仓库克隆至 %LOCALAPPDATA%\hermes\hermes-agent，创建虚拟环境，并将 hermes 添加到你的 用户 PATH 路径 中。安装完成后，请重启终端（或打开新的 PowerShell 窗口）以使 PATH 生效。
关于 Git 的处理方式：
- 如果你的 PATH 中已有
git，安装程序将使用现有版本。 - 否则，它将下载便携式 PortableGit（约 50MB，来自官方 git-for-windows GitHub 发行版）并解压至
%LOCALAPPDATA%\hermes\git。无需管理员权限，完全隔离 —— 不会干扰任何已有的系统 Git 安装（无论其是否损坏）。（在 32 位 Windows 上会回退到 MinGit，因为 PortableGit 仅提供 64 位和 ARM64 资源；依赖 bash 的 Hermes 功能在 32 位主机上将无法使用。）
为什么不使用 winget？ 早期的设计曾通过 winget install Git.Git 自动安装 Git，但当系统原有的 Git 处于部分损坏状态时，winget 的表现极差。使用便携式 Git 方案可以避开 winget、Windows 安装程序注册表以及任何现有的系统 Git。如果 Hermes 自带的 Git 损坏了，只需运行 Remove-Item %LOCALAPPDATA%\hermes\git 并重新运行安装程序即可 —— 对系统无影响，也无卸载烦恼。
安装程序还会将 HERMES_GIT_BASH_PATH 设置为指向找到的 bash.exe，以便 Hermes 在新的 Shell 中能确定性地找到它。
如果你更喜欢 WSL2，上方的 Linux 安装程序可以在其内部运行；原生安装和 WSL 安装可以共存且互不冲突（原生数据位于 %LOCALAPPDATA%\hermes，WSL 数据位于 ~/.hermes）。
Android / Termux
Section titled “Android / Termux”Hermes 现在也提供支持 Termux 的安装路径：
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash安装程序会自动检测 Termux 并切换至经过测试的 Android 流程：
- 使用 Termux 的
pkg管理器安装系统依赖（git,python,nodejs,ripgrep,ffmpeg, 编译工具）。 - 使用
python -m venv创建虚拟环境。 - 为 Android Wheel 构建自动导出
ANDROID_API_LEVEL。 - 优先尝试安装
.[termux-all]扩展包；如果编译失败，则回退到较小的.[termux]，最后尝试基础安装。 - 默认跳过未经测试的浏览器 / WhatsApp 引导程序。
如果你需要完全手动的路径，请参考专门的 Termux 指南。
安装程序做了什么
Section titled “安装程序做了什么”安装程序会自动处理一切 —— 所有依赖项（Python, Node.js, ripgrep, ffmpeg）、仓库克隆、虚拟环境、全局 hermes 命令设置以及 LLM 服务商配置。完成后，你就可以直接开始聊天了。
安装程序放置文件的位置取决于你是以普通用户还是 root 身份安装：
| 安装方式 | 代码位于 | hermes 二进制文件 | 数据目录 |
|---|---|---|---|
| pip install | Python site-packages | ~/.local/bin/hermes（console_scripts） | ~/.hermes/ |
| 每用户安装（git 安装器） | ~/.hermes/hermes-agent/ | ~/.local/bin/hermes（符号链接） | ~/.hermes/ |
Root 模式（sudo curl … | sudo bash） | /usr/local/lib/hermes-agent/ | /usr/local/bin/hermes | /root/.hermes/（或 $HERMES_HOME） |
Root 模式的 FHS 布局（/usr/local/lib/…、/usr/local/bin/hermes）与 Linux 上其他系统级开发工具的安装位置一致。它适用于共享机器部署，即一个系统级安装需要服务所有用户的场景。每个用户的配置（认证、skills、sessions）仍然位于各自的 ~/.hermes/ 或显式指定的 HERMES_HOME 下。
重新加载 Shell 并开始聊天：
source ~/.bashrc # 或者: source ~/.zshrchermes # 开始聊天！稍后若需重新配置具体设置，请使用专用命令：
hermes model—— 选择你的 LLM 服务商和模型。hermes tools—— 配置启用的工具。hermes gateway setup—— 设置消息平台。hermes config set—— 设置具体的配置项。hermes setup—— 或者运行完整的设置向导来一次性配置所有内容。
唯一的必备条件是 Git。安装程序会自动处理其他所有事项：
- uv（极速 Python 包管理器）
- Python 3.11（通过 uv 安装，无需 sudo 权限）
- Node.js v22（用于浏览器自动化和 WhatsApp 桥接）
- ripgrep（极速文件搜索）
- ffmpeg（用于 TTS 的音频格式转换）
手动 / 开发者安装
Section titled “手动 / 开发者安装”如果你想通过克隆仓库并从源码安装 —— 以便贡献代码、运行特定分支或完全控制虚拟环境 —— 请参阅贡献指南中的 开发环境设置 部分。
非 Sudo / 系统服务用户安装
Section titled “非 Sudo / 系统服务用户安装”支持将 Hermes 作为独立的非特权用户（例如 hermes 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://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh](https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh) | bash如果你想完全跳过 Playwright 步骤 —— 例如因为你正在无头（headless）环境下运行且不需要浏览器自动化 —— 请传递 --skip-browser 参数：
curl -fsSL [https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh](https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh) | bash -s -- --skip-browser- 让 hermes 在服务用户的 shell 中可用。安装程序会将启动器写入
~/.local/bin/hermes。系统服务账户通常只有极其精简的 PATH，其中不包含~/.local/bin。要么将其添加到该用户境变量中，要么将启动器软链接到系统目录：
# 选项 A — 添加到服务用户的 profile 中echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
# 选项 B — 在全系统范围内创建软链接（作为管理员运行）sudo ln -s /home/hermes/.hermes/hermes-agent/venv/bin/hermes /usr/local/bin/hermes- 验证：此时运行
hermes doctor应当可以顺利通过。如果你遇到ModuleNotFoundError: No module named 'dotenv'，说明你正在使用系统 Python 调用源码仓库中的 hermes 文件（~/.hermes/hermes-agent/hermes），而不是使用 venv 启动器（~/.hermes/hermes-agent/venv/bin/hermes）—— 请修正第 3 步。
同样的模式也适用于 Arch（安装程序使用 pacman 并带有相同的 sudo 检测逻辑）、Fedora/RHEL 和 openSUSE —— 这些发行版完全不支持 --with-deps，因此管理员总是需要单独安装系统库。相关的 dnf/zypper 命令会由安装程序打印出来。
| 问题 | 解决方法 |
|---|---|
| hermes: command not found | 重新加载你的 Shell（source ~/.bashrc）或检查 PATH 变量 |
| API key not set | 运行 hermes model 配置你的服务商，或执行 hermes config set OPENROUTER_API_KEY your_key |
| 更新后配置丢失 | 运行 hermes config check 然后执行 hermes config migrate |
如需更多诊断信息，请运行 hermes doctor —— 它会明确告知你缺失的内容及修复方法。