一、引言

在 AI Agent 工具百花齐放的 2025–2026 年，开发者面临着一个新的问题：哪个 Agent 框架真正能干活？

Claude Code 强在代码理解、Codex 强在 IDE 集成，但它们都有一个共同的局限——只能活在终端里。而实际工作中，消息通知、定时任务、团队协作、跨平台响应……这些场景需要一个能「无处不在」的 Agent。

Hermes Agent 正是为此而生。它不是另一个聊天机器人，而是一个多网关、可扩展、自学习的 AI Agent 运行时——同一个 Agent 实例，可以同时运行在 Telegram、QQ、Discord、Slack、终端、Web API 等十余个平台上，共享配置、记忆和技能。

本文将从架构设计出发，深入 Hermes Agent 的核心机制，并给出完整的 QQ Bot 配置实战。

二、架构概览：Hermes 是如何运行的？

2.1 核心循环（Agent Loop）

Hermes 的核心是一个同步循环（run_agent.py → AIAgent.run_conversation()），逻辑非常清晰：

1
2
3
4
5
6
while 迭代次数 < max_turns:
    1. 组装消息列表（system prompt + 历史 + 工具 schema）
    2. 调用 LLM（OpenAI 格式）
    3. 如果返回 tool_calls → 分派给对应 handler → 追加结果 → 继续
    4. 如果返回纯文本 → 结束循环，返回响应
    5. 上下文接近 token 限制时触发自动压缩

这个设计的精妙之处在于纯同步、无事件循环——它不需要 asyncio，不需要消息队列，所有工具调用都是顺序执行的。这让调试和追踪变得极其简单。

2.2 工具注册机制

每个工具都是一个独立文件（tools/*.py），在模块导入时调用 registry.register() 注册自身：

1
2
3
4
5
6
7
8
9
10
from tools.registry import registry

registry.register(
    name="terminal",
    toolset="terminal",
    schema={...},  # OpenAI 格式的 function schema
    handler=lambda args, **kw: terminal_tool(args.get("command", ""), ...),
    check_fn=check_requirements,  # 条件满足时才暴露
    requires_env=["SOME_API_KEY"],
)

工具默认自动发现——tools/ 目录下任何包含 registry.register() 的 .py 文件都会被自动导入。这意味着添加一个新工具只需要创建 一个文件，不需要修改任何注册表。

2.3 提示缓存（Prompt Caching）

Hermes 对 Anthropic 的 prompt caching 有深度集成。关键规则：

  • 会话中不变更 system prompt 和 tools——这确保缓存可以被复用
  • 不插入两段连续的 assistant 或 user 消息（OpenAI 格式要求交替）
  • 上下文压缩在后台自动触发，降低 token 消耗

2.4 上下文压缩

当上下文使用率超过 compression.threshold（默认 50%）时，会自动触发压缩：

  • 将早期对话用 LLM 摘要替换
  • 保护最近 N 条消息不被压缩（protect_last_n: 20）
  • 压缩后目标比例 target_ratio: 0.20（20%）

三、安装与配置

3.1 快速安装

1
2
3
4
5
6
# 一键安装（推荐）
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

# 验证安装
hermes --version
hermes doctor        # 检查依赖和配置完整性

3.2 初始化设置

安装后，运行交互式设置向导：

1
hermes setup

这会引导你完成：

  1. 模型提供商选择——OpenRouter、Anthropic、OpenAI、DeepSeek 等
  2. API Key 配置——写入 ~/.hermes/.env
  3. 工具集启用——终端、浏览器、文件系统等
  4. 平台网关设置——Telegram、QQ、Discord 等

也可以单独配置特定组件：

1
2
3
4
hermes setup model       # 只配置模型
hermes setup gateway     # 只配置消息平台
hermes setup terminal    # 只配置终端后端
hermes setup tools       # 只配置工具集

3.3 手动配置

配置文件位于 ~/.hermes/config.yaml，核心结构：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
model:
  default: deepseek-reasoner
  provider: deepseek
  base_url: https://api.deepseek.com/v1
  max_tokens: 8192

agent:
  max_turns: 90
  gateway_timeout: 1800
  reasoning_effort: medium

terminal:
  backend: local        # local | docker | ssh | modal
  timeout: 180

compression:
  enabled: true
  threshold: 0.50
  target_ratio: 0.20

memory:
  memory_enabled: true
  user_profile_enabled: true
  memory_char_limit: 2200

API Key 存储在 ~/.hermes/.env（不提交到 Git）：

1
2
3
4
5
OPENROUTER_API_KEY=sk-or-v1-...
ANTHROPIC_API_KEY=sk-ant-...
DEEPSEEK_API_KEY=sk-...
QQ_APP_ID=1903937598
QQ_CLIENT_SECRET=your-secret-here

3.4 模型提供商支持

Hermes 支持 20+ 个模型提供商，可通过 hermes model 随时切换：

提供商 认证方式 环境变量
OpenRouter API Key OPENROUTER_API_KEY
Anthropic API Key ANTHROPIC_API_KEY
OpenAI Codex OAuth hermes auth
DeepSeek API Key DEEPSEEK_API_KEY
Google Gemini API Key GOOGLE_API_KEY
GitHub Copilot OAuth 设备流 hermes model 中交互式登录
智谱 GLM (Z.AI) API Key ZAI_API_KEY
MiniMax API Key MINIMAX_API_KEY
Kimi / Moonshot API Key KIMI_API_KEY
阿里 DashScope API Key DASHSCOPE_API_KEY
小米 MiMo API Key XIAOMI_API_KEY
Hugging Face Token HF_TOKEN
自定义端点 Config 在 config.yaml 中设置 base_url + api_key

切换模型非常简单：

1
2
hermes model                          # 交互式选择
hermes chat -m "deepseek/deepseek-r1" # 单次指定模型

四、QQ Bot 配置实战

这是最具实用价值的功能——将 Hermes Agent 接入 QQ，让它能在 QQ 群和私聊中直接响应。

4.1 前置准备

1. 注册 QQ 机器人

前往 q.qq.com 创建应用：

  • 登记 App ID 和 App Secret（AppSecret）
  • 开启必要的 Intents：C2C 消息、群 @消息
  • 开发模式下只能在沙箱频道测试，发布后才能在生产环境使用

2. 安装依赖

1
pip install aiohttp httpx

aiohttp 用于 WebSocket 长连接（接收消息），httpx 用于 REST API 调用（发送消息）。

4.2 配置方法

方式一：交互式配置（推荐）

1
hermes setup gateway

选择 QQ Bot，按提示输入 App ID 和 App Secret 即可。

方式二：手动配置环境变量

编辑 ~/.hermes/.env：

1
2
QQ_APP_ID=1903937598
QQ_CLIENT_SECRET=你的AppSecret

方式三：手动配置 config.yaml

编辑 ~/.hermes/config.yaml，添加：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
platforms:
  qq:
    enabled: true
    extra:
      app_id: "1903937598"
      # client_secret 建议通过环境变量 QQ_CLIENT_SECRET 传入
      markdown_support: true          # 启用 QQ Markdown 消息（msg_type 2）
      dm_policy: "open"               # open | allowlist | disabled
      group_policy: "open"            # open | allowlist | disabled
      # 可选：限制特定用户/群
      # allow_from:
      #   - "用户OpenID_1"
      # group_allow_from:
      #   - "群OpenID_1"

同时新增 platform_toolsets 条目：

1
2
3
platform_toolsets:
  qqbot:
    - hermes-qqbot           # QQ Bot 专属工具集

4.3 环境变量参考

变量 说明 默认值
QQ_APP_ID QQ Bot App ID（必填） —
QQ_CLIENT_SECRET QQ Bot App Secret（必填） —
QQBOT_HOME_CHANNEL 定时任务/通知的默认 OpenID —
QQ_ALLOWED_USERS 允许私聊的用户 OpenID（逗号分隔） open
QQ_ALLOW_ALL_USERS 是否允许所有用户私聊 false
QQ_MARKDOWN_SUPPORT 启用 Markdown 消息格式 true
QQ_STT_API_KEY 语音转文字 API Key —
QQ_STT_MODEL 语音识别模型 glm-asr

4.4 启动网关

1
2
3
4
5
6
7
8
9
10
11
# 前台运行（调试用）
hermes gateway run

# 安装为后台服务
hermes gateway install

# 管理服务
hermes gateway start
hermes gateway stop
hermes gateway status
hermes gateway restart

服务启动后，你的 QQ Bot 就能在群里被 @ 时或私聊中自动响应了。

4.5 语音消息支持

QQ Bot 适配器支持两级语音转文字：

  1. QQ 内置 ASR（免费，优先使用）——QQ 会在语音消息附件中附带 asr_refer_text 字段
  2. 配置的 STT 提供商（备选）——如果 QQ 内置 ASR 没返回文字，会调用 OpenAI 兼容接口：
1
2
3
4
5
6
7
8
platforms:
  qq:
    extra:
      stt:
        provider: "zai"            # zai（智谱 GLM-ASR）、openai（Whisper）等
        baseUrl: "https://open.bigmodel.cn/api/coding/paas/v4"
        apiKey: "your-stt-key"
        model: "glm-asr"

也可以通过环境变量配置：

1
2
3
QQ_STT_API_KEY=your-key
QQ_STT_BASE_URL=https://open.bigmodel.cn/api/coding/paas/v4
QQ_STT_MODEL=glm-asr

4.6 常见问题

Q: Bot 连上就断开？
A: 检查 App ID 和 Secret 是否正确，以及 Intents 是否已开启。

Q: 消息收不到？
A: 群消息需要 @Bot 才能触发响应；沙箱模式下只能接收沙箱频道消息。

Q: 如何重置连接？
A: 在 QQ 聊天中发送 /restart 重启网关。

Q: 查看日志
A: tail -f ~/.hermes/logs/gateway.log | grep qq

五、技能系统（Skills）：让 Agent 自我进化

5.1 什么是技能？

技能是可复用的过程性知识。当 Hermes 完成一个复杂任务、解决一个棘手 Bug、或者你纠正了它的某个做法时，它可以把这些经验保存为技能。下次遇到类似任务时，技能会自动加载。

技能本质上是 Markdown 文件（SKILL.md），存储在 ~/.hermes/skills/：

1
2
3
4
5
6
7
8
9
10
11
---
name: systematic-debugging
description: 系统化的 Bug 排查流程
---

# 步骤
1. 收集错误信息（日志、堆栈、截图）
2. 缩小范围（二分法注释代码）
3. 查阅文档和社区
4. 编写最小可复现用例
5. 修复并验证

5.2 技能管理命令

1
2
3
4
5
6
7
8
9
10
hermes skills list              # 列出已安装技能
hermes skills search "deploy"   # 搜索技能中心
hermes skills install git-deploy # 安装社区技能
hermes skills uninstall 3       # 卸载技能

# 创建/编辑技能（在会话中直接让 Hermes 帮你保存）
hermes "将刚才的部署流程保存为技能 'docker-deploy'"

# 会话中加载技能
/skill systematic-debugging

5.3 技能自动加载

Hermes 在执行任何任务前，会扫描所有技能描述，如果发现与当前任务相关的技能，会自动加载其内容。这意味着：

  • 技能越多，Hermes 在你特定领域的表现就越好
  • 常犯的错误只需要纠正一次，技能就会记住
  • 团队内可以共享技能库

5.4 实际技能示例

以我们实际配置的 QQ Bot 为例，以下是 Hermes 记住的关键技能：

技能 用途
test-driven-development 测试驱动开发流程
systematic-debugging 系统化调试方法
hexo-blog-management Hexo 博客管理和部署
github-pr-workflow GitHub PR 全流程
px4-drone-simulation-v1-16-0 PX4 无人机仿真环境搭建
writing-plans 复杂任务的前期规划

六、跨平台网关详解

6.1 支持的平台

Hermes 的网关架构使其能在同一实例上同时接入多个平台：

平台 状态 工具集
终端 (CLI) ✅ 内置 hermes-cli
Telegram ✅ 完整支持 hermes-telegram
QQ Bot ✅ 完整支持 hermes-qqbot
Discord ✅ 完整支持 hermes-discord
Slack ✅ 完整支持 hermes-slack
WhatsApp ✅ 完整支持 hermes-whatsapp
Signal ✅ 完整支持 hermes-signal
Email (IMAP/SMTP) ✅ 完整支持 —
SMS ✅ 完整支持 —
Matrix ✅ 完整支持 —
Mattermost ✅ 完整支持 —
Home Assistant ✅ 智能家居 hermes-homeassistant
飞书 / 钉钉 / 企业微信 ✅ 支持 —
Web API Server ✅ RESTful —
Webhooks ✅ 事件驱动 —

6.2 平台工具集隔离

不同平台可以有不同的可用工具集。例如：

1
2
3
4
5
6
7
platform_toolsets:
  cli:
    - hermes-cli          # 终端有全部权限
  telegram:
    - hermes-telegram     # Telegram 有安全限制
  qqbot:
    - hermes-qqbot        # QQ 同样有安全限制

6.3 网关常用命令

在任意平台聊天中发送：

1
2
3
4
5
6
/platforms         # 查看所有平台连接状态
/restart           # 重启网关
/sethome           # 将当前聊天设为默认通知频道
/help              # 查看所有可用命令
/status            # 查看会话状态
/model claude      # 切换模型

七、其他核心功能

7.1 持久记忆系统

Hermes 具有跨会话的持久记忆，分为两个存储：

  • memory（个人笔记）——环境信息、工具偏见、项目约定
  • user（用户画像）——姓名、偏好、编码风格、沟通习惯

每次对话开始时，记忆自动注入 system prompt。这意味着 Hermes 会用你特有的偏好和方式工作，即使跨越多天。

支持多种记忆后端：

  • 内置（默认）
  • Honcho 记忆服务器
  • Mem0
  • 自定义后端（通过插件）

7.2 定时任务（Cron）

1
2
3
4
5
6
7
8
9
# 创建定时任务
hermes cron create "0 9 * * *"  # 每天上午9点
hermes cron create "30m"        # 每30分钟
hermes cron create "2026-12-01T00:00:00"  # 单次

# 管理
hermes cron list
hermes cron pause JOB_ID
hermes cron remove JOB_ID

定时任务支持完整的工具访问——你可以让 Hermes 每天自动备份数据库、每周生成项目周报、或者定时检查网站健康状态。

7.3 Webhooks

1
2
3
hermes webhook subscribe myhook   # 创建 /webhooks/myhook 端点
hermes webhook list
hermes webhook remove myhook

Webhook 端点接收 POST 请求后会自动启动一个 Hermes 会话处理，适合 CI/CD 触发、GitHub Webhook 集成等场景。

7.4 委派任务（Delegation）

对于需要独立上下文的复杂子任务，Hermes 可以委派子 Agent处理：

1
2
# 内部机制——用户可以自然语言触发
"并行探索三种数据库方案，每种方案写一份评估报告"

每个子 Agent 获得独立的会话和工具环境，互不干扰。支持配置独立的模型和提供商：

1
2
3
4
delegation:
  model: "deepseek/deepseek-r1"
  provider: "openrouter"
  max_iterations: 50

7.5 配置文件（Profiles）

通过 Profiles 可以运行多个完全隔离的 Hermes 实例：

1
2
3
4
hermes profile create work --clone   # 从当前配置克隆
hermes profile create personal       # 空白新建
hermes profile use work              # 设为默认
hermes profile list                  # 列表

每个 Profile 有独立的 config.yaml、.env、skills/、sessions/。适合区分工作/个人用途。

八、语音功能

8.1 语音合成（TTS）

提供商 免费？ 环境变量
Edge TTS ✅ 免费（默认） 无
ElevenLabs 有免费额度 ELEVENLABS_API_KEY
OpenAI TTS 付费 VOICE_TOOLS_OPENAI_KEY
MiniMax 付费 MINIMAX_API_KEY
NeuTTS（本地） ✅ 免费 需安装 pip install neutts[all]

8.2 语音识别（STT）

提供商 免费？ 环境变量
Local faster-whisper ✅ 免费 pip install faster-whisper
Groq Whisper 有免费额度 GROQ_API_KEY
OpenAI Whisper 付费 VOICE_TOOLS_OPENAI_KEY
GLM-ASR（智谱） — QQ_STT_API_KEY（QQ Bot 专用）

九、真实部署经验

9.1 在 WSL2 上部署的注意事项

部署在 WSL2 Ubuntu 22.04 环境，以下经验可供参考：

  1. Systemd 支持——确保 /etc/wsl.conf 包含 systemd=true，否则网关服务无法持久运行
  2. WSL2 会话关闭——关闭 WSL2 终端会导致 gateway 进程被杀死，可通过 sudo loginctl enable-linger $USER 启用 linger
  3. Windows 编码问题——Windows 编辑的 config.yaml 可能带 BOM 头，导致 HTTP 400 “No models provided” 错误。确保保存为 UTF-8 without BOM

9.2 Gateway 日志分析

1
2
3
4
5
6
7
8
# 查看最近错误
grep -i "error\|failed" ~/.hermes/logs/gateway.log | tail -20

# 特定平台日志
grep "qqbot" ~/.hermes/logs/gateway.log | tail -20

# 实时监控
tail -f ~/.hermes/logs/gateway.log

9.3 安全机制

  • 命令审批——危险操作（删除文件、系统配置修改）需要用户确认
  • Tirith 策略引擎——可配置安全策略，自动阻止特定操作
  • 平台隔离——不同平台的工具集可独立配置，Telegram 和 QQ 可以有不同权限

十、总结

Hermes Agent 区别于其他 AI Agent 的关键在于：

  1. 多网关架构——同一个 Agent 同时在终端、QQ、Telegram、Discord 等平台运行
  2. 自学习能力——通过 Skills 系统积累经验，越用越好用
  3. Provider 无关——随时切换模型提供商，不被任何一家锁定
  4. 持久记忆——跨会话记住用户偏好和环境信息
  5. 企业级功能——Cron 定时任务、Webhook 事件驱动、Profile 多环境隔离

从实际使用体验来看，Hermes Agent 最实用的场景是：

  • 日常开发——通过 QQ/Telegram 随时发起任务，无需打开终端
  • 运维监控——结合 Cron + QQ Bot，自动巡检并推送告警
  • 团队协作——在群聊中被 @ 即可执行任务，结果直接回复到群里

附录：相关资源

本文 Hermes Agent 部分基于 v2.0 版本编写，实际功能以最新版本为准。QQ Bot 配置部分基于实际部署经验。