Keyboard shortcuts

Press ← or → to navigate between chapters

Press ? to show this help

Press Esc to hide this help

提供程序配置

每个模型提供方都位于 [providers.models.<type>.<alias>]。<type> 是规范的系列槽位（参见 Catalog 查看每个槽位及其端点）。<alias> 是你作为运维人员指定的实例名称，可以选择任意具有描述性的名称（home、work、cn、gpt5……）。

最小可运行示例

加载无误的最小配置包含四个节标题：一个 provider 条目、一个引用该条目的 agent，以及一个 agent 据以进行门控的风险配置。可通过 gateway、zerocode 或 zeroclaw config set 进行配置；配置参考中有完整的字段索引。

字段参考：提供程序条目

几乎每个 family 也会从 ModelProviderConfig 中获取共享字段：

  • api_key：用于使用 bearer 或订阅式 API 密钥的提供方的凭据。
  • uri：完整端点覆盖。保持未设置以使用该 family 的端点解析器。
  • model：发送给提供方的模型标识符。
  • temperature：可选的采样温度。
  • timeout_secs: HTTP 请求超时时间（秒）。
  • max_tokens：可选的响应长度上限。
  • extra_headers：用于自定义网关或认证桥接的额外 HTTP 标头。
  • fallback_models：同一提供程序别名上的备用模型 ID。
  • fallback：在此别名失败后要尝试的其他带点的 provider 别名有序列表。
  • wire_api, native_tools, provider_extra, think, and chat_template_kwargs：高级协议和请求体覆盖。
  • vision: 覆盖提供商的图像输入（视觉）能力。保持未设置以使用该系列的内置默认值。对于由具备视觉能力的系列提供服务的纯文本模型（例如，位于 llama.cpp 后面的文本模型），设置为 false，以便图像消息路由到已配置的 [multimodal] vision_model_provider，而不是报错；设置为 true 可强制启用它。
  • tool_result_image_policy：用于处理发送到兼容聊天补全提供商的原生 role = "tool" 结果中的图像标记。默认为"image_url"；设置为"omit"可移除图像 URI/base64 负载并附加固定提示。不会更改直接用户图像或 OpenAI Responses 提供商。
  • tls_ca_cert_path：用于与此提供程序建立 TLS 连接的 PEM 编码 CA 证书的绝对路径（按提供程序的信任覆盖，区别于网关 TLS 的 ca_cert_path）。不会执行诸如 ~ 之类的 Shell 展开；留空则使用系统信任存储。

特定 family 的条目会在这些共享字段之上添加它们自己的类型化字段。

字段解析顺序

对于大多数系列，URL 按以下顺序解析：

  1. 运算符覆盖：别名条目上的 uri 字段（如果已设置）。
  2. Family 端点：该 family 的 *Endpoint 枚举提供 URL（例如 OpenAIEndpoint::Default -> https://api.openai.com/v1）。多区域 family 在别名条目上有一个 endpoint 字段，用于选择变体（例如 Moonshot 的 endpoint = "cn"）。
  3. 模板化家族：Azure 接受类型化输入（resource、deployment、api_version），并将其替换到家族的 URI 模板中。缺少字段时，运行时会立即报错。

Bedrock 是个例外：其端点主机名会在请求时根据通过 AWS 凭证链解析出的签名区域构造（该区域来自 AWS_REGION、AWS_DEFAULT_REGION，或活动 credential_process 或 IMDS 配置文件中的 region）。uri 别名字段以及 schema 级别的 providers.models.bedrock.<alias>.region 字段在当前实现中不起作用。

家庭席位

每个槽位、其默认端点以及是否在本地运行均记录在目录中。每个供应商只有一个规范键名：不设同义词。

凭证

支持的凭据输入和存储形式：

  1. 内联 api_key = "..."，置于别名条目中（开发时尚可，但对于提交到版本库的配置存在风险）。
  2. 1Password 引用：将密钥字段设置为 op://vault/item/field。ZeroClaw 会在配置中保留该引用，并在运行时通过 op read 解析它，因此必须安装并登录 1Password CLI。
  3. 配置级密钥存储：通过本地密钥文件在 ~/.zeroclaw/secrets 中加密存储。
  4. 通用环境变量覆盖：ZEROCLAW_providers__models__<type>__<alias>__api_key=... 会在启动时设置 providers.models.<type>.<alias>.api_key。完整的语法规则请参阅环境变量。

架构镜像环境变量覆盖在启动时优先生效。它们会替换该进程的内存凭据，而不会重写磁盘上存储的内联、加密或 op:// 值。

zeroclaw quickstart 默认将凭据写入密钥存储。你提交的配置不应包含内联密钥。对于你已在 shell 中导出的生态系统默认名称（$ANTHROPIC_API_KEY、$OPENROUTER_API_KEY 等），env-vars 参考文档展示了将 schema-mirror 名称指向现有值的单行 bash 展开式。

OAuth 和订阅认证

一些提供商接受 OAuth 或订阅式令牌，而非原始 API 密钥。请从供应商自己的仪表板或 CLI 流程中获取令牌，然后像填写 API 密钥那样将其填入别名条目：

  • Anthropic / Claude: 由 claude setup-token 为 Claude Max 生成的控制台 API 密钥和令牌应填写到 [providers.models.anthropic.<alias>] 中的 api_key。在 Quickstart 中，选择 api_key 或 setup_token；已保存的提供商条目仍然是规范的 anthropic 插槽。
  • OpenAI Codex 订阅：运行 zeroclaw auth login --model-provider openai-codex（或使用 --import ~/.codex/auth.json 导入现有的 Codex CLI 登录），然后将 requires_openai_auth = true 设为启用，并在 [providers.models.openai.<alias>] 上保持 api_key 未设置；运行时会读取 ZeroClaw 存储的 openai-codex 认证配置文件。
  • Gemini CLI：[providers.models.gemini_cli.<alias>] 会调用 gemini CLI；请使用该 CLI 自带的认证流程。
  • Grok Build CLI：[providers.models.grok_cli.<alias>] 会通过文档所述的 grok agent stdio ACP 接口调用外部进程。组装后的提示词以 JSON-RPC 形式通过 stdin 传入，绝不会通过 argv 或提示词文件传递。默认情况下，身份验证使用 CLI 登录缓存。对于 API 密钥身份验证，请将 XAI_API_KEY 导出到守护进程环境中，并将 env_passthrough = ["XAI_API_KEY"] 明确添加到别名配置中；类型化别名 api_key 仍不受支持。必须指定一个已存在的绝对 working_directory，它同时定义子进程 cwd 和 ACP 会话边界。子进程启动前会清空其环境，env_passthrough 默认为空。其他提供商自有的 XAI_* 名称以及所有 GROK_* 名称都会被拒绝。ZeroClaw 默认使用 --sandbox strict、--permission-mode dontAsk、空的内置工具集以及失败关闭的 ACP 权限响应。extra_args 是按别名显式选择放宽这些控制的方式。绕过标志 --always-approve、--dangerously-skip-permissions、--yolo 和 --permission-mode=bypassPermissions 会使无头 ACP 客户端选择 allow_once；其他权限模式仍选择 reject_once。ACP 传输、模型、会话和 cwd 标志，以及位置参数和短参数均为保留项；未知的取值型长选项使用 --flag=value。别名 vision = true 仅会让 ZeroClaw 选择发送 ACP 图像块；截至 0.2.118，Grok 仍宣称 promptCapabilities.image = false，并且无法可靠地使用图像内容 - 生产环境请勿设置；请参阅 ACP 视觉 / 图像输入。
  • Qwen / MiniMax：在别名条目中设置 auth_mode = "o_auth"，并添加相关的 oauth_* 字段（参见 env-vars → OAuth 和 CLI 路径字段）。

容器友好的覆盖

当 ZeroClaw 在容器内运行而提供商位于主机上（例如 Ollama）时，请将 uri 设置为主机可访问的地址。通用的环境变量覆盖机制（ZEROCLAW_<dotted_path_with_double_underscores>=<value>）可以在运行时设置同一字段，而无需编辑配置：

sh

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

__ 是路径分隔符；上面的示例设置了 providers.models.ollama.home.uri。完整语法请参阅环境变量。

每个模型的视觉能力

当某个提供商系列可以同时支持多模态和纯文本模型时，请使用 vision。该值属于提供商别名，因此路由和回退路径会将其与该别名的端点、凭据和模型一起解析：

[providers.models.openai.vision]
model = "gpt-4o"
wire_api = "responses"
vision = true

[providers.models.llamacpp.text]
model = "qwen3-4b"
vision = false

不设置 vision 会保留提供商系列内置的默认值。对于 OpenAI Responses 别名，请为接受图像输入的模型设置 vision = true；此显式启用可避免仅支持文本的 Responses 模型意外接收图像负载。

设置 vision = true 表示操作员明确声明所选别名接受图像输入。它会改变图像路由：ZeroClaw 会将图像附件保留在该别名上，而不是将其视为纯文本，或将其路由到 multimodal.vision_model_provider。仅在经过测试的 provider 和模型组合上设置此项。对于 grok_cli，同一字段仅控制 ZeroClaw 是否 发送 ACP 图像块；它不会重写 Grok 的 promptCapabilities.image 声明（截至 0.2.118 仍为 false），也不会让 CLI 可靠地描述图像。请参阅 ACP 视觉 / 图像输入。

当 [multimodal] vision_model_provider 指定带点号的提供方别名时，会自动使用其 model。显式设置的 [multimodal] vision_model 优先级高于别名中的模型；若两者均未设置，则使用主对话轮次模型以保持向后兼容。

原生思考显示（Anthropic）

agent.thinking.display 控制启用原生思考时 Anthropic 扩展思考的传递方式（agent.thinking.native_thinking = true）。可接受的值：

  • off（默认）：不发送 display 字段；请求与早期 ZeroClaw 版本逐字节一致，思考请求使用非流式回退。
  • omitted：Anthropic 会从响应中省略思考文本；块仅包含签名（thinking 为空，但包含必需的 signature），在保持回放完整性的同时，尽量减少可见的推理内容。
  • updates：请求携带 thinking-display-updates-2026-08-18 beta，并使用流式响应路径。模型工作时，可读的思考进度会实时呈现；已签名的推理载荷会单独保留，用于历史记录重放，且绝不会显示。
  • summarized：相同的流式传输行为，请求摘要形式的思考。
[agent.thinking]
native_thinking = true
display = "updates"

此设置要求使用已加入 thinking-display-updates beta 的 Anthropic 账户；未加入时，API 会拒绝请求。将 display = "off"（或移除该字段）即可恢复之前的线路行为。

各系列调节项：实例演示

Ollama

Ollama 默认使用本地端点，因此本地别名只需要模型名称：

[providers.models.ollama.local]
model = "llama3.1"

当 ZeroClaw 不是运行在与 Ollama 相同的主机上时，请设置 uri：

[providers.models.ollama.host]
model = "llama3.1"
uri = "http://host.docker.internal:11434"

Ollama 特定的可选字段是 num_ctx、num_predict 和 temperature_override。

Azure OpenAI

Azure OpenAI 根据输入的 Azure 字段计算其 endpoint：

[providers.models.azure.work]
api_key = "op://platform/azure-openai/api-key"
model = "gpt-4o"
resource = "example-resource"
deployment = "gpt-4o-prod"
api_version = "2024-10-21"

resource、deployment 和 api_version 值保存在这个类型化配置中，不会从 Azure 特定的环境变量中读取。仅在需要完全覆盖计算出的端点时才使用 uri。

Amazon Bedrock

Bedrock 需要一个带有模型的别名；终端节点区域当前来自 Bedrock 身份验证环境/配置文件路径：

[providers.models.bedrock.work]
model = "anthropic.claude-sonnet-4-6"

Bedrock 提供程序使用 crates/zeroclaw-providers/src/bedrock.rs 中实现的凭证路径：

  1. Bedrock 别名上的 api_key，或 BEDROCK_API_KEY，使用 Bedrock bearer-token 认证，并优先于 SigV4 凭据。
  2. AWS_ACCESS_KEY_ID 加上 AWS_SECRET_ACCESS_KEY 使用 SigV4。AWS_SESSION_TOKEN 为可选项。AWS_REGION 或 AWS_DEFAULT_REGION 用于选择签名区域，默认回退到 us-east-1。
  3. 来自 ~/.aws/config 或 AWS_CONFIG_FILE 的活动配置文件中的 credential_process 使用 SigV4。AWS_PROFILE 用于选择配置文件，默认为 default。
  4. EC2 IMDSv2 实例凭证是 SigV4 的最后回退方案。

配置架构还定义了一个 providers.models.bedrock.<alias>.region 字段，但当前实现不会读取该字段。端点区域始终从 AWS 凭证链（环境变量、credential_process 或 IMDS）中解析，如上所述。

当前 Bedrock 实现不会读取 ~/.aws/credentials 中的普通静态配置文件。~/.zeroclaw/secrets 仅存储 ZeroClaw 配置密钥（例如别名 api_key），不会为该提供程序导出 AWS_* 变量。

要通过已实现的配置文件路径复用 AWS CLI 配置文件，请在 ~/.aws/config 中放置一个 credential_process：

[profile zeroclaw-bedrock]
credential_process = /usr/bin/aws configure export-credentials --profile my-existing-profile
region = us-east-1

/usr/bin/aws 是 Debian 和 Ubuntu 上的默认路径。在其他系统上，请使用 command -v aws 得到的绝对路径。

然后使用 AWS_PROFILE=zeroclaw-bedrock 运行 ZeroClaw。有关 systemd 用户服务，请参阅服务管理。

多区域（Moonshot / Qwen / GLM / MiniMax / …）

每个系列一种类型；通过别名条目上类型化的 endpoint 字段选择区域。

自定义 OpenAI 兼容端点

custom 插槽需要 uri。请参阅自定义提供程序。

为代理选择使用哪个提供商

智能体通过点分隔的别名引用提供方。提供方条目本身不会执行任何操作。

risk_profile 和 runtime_profile 引用各自独立的别名映射，因此它们的名称不必匹配（runtime_profile 同样是可选的）。如果 model_provider 无法解析到已配置的 [providers.models.<type>.<alias>] 条目，或者 risk_profile 无法解析到已配置的 [risk_profiles.<alias>] 条目，Config::validate() 会在启动时直接报错失败。

关于将多个 agent 指向不同提供方的方法，请参阅 Routing。

失败时回退

当对某个提供方的请求在用尽重试次数后仍然失败时（提供方宕机、密钥受到速率限制、模型不可用），别名可以回退到你在别名条目中声明的备选方案。两个独立、有序的维度：

  • fallback_models：在 此 提供方上尝试的备用模型 ID，使用相同的端点、密钥和请求头。仅模型标识符会发生变化。当某个提供方提供备用模型（更小或更旧的变体）且应在完全离开该提供方之前先行尝试时，可使用此项。
  • fallback：一个由_其他_提供方别名组成的有序列表（采用点号分隔的 <type>.<alias> 形式引用 [providers.models]）。每个回退别名都会使用其自身的凭据、端点和模型进行解析，回退绝不会继承发生故障的别名所使用的密钥。

尝试顺序

遍历采用深度优先方式：在离开某个别名之前，会先穷尽该别名的整个模型列表，然后依次进入每个 fallback 别名，并递归应用该别名自身的 fallback_models 和 fallback。假设 anthropic.prod 提供 claude-sonnet-4-5，在其 fallback_models 中列出了 claude-haiku-4-5，并在其 fallback 中指定了 openai.backup（提供 gpt-4.1）。那么尝试顺序为：

anthropic.prod/claude-sonnet-4-5
  -> anthropic.prod/claude-haiku-4-5
  -> openai.backup/gpt-4.1
  -> (request fails)

后备别名本身也可以声明 fallback，因此整条链的长度取决于你的配置，最大深度为 3 个别名。如果某条链形成自循环（a -> b -> a），系统会检测到并裁剪掉形成环的那条边；如果非环链的深度超过限制，则会裁剪掉多余的链接。无论哪种情况，都不会出现死循环、卡死或栈溢出。

配置错误

一个 fallback 条目若指向未配置的别名、形成循环引用，或导致链路超过最大深度，均属于非致命情况：Config::validate() 仍会成功，运行时会跳过有问题的边，并将该问题作为验证警告（dangling_fallback_ref / fallback_cycle / max_fallback_depth_exceeded）在 CLI 和仪表板中显示。一个 fallback_models 条目若为空白或与该别名的主 model 重复，同样会在运行时被跳过并予以显示（empty_fallback_model / fallback_model_duplicates_primary）。错误的回退链接会优雅降级，绝不会阻止 agent 运行。

另见