OAuth Providers Tab

Adds a polished OAuth settings tab to the OpenClaw Control UI.

What It Installs

Plus wiring changes in:

• - ui/src/ui/app.ts — 6 @state() properties
• INLINECODE5 — render block for INLINECODE6
• INLINECODE7 — tab load trigger
• INLINECODE8 — Tab type, TAB_PATHS, INLINECODE11
• INLINECODE12 — register INLINECODE13
• INLINECODE14 — BUILTIN_UI_VIEWS entry
• INLINECODE16 — "ai-providers" label ("OAuth") and subtitle

Auth Flows

OpenAI — Codex PKCE OAuth

• - Button opens the system browser via INLINECODE19
• Callback captured on INLINECODE20
• Calls loginOpenAICodex() from INLINECODE22
• Credentials written by writeOAuthCredentials() + INLINECODE24
• WSL2 manual-paste fallback: On WSL2, 127.0.0.1:1455 is unreachable from Windows. The UI shows a paste field where the user can paste the full redirect URL (http://localhost:1455/auth/callback?code=...&state=...). The gateway RPC auth.login.openai-codex.submit-code resolves a deferred promise that races with the local callback server via onManualCodeInput.
• Session state: aiProvidersOauthSessionId set by startOpenAICodexOAuth → used by aiProvidersSubmitCode to call the RPC

Anthropic — Subscription Token (setup-token)

• - User runs claude setup-token in terminal to generate a sk-ant-oat01-... token
• Pastes token into UI
• Validated by validateAnthropicSetupToken(), stored via buildTokenProfileId() + INLINECODE36
• Auto-detect button: Reads existing accessToken from ~/.claude/.credentials.json (under claudeAiOauth) and stores it via auth.login.anthropic-auto RPC
• ⚠️ Important: Anthropic has blocked some subscription usage outside Claude Code. The docs warn: "This credential is only authorized for use with Claude Code." Setup-token support is "technical compatibility only" with policy risk. If you get a "not authorized" error, an API key is required.

API Keys (all providers)

• - Encrypted to ~/.openclaw/secrets.json via existing secrets.write RPC
• Env vars: ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY, INLINECODE46

Gateway RPCs

Auth Badge System

The chat UI displays a badge next to assistant messages indicating which auth method was used.

Badge Rendering (grouped-render.ts)

The badge is determined by group.authProfileId in the message group. If the wrong profile is active, the wrong badge appears.

See references/auth-badge.ts.excerpt for the full function.

Auth Profile Order — Architecture & Troubleshooting

How Profile Selection Works

The gateway selects which auth profile to use via resolveAuthProfileOrder() in src/agents/auth-profiles/order.ts:

CODEBLOCK0

Critical: auth-profiles.json order ALWAYS wins over openclaw.json order. If auth-profiles.json has a stale order array, the correct order in openclaw.json will never be consulted.

See references/auth-order.ts.excerpt for the key code.

Common Issue: Stale Order / Ghost Profiles

Symptom: Badge shows "API" or "Fallback" even though the subscription token is configured correctly.

Cause: auth-profiles.json has an order array referencing non-existent profiles (e.g. anthropic:manual from an old setup). The existing profile (like anthropic:default) gets selected instead of the subscription token profile.

Diagnosis:
CODEBLOCK1

Fix:
CODEBLOCK2

Why Option 1 is preferred: The CLI writes to auth-profiles.json, but gateway restarts or other processes can overwrite it. Removing the stored order lets openclaw.json (which is the canonical config) be the authority.

Repair Logic

INLINECODE81 has a repair path (lines 96-100): if ALL profiles in the base order are missing from the store, it scans all stored profiles for the provider. But this only triggers when EVERY profile is missing — if even one exists (like anthropic:default), the repair doesn't kick in.

Config Verification

Ensure openclaw.json has the correct auth section:
CODEBLOCK3

The mode field in openclaw.json profiles is checked against the type field in auth-profiles.json credentials. A mode: "oauth" config is compatible with both type: "oauth" and type: "token" credentials (special-cased in resolveAuthProfileEligibility).

Installation Steps

1. 1. Copy references/view.ts → INLINECODE93
2. Copy references/controller.ts → INLINECODE95
3. Copy references/auth-login.ts → INLINECODE97
4. Wire into the UI (see wiring changes above — follow patterns from other tabs like apikeys)
5. Register authLoginHandlers in INLINECODE100
6. INLINECODE101 — zero new TS errors expected
7. Restart gateway: INLINECODE102
8. Open Settings → OAuth in the Control UI

Provider Catalogue

Defined in PROVIDER_CATALOGUE in references/controller.ts. To add a provider:

CODEBLOCK4

Known Gotchas

1. 1. Auth order precedence: auth-profiles.json order beats openclaw.json. If badge shows wrong auth mode, check for stale order in auth-profiles.json first.
2. Gateway restart overwrites: Manual edits to auth-profiles.json can be overwritten by gateway processes. Prefer editing openclaw.json for persistent config.
3. WSL2 loopback isolation: The OpenAI Codex OAuth callback server binds to 127.0.0.1:1455 (hardcoded in @mariozechner/pi-ai). Windows browsers can't reach WSL2 localhost. Use the manual-paste field.
4. claude setup-token requires interactive TTY: Uses Ink/raw mode — cannot be run non-interactively. The auto-detect button reads ~/.claude/.credentials.json as a workaround.
5. Anthropic policy risk: sk-ant-oat01-* tokens may be blocked outside Claude Code. If API calls return authorization errors, switch to an API key.
6. lastGood persistence: The lastGood field in auth-profiles.json can cause the gateway to skip the configured order and jump straight to a previously-working profile. Remove it along with order when troubleshooting.

Source Files

• - references/controller.ts — full controller with PROVIDERCATALOGUE and all action handlers
• references/view.ts — full Lit HTML view with manual-paste field
• references/auth-login.ts — full gateway RPC handlers including WSL2 fallback + auto-detect
• references/auth-order.ts.excerpt — auth profile order resolution logic (key snippet)
• references/auth-badge.ts.excerpt — badge rendering function (key snippet)

Changelog

v1.1.0

• - Added WSL2 manual-paste fallback for OpenAI Codex OAuth (onManualCodeInput + auth.login.openai-codex.submit-code RPC)
• Added Anthropic auto-detect button (auth.login.anthropic-auto RPC) — reads from INLINECODE121
• Added auth badge rendering reference (renderAuthBadge() from grouped-render.ts)
• Added auth profile order architecture documentation with troubleshooting guide
• Added stale order/ghost profile diagnosis and fix procedures
• Documented resolveAuthProfileOrder() precedence: stored order > config order > explicit profiles > store profiles
• Added known gotchas section covering order precedence, gateway overwrites, WSL2 loopback, TTY requirements, and Anthropic policy risk

v1.0.0

• - Initial release with Anthropic setup-token, OpenAI Codex PKCE OAuth, and API key flows