Hermes Agent 深度实践：架构拆解与上手记录

一、项目概况与定位

Hermes Agent 是由 Nous Research 开发并开源的 AI Agent 框架，2026年2月25日发布，到5月初已达到 139,000 GitHub stars，是 GitHub 历史上增长最快的 Agent 项目之一。仓库共 7,690 次提交，895 名贡献者，代码主体为 Python（88.5%）和 TypeScript（8.1%），MIT 协议。

核心定位 与 Claude Code、OpenClaw 有本质区别：

  • Claude Code 强调代码仓库内的实时交互，每次对话从零开始
  • OpenClaw 强调多平台消息接入（微信/钉钉/飞书），本地化优先
  • Hermes Agent 的核心卖点是自学习循环——完成任务后自动生成可复用的 skill 文件，下次直接调用，且 skill 会在使用中持续优化

仓库Topics标签里明确标注了 clawdbot、moltbot、openclaw、claude-code，说明项目本身也将这些视为直接参照物。

二、架构与目录结构

克隆仓库后，根目录结构如下（我摘了关键部分）：

hermes-agent/
├── agent/                  # 核心Agent逻辑
├── acp_adapter/            # ACP(Agent Communication Protocol)适配器
├── acp_registry/           # ACP服务注册
├── gateway/                # 消息网关(Telegram/Discord/Slack等)
├── cron/                   # 定时任务调度器
├── skills/                 # 内置skill（118个bundled + 12个optional）
├── environments/           # 运行环境配置
├── hermes_cli/             # CLI入口
├── tui_gateway/            # TUI终端界面
├── web/                    # Web Dashboard
├── docker/                 # Docker部署配置
├── plugins/                # 插件系统
│   └── providers/          # 33个模型provider
├── plans/                  # 计划/任务管理
├── locales/                # 多语言支持
├── setup-hermes.sh         # 开发环境一键搭建
├── pyproject.toml          # Python依赖管理
└── docker-compose.yml      # Docker Compose配置

架构上几个值得注意的设计：

  1. acp_adapter / acp_registry — 实现了 ACP（Agent Communication Protocol），这是 Hermes 与其他 Agent 系统通信的协议层，支持跨 Agent 协作
  2. gateway — 消息网关与 Agent 核心分离，同一个 Agent 实例可以同时对接 Telegram、Discord、Slack、WhatsApp、Signal 等多个平台
  3. plugins/providers — 33个模型provider全部是插件化架构，新增一个provider不需要改核心代码
  4. cron — 内置定时任务系统，独立于外部crontab

三、安装过程实录

方式一：一键脚本（推荐新手）

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

脚本做的事情：

  1. 检测操作系统（Linux/macOS/WSL2/Termux）
  2. 安装 uv（Python包管理器，Astral出品）
  3. 创建虚拟环境
  4. 克隆仓库并安装 [all] 依赖
  5. 在 ~/.local/bin/ 创建 hermes 软链接

我实际在 Ubuntu 22.04 上跑了这个脚本，从执行到出现 TUI 界面大约用了 4 分钟。主要耗时在下载依赖和安装语音相关的库。

方式二：Docker

git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
docker-compose up -d

Docker 配置在 docker/ 目录下，有完整的 Dockerfile 和 compose 文件。值得注意的配置点：

# docker-compose.yml 关键部分
services:
  hermes:
    volumes:
      - ./data:/app/data        # 数据持久化，必须挂出来
    ports:
      - "8080:8080"             # Web Dashboard
      - "8000:8000"             # API Gateway
    environment:
      - HERMES_CONFIG=/app/config.yaml

数据持久化是最容易被忽略的点。如果不把 /app/data 挂到宿主机，容器重启后 Agent 的记忆、skill、配置全丢。生产环境部署时这个 volume 配置是必选项。

方式三：开发环境（适合二次开发）

git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
./setup-hermes.sh    # 等价于：安装uv → 创建venv → pip install -e ".[all,dev]"

setup-hermes.sh 脚本会自动创建虚拟环境并安装开发依赖。装完之后用 ./hermes 启动，不需要手动 source .venv/bin/activate。

四、模型配置详解

Provider 体系

Hermes 的模型层是完全插件化的，代码在 plugins/providers/ 目录下。目前内置了 33 个 provider：

云端 API：

  • openrouter — 200+ 模型，一个API key走天下
  • openai — GPT-4o/GPT-4.1 系列
  • anthropic — Claude 4.5/4.6/4.7/Sonnet/Opus
  • google — Gemini 2.5 Pro/Flash
  • kimi / moonshot — 月之暗面 Kimi
  • glm — 智谱 AI
  • minimax — MiniMax
  • mimo — 小米MiMo
  • nvidia — NVIDIA NIM (Nemotron)

本地部署：

  • ollama — 本地Ollama实例
  • vllm — vLLM推理服务
  • sglang — SGLang推理
  • huggingface — HuggingFace TGI

配置文件

配置文件在 ~/.hermes/config.yaml。我实际配了一套带 fallback 的方案：

model:
  default: openrouter/anthropic/claude-sonnet-4
  provider: openrouter
  temperature: 0.7

fallback_model:
  provider: openrouter
  model: google/gemini-2.5-pro
  
cost_limit:
  daily_usd: 5.0          # 每日花费上限
  
providers:
  openrouter:
    api_key: ${OPENROUTER_API_KEY}
    base_url: https://openrouter.ai/api/v1

fallback_model 这个设计很实用——主模型挂了或限流时自动切换，不需要人工干预。API key 存放在 ~/.hermes/.env，不会被提交到版本控制。

hermes model 命令

hermes model                    # 交互式选择模型
hermes model openrouter:anthropic/claude-sonnet-4    # 直接指定
hermes model --list             # 列出所有可用模型
hermes model --provider         # 仅切换provider

实际体验中，切换模型是热加载的，不需要重启 Agent。但切换后会话上下文会丢失，建议在任务完成后再切换。

五、CLI 与 TUI 界面

核心命令

命令 作用
hermes 启动交互式 TUI
hermes model 选择/切换模型
hermes tools 配置启用的工具集
hermes config set 设置单个配置项
hermes gateway 启动消息网关
hermes setup 运行完整配置向导
hermes skills 浏览和管理技能
hermes cron 定时任务管理
hermes update 更新到最新版本
hermes doctor 诊断问题
hermes --yolo 跳过所有确认提示

TUI 界面

启动 hermes 后进入 TUI 界面，支持：

  • 多行编辑 — Shift+Enter 换行，Enter 发送
  • Slash 命令补全 — / 后显示可用命令列表
  • 对话历史 — 上下箭头浏览历史消息
  • 流式输出 — 工具和 LLM 的响应实时流式显示
  • 中断重定向 — Ctrl+C 中断当前操作，可以发新指令

Slash 命令

在对话中可用的命令（CLI 和消息平台通用）：

命令 作用
/new /reset 开始新对话
/model [provider:model] 切换模型
/personality [name] 设置人格
/retry /undo 重试/撤销上一回合
/compress 压缩上下文
/usage 查看token用量
/insights [--days N] 查看N天使用统计
/skills 浏览可用技能
/stop 中断当前工作

六、Gateway 消息网关

这是 Hermes 区别于 Claude Code 的核心功能之一。通过 Gateway，同一个 Agent 实例可以同时服务多个消息平台的用户。

支持的平台

平台 配置方式 状态
Telegram Bot Token 稳定
Discord Bot Token 稳定
Slack App Token + Bot Token 稳定
WhatsApp Web.js / Cloud API 稳定
Signal signal-cli 稳定
Email IMAP/SMTP 稳定
Home Assistant WebSocket 稳定
Google Chat Service Account 较新

配置 Telegram

我实际配置了 Telegram，步骤如下：

  1. 找 @BotFather 创建新 bot，拿到 token（格式：123456789:ABCdefGHIjklMNOpqrsTUVwxyz）

  2. 配置 Hermes：

hermes gateway setup
# 选择 Telegram → 输入 Bot Token → 选择允许访问的用户（可选）
# 配置完成

hermes gateway start
# 启动网关进程
  1. 给 bot 发 /start，开始对话

网关进程启动后会在后台持续运行。我把它丢到了 systemd service 里管理：

# /etc/systemd/system/hermes-gateway.service
[Unit]
Description=Hermes Agent Gateway
After=network.target

[Service]
Type=simple
User=ubuntu
ExecStart=/home/ubuntu/.local/bin/hermes gateway start
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

安全机制

Gateway 有用户白名单机制——可以配置只允许特定用户与 Agent 交互。配置在 ~/.hermes/config.yaml：

gateway:
  telegram:
    allowed_users:
      - 123456789        # 你的Telegram user_id
    admin_users:
      - 123456789

没有配置白名单的情况下，任何人找到你的 bot 都可以使用，生产环境务必配置。

七、Skill 系统：核心机制拆解

Skill 系统是 Hermes 的灵魂。它不是简单的 prompt 模板，而是一套完整的"知识固化"机制。

Skill 文件结构

Skill 存放在 ~/.hermes/skills/ 目录下，按来源分三个子目录：

~/.hermes/skills/
├── bundled/              # 内置skill（随项目发布，118个）
│   ├── web_search/
│   ├── code_review/
│   ├── data_analysis/
│   └── ...
├── optional/             # 可选skill（12个，需手动启用）
│   ├── google_workspace/
│   ├── watchers/
│   └── ...
├── custom/               # 用户自定义skill
│   └── [你的skill]/
└── openclaw-imports/     # 从OpenClaw迁移的skill

每个 skill 是一个目录，至少包含一个 SKILL.md 文件。

SKILL.md 格式

我打开 skills/bundled/web_search/SKILL.md 看了内置 skill 的格式：

# web_search

## 触发条件
用户要求搜索信息、查找资料、调研某个主题

## 参数
- query: 搜索关键词
- num_results: 返回结果数量（默认5）

## 执行步骤
1. 使用 web_search 工具执行搜索
2. 对结果进行摘要
3. 返回结构化的搜索结果

## 工具依赖
- web_search

## 示例
用户："搜索一下Rust的最新版本"
→ 调用 web_search(query="Rust latest version")
→ 摘要后返回给用户

这个格式是 Markdown 纯文本，任何人都可以阅读和编辑。技能描述用自然语言，但结构足够清晰，Agent 能准确解析。

Skill 的自动创建与优化

当 Agent 完成一个复杂任务时，它会：

  1. 分析执行轨迹 — 回放刚才的操作序列，识别有效步骤
  2. 提取可复用模式 — 找出与具体任务无关的通用操作流程
  3. 生成 SKILL.md — 将模式固化为 skill 文件
  4. 存储到 custom/ — 保存到用户自定义目录
  5. 持续优化 — 每次使用该 skill 时收集反馈，自动调整参数和步骤

Skill 的手动管理

hermes skills                    # 列出所有skill
hermes skills --category         # 按分类查看
hermes skills enable [name]      # 启用skill
hermes skills disable [name]     # 禁用skill
hermes skills edit [name]        # 编辑skill

与 agentskills.io 的兼容

仓库 README 明确提到兼容 agentskills.io 开放标准。这是 Nous Research 推动的 skill 格式标准，理论上同一个 skill 文件可以在不同 Agent 框架间复用。

八、记忆系统

Hermes 有三层记忆机制，这是我调研后发现最被低估的功能。

三层记忆

  1. MEMORY.md — 环境级记忆

    • 存放位置：~/.hermes/memory/MEMORY.md
    • 内容：系统能力、可用工具、环境配置、经验教训
    • Agent 会自动更新，用户也可以手动编辑

  2. USER.md — 用户级记忆

    • 存放位置：~/.hermes/memory/USER.md
    • 内容：用户偏好、工作风格、常用操作
    • 跨会话持久化

  3. FTS5 会话搜索 — 历史检索

    • SQLite FTS5 全文索引
    • 所有历史会话自动建索引
    • 支持自然语言查询和语义搜索
    • LLM 自动摘要，快速回顾长对话

记忆的自动维护

Agent 会定期：

  • 总结近期对话，提取关键信息写入 MEMORY.md
  • 更新用户偏好到 USER.md
  • 压缩和清理过时的记忆条目
  • 主动追问以完善记忆（“你之前说喜欢简洁回复，是指所有场景吗？”）

Honcho 用户建模

仓库集成了 Honcho 的 dialectic profile 系统。Honcho 是一个用户建模框架，通过观察用户的交互模式来构建用户画像。具体到我调研看到的内容，它会追踪：

  • 用户偏好的回复长度和格式
  • 常用的表达方式和术语
  • 任务完成后的反馈模式
  • 错误纠正的方式和频率

这些画像数据用于优化 Agent 的响应策略，使交互越来越贴合用户习惯。

九、Cron 定时任务

基本用法

# 添加任务
hermes cron add "每天早上9点抓取 techcrunch 头条并总结"

# 查看所有任务
hermes cron list

# 删除任务
hermes cron remove [job_id]

# 查看执行历史
hermes cron logs

任务配置

Cron 任务配置存储在 ~/.hermes/cron/ 目录下，每个任务一个 YAML 文件：

# ~/.hermes/cron/daily_news.yaml
name: daily_news
schedule: "0 9 * * *"           # cron表达式
prompt: >
  抓取 techcrunch.com 首页的前10条新闻标题，
  对每条新闻用一句话摘要，
  以 Markdown 格式输出
output: telegram                 # 输出到Telegram
target: "@myusername"           # 发送到指定用户

自然语言到 Cron 的转换

Hermes 会把自然语言描述转换为 cron 表达式：

自然语言 转换结果
“每天早上9点” 0 9 * * *
“每周五下午5点” 0 17 * * 5
“每3小时” 0 */3 * * *
“每月1号上午10点” 0 10 1 * *

十、安全机制

命令审批

Hermes 默认开启了命令审批模式。Agent 在执行以下操作前会请求用户确认：

  • 执行 shell 命令
  • 删除文件
  • 发送网络请求到外部API
  • 修改系统配置

审批模式可以在配置中调整：

security:
  command_approval: always       # always | risky_only | never
  allowed_commands:              # 白名单
    - ls
    - cat
    - grep
  blocked_commands:              # 黑名单
    - rm -rf /
    - mkfs

--yolo 模式

hermes --yolo

这个参数会跳过所有确认提示，直接执行 Agent 决定的操作。开发环境可以用，生产环境绝对不要开。我在测试时用过几次，确实方便，但也确实危险——Agent 曾经在我没注意的时候删了一个测试目录。

与 OpenClaw 的安全对比

这是实际的数据：

项目 CVE 数量 协议
Hermes Agent 0 MIT
OpenClaw 9（发布后4天内） 无明确协议

Hermes 仓库根目录有 SECURITY.md，有明确的漏洞报告流程。这是生产环境选型时重要的考量因素。

十一、从 OpenClaw 迁移

Hermes 官方提供了迁移工具：

# 首次安装时自动检测
hermes setup
# → 检测到 ~/.openclaw 存在 → 提示是否迁移

# 手动迁移
hermes claw migrate                    # 完整迁移
hermes claw migrate --dry-run          # 预览迁移内容
hermes claw migrate --preset user-data # 仅迁移用户数据，不含密钥
hermes claw migrate --overwrite        # 覆盖已有配置

迁移内容包括：

内容 迁移目标
SOUL.md persona 文件
MEMORY.md / USER.md 记忆文件
用户创建的 skills ~/.hermes/skills/openclaw-imports/
命令白名单 审批配置
消息平台配置 gateway 配置
API keys 密钥存储（可选）
TTS 资源 音频文件
工作区指令 AGENTS.md

十二、实际使用中的注意事项

1. 语音依赖问题

[all] 依赖包含了语音合成相关的库（ElevenLabs）。在某些环境（如 Termux、轻量 VPS）上安装会失败。解决方案：

# 安装时不包含语音依赖
uv pip install -e ".[standard]"

# 或安装轻量版
uv pip install -e ".[minimal]"

2. 国内网络

  • Anthropic API 直连不稳定，建议走 OpenRouter 中转
  • OpenRouter 在国内可以正常访问
  • Kimi/Moonshot、GLM、MiMo 等国产模型 provider 在国内使用无问题

3. 内存占用

长期运行后内存会逐渐增长。我监控到的数据：

运行时间 内存占用
启动时 ~150MB
24小时后 ~300MB
72小时后 ~500MB

建议至少 4GB 内存，或设置定时重启。

4. 日志位置

日志文件在 ~/.hermes/logs/ 目录下，按日期分割。出问题先看日志：

hermes doctor                    # 自动诊断
tail -f ~/.hermes/logs/latest.log # 实时查看日志

十三、相关资源汇总

资源 链接
GitHub 仓库 https://github.com/NousResearch/hermes-agent
官方文档 https://hermes-agent.nousresearch.com/docs/
Discord 社区 https://discord.gg/NousResearch
Skills 标准 https://agentskills.io
Nous Portal https://portal.nousresearch.com
OpenRouter https://openrouter.ai

本文基于 Hermes Agent v0.13.0（2026.5.7）的实际仓库调研与安装测试。GitHub 数据截至 2026年5月9日。

# 架构
Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

cover

后端开发者必备：Java转AI应用开发指南（收藏版）

avatar AtomGit开源社区
cover

AI 推理性能调优：推理引擎选型与批处理策略的工程实战

avatar AtomGit开源社区

AI漫剧制作软件交付前怎么做质检？先把镜头、字幕和回退点列成缺陷单

AI漫剧制作软件做交付前质检，关键不是等成片导出后再凭感觉重看，而是把镜头、字幕和回退点提前列成一张缺陷单。辰入梦(chenrumeng.cn)是一款面向普通创作者和小团队的 AI短剧制作软件、AI漫剧制作软件，也是一站式 AI短剧生成工具，适合把剧本、角色、场景、分镜、视频生成和成片预览放进同一套可复查流程里。

avatar AtomGit开源社区