<!-- source: https://deepwiki.com/openclaw/openclaw/3.3.2-oauth-and-custom-providers -->

# OAuth & Custom Providers

- apps/ios/Sources/Design/TalkProTab.swift
- docs/install/migrating-hermes.md
- extensions/codex/src/migration/auth.ts
- extensions/migrate-hermes/auth-config.ts
- extensions/migrate-hermes/auth.ts
- extensions/migrate-hermes/items.ts
- extensions/migrate-hermes/secrets.test.ts
- extensions/migrate-hermes/secrets.ts
- extensions/migrate-hermes/source.ts
- extensions/openai/realtime-provider-shared.ts
- extensions/openai/realtime-voice-provider.test.ts
- extensions/openai/realtime-voice-provider.ts
- src/gateway/server-startup-log.test.ts
- src/gateway/server-startup-log.ts
- src/plugin-sdk/provider-auth.test.ts
- src/plugin-sdk/provider-auth.ts
- src/plugins/config-contract-matches.ts
- src/plugins/config-contracts.test.ts
- src/plugins/config-contracts.ts
- src/plugins/discovery-threading.test.ts
- src/plugins/installed-plugin-index-registry.ts
- src/plugins/installed-plugin-index-types.ts
- src/plugins/loader.runtime-registry.test.ts
- src/plugins/loader.test-fixtures.ts
- src/plugins/loader.test.ts
- src/plugins/loader.ts
- src/plugins/manifest-registry.ts
- src/plugins/plugin-sdk-dist-alias.ts
- src/plugins/registry.ts
- src/plugins/runtime/standalone-runtime-registry-loader.test.ts
- src/security/dangerous-config-flags-current-snapshot.test.ts
- src/security/dangerous-config-flags-current.ts
- src/security/dangerous-config-flags.ts
- src/talk/provider-types.ts

OpenClaw provides a robust architecture for managing diverse authentication mechanisms beyond simple API keys. This includes OAuth 2.0 flows, device-based authentication, and custom provider discovery via the plugin system, ensuring that the Agent Runtime can access models across various cloud and local providers.

## Authentication Modes

OpenClaw supports several authentication strategies for model providers, ranging from static keys to dynamic, short-lived tokens:

- API Key : Standard bearer token authentication resolved from environment variables or configuration files src/plugin-sdk/provider-auth.ts 90
- OAuth : Full OAuth 2.0 flows with managed access and refresh tokens, used for services like xAI Grok, Google Gemini, or OpenAI Codex src/plugin-sdk/provider-auth.ts 103
- Device Code : A "headless" OAuth flow where the Gateway prints a code and URL for the user to authorize in a separate browser, ideal for SSH/VPS setups src/plugin-sdk/provider-auth.ts 113-116
- Auth Profile : Named credential sets stored in auth-profiles.json . Profiles can be api_key or oauth types and are associated with specific providers src/plugin-sdk/provider-auth.ts 15-21

### Auth Profile System

The `AuthProfileStore` is the central repository for these credentials. OpenClaw prioritizes explicit provider auth order followed by usage heuristics. The system tracks profile health, including expiration times for OAuth tokens to ensure proactive refreshing.

**Sources:** [src/plugin-sdk/provider-auth.ts1-130](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugin-sdk/provider-auth.ts#L1-L130) [src/plugin-sdk/provider-auth.test.ts1-102](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugin-sdk/provider-auth.test.ts#L1-L102)

## OAuth & Provider Runtime Architecture

OpenClaw uses a plugin-driven runtime to bridge the gap between model requests and underlying credentials. The runtime orchestrates token resolution and ensures that background refreshes are handled correctly via plugin hooks.

### Code Entity Space: Auth Resolution

The system resolves a model request into a concrete authenticated transport using the `AuthProfileStore` and provider-specific transport logic.

**Provider Auth Resolution Flow**

```

```

**Sources:** [src/plugin-sdk/provider-auth.ts1-130](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugin-sdk/provider-auth.ts#L1-L130) [src/plugin-sdk/provider-auth.test.ts103-172](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugin-sdk/provider-auth.test.ts#L103-L172) [extensions/openai/realtime-voice-provider.ts1-40](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/openai/realtime-voice-provider.ts#L1-L40)

### Key Implementations

#### OpenAI Realtime & Voice Call

The OpenAI provider supports complex Realtime Voice capabilities through WebSockets.

- WebSocket Transport : Uses the ws library to establish persistent connections for low-latency audio extensions/openai/realtime-voice-provider.ts 33
- Auth Integration : Resolves API keys via resolveProviderAuthProfileApiKey and injects them into provider request headers extensions/openai/realtime-voice-provider.ts 5-7
- Session Configuration : Supports both standard and Azure OpenAI deployments, normalizing configuration for VAD thresholds and audio formats like pcm16 or g711_ulaw extensions/openai/realtime-voice-provider.ts 178-201

#### GitHub Copilot Discovery

- Token Management : Implements a specific caching layer for GitHub Copilot tokens in github-copilot.token.json src/plugin-sdk/provider-auth.ts 143-145
- Refresh Logic : Tokens are considered usable if they have at least 5 minutes of remaining life src/plugin-sdk/provider-auth.ts 147-154
- IDE Emulation : Injects specific headers (User-Agent, Editor-Version) to maintain compatibility with the Copilot internal API src/plugin-sdk/provider-auth.ts 121-128

#### Qwen Portal & Device Flow

Custom providers can register via the `PluginRegistry` to handle specialized auth flows like the Qwen Portal device flow.

- Provider Validation : The normalizeRegisteredProvider function ensures that custom providers meet the required contract for model catalog integration src/plugins/registry.ts 125
- Interactive Handlers : Plugins can register interactive callbacks to handle user-facing auth prompts during the device flow src/plugins/registry.ts 109-110

**Sources:** [extensions/openai/realtime-voice-provider.ts43-240](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/openai/realtime-voice-provider.ts#L43-L240) [src/plugin-sdk/provider-auth.ts130-200](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugin-sdk/provider-auth.ts#L130-L200) [src/plugins/registry.ts1-130](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugins/registry.ts#L1-L130)

## Migration & Provider Discovery

OpenClaw supports migrating configuration and credentials from other AI systems (like Hermes or legacy Codex) and performing implicit provider discovery.

### Code Entity Space: Migration

### Migration Logic

The migration system allows users to port their workspace, skills, and authentication profiles into OpenClaw:

- Hermes/OpenCode Migration : Specifically handles extracting OpenAI OAuth tokens from legacy opencode-auth.json or hermes configurations extensions/migrate-hermes/auth.ts 82-116
- Deduplication : Uses authProfileDedupeKey based on account IDs or email addresses to prevent duplicate credential entries during import extensions/migrate-hermes/auth.ts 223-225
- Config Patching : Migrated credentials can trigger a configPatch to update the default model for the workspace extensions/migrate-hermes/auth.ts 178-185

**Migration Flow**

```

```

**Sources:** [extensions/migrate-hermes/auth.ts1-230](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/migrate-hermes/auth.ts#L1-L230) [src/plugin-sdk/provider-auth.ts103-112](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugin-sdk/provider-auth.ts#L103-L112)

### Implicit Provider Discovery

OpenClaw uses provider aliases and manifest metadata to discover usable credentials:

- Manifest Contracts : Plugins declare supported providers (e.g., realtimeVoiceProviders , imageGenerationProviders ) in their manifest src/plugins/manifest-registry.ts 165-182
- Auto-Enablement : Plugins can be configured to auto-enable when specific providers are detected in the user's environment src/plugins/manifest-registry.ts 208

**Sources:** [src/plugins/manifest-registry.ts198-220](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugins/manifest-registry.ts#L198-L220) [src/plugins/registry.ts125-140](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugins/registry.ts#L125-L140)
