Skip to content

fix: surface Claude CLI OAuth reauth hints#97894

Closed
aditya-vithaldas wants to merge 1 commit into
openclaw:mainfrom
aditya-vithaldas:codex/fix-claude-cli-oauth-reauth-hint
Closed

fix: surface Claude CLI OAuth reauth hints#97894
aditya-vithaldas wants to merge 1 commit into
openclaw:mainfrom
aditya-vithaldas:codex/fix-claude-cli-oauth-reauth-hint

Conversation

@aditya-vithaldas

@aditya-vithaldas aditya-vithaldas commented Jun 29, 2026

Copy link
Copy Markdown
Contributor

Closes #97553

What Problem This Solves

Fixes an issue where users running Claude through the claude-cli backend would see a generic provider authentication failure when the local Claude CLI OAuth login expired.

Why This Change Was Made

Claude CLI 401 authentication failures are now recognized as Claude CLI OAuth-login failures before the generic provider-authentication copy is used. The recovery hint keeps the runtime id visible, but points users at the owning auth flow: claude auth login followed by the Anthropic CLI auth-profile refresh command, formatted through OpenClaw's command formatter so active profile/container flags are preserved and default model selection is not changed.

User Impact

Users get an actionable re-authentication message for expired Claude CLI login state instead of a generic retry/re-auth note that does not name the correct repair path.

Evidence

  • node scripts/run-vitest.mjs src/agents/auth-profiles/oauth-refresh-failure.test.ts src/auto-reply/reply/agent-runner-execution.test.ts src/auto-reply/reply/provider-request-error-classifier.test.ts src/agents/cli-runner/execute.supervisor-capture.test.ts -- --reporter=dot — 3 shards passed: OAuth classifier, auto-reply, provider-request classifier, and CLI-runner supervisor capture.
  • pnpm exec oxfmt --check src/agents/auth-profiles/oauth-refresh-failure.ts src/agents/auth-profiles/oauth-refresh-failure.test.ts src/auto-reply/reply/agent-runner-execution.ts src/auto-reply/reply/agent-runner-execution.test.ts
  • git diff --check
  • .agents/skills/autoreview/scripts/autoreview --mode branch --base origin/main --codex-bin .artifacts/codex-flex --no-web-search — clean, no accepted/actionable findings; overall patch correct 0.86.

@aditya-vithaldas
aditya-vithaldas requested a review from a team as a code owner June 29, 2026 17:43
@openclaw-barnacle openclaw-barnacle Bot added agents Agent runtime and tooling size: S labels Jun 29, 2026
@clawsweeper

clawsweeper Bot commented Jun 29, 2026

Copy link
Copy Markdown
Contributor

Codex review: needs maintainer review before merge. Reviewed July 6, 2026, 6:51 AM ET / 10:51 UTC.

Summary
The PR adds Claude CLI OAuth 401 classification, targeted re-auth reply text, and regression tests for the classifier and auto-reply paths.

PR surface: Source +101, Tests +122. Total +223 across 4 files.

Reproducibility: yes. at source level: a claude-cli FailoverError with reason auth and status 401 currently reaches generic provider-auth guidance on main, while this PR routes it through OAuth guidance. I did not execute a fresh current-main expired-token run in this read-only review.

Review metrics: 1 noteworthy metric.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #97553
Summary: The linked issue is the canonical report; this PR and two sibling open PRs are candidate fixes for the same claude-cli OAuth 401 re-auth hint problem.

Members:

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🐚 platinum hermit
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

  • [P2] Add fresh current-head Telegram Desktop proof if maintainers want channel-visible confirmation beyond terminal/live-output proof.

Mantis proof suggestion
A current-head Telegram Desktop proof would directly show whether the user-visible reply now contains the targeted Claude CLI re-auth guidance. A maintainer can ask Mantis to capture proof by posting this exact PR comment:

@openclaw-mantis telegram desktop proof: verify that a claude-cli 401 auth failure displays the Claude CLI re-auth guidance in Telegram on the current PR head.

Risk before merge

  • [P1] Three open PRs target the same linked issue; merging more than one could duplicate or conflict in claude-cli classifier and reply-copy logic.
  • [P1] The branch changes auth-provider recovery classification for claude-cli 401 failures, so maintainers should accept that these failures are local Claude CLI OAuth expiry before merge.
  • [P1] Current-head proof is strong terminal/live-output plus exported reply mapping, but the visible Telegram Desktop proof on the PR is stale and negative for an older candidate.

Maintainer options:

  1. Make This Branch Canonical (recommended)
    Land this branch after maintainer auth-provider review, then close or supersede the overlapping claude-cli OAuth 401 PRs.
  2. Prefer A Sibling Branch
    If a sibling PR is the desired permanent shape, pause or close this PR after carrying over any uniquely useful tests or wording.
  3. Require Channel-Visible Proof
    If the remaining concern is Telegram delivery, ask for fresh current-head Telegram Desktop proof before merge.

Next step before merge

  • [P2] Human branch selection remains because overlapping open PRs target the same issue; there is no narrow automated repair needed for this branch.

Maintainer decision needed

  • Question: Should maintainers make this PR the canonical fix for claude-cli auth failure shows generic error instead of re-auth hint when OAuth token is expired #97553, or prefer one of the overlapping open PRs?
  • Rationale: Multiple contributor PRs implement the same auth-provider recovery path, and automation should not choose the permanent branch or close siblings without maintainer intent.
  • Likely owner: mbelinky — They introduced the OAuth re-auth reply surface that this PR extends, making them the strongest history-backed branch-selection owner.
  • Options:
    • Use This PR As Canonical (recommended): This branch now has current-head terminal proof, scoped claude-cli matching, and default-preserving recovery copy; review and land it, then close or supersede the sibling fixes.
    • Prefer The Proof Sibling: Use fix(claude-cli): surface re-auth hint when subprocess OAuth token expires #97669 if maintainers prefer its command shape or proof history, preserving any useful tests or copy from this PR before closing it.
    • Pause For Owner Shape: Hold the overlapping PRs until an auth/runtime owner chooses the exact classifier boundary and recovery wording.

Security
Cleared: No security or supply-chain concern found; the diff changes TypeScript auth classification, user-facing recovery copy, and tests without new dependencies, workflows, secret storage, or command execution.

Review details

Best possible solution:

Select one canonical fix for #97553; if this branch is chosen, land the scoped claude-cli OAuth 401 handling and close or supersede the overlapping PRs.

Do we have a high-confidence way to reproduce the issue?

Yes at source level: a claude-cli FailoverError with reason auth and status 401 currently reaches generic provider-auth guidance on main, while this PR routes it through OAuth guidance. I did not execute a fresh current-main expired-token run in this read-only review.

Is this the best way to solve the issue?

Yes: this is a narrow maintainable fix shape because it scopes detection to claude-cli provider/status/message evidence and keeps other provider auth failures on existing generic handling. The remaining question is canonical branch selection, not an observed code defect.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 1f06b890a66f.

Label changes

Label changes:

  • add proof: sufficient: Contributor real behavior proof is sufficient. The latest contributor comment provides redacted current-head terminal proof from a real Claude CLI 401 plus OpenClaw mapping proof for the targeted reply path.
  • add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
  • add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): The latest contributor comment provides redacted current-head terminal proof from a real Claude CLI 401 plus OpenClaw mapping proof for the targeted reply path.
  • remove rating: 🦪 silver shellfish: Current PR rating is rating: 🐚 platinum hermit, so this older rating label is no longer current.
  • remove status: 📣 needs proof: Current PR status label is status: 👀 ready for maintainer look.
  • remove proof: 📸 screenshot: Current real behavior proof evidence kind is terminal.

Label justifications:

  • P2: The PR targets a normal auth-provider recovery bug with limited blast radius and no crash, data-loss, or security-bypass signal.
  • merge-risk: 🚨 auth-provider: The diff changes auth failure classification and recovery guidance for claude-cli provider/runtime failures.
  • rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
  • status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): The latest contributor comment provides redacted current-head terminal proof from a real Claude CLI 401 plus OpenClaw mapping proof for the targeted reply path.
  • proof: sufficient: Contributor real behavior proof is sufficient. The latest contributor comment provides redacted current-head terminal proof from a real Claude CLI 401 plus OpenClaw mapping proof for the targeted reply path.
  • mantis: telegram-visible-proof: Mantis should capture Telegram visible proof. The changed failure text is visible in Telegram channel replies and can be demonstrated with a short Telegram Desktop proof.
Evidence reviewed

PR surface:

Source +101, Tests +122. Total +223 across 4 files.

View PR surface stats
Area Files Added Removed Net
Source 2 132 31 +101
Tests 2 122 0 +122
Docs 0 0 0 0
Config 0 0 0 0
Generated 0 0 0 0
Other 0 0 0 0
Total 4 254 31 +223

What I checked:

Likely related people:

  • mbelinky: PR 63217 added the OAuth refresh failure helper and channel re-auth guidance that this PR extends. (role: introduced OAuth reply surfacing; confidence: high; commits: b77db8c0b610; files: src/agents/auth-profiles/oauth-refresh-failure.ts, src/auto-reply/reply/agent-runner-execution.ts)
  • RomneyDa: PR 89181 threaded structured auth and failover errors through the same reply path. (role: typed auth failure routing contributor; confidence: high; commits: 50b69e16dc0d; files: src/agents/auth-profiles/oauth-refresh-failure.ts, src/auto-reply/reply/agent-runner-execution.ts, src/agents/failover-error.ts)
  • vincentkoc: PR 61276 hardened the host-managed Claude CLI auth path and Anthropic CLI migration behavior adjacent to this recovery hint. (role: Claude CLI auth path contributor; confidence: medium; commits: 3b84884793e8, 0479b9ed5d8d; files: extensions/anthropic/cli-shared.ts, extensions/anthropic/register.runtime.ts, src/commands/models/auth.ts)
  • steipete: Recent main history shows adjacent refactors in both OAuth helper and auto-reply failure delivery paths. (role: recent adjacent contributor; confidence: medium; commits: 49cc59b1e88e, 2c31af136429; files: src/agents/auth-profiles/oauth-refresh-failure.ts, src/auto-reply/reply/agent-runner-execution.ts)
What the crustacean ranks mean
  • 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
  • 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
  • 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
  • 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
  • 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
  • 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
  • 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works
  • ClawSweeper keeps one durable marker-backed review comment per issue or PR.
  • Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
  • A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
  • PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
  • Maintainers can also comment @clawsweeper review to request a fresh review only.
  • Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
  • Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
  • Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.
Review history (3 earlier review cycles)
  • reviewed 2026-07-03T16:16:12.306Z sha 305d073 :: needs real behavior proof before merge. :: none
  • reviewed 2026-07-06T06:48:06.663Z sha 384f97c :: needs real behavior proof before merge. :: none
  • reviewed 2026-07-06T08:40:28.197Z sha 06ea905 :: needs real behavior proof before merge. :: none

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

Copy link
Copy Markdown
Contributor

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: 39f657792c

ℹ️ 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".

Comment thread src/auto-reply/reply/agent-runner-execution.ts Outdated
@clawsweeper clawsweeper Bot added rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work. status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask. mantis: telegram-visible-proof Mantis should capture Telegram visible proof. P2 Normal backlog priority with limited blast radius. merge-risk: 🚨 auth-provider 🚨 May break OAuth, tokens, provider routing, model choice, or credentials. labels Jun 29, 2026
@clawsweeper clawsweeper Bot added rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. merge-risk: 🚨 compatibility 🚨 May break existing users, config, migrations, defaults, or upgrade paths. and removed rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work. merge-risk: 🚨 compatibility 🚨 May break existing users, config, migrations, defaults, or upgrade paths. labels Jun 29, 2026
@openclaw-mantis

Copy link
Copy Markdown
Contributor

Mantis Telegram Desktop Proof

Summary: Mantis captured Telegram Desktop before/after GIFs for the Claude CLI auth failure message.

Main screenshot This PR screenshot
Baseline native Telegram Desktop screenshot Candidate native Telegram Desktop screenshot
Main This PR
Baseline native Telegram Desktop proof GIF Candidate native Telegram Desktop proof GIF

Motion-trimmed clips:

Raw QA files: https://artifacts.openclaw.ai/mantis/telegram-desktop/pr-97894/run-28391904738-1/index.json

@clawsweeper clawsweeper Bot added the proof: 📸 screenshot Contributor real behavior proof includes screenshot evidence. label Jul 1, 2026
@aditya-vithaldas
aditya-vithaldas force-pushed the codex/fix-claude-cli-oauth-reauth-hint branch from d7bad1f to 2ac6874 Compare July 3, 2026 13:34
@clawsweeper clawsweeper Bot added proof: 🎥 video Contributor real behavior proof includes video or recording evidence. rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work. and removed proof: 📸 screenshot Contributor real behavior proof includes screenshot evidence. rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. labels Jul 3, 2026
@aditya-vithaldas
aditya-vithaldas force-pushed the codex/fix-claude-cli-oauth-reauth-hint branch from 2ac6874 to 305d073 Compare July 3, 2026 15:55
@aditya-vithaldas

Copy link
Copy Markdown
Contributor Author

@clawsweeper re-review

Fixed the OAuth reply precedence finding in 305d073d5097f4c245c9bdb616fd0acfb8efecdf by routing the external/known failure payload path through the shared OAuth helper before provider-auth fallback, and added the exported buildKnownAgentRunFailureReplyPayload regression for claude-cli 401 auth failures.

Current-head evidence:

  • GitHub CI on 305d073d5097f4c245c9bdb616fd0acfb8efecdf: 67 passed, 27 skipped, 0 failed/pending.
  • Mergeability: MERGEABLE / CLEAN.
  • GraphQL unresolved review threads: 0.
  • Local checks before push: git diff --check; node_modules/oxfmt/bin/oxfmt --check --threads=1 src/auto-reply/reply/agent-runner-execution.ts src/auto-reply/reply/agent-runner-execution.test.ts.
  • Earlier same-head-series focused proof before the final precedence-only test patch: node scripts/run-vitest.mjs src/agents/auth-profiles/oauth-refresh-failure.test.ts src/auto-reply/reply/agent-runner-execution.test.ts; node scripts/plugin-sdk-surface-report.mjs --check; node scripts/run-vitest.mjs --testTimeout 300000 test/scripts/plugin-sdk-surface-report.test.ts.

No live Claude/Telegram provider proof was run in this pass.

@clawsweeper

clawsweeper Bot commented Jul 3, 2026

Copy link
Copy Markdown
Contributor

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

@aditya-vithaldas
aditya-vithaldas force-pushed the codex/fix-claude-cli-oauth-reauth-hint branch from 384f97c to ed32547 Compare July 6, 2026 07:53
@aditya-vithaldas
aditya-vithaldas force-pushed the codex/fix-claude-cli-oauth-reauth-hint branch from ed32547 to 06ea905 Compare July 6, 2026 07:56
@clawsweeper clawsweeper Bot added proof: 📸 screenshot Contributor real behavior proof includes screenshot evidence. and removed proof: 🎥 video Contributor real behavior proof includes video or recording evidence. labels Jul 6, 2026
@aditya-vithaldas

Copy link
Copy Markdown
Contributor Author

@clawsweeper re-review

Current-head proof for 06ea905af96a3c793247890d5f2982c4dc9ac9ba.

Real Claude CLI OAuth-token 401 proof:

  • Claude CLI version: 2.1.201 (Claude Code).
  • Ran the CLI in an isolated temporary HOME and CLAUDE_CONFIG_DIR with a dummy CLAUDE_CODE_OAUTH_TOKEN value. No real credential or account token was used.
  • Command shape: HOME=<tmp>/home CLAUDE_CONFIG_DIR=<tmp>/claude CLAUDE_CODE_OAUTH_TOKEN=<dummy> claude --debug --debug-file <tmp>/claude-debug.log -p "Reply with ok" --model claude-sonnet-4-6.
  • Result: exit 1; stdout contained Failed to authenticate. API Error: 401 Invalid bearer token.
  • Redacted debug markers included [API:auth] OAuth token check starting, [API:auth] OAuth token check complete, and Anthropic API 401 authentication_error / Invalid bearer token entries. Request ids and token-shaped values were redacted before recording this proof.

OpenClaw mapping proof:

  • The branch classifies the real CLI failure shape as provider=claude-cli, status=401, reason=auth, message=Invalid bearer token, and routes it through the OAuth reauth guidance instead of generic provider-auth copy.
  • Focused verification passed:
    • node scripts/run-vitest.mjs src/agents/auth-profiles/oauth-refresh-failure.test.ts src/auto-reply/reply/agent-runner-execution.test.ts -> 2 Vitest shards passed; 7 auth-profile tests and 234 auto-reply tests passed.
    • git diff --check -> clean.

This proves the current Claude CLI OAuth-token 401 output shape and the OpenClaw reauth-copy path at the PR head without exposing or depending on a real user credential.

@clawsweeper

clawsweeper Bot commented Jul 6, 2026

Copy link
Copy Markdown
Contributor

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

@clawsweeper clawsweeper Bot added proof: sufficient ClawSweeper judged the real behavior proof convincing. rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. and removed proof: 📸 screenshot Contributor real behavior proof includes screenshot evidence. rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work. status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask. labels Jul 6, 2026
@sallyom

sallyom commented Jul 7, 2026

Copy link
Copy Markdown
Contributor

Thanks for working through this. We’re going to make #97669 the canonical fix for #97553, since it was the earlier active PR and its current shape keeps the claude-cli recovery command in the shared OAuth failure helper while covering both the raw Claude CLI 401 message and the structured FailoverError path.

From my review:
The main difference is: #97894 special-cases more reply text in agent-runner-execution.ts; #97669 keeps the recovery command behavior in the shared OAuth helper. That’s why #97669 is the better canonical path.

This PR is viable too and has a clean review, but it overlaps the same auth recovery surface. Thanks, again, for this contribution.

@sallyom sallyom closed this Jul 7, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

agents Agent runtime and tooling mantis: telegram-visible-proof Mantis should capture Telegram visible proof. merge-risk: 🚨 auth-provider 🚨 May break OAuth, tokens, provider routing, model choice, or credentials. P2 Normal backlog priority with limited blast radius. proof: sufficient ClawSweeper judged the real behavior proof convincing. rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. size: M status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

claude-cli auth failure shows generic error instead of re-auth hint when OAuth token is expired

2 participants