Hermes 多平台同源 — 完整手册

同一个 Hermes 实例，同时在 CLI、Telegram、Discord、Slack 等多个平台上工作。所有平台共享同一份会话和记忆。

一、核心概念

什么是"同源"

不是"多设备登录同一个账号"，而是：

你在 CLI 里：帮我把登录功能做了
                      ↓
Hermes 开始干活，会话进入"任务进行中"
                      ↓
你合上电脑，出门在地铁上打开 Telegram：
  给 Hermes bot 发：那个登录功能做完了吗？
                      ↓
Hermes 知道你在说哪个任务：
  "还在做，Worker B 在处理网络层，预计 5 分钟"

CLI 和 Telegram 看到的是同一个 Hermes、同一个会话、同一个状态。

架构

┌────────────────────────────────────────────────┐
│              Hermes Gateway                      │
│                                                  │
│   ┌────────┐  ┌──────────┐  ┌──────┐  ┌──────┐ │
│   │  CLI   │  │ Telegram │  │Discord│  │Slack │ │
│   └────┬───┘  └────┬─────┘  └──┬───┘  └──┬───┘ │
│        │           │           │         │      │
│   ┌────┴───────────┴───────────┴─────────┴────┐ │
│   │         统一路由层 + 会话管理               │ │
│   └────────────────┬──────────────────────────┘ │
│                    │                            │
│   ┌────────────────┴──────────────────────────┐ │
│   │      共享记忆 + 共享 Skills + 共享看板      │ │
│   └───────────────────────────────────────────┘ │
└──────────────────────────────────────────────────┘

二、配置步骤

第一步：安装 Gateway 依赖

Gateway 需要长期运行的后台服务。

# 安装为系统服务（macOS launchd / Linux systemd）
hermes gateway install

第二步：交互式配置

hermes gateway setup

这是一个向导，会依次问你：

? 是否启用 Telegram？(y/N)
? 输入 Telegram Bot Token：123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
? 是否启用 Discord？(y/N)
? 输入 Discord Bot Token：...
? 是否启用 Slack？(y/N)
...

配置完成后写入 ~/.hermes/config.yaml。

第三步：启动 Gateway

# 后台服务（推荐）
hermes gateway start
hermes gateway status      # 确认运行中

# 或前台运行（看实时日志）
hermes gateway run

# 停止
hermes gateway stop

三、各平台详细配置

Telegram

步骤：

1. 打开 Telegram，搜索 @BotFather
2. 发送 /newbot，按提示创建 bot，取名
3. BotFather 给你一个 token：123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
4. hermes gateway setup → 选 Telegram → 填入 token
5. 在 Telegram 里找到你的 bot，点 Start

配置项：

telegram:
  require_mention: false        # 群聊里要不要 @bot 才回复
  free_response_channels: ''     # 哪些频道不用 @ 也能触发
  allowed_chats: ''              # 只允许这些聊天使用（空=全部）
  reactions: false               # 给消息加 emoji 反应
  channel_prompts: {}            # 不同频道设置不同的 prompt
  extra:
    rich_messages: false         # 是否支持富文本（按钮、卡片等）

Discord

1. 去 https://discord.com/developers/applications 创建应用
2. 创建 Bot，复制 token
3. 在 OAuth2 → URL Generator 勾选 bot → 生成邀请链接
4. 把 bot 邀请到你的服务器
5. hermes gateway setup → 选 Discord → 填入 token

配置项：

discord:
  require_mention: true          # 需要 @Hermes 才回复
  auto_thread: true              # 自动建线程（避免刷屏）
  thread_require_mention: false  # 线程里也要 @ 才回复
  history_backfill: true         # 恢复会话时拉取最近消息
  history_backfill_limit: 50     # 拉取最近 50 条
  reactions: true                # 给消息加 emoji
  dm_role_auth_guild: ''         # 仅某个角色的用户能 DM bot
  allowed_channels: ''           # 只在这些频道工作（空=全部）
  server_actions: ''             # 是否允许 bot 管理服务器
  channel_prompts: {}            # 不同频道不同 prompt

Slack

# 先生成 manifest 文件
hermes slack manifest
# 输出一个 JSON，到 Slack API 后台创建 app 时用

配置项：

slack:
  require_mention: true
  free_response_channels: ''     # 这些频道不用 @ 也能触发
  allowed_channels: ''           # 只在这些频道工作
  channel_prompts: {}

WhatsApp

hermes whatsapp                 # WhatsApp 个人号集成
hermes whatsapp-cloud           # WhatsApp Business API

四、跨平台使用技巧

1. CLI 和手机交替工作

在 CLI 里发起任务：
  $ hermes chat
  > 重构战斗系统状态机

出门后继续：
  打开 Telegram → 给 bot 发消息
  "做完了吗？"
  → Hermes 回复进度
  "把伤害计算公式改成百分比"
  → Hermes 更新任务规格

回到电脑前：
  CLI 里继续上下文
  $ hermes chat
  # 自动恢复上次会话

2. 不同平台设不同角色

channel_prompts:
  telegram:
    "Work Chat": "你是一个简洁的技术助手，只说要点"
    "闲聊": "你是一个轻松友好的聊天伙伴"
  discord:
    "bug-reports": "你是一个专业的 QA 工程师"

3. 手机端快速指令

Telegram/Discord 上给 bot 发简短指令：

/status         → 当前在看板上有什么任务
/tasks          → 我有哪些未完成的任务
/summary        → 当前项目进度摘要
/kanban ls      → 列出看板任务

这些是 Hermes 内置的 slash commands，Gateway 自动注册。

五、Gateway 管理

# 服务管理
hermes gateway start             # 启动
hermes gateway stop              # 停止
hermes gateway restart           # 重启
hermes gateway status            # 查看状态
hermes gateway run               # 前台运行（调试用）
hermes gateway install           # 安装为系统服务
hermes gateway uninstall         # 卸载系统服务

# 查看所有 profiles 的 gateway 状态
hermes gateway list

# Gateway 日志
hermes logs                      # 查看 Hermes 日志

六、注意事项

Gateway 需要长期运行

• 建议装在服务器或长期开机的机器上
• 用 hermes gateway install 装成系统服务（自动开机启动）
• 你的 MacBook 合盖后 Gateway 会断

各平台需要的 token

安全建议

security:
  allow_private_urls: false      # 禁止 bot 访问内网资源
  redact_secrets: true           # 日志中隐藏敏感信息

七、常见问题

Q: 为什么 Telegram 上发了消息没反应？ A: Gateway 没运行。检查 hermes gateway status。

Q: CLI 和 Telegram 上看到的状态不一致？ A: CLI 是直接连接，Telegram 通过 Gateway 转发。检查 Gateway 日志是否有错误：hermes gateway run 看实时输出。

Q: 能不能在飞机上离线用？ A: 不能。Hermes 需要网络连接 LLM API。Gateway 也需要网络。