Skip to content

Agent UX: show clear hint for missing provider API keys#31554

Closed
liuxiaopai-ai wants to merge 1 commit intoopenclaw:mainfrom
liuxiaopai-ai:codex/fix-model-auth-missing-key-hint
Closed

Agent UX: show clear hint for missing provider API keys#31554
liuxiaopai-ai wants to merge 1 commit intoopenclaw:mainfrom
liuxiaopai-ai:codex/fix-model-auth-missing-key-hint

Conversation

@liuxiaopai-ai
Copy link

@liuxiaopai-ai liuxiaopai-ai commented Mar 2, 2026

Summary

  • Problem: when a /model selection fails due to missing provider credentials, users see a long fallback-chain error blob that is hard to act on.
  • Why it matters: onboarding friction and confusion; users may not know the immediate next step.
  • What changed: detect No API key found for provider "..." failures and show a concise actionable hint (openclaw configure) in the user-facing final error text.
  • What did NOT change (scope boundary): no auth resolution logic changes, no provider fallback behavior changes, no retries added.

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

User-visible / Behavior Changes

  • Missing-provider-key failures now surface as:
    • Missing API key for provider "<provider>"
    • actionable next step: openclaw configure
  • This replaces only the generic final error text for that specific failure pattern.

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: local test env
  • Runtime/container: Node + Vitest
  • Model/provider: auth failure simulation
  • Integration/channel (if any): agent reply error path
  • Relevant config (redacted): N/A

Steps

  1. Mock model fallback to fail with No API key found for provider "anthropic".
  2. Run runReplyAgent path with onAgentRunStart callback.
  3. Assert final user text contains concise missing-key hint and configure guidance.

Expected

  • User-facing text is concise and actionable.

Actual

  • Test passes with new message shape.

Evidence

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

Human Verification (required)

  • Verified scenarios:
    • pnpm test src/auto-reply/reply/agent-runner.misc.runreplyagent.test.ts
    • pnpm format:check
  • Edge cases checked:
    • Existing non-auth error fallback path unchanged.
    • Existing context-overflow and role-ordering messages unchanged.
  • What you did not verify:
    • Full repo pnpm check (known unrelated existing failures in other areas).

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 4831cb36d.
  • Files/config to restore:
    • src/auto-reply/reply/agent-runner-execution.ts
    • src/auto-reply/reply/agent-runner.misc.runreplyagent.test.ts
    • CHANGELOG.md
  • Known bad symptoms reviewers should watch for:
    • Missing-key errors no longer include explicit provider hints.

Risks and Mitigations

  • Risk: regex match could miss variants of missing-key messages.
    • Mitigation: fallback keeps existing generic error text when pattern is not matched.

chatgpt-codex-connector[bot]
chatgpt-codex-connector bot reviewed Mar 2, 2026
View reviewed changes
Copy link

@chatgpt-codex-connector chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4831cb36d4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

src/auto-reply/reply/agent-runner-execution.ts
| { kind: "final"; payload: ReplyPayload };

function resolveMissingApiKeyProvider(message: string): string | null {
const match = message.match(/No API key found for provider "([^"]+)"/i);
Copy link

@chatgpt-codex-connector chatgpt-codex-connector bot Mar 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Restrict missing-key hint to direct auth failures

resolveMissingApiKeyProvider does an unanchored substring match against the entire error text, so it also matches fallback summaries that include a single No API key found... attempt among other failures; runWithModelFallback emits combined messages like All models failed ... | ..., which means a primary outage/other error can be misreported to users as a missing-key problem and send them to openclaw configure even though that won’t fix the run. Gate this path to direct single-attempt auth errors (or parse structured attempt reasons) before replacing the final message.

Useful? React with 👍 / 👎.

@greptile-apps
Copy link
Contributor

greptile-apps bot commented Mar 2, 2026

Greptile Summary

This PR improves the user experience when model selection fails due to missing provider API keys by showing a clear, actionable error message instead of a verbose fallback-chain error.

Changes made:

  • Added resolveMissingApiKeyProvider() function that extracts the provider name from "No API key found for provider" errors using regex
  • Updated error handling to detect missing API key errors and show: ⚠️ Missing API key for provider "{provider}". Run openclaw configure (or set the provider API key), then retry.
  • Updated test expectations to verify the new error message format

Implementation quality:

  • Regex pattern correctly matches the consistent error format used throughout the codebase
  • Proper null handling with optional chaining and fallback to generic error message
  • Defensive programming with trimming and empty string checks
  • No changes to auth resolution logic or provider fallback behavior

The change is well-scoped, improves onboarding UX, and maintains backward compatibility by only affecting the final user-facing error text.

Confidence Score: 5/5

  • This PR is safe to merge with minimal risk
  • The change is simple, well-tested, and only affects user-facing error messages without modifying any auth resolution or fallback logic. The regex pattern correctly matches the consistent error format used throughout the codebase, and proper defensive programming ensures graceful fallback to the generic error message if the pattern doesn't match.
  • No files require special attention

Last reviewed commit: 4831cb3

This was referenced Mar 2, 2026
Closed
Closed
Closed
Closed
Closed
Closed
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@chatgpt-codex-connector chatgpt-codex-connector[bot] chatgpt-codex-connector[bot] left review comments

Assignees

No one assigned

Labels

size: XS

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[Bug]: Warning Message When Selecting a Model with API KEY Not Configured is Not Helpful

2 participants

@liuxiaopai-ai @thewilloftheshadow