Draft GitHub Issue — Surface raw provider errors in UI/logs when OpenClaw rewrites assistant error text

Summary

When a provider error occurs, OpenClaw can preserve the raw provider message in the session transcript while showing a much less useful message in the Control UI / operator-facing surfaces.

In today's incident, a long-lived Discord thread on openai/gpt-5.4 hit an OpenAI TPM limit. The transcript preserved the full provider error:

Rate limit reached for gpt-5.4 ... on tokens per min (TPM): Limit 500000, Used 375783, Requested 170059. Please try again in 5.501s.

But the operator-facing experience did not surface that actionable detail. That cost a lot of debugging time because the UI/log view looked generic enough to suggest a broader outage rather than a concrete TPM failure.

This feels like the wrong tradeoff for operator surfaces. Friendly end-user copy is fine, but the raw provider error should still be visible somewhere obvious.

Environment

• OpenClaw: 2026.3.24
• Platform: macOS 26.3.1 (arm64)
• Node: 25.6.1
• Active model at failure: openai/gpt-5.4
• API path: OpenAI Responses
• Surface in use: Discord thread lanes + Webchat / Control UI

Concrete case

Affected session artifact showed:

• contextTokens: 272000
• totalTokens: 166009
• transcript assistant message with:
  • stopReason: "error"
  • errorMessage: "Rate limit reached for gpt-5.4 in organization ... on tokens per min (TPM): Limit 500000, Used 375783, Requested 170059. Please try again in 5.501s. ..."

This exact provider detail was available in the transcript/session artifact but was not surfaced clearly enough in the operator-facing experience.

Expected behavior

When a provider returns a concrete error message (especially for rate limits, auth failures, billing failures, or request rejections), OpenClaw should do both:

1. provide a friendly user-facing summary if desired
2. preserve and surface the raw provider error in an obvious operator-visible place

Good examples:

• visible expandable “raw provider error” block in Control UI
• operator log line including the raw provider message and request id
• lifecycle/event payload carrying both:
  • friendlyError
  • rawProviderError

Actual behavior

• transcript/session artifact preserved the actionable TPM string
• operator-facing UI/log experience did not surface that same detail clearly
• result: debugging started from a misleadingly generic symptom instead of the real provider failure

Why this matters

For operators, these are not cosmetic details.

A raw provider error often immediately answers:

• was this rate-limit vs outage vs auth vs billing?
• was it request-size / TPM / RPM?
• what cooldown did the provider recommend?
• was there a request id to correlate upstream?

In this case, surfacing the raw TPM error would have saved roughly 45 minutes of unnecessary incident triage.

Likely relevant implementation area

From local inspection of the installed bundle, it appears OpenClaw intentionally rewrites some assistant errors into friendly/safe copy before emitting them to UI-facing payloads.

Examples observed locally in the bundled runtime:

• recognized rate-limit errors can be rewritten to:
  • ⚠️ API rate limit reached. Please try again later.
• embedded run payload building appears to prefer a friendly/safe error string instead of always exposing the raw provider message

That seems reasonable for end-user polish, but there should still be an operator-visible raw field.

Suggested fix

Minimum acceptable fix

Add a raw provider error field alongside friendly text wherever final run errors are surfaced.

For example:

• friendlyError: ⚠️ API rate limit reached. Please try again later.
• rawProviderError: Rate limit reached for gpt-5.4 ... Limit 500000, Used 375783, Requested 170059. Please try again in 5.501s.

Better fix

In Control UI, render:

• friendly summary by default
• collapsible diagnostics section with:
  • raw provider error
  • provider/model
  • response/request id if present
  • HTTP status if known

Related issues

Possibly adjacent / same family:

• #54417 — Subagent errors (e.g. 429 Rate Limit) are not surfaced to user, messages appear to be swallowed
• #48603 — [Feature]: API rate limit reached. Please try again later.
• #36142 — Silent empty response when LLM rate limit hits mid-turn (after tool calls)

Workaround today

Current workaround is ugly:

• inspect session .jsonl artifacts directly
• compare transcript error fields against UI behavior
• infer the real cause manually

That is workable for forensics, but it is not acceptable as the primary operator experience.

Nice-to-have

If OpenClaw wants to keep end-user surfaces clean, consider a config/role split such as:

• normal chat surfaces → friendly error only
• operator/admin/control surfaces → friendly error + raw provider diagnostics