Messaging Gateway 是一个长期后台进程：同时连接一个或多个消息平台，为每个 chat 保存 session，运行 cron scheduler，并把 Agent 的回复送回原入口。当前各平台 toolset 通常包含 terminal 等完整工具，所以接入消息的同时也把远程触发面带进了运行环境。
本课只接一个低风险入口，使用 GW-CANARY-219 验证配置、进程、adapter、端到端回复和停用。没有证据前不接第二个平台。
本站验证范围： 本页于 2026-09-09 核读 v0.21.1 / v2026.9.7 当前 Messaging Gateway、Telegram、Profiles 和 Slash Commands；没有配置真实 adapter、保存凭据或安装后台服务。
下载两份运行材料
验收表中的“未验证”必须由实际结果替换。不要记录 token、API Key、cookie、完整 .env 或带私人消息的日志。
先理解四层状态
| 层 | 它证明什么 | 不能证明什么 |
|---|---|---|
| 配置 | 当前 profile 已保存 adapter 凭据与选项 | 进程正在运行 |
| Gateway 进程 | 服务或前台进程存活 | 某个 adapter 已成功连接 |
| Adapter | /platform list 显示 running | 用户授权和端到端回复正确 |
| 端到端 | 授权用户在原 chat 收到正确回复 | 未授权用户一定被拒绝 |
Desktop 或 dashboard 中出现 Saved，也只属于配置层。不同 profile 不继承服务进程的凭据；一个已配置平台完全可能同时显示 Gateway stopped。
G01：锁定 profile 和 home
先运行：
hermes dump把版本、profile 和实际 HERMES_HOME 写入运行卡。后续所有 .env、config.yaml、日志和服务命令必须属于同一 home。多 profile 环境不要凭 shell 提示猜身份。
每个 profile 需要自己的 gateway 进程和 bot token。当前 Telegram、Discord、Slack、WhatsApp、Signal 等平台还有 token lock：两个 profile 误用同一个 token 时，第二个 gateway 会被阻止，而不是安全地共享同一 bot。
G02：只配置一个 adapter
当前推荐入口是交互式向导：
hermes gateway setup只选本轮要测的平台。向导会显示已经配置的 adapter，并在结束时提供启动或重启。凭据写入后不要把 .env 内容复制到验收表；只记录“目标 profile 中已保存”和核对时间。
如果配置里显式写了：
platforms:
telegram:
enabled: false它会覆盖环境中已有凭据，不启动该 adapter。保留 token 供 send-only 工具使用与启动接收 adapter 是两件事。
G03：第一次必须前台启动
先不要安装服务，直接运行：
hermes gateway前台日志应显示预期 adapter 初始化，并且没有凭据、重复 token、代理或网络错误。此时只完成进程与连接观察；还需要真实消息证明端到端路径。
如果服务环境继承了失效代理，日志可能持续连接 127.0.0.1 的旧代理端口。当前所有 adapter 默认尊重 HTTP_PROXY、HTTPS_PROXY、NO_PROXY 和 macOS 系统代理。确认确实不需要继承代理后，才可在配置使用：
gateway:
trust_env: false这不会覆盖明确的单平台代理设置。
G04–G06：跑正常与授权负例
从唯一允许的个人私聊发送：
请只回复 GW-CANARY-219，不调用工具，不补充解释。回复必须回到相同 chat。随后发送 /status 核对 session，再用 /whoami 查看当前作用域是 admin、user 还是 unrestricted，以及能运行哪些 slash command。
再用第二个自控测试账号发送无害问候。通过标准是没有 Agent 回复，并能在脱敏日志中辨认拒绝或忽略。仅验证授权账号成功不够；入口安全必须包含拒绝证据。
当前平台允许把 slash command 分为管理员和普通用户。普通用户只应得到 user_allowed_commands 列出的命令，加上始终可用的 /help、/whoami。没有设置管理员列表的旧配置可能处于 unrestricted 兼容模式，因此 /whoami 是必须执行的验收项。
G07：证明单 adapter 可暂停
从已连接 chat 或 CLI 运行：
/platform list
/platform pause telegram把平台名换成实际 adapter。确认状态从 running 变为 paused，在暂停期发送另一个金丝雀，然后执行：
/platform resume telegram暂停会保留 adapter 和连接循环，但新入站消息会被丢弃。通过标准是暂停期消息没有执行，并且恢复后只处理新消息；如果旧消息补跑，说明观察结果与当前官方语义不一致，需要停止上线。
G08：区分重启与新 session
先给当前 session 设置标题并记录 /status，重启 gateway，再在同 chat 发送一个问题。当前会话不会因为空闲、跨天或 gateway 重启自动清空；模型选择也可能从 session store 恢复。
只有下面的命令才明确开始新会话：
/new gateway-clean-room不要把重启后仍记得上下文误判为 Memory，也不要把进程 PID 变化误判为新 session。
G09：验收成功与失败投递
Gateway 使用持久 delivery ledger 记录最终回复。若崩溃发生在发送中间，当前语义是诚实的 at-least-once：恢复消息可能带重复提示；有界重投不等于 exactly-once。
运行卡至少记录：
- 一条成功回复的 chat、时间和可见结果；
- 一个无害错误目标或被拒绝动作的失败回执；
- 错误中没有 token、主机 secrets 或完整内部路径；
- 业务若无法容忍重复，消费端按任务 ID 做幂等，而不是假设 Gateway 永不重复。
G10：前台通过后再安装服务
Linux/macOS 的常用命令：
hermes gateway install
hermes gateway start
hermes gateway status
hermes gateway stopLinux 无登录的服务器可选择 user service 加 linger，或显式 system service。不要让 user 与 system 两套服务同时管理同一个 profile；当前 Hermes 会告警，但运行归属仍会变得难以判断。
Windows、Docker 和 Android 的长期运行方式不同，以当前官方对应平台文档为准。本课只要求记录“谁负责拉起进程、谁负责重启、日志在哪里、如何停止”。
G11：认识自动熔断
adapter 连续遇到可重试网络错误、限流、上游 5xx 或 socket 断连时，当前 Gateway 会触发 circuit breaker 并进入 paused-by-breaker。它不会自动恢复，以免持续重连。
处理顺序：
/platform list识别具体 adapter；- 查看该平台日志与上游状态；
- 修复凭据、代理、限流或网络原因；
/platform resume <name>手动恢复；- 再跑新的端到端金丝雀。
不要用循环 restart 掩盖根因。
G12：完整停用
停用顺序应写进运行卡：
/platform pause <name>阻止新分发；- 等待或终止正在运行的低风险任务；
hermes gateway stop；- 在平台侧撤销或轮换 token；
- 检查 cron 是否仍把结果投递到旧入口；
- 发送新金丝雀，确认不会运行。
只删聊天里的 bot 不等于撤销 token，只停止 gateway 也不等于外部平台凭据失效。
什么时候才能接第二个平台
G01–G12 全部通过，且没有以下硬失败后再扩展：
- 未授权用户得到 Agent 回复；
- 普通用户拥有意外的管理命令；
- 回复发到错误 chat；
- 暂停期消息在恢复后意外执行；
- 错误回执泄露凭据；
- user 与 system 服务同时运行；
- 无法在一分钟内暂停入口并停止服务。
第二个平台要重复完整验收，不能因为它与第一个共用一个 Gateway 进程就跳过授权和投递负例。
完成检查
- 你能区分配置、进程、adapter 和端到端四层状态。
- 你在一个明确 profile 中完成了正常与未授权账号测试。
/whoami显示的命令层级符合预期。- 你验证了 pause 丢弃语义、重启后的 session 连续性和显式
/new。 - 你知道 paused-by-breaker 需要查因后手动恢复。
- 你完成了 Gateway、adapter 和平台 token 的停用路径。
如果首个入口选择 Telegram，下一步按 Hermes Telegram 接入实验 填完 T01–T12。如果结果要由 Cron 定时投递，再进入 Hermes Cron 自动化。