📡 05-接入一个消息平台（推荐飞书）LCP

到这一页时，你应该已经在命令行里把 Hermes 用顺了。现在再把它接进消息平台，排错会简单很多，也更容易真的放进日常工作流。

如果你前面的 CLI 使用还不顺，先回上一页：

• 04-常用 Skills（按日常使用场景精选）

🎯 这页做完以后，你应该得到什么

完成这页后，你应该能确认 4 件事：

1. 你已经知道为什么先接飞书
2. 你已经准备好接入前提
3. 你已经完成一次 Feishu / Lark 的基础配置
4. 你已经在飞书里看到一条真实回复

注意：

• 配置看起来对，不算通过
• 真正在飞书里收到一条回复，才算通过

❓ 为什么平台接入放到现在，而不是更前面

原因很直接：

• 你先在 CLI 跑通，排错层次最少
• 你先学会日常使用，再接入消息流，不容易两边一起乱
• 如果现在连命令行都还不稳，平台接入只会把问题再多包一层

所以这页的前提非常明确：

• 先把 CLI 跑顺
• 再把 Hermes 带进消息平台

✅ 第一步：接入前先确认这 5 个前提

开始前先只检查这 5 件事：

1. Hermes 已经能在命令行里正常回复
2. 你有可登录的飞书账号
3. 你准备创建或管理一个飞书应用
4. 你有一台可以持续运行 Hermes 的环境
5. 你知道这次是先跑最小验证，不是一次做完所有团队治理

如果这 5 条有任何一条还没成立，先不要往下配。

为什么这一步重要：

• 平台接入最常见的误区不是命令不会输
• 而是前提没齐，就急着配

🇨🇳 第二步：为什么第一推荐是飞书

第一站先选飞书，主要因为：

• 更符合国内团队日常协作习惯
• 更适合办公和消息流场景
• Hermes 已经提供清晰的 setup 向导
• 先用 websocket 起步，通常更稳、更容易跑通第一条消息

你现在不用把飞书理解成“唯一平台”。 只要把它理解成：

• 当前最适合中文团队先完成第一条消息闭环的平台入口

🧰 第三步：先跑交互式配置向导

执行：

hermes gateway setup

进入向导后，按顺序做：

1. 选择平台：Feishu / Lark
2. 选择连接模式：优先选 websocket
3. 按提示填写 App ID、App Secret 等必要信息
4. 如果弹出登录或扫码步骤，就按提示完成
5. 保存配置

为什么先用 setup：

• 它会帮你把能自动处理的步骤先处理掉
• 比起手动从空白 .env 开始更不容易漏项

成功标志：

• 向导顺利走完
• 你知道自己选的是 Feishu / Lark + websocket
• Hermes 已经保存了消息平台相关配置

如果 setup 没走通，先查：

1. 当前 Hermes 安装是否正常
2. 你是否在正确环境里执行
3. 飞书应用信息是否准备齐全

🔐 第四步：必要时检查 .env 里的关键字段

如果你需要手动核对配置，至少确认这些字段已经正确写入当前 Hermes 使用的 .env：

FEISHU_APP_ID=cli_xxx
FEISHU_APP_SECRET=***
FEISHU_DOMAIN=feishu
FEISHU_CONNECTION_MODE=websocket

如果你已经准备好了访问限制或通知目标，还可以继续补：

FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy
FEISHU_HOME_CHANNEL=oc_xxx

这几个字段分别在做什么：

• FEISHU_APP_ID / FEISHU_APP_SECRET：让 Hermes 能代表这个飞书应用工作
• FEISHU_DOMAIN=feishu：国内飞书通常先用这个默认值
• FEISHU_CONNECTION_MODE=websocket：第一次本机或内网验证时更稳
• FEISHU_ALLOWED_USERS：限制哪些用户可以先使用
• FEISHU_HOME_CHANNEL：后续做通知、cron 或 Home Chat 时更方便

如果你以前试过 webhook，先不要和 websocket 混着排查。 第一次上手建议先把 websocket 单独跑通。

▶️ 第五步：前台启动 gateway，先看它能不能稳定跑起来

执行：

hermes gateway run

为什么这里先用 run：

• 你现在是在做第一次验证
• 前台运行最方便直接看日志和报错
• 一旦立刻退出，你马上就知道问题还在接入这一层

你现在要重点确认 3 件事：

• 进程没有一启动就退出
• 没有马上出现凭证缺失、配置缺失这类致命报错
• gateway 处于可继续接收消息的状态

如果它启动后立刻退出，先查：

1. .env 里关键信息是否齐全
2. App ID / Secret 是否填错
3. 连接模式是否与你当前配置一致
4. 你是不是在错误的 profile 或错误环境里启动了 gateway

💬 第六步：一定要用真实消息做最终验收

最后一步不要停在“服务启动了”。 你必须去飞书里发一条真实消息，例如：

• 你好，Hermes
• 请用一句中文确认你已经接入飞书成功

你最终想看到的是：

• 你在飞书里发出消息
• Hermes 在飞书里返回一条可读回复

如果是群聊场景，再顺手确认：

• 是否需要 @ 机器人后才回复
• 回复范围是否符合你的预期

真正通过标准只有一个：

• 平台里出现一次真实、可读、可复现的机器人回复

🛠 如果已经配完但飞书里没回复，先按这个顺序排查

情况 1：hermes gateway setup 正常，但 hermes gateway run 立刻退出

先查：

1. FEISHU_APP_ID 和 FEISHU_APP_SECRET 是否真的写进当前环境
2. 连接模式是不是 websocket
3. 当前环境是否能正常读取 .env

情况 2：gateway 在跑，但飞书里发消息没反应

先查：

1. 飞书应用配置是否真的生效
2. 你发消息的用户是否在允许列表中
3. 你测试的是私聊还是群聊，触发方式是否正确

情况 3：你收到的是报错，而不是正常回复

先查：

1. Hermes CLI 本身是否还能正常工作
2. 默认模型和 provider 是否仍然可用
3. 飞书接入只是消息壳，模型层如果坏了，平台里也不会正常回答

排查时先坚持一个原则：

• 一次只改一层
• 先修配置，再重发一条真实消息验证

🚫 这一页先不要做的 4 件事

第一次平台接入时，先不要：

1. 一口气把所有消息平台都配上

• 先把飞书这一条最小闭环跑通

1. 把 websocket 和 webhook 混在一起排查

• 先固定 websocket，跑通再说

1. 服务还没回复，就先研究运维和团队治理细节

• 先拿到第一条真实回复

1. 看到 gateway 启动就默认成功

• 以平台里收到消息回复为准

✅ 这一页什么时候算通过

当下面这些事已经成立，这一页就通过：

• 你知道为什么平台接入放在现在做
• 你已经检查过飞书接入前提
• 你已经用 hermes gateway setup 完成基础配置
• 你已经用 hermes gateway run 跑起 gateway 做前台验证
• 你已经在飞书里看到一次真实正常回复

➡️ 下一步

完成后进入：

• 03-玩出花样

如果你想先回到上一阶段入口重新确认位置：

• 02-开始上手