安装

只需两分钟，通过一行命令即可启动 Hermes Agent。

快速安装

Linux / macOS / WSL2

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

Windows（原生，PowerShell）— 早期测试版

早期测试版

原生 Windows 支持处于早期测试版。它可以安装并适用于常见场景，但尚未经过像 POSIX 安装程序那样广泛的实战测试。遇到问题时请提交 issue。如需目前在 Windows 上最成熟的方案，请使用上方 WSL2 中的 Linux/macOS 一键安装命令。

打开 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 — 一个自包含的 Git-for-Windows 发行版，提供 bash.exe 和 Hermes 用于执行 shell 命令的完整 POSIX 工具链；在 32 位 Windows 上，安装程序会回退到 MinGit，它缺少 bash 并禁用 terminal-tool / agent-browser 功能）。它会在 %LOCALAPPDATA%\hermes\hermes-agent 下克隆仓库，创建虚拟环境，并将 hermes 添加到你的用户 PATH。安装后请重启终端（或打开一个新的 PowerShell 窗口），以便 PATH 生效。

Git 的处理方式：

如果 git 已经在你的 PATH 中，安装程序会使用现有安装。
否则，它会下载可移植的 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

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_API_LEVEL 以支持 Android wheel 构建
优先使用完整的 .[termux-all] 扩展，如果首次尝试编译失败，则回退到较小的 .[termux] 扩展（最后是基础安装）
默认跳过未经测试的浏览器 / WhatsApp 引导流程

如需完整的手动安装步骤，请参考专门的 Termux 指南。

Windows 功能完整性（早期测试版）

原生 Windows 处于早期测试版。除基于浏览器的仪表板聊天终端外，所有功能都可以在 Windows 上原生运行：

CLI（hermes chat、hermes setup、hermes gateway 等） — 原生，使用你的默认终端
网关（Telegram、Discord、Slack 等） — 原生，作为后台 PowerShell 进程运行
Cron 调度器 — 原生
浏览器工具 — 原生（通过 Node.js 使用 Chromium）
MCP 服务器 — 原生（支持 stdio 和 HTTP 传输）
仪表板 /chat 终端面板 — 仅限 WSL2（使用 POSIX PTY；原生 Windows 没有等效功能）。仪表板的其余部分（会话、作业、指标）可以原生运行 —— 只有嵌入式 PTY 终端选项卡受限。

如果在环境中遇到与编码相关的错误并想回退到旧的 cp1252 stdio 路径（用于二分查找），请设置 HERMES_DISABLE_WINDOWS_UTF8=1。

安装脚本做了什么

安装脚本会自动处理一切——所有依赖项（Python、Node.js、ripgrep、ffmpeg）、仓库克隆、虚拟环境创建、全局 hermes 命令配置，以及 LLM 提供商设置。完成后即可开始对话。

安装目录布局

安装位置取决于你是以普通用户还是以 root 身份运行安装：

安装方式	代码位置	`hermes` 二进制文件	数据目录
用户级（普通）	`~/.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、会话）仍保存在各自的 ~/.hermes/ 或显式指定的 HERMES_HOME 目录下。

安装完成后

重新加载 Shell 即可开始使用：

source ~/.bashrc   # 或: source ~/.zshrc
hermes             # 开始对话！

后续如需单独调整某项配置，可使用以下命令：

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 音频格式转换）

信息

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

Nix 用户

如果你使用 Nix（无论是 NixOS、macOS 还是 Linux），我们提供了专用的安装路径——包括 Nix flake、声明式 NixOS 模块和可选的容器模式。请参阅 Nix & NixOS 安装指南。

手动 / 开发者安装

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

无 Sudo 权限 / 系统服务用户安装

以专用非特权用户（例如 hermes systemd 服务账户，或任何没有 sudo 访问权限的用户）运行 Hermes 是受支持的。安装路径中真正需要 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 | bash
```
如果你想完全跳过 Playwright 步骤 —— 例如因为你运行在无头模式下且不需要浏览器自动化 —— 传递 --skip-browser：
```
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash -s -- --skip-browser
```

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

# 选项 A — 添加到服务用户的环境变量
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——它会准确告诉你缺少什么以及如何修复。

快速安装​

Linux / macOS / WSL2​

Windows（原生，PowerShell）— 早期测试版​

Android / Termux​

安装脚本做了什么​

安装目录布局​

安装完成后​

前置要求​

手动 / 开发者安装​

无 Sudo 权限 / 系统服务用户安装​

故障排查​