# 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会话隔离

---