网关内部机制
消息网关（Messaging Gateway）是连接 Hermes 与 20 多个外部消息平台的长时间运行进程，采用统一架构。
关键文件
| 文件 | 用途 |
|---|---|
gateway/run.py | GatewayRunner — 主循环、斜杠命令、消息分发（大文件；查看 git 获取当前行数） |
gateway/session.py | SessionStore — 对话持久化和会话键构建 |
gateway/delivery.py | 向目标平台/频道投递出站消息 |
gateway/pairing.py | 用于用户授权的 DM 配对流程 |
gateway/channel_directory.py | 将聊天 ID 映射为人类可读名称（用于 cron 投递） |
gateway/hooks.py | 钩子发现、加载和生命周期事件分发 |
gateway/mirror.py | 用于 send_message 的跨会话消息镜像 |
gateway/status.py | 用于配置文件作用域的网关实例的令牌锁管理 |
gateway/builtin_hooks/ | 始终注册的钩子的扩展点（目前未提供任何钩子） |
gateway/platforms/ | 平台适配器（每个消息平台一个） |
架构概览
┌─────────────────────────────────────────────────┐
│ GatewayRunner │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Telegram │ │ Discord │ │ Slack │ │
│ │ Adapter │ │ Adapter │ │ Adapter │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │ │
│ └─────────────┼─────────────┘ │
│ ▼ │
│ _handle_message() │
│ │ │
│ ┌───────────┼───────────┐ │
│ ▼ ▼ ▼ │
│ Slash command AIAgent Queue/BG │
│ dispatch creation sessions │
│ │ │
│ ▼ │
│ SessionStore │
│ (SQLite 持久化) │
└───────┴─────────────┴─────────────┴─────────────┘消息流程
当消息从任何平台到达时：
- 平台适配器接收原始事件，将其归一化为
MessageEvent - 基础适配器检查活动会话守卫：
- 如果此会话的代理正在运行 → 将消息加入队列，设置中断事件
- 如果是
/approve、/deny、/stop→ 绕过守卫（内联分发）
- GatewayRunner._handle_message() 接收事件：
- 通过
_session_key_for_source()解析会话键（格式：agent:main:{platform}:{chat_type}:{chat_id}） - 检查授权（见下文授权部分）
- 检查是否为斜杠命令 → 分派到命令处理器
- 检查代理是否已在运行 → 拦截
/stop、/status等命令 - 否则 → 创建
AIAgent实例并运行对话
- 通过
- 响应通过平台适配器发送回去
会话键格式
会话键编码了完整的路由上下文：
agent:main:{platform}:{chat_type}:{chat_id}
例如：agent:main:telegram:private:123456789
支持线程的平台（Telegram 论坛话题、Discord 线程、Slack 线程）可能在 chat_id 部分包含线程 ID。切勿手动构建会话键——始终使用 gateway/session.py 中的 build_session_key()。
两级消息守卫
当代理正在运行时，传入消息通过两个顺序守卫：
-
第 1 级 — 基础适配器（
gateway/platforms/base.py）：检查_active_sessions。如果会话处于活动状态，将消息加入_pending_messages队列并设置中断事件。这会在消息到达网关运行器之前捕获消息。 -
第 2 级 — 网关运行器（
gateway/run.py）：检查_running_agents。拦截特定命令（/stop、/new、/queue、/status、/approve、/deny）并进行相应路由。其他所有内容触发running_agent.interrupt()。
必须在代理阻塞时到达运行器的命令（如 /approve）通过 await self._message_handler(event) 内联分发——它们绕过后台任务系统以避免竞态条件。
授权
网关使用多层授权检查，按顺序评估：
- 平台级别的允许所有标志（例如
TELEGRAM_ALLOW_ALL_USERS）——如果设置，该平台上的所有用户都获得授权 - 平台允许列表（例如
TELEGRAM_ALLOWED_USERS）——逗号分隔的用户 ID - DM 配对——已认证用户可以通过配对码将新用户配对
- 全局允许所有（
GATEWAY_ALLOW_ALL_USERS）——如果设置，所有平台的所有用户都获得授权 - 默认：拒绝——未授权用户被拒绝
DM 配对流程
管理员：/pair
网关："配对码：ABC123。请分享给用户。"
新用户：ABC123
网关："配对成功！你现在已获得授权。"配对状态持久化存储在 gateway/pairing.py 中，重启后仍然有效。
斜杠命令分发
网关中的所有斜杠命令都通过相同的解析管道：
hermes_cli/commands.py中的resolve_command()将输入映射到规范名称（处理别名、前缀匹配）- 规范名称在
GATEWAY_KNOWN_COMMANDS中检查 _handle_message()中的处理器根据规范名称进行分发- 某些命令受配置限制（
CommandDef上的gateway_config_gate）
运行代理守卫
在代理处理过程中不得执行的命令会被提前拒绝：
if _quick_key in self._running_agents:
if canonical == "model":
return "⏳ 代理正在运行——请等待处理完成或使用 /stop 停止。"绕过命令（/stop、/new、/approve、/deny、/queue、/status）具有特殊处理。
配置来源
网关从多个来源读取配置：
| 来源 | 提供内容 |
|---|---|
~/.hermes/.env | API 密钥、机器人令牌、平台凭据 |
~/.hermes/config.yaml | 模型设置、工具配置、显示选项 |
| 环境变量 | 覆盖上述任何设置 |
与 CLI（使用带硬编码默认值的 load_cli_config()）不同，网关直接通过 YAML 加载器读取 config.yaml。这意味着存在于 CLI 默认值字典中但不在用户配置文件中的配置键，在 CLI 和网关之间的行为可能不同。
平台适配器
每个消息平台在 gateway/platforms/ 中都有一个适配器：
gateway/platforms/
├── base.py # BaseAdapter — 所有平台的共享逻辑
├── telegram.py # Telegram Bot API（长轮询或 webhook）
├── discord.py # 通过 discord.py 的 Discord 机器人
├── slack.py # Slack Socket Mode
├── whatsapp.py # WhatsApp Business Cloud API
├── signal.py # 通过 signal-cli REST API 的 Signal
├── matrix.py # 通过 mautrix 的 Matrix（可选 E2EE）
├── mattermost.py # Mattermost WebSocket API
├── email.py # 通过 IMAP/SMTP 的电子邮件
├── sms.py # 通过 Twilio 的短信
├── dingtalk.py # 钉钉 WebSocket
├── feishu.py # 飞书/Lark WebSocket 或 webhook
├── wecom.py # 企业微信回调
├── weixin.py # 通过 iLink Bot API 的微信
├── bluebubbles.py # 通过 BlueBubbles macOS 服务器的 Apple iMessage
├── qqbot/ # QQ 机器人（腾讯 QQ）通过官方 API v2（子包：adapter.py、crypto.py、keyboards.py 等）
├── yuanbao.py # 元宝（腾讯）私信/群组适配器
├── feishu_comment.py # 飞书文档/云盘评论回复处理器
├── msgraph_webhook.py # Microsoft Graph 变更通知 webhook（Teams、Outlook 等）
├── webhook.py # 入站/出站 webhook 适配器
├── api_server.py # REST API 服务器适配器
└── homeassistant.py # Home Assistant 对话集成适配器实现公共接口：
connect()/disconnect()— 生命周期管理send_message()— 出站消息投递on_message()— 入站消息归一化 →MessageEvent
令牌锁
使用唯一凭据连接的适配器在 connect() 中调用 acquire_scoped_lock()，在 disconnect() 中调用 release_scoped_lock()。这防止两个配置文件同时使用相同的机器人令牌。
投递路径
出站投递（gateway/delivery.py）处理：
- 直接回复 — 将响应发送回原始聊天
- 首页频道投递 — 将 cron 任务输出和后台结果路由到配置的首页频道
- 显式目标投递 —
send_message工具指定telegram:-1001234567890，或hermes sendCLI 包装同一工具用于 Shell 脚本 - 跨平台投递 — 投递到与原始消息不同的平台
Cron 任务投递不会镜像到网关会话历史中——它们仅存在于自己的 cron 会话中。这是一个有意的设计选择，以避免消息交替违规。
钩子
网关钩子是响应生命周期事件的 Python 模块：
网关钩子事件
| 事件 | 触发时机 |
|---|---|
gateway:startup | 网关进程启动 |
session:start | 新对话会话开始 |
session:end | 会话完成或超时 |
session:reset | 用户通过 /new 重置会话 |
agent:start | 代理开始处理消息 |
agent:step | 代理完成一次工具调用迭代 |
agent:end | 代理完成处理并返回响应 |
command:* | 执行任何斜杠命令 |
钩子从 gateway/builtin_hooks/（一个扩展点——当前在发布版本中为空；_register_builtin_hooks() 是一个空操作存根）和 ~/.hermes/hooks/（用户安装）发现。每个钩子是一个包含 HOOK.yaml 清单和 handler.py 的目录。
记忆提供者集成
当启用了记忆提供者插件（例如 Honcho）时：
- 网关为每条消息创建一个
AIAgent，附带会话 ID MemoryManager（记忆管理器）使用会话上下文初始化提供者- 提供者工具（例如
honcho_profile、viking_search）通过以下路径路由：
AIAgent._invoke_tool()
→ self._memory_manager.handle_tool_call(name, args)
→ provider.handle_tool_call(name, args)- 在会话结束/重置时，触发
on_session_end()进行清理和最终数据刷新
记忆刷新生命周期
当会话被重置、恢复或过期时：
- 内置记忆刷新到磁盘
- 记忆提供者的
on_session_end()钩子触发 - 一个临时
AIAgent运行一个仅记忆的对话轮次 - 上下文随后被丢弃或归档
后台维护
网关在处理消息的同时运行定期维护：
- Cron 滴答 — 检查任务调度并触发到期任务
- 会话过期 — 超时后清理废弃的会话
- 记忆刷新 — 在会话过期前主动刷新记忆
- 缓存刷新 — 刷新模型列表和提供者状态
进程管理
网关作为长期运行的进程，通过以下方式管理：
hermes gateway start/hermes gateway stop— 手动控制systemctl（Linux）或launchctl（macOS）— 服务管理- PID 文件位于
~/.hermes/gateway.pid— 配置文件作用域的进程跟踪
配置文件作用域 vs 全局：start_gateway() 使用配置文件作用域的 PID 文件。hermes gateway stop 仅停止当前配置文件的网关。hermes gateway stop --all 使用全局 ps aux 扫描来终止所有网关进程（在更新时使用）。