---
title: "安装 Hermes Agent"
description: "用官方安装路径在 Linux、macOS、WSL2、原生 Windows（早期测试）或 Termux 上安装 Hermes Agent，并完成 PATH、目录、依赖和排障验收。"
verifiedAt: "2026-05-09"
---

Hermes Agent 的安装本身不复杂。真正容易出错的是：脚本跑完后 shell 找不到 `hermes` 命令、provider（推理服务商）没配置、`~/.hermes/` 这个配置目录看不懂、Termux 或 WSL2 环境误用、或者一上来就接 Gateway（消息网关）和 cron（定时任务）导致问题叠在一起没法定位。

官方资料：[Installation](https://hermes-agent.nousresearch.com/docs/getting-started/installation)、[Quickstart](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart)、[GitHub README](https://github.com/NousResearch/hermes-agent)。

> [!NOTE]
> **先给结论**：先用官方一行安装脚本；POSIX 系（Linux / macOS / WSL2 / Termux）跑 `install.sh`，原生 Windows 跑 PowerShell `install.ps1`（早期测试，比 WSL2 路径粗糙）。安装后先确认 `hermes --help`、`hermes model` 和 `~/.hermes/`，不要马上接消息平台和 cron。

## 支持环境

官方安装脚本现在覆盖五类环境：

| 环境 | 脚本 | 状态 |
| --- | --- | --- |
| Linux | `install.sh`（一行 curl） | 主路径，最稳定 |
| macOS | `install.sh` | 主路径 |
| Windows via WSL2 | 在 WSL2 里跑 `install.sh` | **Windows 推荐路径**——比原生 Windows 经过更多验证 |
| 原生 Windows（PowerShell） | `install.ps1`（一行 PowerShell） | **Early Beta** ⚠️ —— 装得上、跑得通主流程，但还没经过 POSIX 那么广的实战，遇到坑请回报 |
| Android via Termux | `install.sh`（自动检测 Termux） | 主路径，安装器自动切换到 Android 流程 |

> [!TIP]
> **Windows 怎么选**：日常工作或团队部署用 **WSL2 + `install.sh`**——稳定且能复用所有 Linux 资料；只想在原生 Windows 上快速试一下、不在意细节问题，可以试 `install.ps1`。两者数据互不冲突（原生数据在 `%LOCALAPPDATA%\hermes`，WSL 数据在 `~/.hermes`）。

Termux（Android 终端模拟器）走同一个 `install.sh`，但安装器会自动检测并切换到 Android 专用流程：用 Termux `pkg` 装系统依赖（`git`、`python`、`nodejs`、`ripgrep`、`ffmpeg`），用 `python -m venv` 创建虚拟环境，自动设 `ANDROID_API_LEVEL` 让 Python wheel（预编译包）能正确构建，并装精简的 `.[termux]` extra。浏览器和 WhatsApp bootstrap（启动）这类不稳定能力默认不启用。

## 一行安装

POSIX 系（Linux、macOS、WSL2、Termux）执行：

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

原生 Windows 打开 PowerShell（早期测试，遇坑可切 WSL2）：

```powershell
irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex
```

安装前只需要先确认 `git` 可用：

```bash
git --version
```

官方安装器会自动处理常见依赖：`uv`（Python 包管理器）、Python、Node.js、`ripgrep`（高速正则搜索）、`ffmpeg`（音视频处理）等（具体版本号按官方 [Installation 页](https://hermes-agent.nousresearch.com/docs/getting-started/installation) 当前要求为准，避免在教程里写死）。**不要**在安装前手动混装一堆 Python / Node 环境——先让安装器走完，再按报错补缺口；提前装的版本反而容易和安装器期望版本冲突。

## 安装器会做什么

安装器主要完成五件事：

1. 检查系统和依赖。
2. 克隆 Hermes Agent 仓库。
3. 创建 Python virtualenv（虚拟环境，把 Hermes 的依赖和系统 Python 隔离）。
4. 注册全局 `hermes` 命令（在 `~/.local/bin/` 下放一个 symlink 指向真正的入口脚本）。
5. 引导你进入 LLM provider（推理服务商）配置——填 OpenAI / Anthropic / Nous Portal 等家的 API key 或 OAuth 凭据。

安装成功的标准不是「脚本没有红字」，而是 `hermes` 命令能被当前 shell 找到，并能进入帮助或模型配置。脚本跑通了 ≠ 装好了——下一节验收命令入口才是真的标准。

## 安装目录

POSIX 系普通用户安装后，先记住这三个位置：

```text
~/.hermes/hermes-agent/    Hermes Agent 源码（仓库本体 + virtualenv）
~/.local/bin/hermes        全局命令入口，通常是指向源码内启动脚本的 symlink
~/.hermes/                 配置、auth、skills、sessions、memory、logs（用户数据，可备份）
```

如果用 root-mode（`sudo curl ... | sudo bash`）做系统级安装，官方路径会变成类似：

```text
/usr/local/lib/hermes-agent/    系统级源码位置（FHS 标准）
/usr/local/bin/hermes           系统级命令入口
/root/.hermes/ 或 HERMES_HOME   root 用户数据目录
```

原生 Windows 安装路径不同：源码放在 `%LOCALAPPDATA%\hermes\hermes-agent`，自带的 portable Git 放在 `%LOCALAPPDATA%\hermes\git`，`hermes` 加进**用户级 PATH**（不是系统级，不要 admin），数据在 `%LOCALAPPDATA%\hermes`。**装完一定要重启终端**或开新 PowerShell 窗口，PATH 才会生效。

个人学习和单用户机器优先用普通用户安装。共享服务器或统一运维场景才考虑 root-mode，并且要单独规划每个用户的 `HERMES_HOME` 环境变量和密钥边界——不要让所有用户共享一份 `~/.hermes/` 数据。

## 安装后第一步

POSIX 系安装完成后先**重载 shell**，让新加进 PATH 的 `hermes` 命令在当前终端生效。bash 用户：

```bash
source ~/.bashrc
```

zsh 用户：

```bash
source ~/.zshrc
```

> [!TIP]
> 不确定自己用的是哪个 shell？运行 `echo $SHELL`。看到 `/bin/zsh` 就用 `.zshrc`，看到 `/bin/bash` 就用 `.bashrc`——**改错文件是 `command not found` 最常见的原因**：明明是 zsh 用户，却只重载了 `.bashrc`。

原生 Windows 用户**关掉当前 PowerShell 窗口、开个新窗口**，或在当前窗口运行 `$env:Path` 看 `%LOCALAPPDATA%\hermes` 是否在里面。

然后验收命令入口：

```bash
hermes --help
hermes model
```

`hermes --help` 能输出帮助，说明 PATH 基本没问题。`hermes model` 能进入交互配置，说明下一步可以配置 provider。

## 不要一开始全开功能

第一次安装后的顺序应该是：

```text
install -> PATH check -> hermes model -> first chat -> session resume
（安装 → PATH 验证 → 配 provider → 第一次对话 → 会话恢复）
```

**不要**反过来先接 Telegram、Discord、Slack、WhatsApp、cron、MCP（模型上下文协议）、skills 或 browser automation（浏览器自动化）。基础对话还没跑通时，功能开得越多，排障越慢——同一个问题既可能在模型层、也可能在 toolset、也可能在 backend，最后变成「哪都可能错」。

## 常见问题

**`hermes: command not found`**

先重载 shell（`source ~/.zshrc` 或 `~/.bashrc`），再检查 `~/.local/bin` 是否真的在 `PATH` 里：

```bash
echo $PATH | tr ':' '\n' | grep '\.local/bin'
```

如果你用的是 zsh 却只改了 `.bashrc`，当前 shell 不会自动读到——这是最常见误区。原生 Windows 上则是没重启 PowerShell。

**`API key not set` 或 provider 拒绝调用**

运行 `hermes model` 重新配置 provider。密钥应该写入 Hermes 的配置路径（`~/.hermes/auth.json` 或 `.env`），**不要**贴进公开仓库、普通 Markdown、shell 历史命令或团队聊天群——一旦提交进 git 历史就很难真正撤回。

**Termux 编译失败**

先确认你在 Termux 原生环境里直接执行官方脚本，**不是**在 Android 上套了不受支持的 Linux 容器（如某些"Linux on Android" 应用）。再看 [官方 Termux guide](https://hermes-agent.nousresearch.com/docs/getting-started/termux)。

**原生 Windows：装完了但找不到命令**

99% 是 PATH 没刷新。**关掉当前 PowerShell 窗口、开新窗口**，再 `hermes --help`。还不行就检查 `$env:Path` 里有没有 `%LOCALAPPDATA%\hermes`。

**更新后配置异常**

先跑诊断命令，让 Hermes 自己告诉你哪里坏了：

```bash
hermes doctor
hermes config check
```

必要时再做配置迁移，**不要**直接 `rm -rf ~/.hermes/`——那会一并删掉你所有的 session、memory 和已配的 skill。

## 安装验收清单

安装完成后至少确认下面 6 条。任何一条不过，**先停下排查**，不要继续往下接 provider、Gateway 或 cron：

- [ ] `git --version` 正常输出。
- [ ] `hermes --help` 能打印帮助。
- [ ] `hermes model` 能打开 provider 配置交互界面。
- [ ] `~/.hermes/` 目录已创建（POSIX）或 `%LOCALAPPDATA%\hermes` 已创建（Windows native）。
- [ ] 你能用一句话解释 `config.yaml`、`.env`、`skills`、`sessions`、`memory` 和 `logs` 大致放在哪里、各管什么。
- [ ] **没有把任何 API key 写进公开文件、git 仓库或 shell history**。

## 下一步

<Cards>
  <Card title="快速上手 Hermes Agent" description="安装完成后，下一步配置 provider、完成第一次对话并验证 session 恢复——5 分钟跑通最小闭环。" href="/docs/hermes/official/00-getting-started/quickstart" />
  <Card title="配置 Hermes Agent" description="如果安装成功但 provider、密钥或 backend 混乱，先查配置页弄清 ~/.hermes 下各文件的分工。" href="/docs/hermes/official/01-user-guide/configuration" />
</Cards>

## 官方资料

- [Installation 完整页](https://hermes-agent.nousresearch.com/docs/getting-started/installation)
- [Quickstart](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart)
- [Termux 专项 guide](https://hermes-agent.nousresearch.com/docs/getting-started/termux)
- [Updating & Uninstalling](https://hermes-agent.nousresearch.com/docs/getting-started/updating)
- [GitHub README](https://github.com/NousResearch/hermes-agent)
