undermybelt Hermes Feishu gateway debugging
用时机：
- 用户说“飞书联系 Hermes 他不理我”
- 已配置 Feishu app 凭据，但无回复
hermes gateway status显示服务在跑，仍怀疑飞书未接入
目标
先判定故障层：
- Hermes 运行时未读到 Feishu 配置
- 平台未启用
- 旧 gateway 未重载新配置
- Feishu websocket/connect 失败
- 另一个本地 gateway 占用同一
app_id
步骤
- 验证 Hermes 运行时实际读到的 Feishu 环境变量，而非只看磁盘上的配置文件：
cd ~/.hermes/hermes-agent
. venv/bin/activate
python - <<'PY'
import os
from pathlib import Path
from hermes_cli.env_loader import load_hermes_dotenv
from hermes_constants import get_hermes_home
load_hermes_dotenv(hermes_home=get_hermes_home(), project_env=Path('~/.hermes/hermes-agent/.env').expanduser())
for k in ['FEISHU_APP_ID','FEISHU_APP_SECRET','FEISHU_DOMAIN','FEISHU_CONNECTION_MODE']:
v=os.getenv(k,'')
if 'SECRET' in k and v:
v=v[:4]+'***'+v[-4:]
print(k, bool(os.getenv(k)), v)
PY
- 看 gateway 常驻实例是否真在跑：
hermes gateway status
ps -p <PID> -o pid=,ppid=,etime=,command=
- 先查日志，不要只信 status：
grep -n "Feishu\|No messaging platforms enabled\|failed to connect any configured messaging platform" ~/.hermes/logs/gateway.log | tail -n 50
grep -n "Feishu\|No messaging platforms enabled\|failed to connect any configured messaging platform" ~/.hermes/logs/gateway.error.log | tail -n 50
- 若日志出现：
No messaging platforms enabled.
则结论优先为：当前常驻 gateway 进程启动时未载入 Feishu 配置；常见于配置后未重启、launchd 旧进程仍在跑。
- 若日志出现 Feishu 相关连接失败，再细分：
[Feishu] FEISHU_APP_ID or FEISHU_APP_SECRET not set→ env 未被进程读到[Feishu] lark-oapi not installed→ 缺依赖Unsupported FEISHU_CONNECTION_MODE→ 模式值错，只支持websocket/webhookAnother local Hermes gateway is already using this Feishu app_id→ 本机另一实例占锁Gateway failed to connect any configured messaging platform:→ 平台启用但连接失败
- 若怀疑是旧进程未重载配置，直接重启并验收：
cd ~/.hermes/hermes-agent
. venv/bin/activate
hermes gateway restart
- 验收标准：
tail -f ~/.hermes/logs/gateway.log
应看到近似：
[Feishu] Connected in websocket modeGateway running with 1 platform(s)
关键代码定位
~/.hermes/hermes-agent/gateway/config.py- Feishu 平台启用条件：
FEISHU_APP_ID+FEISHU_APP_SECRET
- Feishu 平台启用条件：
~/.hermes/hermes-agent/gateway/platforms/feishu.pyconnect()内含依赖、凭据、连接模式、app_id 锁检查
~/.hermes/hermes-agent/gateway/run.py- 若
connected_count == 0且enabled_platform_count == 0，会写：No messaging platforms enabled.
- 若
实战判据
若同时满足：
- 运行时 env 检查里
FEISHU_APP_ID/SECRET为真 hermes gateway status显示服务 loaded/running- 日志却写
No messaging platforms enabled.
则不要先怀疑用户消息格式；先判为“当前 launchd/gateway 进程未载入新 Feishu 配置”，重启 gateway 优先。
易错点
- 只看配置文件，不验证 Hermes 实际加载结果
- 只看
hermes gateway status，不看gateway.error.log - 自己再起一个
python -m gateway.run，却被已有 PID 挡住，误判为 Feishu 故障 - 误把 provider 429/timeout 当成飞书未接通；二者可并存，需分开看日志