接入消息网关和平台

Gateway（消息网关）会把 Hermes 从终端工具变成常驻远程入口。只要 Agent 有 terminal、file、browser、MCP、cron 或 send_message 权限，消息平台用户就可能远程触发真实动作——一条消息可能等价于一条 shell 命令。这页讲怎么把这件事做对。

官方资料：Messaging Gateway、Voice Mode、Gateway Internals、Sessions、Security、Slash Commands Reference。

Gateway 做什么

Hermes Gateway 是一个后台进程，负责：

• 接收 Telegram、Discord、Slack、WhatsApp、Signal、Email 等平台消息。
• 为每个 chat 维护 session。
• 把消息送入 AIAgent。
• 运行 cron scheduler。
• 处理 voice message、file、image、thread、typing、streaming 等平台能力差异。
• 把结果发回原平台。

这不是“换个聊天界面”。它是带权限的远程控制入口。

支持的平台

官方文档列出的 Gateway 入口覆盖很多平台：

不要一次接很多平台。先接一个最可控的平台，跑通 allowlist、/status、/stop、/reset 和低风险 background task，再复制到其他平台。

快速设置

hermes gateway setup

常用命令：

hermes gateway              # 前台运行
hermes gateway setup        # 交互配置平台
hermes gateway install      # 安装用户服务
hermes gateway start
hermes gateway stop
hermes gateway status

Linux system service 需要额外确认权限边界。不要因为能 sudo hermes gateway install --system 就默认这样部署。

安全默认值

Gateway 默认拒绝不在 allowlist、也没有通过 DM pairing 的用户。这是正确默认值，因为 bot 背后可能有 terminal 权限。

示例：

TELEGRAM_ALLOWED_USERS=123456789,987654321
DISCORD_ALLOWED_USERS=123456789012345678
EMAIL_ALLOWED_USERS=[email protected]
GATEWAY_ALLOWED_USERS=123456789,987654321

GATEWAY_ALLOW_ALL_USERS=true 不建议用于任何有 terminal、file、browser 或 MCP 写入能力的 bot。开放入口加高权限工具，是最危险组合。

DM pairing

如果不想手动收集 user id，可以用 DM pairing。未知用户私聊 bot 时拿到一次性 pairing code，管理员本地批准：

hermes pairing list
hermes pairing approve telegram XKGH5N7P
hermes pairing revoke telegram 123456789

pairing code 有过期时间、速率限制和随机性，但它不是权限审计替代品。批准前仍要确认用户是谁、应该拿到哪些平台和工具权限。

聊天内命令（slash commands）

消息平台里可以执行很多 slash command（按官方 Slash Commands Reference 当前列表为准；具体清单跟 toolset 和已装 skill 联动）：

• /new、/reset：开新会话或重置当前会话。
• /model：查看或切换模型。
• /retry、/undo：重试上一条或撤销。
• /status：查看当前 session 状态（任务进度、上下文用量等）。
• /stop：停止当前正在跑的任务（重要——有问题第一时间用这个）。
• /approve、/deny：处理危险命令审批（terminal 工具产生的高风险动作弹窗）。
• /compress、/usage、/insights：压缩历史、查看用量、得到行为洞察。
• /background <prompt>：启动独立后台任务，主聊天保持响应。
• /reload-mcp：重新加载 MCP server 配置。
• /<skill-name>：直接调用某个 skill。

这意味着消息平台用户不是"只能聊天"——他们在远程控制一个有工具、session 和后台任务能力的 agent。这个心智锚点 mismatch 是大部分 Gateway 安全事故的根源：用户和管理员都默认把它当聊天机器人来管。

Busy input：interrupt、queue、steer

默认情况下，agent 忙碌时收到新消息会 interrupt 当前任务。官方还提供两种模式：

• queue：当前任务结束后再运行下一条。
• steer：把跟进消息注入当前运行过程，等待下一次 tool call 后生效。

配置示例：

display:
  busy_input_mode: steer
  busy_ack_enabled: true

如果用户会连续发语音或碎片消息，默认 interrupt 可能导致任务频繁中断；但 queue/steer 也可能让上下文更难追踪。团队入口要统一选择一种模式。

Background session

/background 会启动独立 agent instance：

/background Check all servers in the cluster and report any that are down

关键边界：

• 背景任务有自己的 session。
• 它继承当前 gateway 的 provider、toolsets、reasoning 和路由配置。
• 主 chat 保持可交互。
• 结果回到发起任务的同一个 chat/channel。
• background session 不知道你当前 chat 的完整上下文，只接收 prompt。

适合 background 的任务：巡检、报告、研究、低风险批处理。不要把生产发布、删除数据、数据库迁移、权限变更直接后台化。

Session reset

Gateway session 会按策略重置，例如按每日固定时间或 idle minutes。团队使用时要明确 reset 策略，否则旧上下文可能影响新任务。

示例：

{
  "reset_by_platform": {
    "telegram": { "mode": "idle", "idle_minutes": 240 },
    "discord": { "mode": "idle", "idle_minutes": 60 }
  }
}

长任务要有标题、状态和恢复方式；短任务要能 /reset 清理上下文。

上线验收

上线前确认：

• CLI 本地 hermes 和 hermes --continue 已稳定。
• Gateway 只接入必要平台。
• allowlist 或 DM pairing 已启用。
• Bot token 没有进入仓库、截图、日志或群聊。
• /status、/stop、/reset 能工作。
• 低风险 /background 能完成并回到正确 chat。
• 群聊和 DM 使用不同 toolsets 或审批策略。
• 停止 Gateway 后平台入口不再接收任务。

常见坑

按事故频率从高到低：

• CLI 还不稳定就接 Gateway —— 故障来源至少多两层（平台 + Gateway 进程），定位时间指数增长
• allowlist 没设就上线 —— 任何人发消息都能命令你的机器；最坏情况一晚上被滥用到限流封号
• Bot token 写进仓库或截图 —— GitHub 推送扫描会泄露，截图分享到群里也跑不掉
• 群聊和 DM 共用一套宽权限 —— 群里人员变动，没及时收权限就出事
• 不知道 reset 策略，旧上下文污染新任务 —— 一个用户 4 小时前的危险任务影响下一次问候
• background 任务没有范围、停止条件和输出格式 —— 后台跑成无限循环，等用户回来才发现 token 烧完
• 把 /approve 当成形式流程，没看清实际命令 —— 高风险审批要逐条人脑审，不是机械点 yes

官方资料

• Messaging Gateway 总览 + 各平台子页
• Gateway Internals（路由 / 授权 / session 调度）
• Slash Commands Reference（完整命令列表）
• Voice Mode
• Sessions
• Security（命令审批、用户授权、容器隔离）

下一步