Closes #97313

Summary

Fixes an issue where Z.AI users could rotate credentials or run setup/doctor repair, but sub-agents and embedded model auth would still try a stale stored zai:default auth profile whose API-key value was accidentally saved as an openclaw onboard ... --auth-choice ... command. That made the bad profile look usable, so auth selection could prefer it over current env/config credentials and produce Z.AI 401s.

• Fix classification: root-cause auth-profile credential eligibility fix with input-boundary prevention.
• Maintainer-ready confidence: high; the patch covers the stored-profile consumer boundary, explicit profile lookup, doctor health reporting, interactive provider setup input, CLI provider option input, and non-interactive API-key flag input.
• Root cause: command text saved in an API-key credential was treated like a valid static API key because stored profile eligibility only checked whether a string existed.
• Why this is root-cause fix: the root invariant is that an auth profile is eligible only when its credential can actually be used by the provider resolver. This fix moves the malformed command check to that source eligibility predicate, so every downstream resolver/doctor consumer sees the same invalid state instead of each path masking a bad profile separately; setup/onboarding input validation reuses the same source classifier to prevent reintroducing the same malformed state.
• Patch quality notes: the new return null branches are explicit fail-closed paths for malformed explicit profile and non-interactive flag inputs after emitting a user-facing diagnostic, so the caller stops before using command text as provider auth. The return undefined branch in option handling preserves the existing “this option did not apply” contract for unmatched provider options and is not a fallback for malformed matching options. The test prompter cast stays local to the doctor-auth test fixture because the test only exercises the prompt methods used by that doctor path.

Linked context

• Issue: Z.AI provider sub-agent auth fails with stale auth profile cache after key rotation / doctor --fix #97313
• Related open PR / same-contract scan: this update is scoped to the current PR and the auth-profile/API-key contract for Z.AI provider sub-agent auth fails with stale auth profile cache after key rotation / doctor --fix #97313; no public comparison with other PRs is included here.
• Out of scope: no schema migration, provider catalog change, OAuth/token credential behavior change, keyRef/SecretRef handling change, or broad command parser is added.

What Problem This Solves

Fixes an issue where users who accidentally saved an OpenClaw onboarding command as a Z.AI API key could still see sub-agent or embedded model auth use that stale stored profile after credential rotation or setup/doctor repair. The expected recovery path is that current env/config credentials can take over and doctor points to the malformed stored profile instead of letting it masquerade as usable auth.

• Why it matters / User impact: users can recover from the malformed zai:default profile without deleting all auth state, and future setup/onboarding attempts reject the command text before it is stored or sent to provider endpoint detection.
• Behavior or issue addressed: command-shaped API-key profile values are treated as malformed, skipped for auth resolution, surfaced in doctor health, and rejected from provider setup/onboarding API-key input paths.

Why This Change Was Made

This treats command-shaped API-key profile values as malformed at the shared auth-profile eligibility boundary. Stored malformed profiles are skipped during provider auth selection and explicit profile resolution, doctor surfaces them as missing [malformed_api_key], and provider setup/onboarding input validation rejects pasted onboarding commands before they can be persisted or used.

• Architecture / source-of-truth check: the source of truth is stored credential eligibility, because the same saved profile is consumed by sub-agent auth selection, explicit profile resolution, and doctor health. Provider setup, CLI option, and non-interactive flag checks reuse that same detector so prevention and recovery classify the same malformed shape consistently.
• What did NOT change: ordinary API-key strings, token credentials, OAuth credentials, keyRef, SecretRef, env fallback, config fallback, and provider precedence for healthy stored profiles are unchanged. This is only a narrow malformed-command boundary and does not change schemas, migrations, provider catalogs, or unrelated auth flows.
• Risk labels considered: auth-provider, compatibility, session-state, and security-boundary.
• Risk explanation: the change tightens auth-provider/profile eligibility and setup input validation, but only for OpenClaw onboarding command text containing --auth-choice, including documented non-interactive forms with intervening flags.
• Why acceptable: a literal openclaw onboard ... --auth-choice ... command is not a valid provider API key, and leaving it eligible causes the reported Z.AI 401 recovery failure; the detector deliberately stays narrower than general shell-command detection to avoid rejecting normal secrets.

Compatibility/risk boundary: the new malformed check is intentionally narrow to OpenClaw onboarding command text containing --auth-choice, including documented non-interactive forms where other flags appear before --auth-choice. It does not change normal API-key, token, OAuth, keyRef, or SecretRef handling. This PR keeps the behavior in shared auth-profile eligibility because the poisoned value is consumed by multiple paths: sub-agent auth selection, explicit profile lookup, doctor health, and provider setup/onboarding input.

User Impact

Users who accidentally persisted an onboarding command in zai:default can recover without manually deleting all auth state: current env/config Z.AI credentials are allowed to take over, and openclaw doctor now tells them exactly which profile is malformed and what to paste instead. Future setup/onboarding attempts reject command text at input time.

Real behavior proof

• Exact steps or command run after this patch: a redacted local OpenClaw doctor/auth proof used an isolated temporary agent auth store, saved a fake malformed zai:default API-key profile through OpenClaw's auth-profile store helper, loaded the real doctor/auth modules, built the health summary, and ran noteAuthProfileHealth with keychain prompts disabled.

• Evidence after fix (redacted local OpenClaw doctor/auth path): Validation real-doctor-auth-proof (pass, exit_code=0):

  OpenClaw doctor/auth proof: isolated temp auth store with malformed Z.AI profile
  Profile under test: zai:default
  Stored value shape: openclaw onboard --non-interactive --auth-choice=zai-coding-global --zai-api-key $ZAI_API_KEY
  Auth source detected: true
  Loaded profile type/provider: api_key/zai
  Health summary: zai:default: missing [malformed_api_key]
  Doctor note output:
  │
  ◇  Model auth ────────────────────────────────────────────────────────────╮
  │                                                                         │
  │  - zai:default: missing [malformed_api_key] — Paste the API key value,  │
  │    not an OpenClaw onboarding command.                                  │
  │                                                                         │
  ├─────────────────────────────────────────────────────────────────────────╯
  

• Observed result after fix: the malformed static Z.AI profile is loaded from the auth store, classified as missing [malformed_api_key], and surfaced by the doctor auth output with the direct remediation hint instead of being treated as usable auth.

• What was not tested: no real Z.AI credential was used and no live provider request was sent; the proof intentionally uses a fake command-shaped value and isolated temp auth store to avoid exposing credentials or touching user auth state.

Tests and validation

• Target test file: src/agents/auth-profiles/credential-state.test.ts, src/plugins/provider-auth-input.test.ts, src/commands/onboard-non-interactive/api-keys.test.ts, src/agents/model-auth.profiles.test.ts, src/agents/auth-health.test.ts, and src/commands/doctor-auth.profile-health.test.ts.

• Scenario locked in: documented openclaw onboard --auth-choice ... and openclaw onboard --non-interactive ... --auth-choice=... --zai-api-key ... command variants are rejected as malformed API keys; malformed stored Z.AI profiles are skipped in favor of current env auth; doctor prints missing [malformed_api_key]; CLI option and non-interactive flag inputs reject command-shaped values before storing or returning them.

• Why this is the smallest reliable guardrail: the tests pin both recovery and prevention boundaries without adding provider-specific branches beyond the shared malformed-command classifier.

• CLI API-key option and non-interactive flag regression tests: node scripts/run-vitest.mjs src/plugins/provider-auth-input.test.ts src/commands/onboard-non-interactive/api-keys.test.ts --reporter=verbose

  [test] passed 2 Vitest shards in 27.37s
  src/commands/onboard-non-interactive/api-keys.test.ts: 7 tests passed
  src/plugins/provider-auth-input.test.ts: 20 tests passed
  

• Focused auth regression tests: node scripts/run-vitest.mjs src/agents/auth-profiles/credential-state.test.ts src/plugins/provider-auth-input.test.ts src/commands/onboard-non-interactive/api-keys.test.ts src/agents/model-auth.profiles.test.ts src/agents/auth-health.test.ts src/commands/doctor-auth.profile-health.test.ts --reporter=verbose

  [test] passed 4 Vitest shards in 63.04s
  src/agents/auth-profiles/credential-state.test.ts: 15 tests passed
  src/commands/doctor-auth.profile-health.test.ts and src/commands/onboard-non-interactive/api-keys.test.ts: 13 tests passed
  src/agents/model-auth.profiles.test.ts and src/agents/auth-health.test.ts: 88 tests passed
  src/plugins/provider-auth-input.test.ts: 20 tests passed
  

• Format check: pnpm exec oxfmt --check src/agents/auth-profiles/credential-state.ts src/agents/auth-profiles/credential-state.test.ts src/plugins/provider-auth-input.ts src/plugins/provider-auth-input.test.ts src/commands/onboard-non-interactive/api-keys.ts src/commands/onboard-non-interactive/api-keys.test.ts src/agents/auth-health.ts src/agents/auth-health.test.ts src/agents/auth-profiles/oauth.ts src/agents/model-auth.profiles.test.ts src/commands/doctor-auth.ts src/commands/doctor-auth.profile-health.test.ts

  All matched files use the correct format.
  Finished in 176ms on 12 files using 8 threads.
  

• Test typecheck: pnpm check:test-types

  $ pnpm tsgo:test
  $ pnpm tsgo:core:test && pnpm tsgo:extensions:test
  

Risk checklist

• Auth-provider risk: limited to static API-key values matching OpenClaw onboarding command text with --auth-choice; healthy stored profiles and env/config fallbacks are unchanged.
• Compatibility risk: a saved profile whose key is literally an OpenClaw onboarding command becomes ineligible and visible in doctor as malformed; that is the intended recovery behavior for Z.AI provider sub-agent auth fails with stale auth profile cache after key rotation / doctor --fix #97313.
• Security-boundary risk: the PR avoids printing or persisting real credentials in proof, keeps malformed command text out of provider endpoint probing, and does not expand accepted secret formats.
• Session-state risk: no auth store schema or migration changes are introduced; only eligibility and health classification change for the malformed static API-key shape.
• Merge-risk explanation: the diff touches several auth files because the same malformed profile flows through selection, explicit resolution, doctor output, and setup input; the behavior is still one narrow invariant rather than separate feature work.

Current review state

Which bot or reviewer comments were addressed?

• RF-001: fixed. Documented openclaw onboard command variants with intervening flags and --auth-choice= are covered by credential-state.test.ts and provider-auth-input.test.ts.
• RF-002: fixed. PR body now includes redacted local OpenClaw doctor/auth proof from the real auth-profile store and doctor health path.
• RF-003: fixed. The real behavior proof shows the malformed zai:default profile loading as api_key/zai, health classification as missing [malformed_api_key], and doctor output with the remediation hint.
• RF-004: maintainer decision disclosed. Compatibility risk is limited to command-shaped API-key values containing --auth-choice; normal API-key, token, OAuth, keyRef, and SecretRef behavior is unchanged.
• RF-005: fixed. The detector now recognizes documented non-interactive onboard command variants where other flags appear before --auth-choice.
• RF-006: fixed. Redacted after-fix OpenClaw doctor/auth proof is included under Real behavior proof.
• RF-007: maintainer decision disclosed. The PR keeps the classifier in shared auth-profile eligibility because the poisoned value is consumed by auth selection, explicit profile lookup, doctor health, and setup/onboarding input.
• RF-008: fixed. src/agents/auth-profiles/credential-state.ts now covers documented onboard command variants, with regression tests for the missed forms.
• Additional ClawSweeper commit-review finding: fixed. CLI provider option and non-interactive API-key flag inputs now reject command-shaped values before storage or endpoint probing, with focused regression tests.