Struct ModelProviderConfig 

pub struct ModelProviderConfig {

    pub api_key: Option<String>,
    pub kind: Option<String>,
    pub uri: Option<String>,
    pub model: Option<String>,
    pub fallback: Vec<ModelProviderRef>,
    pub fallback_models: Vec<String>,
    pub temperature: Option<f64>,
    pub timeout_secs: Option<u64>,
    pub extra_headers: HashMap<String, String>,
    pub wire_api: Option<WireApi>,
    pub requires_openai_auth: bool,
    pub max_tokens: Option<u32>,
    pub merge_system_into_user: bool,
    pub provider_extra: Option<Value>,
    pub pricing: HashMap<String, f64>,
    pub replay_assistant_reasoning: Option<bool>,
    pub live_pricing: bool,
    pub native_tools: Option<bool>,
    pub think: Option<bool>,
    pub vision: Option<bool>,
    pub chat_template_kwargs: Option<Value>,
    pub context_window: Option<usize>,
    pub tls_ca_cert_path: Option<String>,
}

Named model_provider profile definition.

Fields

api_key: Option<String>

Secret API token for this model_provider. Grab it from the model_provider’s dashboard (OpenAI platform, Anthropic console, OpenRouter keys page, etc.). Stored via the OS keyring when possible; never commit it to config.toml directly.

kind: Option<String>

Provider implementation to instantiate for this profile. Use this when a canonical typed slot should run through a compatible implementation, e.g. [providers.models.openai.proxy] kind = "openai-compatible".

uri: Option<String>

Endpoint URI the client hits. Override the family’s default endpoint when pointing at a self-hosted gateway (LiteLLM, vLLM, Ollama), a custom proxy, or any non-standard URL. Leave unset to use the family’s default URI from its ModelEndpoint impl. Set this to the FULL endpoint URL; there is no separate path-suffix field.

model: Option<String>

Model identifier to send with each request: the ID string from the model_provider’s catalog (e.g. gpt-4o, claude-sonnet-4-5, llama-3.3-70b). Must match a model the model_provider actually serves on this account.

fallback: Vec<ModelProviderRef>

Ordered list of other provider aliases to try when every model on this alias has failed. Each entry is a dotted <type>.<alias> reference into providers.models and resolves with its own credentials, endpoint, and model. A fallback never inherits this alias’s key. The walk is depth-first: this alias’s models are exhausted first, then each fallback alias is descended in turn (applying its own fallback_models and fallback). Empty means no provider-level fallback.

fallback_models: Vec<String>

Ordered alternate models to try on THIS provider before falling over to the fallback aliases. Same endpoint, key, and headers as the primary model. Only the model identifier changes. Use this when a provider serves a backup model (e.g. a smaller or older variant) that should be tried before leaving the provider entirely. Empty means only model is tried.

temperature: Option<f64>

Sampling temperature passed to the model. Lower values (0.0–0.3) give deterministic, near-verbatim output, which fits code, routing, summarization. Higher values (0.7–1.2) give more varied output, which fits open-ended chat.

timeout_secs: Option<u64>

HTTP request timeout in seconds. Bump this for slow local model_providers (Ollama on CPU, big local models) or high-latency networks; leave unset otherwise.

extra_headers: HashMap<String, String>

Extra HTTP headers sent with every request. Niche: used for auth bridges, corporate proxies, or custom gateways that demand a tracing header. Most users never touch this; edit config.toml directly if you need it.

wire_api: Option<WireApi>

Wire protocol flavor: responses for OpenAI’s Responses API (POST /v1/responses), chat_completions for the legacy chat wire and most OpenAI-compatible gateways. New OpenAI provider slots default to responses; other families default to chat-completions (or ignore the field). Only override if you’re forcing an unusual combination.

requires_openai_auth: bool

When true, the client pulls credentials from ZeroClaw’s stored openai-codex auth profile instead of the api_key field above. Import an existing Codex CLI login with zeroclaw auth login --model-provider openai-codex --import ~/.codex/auth.json, or run zeroclaw auth login --model-provider openai-codex. Turn on only for the OpenAI Codex model_provider; leave off for standard API-key model_providers.

max_tokens: Option<u32>

Hard cap on response length in tokens. Most models enforce sensible built-in limits already; leave unset unless you specifically need to clip long outputs for cost or latency reasons.

merge_system_into_user: bool

ModelProvider-specific quirk: fold the system prompt into the first user message instead of sending a separate system role. Only needed for models that reject (or mishandle) a standalone system role, e.g. certain older Mistral variants.

provider_extra: Option<Value>

Extra JSON parameters to include in API requests. Merged at the top level of the request body, allowing provider-specific features (routing, transforms, etc.) without code changes. Example: provider_extra = { model_provider = { only = ["Anthropic"] } }

pricing: HashMap<String, f64>

Per-model pricing for cost tracking, USD per 1M tokens.

Free-form key/value map. Keys are user-defined model identifiers; an optional .input / .output suffix encodes pricing dimension when the operator wants to split rates. A bare key without a suffix is used as a flat per-token rate when neither dimension is specified. Default is empty: cost tracking falls back to “unknown” rates and only token usage is recorded.

Example: pricing = { opus = 15.0, sonnet = 3.0 } Or split: pricing = { "opus.input" = 15.0, "opus.output" = 75.0 }

replay_assistant_reasoning: Option<bool>

Whether stored assistant reasoning should be replayed on outbound assistant history messages. Some(false) strips reasoning_content and reasoning before sending. None (default) honours the provider’s built-in default (true for most compat providers, false for Groq).

live_pricing: bool

Pull live token prices for this provider’s models from its own OpenAI-compatible /models listing (the gateway is the source of truth for its prices), filling cost-tracking rates for models the operator has NOT priced under [cost.rates] / pricing. Models the gateway does not price (or providers with no HTTP /models listing at all, such as a subprocess gateway like kilocli) fall back to the public models.dev catalog. Configured rates always win; live prices only fill gaps. A background task refreshes the price snapshot hourly; the cost-recording path reads the cached snapshot and never blocks on the network. Default false: off means no fetching and behavior identical to a build without the feature.

native_tools: Option<bool>

Override the provider’s default for native tool calling. None (default) honors the provider’s built-in choice. Some(true) forces native tool calls on, Some(false) forces text-fallback. Currently consulted only by the Groq factory, which defaults to text-fallback because llama-family Groq models reject native tool calls with HTTP 400. Setting native_tools = true re-enables native tool calling for Groq models that support it.

think: Option<bool>

Enable or disable chain-of-thought thinking for models that support it (e.g. Qwen3, GLM-4). true turns thinking on, false turns it off. None (default) lets the model decide. Forwarded as enable_thinking in the request body; mirrors the Ollama provider’s think field.

vision: Option<bool>

Override the provider’s vision (image input) capability. None (default) uses the provider family’s built-in default. Several families (llama.cpp, the generic OpenAI-compatible endpoint, etc.) assume vision-capable because they can serve multimodal models. Set vision = false for a text-only model served by such a family (e.g. a text LLM behind llama.cpp) so image messages are routed to a configured [multimodal] vision_model_provider instead of being sent to a model that rejects them. Some(true) forces vision on.

chat_template_kwargs: Option<Value>

Arbitrary key/value pairs forwarded verbatim as chat_template_kwargs in the request body (llama.cpp-specific). Use this to pass model-family template variables that control behaviour not exposed by other fields. Example (Qwen3 thinking suppression): chat_template_kwargs = { enable_thinking = false }

context_window: Option<usize>

Context window size (max input tokens) for this model. Auto-populated on setup from provider’s /models endpoint if available. Override manually for custom endpoints or when auto-detection fails.

tls_ca_cert_path: Option<String>

Path to a PEM-encoded CA certificate for TLS connections to this provider. Must be an absolute path; shell expansion (e.g. ~) is not performed. Leave unset to use the system’s default trust store.

Implementations

impl ModelProviderConfig

pub fn configurable_prefix() -> &'static str

Returns the #[prefix] value for this Configurable struct.

pub fn secret_fields(&self) -> Vec<SecretFieldInfo>

Returns metadata about all #[secret] fields on this struct and nested children.

pub fn secret_field_terminals() -> Vec<&'static str>

pub fn encrypt_secrets(&mut self, store: &SecretStore) -> Result<()>

Encrypt all secret fields in place using the provided store.

pub fn decrypt_secrets(&mut self, store: &SecretStore) -> Result<()>

Decrypt all secret fields in place using the provided store.

pub fn set_secret(&mut self, name: &str, value: String) -> Result<()>

Set a secret field by its full dotted name, dispatching to nested children.

pub fn prop_fields(&self) -> Vec<PropFieldInfo>

Returns metadata about all property fields on this struct and nested children.

pub fn get_prop(&self, name: &str) -> Result<String>

Get a property value by its full dotted name, returning it as a display string.

pub fn set_prop(&mut self, name: &str, value_str: &str) -> Result<()>

Set a property value by its full dotted name, parsing from string.

pub fn prop_is_secret(name: &str) -> bool

Check if a property name refers to a secret field (static, no instance needed).

pub fn init_defaults(&mut self, prefix: Option<&str>) -> Vec<&'static str>

Instantiate None nested sections whose prefix matches. Returns the prefixes that were initialized.

pub fn map_key_sections() -> Vec<MapKeySection>

Enumerate every map-keyed (HashMap<String, T>) and list-shaped (Vec<T>) section discoverable from this Configurable’s tree. The dashboard / CLI consume this to surface “+ Add” affordances without hardcoding the section list.

pub fn nested_section_help(name: &str) -> Option<&'static str>

Help blurb for a #[nested] field on this struct, sourced from the field-level /// docstring. Returns None for unknown names so callers can fall through to a different lookup.

pub fn nested_section_group(name: &str) -> Option<&'static str>

pub fn get_map_keys(&self, section_path: &str) -> Option<Vec<String>>

Return the current alias keys at section_path, or None if the path doesn’t resolve to a map-keyed section in this tree.

pub fn nested_option_entries(&self) -> Vec<NestedOptionEntry>

pub fn create_map_key( &mut self, section_path: &str, map_key: &str, ) -> Result<bool, String>

pub fn delete_map_key( &mut self, section_path: &str, map_key: &str, ) -> Result<bool, String>

pub fn rename_map_key( &mut self, section_path: &str, map_key: &str, new_key: &str, ) -> Result<bool, String>

Trait Implementations

impl Clone for ModelProviderConfig

fn clone(&self) -> ModelProviderConfig

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ModelProviderConfig

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ModelProviderConfig

fn default() -> ModelProviderConfig

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for ModelProviderConfig

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl JsonSchema for ModelProviderConfig

fn schema_name() -> Cow<'static, str>

The name of the generated JSON Schema.

fn schema_id() -> Cow<'static, str>

Returns a string that uniquely identifies the schema produced by this type.

fn json_schema(generator: &mut SchemaGenerator) -> Schema

Generates a JSON Schema for this type.

fn inline_schema() -> bool

Whether JSON Schemas generated for this type should be included directly in parent schemas, rather than being re-used where possible using the $ref keyword.

impl MaskSecrets for ModelProviderConfig

fn mask_secrets(&mut self)

fn restore_secrets_from(&mut self, current: &Self)

impl Serialize for ModelProviderConfig

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.