#18670: feat: add first-class Claude Code CLI auth path + CLI model UX hardening

## Motivation / safety context This change is partly motivated by provider-policy enforcement around Anthropic subscription credentials. There are public reports (and recurring issue threads) of users seeing errors such as: > "This credential is only authorized for use with Claude Code and cannot be used for other API requests." and, in some cases, account/credential restrictions after attempting to use Claude subscription auth through non-Claude-Code API-style paths. To reduce that risk, this PR intentionally avoids unsupported token-spoof/reuse patterns and makes the **official Claude Code CLI path** first-class in OpenClaw: - prefer `claude-code-cli` (official Claude Code harness context) - keep `setup-token` as manual/headless fallback - keep API key flow available (often best for production / multi-user) Net effect: better alignment with provider auth boundaries, fewer accidental policy violations, and clearer user guidance. --- ## Summary Adds first-class **Claude Code CLI** onboarding/auth support in OpenClaw and hardens related model/auth UX so CLI-backed Claude can be used as either **primary** model path or **fallback**. Also improves failover billing classification and closes diagnostics gaps for CLI readiness in `models status` and `doctor`. --- ## What changed ### 1) First-class Claude Code CLI auth choice - New auth choice: `claude-code-cli` - New apply/wiring: - `src/commands/auth-choice.claude-code-cli.ts` - `src/commands/auth-choice.apply.claude-code-cli.ts` - updates in auth-choice/onboard flows + schema/help text - Cross-platform command detection for `claude` (`which`/`where`) ### 2) Legacy alias compatibility + clearer guidance - Map legacy `claude-cli` auth choice to `claude-code-cli` - Keep legacy aliases accepted internally while de-emphasizing in help - Clarify non-interactive deprecated `codex-cli` guidance: - points users to `openai-api-key` (instead of interactive-only OAuth path) ### 3) Onboarding UX improvements - Skip redundant default-model reprompt when `claude-code-cli` is selected ### 4) CLI-aware model validation and list/status behavior - `auth-choice.model-check` now handles CLI providers explicitly - Avoid false API auth/catalog warnings for CLI selections - `models list`/status UX no longer mislabels configured CLI models as missing ### 5) CLI readiness diagnostics gap closed - New shared helper: - `src/agents/cli-backend-readiness.ts` - `models status` enhancements: - JSON now includes `auth.cliReadiness.providersInUse` and `auth.cliReadiness.backends` - text output includes **CLI backend readiness** section with actionable hints - `--check` fails on CLI readiness issues - `--check` scopes OAuth expiry/missing checks to **non-CLI providers in use** - `doctor` enhancements: - provider-in-use derivation from model/image primary+fallbacks - CLI vs non-CLI split for diagnostics - provider-scoped auth health checks - CLI readiness notes via `noteCliProviderReadiness(...)` ### 6) Failover/billing robustness - Expanded billing/credits-exhausted detection patterns - Billing classification prioritized ahead of generic rate-limit classification - 402/status-code handling aligned in related auth-key checks ### 7) Docs consistency updates - Anthropic docs updated to frame **Claude Code OAuth** as first-class subscription path - setup-token documented as manual/headless fallback - Fixed markdownlint duplicate-heading issue in `docs/providers/anthropic.md` --- ## Testing Ran locally (targeted): ```bash # unit pnpm exec vitest run --config vitest.unit.config.ts \ src/commands/auth-choice-legacy.test.ts \ src/commands/auth-choice.model-check.test.ts \ src/wizard/onboarding.test.ts \ src/agents/cli-backend-readiness.test.ts # e2e/targeted pnpm exec vitest run --config vitest.e2e.config.ts \ src/commands/models/list.registry.cli-backend.e2e.test.ts \ src/commands/onboard-non-interactive.provider-auth.e2e.test.ts \ src/commands/models/list.status.e2e.test.ts \ src/commands/doctor-auth.cli-readiness.e2e.test.ts \ src/commands/auth-choice.e2e.test.ts \ src/commands/auth-choice-options.e2e.test.ts \ src/agents/pi-embedded-helpers.isbillingerrormessage.e2e.test.ts \ src/agents/pi-embedded-helpers.formatassistanterrortext.e2e.test.ts \ src/agents/model-fallback.e2e.test.ts \ src/agents/live-auth-keys.e2e.test.ts # smoke pnpm exec vitest run --config vitest.e2e.config.ts src/cli/program.smoke.e2e.test.ts ``` --- ## Notes - Earlier bun/windows failures were triaged against near-simultaneous `main` and matched baseline instability (not PR-specific). - Follow-up branch runs include passing docs + bun/windows lanes after fixes.