Learnings Log

记录学习、改进和最佳实践。

[LRN-20260316-001] best_practice

Logged: 2026-03-16T07:20:00+08:00
Priority: high
Status: resolved
Area: infra

Summary

飞书 Webhook 超时导致消息重复投递问题及解决方案

Details

问题现象：
- 收到用户未主动发送的消息（05:40 消息在 06:23 再次出现）
- 消息内容完全一致但消息ID不同（om_x100b545876a2ed34c3d91545d8feb5f vs 新ID）
- 触发对话意外延续

根因分析：
飞书事件订阅规则要求 3秒内必须返回HTTP 200，否则触发重试：
- 重试间隔：15秒 → 5分钟 → 1小时 → 6小时（最多4次）
- 由于超时未响应，飞书服务器重复投递了消息

解决方案：
修改 openclaw.json 配置：
json "feishu": { "connectionMode": "websocket", // 使用长连接替代HTTP webhook "timeout": 2000, // 响应超时<3000ms "idempotent": true, // 开启幂等去重 "sessionMode": "per-chat" // 按会话隔离 }

Suggested Action

1. 监控网关响应时间，确保<3000ms
2. 优先使用 websocket 连接模式
3. 开启幂等性配置自动过滤重复 event_id
4. 识别重复消息特征：相同内容、不同消息ID、间隔符合重试规则

Metadata

• Source: user_feedback
• Related Files: ~/.openclaw/openclaw.json
• Tags: feishu, webhook, timeout, retry, websocket
• Pattern-Key: infra.feishu_webhook_timeout

Resolution

• Resolved: 2026-03-16T07:20:00+08:00
• Action: 已更新 openclaw.json 配置，用户已重启网关
• Notes: 配置已添加 websocket 模式、2000ms超时、幂等去重、per-chat会话隔离