feat(native-agent): Anthropic OAuth (Claude Pro/Max) login for openab-agent

[canyugs]

What problem does this solve?

openab-agent can only reach Anthropic via ANTHROPIC_API_KEY (pay-per-token). Codex already supports subscription login, but Claude Pro/Max subscribers cannot use their subscription with the native agent. This adds native Anthropic OAuth (Claude Pro/Max) so users run openab-agent on the Claude subscription they already pay for — no API key — matching the existing Codex experience.

Closes #1186

Discord Discussion URL: https://discord.com/channels/1491295327620169908/1519271476002291752

At a Glance

  openab-agent auth anthropic-oauth          ~/.openab/agent/auth.json
        │ PKCE + browser/paste                ┌────────────────────────────┐
        ▼                                      │ "codex"          (Token)   │
  claude.ai/oauth/authorize ──code──► token   │ "anthropic-oauth"(Token) ◄─┼─ new tenant
  platform.claude.com/v1/oauth/token          │ "<mcp server>"   (Mcp)     │
        │ JSON exchange + scope-less refresh   └────────────────────────────┘
        ▼
  AnthropicProvider (OAuth mode)
    Authorization: Bearer <sk-ant-oat…>
    anthropic-beta: claude-code-20250219,oauth-2025-04-20   x-app: cli
    system[0] = "You are Claude Code, …"   tools: read→Read …
        │
        ▼   api.anthropic.com/v1/messages
  provider select: ANTHROPIC_API_KEY → anthropic-oauth → codex

Prior Art & Industry Research

I looked at how two comparable self-hosted agents authenticate to Anthropic and Codex. The headline finding: neither implements a native Anthropic (Claude Pro/Max) OAuth login — both avoid the PKCE flow and instead lean on a setup-token or on reusing Claude Code's local credentials. This PR (following Pi) does the full native PKCE login, which is strictly more self-contained for pod deployments. Their surrounding architecture, however, validates the storage/refresh choices here.

OpenClaw — supports API keys and subscription OAuth.

• Anthropic: no native OAuth login — either a user-supplied setup-token stored in an auth profile, or reuse of the local Claude CLI (claude -p).
• Codex: full PKCE — auth.openai.com/oauth/authorize → callback http://127.0.0.1:1455/auth/callback (or manual paste) → token exchange → accountId extracted from the access token. This is byte-for-byte the same flow openab-agent already uses for Codex, corroborating our approach as the de-facto standard.
• Storage: ~/.openclaw/agents/<id>/agent/auth-profiles.json, one {access, refresh, expires, accountId} tuple per profile.
• Refresh: treats the profile file as a "token sink", refreshes under a file lock, and is careful not to spend copied refresh tokens — the same rotation hazard we handle by persisting the rotated refresh token on every refresh.
• Refs: https://docs.openclaw.ai/concepts/oauth , https://docs.openclaw.ai/gateway/authentication

Hermes Agent — PROVIDER_REGISTRY dataclasses in hermes_cli/auth.py declare each provider's auth type + base URLs + env vars; resolve_runtime_provider() is the single resolution entry point.

• Anthropic: API key only — no OAuth. Reads ANTHROPIC_API_KEY, and if absent reads ~/.claude/.credentials.json (reuses Claude Code's store). Docs explicitly note Anthropic here is "straightforward API key authentication without refresh token complexity."
• Storage: ~/.hermes/auth.json (OAuth tokens + active provider), credential_pool.json (rotation), .env (API keys); auth.json guarded with fcntl/msvcrt file locks.
• Refs: https://deepwiki.com/NousResearch/hermes-agent/2.3-authentication-and-providers , https://github.com/NousResearch/hermes-agent

Primary source ported: Pi (earendil-works/pi) — packages/ai/src/utils/oauth/anthropic.ts (PKCE flow, endpoints, scopes; verifier doubles as state) and packages/ai/src/api/anthropic-messages.ts (OAuth headers, Claude Code system block, tool-name normalisation). The OAuth client is Claude Code's public client.

How this PR compares: like both systems, openab-agent keeps a single namespaced credential file (~/.openab/agent/auth.json) with atomic writes + per-refresh rotation handling, and an existing Codex tenant identical to OpenClaw's Codex flow. Unlike both, it adds a native Anthropic PKCE login so subscribers need neither a setup-token nor a local Claude Code install.

Proposed Solution

Add an anthropic-oauth tenant alongside the existing codex tenant in ~/.openab/agent/auth.json:

• auth.rs — login_anthropic_browser_flow() (PKCE; verifier doubles as state per Claude's flow); namespaced token store (load/save/get_valid_token/force_refresh _for(provider)); per-provider refresh encoding (Anthropic = JSON, no scope; Codex = form); shared loopback-callback helpers; show_status lists all tenants.
• llm.rs — AnthropicProvider gains AnthropicAuth { ApiKey | OAuth }. OAuth mode sends Bearer + Claude Code identity headers (anthropic-beta: claude-code-20250219,oauth-2025-04-20, x-app: cli), prepends the required "You are Claude Code…" system block, normalises built-in tool names to Claude Code casing (read↔Read), and refreshes once on a mid-flight 401. select_provider gains anthropic-oauth; anthropic/auto fall back API-key → OAuth.
• acp.rs — session/model selection via AnthropicProvider::auto*() (covers both auth modes); model catalog shows Anthropic models when an API key or OAuth token is present.
• main.rs — openab-agent auth anthropic-oauth [--no-browser].

Also bumps the stale default model claude-sonnet-4-20250514 → claude-opus-4-8 (the old dated snapshot returns 404 on the subscription endpoint).

Why this approach?

• Consistency: reuses the existing Codex OAuth tenant pattern in the same auth.json, so the two subscription logins coexist without new storage mechanisms.
• Proven flow: endpoints/headers/system block are ported verbatim from Pi (a shipping Anthropic-OAuth client), de-risking the Claude-Code-beta specifics.
• Refresh safety: each refresh persists the rotated refresh token (OpenClaw/Hermes both flag this as a sharp edge).

Tradeoffs / limitations: depends on Claude Code's public OAuth client and the claude-code-20250219,oauth-2025-04-20 beta headers — if Anthropic changes these, the OAuth path needs updating (API-key path is unaffected). The claude-opus-4-8 default now also applies to API-key mode (Opus is pricier per-token; overridable via OPENAB_AGENT_MODEL). The legacy Dockerfile.native is unrelated and intentionally out of scope (canonical Dockerfile.unified builds the native variant correctly).

Alternatives Considered

• API key only (status quo): excludes every Pro/Max subscriber — the whole point.
• Reuse Claude Code's local credential store (what Hermes does via ~/.claude/.credentials.json, and OpenClaw via claude -p): rejected — openab-agent runs in a pod with no Claude Code install and no ~/.claude. Owning an anthropic-oauth tenant in our own auth.json keeps it self-contained and matches the Codex tenant already present.
• Setup-token paste (OpenClaw's other Anthropic path): rejected — a full PKCE login is a better UX (no manual token minting) and reuses the exact callback/paste plumbing the Codex flow already has.
• Separate credential file per provider: rejected — the namespaced single auth.json already serves Codex + MCP; a new file would fragment storage and duplicate the atomic-write/rotation logic.

Validation

Rust:

• cargo check / cargo build pass (0 warnings)
• cargo test passes — 194 passed, incl. 4 new (authorize-URL, namespaced storage disjointness, OAuth request-body identity+tool-casing, name round-trip)
• cargo clippy — no new warnings from this change (6 pre-existing in test-module ENV_LOCK-across-await + mcp/runtime.rs; the OAuth code is clippy-clean)

Manual (real Claude Pro/Max account):

• auth anthropic-oauth --no-browser login → token stored under anthropic-oauth, auth status shows valid
• Live chat on claude-opus-4-8 (default) / claude-sonnet-4-6 / 4-5 → correct responses
• Real tool call — bash executes in-sandbox (echo …$((6*7)) → 42), confirming tool-name normalisation round-trips
• Token refresh — forced expiry → live JSON refresh succeeds, access+refresh tokens rotate, request still completes
• Canonical image — built Dockerfile.unified --target native; ran the in-image agent end-to-end (chat + tool call) via the stored OAuth token

[Copilot]

Pull request overview

Adds first-class Anthropic (Claude Pro/Max) OAuth login support to openab-agent, storing credentials as a new anthropic-oauth tenant alongside the existing codex tenant in ~/.openab/agent/auth.json. This extends provider auto-detection and request shaping so Claude subscription users can run the native agent without an ANTHROPIC_API_KEY.

Changes:

• Introduces openab-agent auth anthropic-oauth [--no-browser] PKCE login flow and namespaced token load/save/refresh helpers.
• Extends AnthropicProvider to support OAuth auth mode (Bearer + Claude Code identity headers/system block + tool-name casing normalization).
• Updates ACP provider/model selection and available-model listing to recognize Anthropic OAuth credentials; bumps default Anthropic model to claude-opus-4-8.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

File	Description
openab-agent/src/main.rs	Adds the auth anthropic-oauth CLI subcommand wiring.
openab-agent/src/auth.rs	Implements Anthropic PKCE/OAuth flow and namespaced token storage/refresh.
openab-agent/src/llm.rs	Adds Anthropic OAuth request behavior (headers/system/tool name normalization) and provider selection updates.
openab-agent/src/acp.rs	Uses Anthropic auto* selection (API key or OAuth), updates default model and model availability gating.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[canyugs]

Thanks for the thorough review — addressed in 73bf9a2.

F1 (🔴 CI workspace) — fixed, with a root-cause correction. The "rebase onto main" suggestion doesn't apply: this branch is already based on current main (d1b0cfb), and the breakage is present-but-dormant there. ci-openab-agent.yml only runs on paths: openab-agent/**; its last run was 2026-06-17 (#1133) — before the workspace restructure (#1146/#1170) made the repo root a workspace without excluding openab-agent. Nothing has touched openab-agent/ on main since, so the check never re-ran — this PR is the first openab-agent/ change to expose it. Fix: exclude = ["openab-agent"] in the root Cargo.toml (the cargo error's own suggestion), plus cargo fmt. Locally the full CI sequence now passes: cargo fmt --check, cargo clippy -- -D warnings, cargo test (194), cargo test -- --ignored (11). Note: committing [workspace] into openab-agent/Cargo.toml instead would have collided with Dockerfile.unified's build-time [workspace] injection (duplicate-key error), so the root exclude is the non-conflicting fix.

F2 (🟡 PKCE state) — fixed + verified live. Now uses an independent 32-byte random state; the verifier stays back-channel-only. Worth recording: claude.ai's authorize rejects a short independent state with Invalid request format, so the state is sized to match the verifier (32 bytes) — value still independent. Verified end-to-end against a real Pro/Max account (browser login → token exchange with state ≠ verifier → live chat).

F3 (🟡 error UX) — fixed. Credential errors now name fully-qualified subcommands (openab-agent auth anthropic-oauth / openab-agent auth codex-oauth) and preserve the underlying read/parse error.

F4 (🟡 comment tag) — fixed. ponytail: → Note:.

Also confirmed the canonical native image still builds: Dockerfile.unified --target native (the path build-images.yml uses) builds clean and runs the OAuth flow end-to-end in-container. The legacy Dockerfile.native is a separate pre-existing issue (missing the [workspace] injection that Dockerfile.unified does) and is intentionally out of scope here.

[canyugs]

Follow-up: the CI openab-agent check went green only after one more fix (4ef7c49).

With the workspace exclude in place, fmt/clippy/test ran and passed, but the ACP initialize smoke test then failed (empty response). Root cause: a latent flush-on-shutdown race — the dispatch loop fed responses to a detached stdout-drain task, and on stdin-EOF #[tokio::main] aborted the drain before it flushed the last line. main wins this race by timing; this branch's slightly different startup timing lost it ~85% of the time locally (origin/main binary: 20/20 pass; this branch pre-fix: 3/20). Fix captures the drain handle and bounded-awaits it after the loop so queued output is flushed before return — 20/20 after. All CI openab-agent steps now pass.

[brettchien]

Supplementary architectural review (forward-looking — this PR is already LGTM'd and the line-level items
are well covered by the automated review + the author's fixes; CI is green, state is now independent, the
workspace exclude is in). None of the below blocks merging — they're direction/follow-up points for the
planned OAuth revamp + a forthcoming ADR, worth anchoring on record before this lands as the first vendor.

Findings

#	Severity	Finding	Location
1	🟡	auth.json read-modify-write is unlocked across processes — concurrent refresh can trip OAuth 2.1 §10.4 token-family revocation. Not introduced here; follow-up, not blocking.	auth.rs storage layer
2	🟢	Add CLAUDE_CODE_OAUTH_TOKEN env support — unblocks headless/pod/CI now, and is race-free	llm.rs / auth.rs
3	🟢	Keep per-vendor specifics in a descriptor (sets up the shared multi-vendor adapter as a refactor, not a rewrite)	auth.rs / llm.rs
4	🟡	Hardcoded default claude-opus-4-8 is a recurring-staleness/404 risk (no evergreen alias in 4.6+) — recommend dropping the hardcoded default and requiring the model via config/env (fail-loud)	llm.rs:152, acp.rs:385/446
5	🟢	Stale doc comment still says "PKCE with the verifier doubling as state" though the code now uses an independent state	auth.rs:692
6	🟢	getrandom::fill(...).expect(...) in a Result-returning fn → prefer ?	auth.rs:461/472

Detail — F1: cross-process auth.json race (follow-up)

auth.json is multi-tenant (codex / anthropic-oauth / mcp:*) and every writer does
read_auth_file → mutate → write_auth_file with no lock. openab-agent runs one process per session
thread (SessionPool → connection.rs spawns a child per thread), so concurrent threads = concurrent
processes doing that RMW. When a token expires, multiple processes refresh in the same window; with
refresh-token rotation the later ones present an already-rotated token, which under OAuth 2.1 §10.4 reuse
detection can revoke the whole token family → every session logged out at once.

This is not introduced by this PR (Codex already shares the same store), but OAuth widens the exposure,
and API-key users never hit it (no refresh writes). Not merge-blocking for this PR. The fix — a
flock-guarded RMW funnel that all writers (including the MCP CredentialStore) share, with the network
refresh done outside the lock + a re-read inside for single-flight — is planned for the revamp PR. Until
then, F2 (env token) gives a race-free path for fleet/pod use.

Detail — F4: default model staleness

This PR replaces the old default claude-sonnet-4-20250514 precisely because it 404s on the subscription
endpoint (retired there). The replacement claude-opus-4-8 will eventually hit the same fate when it's
retired from the Claude Code surface — i.e. this is a recurring 404 timebomb, not a one-off. And there's no
escape via a floating alias: in the 4.6+ generation, dateless IDs (claude-opus-4-8, claude-sonnet-4-6)
are fixed canonical IDs, not evergreen pointers — Anthropic ships new versions under new IDs and never
re-points an old one. So the default must be bumped by hand each generation.

Recommendation — no hardcoded model default; require it via config/env and fail loud. Since Messages V1
mandates a model and there is no evergreen alias to fall back to, any in-code default is a 404 timebomb.
Resolve model as: ACP/CLI model_override → OPENAB_AGENT_MODEL → error ("no model configured; set
OPENAB_AGENT_MODEL or select one") instead of the hardcoded claude-opus-4-8. This also removes the
silent Opus cost bump for API-key users.

Note this is a behavior change: today's zero-config default goes away, so a model must be set
(deployments via values.yaml/env already do; zero-config npx/local users will need to set
OPENAB_AGENT_MODEL). Worth a clear error message + CHANGELOG line. Drops the three duplicated default
sites (llm.rs:152, acp.rs:385/446).

Detail — F2: support CLAUDE_CODE_OAUTH_TOKEN

claude setup-token mints a 1-year subscription OAuth token. Reading it as a Bearer source — precedence
ANTHROPIC_API_KEY → CLAUDE_CODE_OAUTH_TOKEN → stored anthropic-oauth tenant (same shape as pi,
earendil-works/pi#3591) — is only a few lines and:

• makes Claude subscription auth usable in headless / pod / CI today (no browser, no loopback, no stdin
  paste), which the interactive PKCE flow can't cover in a container; and
• is race-free (env token, no auth.json refresh writes) — see F1.

For ops-managed deployments this is arguably the primary path; interactive PKCE is for local self-service.

Detail — F3: per-vendor descriptor

client_id / client_secret / endpoints / scope / token-body-format are the only things that vary between
Codex, Anthropic, and upcoming vendors (Gemini, agy, grok…). Holding them in a small per-vendor struct now
(rather than inlined in the Anthropic flow) makes the planned shared OAuth adapter a clean extraction
instead of a rewrite. No need to build the adapter in this PR — just don't entrench Claude-only assumptions.

Direction / roadmap (tracked in a forthcoming ADR)

A short ADR is being drafted for multi-vendor LLM-provider OAuth + credential storage; this PR is the first
vendor under it. Explicitly out of scope here, listed so the follow-ups are on record:

• the shared OAuthVendor adapter + Codex refactor onto it (+ grok as a cheap OpenAI-compatible add);
• the flock locked-RMW storage fix (F1);
• additional vendors (Gemini / agy via Google Code Assist, etc.);
• /auth (PR feat(discord): add /auth slash command for device-flow auth #1185) interactive integration — later roadmap. Note for whenever it's picked up:
  Anthropic has no device flow (claude.ai is authorization_code only, Support device-code authentication flow (RFC 8628) for Pro/Max subscription users in headless environments anthropics/claude-code#22992) and the
  --no-browser paste reads stdin, which the /auth relay can't feed, so that path will likely be a
  two-step code-as-CLI-arg flow. No action needed in this PR.

[brettchien]

Follow-up on F4 — one thing worth doing in this PR before it merges: please don't pin claude-opus-4-8 as a hardcoded default.

This PR exists because the previous hardcoded default (claude-sonnet-4-20250514) 404'd on the subscription endpoint after retirement — and claude-opus-4-8 will eventually hit the same fate. There's no escape via an alias: in the 4.6+ generation, dateless IDs are fixed canonical IDs, not evergreen pointers, so a hardcoded default is a recurring 404 timebomb that has to be chased by hand every generation.

Since Messages V1 mandates a model, the cleanest fix is to require it and fail loud rather than bake in a new pin:

• resolve model as ACP/CLI model_override → OPENAB_AGENT_MODEL → error ("no model configured; set OPENAB_AGENT_MODEL or select one")
• drop the three hardcoded default sites: llm.rs:153, acp.rs:385, acp.rs:446
• (the ModelOption catalog entry at acp.rs:509 is fine — that's offering the model, not defaulting to it)

It's a small change, and it also removes the silent Opus cost bump for API-key users. Behavior note: this drops the zero-config default, so a model must be set — deployments via values.yaml/env already do; worth a clear error message + CHANGELOG line for zero-config/local users.

[canyugs]

@brettchien Great call — this is exactly the right framing, thank you. The dateless 4.6+ IDs being fixed canonical IDs (not evergreen pointers) makes any hardcoded default a recurring 404 timebomb, and pinning Opus also quietly raised costs for API-key users. Implemented your fail-loud approach in b28c312:

• Model resolution is now: explicit ACP/CLI override → OPENAB_AGENT_MODEL → error (no model configured; set OPENAB_AGENT_MODEL or select a model). No baked-in default.
• Dropped the three hardcoded sites (llm.rs anthropic_model_from_env, acp.rs session new/load). anthropic_model() is now fallible; session new/load report the provider's actually-resolved model instead of a fallback.
• Kept the claude-opus-4-8 entry in the model catalog (acp.rs) — offering, not defaulting, as you noted.
• Two implementation details worth flagging: a model override (CLI/ACP) does not require OPENAB_AGENT_MODEL, and credentials are still checked before the model so a missing key/token surfaces its own error rather than the generic "no model configured". auto() only falls through to OAuth when no API key is present.
• Behavior note + CHANGELOG-equivalent: documented in docs/native-agent.md that OPENAB_AGENT_MODEL is required for Anthropic — zero-config now fails loud with a clear message; env/values.yaml deployments are unaffected.

Tests: cargo fmt/clippy -D warnings clean, cargo test 196 + 11 ignored. Added test_session_new_requires_model to lock in the fail-loud contract. This also resolves the earlier #5 (silent Opus cost bump for API-key users).

[chaodu-agent]

CHANGES REQUESTED ⚠️ — Well-architected multi-tenant Anthropic OAuth addition; one comment/behaviour mismatch in the 401 retry path.

What This PR Does

Adds native Anthropic OAuth (Claude Pro/Max subscription) login alongside the existing Codex OAuth flow, letting subscribers use openab-agent without an API key.

How It Works

• auth.rs — new anthropic-oauth tenant: PKCE browser flow with independent CSRF state, JSON token exchange against platform.claude.com, per-provider refresh encoding, namespaced save_tokens_for/load_tokens_for.
• llm.rs — AnthropicAuth { ApiKey | OAuth } enum; OAuth mode sends Claude Code identity headers (anthropic-beta: claude-code-20250219,oauth-2025-04-20, x-app: cli), prepends required system block, normalises tool names to Claude Code casing (read→Read), force-refreshes on 401. auto() prefers API key then OAuth; OPENAB_AGENT_MODEL is now required (no hardcoded default).
• acp.rs — provider selection via auto*() / from_oauth_store(); session OAuth mode preserved on model switch.
• main.rs — openab-agent auth anthropic-oauth [--no-browser] subcommand.
• Existing Codex flow preserved via backward-compatible wrapper functions.

Findings

#	Severity	Finding	Location
1	🟡	401 retry comment says "retry once" but the loop allows up to 3 force-refresh attempts on persistent 401s	llm.rs:427
2	🟢	Independent CSRF state (not reusing PKCE verifier) — correct defense-in-depth	auth.rs:700
3	🟢	Refresh-token rotation persisted immediately on every refresh	auth.rs:380
4	🟢	Claude Code identity headers match Pi's production implementation	llm.rs:404
5	🟢	Tool name normalisation is bidirectional with passthrough for unknown names (MCP tools)	llm.rs:220
6	🟢	Session OAuth mode preserved on model switch — no silent auth fallback	acp.rs:598
7	🟢	No hardcoded default model — fails loud instead of pinning a 404 timebomb	llm.rs:190
8	🟢	State always validated: loopback callback + paste mode (code#state) both reject mismatches	auth.rs:660,725

Finding Details

🟡 F1: 401 retry comment/behaviour mismatch

The comment at llm.rs:427 reads:

// 401 on OAuth: token may have expired mid-request; force a
// refresh and retry once.

But the condition is attempt < max_retries (where max_retries = 3), meaning 401s trigger up to 3 consecutive force_refresh_for calls — not "once". Each refresh persists the rotated token, so 3 force-refreshes against a revoked token waste round-trips and may rotate a still-valid refresh token off the server's grace window.

Suggestion: either add an oauth_refreshed flag that short-circuits after the first 401 refresh (matching the documented intent), or update the comment to reflect the actual 3-retry behaviour.

🟢 F2–F8: What's done well

All the positive findings listed above demonstrate thorough, production-quality work — the PKCE flow, refresh handling, Claude Code headers, tool-name round-tripping, and session-state preservation are all correctly implemented with appropriate tests (4 new unit tests + comprehensive manual validation).

Baseline Check

• PR opened: 2025-06-22
• Main already has: auth.rs (1093 lines) — Codex OAuth PKCE + device flow, MCP credential store, TokenStore, AuthEntry enum. llm.rs — AnthropicProvider with API-key-only auth.
• Net-new value: full native Anthropic subscription OAuth tenant, Claude Code identity protocol, tool-name normalisation, auto() credential fallback chain, removal of hardcoded default model.

What's Good (🟢)

• Clean extension of existing multi-tenant credential pattern — no new storage mechanisms
• Security: independent CSRF state, immediate refresh-token persistence, state validation on all paths
• UX: auto() gracefully falls back API-key → OAuth → Codex with clear error messages
• Thorough testing: 194 tests pass, 4 new (authorize URL params, namespaced storage disjointness, OAuth request body identity/tool-casing, name round-trip)
• All CI green (30+ smoke tests across all agent variants)
• Excellent PR description with prior-art research