docs/book/src/providers/configuration.md
Every model provider lives at [providers.models.<type>.<alias>]. <type> is a canonical family slot (see the Catalog for every slot with its endpoint). <alias> is your operator-assigned instance name, pick any descriptive name (home, work, cn, gpt5, ...).
The smallest config that loads clean has four section headers: a provider entry, an agent that references it, and a risk profile the agent gates against. Configure them through the gateway, zerocode, or zeroclaw config set; the config reference has the full field index.
Almost every family also takes:
For every family, the URL is resolved in this order:
uri field on the alias entry, if set.*Endpoint enum supplies the URL (e.g. OpenAIEndpoint::Default -> https://api.openai.com/v1). Multi-region families have an endpoint field on the alias entry that picks the variant (e.g. endpoint = "cn" for Moonshot).resource, deployment, api_version for Azure; region for Bedrock) and substitute them into the family's URI template. Missing fields fail loud at runtime.Every slot, its default endpoint, and whether it runs locally is in the Catalog. There is one canonical key per vendor: no synonyms.
Supported credential input and storage forms:
api_key = "..." in the alias entry (fine for dev, risky for checked-in configs).op://vault/item/field. ZeroClaw keeps the reference in config and resolves it at runtime with op read, so the 1Password CLI must be installed and signed in.~/.zeroclaw/secrets via a local key file.ZEROCLAW_providers__models__<type>__<alias>__api_key=... sets providers.models.<type>.<alias>.api_key at startup. See Environment variables for the full grammar.Schema-mirror env overrides win at startup. They replace the in-memory credential for that process without rewriting the stored inline, encrypted, or op:// value on disk.
zeroclaw quickstart writes credentials to the secrets store by default. Configs you commit should not contain inline keys. For ecosystem-default names you already export in your shell ($ANTHROPIC_API_KEY, $OPENROUTER_API_KEY, …), the env-vars reference shows the one-line bash expansions that point a schema-mirror name at the existing value.
Several providers accept OAuth or subscription-style tokens instead of raw API keys. Get the token from the vendor's own dashboard or CLI flow, then drop it into the alias entry the same way you would an API key:
sk-ant-oat-* OAuth tokens (from Claude Pro/Team) go in api_key on [providers.models.anthropic.<alias>].requires_openai_auth = true and leave api_key unset on [providers.models.openai.<alias>]; the runtime reads the stored Codex login.[providers.models.gemini_cli.<alias>] shells out to the gemini CLI; use the CLI's own auth flow.auth_mode = "oauth" on the alias entry plus the relevant oauth_* fields (see env-vars → OAuth and CLI-path fields).When ZeroClaw runs inside a container and a provider is on the host (e.g. Ollama), set uri to a host-reachable address. The generic env-override mechanism (ZEROCLAW_<dotted_path_with_double_underscores>=<value>) can set the same field at runtime without editing config:
{{#env-var container}}
The __ is the path separator; the example above sets providers.models.ollama.home.uri. See Environment variables for the full grammar.
The resource, deployment, and api_version values live in this typed config, they are not read from environment variables.
One type per family; pick the region via the typed endpoint field on the alias entry.
The custom slot requires uri. See Custom providers.
Agents reference a provider by dotted alias. Provider entries on their own do nothing.
risk_profile and runtime_profile reference independent alias maps, so their names need not match (runtime_profile is also optional). Config::validate() fails loud at startup if model_provider doesn't resolve to a configured [providers.models.<type>.<alias>] entry, or if risk_profile doesn't resolve to a configured [risk_profiles.<alias>] entry.
For multiple agents pointing at different providers, see Routing.
When a request to a provider fails after exhausting its retries (provider down, key rate-limited, model unavailable), the alias can fall over to alternatives you declare on the alias entry. Two independent, ordered axes:
fallback_models: alternate model IDs tried on this provider, using the
same endpoint, key, and headers. Only the model identifier changes. Use it when
a provider serves a backup model (a smaller or older variant) that should be
tried before leaving the provider entirely.fallback: an ordered list of other provider aliases (dotted
<type>.<alias> references into [providers.models]). Each fallback alias
resolves with its own credentials, endpoint, and model, a fallback never
inherits the failing alias's key.The walk is depth-first: an alias's entire model list is exhausted before leaving
it, then each fallback alias is descended in turn, applying that alias's own
fallback_models and fallback recursively. Suppose anthropic.prod serves
claude-sonnet-4-5, lists claude-haiku-4-5 in its fallback_models, and
names openai.backup (serving gpt-4.1) in its fallback. The attempt order
is then:
anthropic.prod/claude-sonnet-4-5
-> anthropic.prod/claude-haiku-4-5
-> openai.backup/gpt-4.1
-> (request fails)
Fallback aliases can themselves declare fallback, so the chain is as long as
your config makes it, up to a maximum depth of 3 aliases. A chain that loops
back on itself (a -> b -> a) is detected and the cycle edge is pruned, and
an acyclic chain deeper than the limit has its remaining links pruned; neither
ever loops, hangs, or overflows the stack.
A fallback entry that names an alias which is not configured, one that closes a
cycle, or a chain that exceeds the maximum depth is non-fatal:
Config::validate() still succeeds, the offending edge is skipped at runtime, and
the issue is surfaced as a validation warning (dangling_fallback_ref /
fallback_cycle / max_fallback_depth_exceeded) on the CLI and in the dashboard.
A fallback_models entry that is blank or duplicates the alias's primary model
is likewise skipped at runtime and surfaced (empty_fallback_model /
fallback_model_duplicates_primary). A bad fallback link degrades gracefully, it
never prevents the agent from running.