Hermes Agent 完整使用指南

Hermes Agent 完整使用指南

---

目录

1. 项目概览
2. 安装部署
3. 初始配置
4. [CLI 基本使用](#CLI 基本使用)
5. 核心功能详解
   • 5.1 工具与工具集
   • 5.2 技能系统
   • 5.3 持久化记忆
   • 5.4 上下文文件
   • 5.5 子代理委派
   • 5.6 代码执行
   • 5.7 [定时任务 Cron](#定时任务 Cron)
   • 5.8 检查点与回滚
6. 终端后端
7. 消息平台集成
8. 语音模式
9. 浏览器自动化
10. [MCP 集成](#MCP 集成)
11. 个性化定制
12. 安全机制
13. 高级配置参考
14. 实战应用案例
15. [常见问题 FAQ](#常见问题 FAQ)

---

1. 项目概览

Hermes Agent 不是绑定在 IDE 上的编码助手，也不是单纯包装 API 的聊天机器人。它是一个自主代理（Autonomous Agent），运行时间越长就越强大。

核心特性

• 学习闭环：代理策管的记忆 + 自主技能创建 + 使用中技能自我改进 + FTS5 跨会话召回 + Honcho 辩证用户建模
• 可部署任何环境：6 种终端后端------本地、Docker、SSH、Daytona、Singularity、Modal；Daytona 和 Modal 提供无服务器持久化，空闲时几乎零成本
• 多平台即时通讯：CLI、Telegram、Discord、Slack、WhatsApp、Signal、Matrix、Mattermost、Email、SMS、DingTalk、飞书、企业微信、BlueBubbles、Home Assistant 等 15+ 平台
• 47 个内置工具：覆盖网页搜索、终端执行、文件编辑、记忆管理、浏览器自动化、图像生成、TTS 等
• 技能标准开放：兼容 agentskills.io 开放标准，技能可移植、共享
• 支持并行子代理：最多同时运行 3 个隔离子代理
• MCP 协议支持：连接任意 MCP 服务器扩展工具能力
• RL 训练就绪：批处理、轨迹导出、Atropos 强化学习训练

---

2. 安装部署

2.1 一键安装（推荐）

Linux / macOS / WSL2：

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

安装脚本会自动处理所有依赖（Python 3.11、Node.js v22、ripgrep、ffmpeg）、仓库克隆、虚拟环境创建、全局 hermes 命令设置，以及 LLM 提供商配置。

Android / Termux：

同样使用上述命令，安装脚本会自动检测 Termux 环境并切换到专用 Android 安装流程。

⚠️ Windows：不支持原生 Windows，请安装 WSL2 后在 WSL2 内运行。

2.2 安装完成后

source ~/.bashrc   # 或 source ~/.zshrc
hermes             # 开始聊天！

2.3 手动安装

如果需要完全控制安装过程：

# 1. 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. 克隆仓库
git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

# 3. 创建虚拟环境
uv venv venv --python 3.11
export VIRTUAL_ENV="$(pwd)/venv"

# 4. 安装依赖（全量安装）
uv pip install -e ".[all]"

# 5. 可选：Node.js 依赖（浏览器自动化和 WhatsApp）
npm install

# 6. 创建配置目录
mkdir -p ~/.hermes/{cron,sessions,logs,memories,skills,pairing,hooks,image_cache,audio_cache,whatsapp/session}
cp cli-config.yaml.example ~/.hermes/config.yaml
touch ~/.hermes/.env

# 7. 添加 API 密钥
echo 'OPENROUTER_API_KEY=sk-or-v1-your-key' >> ~/.hermes/.env

# 8. 全局可用
mkdir -p ~/.local/bin
ln -sf "$(pwd)/venv/bin/hermes" ~/.local/bin/hermes

# 9. 验证
hermes doctor
hermes

2.4 可选依赖包一览

额外包	功能	安装命令
all	安装全部	uv pip install -e ".[all]"
messaging	Telegram 和 Discord 网关	uv pip install -e ".[messaging]"
cron	定时任务表达式解析	uv pip install -e ".[cron]"
modal	Modal 云执行后端	uv pip install -e ".[modal]"
tts-premium	ElevenLabs 高级语音	uv pip install -e ".[tts-premium]"
voice	CLI 麦克风输入 + 音频播放	uv pip install -e ".[voice]"
honcho	AI 原生记忆（Honcho 集成）	uv pip install -e ".[honcho]"
mcp	Model Context Protocol 支持	uv pip install -e ".[mcp]"
slack	Slack 消息	uv pip install -e ".[slack]"
termux	Android/Termux 专用包	python -m pip install -e ".[termux]"

可组合使用：uv pip install -e ".[messaging,cron,mcp]"

---

3. 初始配置

3.1 目录结构

~/.hermes/
├── config.yaml     # 主配置文件（模型、终端、TTS、压缩等）
├── .env            # API 密钥和秘密
├── auth.json       # OAuth 提供商凭证
├── SOUL.md         # 代理主要身份（系统提示词第一位）
├── memories/       # 持久化记忆（MEMORY.md、USER.md）
├── skills/         # 代理创建的技能
├── cron/           # 定时任务
├── sessions/       # 网关会话
└── logs/           # 日志（自动脱敏）

3.2 配置管理命令

hermes config              # 查看当前配置
hermes config edit         # 编辑器打开 config.yaml
hermes config set KEY VAL  # 设置特定值
hermes config check        # 检查缺失选项
hermes config migrate      # 交互式添加缺失选项

hermes model               # 选择 LLM 提供商和模型
hermes tools               # 配置启用的工具
hermes gateway setup       # 设置消息平台
hermes setup               # 完整设置向导

3.3 配置优先级

优先级从高到低：

1. CLI 参数 --- 如 hermes chat --model anthropic/claude-sonnet-4
2. ~/.hermes/config.yaml --- 主配置文件
3. ~/.hermes/.env --- 环境变量，API 密钥必须存放于此
4. 内置默认值

经验法则 ：秘密信息（API 密钥、令牌、密码）放 .env。其他所有内容放 config.yaml。

3.4 支持的 LLM 提供商

Hermes 兼容多种提供商：

• OpenRouter --- 路由到数百个模型（推荐入门）
• Nous Portal --- Nous Research 官方门户
• Anthropic --- Claude 系列
• OpenAI --- GPT 系列
• Codex --- ChatGPT OAuth 方式
• 自定义端点 --- 任何 OpenAI 兼容 API（本地模型、Ollama、vLLM 等）

---

4. CLI 基本使用

hermes                        # 启动交互式聊天
hermes chat -q "你好！"       # 单次查询
hermes chat --model openai/gpt-4o -q "解释量子计算"  # 指定模型

# 常用斜杠命令
/help                         # 帮助信息
/tools                        # 查看可用工具
/skills                       # 查看已安装技能
/memory                       # 查看记忆内容
/voice on                     # 启用语音模式
/verbose                      # 切换工具输出详细度
/reasoning high               # 设置推理强度
/rollback                     # 回滚到上一个检查点
/clear                        # 清除当前会话
/exit                         # 退出

上下文引用（@ 语法）

在消息中输入 @ 后跟引用即可注入外部内容：

@file.py           # 注入文件内容
@src/              # 注入目录结构
@git:diff          # 注入 git 差异
@https://url.com   # 注入网页内容

---

5. 核心功能详解

5.1 工具与工具集（Tools & Toolsets）

Hermes 内置 47 个工具，按逻辑分组为工具集：

工具集	包含工具示例
terminal	终端命令执行
file	文件读写、编辑、搜索
web	网页搜索、网页提取、网页爬取
browser	浏览器导航、截图、表单填写
memory	记忆管理、会话搜索
skills	技能列表、查看、创建、管理
delegation	子代理任务委派
code_execution	Python 沙盒代码执行
media	图像生成、TTS、视觉分析
cron	定时任务管理

通过 hermes tools 配置启用/禁用各工具集。

5.2 技能系统（Skills）

技能是代理按需加载的知识文档，遵循渐进式披露模式以最小化 token 消耗。

使用方式：

# 作为斜杠命令使用
/gif-search funny cats
/axolotl help me fine-tune Llama 3
/plan design a rollout for auth migration

# 通过对话自然触发
"你有什么技能？"

渐进式加载层次：

层级	调用	内容
Level 0	skills_list()	名称、描述、分类概览（~3k tokens）
Level 1	skill_view(name)	完整内容 + 元数据
Level 2	skill_view(name, path)	特定参考文件

技能目录： ~/.hermes/skills/

代理可以自主创建和改进技能------当它发现某个流程值得记录时，会自动将其保存为可复用的技能。

SKILL.md 格式示例：

---
name: my-skill
description: 简要描述技能功能
version: 1.0.0
platforms: [macos, linux]
metadata:
  hermes:
    tags: [python, automation]
    category: devops
---

# 技能标题

## When to Use
触发条件

## Procedure
1. 步骤一
2. 步骤二

## Pitfalls
- 已知故障模式和修复

## Verification
确认生效的方法

5.3 持久化记忆（Memory）

Hermes 的记忆由两个文件组成，持久化于 ~/.hermes/memories/：

文件	用途	字符限制
MEMORY.md	代理个人笔记------环境事实、约定、经验教训	2,200 字符（~800 tokens）
USER.md	用户画像------偏好、沟通风格、期望	1,375 字符（~500 tokens）

记忆工作方式：

• 两个文件在会话启动时作为冻结快照注入系统提示词
• 代理通过 memory 工具管理记忆（add、replace、remove）
• 代理会主动保存学到的信息，无需用户要求
• 记忆写入即时持久化到磁盘，但在当前会话的系统提示词中不变（下次会话生效）
• 包含安全扫描，防止注入攻击

代理自动保存的内容示例：

• 用户偏好："我偏好 TypeScript"
• 环境事实："该服务器运行 Debian 12 + PostgreSQL 16"
• 纠正："Docker 命令不需要 sudo"
• 编码约定："项目使用 tabs、120 字符行宽"

会话搜索（session_search）：

除了 MEMORY.md 和 USER.md，代理还能通过 FTS5 全文搜索回顾所有历史会话。

5.4 上下文文件（Context Files）

Hermes 自动发现并加载多种项目上下文文件：

文件	用途
SOUL.md	代理主要身份，占系统提示词第一位
.hermes.md / HERMES.md	项目特定指令（最高优先级）
AGENTS.md	项目特定指令、编码约定（支持子目录层级合并）
CLAUDE.md	Claude Code 上下文文件
.cursorrules	Cursor IDE 规则

优先级：.hermes.md → AGENTS.md → CLAUDE.md → .cursorrules（仅加载第一个匹配）。SOUL.md 始终独立加载。

5.5 子代理委派（Delegation）

delegate_task 工具可以派生子代理实例，具有隔离的上下文、受限的工具集和独立的终端会话。

• 最多同时运行 3 个并行子代理
• 子代理可以使用不同的模型（如用便宜模型处理子任务）
• 配置示例：

delegation:
  model: "google/gemini-3-flash-preview"
  provider: "openrouter"

5.6 代码执行（Code Execution）

execute_code 工具让代理编写 Python 脚本，通过沙盒 RPC 调用 Hermes 工具，将多步骤工作流合并为单次 LLM 推理。

code_execution:
  timeout: 300
  max_tool_calls: 50

5.7 定时任务 Cron

支持自然语言或 cron 表达式调度任务。任务可以附加技能，将结果推送到任意消息平台。

# 在对话中
"每天早上 8 点给我发送天气预报到 Telegram"
"每周一生成项目进度报告"

5.8 检查点与回滚（Checkpoints）

Hermes 在执行破坏性文件操作前自动创建文件系统快照。

checkpoints:
  enabled: true
  max_snapshots: 50

使用 /rollback 命令回滚到之前的状态。

---

6. 终端后端

Hermes 支持 6 种终端后端，决定代理的 Shell 命令在哪里执行：

后端	执行位置	隔离级别	适用场景
local	本地机器	无	开发、个人使用
docker	Docker 容器	完全隔离	安全沙盒、CI/CD
ssh	远程服务器	网络边界	远程开发、强力硬件
modal	Modal 云沙盒	完全隔离（云 VM）	临时云计算、评估
daytona	Daytona 工作空间	完全隔离（云容器）	托管云开发环境
singularity	Singularity 容器	命名空间隔离	HPC 集群、共享机器

配置示例：

terminal:
  backend: docker
  docker_image: "nikolaik/python-nodejs:python3.11-nodejs20"
  container_cpu: 1
  container_memory: 5120
  container_persistent: true
  timeout: 180

Docker 后端安全加固：

• --cap-drop ALL，仅恢复 DAC_OVERRIDE、CHOWN、FOWNER
• --security-opt no-new-privileges
• --pids-limit 256
• 大小受限的 tmpfs

---

7. 消息平台集成

Hermes 支持 15+ 消息平台，通过统一消息网关接入：

平台	特性
Telegram	完整支持，含语音消息、文件、流式编辑
Discord	服务器频道、DM、语音频道、线程
Slack	频道、线程、应用集成
WhatsApp	通过 WhatsApp Web 桥接
Signal	安全消息
Matrix	去中心化协议
Email	IMAP/SMTP
SMS	短信
DingTalk / 飞书 / 企业微信	国内企业通讯平台
Home Assistant	智能家居集成

设置命令：

hermes gateway setup    # 交互式设置
hermes gateway start    # 启动网关

群聊会话隔离：

group_sessions_per_user: true   # 每个用户独立会话（默认推荐）

---

8. 语音模式

Hermes 支持完整的语音交互，覆盖 CLI 和消息平台。

CLI 语音：

/voice on      # 启用麦克风模式
/voice tts     # 开启语音回复

TTS 提供商：

提供商	说明
Edge TTS	免费，322 种声音，74 种语言
ElevenLabs	高质量高级语音
OpenAI TTS	GPT-4o-mini-tts
NeuTTS	本地运行

STT 提供商： local（faster-whisper）、groq、openai

配置：

tts:
  provider: "edge"
  edge:
    voice: "zh-CN-XiaoxiaoNeural"   # 中文语音示例

voice:
  record_key: "ctrl+b"
  max_recording_seconds: 120

stt:
  provider: "local"
  local:
    model: "base"

---

9. 浏览器自动化

支持多后端浏览器自动化：Browserbase 云、Browser Use 云、本地 Chrome CDP、本地 Chromium。

能力包括：

• 网页导航和截图
• 表单填写
• 信息提取
• 视觉分析（配合多模态模型）

browser:
  inactivity_timeout: 120
  command_timeout: 30
  record_sessions: false

---

10. MCP 集成

Hermes 可以连接任意 MCP（Model Context Protocol）服务器，通过 stdio 或 HTTP 传输协议访问外部工具。

功能包括：

• 连接 GitHub、数据库、文件系统、内部 API 等
• 无需编写原生 Hermes 工具
• 支持每服务器工具过滤和采样

---

11. 个性化定制

SOUL.md --- 代理身份

~/.hermes/SOUL.md 定义代理的核心身份，是系统提示词的第一部分。完全可自定义。

人格预设

使用 /personality 命令切换预设人格，或在 SOUL.md 中完全自定义。

皮肤与主题

display:
  skin: default    # 内置或自定义 CLI 皮肤
  compact: false

插件

将自定义工具、钩子、集成放入 ~/.hermes/plugins/ 目录，包含 plugin.yaml 和 Python 代码。

---

12. 安全机制

命令审批

approvals:
  mode: manual    # manual | smart | off

• manual：执行任何危险命令前提示用户
• smart：使用辅助 LLM 评估命令风险，低风险自动批准
• off：跳过所有审批（仅用于可信沙盒环境）

秘密信息脱敏

security:
  redact_secrets: true

自动检测并脱敏工具输出和日志中的 API 密钥、令牌、密码。

Tirith 安全扫描

终端命令执行前通过 Tirith 扫描，检测潜在危险操作。

网站黑名单

security:
  website_blocklist:
    enabled: true
    domains:
      - "*.internal.company.com"
      - "admin.example.com"

记忆安全扫描

记忆条目在接受前会扫描注入和数据泄露模式。

---

13. 高级配置参考

上下文压缩

长对话自动压缩以保持在模型上下文窗口内：

compression:
  enabled: true
  threshold: 0.50
  target_ratio: 0.20
  protect_last_n: 20
  summary_model: "google/gemini-3-flash-preview"
  summary_provider: "auto"

辅助模型

图像分析、网页摘要、浏览器截图分析等旁路任务使用轻量级辅助模型：

auxiliary:
  vision:
    provider: "auto"
    model: ""
  web_extract:
    provider: "auto"
    timeout: 360

凭证池

多个 API 密钥轮换策略：

credential_pool_strategies:
  openrouter: round_robin     # fill_first | round_robin | least_used | random

推理强度

agent:
  reasoning_effort: ""    # none | minimal | low | medium | high | xhigh
  max_turns: 90

流式输出

display:
  streaming: true
  show_reasoning: true

streaming:
  enabled: true
  transport: edit
  edit_interval: 0.3

网页搜索后端

web:
  backend: firecrawl    # firecrawl | parallel | tavily | exa

隐私保护

privacy:
  redact_pii: false     # 从 LLM 上下文中脱敏 PII（网关专用）

快速命令

定义零 token 消耗的自定义命令：

quick_commands:
  status:
    type: exec
    command: systemctl status hermes-agent
  disk:
    type: exec
    command: df -h /
  gpu:
    type: exec
    command: nvidia-smi --query-gpu=name,utilization.gpu,memory.used --format=csv,noheader

---

14. 实战应用案例

案例 1：个人编程助手

# 在项目目录中启动
cd ~/projects/my-app
hermes

# 对话
"分析 src/ 目录的代码结构并给出改进建议"
"重构 auth 模块，使用 JWT 替换 session-based auth"
"为所有 API 端点编写单元测试"

案例 2：远程服务器管理

# config.yaml
terminal:
  backend: ssh

# 通过 Telegram 远程管理
"检查服务器磁盘使用情况"
"重启 nginx 服务"
"查看最近的错误日志"

案例 3：自动化工作流

# 设置定时任务
"每天早上 9 点搜索 Hacker News 上关于 AI 的最新文章，生成摘要发送到 Telegram"

# 并行处理
"同时搜索三个竞品的定价页面，整理成对比表格"

案例 4：知识管理

# 技能创建
"基于我们刚才的部署流程，创建一个可复用的技能"

# 跨会话记忆
"上周我们讨论过的数据库迁移方案是什么？"

案例 5：Docker 安全沙盒开发

terminal:
  backend: docker
  docker_image: "nikolaik/python-nodejs:python3.11-nodejs20"
  container_persistent: true
  docker_volumes:
    - "/home/user/projects:/workspace/projects"

"安装 TensorFlow 并运行 benchmark 测试"
# 完全隔离，不影响宿主机环境

---

15. 常见问题 FAQ

Q：hermes: command not found

A：重新加载 Shell（source ~/.bashrc），或检查 ~/.local/bin 是否在 PATH 中。

Q：API key not set

A：运行 hermes model 配置提供商，或 hermes config set OPENROUTER_API_KEY your_key。

Q：更新后配置缺失

A：运行 hermes config check 然后 hermes config migrate。

Q：如何更新 Hermes？

A：

cd ~/.hermes/hermes-agent   # 或你克隆仓库的位置
git pull
uv pip install -e ".[all]"

Q：如何完全诊断问题？

A：运行 hermes doctor，它会告诉你缺少什么以及如何修复。

Q：支持哪些模型？

A：通过 OpenRouter 支持数百个模型，也可以使用任何 OpenAI 兼容 API（包括本地部署的 Ollama、vLLM 等）。

Q：如何降低成本？

A：使用便宜的模型（如 Gemini Flash）作为辅助任务模型；使用 delegation 让子代理使用更便宜的模型；启用上下文压缩减少 token 消耗。

---

相关资源

• 📖 官方文档：https://hermes-agent.nousresearch.com/docs
• 💻 GitHub 仓库：https://github.com/NousResearch/hermes-agent
• 🎯 技能中心：https://agentskills.io
• 💬 Discord 社区：https://discord.gg/NousResearch
• 🏢 Nous Research：https://nousresearch.com

---