Hermes Agent 部署指南

🚀 快速安装

pip 安装，一条命令启动，配置文件驱动所有行为

5 分钟上手

⚙️ config.yaml 详解

每个配置字段的含义与最佳实践，附最小配置和进阶配置示例

配置参考

❌ 常见问题

平台接入失败、Skill 不生效、Gateway 超时… 排查思路与解决方案

排错指南

💡 使用技巧

Skill 编写规范、Memory 使用、多 Agent 协作、调试技巧

进阶技巧

一、安装

推荐环境：Ubuntu 20.04+ / macOS 13+，Python 3.10+，有网络连接。无 GPU 要求（纯 CPU 即可运行，GPU 用于加速模型推理）。

安装 Hermes CLI

pip install hermes-agent

# 验证安装
hermes --version

Tip：推荐使用虚拟环境安装：python -m venv hermes-env && source hermes-env/bin/activate && pip install hermes-agent。避免污染系统 Python 环境。

初始化项目

# 在目标目录初始化
hermes init ~/hermes-agent

# 进入目录
cd ~/hermes-agent

初始化后会生成以下文件：

~/hermes-agent/
├── config.yaml       # 主配置文件
├── skills/           # Skill 目录（自行创建）
├── memory/          # 记忆存储目录
└── logs/            # 日志目录

编写 config.yaml

这是 Hermes 的核心配置文件。参考下一节的详细字段说明进行配置。

注意：YAML 格式对缩进敏感，请使用空格（不是 Tab）缩进。建议缩进 2 个空格。

启动

# 前台运行（查看实时日志）
hermes start

# 后台运行
hermes start --daemon

# 查看状态
hermes status

启动后：Hermes Gateway 默认监听 http://localhost:8000。API 端点在 /v1/chat，Web UI 在 /ui（如果启用）。

二、config.yaml 配置详解

config.yaml 控制 Hermes 的所有行为：模型来源、平台接入、Skill 目录、日志级别等。以下是完整字段说明。

字段	类型	说明
agent.name	string	Agent 名称，用于日志和调试标识
agent.model	string	默认模型 ID，如 `gpt-4o`、`claude-4-sonnet`、`deepseek-v3`
agent.api_base	string	API 地址，留空默认 OpenAI官方。填 FlowerWolf 节点：`https://api.flowerwolf.net/v1`
agent.api_key	string	API Key，必填。从 flowerwolf.net/token.html 获取
agent.max_tokens	int	单次回复最大 token 数，默认 4096。复杂任务建议设到 8192
agent.temperature	float	采样温度，0.0–2.0，默认 0.7
agent.system_prompt	string	系统提示词，定义 Agent 的角色和行为风格
gateway.host	string	Gateway 监听地址，默认 `0.0.0.0`（接受所有来源）
gateway.port	int	Gateway HTTP 端口，默认 8000
gateway.allow_all_users	bool	设为 true 则允许所有用户访问，false 则只允许白名单用户
skills.dir	string	Skill 文件目录，默认 `./skills`
skills.autoload	bool	启动时是否自动加载全部 Skill
memory.provider	string	记忆存储方式：`sqlite`（默认）、`postgres`、`memory`
memory.session_limit	int	单会话最大消息数，超出自动摘要压缩
platforms.feishu.enabled	bool	是否启用飞书
platforms.feishu.app_id	string	飞书应用 App ID
platforms.feishu.app_secret	string	飞书应用 App Secret
platforms.feishu.bot_name	string	机器人名称
platforms.telegram.enabled	bool	是否启用 Telegram
platforms.telegram.bot_token	string	Telegram Bot Token，从 @BotFather 获取
platforms.discord.enabled	bool	是否启用 Discord
platforms.discord.bot_token	string	Discord Bot Token
log.level	string	日志级别：`debug` / `info` / `warn` / `error`
log.file	string	日志文件路径，留空只输出到 stdout
cors.enabled	bool	是否允许跨域请求（前端调试时开启）
cors.origins	list	允许的来源域名列表，如 `["https://flowerwolf.net"]`

最小可用配置

agent:
  name: my-hermes
  model: gpt-4o
  api_base: https://api.flowerwolf.net/v1
  api_key: your-token-here

gateway:
  host: "0.0.0.0"
  port: 8000
  allow_all_users: true

skills:
  dir: ./skills
  autoload: true

memory:
  provider: sqlite
  session_limit: 30

log:
  level: info

Tip — system_prompt 模板变量：在 system_prompt 里可以使用 {{user_name}}、{{agent_name}}、{{current_time}} 等变量，Hermes 会在运行时自动替换。

三、Skill 编写规范

Skill 是 Hermes 的扩展单元。每个 Skill 是一个独立文件，放在 skills/ 目录，启动时自动加载。

Skill 文件结构

name: summarize_text
description: 将长文本压缩为摘要，适用于"帮我总结一下这篇文章"这类请求
version: "1.0"
trigger:
  keywords: ["总结", "摘要", "概括", "太长", "精简"]
action: python
script: |
  def summarize(text, ratio=0.3):
      # 调用大模型进行摘要（这里用简单的抽取式演示）
      sentences = text.replace("\n", " ").split("。")
      summary = "。".join(sentences[:max(1, int(len(sentences) * ratio))]) + "。"
      return summary

  # Hermes 会自动将对话中的相关文本传入 text 参数
  result = summarize(text="{{context}}", ratio=0.3)
  print(result)

关键字段说明：

• name：Skill 唯一名称，不能与其他 Skill 重名。

• description：描述 Agent 何时该调用这个 Skill，越详细 Agent 判断越准确。

• trigger.keywords：触发关键词，当用户消息包含这些词时，Agent 会优先考虑调用。

• action: python：当前支持 python（执行 Python 脚本）和 http（发起 HTTP 请求）两种类型。

• {{context}}：特殊变量，会被替换为对话中的相关上下文。

HTTP 类型 Skill

不只调用本地脚本，也可以用 Skill 发起 HTTP 请求，对接外部 API。

name: weather_query
description: 查询城市天气，如"北京天气怎么样"
version: "1.0"
trigger:
  keywords: ["天气", "气温", "下雨", "温度"]
action: http
script:
  method: GET
  url: "https://api.weather.com/v3/wx/conditions/current?city={{city}}&key=YOUR_KEY"
  headers:
    Accept: application/json

调试 Skill：用 hermes skills list 查看已加载的 Skill。用 hermes skills test summarize_text 可以单独测试某个 Skill。

四、常见问题排查

飞书消息收不到 / DM 正常但群消息不触发

这是最常见的问题。排查顺序：

1. 确认飞书应用已开通「机器人」能力，并在「事件订阅」里选择了「使用长连接接收事件」（不是 Webhook URL 模式）。

2. 确认应用已开通权限：im:message、im:message:send_as_bot。

3. 群组消息：飞书默认不把群消息发给应用。需要在应用配置里设置 FEISHU_GROUP_POLICY=open（或在 config.yaml 的 platforms.feishu.group_policy 字段设置）。

4. 检查日志：hermes logs | grep feishu 看有没有收到事件的记录。

5. 同一个飞书应用下的 OpenClaw bot 能收群消息，说明平台层配置没问题，问题在 Hermes 配置。

Gateway 启动报错 / Port already in use

端口被占用。先查占用进程：ss -tlnp | grep 8000。如果是你自己之前的 Hermes，用 hermes stop 停止。如果是被其他程序占用，结束那个进程或改端口：gateway.port: 8001。

Skill 加载了但 Agent 不调用

确认两件事：1) Skill 文件语法正确（YAML 格式），用 hermes skills list 看 Skill 是否在列表里。2) Skill 的 description 写得够具体，Agent 根据 description 判断是否调用——描述越具体，触发越准确。

也可以手动触发：在对话里直接说「使用 summarize_text Skill 处理这段文字」。

API 请求 403 / 429 / 500

403：API Key 无效或无余额。检查 Key 拼写和 Token 余额。

429：请求频率超限。FlowerWolf 有 RPM 限制，高频调用需要排队或升级套餐。

500：上游 API 报错。看 Hermes 日志里的具体错误信息，通常是模型服务方内部问题，等待重试即可。

Memory 占用不断增长

默认 SQLite 模式会不断追加对话历史。设置 memory.session_limit 控制单会话最大消息数。超出的消息会被自动摘要压缩。如果想完全关闭记忆：memory.provider: none。

CORS 报错 / 前端无法访问 API

前端直接调用 Hermes API 时，浏览器会检查 CORS。如果 cors.enabled: false，请求会被拦截。

开发环境设 cors.enabled: true，cors.origins: ["*"]（或指定前端域名）。生产环境务必指定具体域名，不使用 *。

hermes start 没有任何输出

前台运行看不到日志通常是配置问题。用 hermes start -v（verbose 模式）看详细信息。也可以直接运行 python -m hermes 看 Python 层的报错。

五、使用技巧

用 Memory 做上下文注入

Hermes 的 Memory 不只存储对话历史，还可以在每次请求时注入自定义上下文。

在 config.yaml 里设置 memory.inject_user_profile，可以为不同用户存储个性化信息（偏好、角色、历史），Agent 在每次回复时都能看到，相当于给每个用户一个专属记忆。

Cron Job：让 Agent 定时执行任务

在 config.yaml 里配置 Cron Job，实现自动化：

cron:
  "0 9 * * 1-5": "daily_briefing"    # 工作日早上9点推送日报摘要
  "0 */2 * * *": "check_alerts"      # 每2小时检查一次异常
  "0 0 * * 0": "weekly_report"       # 每周日凌晨生成周报

Cron 任务名称对应一个 Skill，Skill 执行完毕后结果会推送到配置的频道（飞书/TG/Discord）。

多 Agent 协作：分工处理不同业务

一个 Hermes 实例可以配置多个 Agent，每个 Agent 有独立的模型、Skill 和职责。

比如：agents[0].name: "coder" 专职代码审查，agents[1].name: "support" 专职客服。通过 Router Agent 根据用户意图分发请求到对应 Agent。

用 Webhook 接入更多平台

Hermes 支持自定义 Webhook，可以接入任何支持 Webhook 的平台（Slack、钉钉、企业微信等）。

在 platforms.custom 下配置 Webhook URL，Hermes 会把消息以固定格式 POST 到该地址，由你的服务做后续处理。

日志调试：精确定位问题

遇到问题，把 log.level 改为 debug 重启。debug 级别会记录每个 Skill 的触发决策、HTTP 请求的完整响应、Memory 的注入内容，信息量很大，正常运行时用 info 即可。

Skill 热加载

不需要重启 Hermes 就能加载新 Skill 或更新现有 Skill。

运行 hermes skills reload 会重新扫描 skills/ 目录并加载所有 Skill，新增和修改的 Skill 立即生效。配合 log.level: debug 可以看到 Skill 加载的详细日志。

六、常见问答

问：Hermes 和 OpenClaw 有什么区别？

两个都是 Agent 框架，核心区别在于架构风格。OpenClaw 更「一体化」，配置集中在 config.yaml，多平台接入内置。Hermes 更「模块化」，Skill 是独立文件，平台配置更灵活。OpenClaw 适合快速上手，Hermes 适合深度定制。

问：一台服务器能跑几个 Hermes 实例？

每个实例监听一个端口，互不干扰。内存允许的情况下跑 3–5 个实例没问题。如果都用 GPU 推理，受限于 GPU 显存，3090 24GB 大约跑 2 个带 GPU 加速的实例，CPU 模式则只受内存限制。

问：Hermes 支持流式输出（Streaming）吗？

支持。在 config.yaml 启用 agent.stream: true，API 请求会使用 Server-Sent Events（SSE），前端可以逐字显示 AI 输出。

问：如何升级 Hermes？

pip install hermes-agent --upgrade。升级前建议先 hermes stop 停止服务。配置文件的字段通常向前兼容，但如果新版本有重大变更，会在升级说明里注明。

问：能否把 Hermes 对接到已有系统（飞书/钉钉）？

完全可以。Hermes 提供了标准的 HTTP API（/v1/chat）和 WebSocket 接口。飞书、钉钉等平台可以通过 Bot 消息事件触发 Hermes，Hermes 处理后把回复通过 Bot API 推送回去。详细接法参考各平台的 Bot 开发文档。