<!-- source: https://deepwiki.com/openclaw/openclaw/3.3-model-providers-and-authentication -->

# Model Providers & Authentication

- docs/help/testing-live.md
- extensions/amazon-bedrock/stream.runtime.test.ts
- extensions/amazon-bedrock/stream.runtime.ts
- extensions/google/transport-stream.test.ts
- extensions/google/transport-stream.ts
- extensions/google/vertex-adc.ts
- extensions/lmstudio/openclaw.plugin.json
- qa/scenarios/config/config-restart-capability-flip.md
- scripts/test-live-subagent-announce-docker.sh
- src/agents/agent-tools.before-tool-call.e2e.test.ts
- src/agents/agent-tools.before-tool-call.embedded-mode.test.ts
- src/agents/agent-tools.before-tool-call.ts
- src/agents/anthropic-transport-stream.test.ts
- src/agents/anthropic-transport-stream.ts
- src/agents/json-unsafe-integers.ts
- src/agents/live-cache-regression-runner.test.ts
- src/agents/live-cache-regression-runner.ts
- src/agents/live-cache-test-support.ts
- src/agents/live-model-filter.ts
- src/agents/live-test-helpers.test.ts
- src/agents/live-test-helpers.ts
- src/agents/live-test-provider-drift.test.ts
- src/agents/live-test-provider-drift.ts
- src/agents/model-auth-env.provider-aliases.test.ts
- src/agents/model-auth-env.ts
- src/agents/model-auth-label.test.ts
- src/agents/model-auth-label.ts
- src/agents/model-auth.profiles.test.ts
- src/agents/model-auth.test.ts
- src/agents/model-auth.ts
- src/agents/model-auth.workspace-plugin.test.ts
- src/agents/model-catalog-visibility.test.ts
- src/agents/model-catalog-visibility.ts
- src/agents/model-compat.test.ts
- src/agents/model-provider-auth.test.ts
- src/agents/model-provider-auth.ts
- src/agents/models.profiles.live.test.ts
- src/agents/openai-reasoning-compat.live.test.ts
- src/agents/subagent-announce.live.test.ts
- src/agents/tool-replay-repair.live.test.ts
- src/auto-reply/reply/commands-models.test.ts
- src/auto-reply/reply/commands-models.ts
- src/commands/configure.gateway-auth.prompt-auth-config.test.ts
- src/commands/configure.gateway-auth.ts
- src/commands/doctor.runs-legacy-state-migrations-yes-mode-without.e2e.test.ts
- src/commands/model-picker.test.ts
- src/config/model-input.ts
- src/config/types.skills.ts
- src/config/zod-schema.models.test.ts
- src/flows/model-picker.ts
- src/gateway/gateway-cli-backend.live.test.ts
- src/gateway/gateway-models.profiles.live.test.ts
- src/gateway/server-methods/models.ts
- src/llm/providers/anthropic.test.ts
- src/llm/providers/anthropic.ts
- src/llm/providers/simple-options.ts
- src/plugins/contracts/host-hooks.contract.test.ts
- src/plugins/synthetic-auth.runtime.test.ts
- src/plugins/synthetic-auth.runtime.ts
- src/plugins/trusted-tool-policy.ts
- src/secrets/provider-env-vars.dynamic.test.ts
- src/secrets/provider-env-vars.ts
- src/skills/workshop/config.ts
- src/skills/workshop/policy.ts
- src/tui/tui-event-handlers.test.ts
- src/tui/tui-event-handlers.ts
- test/proof/thinking-signature-real-proof.ts

OpenClaw acts as a multi-platform AI gateway that abstracts various LLM providers (Anthropic, OpenAI, Google Gemini, DeepSeek, etc.) into a unified interface. This page documents how OpenClaw configures these providers, manages authentication profiles, and resolves credentials during agent execution.

For **Gateway authentication** (WebSocket tokens, passwords, and device pairing), see [Authentication & Authorization](/openclaw/openclaw/2.2-authentication-and-authorization). For the full configuration schema, see [Configuration Reference](/openclaw/openclaw/2.3.1-configuration-reference).

## Auth Profiles & Credential Storage

Credentials for model providers are managed in `auth-profiles.json`, located within each agent's state directory. This store is managed by the `AuthProfileStore` logic [src/agents/auth-profiles/store.ts18-21](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/auth-profiles/store.ts#L18-L21)

### Profile ID Structure

Profiles are identified by a string in the format `<provider>:<name>`.

- API Keys : Typically use the default name (e.g., anthropic:default ).
- OAuth : Managed via specialized profiles that support token refresh logic src/agents/model-auth.ts 154-156
- CLI Auth : Specialized IDs like google-gemini-cli are used when bridging to local CLI tools for authentication discovery src/commands/model-picker.test.ts 50-53

### Credential Types

The system supports several credential formats defined in the authentication resolution logic:

Sources: [src/agents/auth-profiles/store.ts18-21](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/auth-profiles/store.ts#L18-L21) [src/agents/model-auth.ts41-156](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/model-auth.ts#L41-L156) [src/commands/model-picker.test.ts50-53](https://github.com/openclaw/openclaw/blob/fbdf5937/src/commands/model-picker.test.ts#L50-L53)

## Provider Configuration & Discovery

OpenClaw uses a dual-layer configuration system: explicit configuration in `openclaw.json` and a synchronized `models.json` used by the agent runtime [src/gateway/gateway-models.profiles.live.test.ts44](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/gateway-models.profiles.live.test.ts#L44-L44)

### The Model Selection Logic

The system handles parsing model references (e.g., `provider/model`) and inferring providers through normalization and alias mapping. The `model-selection` module [src/agents/model-selection.ts](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/model-selection.ts) is central to this process.

**Title: Model Selection & Identity Resolution**

```

```

Sources: [src/agents/model-selection.ts14-27](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/model-selection.ts#L14-L27) [src/agents/model-selection.test.ts103-110](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/model-selection.test.ts#L103-L110) [src/agents/model-selection-shared.ts25-29](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/model-selection-shared.ts#L25-L29)

### Provider Catalog & Discovery

OpenClaw automatically enables providers if it detects valid credentials or via catalogs:

- Plugin-Owned Catalogs : Provider plugins own onboarding, model catalogs, and transport normalization src/agents/model-provider-auth.ts 22
- Normalization : Provider IDs are normalized to canonical forms using normalizeProviderId src/agents/model-selection.ts 14
- Discovery : The system scans for available models using loadModelCatalog src/agents/model-catalog.js 15-16

For details on the discovery pipeline, see [Provider Normalization](/openclaw/openclaw/3.3.1-provider-normalization).

## Runtime Auth Resolution

When an agent initiates a request, the execution pipeline determines how to authenticate with the chosen provider using a strict resolution hierarchy.

### Auth Selection & Failover

The `hasAuthForModelProvider` function coordinates credential resolution, prioritizing explicit config while allowing for environment fallbacks. This logic handles finding and validating API keys and other credentials before they leave the gateway [src/agents/model-provider-auth.ts145-158](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/model-provider-auth.ts#L145-L158)

**Title: Auth Resolution Hierarchy**

```

```

Sources: [src/commands/model-picker.test.ts72-113](https://github.com/openclaw/openclaw/blob/fbdf5937/src/commands/model-picker.test.ts#L72-L113) [src/agents/model-auth.ts41](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/model-auth.ts#L41-L41) [src/agents/model-provider-auth.ts145-158](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/model-provider-auth.ts#L145-L158)

## Implicit Provider Discovery

OpenClaw can implicitly discover providers based on environment variables and local configuration. To optimize performance, the gateway "warms" this state at startup.

### Prewarming Auth State

To avoid expensive CLI probing and plugin discovery on the hot path, OpenClaw populates a `PreparedProviderAuthState` during gateway startup [src/agents/model-provider-auth.ts31-41](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/model-provider-auth.ts#L31-L41) This cache is consulted by `hasAuthForModelProvider` so every model-listing call (pickers, `/models`, status commands) skips per-provider plugin discovery [src/agents/model-provider-auth.ts166-201](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/model-provider-auth.ts#L166-L201)

### Discovery Mechanisms

- Environment-Based : Primary keys like ANTHROPIC_API_KEY are scanned via resolveEnvApiKey src/agents/model-auth.ts 41
- Synthetic Auth : Plugins can inject synthetic provider references at runtime src/plugins/synthetic-auth.runtime.ts 10-25
- External CLI Probing : The system can probe local tools (e.g., az , gcloud , google-gemini-cli ) for credentials src/agents/auth-profiles.js 29-30

### Hot Reloading

The gateway supports hot reloading of authentication state. When configuration changes, the prepared state is invalidated via `clearCurrentProviderAuthState` to ensure the next request re-warms with the new config [src/agents/model-provider-auth.ts108-112](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/model-provider-auth.ts#L108-L112)

For details on OAuth flows and CLI integrations, see [OAuth & Custom Providers](/openclaw/openclaw/3.3.2-oauth-and-custom-providers).

Sources: [src/agents/model-provider-auth.ts31-201](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/model-provider-auth.ts#L31-L201) [src/agents/model-auth.ts41](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/model-auth.ts#L41-L41) [src/plugins/synthetic-auth.runtime.ts10-25](https://github.com/openclaw/openclaw/blob/fbdf5937/src/plugins/synthetic-auth.runtime.ts#L10-L25) [src/agents/auth-profiles.js29-30](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/auth-profiles.js#L29-L30)
