提供程序配置

Every model provider lives at [providers.models.<type>.<alias>] in ~/.zeroclaw/config.toml. <type> is the canonical family slot (anthropic, openai, azure, gemini, groq, moonshot, …). <alias> is your operator-assigned instance name — pick any descriptive name (home, work, cn, gpt5, …).

Minimal working example

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:

schema_version = 3

# Provider entry. Section header is `[providers.models.<type>.<alias>]`:
#   `anthropic` = type (fixed provider family name)
#   `home`      = alias (you pick any name)
[providers.models.anthropic.home]
model = "claude-sonnet-4-6"
temperature = 0.7            # omit this line entirely to send no temperature override
                             # (required for claude-opus-4-7 — see below)
api_key = "sk-ant-..."

# Agent. Section header is `[agents.<alias>]`:
#   `assistant` = alias (you pick any name)
[agents.assistant]
model_provider = "anthropic.home"   # `<type>.<alias>` reference to the entry above
risk_profile   = "assistant"        # alias reference to the section below

# Risk profile. Section header is `[risk_profiles.<alias>]`:
#   `assistant` = must match agents.assistant.risk_profile
[risk_profiles.assistant]
level = "supervised"

# --- Alternate provider entry: claude-opus-4-7 rejects any temperature
# setting, so its `[providers.models.anthropic.<alias>]` block must omit
# the `temperature` line entirely. To switch the agent to this entry,
# set `agents.assistant.model_provider = "anthropic.opus"`.
# [providers.models.anthropic.opus]
# model = "claude-opus-4-7"
# api_key = "sk-ant-..."

The aliases (home, assistant) above are example names — substitute whatever suits your install.

Field reference — provider entry

[providers.models.<type>.<alias>]
model = "<model-id>"        # passed to the provider as the model selector

Almost every family also takes:

api_key = "..."             # or use the secrets store, or a provider-specific env var
uri     = "https://..."     # optional operator override; otherwise the family's typed endpoint enum supplies the URL

Field resolution order

For every family, the URL is resolved in this order:

1. Operator override — uri field on the alias entry, if set.
2. Family endpoint — the family’s *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).
3. Templated families — Azure and Bedrock take typed inputs (resource, deployment, api_version for Azure; region for Bedrock) and substitute them into the family’s URI template. Missing fields fail loud at runtime.

Family slots

Run cargo doc --open -p zeroclaw-config (or read crates/zeroclaw-config/src/providers.rs) for the complete list. Highlights:

There is one canonical key per vendor — no synonyms.

凭证

Three ways to supply credentials, in resolution order:

1. Inline api_key = "..." in the alias entry (fine for dev, risky for checked-in configs).
2. Config-level secrets store — encrypted at ~/.zeroclaw/secrets via a local key file.
3. Generic env override — ZEROCLAW_providers__models__<type>__<alias>__api_key=... sets providers.models.<type>.<alias>.api_key at startup. See Environment variables for the full grammar.

zeroclaw onboard 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.

OAuth 和订阅认证

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:

• Anthropic — sk-ant-oat-* OAuth tokens (from Claude Pro/Team) go in api_key on [providers.models.anthropic.<alias>].
• OpenAI Codex subscription — set requires_openai_auth = true and leave api_key unset on [providers.models.openai.<alias>]; the runtime reads the stored Codex login.
• Gemini CLI — [providers.models.gemini_cli.<alias>] shells out to the gemini CLI; use the CLI’s own auth flow.
• Qwen / MiniMax — set 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:

[providers.models.ollama.local]
uri   = "http://host.docker.internal:11434"
model = "qwen3.6:35b-a3b"

The generic env-override mechanism (ZEROCLAW_<dotted_path_with_double_underscores>=<value>) can set the same field at runtime without editing config.toml:

ZEROCLAW_providers__models__ollama__home__uri=http://ollama:11434 zeroclaw agent -a assistant

The __ is the path separator; the example above sets providers.models.ollama.home.uri. See Environment variables for the full grammar.

Per-family knobs — worked examples

Ollama

[providers.models.ollama.local]
uri              = "http://localhost:11434"
model            = "qwen3.6:35b-a3b"
think            = false                    # disable reasoning mode for faster output
reasoning_effort = "none"                   # same intent, passed as a top-level field
options          = { temperature = 0, num_ctx = 32768 }

Azure OpenAI

[providers.models.azure.work]
resource    = "my-resource"                 # template var: https://{resource}.openai.azure.com/...
deployment  = "gpt-4o"
api_version = "2024-10-01-preview"
api_key     = "..."

The resource, deployment, and api_version values live in this typed config — they are not read from environment variables.

Multi-region (Moonshot / Qwen / GLM / MiniMax / …)

Pick the region with the typed endpoint field on the alias entry:

[providers.models.moonshot.cn]
api_key  = "..."
endpoint = "cn"                             # MoonshotEndpoint::Cn -> https://api.moonshot.cn/v1

[providers.models.moonshot.intl]
api_key  = "..."
endpoint = "intl"                           # MoonshotEndpoint::Intl -> https://api.moonshot.ai/v1

One type per family; region picks via the endpoint field on the alias entry.

Custom OpenAI-compatible endpoint

[providers.models.custom.gateway]
uri     = "https://my-gateway.example.com/v1"
model   = "my-model-id"
api_key = "..."

The custom slot requires uri. See Custom providers.

Picking which provider an agent uses

Agents reference a provider by dotted alias. Provider entries on their own do nothing.

[agents.assistant]
model_provider  = "anthropic.home"   # `<type>.<alias>` into providers.models
risk_profile    = "hardened"         # alias into risk_profiles.<alias>
runtime_profile = "deep"             # alias into runtime_profiles.<alias>; independent of risk_profile

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.

另见

• 概述
• Provider catalog — concrete config example for every family
• 流式传输
• Routing
• Custom providers