OAuth Providers

Adds an "OAuth" settings tab to the OpenClaw Control UI for connecting AI model providers. Supports Anthropic Claude Pro/Max subscription tokens (setup-token...

Security Scan

The skill's files, runtime instructions, and requested actions are consistent with an OAuth/settings UI that manages provider credentials; it reads/writes local OpenClaw config and secrets and auto-detects Anthropic tokens from the Claude CLI, which is coherent with the described purpose.

Purpose & Capability

Name/description align with the code and SKILL.md: the UI view, controller, and gateway RPCs implement OAuth, subscription-token, and API-key storage for Anthropic, OpenAI (Codex PKCE), Google, and OpenRouter. The actions (reading ~/.claude, writing auth-profiles and secrets, invoking a PKCE flow) are expected for this feature.

Instruction Scope

Instructions and code stay within the stated purpose but do include reading another tool's credentials (~/.claude/.credentials.json) for an auto-detect feature and accept pasted redirect URLs for OAuth manual completion. Those behaviors are documented in SKILL.md and implemented in code; users should be aware this imports tokens from the Claude CLI into OpenClaw's auth store.

Install Mechanism

No install spec / no arbitrary remote downloads. The code dynamically imports an external package (@mariozechner/pi-ai) at runtime; if that package is required it must be present in the runtime environment (the code handles a missing package by returning an error). No extract-from-URL installs or unknown binary downloads are present in the skill bundle.

Credentials

The skill declares no required env vars but writes API keys into OpenClaw's secrets store and the mapping uses environment variable names (ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY, OPENROUTER_API_KEY). It also reads/writes local config and agent store files (auth-profiles.json, openclaw config, secrets.json). These accesses are proportionate to credential management, but users should expect these files to be modified and tokens copied into OpenClaw's encrypted stores.

Persistence & Privilege

always:false and user-invocable:true; the skill registers gateway RPC handlers and writes auth profiles/config when invoked, but it does not request permanent inclusion or modify other skills. Autonomous invocation is allowed by default but not combined here with other elevated privileges.

Assessment

This skill appears to do what it says: add an OAuth/API-key UI and store credentials in OpenClaw's auth and secrets stores. Before installing, consider the following: - It will read ~/.claude/.credentials.json (Claude CLI) if you use the Anthropic auto-detect feature and copy that token into OpenClaw — only enable auto-detect if you trust this behavior. - Credentials are written to OpenClaw config/secrets (auth-profiles.json, ~/.openclaw/secrets.json). Make backups if you want to revert changes. - OAuth manual fallback requires pasting the full redirect URL (contains codes/state). Avoid pasting such URLs into untrusted UIs or shared clipboards. - The gateway uses a third-party package (@mariozechner/pi-ai) via dynamic import; ensure that dependency in your environment comes from a trusted source before using the OAuth flow. - Logs may include short token prefixes in error messages (the code prints the token start in some errors). If that concerns you, review/modify logging before use. If you are comfortable with these behaviors (reading Claude CLI creds, writing to OpenClaw auth/secrets, and relying on the external pi-ai package), the skill is coherent with its stated purpose. If you need higher assurance, review the included TypeScript files and the provenance of @mariozechner/pi-ai before enabling the feature.

OAuth Providers Tab

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

What It Installs

File	Purpose
ui/src/ui/views/ai-providers.ts	Lit HTML view — provider cards, mode tabs, OAuth spinner, manual-paste field
ui/src/ui/controllers/ai-providers.ts	State management, RPC calls, provider catalogue
src/gateway/server-methods/auth-login.ts	Gateway RPC handlers for all auth flows

Plus wiring changes in:

• ui/src/ui/app.ts — 6 @state() properties
• ui/src/ui/app-render.ts — render block for state.tab === "ai-providers"
• ui/src/ui/app-settings.ts — tab load trigger
• ui/src/ui/navigation.ts — Tab type, TAB_PATHS, iconForTab
• src/gateway/server-methods.ts — register authLoginHandlers
• src/gateway/server-methods/plugins-ui.ts — BUILTIN_UI_VIEWS entry
• ui/src/i18n/locales/en.ts — "ai-providers" label ("OAuth") and subtitle

Auth Flows

OpenAI — Codex PKCE OAuth

• Button opens the system browser via openUrl()
• Callback captured on localhost:1455/auth/callback
• Calls loginOpenAICodex() from @mariozechner/pi-ai
• Credentials written by writeOAuthCredentials() + applyAuthProfileConfig()
• 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() + upsertAuthProfile()
• 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, OPENROUTER_API_KEY

Gateway RPCs

Method	Description
auth.login.status	List all configured auth profiles
auth.login.anthropic-token	Validate + store Anthropic setup-token
auth.login.anthropic-auto	Auto-detect token from ~/.claude/.credentials.json
auth.login.openai-codex	Run PKCE OAuth (opens browser)
auth.login.openai-codex.submit-code	Manual paste of redirect URL (WSL2 fallback)
auth.login.remove	Remove a profile by profileId

Auth Badge System

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

Badge Rendering (grouped-render.ts)

profileId pattern	Badge	CSS class
__mode:oauth	OAuth (green)	auth-badge--oauth
Contains :manual or claude-cli or starts with anthropic:oat	OAuth (green)	auth-badge--oauth
Starts with anthropic: (catch-all)	API (blue)	auth-badge--api
Starts with openai:	Fallback	auth-badge--fallback
Everything else	API	auth-badge--fallback

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:

storedOrder (auth-profiles.json)  →  takes precedence
configuredOrder (openclaw.json)   →  fallback if no stored order
explicitProfiles (config keys)    →  fallback if no explicit order
storeProfiles (all in store)      →  last resort

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:

# Check current auth status
openclaw models status

# Check what auth-profiles.json actually has
python3 -c "
import json
with open('$HOME/.openclaw/agents/main/agent/auth-profiles.json') as f:
    d = json.load(f)
print('order:', d.get('order'))
print('lastGood:', d.get('lastGood'))
print('profiles:', list(d['profiles'].keys()))
"

Fix:

# Option 1: Remove stale order so openclaw.json becomes authoritative
python3 -c "
import json
path = '$HOME/.openclaw/agents/main/agent/auth-profiles.json'
with open(path) as f: d = json.load(f)
d.pop('order', None)
d.pop('lastGood', None)
with open(path, 'w') as f: json.dump(d, f, indent=2)
print('Stale order removed')
"

# Option 2: Set order via CLI (writes to auth-profiles.json)
openclaw models auth order set --provider anthropic anthropic:claude-cli anthropic:default

# Then restart gateway
(sleep 3 && systemctl --user restart openclaw-gateway) &

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

resolveAuthProfileOrder() 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:

{
  "auth": {
    "profiles": {
      "anthropic:claude-cli": { "provider": "anthropic", "mode": "oauth" },
      "anthropic:default": { "provider": "anthropic", "mode": "api_key" }
    },
    "order": {
      "anthropic": ["anthropic:claude-cli", "anthropic:default"]
    }
  }
}

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. Copy references/view.ts → ui/src/ui/views/ai-providers.ts
2. Copy references/controller.ts → ui/src/ui/controllers/ai-providers.ts
3. Copy references/auth-login.ts → src/gateway/server-methods/auth-login.ts
4. Wire into the UI (see wiring changes above — follow patterns from other tabs like apikeys)
5. Register authLoginHandlers in src/gateway/server-methods.ts
6. npm run build — zero new TS errors expected
7. Restart gateway: (sleep 3 && systemctl --user restart openclaw-gateway) &
8. Open Settings → OAuth in the Control UI

Provider Catalogue

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

{
  id: "mistral",
  name: "Mistral AI",
  logo: "🌊",
  color: "#ff7000",
  description: "Mistral Large, Codestral — fast European models",
  connectOptions: [
    { mode: "api-key", label: "API Key", hint: "Get a key from console.mistral.ai", profileMode: "api_key" },
  ],
}

Known Gotchas

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 PROVIDER_CATALOGUE 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 ~/.claude/.credentials.json
• 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