# Nanobot Provider Configuration Options: Complete Guide to LLM Settings

> Explore Nanobot provider configuration options for LLM settings. This guide covers authentication, endpoint, and behavior parameters defined in the Pydantic schema.

- Repository: [✨Data Intelligence Lab@HKU✨/nanobot](https://github.com/HKUDS/nanobot)
- Tags: how-to-guide
- Published: 2026-07-22

---

**Nanobot provider configuration options are defined in the Pydantic schema at [`nanobot/config/schema.py`](https://github.com/HKUDS/nanobot/blob/main/nanobot/config/schema.py), where the `ProviderConfig` model specifies authentication, endpoint, and behavior parameters for each LLM backend.**

The HKUDS/nanobot repository uses a structured configuration system to manage connections to various LLM providers including OpenAI, Azure, Anthropic, and custom endpoints. Understanding these configuration options allows you to tailor authentication headers, proxy settings, and request formatting to your specific deployment environment.

## Core Configuration Schema

Nanobot centralizes all provider settings in two primary Pydantic models that handle validation and serialization.

### ProviderConfig Model

The `ProviderConfig` class (lines 84-107 in [`nanobot/config/schema.py`](https://github.com/HKUDS/nanobot/blob/main/nanobot/config/schema.py)) defines the parameters available for any single LLM endpoint. This model accepts standard OpenAI-compatible settings alongside Nanobot-specific extensions like `thinking_style` and `proxy`.

### ProvidersConfig Container

The `ProvidersConfig` class (lines 26-41) aggregates individual `ProviderConfig` instances into a unified hierarchy. It provides dedicated fields for built-in providers—`openai`, `azure_openai`, `anthropic`, `ollama`—while accepting arbitrary custom providers through dynamic key handling.

## Key Configuration Fields

Each `ProviderConfig` instance supports the following fields to control endpoint behavior and authentication:

- **`api_key`** (`str | None`): Authentication secret for the provider. The implementation redacts this value in string representations to prevent accidental logging of credentials.
- **`api_base`** (`str | None`): Base URL for the provider's OpenAI-compatible HTTP API (e.g., `https://api.openai.com/v1` or `http://localhost:11434/v1` for Ollama).
- **`api_type`** (`Literal["auto","chat_completions","responses"]`): Forces the request shape. According to the validation logic at lines 95-105, only the `openai` entry may specify a non-default value; all other built-in providers must use `"auto"`.
- **`extra_headers`** (`dict[str,str] | None`): Custom HTTP headers for provider-specific requirements (e.g., `APP-Code` for AiHubMix).
- **`extra_body`** (`dict[str,Any] | None`): Provider-specific extensions to the request payload.
- **`extra_query`** (`dict[str,str] | None`): Additional query-string parameters, commonly used for Azure API versioning (e.g., `{"api-version":"2023-03-15"}`).
- **`proxy`** (`str | None`): HTTP proxy URL for routing OpenAI-compatible requests through intermediate servers.
- **`thinking_style`** (`str | None`): Selects a built-in reasoning mode validated against `_VALID_THINKING_STYLES` (supports `thinking_type`, `enable_thinking`, `reasoning_split`).

## Validation Rules and Constraints

The schema enforces specific constraints to ensure compatibility across provider implementations.

**API Type Restrictions**: The validator at lines 95-105 ensures that only the generic `openai` provider entry can override the default `api_type`. Built-in providers like `azure_openai` or `anthropic` must retain `api_type="auto"` to use their specialized implementations in [`nanobot/providers/azure_openai_provider.py`](https://github.com/HKUDS/nanobot/blob/main/nanobot/providers/azure_openai_provider.py) and related modules.

**Dynamic Provider Registration**: The `convert_extra_providers` validator (lines 78-93) automatically wraps dictionary values into `ProviderConfig` objects. This allows you to add arbitrary provider keys to the configuration without modifying the source schema.

## Practical Configuration Examples

The following example demonstrates instantiating `ProvidersConfig` with multiple providers, including custom endpoints and thinking-style configurations:

```python
from nanobot.config.schema import ProvidersConfig, ProviderConfig

# Configure built-in providers with specific endpoints

cfg = ProvidersConfig(
    openai=ProviderConfig(
        api_key="sk-...", 
        api_base="https://api.openai.com/v1"
    ),
    azure_openai=ProviderConfig(
        api_key="...",
        api_base="https://my-resource.openai.azure.com",
        extra_query={"api-version": "2023-03-15"},
    ),
    anthropic=ProviderConfig(api_key="..."),
    ollama=ProviderConfig(api_base="http://localhost:11434/v1"),
    
    # Custom OpenAI-compatible endpoint with proxy

    custom=ProviderConfig(
        api_base="https://my.custom.llm/api",
        extra_headers={"X-My-Header": "demo"},
        proxy="http://localhost:8080",
    ),
    
    # Enable reasoning split for compatible providers

    openrouter=ProviderConfig(
        api_key="sk-or-test",
        thinking_style="reasoning_split",
    ),
)

# Access configuration in application code

azure_cfg: ProviderConfig = cfg.azure_openai
print(f"Azure base: {azure_cfg.api_base}")
print(f"Extra query: {azure_cfg.extra_query}")

```

You can also dynamically inject providers at runtime:

```python

# Add a completely custom provider not defined in the schema

cfg.model_extra = {
    "my_fancy_llm": {"api_key": "secret", "api_base": "https://fancy.ai/v1"}
}

# The validator converts the dict to ProviderConfig automatically

print(cfg.my_fancy_llm.api_base)   # → https://fancy.ai/v1

```

## Summary

- **Central Schema**: All Nanobot provider configuration options live in [`nanobot/config/schema.py`](https://github.com/HKUDS/nanobot/blob/main/nanobot/config/schema.py), utilizing `ProviderConfig` for individual endpoints and `ProvidersConfig` for the complete hierarchy.
- **Flexible Authentication**: Support for `api_key`, `extra_headers`, and `extra_query` accommodates diverse authentication schemes including Azure's api-version parameters and custom header requirements.
- **Proxy and Thinking Support**: Advanced options like `proxy` and `thinking_style` (validated against `_VALID_THINKING_STYLES`) enable enterprise routing and chain-of-thought injection.
- **Runtime Extensibility**: The `convert_extra_providers` validator allows arbitrary provider keys, wrapping them into `ProviderConfig` objects without schema modifications.
- **Implementation Reference**: Built-in providers are implemented in [`nanobot/providers/azure_openai_provider.py`](https://github.com/HKUDS/nanobot/blob/main/nanobot/providers/azure_openai_provider.py) and [`nanobot/providers/openai_compat_provider.py`](https://github.com/HKUDS/nanobot/blob/main/nanobot/providers/openai_compat_provider.py), with test examples available in [`tests/providers/test_xiaomi_mimo_thinking.py`](https://github.com/HKUDS/nanobot/blob/main/tests/providers/test_xiaomi_mimo_thinking.py).

## Frequently Asked Questions

### How do I configure a custom LLM provider in Nanobot?

Add an arbitrary key to the `providers` configuration object with the required `api_base` and authentication fields. The `convert_extra_providers` validator in [`nanobot/config/schema.py`](https://github.com/HKUDS/nanobot/blob/main/nanobot/config/schema.py) automatically wraps the dictionary into a `ProviderConfig` instance. For OpenAI-compatible endpoints, specify `api_base` and optional `extra_headers` or `proxy` settings.

### What is the difference between `api_base` and `api_type` in Nanobot?

The `api_base` parameter defines the root URL for the provider's HTTP endpoint (e.g., `https://api.openai.com/v1`), while `api_type` controls the request payload structure. Only the generic `openai` provider entry may specify non-default `api_type` values (`chat_completions` or `responses`); specialized providers like Azure or Anthropic must use `api_type="auto"` to trigger their specific implementations.

### How does Nanobot handle authentication headers for providers?

Nanobot extracts the `api_key` from `ProviderConfig` for standard Bearer token authentication, while the `extra_headers` dictionary allows injection of custom headers required by specific providers (such as `X-My-Header` or `APP-Code`). The `api_key` field is automatically redacted in object representations to prevent credential leakage in logs.

### Can I use environment variables for Nanobot provider configuration?

While the schema defines the structure in [`nanobot/config/schema.py`](https://github.com/HKUDS/nanobot/blob/main/nanobot/config/schema.py), Nanobot typically loads configuration from JSON files (e.g., `~/.nanobot/config.json`). You can programmatically instantiate `ProvidersConfig` with environment variables by passing them to the `ProviderConfig` constructor, or by modifying `model_extra` at runtime to inject credentials from your environment.