飞书或 Lark 设置与故障排查

适用场景

• 用户希望将 Hermes Agent 与飞书或 Lark 进行连接。
• 机器人在线但不回复消息。
• 需要诊断权限、网关状态或连接问题。

前置条件

• 已安装 Hermes Agent，且 hermes CLI 可用。
• 已创建具备机器人功能的飞书或 Lark 应用。
• 已获取所需的 App ID 和 App Secret。

权限控制提醒

飞书访问包含两层独立的控制：

• FEISHU_ALLOW_ALL_USERS
• GATEWAY_ALLOW_ALL_USERS

若网关层仍处于关闭状态，即使飞书层显示开放，飞书用户仍将被拒绝接入。

设置与故障排查流程

1. 确认配置正确。

检查必需的飞书或 Lark 变量是否已设置，且域名和连接模式与部署环境一致。

1. 确认网关正在运行。

hermes gateway status

1. 查看最近的日志。

hermes logs 2>&1 | grep -i feishu | tail -20

1. 测试消息发送。

发送一条直接消息，观察是否有入站消息日志，随后是否返回模型响应。

1. 配置更改后重启服务。

hermes gateway restart

常见问题

• 机器人完全无响应：网关未运行。
• 日志中出现 Unauthorized user：网关层级的允许规则仍在阻止访问。
• 区域或域名错误：FEISHU_DOMAIN 与实际部署环境不匹配。
• 消息到达但无回复：Hermes 后端的模型提供商或 API Key 出现故障。

安全注意事项

• 生产环境中建议使用白名单策略。
• 永远不要提交 App Secret，对密钥或验证令牌进行加密。
• 以权限受限的用户账户运行网关服务。
• 在对外分享日志前，检查是否存在敏感信息输出。