Update: Auto-sync Claude Code OAuth + Keychain fallback (e77978d92)

This commit fixes the core issue where Anthropic OAuth tokens can't auto-refresh because Claude Code stores credentials in macOS Keychain while OpenClaw was reading from the empty ~/.claude/.credentials.json file.

Changes

src/agents/auth-profiles/external-cli-sync.ts

• Added Claude Code to the external CLI sync chain (same pattern as Qwen/MiniMax)
• On auth store load, syncs fresh credentials from Claude Code Keychain → anthropic:claude-cli profile
• Also updates anthropic:default if it exists with stale credentials

src/agents/auth-profiles/oauth.ts

• Write-back: After successful Anthropic token refresh, writes new tokens back to Claude Code Keychain via writeClaudeCliCredentials() so both stay in sync
• Keychain fallback: When refreshAnthropicTokens() fails (e.g. rotated refresh token), reads fresh credentials from Claude Code's Keychain before giving up

scripts/sync-claude-oauth.ts

• Replaced raw fs.readFileSync of ~/.claude/.credentials.json with readClaudeCliCredentials() which tries Keychain first on macOS — fixes the empty file issue

src/agents/anthropic-oauth.test.ts (new)

• 10 unit tests covering: successful refresh, missing refresh token, error responses, expiry buffer math (5-min buffer + 30s floor), custom clientId, email preservation

Verification

• pnpm build ✅
• pnpm check ✅
• pnpm test — all 208 tests pass including 10 new ones ✅

@steipete, please look for this solution

2 failed CIs doesn't seem to be related to my changes. @steipete Please check and consider merging this.

@steipete — Could you please review this PR? It's been open for weeks and is blocking all users who rely on Anthropic OAuth.

I've confirmed the underlying issue thoroughly on v2026.2.9:

1. loginAnthropic() from @mariozechner/pi-ai works — creates a proper OAuth profile with access + refresh tokens ✅
2. refreshAnthropicToken(refreshToken) works — manually refreshing returns valid new tokens ✅
3. But OpenClaw's refreshOAuthTokenWithLock() never calls it — when the token expires, it throws "No API key found for provider anthropic" instead of refreshing ❌

The pi-ai library already has full Anthropic OAuth support (loginAnthropic, refreshAnthropicToken, anthropicOAuthProvider). The provider IS registered in getOAuthProviders(). But the runtime dispatch in the auth module fails to resolve it, so tokens expire and are never renewed.

This PR wires up exactly what's missing. Multiple users have confirmed it works locally. The CI failures on macOS/Windows appear unrelated to the actual code changes (as @maxtongwang noted).

This is the #1 most impactful issue on the tracker right now — 15+ comments on #9095, affecting everyone using Anthropic without a paid API key. Would really appreciate a review. 🙏

@steipete this PR is urgent. please review/approve. thanks!

Urgent: This PR is the only path to Anthropic OAuth support in OpenClaw

I just tested both auth methods with a fresh OAT token (sk-ant-oat01-*) on v2026.2.15:

# x-api-key header → "invalid x-api-key"
curl -H 'x-api-key: sk-ant-oat01-...' https://api.anthropic.com/v1/messages
→ 401: {"error":{"type":"authentication_error","message":"invalid x-api-key"}}

# Authorization: Bearer → "OAuth not supported"  
curl -H 'Authorization: Bearer sk-ant-oat01-...' https://api.anthropic.com/v1/messages
→ 401: {"error":{"type":"authentication_error","message":"OAuth authentication is currently not supported."}}

OAT tokens cannot be used with the raw Anthropic API. This PR implements the OAuth flow that makes them work. Without it, the only way to use Anthropic in OpenClaw is with a paid API key.

This blocks every user who wants to use their Claude Pro/Max subscription with OpenClaw instead of paying separate API credits.

With @steipete's transition to OpenAI, could one of the active maintainers review this? The auth subsystem has no dedicated maintainer in CONTRIBUTING.md.

cc @sebslight @tyler6204 @gumadeiras — this has been open for weeks with CI passing and confirmed working by 5+ users. No human reviewer has been assigned.

i was one of the first trying to figure this out and at this point i've moved to the OpenAI pro subscription, despite my reservations.

Anthropic, especially after today's news, will not make it easy to make this happen. everything they can do to patch they will.

to be clear, i wanted xAI to do what OpenAI did today so i'm riding the wave until the next better alternative comes available.

can yall try the current implementation and let me know if you still have problems?

@gumadeiras — tested the current implementation (v2026.2.15). Here's what I found:

What WORKS

The @mariozechner/pi-ai library (bundled in v2026.2.15) already has Anthropic OAuth support:

• anthropicOAuthProvider is registered in the OAuth provider registry
• refreshAnthropicToken() exists and is exported
• getOAuthProviders() returns 5 providers including anthropic
• The refreshOAuthTokenWithLock() dispatch chain in model-selection-*.js correctly routes to resolveOAuthProvider() which finds anthropic in the registered set

What DOES NOT WORK

1. openclaw models auth login --provider anthropic fails:

Error: Unknown provider "anthropic". Loaded providers: google-antigravity, google-gemini-cli.

The login command resolves providers from loaded gateway plugins, not from the pi-ai OAuth registry. Since there's no Anthropic plugin loaded (it's a built-in provider), the login command can't find it.

2. openclaw models auth setup-token --provider anthropic requires TTY — can't test programmatically, but it defaults to --provider anthropic so it might work interactively.

3. Manually created type: "token" profiles don't refresh:
Our auth profile is type: "token" with an OAT token. The refreshOAuthTokenWithLock() function checks cred.type !== "oauth" and returns null (line 729). Static tokens can't be refreshed.

4. OAT tokens don't work with the raw API:

curl -H 'x-api-key: sk-ant-oat01-...' → 401 "invalid x-api-key"
curl -H 'Authorization: Bearer sk-ant-oat01-...' → 401 "OAuth authentication is currently not supported"

Root cause

The OAuth refresh infrastructure exists in v2026.2.15, but there's no way to create an type: "oauth" Anthropic credential with a refresh token through the CLI. The login command doesn't recognize Anthropic, and paste-token creates type: "token" entries without refresh tokens.

What PR #8602 adds

• Routes the login command through the pi-ai OAuth flow for Anthropic
• Creates proper type: "oauth" credentials with refresh token
• Implements refreshAnthropicTokens() that calls platform.claude.com/v1/oauth/token
• Syncs back to Claude Code Keychain on macOS

Suggestion

The simplest fix might be to wire openclaw models auth login to use getOAuthProvider("anthropic") from pi-ai directly, instead of requiring a loaded gateway plugin. This would unblock the entire OAuth flow without needing most of PR #8602's changes.

@nikolasdehor I meant the current implementation in this PR, not on main

@gumadeiras I checked out and built the PR branch locally. Here are my test results:

Build

• Branch: feat/anthropic-oauth (commit 9e8feb3)
• Build: ✅ Clean build, 274 output files, no errors
• Unit tests: ✅ All 10 tests in anthropic-oauth.test.ts pass

CLI Commands

What I couldn't test without TTY

The actual models auth login --provider anthropic flow requires an interactive terminal to open the browser for Anthropic OAuth consent. Since I'm testing from a non-interactive context, I get:

Error: models auth login requires an interactive TTY.

I'll run this in an interactive terminal session and report back on the full OAuth flow (browser → consent → token → refresh cycle).

Code Review Observations

The implementation looks solid:

1. src/agents/anthropic-oauth.ts — Clean refresh logic hitting platform.claude.com/v1/oauth/token with JSON body. 5-minute expiry buffer is sensible.

2. src/agents/auth-profiles/oauth.ts:64 — Routes provider === "anthropic" to refreshAnthropicTokens(). The fallback to reading fresh creds from Claude CLI's Keychain (readClaudeCliCredentialsCached({ ttlMs: 0 })) is a smart recovery path.

3. Changelog note about preserving auth mode — Important: prevents static api_key/token profiles from being auto-converted to OAuth. This was a concern I had from my v2026.2.15 investigation.

Key improvement over main

On main (v2026.2.15):

• models auth login --provider anthropic → "Unknown provider" ❌
• refreshOAuthTokenWithLock() skips type: "token" credentials → no refresh ❌
• Token expires after ~8h → permanent cooldown ❌

On this PR branch:

• models auth login --provider anthropic → ✅ Recognized, ready for OAuth flow
• Proper refreshAnthropicTokens() wired in → ✅ refresh infrastructure connected
• Fallback to Claude CLI Keychain → ✅ recovery path exists

This PR would resolve #9095 (my issue), #17873, and #18624. Looking forward to testing the full interactive flow.

sounds good; thanks for testing
let me know when you had a chance to test the interactive flow

@gumadeiras Important finding from TTY testing:

My earlier report was incomplete — the "requires interactive TTY" error was masking the real issue. When I run with an actual TTY (via script -q /dev/null), the command gets past the TTY check but fails with:

Error: Unknown provider "anthropic". Loaded providers: google-antigravity, google-gemini-cli.
Verify plugins via `openclaw plugins list --json`.

Root cause

models auth login resolves providers from loaded gateway plugins, not from the pi-ai OAuth registry. Only google-antigravity and google-gemini-cli are loaded as plugins. anthropicOAuthProvider is registered in @mariozechner/pi-ai/dist/utils/oauth/index.js but the login command never consults that registry.

What works vs what doesn't

So paste-token and setup-token use a different provider resolution path than login. The login command goes through the plugin system, while paste-token/setup-token accept arbitrary provider names.

Suggested fix

The login command's provider resolution should fall back to the pi-ai OAuth registry when the provider isn't found in loaded plugins:

// Current (broken):
const provider = loadedPlugins.find(p => p.id === providerId);
if (!provider) throw new Error(`Unknown provider "${providerId}"`);

// Fixed:
const provider = loadedPlugins.find(p => p.id === providerId) 
  ?? getOAuthProvider(providerId);  // fall back to pi-ai registry
if (!provider) throw new Error(`Unknown provider "${providerId}"`);

This would connect the existing anthropicOAuthProvider (which already has loginAnthropic() and refreshAnthropicToken()) to the CLI command.

Test environment

• PR branch: feat/anthropic-oauth (commit 9e8feb3)
• Node: v24.11.0, macOS 15.4
• Gateway v2026.2.15 installed (tested PR build separately)

you don't need TTY on the gateway machine but you need TTY in some machine:

Setup-tokens are created by the Claude Code CLI, not the Anthropic Console. You can run this on any machine:
claude setup-token

Paste the token into OpenClaw (wizard: Anthropic token (paste setup-token)), or run it on the gateway host:
openclaw models auth setup-token --provider anthropic

If you generated the token on a different machine, paste it using:
openclaw models auth paste-token --provider anthropic

there is no auth login --provider anthropic; just use the steps above
you don't need to manually create any auth entries in the config files. If this is not working then you might have conflicts/bad config from previous tests you were doing. Start clean and give it a try

pi will check if the token is oauth and route things properly

https://docs.openclaw.ai/providers/anthropic#anthropic

Hey, we were pulling this into our fork and ran it through our @claude automated review workflow. The workflow kept catching issues and iterating until clean — ended up with a handful of real fixes. Opened #21518 as a superseding PR with everything included.

Here's what we found:

Bug — Qwen double-read in external-cli-sync.ts
store.profiles[QWEN_CLI_PROFILE_ID] was read into two separate variables (existingQwen and existing) that always point to the same value, plus the Qwen block duplicated ~20 lines of logic already in syncExternalCliCredentialsForProvider. Migrated to the shared helper (same pattern as MiniMax/Anthropic).

Bug — external-cli-sync.test.ts tests silently not running
The vi.mock("../cli-credentials.js") pattern doesn't intercept module bindings in Vitest's fork pool with ESM. The mock call count was always 0 while the real function ran. Fixed with an optional deps injection parameter on syncExternalCliCredentials — no vi.mock needed, and the test now actually exercises the sync logic.

Code quality — redundant String() casts in oauth.ts
String(cred.provider) === "anthropic" etc. — cred.provider is already string.

Test quality — unsafe cast in anthropic-oauth.test.ts
(result as Record<string, unknown>).email → result.email directly since email? is declared on the return type.

Refactor — coerceExpiresAt duplication
Both anthropic-oauth.ts and chutes-oauth.ts had identical copies. Extracted to src/agents/oauth-utils.ts.

PR #21518 has all of the above in a single commit on top of a clean branch from main. Feel free to pull the changes into this branch or close this one in favour of that.

cc @gumadeiras for review