Sami/hermes-agent
1
0
Fork 0
forked from Zakaria/hermes-agent
Code Pull Requests Activity

Hermes-agent

Browse Source
This commit is contained in:
Zakaria
2026-06-14 14:30:48 -04:00
commit dac4b88b94
5058 changed files with 1884848 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting-started/installation.md
+207
View File
@@ -0,0 +1,207 @@
---
sidebar_position: 2
title: "安装"
description: "在 Linux、macOS、WSL2、原生 Windows 或通过 Termux 在 Android 上安装 Hermes Agent"
---
# 安装
使用一行安装命令，两分钟内即可启动并运行 Hermes Agent。
## 快速安装
### 一行安装命令（Linux / macOS / WSL2）
基于 git 的安装方式，跟踪 `main` 分支，可立即获取最新变更：
```bash
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
```
### Windows（原生，PowerShell）
原生 Windows 无需 WSL 即可运行 Hermes——CLI、gateway、TUI 和工具均可原生运行。（原生安装与 WSL2 安装可干净共存；唯一仅限 WSL2 的功能见下方功能说明。）遇到 bug 请[提交 issue](https://github.com/NousResearch/hermes-agent/issues)。
打开 PowerShell 并运行：
```powershell
iex (irm https://hermes-agent.nousresearch.com/install.ps1)
```
安装程序处理**一切**：`uv`、Python 3.11、Node.js 22、`ripgrep`、`ffmpeg`，**以及一个便携式 Git Bash**（PortableGit——一个自包含的 Git-for-Windows 发行版，附带 `bash.exe` 和 Hermes 用于 shell 命令的完整 POSIX 工具链；在 32 位 Windows 上安装程序会回退到 MinGit，后者缺少 bash，终端工具和 agent 浏览器功能将被禁用）。它将仓库克隆到 `%LOCALAPPDATA%\hermes\hermes-agent`，创建虚拟环境，并将 `hermes` 添加到**用户 PATH**。安装完成后请重启终端（或打开新的 PowerShell 窗口）以使 PATH 生效。
**Git 的处理方式：**
1. 如果 `git` 已在你的 PATH 中，安装程序将使用现有安装。
2. 否则，它会下载便携式 **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`）。
**桌面安装程序（替代方案）：** 也提供一个轻量 GUI 安装程序——下载 Hermes Desktop，运行 `.exe`，首次启动时它会在后台调用 `install.ps1` 来配置 Python（通过 `uv`）、Node、PortableGit 及其余依赖。桌面应用和 PowerShell 安装的 CLI 共享相同的安装目录和数据目录，可以单独或同时使用。详见 [Windows（原生）指南](../user-guide/windows-native#desktop-installer-alternative)。
### Android / Termux
Hermes 现在也提供 Termux 感知的安装路径：
```bash
curl -fsSL https://hermes-agent.nousresearch.com/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 指南](./termux.md)。
:::note Windows 功能对等性
除基于浏览器的 dashboard 聊天终端外，其余功能均可在 Windows 上原生运行：
- **CLI（`hermes chat`、`hermes setup`、`hermes gateway` 等）** — 原生，使用默认终端
- **Gateway（Telegram、Discord、Slack 等）** — 原生，作为后台 PowerShell 进程运行
- **Cron 调度器** — 原生
- **浏览器工具** — 原生（通过 Node.js 使用 Chromium）
- **MCP 服务器** — 原生（stdio 和 HTTP 传输均支持）
- **Dashboard `/chat` 终端面板** — **仅限 WSL2**（使用 POSIX PTY（伪终端），原生 Windows 无等效实现）。Dashboard 的其余部分（会话、任务、指标）可原生运行——仅嵌入式 PTY 终端标签页受限。
如果遇到编码相关的 bug 并希望回退到旧版 cp1252 stdio 路径（用于问题定位），请在环境中设置 `HERMES_DISABLE_WINDOWS_UTF8=1`。
:::
### 安装程序做了什么
安装程序自动处理一切——所有依赖（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 上的安装位置一致。适用于共享机器部署场景，一次系统安装可服务所有用户。每个用户的个人配置（认证、技能、会话）仍位于各自的 `~/.hermes/` 或显式指定的 `HERMES_HOME` 下。
### 安装后
重新加载 shell 并开始聊天：
```bash
source ~/.bashrc # 或：source ~/.zshrc
hermes # 开始聊天！
```
如需稍后重新配置单项设置，使用以下专用命令：
```bash
hermes model # 选择 LLM 提供商和模型
hermes tools # 配置启用的工具
hermes gateway setup # 配置消息平台
hermes config set # 设置单个配置项
hermes setup # 或运行完整的设置向导一次性配置所有内容
```
:::tip 最快路径：Nous Portal
一个订阅涵盖 300+ 个模型以及 [Tool Gateway](/user-guide/features/tool-gateway)（网络搜索、图像生成、TTS、云端浏览器）。无需逐一管理各工具的密钥：
```bash
hermes 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 的音频格式转换）
:::info
你**无需**手动安装 Python、Node.js、ripgrep 或 ffmpeg。安装程序会检测缺失的依赖并自动安装。只需确保 `git` 可用（`git --version`）。
:::
:::tip Nix 用户
如果你使用 Nix（在 NixOS、macOS 或 Linux 上），有专门的配置路径，包含 Nix flake、声明式 NixOS 模块和可选容器模式。请参阅 **[Nix & NixOS 配置](./nix-setup.md)** 指南。
:::
---
## 手动 / 开发者安装
如果你想克隆仓库并从源码安装——用于贡献代码、从特定分支运行或完全控制虚拟环境——请参阅贡献指南中的[开发环境配置](../developer-guide/contributing.md#development-setup)章节。
---
## 非 Sudo / 系统服务用户安装
支持以专用非特权用户身份运行 Hermes（例如 `hermes` systemd 服务账户，或任何没有 `sudo` 权限的用户）。安装路径中真正需要 root 权限的只有 Playwright 的 `--with-deps` 步骤，该步骤通过 `apt` 安装 Chromium 所需的共享库（`libnss3`、`libxkbcommon` 等）。安装程序会检测 sudo 是否可用，并在不可用时优雅降级——它会将 Chromium 二进制安装到服务用户自己的 Playwright 缓存中，并打印管理员需要单独运行的确切命令。
**推荐的分步方式（Debian/Ubuntu）：**
1. **一次性操作，以具有 sudo 权限的管理员用户身份**，安装 Chromium 所需的系统库：
```bash
sudo npx playwright install-deps chromium
```
（可在任意位置运行——`npx` 会自动获取 Playwright。）
2. **以非特权服务用户身份**，运行常规安装程序。它会检测到缺少 sudo，跳过 `--with-deps`，并将 Chromium 安装到用户本地的 Playwright 缓存中：
```bash
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
```
如果想完全跳过 Playwright 步骤——例如在无头环境中运行且不需要浏览器自动化——传入 `--skip-browser`：
```bash
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -s -- --skip-browser
```
3. **使 `hermes` 对服务用户的 shell 可用。** 安装程序将启动器写入 `~/.local/bin/hermes`。系统服务账户通常具有不包含 `~/.local/bin` 的最小 PATH。可以将其添加到用户环境，或将启动器符号链接到系统位置：
```bash
# 方案 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
```
4. **验证：** `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`——它会告诉你确切缺少什么以及如何修复。
## 安装方式自动检测
Hermes 会自动检测安装方式（`pip`、git 安装程序、Homebrew 或 NixOS），`hermes update` 会打印对应路径的更新命令。无需设置任何环境变量——检测基于安装目录结构（Python site-packages、`~/.hermes/hermes-agent/`、Homebrew 前缀或 Nix store 路径）。`hermes doctor` 也会在其环境摘要中显示检测到的安装方式。
website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting-started/learning-path.md
+154
View File
@@ -0,0 +1,154 @@
---
sidebar_position: 3
title: '学习路径'
description: '根据您的经验水平和目标，选择适合您的 Hermes Agent 文档学习路径。'
---
# 学习路径
Hermes Agent 功能丰富——CLI 助手、Telegram/Discord 机器人、任务自动化、强化学习训练等。本页帮助您根据自身经验水平和目标，确定从哪里开始、阅读哪些内容。
:::tip 从这里开始
如果您尚未安装 Hermes Agent，请先阅读[安装指南](/getting-started/installation)，然后完成[快速入门](/getting-started/quickstart)。以下内容均假设您已完成安装。
:::
## 如何使用本页
- **已知自己的水平？** 跳转至[按经验水平](#by-experience-level)表格，按照对应层级的阅读顺序进行。
- **有明确目标？** 跳至[按使用场景](#by-use-case)，找到匹配的场景。
- **随便浏览？** 查看[主要功能](#key-features-at-a-glance)表格，快速了解 Hermes Agent 的全部能力。
## 按经验水平
| 水平 | 目标 | 推荐阅读 | 预计时间 |
|---|---|---|---|
| **初级** | 快速上手，进行基本对话，使用内置工具 | [安装](/getting-started/installation) → [快速入门](/getting-started/quickstart) → [CLI 用法](/user-guide/cli) → [配置](/user-guide/configuration) | 约 1 小时 |
| **中级** | 搭建消息机器人，使用记忆、cron 任务、技能等高级功能 | [会话](/user-guide/sessions) → [消息](/user-guide/messaging) → [工具](/user-guide/features/tools) → [技能](/user-guide/features/skills) → [记忆](/user-guide/features/memory) → [Cron](/user-guide/features/cron) | 约 2–3 小时 |
| **高级** | 构建自定义工具、创建技能、使用强化学习训练模型、参与项目贡献 | [架构](/developer-guide/architecture) → [添加工具](/developer-guide/adding-tools) → [创建技能](/developer-guide/creating-skills) → [强化学习训练](/user-guide/features/rl-training) → [贡献指南](/developer-guide/contributing) | 约 4–6 小时 |
## 按使用场景
选择与您目标匹配的场景，每个场景均按推荐顺序链接到相关文档。
### "我想要一个 CLI 编程助手"
将 Hermes Agent 用作交互式终端助手，用于编写、审查和运行代码。
1. [安装](/getting-started/installation)
2. [快速入门](/getting-started/quickstart)
3. [CLI 用法](/user-guide/cli)
4. [代码执行](/user-guide/features/code-execution)
5. [上下文文件](/user-guide/features/context-files)
6. [技巧与窍门](/guides/tips)
:::tip
通过上下文文件将文件直接传入对话。Hermes Agent 可以读取、编辑并运行您项目中的代码。
:::
### "我想要一个 Telegram/Discord 机器人"
将 Hermes Agent 部署为您常用消息平台上的机器人。
1. [安装](/getting-started/installation)
2. [配置](/user-guide/configuration)
3. [消息概览](/user-guide/messaging)
4. [Telegram 配置](/user-guide/messaging/telegram)
5. [Discord 配置](/user-guide/messaging/discord)
6. [语音模式](/user-guide/features/voice-mode)
7. [在 Hermes 中使用语音模式](/guides/use-voice-mode-with-hermes)
8. [安全](/user-guide/security)
完整项目示例请参阅：
- [每日简报机器人](/guides/daily-briefing-bot)
- [团队 Telegram 助手](/guides/team-telegram-assistant)
### "我想自动化任务"
调度周期性任务、运行批处理作业，或将多个 agent 动作串联起来。
1. [快速入门](/getting-started/quickstart)
2. [Cron 调度](/user-guide/features/cron)
3. [批处理](/user-guide/features/batch-processing)
4. [委派](/user-guide/features/delegation)
5. [Hooks](/user-guide/features/hooks)
:::tip
Cron 任务让 Hermes Agent 按计划执行任务——每日摘要、定期检查、自动报告——无需您在场。
:::
### "我想构建自定义工具/技能"
通过自定义工具和可复用技能包扩展 Hermes Agent。
1. [插件](/user-guide/features/plugins)
2. [构建 Hermes 插件](/guides/build-a-hermes-plugin)
3. [工具概览](/user-guide/features/tools)
4. [技能概览](/user-guide/features/skills)
5. [MCP（模型上下文协议）](/user-guide/features/mcp)
6. [架构](/developer-guide/architecture)
7. [添加工具](/developer-guide/adding-tools)
8. [创建技能](/developer-guide/creating-skills)
:::tip
对于大多数自定义工具的创建，建议从插件开始。[添加工具](/developer-guide/adding-tools)页面面向 Hermes 核心内置开发，而非常规用户/自定义工具路径。
:::
### "我想训练模型"
使用强化学习（RL）通过 Hermes Agent 内置的 RL 训练流水线对模型行为进行微调。
1. [快速入门](/getting-started/quickstart)
2. [配置](/user-guide/configuration)
3. [强化学习训练](/user-guide/features/rl-training)
4. [Provider 路由](/user-guide/features/provider-routing)
5. [架构](/developer-guide/architecture)
:::tip
强化学习训练在您已了解 Hermes Agent 如何处理对话和工具调用的基础上效果最佳。如果您是新手，请先完成初级路径。
:::
### "我想将其作为 Python 库使用"
以编程方式将 Hermes Agent 集成到您自己的 Python 应用中。
1. [安装](/getting-started/installation)
2. [快速入门](/getting-started/quickstart)
3. [Python 库指南](/guides/python-library)
4. [架构](/developer-guide/architecture)
5. [工具](/user-guide/features/tools)
6. [会话](/user-guide/sessions)
## 主要功能一览
不确定有哪些功能？以下是主要功能的快速目录：
| 功能 | 说明 | 链接 |
|---|---|---|
| **工具** | Agent 可调用的内置工具（文件 I/O、搜索、Shell 等） | [工具](/user-guide/features/tools) |
| **技能** | 可安装的插件包，用于添加新能力 | [技能](/user-guide/features/skills) |
| **记忆** | 跨会话的持久化记忆 | [记忆](/user-guide/features/memory) |
| **上下文文件** | 将文件和目录传入对话 | [上下文文件](/user-guide/features/context-files) |
| **MCP** | 通过模型上下文协议连接外部工具服务器 | [MCP](/user-guide/features/mcp) |
| **Cron** | 调度周期性 agent 任务 | [Cron](/user-guide/features/cron) |
| **委派** | 生成子 agent 以并行处理工作 | [委派](/user-guide/features/delegation) |
| **代码执行** | 运行以编程方式调用 Hermes 工具的 Python 脚本 | [代码执行](/user-guide/features/code-execution) |
| **浏览器** | 网页浏览与抓取 | [浏览器](/user-guide/features/browser) |
| **Hooks** | 事件驱动的回调与中间件 | [Hooks](/user-guide/features/hooks) |
| **批处理** | 批量处理多个输入 | [批处理](/user-guide/features/batch-processing) |
| **强化学习训练** | 使用强化学习微调模型 | [强化学习训练](/user-guide/features/rl-training) |
| **Provider 路由** | 在多个 LLM provider 之间路由请求 | [Provider 路由](/user-guide/features/provider-routing) |
## 下一步阅读
根据您当前所处阶段：
- **刚完成安装？** → 前往[快速入门](/getting-started/quickstart)，运行您的第一次对话。
- **完成了快速入门？** → 阅读 [CLI 用法](/user-guide/cli)和[配置](/user-guide/configuration)，自定义您的设置。
- **已熟悉基础？** → 探索[工具](/user-guide/features/tools)、[技能](/user-guide/features/skills)和[记忆](/user-guide/features/memory)，释放 agent 的全部能力。
- **为团队部署？** → 阅读[安全](/user-guide/security)和[会话](/user-guide/sessions)，了解访问控制与对话管理。
- **准备好开发了？** → 进入[开发者指南](/developer-guide/architecture)，了解内部机制并开始贡献。
- **想要实际示例？** → 查看[指南](/guides/tips)部分，获取真实项目案例和技巧。
:::tip
您无需阅读所有内容。选择与您目标匹配的路径，按顺序跟随链接，即可快速上手。随时可以回到本页寻找下一步。
:::
website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting-started/nix-setup.md
+975
View File
@@ -0,0 +1,975 @@
---
sidebar_position: 3
title: "Nix & NixOS 安装配置"
description: "使用 Nix 安装和部署 Hermes Agent——从快速 `nix run` 到完全声明式的 NixOS 模块（含容器模式）"
---
# Nix & NixOS 安装配置
Hermes Agent 提供了一个 Nix flake，支持三个层级的集成：
| 层级 | 适用对象 | 提供内容 |
|-------|-------------|--------------|
| **`nix run` / `nix profile install`** | 任意 Nix 用户（macOS、Linux） | 包含所有依赖的预构建二进制文件——然后使用标准 CLI 工作流 |
| **NixOS 模块（原生）** | NixOS 服务器部署 | 声明式配置、加固的 systemd 服务、托管密钥 |
| **NixOS 模块（容器）** | 需要自我修改能力的 Agent | 以上所有功能，加上一个持久化 Ubuntu 容器，Agent 可在其中执行 `apt`/`pip`/`npm install` |
:::info 与标准安装的区别
`curl | bash` 安装程序自行管理 Python、Node 及依赖项。Nix flake 替代了所有这些——每个 Python 依赖都是由 [uv2nix](https://github.com/pyproject-nix/uv2nix) 构建的 Nix derivation，运行时工具（Node.js、git、ripgrep、ffmpeg）已封装进二进制文件的 PATH 中。不需要运行时 pip，不需要激活 venv，不需要 `npm install`。
**对于非 NixOS 用户**，这只影响安装步骤。之后的操作（`hermes setup`、`hermes gateway install`、编辑配置）与标准安装完全相同。
**对于 NixOS 模块用户**，整个生命周期有所不同：配置存放在 `configuration.nix` 中，密钥通过 sops-nix/agenix 管理，服务是一个 systemd 单元，CLI 配置命令被屏蔽。管理 hermes 的方式与管理其他 NixOS 服务相同。
:::
## 前提条件
- **已启用 flakes 的 Nix** — 推荐使用 [Determinate Nix](https://install.determinate.systems)（默认启用 flakes）
- **API 密钥**，用于你想使用的服务（至少需要一个 OpenRouter 或 Anthropic 密钥）
---
## 快速开始（任意 Nix 用户）
无需克隆仓库。Nix 会自动获取、构建并运行所有内容：
```bash
# 直接运行（首次使用时构建，之后使用缓存）
nix run github:NousResearch/hermes-agent -- setup
nix run github:NousResearch/hermes-agent -- chat
# 或持久化安装
nix profile install github:NousResearch/hermes-agent
hermes setup
hermes chat
```
执行 `nix profile install` 后，`hermes`、`hermes-agent` 和 `hermes-acp` 将出现在你的 PATH 中。之后的工作流与[标准安装](./installation.md)完全相同——`hermes setup` 引导你完成提供商选择，`hermes gateway install` 设置 launchd（macOS）或 systemd 用户服务，配置存放在 `~/.hermes/`。
<details>
<summary><strong>从本地克隆构建</strong></summary>
```bash
git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
nix build
./result/bin/hermes setup
```
</details>
---
## NixOS 模块
该 flake 导出 `nixosModules.default`——一个完整的 NixOS 服务模块，以声明式方式管理用户创建、目录、配置生成、密钥、文档和服务生命周期。
:::note
此模块需要 NixOS。对于非 NixOS 系统（macOS、其他 Linux 发行版），请使用 `nix profile install` 和上述标准 CLI 工作流。
:::
### 添加 Flake 输入
```nix
# /etc/nixos/flake.nix（或你的系统 flake）
{
inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
hermes-agent.url = "github:NousResearch/hermes-agent";
};
outputs = { nixpkgs, hermes-agent, ... }: {
nixosConfigurations.your-host = nixpkgs.lib.nixosSystem {
system = "x86_64-linux";
modules = [
hermes-agent.nixosModules.default
./configuration.nix
];
};
};
}
```
### 最小化配置
```nix
# configuration.nix
{ config, ... }: {
services.hermes-agent = {
enable = true;
settings.model.default = "anthropic/claude-sonnet-4";
environmentFiles = [ config.sops.secrets."hermes-env".path ];
addToSystemPackages = true;
};
}
```
就这些。`nixos-rebuild switch` 会创建 `hermes` 用户、生成 `config.yaml`、连接密钥并启动 gateway——这是一个长期运行的服务，将 Agent 连接到消息平台（Telegram、Discord 等）并监听传入消息。
:::warning 密钥是必需的
上面的 `environmentFiles` 行假设你已配置 [sops-nix](https://github.com/Mic92/sops-nix) 或 [agenix](https://github.com/ryantm/agenix)。该文件至少应包含一个 LLM 提供商密钥（例如 `OPENROUTER_API_KEY=sk-or-...`）。完整设置请参阅[密钥管理](#secrets-management)。如果你还没有密钥管理器，可以先使用普通文件——只需确保它不是全局可读的：
```bash
echo "OPENROUTER_API_KEY=sk-or-your-key" | sudo install -m 0600 -o hermes /dev/stdin /var/lib/hermes/env
```
```nix
services.hermes-agent.environmentFiles = [ "/var/lib/hermes/env" ];
```
:::
:::tip addToSystemPackages
设置 `addToSystemPackages = true` 有两个作用：将 `hermes` CLI 添加到系统 PATH，**并**在系统范围内设置 `HERMES_HOME`，使交互式 CLI 与 gateway 服务共享状态（会话、技能、cron）。不设置此项时，在 shell 中运行 `hermes` 会创建独立的 `~/.hermes/` 目录。
:::
### 容器感知 CLI
:::info
当 `container.enable = true` 且 `addToSystemPackages = true` 时，主机上的**所有** `hermes` 命令都会自动路由到托管容器中执行。这意味着你的交互式 CLI 会话在与 gateway 服务相同的环境中运行——可以访问所有容器内安装的包和工具。
- 路由是透明的：`hermes chat`、`hermes sessions list`、`hermes version` 等命令都会在底层 exec 进容器
- 所有 CLI 参数原样转发
- 如果容器未运行，CLI 会短暂重试（交互式使用时显示 5 秒 spinner，脚本中静默等待 10 秒），然后以明确的错误退出——不会静默回退
- 对于在 hermes 代码库上工作的开发者，设置 `HERMES_DEV=1` 可绕过容器路由，直接运行本地检出版本
设置 `container.hostUsers` 可创建 `~/.hermes` 到服务状态目录的符号链接，使主机 CLI 和容器共享会话、配置和记忆：
```nix
services.hermes-agent = {
container.enable = true;
container.hostUsers = [ "your-username" ];
addToSystemPackages = true;
};
```
`hostUsers` 中列出的用户会自动加入 `hermes` 组以获得文件权限访问。
**Podman 用户：** NixOS 服务以 root 身份运行容器。Docker 用户通过 `docker` 组 socket 获得访问权限，但 Podman 的 rootful 容器需要 sudo。为你的容器运行时授予免密 sudo：
```nix
security.sudo.extraRules = [{
users = [ "your-username" ];
commands = [{
command = "/run/current-system/sw/bin/podman";
options = [ "NOPASSWD" ];
}];
}];
```
CLI 会自动检测何时需要 sudo 并透明地使用它。没有此配置，你需要手动运行 `sudo hermes chat`。
:::
### 验证运行状态
执行 `nixos-rebuild switch` 后，检查服务是否正在运行：
```bash
# 检查服务状态
systemctl status hermes-agent
# 查看日志（Ctrl+C 停止）
journalctl -u hermes-agent -f
# 如果 addToSystemPackages 为 true，测试 CLI
hermes version
hermes config # 显示生成的配置
```
### 选择部署模式
模块支持两种模式，由 `container.enable` 控制：
| | **原生**（默认） | **容器** |
|---|---|---|
| 运行方式 | 主机上加固的 systemd 服务 | 持久化 Ubuntu 容器，`/nix/store` 以只读方式绑定挂载 |
| 安全性 | `NoNewPrivileges`、`ProtectSystem=strict`、`PrivateTmp` | 容器隔离，内部以非特权用户运行 |
| Agent 可自行安装包 | 否——仅限 Nix 提供的 PATH 上的工具 | 是——`apt`、`pip`、`npm` 安装的包在重启后持久保留 |
| 配置界面 | 相同 | 相同 |
| 适用场景 | 标准部署、最高安全性、可重现性 | Agent 需要运行时安装包、可变环境、实验性工具 |
启用容器模式只需添加一行：
```nix
{
services.hermes-agent = {
enable = true;
container.enable = true;
# ... 其余配置相同
};
}
```
:::info
容器模式通过 `mkDefault` 自动启用 `virtualisation.docker.enable`。如果你使用 Podman，请设置 `container.backend = "podman"` 并将 `virtualisation.docker.enable` 设为 `false`。
:::
---
## 配置
### 声明式设置
`settings` 选项接受任意 attrset，并将其渲染为 `config.yaml`。它支持跨多个模块定义的深度合并（通过 `lib.recursiveUpdate`），因此你可以将配置拆分到多个文件中：
```nix
# base.nix
services.hermes-agent.settings = {
model.default = "anthropic/claude-sonnet-4";
toolsets = [ "all" ];
terminal = { backend = "local"; timeout = 180; };
};
# personality.nix
services.hermes-agent.settings = {
display = { compact = false; personality = "kawaii"; };
memory = { memory_enabled = true; user_profile_enabled = true; };
};
```
两者在求值时深度合并。Nix 声明的键始终优先于磁盘上现有 `config.yaml` 中的键，但 **Nix 未涉及的用户添加键会被保留**。这意味着如果 Agent 或手动编辑添加了 `skills.disabled` 或 `streaming.enabled` 等键，它们在 `nixos-rebuild switch` 后仍会保留。
:::note 模型命名
`settings.model.default` 使用你的提供商所期望的模型标识符。使用 [OpenRouter](https://openrouter.ai)（默认）时，格式如 `"anthropic/claude-sonnet-4"` 或 `"google/gemini-3-flash"`。如果直接使用提供商（Anthropic、OpenAI），请将 `settings.model.base_url` 指向其 API，并使用其原生模型 ID（例如 `"claude-sonnet-4-20250514"`）。未设置 `base_url` 时，Hermes 默认使用 OpenRouter。
:::
:::tip 查找可用配置键
运行 `nix build .#configKeys && cat result` 可查看从 Python `DEFAULT_CONFIG` 中提取的所有叶配置键。你可以将现有的 `config.yaml` 粘贴到 `settings` attrset 中——结构是 1:1 对应的。
:::
<details>
<summary><strong>完整示例：所有常用自定义设置</strong></summary>
```nix
{ config, ... }: {
services.hermes-agent = {
enable = true;
container.enable = true;
# ── 模型 ──────────────────────────────────────────────────────────
settings = {
model = {
base_url = "https://openrouter.ai/api/v1";
default = "anthropic/claude-opus-4.6";
};
toolsets = [ "all" ];
max_turns = 100;
terminal = { backend = "local"; cwd = "."; timeout = 180; };
compression = {
enabled = true;
threshold = 0.85;
summary_model = "google/gemini-3-flash-preview";
};
memory = { memory_enabled = true; user_profile_enabled = true; };
display = { compact = false; personality = "kawaii"; };
agent = { max_turns = 60; verbose = false; };
};
# ── 密钥 ────────────────────────────────────────────────────────
environmentFiles = [ config.sops.secrets."hermes-env".path ];
# ── 文档 ──────────────────────────────────────────────────────────
documents = {
"USER.md" = ./documents/USER.md;
};
# ── MCP 服务器 ────────────────────────────────────────────────────
mcpServers.filesystem = {
command = "npx";
args = [ "-y" "@modelcontextprotocol/server-filesystem" "/data/workspace" ];
};
# ── 容器选项 ──────────────────────────────────────────────────────
container = {
image = "ubuntu:24.04";
backend = "docker";
hostUsers = [ "your-username" ];
extraVolumes = [ "/home/user/projects:/projects:rw" ];
extraOptions = [ "--gpus" "all" ];
};
# ── 服务调优 ─────────────────────────────────────────────────────
addToSystemPackages = true;
extraArgs = [ "--verbose" ];
restart = "always";
restartSec = 5;
};
}
```
</details>
### 逃生舱：自带配置文件
如果你希望完全在 Nix 之外管理 `config.yaml`，请使用 `configFile`：
```nix
services.hermes-agent.configFile = /etc/hermes/config.yaml;
```
这会完全绕过 `settings`——不合并，不生成。每次激活时，该文件会原样复制到 `$HERMES_HOME/config.yaml`。
### 自定义速查表
Nix 用户最常见自定义需求的快速参考：
| 我想要... | 选项 | 示例 |
|---|---|---|
| 更改 LLM 模型 | `settings.model.default` | `"anthropic/claude-sonnet-4"` |
| 使用不同的提供商端点 | `settings.model.base_url` | `"https://openrouter.ai/api/v1"` |
| 添加 API 密钥 | `environmentFiles` | `[ config.sops.secrets."hermes-env".path ]` |
| 给 Agent 设置个性 | `${services.hermes-agent.stateDir}/.hermes/SOUL.md` | 直接管理该文件 |
| 添加 MCP 工具服务器 | `mcpServers.<name>` | 参见 [MCP 服务器](#mcp-servers) |
| 将主机目录挂载到容器 | `container.extraVolumes` | `[ "/data:/data:rw" ]` |
| 为容器传入 GPU 访问 | `container.extraOptions` | `[ "--gpus" "all" ]` |
| 使用 Podman 替代 Docker | `container.backend` | `"podman"` |
| 在主机 CLI 和容器间共享状态 | `container.hostUsers` | `[ "sidbin" ]` |
| 为 Agent 提供额外工具 | `extraPackages` | `[ pkgs.pandoc pkgs.imagemagick ]` |
| 使用自定义基础镜像 | `container.image` | `"ubuntu:24.04"` |
| 覆盖 hermes 包 | `package` | `inputs.hermes-agent.packages.${system}.default.override { ... }` |
| 更改状态目录 | `stateDir` | `"/opt/hermes"` |
| 设置 Agent 的工作目录 | `workingDirectory` | `"/home/user/projects"` |
---
## 密钥管理
:::danger 切勿将 API 密钥放入 `settings` 或 `environment`
Nix 表达式中的值会进入 `/nix/store`，该目录是全局可读的。请始终使用带有密钥管理器的 `environmentFiles`。
:::
`environment`（非密钥变量）和 `environmentFiles`（密钥文件）在激活时（`nixos-rebuild switch`）都会合并到 `$HERMES_HOME/.env` 中。Hermes 在每次启动时读取此文件，因此更改在 `systemctl restart hermes-agent` 后生效——无需重建容器。
### sops-nix
```nix
{
sops = {
defaultSopsFile = ./secrets/hermes.yaml;
age.keyFile = "/home/user/.config/sops/age/keys.txt";
secrets."hermes-env" = { format = "yaml"; };
};
services.hermes-agent.environmentFiles = [
config.sops.secrets."hermes-env".path
];
}
```
密钥文件包含键值对：
```yaml
# secrets/hermes.yaml（使用 sops 加密）
hermes-env: |
OPENROUTER_API_KEY=sk-or-...
TELEGRAM_BOT_TOKEN=123456:ABC...
ANTHROPIC_API_KEY=sk-ant-...
```
### agenix
```nix
{
age.secrets.hermes-env.file = ./secrets/hermes-env.age;
services.hermes-agent.environmentFiles = [
config.age.secrets.hermes-env.path
];
}
```
### OAuth / 认证预置
对于需要 OAuth 的平台（例如 Discord），使用 `authFile` 在首次部署时预置凭据：
```nix
{
services.hermes-agent = {
authFile = config.sops.secrets."hermes/auth.json".path;
# authFileForceOverwrite = true; # 每次激活时强制覆盖
};
}
```
仅当 `auth.json` 不存在时才复制该文件（除非 `authFileForceOverwrite = true`）。运行时 OAuth token 刷新会写入状态目录，并在重建后保留。
---
## 文档
`documents` 选项将文件安装到 Agent 的工作目录（即 `workingDirectory`，Agent 将其作为工作区读取）。Hermes 按约定查找特定文件名：
- **`USER.md`** — 关于 Agent 正在交互的用户的上下文信息。
- 你放置在此处的任何其他文件对 Agent 都可见，作为工作区文件。
Agent 身份文件是独立的：Hermes 从 `$HERMES_HOME/SOUL.md` 加载其主要 `SOUL.md`，在 NixOS 模块中对应 `${services.hermes-agent.stateDir}/.hermes/SOUL.md`。将 `SOUL.md` 放入 `documents` 只会创建一个工作区文件，不会替换主角色文件。
```nix
{
services.hermes-agent.documents = {
"USER.md" = ./documents/USER.md; # 路径引用，从 Nix store 复制
};
}
```
值可以是内联字符串或路径引用。文件在每次 `nixos-rebuild switch` 时安装。
---
## MCP 服务器
`mcpServers` 选项以声明式方式配置 [MCP（Model Context Protocol，模型上下文协议）](https://modelcontextprotocol.io)服务器。每个服务器使用 **stdio**（本地命令）或 **HTTP**（远程 URL）传输方式。
### stdio 传输（本地服务器）
```nix
{
services.hermes-agent.mcpServers = {
filesystem = {
command = "npx";
args = [ "-y" "@modelcontextprotocol/server-filesystem" "/data/workspace" ];
};
github = {
command = "npx";
args = [ "-y" "@modelcontextprotocol/server-github" ];
env.GITHUB_PERSONAL_ACCESS_TOKEN = "\${GITHUB_TOKEN}"; # 从 .env 解析
};
};
}
```
:::tip
`env` 值中的环境变量在运行时从 `$HERMES_HOME/.env` 解析。使用 `environmentFiles` 注入密钥——切勿将 token 直接放入 Nix 配置。
:::
### HTTP 传输（远程服务器）
```nix
{
services.hermes-agent.mcpServers.remote-api = {
url = "https://mcp.example.com/v1/mcp";
headers.Authorization = "Bearer \${MCP_REMOTE_API_KEY}";
timeout = 180;
};
}
```
### 带 OAuth 的 HTTP 传输
对于使用 OAuth 2.1 的服务器，设置 `auth = "oauth"`。Hermes 实现了完整的 PKCE 流程——元数据发现、动态客户端注册、token 交换和自动刷新。
```nix
{
services.hermes-agent.mcpServers.my-oauth-server = {
url = "https://mcp.example.com/mcp";
auth = "oauth";
};
}
```
Token 存储在 `$HERMES_HOME/mcp-tokens/<server-name>.json` 中，在重启和重建后持久保留。
<details>
<summary><strong>无头服务器上的初始 OAuth 授权</strong></summary>
首次 OAuth 授权需要基于浏览器的同意流程。在无头部署中，Hermes 将授权 URL 打印到 stdout/日志，而不是打开浏览器。
**方案 A：交互式引导** — 通过 `docker exec`（容器）或 `sudo -u hermes`（原生）运行一次流程：
```bash
# 容器模式
docker exec -it hermes-agent \
hermes mcp add my-oauth-server --url https://mcp.example.com/mcp --auth oauth
# 原生模式
sudo -u hermes HERMES_HOME=/var/lib/hermes/.hermes \
hermes mcp add my-oauth-server --url https://mcp.example.com/mcp --auth oauth
```
容器使用 `--network=host`，因此 `127.0.0.1` 上的 OAuth 回调监听器可从主机浏览器访问。
**方案 B：预置 token** — 在工作站上完成流程，然后复制 token：
```bash
hermes mcp add my-oauth-server --url https://mcp.example.com/mcp --auth oauth
scp ~/.hermes/mcp-tokens/my-oauth-server{,.client}.json \
server:/var/lib/hermes/.hermes/mcp-tokens/
# 确保：chown hermes:hermes，chmod 0600
```
</details>
### Sampling（服务器发起的 LLM 请求）
部分 MCP 服务器可以向 Agent 请求 LLM 补全：
```nix
{
services.hermes-agent.mcpServers.analysis = {
command = "npx";
args = [ "-y" "analysis-server" ];
sampling = {
enabled = true;
model = "google/gemini-3-flash";
max_tokens_cap = 4096;
timeout = 30;
max_rpm = 10;
};
};
}
```
---
## 托管模式
当 hermes 通过 NixOS 模块运行时，以下 CLI 命令会被**屏蔽**，并显示指向 `configuration.nix` 的描述性错误：
| 被屏蔽的命令 | 原因 |
|---|---|
| `hermes setup` | 配置是声明式的——请在 Nix 配置中编辑 `settings` |
| `hermes config edit` | 配置由 `settings` 生成 |
| `hermes config set <key> <value>` | 配置由 `settings` 生成 |
| `hermes gateway install` | systemd 服务由 NixOS 管理 |
| `hermes gateway uninstall` | systemd 服务由 NixOS 管理 |
这可以防止 Nix 声明的内容与磁盘上实际内容之间产生漂移。检测使用两个信号：
1. **`HERMES_MANAGED=true`** 环境变量——由 systemd 服务设置，对 gateway 进程可见
2. **`.managed` 标记文件**，位于 `HERMES_HOME` 中——由激活脚本设置，对交互式 shell 可见（例如 `docker exec -it hermes-agent hermes config set ...` 也会被屏蔽）
要更改配置，请编辑你的 Nix 配置并运行 `sudo nixos-rebuild switch`。
---
## 容器架构
:::info
本节仅在使用 `container.enable = true` 时相关。原生模式部署可跳过。
:::
启用容器模式后，hermes 在持久化 Ubuntu 容器内运行，Nix 构建的二进制文件以只读方式从主机绑定挂载：
```
主机 容器
──── ─────────
/nix/store/...-hermes-agent-0.1.0 ──► /nix/store/... (ro)
~/.hermes -> /var/lib/hermes/.hermes （符号链接桥接，按 hostUsers）
/var/lib/hermes/ ──► /data/ (rw)
├── current-package -> /nix/store/... （符号链接，每次重建更新）
├── .gc-root -> /nix/store/... （防止 nix-collect-garbage）
├── .container-identity （sha256 哈希，触发重建）
├── .hermes/ （HERMES_HOME）
│ ├── .env （从 environment + environmentFiles 合并）
│ ├── config.yaml （Nix 生成，激活时深度合并）
│ ├── .managed （标记文件）
│ ├── .container-mode （路由元数据：backend、exec_user 等）
│ ├── state.db, sessions/, memories/ （运行时状态）
│ └── mcp-tokens/ （MCP 服务器的 OAuth token）
├── home/ ──► /home/hermes (rw)
└── workspace/ （MESSAGING_CWD）
├── SOUL.md （来自 documents 选项）
└── （Agent 创建的文件）
容器可写层（apt/pip/npm）： /usr, /usr/local, /tmp
```
Nix 构建的二进制文件能在 Ubuntu 容器内运行，是因为 `/nix/store` 被绑定挂载——它携带自己的解释器和所有依赖，不依赖容器的系统库。容器入口点通过 `current-package` 符号链接解析：`/data/current-package/bin/hermes gateway run --replace`。执行 `nixos-rebuild switch` 时，只更新符号链接——容器继续运行。
### 各事件的持久性
| 事件 | 容器重建？ | `/data`（状态） | `/home/hermes` | 可写层（`apt`/`pip`/`npm`） |
|---|---|---|---|---|
| `systemctl restart hermes-agent` | 否 | 保留 | 保留 | 保留 |
| `nixos-rebuild switch`（代码变更） | 否（更新符号链接） | 保留 | 保留 | 保留 |
| 主机重启 | 否 | 保留 | 保留 | 保留 |
| `nix-collect-garbage` | 否（GC root） | 保留 | 保留 | 保留 |
| 镜像变更（`container.image`） | **是** | 保留 | 保留 | **丢失** |
| 卷/选项变更 | **是** | 保留 | 保留 | **丢失** |
| `environment`/`environmentFiles` 变更 | 否 | 保留 | 保留 | 保留 |
仅当容器的**身份哈希**发生变化时才会重建容器。哈希涵盖：schema 版本、镜像、`extraVolumes`、`extraOptions` 和入口点脚本。环境变量、settings、文档或 hermes 包本身的变更**不会**触发重建。
:::warning 可写层丢失
当身份哈希发生变化（镜像升级、新卷、新容器选项）时，容器会被销毁并从 `container.image` 的全新拉取重建。可写层中通过 `apt install`、`pip install` 或 `npm install` 安装的包将丢失。`/data` 和 `/home/hermes` 中的状态会保留（这些是绑定挂载）。
如果 Agent 依赖特定包，考虑将其烘焙到自定义镜像中（`container.image = "my-registry/hermes-base:latest"`），或在 Agent 的 SOUL.md 中编写安装脚本。
:::
### GC Root 保护
`preStart` 脚本在 `${stateDir}/.gc-root` 创建一个指向当前 hermes 包的 GC root。这可以防止 `nix-collect-garbage` 删除正在运行的二进制文件。如果 GC root 损坏，重启服务会重新创建它。
---
## 插件
NixOS 模块支持声明式插件安装——无需命令式的 `hermes plugins install`。
### 目录插件（`extraPlugins`）
对于只包含 `plugin.yaml` + `__init__.py` 的源码树插件（例如 [hermes-lcm](https://github.com/stephenschoettler/hermes-lcm)）：
```nix
services.hermes-agent.extraPlugins = [
(pkgs.fetchFromGitHub {
owner = "stephenschoettler";
repo = "hermes-lcm";
rev = "v0.7.0";
hash = "sha256-...";
})
];
```
插件在激活时以符号链接方式安装到 `$HERMES_HOME/plugins/`。Hermes 通过其正常的目录扫描发现它们。从列表中移除插件并运行 `nixos-rebuild switch` 会删除符号链接。
### 入口点插件（`extraPythonPackages`）
对于通过 `[project.entry-points."hermes_agent.plugins"]` 注册的 pip 打包插件（例如 [rtk-hermes](https://github.com/ogallotti/rtk-hermes)）：
```nix
services.hermes-agent.extraPythonPackages = [
(pkgs.python312Packages.buildPythonPackage {
pname = "rtk-hermes";
version = "1.0.0";
src = pkgs.fetchFromGitHub {
owner = "ogallotti";
repo = "rtk-hermes";
rev = "v1.0.0";
hash = "sha256-...";
};
format = "pyproject";
build-system = [ pkgs.python312Packages.setuptools ];
})
];
```
该包的 `site-packages` 会添加到 hermes wrapper 的 PYTHONPATH 中。`importlib.metadata` 在会话启动时发现入口点。
### 可选依赖组（`extraDependencyGroups`）
对于已在 hermes-agent 的 `pyproject.toml` 中声明的可选 extras（例如 `hindsight` 或 `honcho` 等记忆提供商），使用 `extraDependencyGroups` 在构建时将其包含到封闭的 venv 中：
```nix
services.hermes-agent = {
extraDependencyGroups = [ "hindsight" ];
settings.memory.provider = "hindsight";
};
```
这由 uv 与核心依赖在单次解析中完成——不需要 PYTHONPATH 补丁，没有冲突风险。可用的组与 `pyproject.toml` 中 `[project.optional-dependencies]` 的键对应（例如 `"hindsight"`、`"honcho"`、`"voice"`、`"matrix"`、`"mistral"`、`"bedrock"`）。
**何时使用哪个：**
| 需求 | 选项 |
|------|--------|
| 启用 pyproject.toml 可选 extra | `extraDependencyGroups` |
| 添加不在 pyproject.toml 中的外部 Python 插件 | `extraPythonPackages` |
| 添加系统二进制文件（pandoc、jq 等） | `extraPackages` |
| 添加基于目录的插件源码树 | `extraPlugins` |
### 组合使用
带有第三方 Python 依赖的目录插件需要同时使用两个选项：
```nix
services.hermes-agent = {
extraPlugins = [ my-plugin-src ]; # 插件源码
extraPythonPackages = [ pkgs.python312Packages.redis ]; # 其 Python 依赖
extraPackages = [ pkgs.redis ]; # 其需要的系统二进制文件
};
```
### 使用 Overlay
外部 flake 可以直接覆盖包：
```nix
{
inputs.hermes-agent.url = "github:NousResearch/hermes-agent";
outputs = { hermes-agent, nixpkgs, ... }: {
nixpkgs.overlays = [ hermes-agent.overlays.default ];
# 然后：
# pkgs.hermes-agent.override { extraPythonPackages = [...]; }
# pkgs.hermes-agent.override { extraDependencyGroups = [ "hindsight" ]; }
};
}
```
### 插件配置
插件仍需在 `config.yaml` 中启用。通过声明式 settings 添加：
```nix
services.hermes-agent.settings.plugins.enabled = [
"hermes-lcm"
"rtk-rewrite"
];
```
:::note
构建时冲突检查可防止插件包覆盖核心 hermes 依赖。如果插件提供了封闭 venv 中已有的包，`nixos-rebuild` 会以明确的错误失败。
:::
---
## 开发
### 开发 Shell
该 flake 提供了一个包含 Python 3.12、uv、Node.js 和所有运行时工具的开发 shell：
```bash
cd hermes-agent
nix develop
# Shell 提供：
# - Python 3.12 + uv（首次进入时将依赖安装到 .venv）
# - Node.js 22、ripgrep、git、openssh、ffmpeg 在 PATH 上
# - 戳记文件优化：依赖未变更时重新进入几乎即时
hermes setup
hermes chat
```
### direnv（推荐）
包含的 `.envrc` 会自动激活开发 shell：
```bash
cd hermes-agent
direnv allow # 仅需一次
# 后续进入几乎即时（戳记文件跳过依赖安装）
```
### Flake 检查
该 flake 包含在 CI 和本地运行的构建时验证：
```bash
# 运行所有检查
nix flake check
# 单独检查
nix build .#checks.x86_64-linux.package-contents # 二进制文件存在 + 版本
nix build .#checks.x86_64-linux.entry-points-sync # pyproject.toml ↔ Nix 包同步
nix build .#checks.x86_64-linux.cli-commands # gateway/config 子命令
nix build .#checks.x86_64-linux.managed-guard # HERMES_MANAGED 屏蔽变更操作
nix build .#checks.x86_64-linux.bundled-skills # 包中存在 skills
nix build .#checks.x86_64-linux.config-roundtrip # 合并脚本保留用户键
```
<details>
<summary><strong>每项检查的验证内容</strong></summary>
| 检查 | 测试内容 |
|---|---|
| `package-contents` | `hermes` 和 `hermes-agent` 二进制文件存在且 `hermes version` 可运行 |
| `entry-points-sync` | `pyproject.toml` 中 `[project.scripts]` 的每个条目在 Nix 包中都有对应的封装二进制文件 |
| `cli-commands` | `hermes --help` 暴露 `gateway` 和 `config` 子命令 |
| `managed-guard` | `HERMES_MANAGED=true hermes config set ...` 打印 NixOS 错误 |
| `bundled-skills` | skills 目录存在，包含 SKILL.md 文件，wrapper 中设置了 `HERMES_BUNDLED_SKILLS` |
| `config-roundtrip` | 7 种合并场景：全新安装、Nix 覆盖、用户键保留、混合合并、MCP 累加合并、嵌套深度合并、幂等性 |
</details>
---
## 选项参考
### 核心
| 选项 | 类型 | 默认值 | 描述 |
|---|---|---|---|
| `enable` | `bool` | `false` | 启用 hermes-agent 服务 |
| `package` | `package` | `hermes-agent` | 使用的 hermes-agent 包 |
| `user` | `str` | `"hermes"` | 系统用户 |
| `group` | `str` | `"hermes"` | 系统组 |
| `createUser` | `bool` | `true` | 自动创建用户/组 |
| `stateDir` | `str` | `"/var/lib/hermes"` | 状态目录（`HERMES_HOME` 的父目录） |
| `workingDirectory` | `str` | `"${stateDir}/workspace"` | Agent 工作目录（`MESSAGING_CWD`） |
| `addToSystemPackages` | `bool` | `false` | 将 `hermes` CLI 添加到系统 PATH 并在系统范围内设置 `HERMES_HOME` |
### 配置
| 选项 | 类型 | 默认值 | 描述 |
|---|---|---|---|
| `settings` | `attrs`（深度合并） | `{}` | 声明式配置，渲染为 `config.yaml`。支持任意嵌套；多个定义通过 `lib.recursiveUpdate` 合并 |
| `configFile` | `null` 或 `path` | `null` | 现有 `config.yaml` 的路径。设置后完全覆盖 `settings` |
### 密钥与环境
| 选项 | 类型 | 默认值 | 描述 |
|---|---|---|---|
| `environmentFiles` | `listOf str` | `[]` | 包含密钥的 env 文件路径。激活时合并到 `$HERMES_HOME/.env` |
| `environment` | `attrsOf str` | `{}` | 非密钥环境变量。**在 Nix store 中可见**——请勿在此放置密钥 |
| `authFile` | `null` 或 `path` | `null` | OAuth 凭据预置文件。仅在首次部署时复制 |
| `authFileForceOverwrite` | `bool` | `false` | 每次激活时始终从 `authFile` 覆盖 `auth.json` |
### 文档
| 选项 | 类型 | 默认值 | 描述 |
|---|---|---|---|
| `documents` | `attrsOf (either str path)` | `{}` | 工作区文件。键为文件名，值为内联字符串或路径。激活时安装到 `workingDirectory` |
### MCP 服务器
| 选项 | 类型 | 默认值 | 描述 |
|---|---|---|---|
| `mcpServers` | `attrsOf submodule` | `{}` | MCP 服务器定义，合并到 `settings.mcp_servers` |
| `mcpServers.<name>.command` | `null` 或 `str` | `null` | 服务器命令（stdio 传输） |
| `mcpServers.<name>.args` | `listOf str` | `[]` | 命令参数 |
| `mcpServers.<name>.env` | `attrsOf str` | `{}` | 服务器进程的环境变量 |
| `mcpServers.<name>.url` | `null` 或 `str` | `null` | 服务器端点 URL（HTTP/StreamableHTTP 传输） |
| `mcpServers.<name>.headers` | `attrsOf str` | `{}` | HTTP 头，例如 `Authorization` |
| `mcpServers.<name>.auth` | `null` 或 `"oauth"` | `null` | 认证方式。`"oauth"` 启用 OAuth 2.1 PKCE |
| `mcpServers.<name>.enabled` | `bool` | `true` | 启用或禁用此服务器 |
| `mcpServers.<name>.timeout` | `null` 或 `int` | `null` | 工具调用超时（秒，默认：120） |
| `mcpServers.<name>.connect_timeout` | `null` 或 `int` | `null` | 连接超时（秒，默认：60） |
| `mcpServers.<name>.tools` | `null` 或 `submodule` | `null` | 工具过滤（`include`/`exclude` 列表） |
| `mcpServers.<name>.sampling` | `null` 或 `submodule` | `null` | 服务器发起 LLM 请求的 sampling 配置 |
### 服务行为
| 选项 | 类型 | 默认值 | 描述 |
|---|---|---|---|
| `extraArgs` | `listOf str` | `[]` | `hermes gateway` 的额外参数 |
| `extraPackages` | `listOf package` | `[]` | Agent 可用的额外包。添加到 hermes 用户的每用户 profile，终端命令、skills 和 cron 任务均可见 |
| `extraPlugins` | `listOf package` | `[]` | 以符号链接方式安装到 `$HERMES_HOME/plugins/` 的目录插件包。每个包必须包含 `plugin.yaml` |
| `extraPythonPackages` | `listOf package` | `[]` | 添加到 PYTHONPATH 用于入口点插件发现的 Python 包。使用 `python312Packages` 构建 |
| `extraDependencyGroups` | `listOf str` | `[]` | 包含到封闭 venv 中的 pyproject.toml 可选 extras（例如 `["hindsight"]`）。由 uv 解析——无冲突 |
| `restart` | `str` | `"always"` | systemd `Restart=` 策略 |
| `restartSec` | `int` | `5` | systemd `RestartSec=` 值 |
### 容器
| 选项 | 类型 | 默认值 | 描述 |
|---|---|---|---|
| `container.enable` | `bool` | `false` | 启用 OCI 容器模式 |
| `container.backend` | `enum ["docker" "podman"]` | `"docker"` | 容器运行时 |
| `container.image` | `str` | `"ubuntu:24.04"` | 基础镜像（运行时拉取） |
| `container.extraVolumes` | `listOf str` | `[]` | 额外卷挂载（`host:container:mode`） |
| `container.extraOptions` | `listOf str` | `[]` | 传递给 `docker create` 的额外参数 |
| `container.hostUsers` | `listOf str` | `[]` | 获得 `~/.hermes` 符号链接（指向服务 stateDir）的交互式用户，自动加入 `hermes` 组 |
---
## 目录结构
### 原生模式
```
/var/lib/hermes/ # stateDir（归 hermes:hermes 所有，权限 0750）
├── .hermes/ # HERMES_HOME
│ ├── config.yaml # Nix 生成（每次重建深度合并）
│ ├── .managed # 标记：CLI 配置变更被屏蔽
│ ├── .env # 从 environment + environmentFiles 合并
│ ├── auth.json # OAuth 凭据（预置后自我管理）
│ ├── gateway.pid
│ ├── state.db
│ ├── mcp-tokens/ # MCP 服务器的 OAuth token
│ ├── sessions/
│ ├── memories/
│ ├── skills/
│ ├── cron/
│ └── logs/
├── home/ # Agent HOME
└── workspace/ # MESSAGING_CWD
├── SOUL.md # 来自 documents 选项
└── （Agent 创建的文件）
```
### 容器模式
相同的布局，挂载到容器中：
| 容器路径 | 主机路径 | 模式 | 说明 |
|---|---|---|---|
| `/nix/store` | `/nix/store` | `ro` | Hermes 二进制文件 + 所有 Nix 依赖 |
| `/data` | `/var/lib/hermes` | `rw` | 所有状态、配置、工作区 |
| `/home/hermes` | `${stateDir}/home` | `rw` | 持久化 Agent home——`pip install --user`、工具缓存 |
| `/usr`、`/usr/local`、`/tmp` | （可写层） | `rw` | `apt`/`pip`/`npm` 安装——重启后持久，重建后丢失 |
---
## 更新
```bash
# 更新 flake 输入（在包含 flake.nix 的目录中运行）
cd /etc/nixos && nix flake update hermes-agent
# 重建
sudo nixos-rebuild switch
```
在容器模式下，`current-package` 符号链接会更新，Agent 在重启时获取新的二进制文件。不会重建容器，不会丢失已安装的包。
---
## 故障排查
:::tip Podman 用户
以下所有 `docker` 命令在 `podman` 中同样适用。如果你设置了 `container.backend = "podman"`，请相应替换。
:::
### 服务日志
```bash
# 两种模式使用相同的 systemd 单元
journalctl -u hermes-agent -f
# 容器模式：也可直接查看
docker logs -f hermes-agent
```
### 容器检查
```bash
systemctl status hermes-agent
docker ps -a --filter name=hermes-agent
docker inspect hermes-agent --format='{{.State.Status}}'
docker exec -it hermes-agent bash
docker exec hermes-agent readlink /data/current-package
docker exec hermes-agent cat /data/.container-identity
```
### 强制重建容器
如果需要重置可写层（全新 Ubuntu）：
```bash
sudo systemctl stop hermes-agent
docker rm -f hermes-agent
sudo rm /var/lib/hermes/.container-identity
sudo systemctl start hermes-agent
```
### 验证密钥已加载
如果 Agent 启动但无法向 LLM 提供商认证，检查 `.env` 文件是否正确合并：
```bash
# 原生模式
sudo -u hermes cat /var/lib/hermes/.hermes/.env
# 容器模式
docker exec hermes-agent cat /data/.hermes/.env
```
### GC Root 验证
```bash
nix-store --query --roots $(docker exec hermes-agent readlink /data/current-package)
```
### 常见问题
| 现象 | 原因 | 解决方法 |
|---|---|---|
| `Cannot save configuration: managed by NixOS` | CLI 守卫已激活 | 编辑 `configuration.nix` 并执行 `nixos-rebuild switch` |
| 容器意外重建 | `extraVolumes`、`extraOptions` 或 `image` 发生变更 | 预期行为——可写层重置。重新安装包或使用自定义镜像 |
| `hermes version` 显示旧版本 | 容器未重启 | `systemctl restart hermes-agent` |
| `/var/lib/hermes` 权限拒绝 | 状态目录为 `0750 hermes:hermes` | 使用 `docker exec` 或 `sudo -u hermes` |
| `nix-collect-garbage` 删除了 hermes | GC root 缺失 | 重启服务（preStart 会重新创建 GC root） |
| `no container with name or ID "hermes-agent"`（Podman） | Podman rootful 容器对普通用户不可见 | 为 podman 添加免密 sudo（参见[容器模式](#container-mode)章节） |
| `unable to find user hermes` | 容器仍在启动中（入口点尚未创建用户） | 等待几秒后重试——CLI 会自动重试 |
| 通过 `extraPackages` 添加的工具在终端中找不到 | 需要 `nixos-rebuild switch` 更新每用户 profile | 重建并重启：`nixos-rebuild switch && systemctl restart hermes-agent` |
website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting-started/quickstart.md
+352
View File
@@ -0,0 +1,352 @@
---
sidebar_position: 1
title: "快速入门"
description: "与 Hermes Agent 的第一次对话——从安装到开始聊天，5 分钟内完成"
---
# 快速入门
本指南带你从零开始搭建一个能够应对实际使用的 Hermes 环境。完成安装、选择 provider（服务提供商）、验证对话正常运行，并了解出现问题时的处理方法。
## 更喜欢看视频？
**Onchain AI Garage** 制作了一套涵盖安装、配置和基本命令的 Masterclass 演示视频——如果你更习惯跟着视频操作，这是本页的绝佳补充。更多内容请查看完整的 [Hermes Agent 教程与使用案例](https://www.youtube.com/channel/UCqB1bhMwGsW-yefBxYwFCCg) 播放列表。
<div style={{position: 'relative', paddingBottom: '56.25%', height: 0, overflow: 'hidden', maxWidth: '100%', marginBottom: '1.5rem'}}>
<iframe
style={{position: 'absolute', top: 0, left: 0, width: '100%', height: '100%'}}
src="https://www.youtube-nocookie.com/embed/R3YOGfTBcQg"
title="Hermes Agent Masterclass: Installation, Setup, Basic Commands"
frameBorder="0"
allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowFullScreen
></iframe>
</div>
## 适用人群
- 全新用户，想以最短路径完成可用配置
- 正在切换 provider，不想因配置错误浪费时间
- 为团队、机器人或长期运行的工作流配置 Hermes
- 厌倦了"安装成功但什么都做不了"的情况
## 最快路径
根据你的目标选择对应行：
| 目标 | 先做这步 | 再做这步 |
|---|---|---|
| 只想让 Hermes 在本机跑起来 | `hermes setup` | 运行一次真实对话并验证有响应 |
| 已知道要用哪个 provider | `hermes model` | 保存配置，然后开始聊天 |
| 想搭建机器人或长期运行的服务 | CLI 正常后运行 `hermes gateway setup` | 接入 Telegram、Discord、Slack 或其他平台 |
| 想使用本地或自托管模型 | `hermes model` → 自定义 endpoint | 验证 endpoint、模型名称和上下文长度 |
| 想要多 provider 故障转移 | 先运行 `hermes model` | 基础对话正常后再添加路由和故障转移 |
**经验法则：** 如果 Hermes 无法完成一次正常对话，暂时不要添加更多功能。先让一次完整对话跑通，再逐步叠加 gateway、cron、skills、语音或路由。
---
## 1. 安装 Hermes Agent
**方式 A — pip（最简单）：**
```bash
pip install hermes-agent
hermes postinstall # 可选：安装 Node.js、浏览器、ripgrep、ffmpeg 并运行 setup
```
PyPI 发布版本跟踪带标签的版本（主/次版本发布），而非 `main` 分支上的每次提交。如需最新代码，请使用方式 B。
**方式 B — git 安装器（跟踪 main 分支）：**
```bash
# Linux / macOS / WSL2 / Android (Termux)
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
```
:::tip Android / Termux
如果你在手机上安装，请参阅专门的 [Termux 指南](./termux.md)，其中包含经过测试的手动安装步骤、支持的扩展功能以及当前 Android 特有的限制。
:::
:::tip Windows 用户
请先安装 [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install)，然后在 WSL2 终端中运行上述命令。
:::
安装完成后，重新加载 shell：
```bash
source ~/.bashrc # 或 source ~/.zshrc
```
详细的安装选项、前置条件和故障排查，请参阅 [安装指南](./installation.md)。
## 2. 选择 Provider
这是最重要的配置步骤。使用 `hermes model` 以交互方式完成选择：
```bash
hermes model
```
:::tip 最简路径：Nous Portal
一个订阅涵盖 300+ 个模型，以及 [Tool Gateway](../user-guide/features/tool-gateway.md)（网页搜索、图像生成、TTS、云端浏览器）。全新安装时：
```bash
hermes setup --portal
```
该命令一次性完成登录、设置 Nous 为 provider 并开启 Tool Gateway。
:::
推荐默认选项：
| Provider | 说明 | 配置方式 |
|----------|-----------|---------------|
| **Nous Portal** | 订阅制，零配置 | 通过 `hermes model` 进行 OAuth 登录 |
| **OpenAI Codex** | ChatGPT OAuth，使用 Codex 模型 | 通过 `hermes model` 进行设备码认证 |
| **Anthropic** | 直接使用 Claude 模型——Max 计划 + 额外用量积分（OAuth），或按 token 付费的 API key | `hermes model` → OAuth 登录（需要 Max + 额外积分），或 Anthropic API key |
| **OpenRouter** | 跨多个 provider 的多模型路由 | 输入 API key |
| **Z.AI** | GLM / Zhipu 托管模型 | 设置 `GLM_API_KEY` / `ZAI_API_KEY` |
| **Kimi / Moonshot** | Moonshot 托管的编程和对话模型 | 设置 `KIMI_API_KEY`（或 Kimi-Coding 专用的 `KIMI_CODING_API_KEY`） |
| **Kimi / Moonshot China** | 中国区 Moonshot endpoint | 设置 `KIMI_CN_API_KEY` |
| **Arcee AI** | Trinity 模型 | 设置 `ARCEEAI_API_KEY` |
| **GMI Cloud** | 多模型直连 API | 设置 `GMI_API_KEY` |
| **MiniMax (OAuth)** | 通过浏览器 OAuth 使用 MiniMax-M2.7，无需 API key | `hermes model` → MiniMax (OAuth) |
| **MiniMax** | 国际版 MiniMax endpoint | 设置 `MINIMAX_API_KEY` |
| **MiniMax China** | 中国区 MiniMax endpoint | 设置 `MINIMAX_CN_API_KEY` |
| **Alibaba Cloud** | 通过 DashScope 使用 Qwen 模型 | 设置 `DASHSCOPE_API_KEY` |
| **Hugging Face** | 通过统一路由器使用 20+ 开源模型（Qwen、DeepSeek、Kimi 等） | 设置 `HF_TOKEN` |
| **AWS Bedrock** | 通过原生 Converse API 使用 Claude、Nova、Llama、DeepSeek | IAM 角色或 `aws configure`（[指南](../guides/aws-bedrock.md)） |
| **Kilo Code** | KiloCode 托管模型 | 设置 `KILOCODE_API_KEY` |
| **OpenCode Zen** | 按需付费访问精选模型 | 设置 `OPENCODE_ZEN_API_KEY` |
| **OpenCode Go** | $10/月订阅，访问开源模型 | 设置 `OPENCODE_GO_API_KEY` |
| **DeepSeek** | 直接访问 DeepSeek API | 设置 `DEEPSEEK_API_KEY` |
| **NVIDIA NIM** | 通过 build.nvidia.com 或本地 NIM 使用 Nemotron 模型 | 设置 `NVIDIA_API_KEY`（可选：`NVIDIA_BASE_URL`） |
| **GitHub Copilot** | GitHub Copilot 订阅（GPT-5.x、Claude、Gemini 等） | 通过 `hermes model` 进行 OAuth，或设置 `COPILOT_GITHUB_TOKEN` / `GH_TOKEN` |
| **GitHub Copilot ACP** | Copilot ACP agent 后端（在本地启动 `copilot` CLI） | `hermes model`（需要 `copilot` CLI + `copilot login`） |
| **Custom Endpoint** | VLLM、SGLang、Ollama 或任何兼容 OpenAI 的 API | 设置 base URL + API key |
对于大多数初次使用的用户：选择一个 provider，接受默认值（除非你明确知道为何要修改）。完整的 provider 目录及环境变量和配置步骤请参阅 [Providers](../integrations/providers.md) 页面。
:::caution 最低上下文要求：64K token
Hermes Agent 要求模型至少具备 **64,000 个 token** 的上下文窗口。上下文窗口较小的模型无法为多步骤工具调用工作流维持足够的工作内存，启动时将被拒绝。大多数托管模型（Claude、GPT、Gemini、Qwen、DeepSeek）均轻松满足此要求。如果你运行本地模型，请将其上下文大小设置为至少 64K（例如 llama.cpp 使用 `--ctx-size 65536`，Ollama 使用 `-c 65536`）。
:::
:::tip
你可以随时通过 `hermes model` 切换 provider——没有锁定。所有支持的 provider 完整列表及配置详情，请参阅 [AI Providers](../integrations/providers.md)。
:::
### 配置的存储方式
Hermes 将密钥与普通配置分开存储：
- **密钥和 token** → `~/.hermes/.env`
- **非密钥配置** → `~/.hermes/config.yaml`
通过 CLI 设置值是最简便的方式，系统会自动将值写入正确的文件：
```bash
hermes config set model anthropic/claude-opus-4.6
hermes config set terminal.backend docker
hermes config set OPENROUTER_API_KEY sk-or-...
```
## 3. 运行第一次对话
```bash
hermes # 经典 CLI
hermes --tui # 现代 TUI（推荐）
```
你会看到一个欢迎横幅，显示你的模型、可用工具和 skills。使用一个具体且易于验证的 prompt（提示词）：
:::tip 选择你的界面
Hermes 提供两种终端界面：经典的 `prompt_toolkit` CLI，以及更新的 [TUI](../user-guide/tui.md)（支持模态覆盖层、鼠标选择和非阻塞输入）。两者共享相同的会话、斜杠命令和配置——分别用 `hermes` 和 `hermes --tui` 试试看。
:::
```
Summarize this repo in 5 bullets and tell me what the main entrypoint is.
```
```
Check my current directory and tell me what looks like the main project file.
```
```
Help me set up a clean GitHub PR workflow for this codebase.
```
**成功的标志：**
- 横幅显示你选择的模型/provider
- Hermes 无错误地回复
- 需要时能够使用工具（终端、文件读取、网页搜索）
- 对话可以正常进行超过一轮
如果以上都正常，你已经过了最难的部分。
## 4. 验证会话功能
继续之前，确认恢复功能正常：
```bash
hermes --continue # 恢复最近的会话
hermes -c # 简写形式
```
这应该会带你回到刚才的会话。如果不行，检查你是否在同一个 profile 下，以及会话是否实际已保存。当你同时管理多个配置或多台机器时，这一点很重要。
## 5. 尝试核心功能
### 使用终端
```
❯ What's my disk usage? Show the top 5 largest directories.
```
Agent 会代你执行终端命令并显示结果。
### 斜杠命令
输入 `/` 查看所有命令的自动补全下拉列表：
| 命令 | 功能 |
|---------|-------------|
| `/help` | 显示所有可用命令 |
| `/tools` | 列出可用工具 |
| `/model` | 交互式切换模型 |
| `/personality pirate` | 尝试一个有趣的人格 |
| `/save` | 保存对话 |
### 多行输入
按 `Alt+Enter`、`Ctrl+J` 或 `Shift+Enter` 换行。`Shift+Enter` 需要终端能将其作为独立序列发送（Kitty / foot / WezTerm / Ghostty 默认支持；iTerm2 / Alacritty / VS Code 终端需启用 Kitty 键盘协议）。`Alt+Enter` 和 `Ctrl+J` 在所有终端中均可使用。
### 中断 Agent
如果 agent 响应时间过长，输入新消息并按 Enter——这会中断当前任务并切换到你的新指令。`Ctrl+C` 同样有效。
## 6. 添加下一层功能
仅在基础对话正常后进行。按需选择：
### 机器人或共享助手
```bash
hermes gateway setup # 交互式平台配置
```
接入 [Telegram](/user-guide/messaging/telegram)、[Discord](/user-guide/messaging/discord)、[Slack](/user-guide/messaging/slack)、[WhatsApp](/user-guide/messaging/whatsapp)、[Signal](/user-guide/messaging/signal)、[Email](/user-guide/messaging/email)、[Home Assistant](/user-guide/messaging/homeassistant) 或 [Microsoft Teams](/user-guide/messaging/teams)。
### 自动化与工具
- `hermes tools` — 按平台调整工具访问权限
- `hermes skills` — 浏览并安装可复用的工作流
- Cron — 仅在机器人或 CLI 配置稳定后使用
### 沙箱终端
为了安全起见，在 Docker 容器或远程服务器中运行 agent：
```bash
hermes config set terminal.backend docker # Docker 隔离
hermes config set terminal.backend ssh # 远程服务器
```
### 语音模式
```bash
# 在 Hermes 安装目录下运行（curl 安装器在 Linux/macOS 上将其放置于
# ~/.hermes/hermes-agent，在 Windows 上为 %LOCALAPPDATA%\hermes\hermes-agent）：
cd ~/.hermes/hermes-agent
uv pip install -e ".[voice]"
# 包含 faster-whisper，用于免费的本地语音转文字
```
然后在 CLI 中输入：`/voice on`。按 `Ctrl+B` 开始录音。参阅 [语音模式](../user-guide/features/voice-mode.md)。
### Skills
```bash
hermes skills search kubernetes
hermes skills install openai/skills/k8s
```
或在聊天会话中使用 `/skills`。
### MCP 服务器
```yaml
# 添加到 ~/.hermes/config.yaml
mcp_servers:
github:
command: npx
args: ["-y", "@modelcontextprotocol/server-github"]
env:
GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx"
```
### 编辑器集成（ACP）
ACP 支持已包含在标准 `[all]` 扩展中，因此 curl 安装器已默认包含。直接运行：
```bash
hermes acp
```
（如果安装时未包含 `[all]`，请先运行 `cd ~/.hermes/hermes-agent && uv pip install -e ".[acp]"`。）
参阅 [ACP 编辑器集成](../user-guide/features/acp.md)。
---
## 常见故障模式
以下是最容易浪费时间的问题：
| 现象 | 可能原因 | 解决方法 |
|---|---|---|
| Hermes 启动但回复为空或异常 | Provider 认证或模型选择有误 | 重新运行 `hermes model`，确认 provider、模型和认证信息 |
| 自定义 endpoint "可用"但返回乱码 | base URL、模型名称有误，或实际上不兼容 OpenAI | 先用独立客户端验证该 endpoint |
| Gateway 启动但无法收到消息 | Bot token、白名单或平台配置不完整 | 重新运行 `hermes gateway setup` 并检查 `hermes gateway status` |
| `hermes --continue` 找不到旧会话 | 切换了 profile 或会话从未保存 | 检查 `hermes sessions list`，确认你在正确的 profile 下 |
| 模型不可用或出现异常的故障转移行为 | Provider 路由或故障转移设置过于激进 | 在基础 provider 稳定之前关闭路由 |
| `hermes doctor` 标记配置问题 | 配置值缺失或已过期 | 修复配置，在添加功能前重新测试普通对话 |
## 恢复工具包
当感觉有问题时，按以下顺序操作：
1. `hermes doctor`
2. `hermes model`
3. `hermes setup`
4. `hermes sessions list`
5. `hermes --continue`
6. `hermes gateway status`
这个顺序能让你快速从"感觉哪里不对"回到已知的正常状态。
---
## 快速参考
| 命令 | 说明 |
|---------|-------------|
| `hermes` | 开始聊天 |
| `hermes model` | 选择 LLM provider 和模型 |
| `hermes tools` | 配置每个平台启用的工具 |
| `hermes setup` | 完整配置向导（一次性配置所有内容） |
| `hermes doctor` | 诊断问题 |
| `hermes update` | 更新到最新版本 |
| `hermes gateway` | 启动消息 gateway |
| `hermes --continue` | 恢复上次会话 |
## 下一步
- **[CLI 指南](../user-guide/cli.md)** — 掌握终端界面
- **[配置](../user-guide/configuration.md)** — 自定义你的配置
- **[消息 Gateway](../user-guide/messaging/index.md)** — 接入 Telegram、Discord、Slack、WhatsApp、Signal、Email、Home Assistant、Teams 等
- **[工具与工具集](../user-guide/features/tools.md)** — 探索可用功能
- **[AI Providers](../integrations/providers.md)** — 完整 provider 列表及配置详情
- **[Skills 系统](../user-guide/features/skills.md)** — 可复用的工作流与知识
- **[技巧与最佳实践](../guides/tips.md)** — 高级用户技巧
website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting-started/termux.md
+236
View File
@@ -0,0 +1,236 @@
---
sidebar_position: 3
title: "Android / Termux"
description: "通过 Termux 在 Android 手机上直接运行 Hermes Agent"
---
# 在 Android 上通过 Termux 运行 Hermes
这是在 Android 手机上通过 [Termux](https://termux.dev/) 直接运行 Hermes Agent 的已验证路径。
它为你提供手机上可用的本地 CLI，以及目前已知可在 Android 上干净安装的核心扩展功能。
## 已验证路径支持哪些功能？
已验证的 Termux 安装包含：
- Hermes CLI
- cron 支持
- PTY（伪终端）/后台终端支持
- Telegram gateway 支持（手动 / 尽力而为的后台运行）
- MCP 支持
- Honcho 记忆支持
- ACP 支持
具体对应以下命令：
```bash
python -m pip install -e '.[termux]' -c constraints-termux.txt
```
## 哪些功能尚未纳入已验证路径？
部分功能仍依赖桌面/服务器风格的依赖项，这些依赖项尚未为 Android 发布，或尚未在手机上验证：
- `.[all]` 目前不支持 Android
- `voice` 扩展被 `faster-whisper -> ctranslate2` 阻塞，`ctranslate2` 未发布 Android wheel 包
- 自动浏览器 / Playwright 引导在 Termux 安装程序中被跳过
- 基于 Docker 的终端隔离在 Termux 内不可用
- Android 可能仍会挂起 Termux 后台任务，因此 gateway 持久化是尽力而为，而非正常的托管服务
这并不妨碍 Hermes 作为手机原生 CLI agent 正常工作——只是意味着推荐的移动端安装有意比桌面/服务器安装更精简。
---
## 方式一：一行安装命令
Hermes 现已内置 Termux 感知的安装路径：
```bash
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
```
在 Termux 上，安装程序会自动：
- 使用 `pkg` 安装系统包
- 使用 `python -m venv` 创建虚拟环境
- 优先尝试较大的 `.[termux-all]` 扩展，失败后回退到较小的 `.[termux]` 扩展（再次失败则进行基础安装）——curl 安装程序自动按此顺序执行
- 将 `hermes` 链接到 `$PREFIX/bin`，使其保留在 Termux PATH 中
- 跳过未经验证的浏览器 / WhatsApp 引导
如果你需要显式命令或需要调试失败的安装，请使用下方的手动安装路径。
---
## 方式二：手动安装（完全显式）
### 1. 更新 Termux 并安装系统包
```bash
pkg update
pkg install -y git python clang rust make pkg-config libffi openssl nodejs ripgrep ffmpeg
```
各包用途说明：
- `python` — 运行时 + 虚拟环境支持
- `git` — 克隆/更新仓库
- `clang`、`rust`、`make`、`pkg-config`、`libffi`、`openssl` — 在 Android 上构建部分 Python 依赖所需
- `nodejs` — 可选的 Node 运行时，用于已验证核心路径之外的实验
- `ripgrep` — 快速文件搜索
- `ffmpeg` — 媒体 / TTS 转换
### 2. 克隆 Hermes
```bash
git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
```
### 3. 创建虚拟环境
```bash
python -m venv venv
source venv/bin/activate
export ANDROID_API_LEVEL="$(getprop ro.build.version.sdk)"
python -m pip install --upgrade pip setuptools wheel
```
`ANDROID_API_LEVEL` 对于基于 Rust / maturin 的包（如 `jiter`）非常重要。
### 4. 安装已验证的 Termux 包
```bash
python -m pip install -e '.[termux]' -c constraints-termux.txt
```
如果你只需要最小化的核心 agent，以下命令同样有效：
```bash
python -m pip install -e '.' -c constraints-termux.txt
```
### 5. 将 `hermes` 添加到 Termux PATH
```bash
ln -sf "$PWD/venv/bin/hermes" "$PREFIX/bin/hermes"
```
`$PREFIX/bin` 在 Termux 中已默认在 PATH 中，因此这样做可以让 `hermes` 命令在新 shell 中持续可用，无需每次重新激活虚拟环境。
### 6. 验证安装
```bash
hermes version
hermes doctor
```
### 7. 启动 Hermes
```bash
hermes
```
---
## 推荐的后续配置
### 配置模型
```bash
hermes model
```
或直接在 `~/.hermes/.env` 中设置密钥。
### 稍后重新运行完整的交互式设置向导
```bash
hermes setup
```
### 手动安装可选的 Node 依赖
已验证的 Termux 路径有意跳过 Node/浏览器引导。如果你之后想尝试浏览器工具：
```bash
pkg install nodejs-lts
npm install
```
浏览器工具会自动将 Termux 目录（`/data/data/com.termux/files/usr/bin`）纳入 PATH 搜索，因此无需额外配置 PATH 即可发现 `agent-browser` 和 `npx`。
在另有文档说明之前，请将 Android 上的浏览器 / WhatsApp 工具视为实验性功能。
---
## 故障排查
### 安装 `.[all]` 时出现 `No solution found`
改用已验证的 Termux 包：
```bash
python -m pip install -e '.[termux]' -c constraints-termux.txt
```
当前阻塞原因是 `voice` 扩展：
- `voice` 依赖 `faster-whisper`
- `faster-whisper` 依赖 `ctranslate2`
- `ctranslate2` 未发布 Android wheel 包
### `uv pip install` 在 Android 上失败
改用标准库 venv + `pip` 的 Termux 路径：
```bash
python -m venv venv
source venv/bin/activate
export ANDROID_API_LEVEL="$(getprop ro.build.version.sdk)"
python -m pip install --upgrade pip setuptools wheel
python -m pip install -e '.[termux]' -c constraints-termux.txt
```
### `jiter` / `maturin` 报错提示缺少 `ANDROID_API_LEVEL`
在安装前显式设置 API 级别：
```bash
export ANDROID_API_LEVEL="$(getprop ro.build.version.sdk)"
python -m pip install -e '.[termux]' -c constraints-termux.txt
```
### `hermes doctor` 提示缺少 ripgrep 或 Node
使用 Termux 包安装：
```bash
pkg install ripgrep nodejs
```
### 安装 Python 包时构建失败
确保已安装构建工具链：
```bash
pkg install clang rust make pkg-config libffi openssl
```
然后重试：
```bash
python -m pip install -e '.[termux]' -c constraints-termux.txt
```
---
## 手机上的已知限制
- Docker 后端不可用
- 通过 `faster-whisper` 进行的本地语音转录在已验证路径中不可用
- 安装程序有意跳过浏览器自动化配置
- 部分可选扩展可能可用，但目前仅 `.[termux]` 和 `.[termux-all]` 被记录为已验证的 Android 安装包
如果你遇到新的 Android 特定问题，请在 GitHub 上提交 issue，并附上：
- 你的 Android 版本
- `termux-info`
- `python --version`
- `hermes doctor`
- 确切的安装命令及完整错误输出
website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/getting-started/updating.md
+257
View File
@@ -0,0 +1,257 @@
---
sidebar_position: 3
title: "更新与卸载"
description: "如何将 Hermes Agent 更新至最新版本或将其卸载"
---
# 更新与卸载
## 更新
### Git 安装方式
使用单条命令更新至最新版本：
```bash
hermes update
```
此命令会从 `main` 拉取最新代码、更新依赖项，并提示你配置自上次更新以来新增的选项。
### pip 安装方式
PyPI 发布版本跟踪**带标签的版本**（主版本和次版本发布），而非 `main` 上的每次提交。检查更新并升级：
```bash
hermes update --check # 查看 PyPI 上是否有更新的版本
hermes update # 执行 pip install --upgrade hermes-agent
```
或手动执行：
```bash
pip install --upgrade hermes-agent # 或：uv pip install --upgrade hermes-agent
```
:::tip
`hermes update` 会自动检测新的配置选项并提示你添加。如果跳过了该提示，可手动运行 `hermes config check` 查看缺失的选项，再运行 `hermes config migrate` 以交互方式添加。
:::
### 更新过程（Git 安装方式）
运行 `hermes update` 时，将依次执行以下步骤：
1. **配对数据快照** — 保存一份轻量级的更新前状态快照（涵盖 `~/.hermes/pairing/`、飞书评论规则及其他运行时修改的状态文件）。可通过 [快照与回滚](../user-guide/checkpoints-and-rollback.md) 中描述的快照恢复流程进行恢复，或从 Hermes 写入 `~/.hermes/` 目录旁的最新快速快照 zip 文件中提取。
2. **Git pull** — 从 `main` 分支拉取最新代码并更新子模块
3. **依赖安装** — 运行 `uv pip install -e ".[all]"` 以获取新增或变更的依赖项
4. **配置迁移** — 检测自当前版本以来新增的配置选项并提示设置
5. **Gateway 自动重启** — 更新完成后刷新正在运行的 gateway，使新代码立即生效。由服务管理的 gateway（Linux 上的 systemd、macOS 上的 launchd）通过服务管理器重启；手动启动的 gateway 在 Hermes 能将运行中的 PID 映射回某个 profile 时会自动重新启动。
### 仅预览：`hermes update --check`
想在拉取前确认是否有更新？运行 `hermes update --check` — 对于 Git 安装方式，它会获取并与 `origin/main` 比较提交；对于 pip 安装方式，它会查询 PyPI 上的最新版本。不修改任何文件，不重启 gateway。适合在以"是否有更新"为条件的脚本和 cron 任务中使用。
### 完整更新前备份：`--backup`
对于高价值 profile（生产环境 gateway、团队共享安装），可选择在拉取前对 `HERMES_HOME`（配置、认证、会话、技能、配对数据）进行完整备份：
```bash
hermes update --backup
```
或将其设为每次运行的默认行为：
```yaml
# ~/.hermes/config.yaml
updates:
pre_update_backup: true
```
`--backup` 在早期版本中是始终开启的行为，但在大型 home 目录上会给每次更新增加数分钟时间，因此现已改为按需启用。上述轻量级配对数据快照仍会无条件执行。
### Windows：另一个 `hermes.exe` 正在运行
在 Windows 上，如果 `hermes update` 检测到另一个 `hermes.exe` 进程持有 venv 入口点可执行文件的句柄，它将拒绝运行 — 最常见的情况是 Hermes Desktop 应用启动的后端进程、另一个终端中打开的 `hermes` REPL，或正在运行的 gateway：
```
$ hermes update
✗ Another hermes.exe is running:
PID 12345 hermes.exe
Updating now would fail to overwrite ...\venv\Scripts\hermes.exe because
Windows blocks REPLACE on a running executable.
Close Hermes Desktop, exit any open `hermes` REPLs, and
stop the gateway (`hermes gateway stop`) before retrying.
Override with `hermes update --force` if you've already
confirmed those processes will not write to the venv.
```
关闭列出的进程后重试。如果你确定并发进程不会造成干扰（极少见 — 通常仅在杀毒软件 shim 被误判时有用），可传入 `--force` 跳过检查。此时更新程序仍会以指数退避方式重试 `.exe` 重命名操作，对于顽固的文件锁，会通过 `MoveFileEx(MOVEFILE_DELAY_UNTIL_REBOOT)` 将替换操作安排在下次重启时执行，以确保更新能够完成。
预期输出如下：
```
$ hermes update
Updating Hermes Agent...
📥 Pulling latest code...
Already up to date. (or: Updating abc1234..def5678)
📦 Updating dependencies...
✅ Dependencies updated
🔍 Checking for new config options...
✅ Config is up to date (or: Found 2 new options — running migration...)
🔄 Restarting gateways...
✅ Gateway restarted
✅ Hermes Agent updated successfully!
```
### 更新后建议的验证步骤
`hermes update` 处理主要的更新流程，但快速验证可确认一切正常落地：
1. `git status --short` — 若工作树出现意外的脏状态，请在继续前检查
2. `hermes doctor` — 检查配置、依赖项和服务健康状态
3. `hermes --version` — 确认版本已按预期更新
4. 如果使用 gateway：`hermes gateway status`
5. 如果 `doctor` 报告 npm audit 问题：在标记的目录中运行 `npm audit fix`
:::warning 更新后工作树出现脏状态
如果 `hermes update` 后 `git status --short` 显示意外变更，请在继续前停下来检查。这通常意味着本地修改被重新应用到了更新后的代码之上，或依赖步骤刷新了锁文件。
:::
### 终端在更新中途断开连接
`hermes update` 针对意外终端断开进行了保护：
- 更新会忽略 `SIGHUP`，因此关闭 SSH 会话或终端窗口不再会在安装中途终止它。`pip` 和 `git` 子进程继承此保护，因此 Python 环境不会因连接断开而处于半安装状态。
- 更新运行期间，所有输出会同步镜像到 `~/.hermes/logs/update.log`。如果终端消失，重新连接后检查日志，确认更新是否完成以及 gateway 重启是否成功：
```bash
tail -f ~/.hermes/logs/update.log
```
- `Ctrl-C`（SIGINT）和系统关机（SIGTERM）仍会被响应 — 这些是主动取消操作，而非意外中断。
你不再需要将 `hermes update` 包裹在 `screen` 或 `tmux` 中来应对终端断开。
### 查看当前版本
```bash
hermes version
```
与 [GitHub releases 页面](https://github.com/NousResearch/hermes-agent/releases) 上的最新版本进行比较。
### 从消息平台更新
你也可以直接从 Telegram、Discord、Slack、WhatsApp 或 Teams 发送以下命令进行更新：
```
/update
```
此命令会拉取最新代码、更新依赖项并重启正在运行的 gateway。Bot 在重启期间会短暂下线（通常为 5–15 秒），之后恢复服务。
### 手动更新
如果你是手动安装的（未使用快速安装脚本）：
```bash
cd /path/to/hermes-agent
export VIRTUAL_ENV="$(pwd)/venv"
# Pull latest code
git pull origin main
# Reinstall (picks up new dependencies)
uv pip install -e ".[all]"
# Check for new config options
hermes config check
hermes config migrate # Interactively add any missing options
```
### 回滚说明
如果更新引入了问题，可以回滚到之前的版本：
```bash
cd /path/to/hermes-agent
# List recent versions
git log --oneline -10
# Roll back to a specific commit
git checkout <commit-hash>
uv pip install -e ".[all]"
# Restart the gateway if running
hermes gateway restart
```
回滚到特定发布标签：
```bash
git checkout v0.6.0
uv pip install -e ".[all]"
```
:::warning
如果新增了配置选项，回滚可能导致配置不兼容。回滚后运行 `hermes config check`，如果遇到错误，请从 `config.yaml` 中删除无法识别的选项。
:::
### Nix 用户注意事项
如果你通过 Nix flake 安装，更新由 Nix 包管理器负责：
```bash
# Update the flake input
nix flake update hermes-agent
# Or rebuild with the latest
nix profile upgrade hermes-agent
```
Nix 安装是不可变的 — 回滚由 Nix 的 generation 系统处理：
```bash
nix profile rollback
```
详情参见 [Nix 安装](./nix-setup.md)。
---
## 卸载
### Git 安装方式
```bash
hermes uninstall
```
卸载程序会提供选项，让你保留配置文件（`~/.hermes/`）以便将来重新安装。
### pip 安装方式
```bash
pip uninstall hermes-agent
rm -rf ~/.hermes # 可选 — 如计划重新安装则保留
```
### 手动卸载
```bash
rm -f ~/.local/bin/hermes
rm -rf /path/to/hermes-agent
rm -rf ~/.hermes # 可选 — 如计划重新安装则保留
```
:::info
如果你将 gateway 安装为系统服务，请先停止并禁用它：
```bash
hermes gateway stop
# Linux: systemctl --user disable hermes-gateway
# macOS: launchctl remove ai.hermes.gateway
```
:::