model-fallback-retry#

大模型 API 异常自动重试 + 多渠道消息回传队列管理

当 AI 模型调用遇到限速（429）、配额耗尽（2056）、服务过载（503）等异常时，自动将消息加入重试队列，通过定时任务自动重新发送，确保 零消息丢失。

---

解决的问题#

使用 OpenClaw 时，你是否遇到过：

• ❌ 消息发出去，AI 返回"已达到用量上限"或"429 Rate Limit"，消息就这样丢了
• ❌ API 临时限速，需要手动重发
• ❌ 配额耗尽后整个 agent 卡住
• ❌ 凌晨异常，醒来发现一整晚的消息都没响应

model-fallback-retry 就是来解决这些问题的。

---

架构#

text

┌─────────────────────────────────────────────────────────────┐
│  Plugin (index.mjs) - 常驻内存                              │
│                                                             │
│  三层异常检测：                                            │
│  Layer 1: errorCategory 拦截（rate_limit_error/quota_exhausted）│
│  Layer 2: HTTP Status Code 拦截（429/402/503）             │
│  Layer 3: 文本正则兜底（quota_error_patterns）              │
│                                                             │
│  命中任一层 → 写入 retry_queue.json (pending)             │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│  Cron 定时任务（每 30 分钟）                               │
│                                                             │
│  检查 retry_queue.json 中到期的 pending 消息               │
│  → sessions_send 发 [RETRY:id=xxx] 原始消息               │
│  → increment_retry() 指数退避计算下次重试时间              │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│  Agent 收到 RETRY 消息                                     │
│                                                             │
│  [RETRY:id=xxx] 用户原始消息                               │
│  → mark_completed(xxx) → 从 pending 移到 completed        │
│  → 用原始消息重新触发 AI 处理                              │
└─────────────────────────────────────────────────────────────┘

---

异常检测规则#

三层拦截机制#

层级触发条件说明Layer 1model_call_ended + errorCategoryOpenClaw 结构化字段，最可靠Layer 2model_call_ended + httpStatusHTTP 状态码（429/402/503）Layer 3agent_end + 文本正则匹配兜底，支持自定义 patterns

支持的 errorCategory#

errorCategory含义建议重试策略rate_limit_errorTPM/RPM 限速短间隔重试quota_exhausted配额耗尽长间隔重试overloaded_error服务过载短间隔重试billing余额不足不重试，只通知

支持的 HTTP Status Code#

Status含义429Rate Limit（限速）402Payment Required（配额耗尽）503Service Unavailable（服务过载）

文本正则 patterns#

当前默认 patterns：

json

"quota_error_patterns": [
  "Something went wrong while processing your request",
  "已达到 Token Plan 用量上限.*\\([0-9]+\\)",
  "Token Plan.*用量上限"
]

支持自定义：在 config.json 中添加更多正则表达式。

---

配置 (config.json)#

配置项说明默认值retry_interval_minutes重试检查间隔（分钟）30initial_wait_minutes首次重试等待时间30max_retry_count最大重试次数5intercept_on_error_categories拦截的 errorCategory 列表["rate_limit_error", "quota_exhausted"]``intercept_on_status_codes拦截的 HTTP 状态码[429, 402, 503]``quota_error_patterns文本正则匹配 patterns见上方clear_command清空指令#清空``status_command状态查询指令#队列状态

指数退避策略#

首次失败 → 等待 initial_wait_minutes 第2次 → initial_wait_minutes * 2 第3次 → initial_wait_minutes * 4 ...以此类推

例如 initial_wait_minutes = 30：

重试次数等待时间第1次30 分钟第2次60 分钟第3次120 分钟第4次240 分钟第5次480 分钟

---

队列格式 (retry_queue.json)#

json

{
  "pending": [{
    "id": "uuid",
    "sessionKey": "agent:dd:feishu:direct:ou_xxx",
    "originalMessage": "用户发送的原始消息",
    "errorOutput": "AI 返回的错误信息",
    "errorType": "quota_error",
    "sent_at": "2026-06-19T12:00:00Z",
    "retry_count": 0,
    "next_retry_at": "2026-06-19T12:30:00Z",
    "max_retry_count": 5,
    "initial_wait_minutes": 30
  }],
  "completed": [],
  "cleared": []
}

---

用户指令#

• #清空 - 清空当前用户所有待重试消息
• #队列状态 - 查看当前排队数量
• #清空 消息ID - 清空指定某一条

---

RETRY 消息格式#

当 Cron 定时任务检测到需要重试的消息时，会通过 sessions_send 发送：

text

[RETRY:id=abc-123] 用户原始消息内容

Agent 收到后：

1. 解析 msg_id = abc-123
2. 调用 mark_completed(abc-123) 从 pending 移到 completed
3. 用原始消息内容重新触发 AI 处理

---

安装#

bash

# 1. 安装 Skill 到 ~/.openclaw/skills/
cp -r model-fallback-retry ~/.openclaw/skills/

# 2. 重启 Gateway（让 Plugin 加载）
openclaw gateway restart

# 3. 配置 Cron 定时任务（使用 config.json 中的 cron 配置）
openclaw cron add \
  --name "model-fallback-retry-check" \
  --every 30m \
  --agent xiaoxiao \
  --to ou_50977b3a4ee416e61d71483e77bf3d09

# 4. 验证 Cron 是否配置成功
openclaw cron list

安装后必读#

config.json 中的 cron 配置项需要根据你的实际情况修改：

配置项说明你的值cron.agent执行重试的 Agent 名称xiaoxiao（默认）cron.notify_to失败通知的飞书/微信 ID需修改为你的 IDcron.interval_minutes检查间隔30（默认）

修改方法：编辑 ~/.openclaw/skills/model-fallback-retry/config.json 中的 cron.notify_to 为你的飞书/微信 ID。

注意：重试消息本身是动态发送到原始 session 的（不依赖此配置），此配置仅用于：

1. 指定哪个 Agent 执行重试检查
2. 失败通知发到哪里

版本#

当前版本： 1.0.0

---

Changelog#

1.0.0#

• 初始版本
• 支持三层异常检测（errorCategory / HTTP Status / 文本正则）
• 支持指数退避重试策略
• 支持多渠道（Feishu/WeChat 等）