You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
[Feature]: Emit first-class plugin hooks for model failover and terminal all-models-failed outcomes
Summary
Add first-class plugin hooks for model failover decisions and terminal "all models failed before reply" outcomes.
Problem to solve
OpenClaw already detects when a run fails over to another model and when a run collapses before reply because no usable model remains. Today those signals are mainly exposed through logs such as embedded_run_failover_decision and Embedded agent failed before reply: ....
That leaves a real automation gap:
alerting depends on polling or tailing gateway logs
plugins cannot react in-process to failover decisions
existing hooks like agent_end are too coarse to explain which model failed, whether fallback was attempted, or why the chain was exhausted
This is currently one part of the broader #65824 item about silent model fallback, but the hook/event gap is narrow enough to track separately.
Proposed solution
Add a dedicated plugin hook surface for:
model failover decisions during a run
terminal before-reply failures when no usable model remains
The goal is to let plugins and operators react to failover activity through structured in-process events instead of log parsing.
Alternatives considered
Keep relying on logs: works today, but it is brittle, delayed, and depends on parsing stderr text.
Reuse agent_end: too coarse, loses the actual failover chain and reason details.
Add more log lines only: improves observability but still does not create a real automation surface.
Impact
Affected: plugin authors, operators, alerting workflows, provider-health automation
Severity: annoying to workflow-blocking during provider outages
Frequency: intermittent but high-value when it happens
Consequence: silent failures, delayed alerts, brittle monitoring, poor user-facing explanations
Evidence/examples
OpenClaw already has the relevant internal seam:
structured failover logging in src/agents/pi-embedded-runner/run/failover-observation.ts
terminal before-reply failure logging in src/agents/pi-embedded-runner/run.ts
That means the runtime already knows the right facts. The missing piece is a first-class plugin/event surface.
#63821 asks for better failover observability via logs, which is related but weaker than a real hook surface
#61485 expands plugin hook capability in nearby lifecycle areas, showing precedent for growing the hook system
#64085 wants provider health / circuit-breaker behavior, which also benefits from structured failover events
Additional information
This issue is intentionally scoped only to the hook/event gap. It does not try to solve the other parts of #65824 item #1, such as non-verbose fallback notices or workspace-context re-injection.
[Feature]: Emit first-class plugin hooks for model failover and terminal all-models-failed outcomes
Summary
Add first-class plugin hooks for model failover decisions and terminal "all models failed before reply" outcomes.
Problem to solve
OpenClaw already detects when a run fails over to another model and when a run collapses before reply because no usable model remains. Today those signals are mainly exposed through logs such as
embedded_run_failover_decisionandEmbedded agent failed before reply: ....That leaves a real automation gap:
agent_endare too coarse to explain which model failed, whether fallback was attempted, or why the chain was exhaustedThis is currently one part of the broader
#65824item about silent model fallback, but the hook/event gap is narrow enough to track separately.Proposed solution
Add a dedicated plugin hook surface for:
The goal is to let plugins and operators react to failover activity through structured in-process events instead of log parsing.
Alternatives considered
agent_end: too coarse, loses the actual failover chain and reason details.Impact
Affected: plugin authors, operators, alerting workflows, provider-health automation
Severity: annoying to workflow-blocking during provider outages
Frequency: intermittent but high-value when it happens
Consequence: silent failures, delayed alerts, brittle monitoring, poor user-facing explanations
Evidence/examples
OpenClaw already has the relevant internal seam:
src/agents/pi-embedded-runner/run/failover-observation.tssrc/agents/pi-embedded-runner/run.tsThat means the runtime already knows the right facts. The missing piece is a first-class plugin/event surface.
Related references:
#65824meta issue, item fix: add @lid format support and allowFrom wildcard handling #1 explicitly notes there is no externally exposed fallback event for hooks#63821asks for better failover observability via logs, which is related but weaker than a real hook surface#61485expands plugin hook capability in nearby lifecycle areas, showing precedent for growing the hook system#64085wants provider health / circuit-breaker behavior, which also benefits from structured failover eventsAdditional information
This issue is intentionally scoped only to the hook/event gap. It does not try to solve the other parts of
#65824item #1, such as non-verbose fallback notices or workspace-context re-injection.