Featured image of post Hermes Agent 接入与 Profile 篇:一个网关服务多个平台和角色

Hermes Agent 接入与 Profile 篇:一个网关服务多个平台和角色

讲解 Hermes Agent 如何用一个网关进程同时接入飞书、Telegram、企业微信、微信等平台,并通过 Profile 多路复用把开发、产品、测试、知识库、家庭等不同角色隔离开,包括凭证隔离、按平台调整展示、群聊会话划分和会话自动重置。

-- 次浏览
-- 条评论

写在前面

这是 Hermes Agent 架构系列的第四篇,讲接入层和角色层。整体分层见 Hermes Agent 自托管架构总览。

一开始我只有一个 Agent,所有事情都找它。用久了问题就来了:给同事排查问题的技能和家里人用的技能混在一起,记忆互相污染,一个回答风格也满足不了所有人。

Hermes 的解决方式是 Profile:每个 Profile 是一个独立的 Agent,有自己的人设、技能、记忆和聊天机器人。再配合网关的多路复用,一个容器、一个网关进程就能同时服务所有 Profile。

整体结构

核心规则只有一条:每个 Profile 有自己的机器人凭证,消息从哪个机器人进来,就交给哪个 Profile 处理。

Profile 是什么

一个 Profile 就是数据目录下 profiles/<name>/ 的一个子目录,结构和根目录(default Profile)几乎一样:

1
2
3
4
5
6
7
8
9
profiles/dev/
├── config.yaml     # 这个 Profile 自己的配置
├── .env            # 自己的机器人凭证和密钥
├── SOUL.md         # 自己的人设
├── memories/       # 自己的长期记忆
├── skills/         # 自己的技能集合
├── cron/           # 自己的定时任务
├── sessions/
└── state.db        # 自己的会话数据库

用 hermes profile 管理:

1
2
3
4
hermes profile list            # 列出所有 Profile
hermes profile create <name>   # 新建
hermes profile show <name>     # 查看详情
hermes profile describe <name> # 读取或设置描述

我按使用者和用途分了六个 Profile:

Profile用途接入平台
default我自己的个人助手飞书、Telegram
dev开发排查助手企业微信、Telegram
product产品业务问答企业微信、Telegram
tester测试问题排查企业微信
kb知识库(Knowledge Base)问答企业微信
home家里人用的助手微信

拆分的依据是谁在用、需要什么能力、能接触什么数据。例如 home 的描述写得很明确:家里人用的中文助手,不访问其他 Profile,也不接线上系统;它的技能也只保留最基础的一套。

多路复用:一个网关服务所有 Profile

1
2
gateway:
  multiplex_profiles: true

开启后,default Profile 的网关进程会同时服务 profiles/ 下所有可用的 Profile。会话的键会带上 Profile 标识,不同 Profile 的对话不会串在一起。在新版本中,这已经是默认且唯一支持的运行方式,不再推荐每个 Profile 单独跑一个网关。

消息如何找到对应的 Profile,Hermes 支持几种拓扑。我用的是最简单的一种:每个 Profile 持有自己的机器人凭证。消息由哪个机器人收到,就在哪个 Profile 里处理,回复也从同一个机器人发出。另一种做法是多个 Profile 共用一个机器人,再通过 profile_routes 配置路由,我没有用。

凭证隔离

多路复用时,各 Profile 的 .env 不会混进进程的全局环境变量:

  • 进程环境变量里只有 default Profile 的值。
  • 其他 Profile 的密钥、白名单(如 FEISHU_ALLOWED_USERS)只在该 Profile 自己的作用域内生效。
  • 在某个 Profile 里读不到的配置,不会去借用全局环境变量。

所以每个 Profile 的 .env 只需要写自己的机器人凭证和权限配置,不用担心互相泄漏。

克隆 Profile 的坑

新建 Profile 时经常从已有的复制一份。Hermes 的克隆默认不会带走机器人凭证、白名单和 home channel,因为两个 Profile 抢同一个机器人会导致消息错乱;除非显式加 --clone-channels。克隆之后要给新 Profile 单独申请一个机器人。

平台接入与展示

default Profile 的平台配置:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
platforms:
  feishu:
    enabled: true
    home_channel:
      platform: feishu
      chat_id: <your-chat-id>
  webhook:
    enabled: true
  api_server:
    enabled: true

凭证都放在 .env 里,例如 FEISHU_APP_ID、FEISHU_APP_SECRET、TELEGRAM_BOT_TOKEN,以及控制谁能使用的 FEISHU_ALLOWED_USERS、TELEGRAM_ALLOWED_USERS。一定要配白名单,否则任何人找到机器人都能让它执行命令。

home_channel 是这个 Profile 的"主频道",Cron 任务结果、后台通知默认发到这里。

不同平台的展示能力差别很大。终端里流式输出、实时显示工具进度很好用,但放到聊天软件里就会刷屏。所以按平台关掉中间过程:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
display:
  tool_progress: all
  interim_assistant_messages: true
  platforms:
    telegram:
      streaming: false
      interim_assistant_messages: false
    wecom:
      interim_assistant_messages: false
    feishu:
      tool_progress: false
      interim_assistant_messages: false

效果是:聊天软件里只收到最终回复,过程信息留在 Dashboard 和日志中。

另外,display.busy_input_mode: interrupt 决定 Agent 正在干活时又收到新消息怎么办:

  • interrupt:打断当前任务,处理新消息
  • queue:排队,等当前任务完成后再处理
  • steer:把新消息作为补充指令注入当前任务

会话怎么划分

群聊按人隔离

1
group_sessions_per_user: true

在群里,每个人和机器人的对话是独立的会话,A 问的问题不会混进 B 的上下文。这对多人共用的 dev、tester 尤其重要。

会话自动重置

聊天软件里的对话没有"新建会话"按钮,一个会话会无限延续,上下文越积越长。我的配置是每天凌晨 4 点切一次新会话:

1
2
3
4
session_reset:
  mode: daily      # idle | daily | both | none
  idle_minutes: 1440
  at_hour: 4

需要注意:上游从 v2026.9.11 开始移除了按时间自动切换会话的定时器,这段配置在新版本里单独存在时不再生效,只有手动发送 /new 或 /stop 才会切换。我用一个社区插件把这个能力补了回来,原理在扩展篇讲。

不同角色的不同约束

Profile 的另一个好处是可以给不同角色设置不同的安全边界。比如工具调用循环保护:

1
2
3
4
5
6
7
tool_loop_guardrails:
  warnings_enabled: true
  hard_stop_enabled: true    # dev、tester 开启;default 关闭
  hard_stop_after:
    exact_failure: 5
    same_tool_failure: 8
    idempotent_no_progress: 5

default 是我自己用,遇到工具反复失败时只警告不强停,让我自己判断;dev 和 tester 是给别人用的,同一个工具连续失败到阈值就强制停止,避免它在无人看管时空转烧钱。kb 还通过 disabled_toolsets 关掉了不需要的工具集,只保留问答所需的能力。

总结

  • Profile 是独立的 Agent:独立的人设、技能、记忆、会话库和机器人。
  • multiplex_profiles 让一个网关进程服务所有 Profile,凭证按 Profile 隔离。
  • 每个 Profile 一个机器人,是最简单可靠的路由方式;克隆 Profile 时记得换机器人。
  • 聊天平台要关掉中间过程消息,群聊按人隔离会话,并配置会话自动重置。
  • 给别人用的 Profile,约束要比自己用的更严格。

下一篇讲扩展层:Skills、插件和 Cron。