Summary

当 primary 模型触发 rate_limit / billing / overloaded 时，OpenClaw 静默挂起 session 30 分钟，用户只感到"卡住"，看到的是 didSendViaMessagingTool=false + non_deliverable_terminal_turn，零提示。

本提案让 OpenClaw 在 fallback 触发时自动通过 channel 发送一条人话消息给用户，并在现有基础上保持 fallback 链立即尝试、context 自动透传。改动量 ~65 行纯增量，零删除。

Background

• Issue Followup agent silent-drops on billing/quota rejection (no user-facing notice) #80700：Followup agent silent-drops on billing/quota rejection（P1，OPEN）
• Issue /model switch + manual gateway restart don't reset provider cooldown; LLM idle timeout is mis-classified as a transient failure and poisons the fallback chain for the whole gateway process lifetime #91659：Cooldown set bug
• Issue user-switched model has no fallback chain, causing session deadlock on provider outage #84865：Provider cooldown
• 实际触发：2026-06-09 23:42 session bad20dda —— M3 rate_limit_error (2077500/2077500)，用户发"现在是哪个模型"，零回复零提示
• 完整调查：6/9–6/10 已做完根因链 + 3 个配置调整，但"用户层错误可见性"缺口未补

The Gap

FailoverError 在 embedded-agent.ts:2691 已经有人话消息：

throw new FailoverError(
  "The AI service is temporarily rate-limited. Please try again in a moment.",
  { reason: "rate_limit", provider: "minimax", model: "MiniMax-M3", suspend: true }
);

但这个消息只存在 error 对象里，从未被投递到 channel。

同时，message-lifecycle-refactor.md Phase 2 已经设计好了：

• MessageOrigin.kind === "gateway_failure" （已有）
• core.messages.send 完整 lifecycle：begin → render → send → commit → fail
• DeliveryFailureKind 已将 rate_limit 分类为可重试
• shouldDropOpenClawEcho 防 bot room 自循环

缺的只是一根线：把这根线从 FailoverError throw 点接到 core.messages.send。

Proposed Changes

4 files, ~65 lines, pure additive

Design

FailoverError thrown
  → notifyFailoverToUser({ session, failoverError })
    → humanizeFailoverError(err) → "⚠️ 主模型 MiniMax-M3 触发速率限制..."
    → core.messages.send(MessageOrigin.kind="gateway_failure", best_effort)
  → if (err.suspend) suspendSession(...)

Two call sites to instrument:

• embedded-agent.ts ~L3503: after prompt submission failover
• embedded-agent.ts ~L3827: after assistant call failover

New MessageOrigin codes

"model_rate_limited"      // rate_limit
"model_overloaded"        // overloaded
"model_billing_exhausted" // billing

FailoverError extension

class FailoverError extends Error {
  // ...existing fields...
  userMessage?: string;  // NEW: pre-constructed user-facing message
}

notifyFailoverToUser() prefers userMessage if set; falls back to auto-translating failoverError.reason.

Humanized messages (examples)

⚠️ 主模型 MiniMax-M3 触发速率限制（rate_limit），约 30 分钟后自动恢复。
⚠️ 主模型 MiniMax-M3 暂时过载，正在切换备用模型。
⚠️ 主模型 MiniMax-M3 账户配额用尽，约 30 分钟后自动恢复。

What This Does NOT Change

• ❌ Does NOT modify fallback chain logic（candidates[i+1] already tries immediately）
• ❌ Does NOT change suspendSession 30min wait
• ❌ Does NOT break session reuse（runEmbeddedAgent context passthrough already works）
• ❌ Does NOT modify model resolution or configuration
• ❌ No tests（per decision: avoid polluting openclaw environment）

Key Insight

The foundation already exists — both sides:

• FailoverError side：already has human-readable message string at throw site
• Message delivery side：core.messages.send already has full lifecycle + MessageOrigin.gateway_failure type

We're not building new infrastructure — we're connecting two things that already exist but aren't wired together.

Compatibility & Risk

Code References

• dist/failover-error-CmbjIKMV.js L24-61: FailoverError class + reason→status mapping
• dist/embedded-agent-CpxCz9I4.js L2691: throw FailoverError with human message
• dist/embedded-agent-CpxCz9I4.js L1781: fallback_model decision throw
• dist/embedded-agent-CpxCz9I4.js L3503, L3827: suspendSession call sites
• dist/model-fallback-D14rZfHX.js L1185-L1452: fallback chain nextCandidate
• dist/model-fallback-D14rZfHX.js L466: suspendSession implementation
• dist/delivery.runtime-ChtITtgt.js L83: didSendViaMessagingTool passthrough
• docs/concepts/message-lifecycle-refactor.md: Phase 2 durable send core design