我的文档

Hermes Agent 是 Nous Research 构建的一个自进化的 AI Agent，它能够通过经验学习、创建和改进技能，并跨会话建立用户模型，从而变得越来越强大。本教程将带你从安装、基本使用到进阶配置，全面掌握 Hermes Agent。

🚀 Hermes Agent 完整教程

📚 简介

Hermes Agent 是一个开源的自主 AI Agent 框架，由 Nous Research 开发。它不仅仅是一个与 IDE 绑定的代码助手或单个 API 的聊天机器人包装器，而是一个能够随着时间推移变得更加智能和强大的自主 Agent。 Hermes Agent 具有内置的学习循环，能够从经验中创建技能、在使用过程中改进技能、记忆会话内容，并构建一个深入的用户模型。

主要特点：

自学习能力：Agent 能够自动创建和改进技能，通过经验积累知识。
持久记忆：跨会话记住用户偏好、环境细节和学习到的经验。
多平台支持：通过单一网关进程支持 CLI、Telegram、Discord、Slack、WhatsApp、Signal 等。
模型无关：支持 OpenAI、Anthropic、Google、OpenRouter 等多种大语言模型，并可在工作流中随时切换。
丰富的工具集：内置终端、文件读写、网页搜索、图像生成等工具。
自动化与调度：内置 Cron 调度器，可用于运行无人值守的自动化任务。
多种终端后端：支持在本地、Docker、SSH、Modal、Daytona 或 Singularity 环境中执行命令。

📦 安装 Hermes Agent

Hermes Agent 提供了多种安装方式，你可以根据自己的操作系统和偏好选择最适合的方法。

1. 前提条件

Python 3.11+ (对于 pip 安装方式，会自动处理其他依赖)。
Git (推荐安装，对于某些安装方式是必需的)。

2. 安装方法

a) 使用 Pip (最简单推荐)

这是最简单快捷的安装方式，适用于 Linux、macOS 和 WSL2。

bash

pip install hermes-agent  
hermes postinstall # 可选：安装 Node.js, 浏览器, ripgrep, ffmpeg 等完整依赖并运行设置。

b) 使用安装脚本 (Linux / macOS / WSL2 / Android Termux)

推荐使用此一键安装脚本，它会自动处理所有依赖，包括 uv (快速 Python 包管理器)、Python 3.11、Node.js v22、ripgrep 和 ffmpeg。

bash

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash  
source ~/.bashrc # 或者 source ~/.zshrc，以使 hermes 命令生效

c) 原生 Windows (早期测试版)

Windows 原生支持仍在早期测试阶段，但提供了 PowerShell 脚本进行安装。建议在 WSL2 中运行 Linux 安装脚本以获得更稳定的体验。

在 PowerShell 中运行：

powershell

iex (irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1)

该安装程序会处理 uv、Python 3.11、Node.js 22、ripgrep、ffmpeg 和一个便携式 Git Bash。安装后请重启终端。

d) Docker (推荐用于生产环境)

Hermes 也提供了官方 Docker 镜像，这是在生产环境中运行的推荐方式，可以避免 Python 环境冲突并简化版本锁定。

bash

# 简单的单容器 WebUI 快速启动 (WebUI 运行 Agent)  
git clone https://github.com/nesquena/hermes-webui  
cd hermes-webui  
# 参考 hermes-webui 仓库的 README 进行 Docker Compose 设置，通常会有 pre-built images.  
# 示例 (根据实际情况调整 Docker Compose 文件):  
# docker compose up -d

e) 桌面安装程序 (Windows 替代方案)

还提供了一个轻量级的 GUI 安装程序。下载 Hermes Desktop，运行 .exe 文件，它会在后台调用 install.ps1 来安装依赖。桌面应用和 PowerShell CLI 共享相同的安装和数据目录。

3. 安装后设置

安装完成后，执行以下步骤以进行初始配置：

加载 shell 配置：如果你使用了安装脚本，请确保重新加载 shell 配置：
bash
```
source ~/.bashrc # 或 source ~/.zshrc
```
运行 hermes setup (推荐)：
使用 hermes setup --portal 命令可以交互式地完成模型提供商和工具网关的设置。这对于刚开始使用并希望快速获得工作环境的用户来说是最简单的路径。
bash
```
hermes setup --portal
```
它会引导你完成选择模型提供商的步骤。
手动选择模型提供商 (如果跳过了 --portal)：
你也可以使用 hermes model 命令来交互式选择和配置你的大语言模型提供商。
bash
```
hermes model
```
Hermes 支持多种模型，如 OpenAI、Anthropic、OpenRouter 等。你需要提供相应的 API 密钥。 API 密钥通常会保存到 ~/.hermes/.env 文件中。

🏃‍♀️ 基本使用

一旦 Hermes Agent 安装并配置好模型，你就可以开始与其进行交互了。

1. 启动会话

Hermes Agent 提供了两种主要的命令行界面：

经典 CLI (推荐用于快速交互):
bash
```
hermes
```
现代 TUI (文本用户界面，推荐用于更丰富的交互体验):
bash
```
hermes --tui
```
TUI 界面提供多行编辑、斜杠命令自动补全、会话历史记录、中断和重定向以及流式工具输出等功能。

2. 进行第一次对话

在启动会话后，你可以像与普通聊天机器人一样与 Hermes 交流。尝试问一些问题或分配一个简单的任务。

例如：

"Write a Python script to list all .txt files in the current directory." (编写一个 Python 脚本来列出当前目录中所有 .txt 文件。)
"Summarize the key features of Hermes Agent." (总结 Hermes Agent 的主要功能。)

3. 验证会话功能

在继续之前，请确保会话可以正常工作，例如测试恢复功能：

发送一条消息。
退出会话。
重新启动会话并检查是否保留了上下文。

4. 配置管理

Hermes 的所有设置都存储在 ~/.hermes/ 目录下。

查看当前配置：
bash
```
hermes config
```

编辑配置文件：

bash

hermes config edit # 将在你的编辑器中打开 config.yaml

设置特定值：

bash

hermes config set KEY VAL # 设置 config.yaml 中的值  
hermes config set model anthropic/claude-opus-4.6 # 示例  
hermes config set terminal.backend docker # 示例

设置 API 密钥 (会自动保存到 .env)：

bash

hermes config set OPENROUTER_API_KEY sk-or-... # 示例

检查缺失选项：
bash
```
hermes config check
```
迁移配置 (更新后)：
bash
```
hermes config migrate
```

重要配置目录结构：

~/.hermes/  
├── config.yaml   # 主要配置文件，存储非秘密设置  
├── .env          # 存储 API 密钥和秘密  
├── auth.json     # OAuth 提供商凭据  
├── SOUL.md       # Agent 的主要身份 (系统提示的第一部分)  
├── memories/     # 持久化记忆 (MEMORY.md, USER.md)  
├── skills/       # Agent 创建的技能 (通过 skill_manage 工具管理)  
├── cron/         # 调度任务  
├── sessions/     # 网关会话  
└── logs/         # 日志文件 (errors.log, gateway.log — 秘密会自动隐藏)

🛠️ 进阶使用

Hermes Agent 的强大之处在于其高级功能，可以让你构建更复杂的自动化和自定义工作流。

1. 消息网关 (Messaging Gateway)

Hermes 可以作为一个统一的 Agent 接口，连接到多种消息平台，实现跨平台会话的连续性。

设置网关：

bash

hermes gateway setup # 在 CLI 正常工作后运行

支持的平台：Telegram, Discord, Slack, WhatsApp, Signal, Email, Home Assistant 等。

例如，设置 Telegram Bot：

从 BotFather 获取 Telegram Bot Token。
运行 hermes gateway setup 并选择 Telegram，然后按照提示输入 Bot Token。
一旦设置完成，你就可以从 Telegram 与你的 Hermes Agent 交流了。

2. 工具与工具集 (Tools & Toolsets)

Hermes Agent 内置了多种工具，并且可以根据需要进行配置和扩展。

管理工具访问：

bash

hermes tools # 交互式调整工具访问  
hermes tools enable NAME # 启用特定工具  
hermes tools disable NAME # 禁用特定工具

工具的更改在新会话 (/reset) 后生效。

核心工具示例：
- 终端 (terminal)：执行 shell 命令。
- 文件操作 (file_read, file_write)：读取和写入文件。
- 网页搜索 (web_search)：执行网络搜索。
- 图像生成 (image_generate)：使用 FAL.ai 等服务生成图像。
- 会话搜索 (session_search)：搜索本地会话数据库中的历史会话。

3. 技能系统 (Skills System)

Hermes Agent 最大的亮点之一是其自学习和自改进的技能系统。

技能的创建与改进：Agent 在完成复杂任务、发现工作流或得到纠正时，可以自动将这些知识作为技能文档保存下来。技能是带有 YAML frontmatter 的 Markdown 文件。

管理技能：

bash

hermes skills # 浏览和安装可重用工作流

技能存储位置：自定义技能通常存储在 ~/.hermes/skills/ 目录下。
自进化：Hermes Agent Self-Evolution (一个独立项目) 使用 DSPy + GEPA 来自动进化和优化 Hermes Agent 的技能、提示和代码。

4. 持久化记忆 (Persistent Memory)

Hermes Agent 具有多层记忆，使其能够跨会话记住信息。

SOUL.md：Agent 的核心身份和个性，是系统提示的第一部分。你可以手写并随着时间调整它，它将在每个项目和会话中保持一致。
memories/ 目录：包含 MEMORY.md (Agent 的笔记) 和 USER.md (用户档案)。
Honcho 辩证用户建模：Hermes 使用此方法构建越来越精确的用户模型，包括你的项目、偏好和工作风格。

5. Cron 调度器 (Scheduled Automations)

内置的 Cron 调度器允许你设置无人值守的自动化任务，并将其结果发送到各种平台。

创建 Cron 任务：

bash

hermes cron # 查看和管理 Cron 任务

典型用途：每日报告、夜间备份、每周审计等，所有这些都以自然语言运行。
GitHub 备份：你可以配置 Agent 自动将技能、记忆文件和配置备份到私有 GitHub 仓库。

6. 终端后端 (Terminal Backends)

Hermes 支持多种终端后端，决定了 Agent 的 shell 命令实际执行的位置。

配置：可以在 config.yaml 中通过 terminal.backend 设置。

yaml

terminal:  
  backend: local # 或 docker, ssh, modal, daytona, singularity

类型：
- local：在本地机器上运行命令 (默认)。
- docker：在隔离的 Docker 容器中运行命令，具有安全强化功能。
  - 需要 Docker Desktop 或 Docker Engine。
  - 可以使用 docker_extra_args 传递额外的 docker run 参数，例如 --gpus=all。
- ssh：通过 SSH 连接到远程服务器执行命令。
  - 需要设置 TERMINAL_SSH_HOST 和 TERMINAL_SSH_USER 环境变量。
- modal / daytona：在云沙盒中运行命令，提供 serverless 持久化。
  - 需要相应的 API 密钥或配置文件。

7. AI 提供商管理 (AI Providers)

Hermes 旨在与任何 LLM 提供商协同工作，并且可以轻松切换。

切换模型：

bash

hermes model # 交互式选择提供商和模型

自定义端点：Hermes 可以通过自定义提供商路径与任何 OpenAI 兼容的端点对话。

好的，我们继续 Hermes Agent 的进阶使用部分。

🛠️ 进阶使用 (续)

8. 子 Agent 和并行化 (Subagents & Parallelization)

Hermes Agent 不仅仅是一个单一的智能体，它还支持创建和管理子 Agent，从而实现更复杂的任务分解和并行化处理。

概念：你可以让一个主 Agent 生成并协调多个子 Agent，每个子 Agent 可以专注于解决主任务中的一个特定子问题。这对于需要处理多个并发任务或需要专业知识的任务非常有用。
用途：
- 任务分解：将一个大型复杂任务分解成更小的、可管理的子任务，并分配给不同的子 Agent。
- 专业化：每个子 Agent 可以拥有不同的“技能集”或“角色”，使其在特定领域表现更出色。
- 并行执行：理论上，不同的子 Agent 可以并行工作，从而加速任务完成。
实现方式：在 Hermes Agent 中，子 Agent 的概念通常通过在 Agent 的思维过程中动态创建和管理任务来实现。这可能涉及：
- Agent 调用一个工具来生成新的 Agent 实例或分配子任务。
- Agent 识别出需要独立执行的子问题，并为之启动一个“思维分支”或“子会话”。
- 利用 Agent 的技能系统来定义子 Agent 的行为和目标。
当前状态：虽然 Hermes Agent 框架设计之初就考虑了这种模块化和扩展性，但具体的子 Agent 管理和并行化工具仍在持续开发和完善中。用户可能需要通过编写自定义技能或利用 Agent 的规划能力来实现子 Agent 的协作。

9. 国际化 (i18n)

Hermes Agent 支持国际化，这意味着你可以使用 Agent 与多种语言进行交互。

配置：你可以在 config.yaml 中设置 language 选项。
yaml
```
language: zh-Hans # 设置为简体中文
```
多语言支持：Agent 应该能够理解和响应你设置的语言，并且它的某些提示和系统信息也会相应地本地化。
Agent 的语言能力：请注意，Agent 的语言理解和生成能力最终取决于所使用的大语言模型。如果 LLM 能够很好地支持某种语言，那么 Hermes Agent 在该语言下的表现也会很好。

10. 高级调试与日志

对于开发和故障排除，Hermes Agent 提供了详细的日志记录功能。

日志文件：日志存储在 ~/.hermes/logs/ 目录下。
- errors.log：记录所有错误信息。
- gateway.log：记录网关相关的所有活动。
- hermes.log：主 Agent 的详细日志，包括推理过程、工具使用等。
日志级别：你可以在 config.yaml 中调整日志级别以获取更详细或更简洁的输出。
yaml
```
logging:  
  level: INFO # 可选 DEBUG, INFO, WARNING, ERROR, CRITICAL
```
秘密隐藏：Hermes 会自动隐藏日志中的 API 密钥和其他敏感信息，确保安全性。
调试技巧：
- 在遇到问题时，首先查看 errors.log。
- 如果 Agent 行为不符合预期，将日志级别设置为 DEBUG，然后重新运行，仔细查看 hermes.log 中的推理步骤和工具调用。
- 使用 hermes config check 检查配置是否有误。

11. 与其他工具和平台集成

Hermes Agent 的设计是开放和可扩展的，这意味着它可以与其他工具和平台进行深度集成。

API 接口：Hermes 可以通过其网关或内部 API 与其他服务进行交互。
自定义工具：你可以编写自己的 Python 工具并将其集成到 Hermes Agent 中。这些工具可以是与特定服务（如 Jira、GitHub API、自定义数据库等）交互的接口。
Webhook：通过 webhook，Hermes 可以接收来自外部事件的触发，或者在完成任务后触发外部系统的操作。
代码仓库集成：如前所述，Hermes 可以与 GitHub 等代码仓库集成，用于备份和管理技能、记忆和配置。

12. 更新 Hermes Agent

保持 Hermes Agent 的最新版本可以获得最新的功能、性能改进和安全修复。

使用 Pip 更新：
bash
```
pip install --upgrade hermes-agent
```
使用安装脚本更新：
如果你最初使用了安装脚本，可以重新运行它来更新。它通常会检查并安装最新版本。
bash
```
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
```
更新配置：更新后，可能需要运行配置迁移：
bash
```
hermes config migrate
```

📝 最佳实践与提示

从简单任务开始：刚开始使用时，给 Agent 分配一些简单明确的任务，例如编写一个小脚本、总结一段文本等，以便熟悉其工作方式。
清晰的指令：向 Agent 提供清晰、明确且详细的指令。避免模糊或模棱两可的表达。
迭代和反馈：Agent 的学习能力来自你的反馈。如果 Agent 的表现不尽如人意，提供纠正性反馈，它会尝试学习和改进。
管理 SOUL.md：花时间完善 SOUL.md 文件。一个好的 Agent 身份可以显著影响其行为和表现。
利用技能系统：当 Agent 完成一个有用的工作流或解决一个特定问题时，考虑将其保存为技能。这将帮助 Agent 在未来更快、更有效地解决类似问题。
定期备份：定期备份 ~/.hermes/ 目录，尤其是 memories/ 和 skills/ 目录，以防数据丢失。
注意安全：Agent 可以访问你的终端和文件系统。在使用前务必理解其权限。在生产环境或敏感任务中，优先考虑使用 Docker 或其他隔离环境运行 Agent。
探索文档：Hermes Agent 的 GitHub 仓库通常包含最新的文档和示例，定期查阅可以帮助你发现新功能和最佳实践。

❓ 常见问题与故障排除

Agent 没有响应或卡住：
- 检查你的网络连接。
- 检查 LLM 提供商的 API 密钥是否有效且有足够的配额。
- 查看 ~/.hermes/logs/errors.log 和 hermes.log 获取详细错误信息。
- 尝试重启会话 (/reset) 或重启 Hermes Agent。
工具无法正常工作：
- 确保工具已启用 (hermes tools)。
- 检查工具所需的外部依赖（例如，ffmpeg 用于视频处理，ripgrep 用于文件搜索）。
- 对于 Docker 或 SSH 后端，确保后端环境配置正确且 Agent 具有访问权限。
Agent 行为异常：
- 检查 SOUL.md 和 memories/ 中的描述是否与预期一致。
- 尝试清除特定会话记忆 (/forget) 或重置整个 Agent 记忆 (谨慎操作)。
- 检查 config.yaml 中是否有意外的设置。

展望未来

Hermes Agent 作为一个自进化的 AI Agent，其潜力巨大。随着 Nous Research 团队的不断发展和社区的贡献，我们可以期待更多高级功能，如更强大的多模态交互、更智能的技能合成、更安全的沙盒环境以及与更广泛的生态系统集成。

希望这份教程能帮助你完整安装、使用并深入探索 Hermes Agent 的强大功能！

🚀 Hermes Agent 完整教程 ​

📚 简介 ​

📦 安装 Hermes Agent ​

1. 前提条件 ​

2. 安装方法 ​

3. 安装后设置 ​

🏃‍♀️ 基本使用 ​

1. 启动会话 ​

2. 进行第一次对话 ​

3. 验证会话功能 ​

4. 配置管理 ​

🛠️ 进阶使用 ​

1. 消息网关 (Messaging Gateway) ​

2. 工具与工具集 (Tools & Toolsets) ​

3. 技能系统 (Skills System) ​

4. 持久化记忆 (Persistent Memory) ​

5. Cron 调度器 (Scheduled Automations) ​

6. 终端后端 (Terminal Backends) ​

7. AI 提供商管理 (AI Providers) ​

🛠️ 进阶使用 (续) ​

8. 子 Agent 和并行化 (Subagents & Parallelization) ​

9. 国际化 (i18n) ​

10. 高级调试与日志 ​

11. 与其他工具和平台集成 ​

12. 更新 Hermes Agent ​

📝 最佳实践与提示 ​

❓ 常见问题与故障排除 ​

展望未来 ​

🚀 Hermes Agent 完整教程

📚 简介

📦 安装 Hermes Agent

1. 前提条件

2. 安装方法

3. 安装后设置

🏃‍♀️ 基本使用

1. 启动会话

2. 进行第一次对话

3. 验证会话功能

4. 配置管理

🛠️ 进阶使用

1. 消息网关 (Messaging Gateway)

2. 工具与工具集 (Tools & Toolsets)

3. 技能系统 (Skills System)

4. 持久化记忆 (Persistent Memory)

5. Cron 调度器 (Scheduled Automations)

6. 终端后端 (Terminal Backends)

7. AI 提供商管理 (AI Providers)

🛠️ 进阶使用 (续)

8. 子 Agent 和并行化 (Subagents & Parallelization)

9. 国际化 (i18n)

10. 高级调试与日志

11. 与其他工具和平台集成

12. 更新 Hermes Agent

📝 最佳实践与提示

❓ 常见问题与故障排除

展望未来