<!-- source: https://deepwiki.com/qhkm/zeptoclaw/10.1-provider-configuration -->

# Provider Configuration

- landing/zeptoclaw/docs/src/content/docs/concepts/providers.md
- src/kernel/provider.rs
- src/providers/mod.rs
- src/providers/registry.rs

This page documents ZeptoClaw's LLM provider configuration system. It covers the `PROVIDER_REGISTRY`, provider resolution logic, authentication methods (API key, OAuth, and Auto), and credential resolution.

ZeptoClaw uses a unified interface to interact with multiple LLM backends, primarily leveraging the OpenAI Chat Completions standard while maintaining native implementations for Anthropic's Claude API, Google Gemini, and Vertex AI.

## Overview

ZeptoClaw supports 19+ LLM providers through a unified configuration interface [src/providers/mod.rs41-60](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/providers/mod.rs#L41-L60) Each provider is defined in the `providers` section of the configuration file or via environment variables. The system is built on the `LLMProvider` trait [src/providers/types.rs84](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/providers/types.rs#L84-L84) with concrete implementations including `ClaudeProvider` [src/providers/claude.rs64](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/providers/claude.rs#L64-L64) `OpenAIProvider` [src/providers/openai.rs69](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/providers/openai.rs#L69-L69) `GeminiProvider` [src/providers/gemini.rs68](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/providers/gemini.rs#L68-L68) and `VertexProvider` [src/providers/mod.rs87](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/providers/mod.rs#L87-L87)

The `OpenAIProvider` serves as a "universal" backend for any OpenAI-compatible endpoint, including local servers like Ollama or vLLM, and cloud services like Groq, DeepSeek, and Azure.

**Sources:** [src/providers/mod.rs41-60](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/providers/mod.rs#L41-L60) [src/providers/types.rs83-85](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/providers/types.rs#L83-L85) [src/providers/mod.rs64-87](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/providers/mod.rs#L64-L87)

## Provider Registry

The `PROVIDER_REGISTRY` is a static array of `ProviderSpec` structs that serves as the single source of truth for provider metadata, default URLs, and backend routing.

### PROVIDER_REGISTRY Structure

```

```

Each `ProviderSpec` [src/providers/registry.rs11-29](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/providers/registry.rs#L11-L29) defines:

- name : The unique identifier used in config (e.g., "anthropic" , "openai" ) src/providers/registry.rs 13
- backend : The routing identifier ( "anthropic" , "openai" , or "vertex" ) determining which implementation class is instantiated src/providers/registry.rs 21
- api_key_required : Set to false for local providers like Ollama src/providers/registry.rs 144 or vLLM src/providers/registry.rs 114 and for providers using system-level auth like Vertex AI src/providers/registry.rs 134
- default_auth_header : Custom headers like api-key for Azure src/providers/registry.rs 182

**Sources:** [src/providers/registry.rs11-29](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/providers/registry.rs#L11-L29) [src/providers/registry.rs55-197](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/providers/registry.rs#L55-L197)

## Supported Providers

**Sources:** [src/providers/registry.rs55-197](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/providers/registry.rs#L55-L197) [src/providers/mod.rs41-60](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/providers/mod.rs#L41-L60) [src/kernel/provider.rs43-130](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/kernel/provider.rs#L43-L130)

## Authentication Methods

ZeptoClaw supports distinct authentication strategies for resolving credentials, defined by the `AuthMethod` enum [src/providers/registry.rs6](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/providers/registry.rs#L6-L6):

1. API Key : Uses a static string from configuration or environment variables.
2. OAuth : Resolves tokens from the system's TokenStore or provider-specific CLI tools.
3. Auto : Attempts to find an OAuth token first, falling back to an API key if none is found.

### Auth Resolution Flow

```

```

**Sources:** [src/providers/registry.rs31-50](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/providers/registry.rs#L31-L50) [src/kernel/provider.rs11-16](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/kernel/provider.rs#L11-L16) [src/providers/registry.rs6-7](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/providers/registry.rs#L6-L7)

## Provider Assembly and Resolution

The kernel assembles the final provider chain using `build_provider_chain` [src/kernel/provider.rs23-30](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/kernel/provider.rs#L23-L30) This process handles credential refreshing and wraps the base provider in decorators.

### Provider Mapping: Selection to Entity

```

```

### Specific Provider Logic

- GeminiProvider : Even though it is categorized under the openai backend in the registry for routing, the kernel specifically intercepts selection.name == "gemini" to instantiate the native GeminiProvider src/kernel/provider.rs 59-76 This allows for native Gemini features like thinking-model filtering.
- VertexProvider : Resolves GCP Project ID from api_key and Location from api_base . It supports both VERTEX_ACCESS_TOKEN and Application Default Credentials (ADC) src/kernel/provider.rs 97-127
- Retry/Quota Decorators : The chain is wrapped in a RetryProvider src/kernel/provider.rs 28 and optionally a QuotaProvider if limits are defined in config src/kernel/provider.rs 158-160

**Sources:** [src/kernel/provider.rs23-30](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/kernel/provider.rs#L23-L30) [src/kernel/provider.rs39-130](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/kernel/provider.rs#L39-L130) [src/kernel/provider.rs145-165](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/kernel/provider.rs#L145-L165)

## Credential Resolution

The `ResolvedCredential` enum encapsulates the final authentication data passed to provider implementations [src/providers/registry.rs43](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/providers/registry.rs#L43-L43)

- ApiKey(String) : A standard API key string.
- BearerToken : Contains an OAuth access token.

### Provider-Specific Auth Resolution

- Claude : Uses ClaudeProvider::with_credential if a bearer token is available src/kernel/provider.rs 47-49 otherwise uses ClaudeProvider::new with a standard key src/kernel/provider.rs 51
- Gemini : GeminiProvider::from_config handles the full auth priority chain: config key → GEMINI_API_KEY → GOOGLE_API_KEY → Gemini CLI OAuth src/kernel/provider.rs 61-75
- Vertex : api_key holds the GCP project ID, while auth is handled via VERTEX_ACCESS_TOKEN or ADC src/kernel/provider.rs 100-114

**Sources:** [src/kernel/provider.rs39-130](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/kernel/provider.rs#L39-L130) [src/providers/registry.rs31-50](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/providers/registry.rs#L31-L50)

## Error Handling

Provider errors are unified via `parse_provider_error` [src/providers/mod.rs93-125](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/providers/mod.rs#L93-L125) This function maps HTTP status codes to a structured `ProviderError` enum.

- 401 : ProviderError::Auth src/providers/mod.rs 95
- 402 : ProviderError::Billing src/providers/mod.rs 96
- 429 : ProviderError::RateLimit src/providers/mod.rs 98
- 400 : Classified via classify_error_message to distinguish between Format errors and ContextOverflow src/providers/mod.rs 99-110
- 5xx : Maps to ProviderError::ServerError unless identified as Overloaded src/providers/mod.rs 111-119

**Sources:** [src/providers/mod.rs89-125](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/providers/mod.rs#L89-L125) [src/providers/mod.rs66](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/providers/mod.rs#L66-L66)
