——
OpenClaw iMessage 网关新增消息补全功能：5 个配置参数详解与实战指南
OpenClaw 最新版本（commit 81e0a1a）正式推出 inbound iMessage catchup 功能，彻底解决网关因崩溃、重启或 Mac 休眠导致的消息丢失问题。这一设计参考了已退役的 BlueBubbles 补全方案，并针对 imsg JSON-RPC 协议进行了深度优化。
本文将深入解析该功能的技术架构、5 个核心配置参数，以及生产环境的最佳实践。
—
为什么需要消息补全功能？
在之前的版本中，当 OpenClaw iMessage 网关 处于离线状态时，新到达的 iMessage 消息会直接写入 macOS 的 chat.db 数据库，但网关无法感知这些消息。这导致：
- AI Agent 漏接消息：用户发送的消息未被及时处理
- 对话上下文断裂：重启后 Agent 对离线期间的消息一无所知
- 用户体验受损：需要手动触发同步或重新发送消息
新的 catchup 功能通过 cursor + replay loop 机制，在网关恢复在线后自动扫描并回放遗漏的消息，确保零消息丢失。
—
核心架构：Cursor + Replay Loop + Monitor 三层设计
1. Cursor 状态持久化（extensions/imessage/src/monitor/catchup.ts）
每个 iMessage 账户的补全状态独立存储在
// 伪代码：cursor 文件结构示例
{
"accountId": "user@example.com",
"cursorRowId": 1528473, // 最后成功处理的消息 ID
"heldFailureRowId": null, // 被阻塞的失败消息（未达重试上限）
"watermarkRowId": 1528469, // 解析失败消息的最低水位线
"lastUpdated": "2024-01-15T09:23:17Z"
}
关键设计原则：
- Oldest-first 扫描：按时间顺序处理，保证消息时序正确
- 失败消息阻塞机制：当某条消息失败且未达
maxFailureRetries时，cursor 停留在failed.rowid - 1，禁止跳过后续消息（防止乱序） - Watermark 保护：解析失败的消息设置最低水位线，避免无限重试
2. Bridge 适配层（extensions/imessage/src/monitor/catchup-bridge.ts）
Bridge 层负责将历史消息转换为实时消息流：
// 核心流程：chats.list → messages.history → handleMessageNow
async function replayMessages(accountId: string, cursor: Cursor) {
// 1. 获取聊天列表（复用实时协议）
const chats = await imsgClient.chats.list({ modifiedSince: cursor.lastSyncTime });
// 2. 逐个聊天获取历史消息
for (const chat of chats) {
const messages = await imsgClient.messages.history({
chatId: chat.id,
afterRowId: cursor.cursorRowId,
limit: config.perRunLimit
});
// 3. 通过 handleMessageNow 分发，确保白名单/策略一致
for (const msg of messages) {
await handleMessageNow(msg, { source: 'catchup', originalRowId: msg.rowId });
}
}
}
关键特性：
- 复用实时消息的
handleMessageNow路径，白名单、群组策略、去重逻辑完全一致 - 当
perRunLimit截断批次时，cursor 自动钳位到最后分发的rowid
3. Monitor 集成（extensions/imessage/src/monitor/monitor-provider.ts）
// 启动时序：watch.subscribe → catchup.run → live dispatch loop
class IMessageMonitorProvider {
async start() {
await this.watch.subscribe(); // 建立实时连接
if (this.config.catchup?.enabled) {
await this.catchup.runOnce(); // 执行一次性补全（跳过 debouncer）
}
this.startLiveDispatchLoop(); // 进入实时消息循环
}
}
注意：补全阶段绕过入站 debouncer，确保每条历史消息都被串行处理。
—
5 个核心配置参数详解
在 channels.imessage.catchup 配置块中，所有参数均为可选且默认禁用：
{
"channels": {
"imessage": {
"catchup": {
"enabled": true, // 开关：默认 false（opt-in）
"maxAgeMinutes": 60, // 范围：1-720，默认 60
"perRunLimit": 100, // 范围：1-500，默认 100
"firstRunLookbackMinutes": 120, // 范围：1-720，默认 120
"maxFailureRetries": 10 // 范围：1-1000，默认 10
}
}
}
}
| 参数 | 作用 | 生产建议 |
|:—|:—|:—|
| enabled | 功能总开关 | 首次启用建议先在测试账户验证 |
| maxAgeMinutes | 单条消息的最大补全年龄 | 设置 720（12小时）覆盖典型 Mac 休眠场景 |
| perRunLimit | 单次运行最多处理消息数 | 根据 chat.db 大小调整，避免启动过慢 |
| firstRunLookbackMinutes | 首次启用时的回溯窗口 | 建议 ≥ maxAgeMinutes，确保历史消息被扫描 |
| maxFailureRetries | 单条消息失败重试次数 | 10 次足够；过高会阻塞后续消息过久 |
配置验证
OpenClaw 使用 AJV 进行运行时 schema 验证。更新配置后，可通过以下命令验证：
验证配置文件语法
openclaw config validate --schema=channel-config
查看 iMessage 通道的完整配置
openclaw config get channels.imessage --format=json
—
重要变更：Echo-Cache TTL 调整
为防止”自己发送的消息被重复识别为入站消息”，echo-cache 的 TTL 已从 2 分钟 延长至 12 小时：
// extensions/imessage/src/cache/echo-cache.ts
const ECHO_CACHE_TTL_MS = 12 60 60 * 1000; // 12 hours
这意味着：网关离线前你发送的出站消息，在 12 小时内重启不会被误判为新的入站消息。
—
从 BlueBubbles 迁移的注意事项
如果你之前使用 BlueBubbles 的补全功能，迁移时需关注以下差异：
| 特性 | BlueBubbles | OpenClaw iMessage |
|:—|:—|:—|
| 协议基础 | 私有 WebSocket API | imsg JSON-RPC |
| 消息获取 | /api/message/ | chats.list + messages.history |
| 失败处理 | 简单重试 | Cursor 阻塞 + Watermark 机制 |
| 策略一致性 | 补全与实时路径分离 | 统一 handleMessageNow |
迁移检查清单：
- [ ] 确认
chat.db文件权限（OpenClaw 需要读取权限） - [ ] 调整
maxAgeMinutes匹配原 BlueBubbles 的catchupWindow - [ ] 首次启用后监控
catchup/目录下的 cursor 文件生成
—
FAQ：常见问题解答
Q1: 启用 catchup 后，网关启动变慢正常吗？
正常。首次启动会扫描 firstRunLookbackMinutes 范围内的所有消息。建议：
- 生产环境先设置较小的
firstRunLookbackMinutes（如 30） - 待 cursor 建立后，逐步扩大至目标值
Q2: 如何确认补全功能正在工作？
查看日志中的关键指标：
openclaw logs --channel=imessage --grep="catchup" --follow
预期输出：
[INFO] catchup: replayed=1 fetchedCount=1 cursor=1528473
[INFO] catchup: agent reply observed, persisting cursor
Q3: 某条消息一直失败，会阻塞整个补全吗？
不会永久阻塞。当失败次数达到 maxFailureRetries 后，cursor 会跳过该消息并继续。被跳过的消息可通过以下方式处理：
- 手动检查
chat.db中对应rowid的消息内容 - 调整解析逻辑后，删除 cursor 文件重新触发补全
Q4: 可以针对特定聊天禁用补全吗？
当前版本不支持聊天级别的细粒度控制。但可通过 群组策略 实现类似效果：将特定聊天加入黑名单，补全消息会经过相同的策略检查。
Q5: 与实时消息相比，补全消息有延迟吗？
补全消息通过相同的 handleMessageNow 处理，业务逻辑延迟一致。唯一的额外开销是 chat.db 的批量读取，通常在毫秒级。
—
总结与下一步
OpenClaw iMessage inbound catchup 通过 cursor 持久化 + replay loop + 统一分发路径 的三层架构，实现了生产级的消息可靠性保障。关键要点：
1. Opt-in 设计：默认关闭，需显式启用并配置参数
2. 时序保证：Oldest-first + 失败阻塞机制确保消息顺序
3. 策略一致：补全与实时消息共用同一路径，无行为差异
建议下一步行动：
- 在测试环境启用并验证配置：OpenClaw iMessage 配置文档
- 查看完整代码变更：GitHub PR #79387
- 了解 BlueBubbles 迁移完整指南：OpenClaw 迁移文档
—
相关阅读
—
参考来源
