Summary

Describe the problem and fix in 2–5 bullets:

• Problem: /model can switch to a provider with no configured key, but the follow-up run failure shows a long multi-model fallback trace that is hard to act on.
• Why it matters: users cannot quickly tell which key is missing (for example Gemini) and what exact next step to take.
• What changed: added targeted user-facing error rewriting for missing-provider-API-key failures (including All models failed (...) summaries), with provider-specific key hinting (google -> GEMINI_API_KEY) and actionable openclaw agents add <id> guidance.
• What did NOT change (scope boundary): no auth resolution logic changed, no fallback order changed, no model-selection behavior changed.

Change Type (select all)

• Bug fix
• Feature
• Refactor
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes [Bug]: Warning Message When Selecting a Model with API KEY Not Configured is Not Helpful #31544
• Related Plugins: expose runtime.system.requestHeartbeatNow #31579

User-visible / Behavior Changes

• Missing API key failures now render concise actionable guidance instead of raw fallback traces.
• google/* missing-key errors now explicitly point to GEMINI_API_KEY.

Security Impact (required)

• New permissions/capabilities? (No)
• Secrets/tokens handling changed? (No)
• New/changed network calls? (No)
• Command/tool execution surface changed? (No)
• Data access scope changed? (No)
• If any Yes, explain risk + mitigation:

Repro + Verification

Environment

• OS: macOS
• Runtime/container: local dev checkout
• Model/provider: google + fallback chain sample
• Integration/channel (if any): TUI/webchat reply path
• Relevant config (redacted): default fallback setup

Steps

1. Trigger an auth-missing error text with No API key found for provider "google" (including fallback summary shape).
2. Run through runReplyAgent/user-facing sanitize path.
3. Verify rendered message content.

Expected

• User sees concise setup guidance that identifies provider and next action.

Actual

• Now shows Missing API key for provider "google". Set GEMINI_API_KEY ... or run openclaw agents add <id> ....

Evidence

Attach at least one:

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios: targeted unit tests for sanitize and runReplyAgent fallback copy.
• Edge cases checked: All models failed (...) summary containing multiple provider errors; direct missing-key message; OpenAI+Codex OAuth-specific missing-key wording path.
• What you did not verify: interactive TUI screenshot/manual walkthrough against a live keyless provider account.

Compatibility / Migration

• Backward compatible? (Yes)
• Config/env changes? (No)
• Migration needed? (No)
• If yes, exact upgrade steps:

Failure Recovery (if this breaks)

• How to disable/revert this change quickly: revert commit 9b03f573b.
• Files/config to restore: src/agents/pi-embedded-helpers/errors.ts, src/auto-reply/reply/agent-runner-execution.ts.
• Known bad symptoms reviewers should watch for: unexpectedly rewritten non-auth errors that mention API keys.

Risks and Mitigations

List only real risks for this PR. Add/remove entries as needed. If none, write None.

• Risk: over-matching could rewrite unrelated text that contains No API key found for provider.
  • Mitigation: rewrite only in errorContext path and kept regex scoped to provider-auth failure phrase.