Nanobot Provider Configuration Options: Complete Guide to LLM Settings

Nanobot provider configuration options are defined in the Pydantic schema at 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) 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 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:

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:

# 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, 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 and nanobot/providers/openai_compat_provider.py, with test examples available in 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 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}