自定义提供程序

三种添加 ZeroClaw 未内置的提供者的方法：

1. 使用 custom 插槽。 适用于现有规范插槽未涵盖的任何兼容 OpenAI 的端点。
2. 使用一流的本地服务器插槽（lmstudio、llamacpp、sglang、vllm、osaurus、litellm）。带有合理默认值的轻量封装。
3. 实现 ModelProvider trait（Rust）。适用于任何与 OpenAI 不兼容的场景。

OpenAI 兼容端点：使用 custom 槽位

如果该服务支持 OpenAI chat-completions，则这只需更改配置即可。custom 槽位需要 uri（该系列的端点枚举没有默认值）；请从某个 agent 的 model_provider 中引用它。

这与 groq、mistral、xai 以及在目录中拥有各自规范槽位的其他所有供应商所使用的 OpenAiCompatibleModelProvider 运行时实现相同。区别在于你使用哪个系列槽位：custom 是用于那些没有专属供应商槽位的端点的通用兜底选项。

对于无法接受包含图像的工具结果的网关，请省略这些载荷，同时保留周围的工具文本：

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

一等公民的本地推理服务器

ZeroClaw 为流行的本地推理栈提供了规范化的插槽配置。它们底层都兼容 OpenAI，但已预先应用了默认的 uri 值，因此你通常可以完全省略 uri。

llama.cpp：插槽 llamacpp

llama-server -hf ggml-org/gpt-oss-20b-GGUF --jinja -c 133000 --host 127.0.0.1 --port 8033

可选字段适用于任何 compat-slot 系列（包括 llamacpp）。完整集合源自 schema：

zeroclaw config set providers.models.custom.<alias>.api_key    # 掩码输入，加密存储

export ZEROCLAW_providers__models__custom__<alias>__api_key=

zeroclaw config set providers.models.custom.<alias>.chat_template_kwargs <value>

export ZEROCLAW_providers__models__custom__<alias>__chat_template_kwargs=

zeroclaw config set providers.models.custom.<alias>.context_window <value>

export ZEROCLAW_providers__models__custom__<alias>__context_window=

zeroclaw config set providers.models.custom.<alias>.extra_headers    # 掩码输入，加密存储

export ZEROCLAW_providers__models__custom__<alias>__extra_headers=

zeroclaw config set providers.models.custom.<alias>.fallback <value>

export ZEROCLAW_providers__models__custom__<alias>__fallback=

zeroclaw config set providers.models.custom.<alias>.fallback_models <value>

export ZEROCLAW_providers__models__custom__<alias>__fallback_models=

zeroclaw config set providers.models.custom.<alias>.kind <value>

export ZEROCLAW_providers__models__custom__<alias>__kind=

zeroclaw config set providers.models.custom.<alias>.live_pricing <value>

export ZEROCLAW_providers__models__custom__<alias>__live_pricing=

zeroclaw config set providers.models.custom.<alias>.max_tokens <value>

export ZEROCLAW_providers__models__custom__<alias>__max_tokens=

zeroclaw config set providers.models.custom.<alias>.merge_system_into_user <value>

export ZEROCLAW_providers__models__custom__<alias>__merge_system_into_user=

zeroclaw config set providers.models.custom.<alias>.model <value>

export ZEROCLAW_providers__models__custom__<alias>__model=

zeroclaw config set providers.models.custom.<alias>.native_tools <value>

export ZEROCLAW_providers__models__custom__<alias>__native_tools=

zeroclaw config set providers.models.custom.<alias>.pricing <value>

export ZEROCLAW_providers__models__custom__<alias>__pricing=

zeroclaw config set providers.models.custom.<alias>.provider_extra <value>

export ZEROCLAW_providers__models__custom__<alias>__provider_extra=

zeroclaw config set providers.models.custom.<alias>.replay_assistant_reasoning <value>

export ZEROCLAW_providers__models__custom__<alias>__replay_assistant_reasoning=

zeroclaw config set providers.models.custom.<alias>.requires_openai_auth <value>

export ZEROCLAW_providers__models__custom__<alias>__requires_openai_auth=

zeroclaw config set providers.models.custom.<alias>.temperature <value>

export ZEROCLAW_providers__models__custom__<alias>__temperature=

zeroclaw config set providers.models.custom.<alias>.think <value>

export ZEROCLAW_providers__models__custom__<alias>__think=

zeroclaw config set providers.models.custom.<alias>.timeout_secs <value>

export ZEROCLAW_providers__models__custom__<alias>__timeout_secs=

zeroclaw config set providers.models.custom.<alias>.tls_ca_cert_path <value>

export ZEROCLAW_providers__models__custom__<alias>__tls_ca_cert_path=

zeroclaw config set providers.models.custom.<alias>.tool_result_image_policy <value>

export ZEROCLAW_providers__models__custom__<alias>__tool_result_image_policy=

zeroclaw config set providers.models.custom.<alias>.uri <value>

export ZEROCLAW_providers__models__custom__<alias>__uri=

zeroclaw config set providers.models.custom.<alias>.vision <value>

export ZEROCLAW_providers__models__custom__<alias>__vision=

zeroclaw config set providers.models.custom.<alias>.wire_api <value>

export ZEROCLAW_providers__models__custom__<alias>__wire_api=

控制思考模式因模型系列而异。think = false 会设置请求中顶层的 enable_thinking 字段。某些模型（例如 Qwen3）会改为通过 chat_template_kwargs 从 Jinja 模板中读取此标志：

其他模型系列使用不同的模板变量名称，请检查您的模型的聊天模板，并在 chat_template_kwargs 下设置相应的键。

SGLang：插槽 sglang

python -m sglang.launch_server --model meta-llama/Llama-3.1-8B-Instruct --port 30000

vLLM：插槽 vllm

vllm serve meta-llama/Llama-3.1-8B-Instruct

LM Studio、Osaurus、LiteLLM

插槽 lmstudio、osaurus、litellm 遵循相同的模式，参见目录。

线路协议：wire_api = "responses"

新的 OpenAI 提供商插槽（写入配置文件 时路径为 providers.models.openai.<alias>，可由 zeroclaw quickstart 或网关/配置界面创建）默认使用 wire_api = "responses"，原因是 OpenAI 近期推出的 GPT 模型以 POST /v1/responses 作为主要传输接口。其他自带端点的插槽（custom、llamacpp 以及兼容 OpenAI 的第三方厂商）仍默认使用 chat-completions 传输接口；若某个端点仅支持 OpenAI responses 传输接口（例如部分自托管的 vLLM / TGI 部署），则需要在对应的别名条目中显式添加 wire_api = "responses" 以启用该接口。

当设置为 "responses" 时，provider 会构建为 OpenAiResponsesModelProvider（通过 responses 协议进行完整的流式工具调用），而不是 chat-completions provider。设置 "chat_completions" 可强制使用旧版传输协议。为实现向后兼容，有两种情况会在运行时继续使用 chat-completions，因此升级时任何现有设置都不会更改传输协议：

• 一个持久化的 providers.models.openai.<alias> 条目若省略 wire_api，反序列化后将视为未设置，并保持使用 chat-completions。
• 裸露的 model_provider = "openai" 引用（或指向不存在别名的点式引用）没有可读取的配置项；它由系列回退构建而成，并保持使用 chat-completions。responses 默认值仅在插槽实际写入配置时才适用。

wire_api 在自带端点系列中生效，这些系列的 wire 可由操作员配置：openai、llamacpp 和 custom（以及通用的 openai 兼容路径）。品牌厂商插槽（groq、mistral、deepseek 等）具有固定的 wire 协议并忽略该字段，但有一个例外：opencode 会遵循 wire_api = "responses"，因为 OpenCode Zen 同时提供两种 wire。在没有 uri 覆盖的情况下，OpenCode responses 路由指向 https://opencode.ai/zen/v1/responses：

[providers.models.opencode.default]
model    = "big-pickle"
wire_api = "responses"

该设置同时管理主代理路径和委托目标，因此当委托的目标别名声明了 wire_api = "responses" 时，将通过 responses 协议访问端点。

验证

无论采用哪种方法：

zeroclaw config list                          # 加载配置；任何验证失败都会输出到 stderr
zeroclaw models refresh --model-provider <type>.<alias>   # list models the endpoint advertises
zeroclaw agent -a <alias> -m "hello"          # 针对 `[agents.<alias>]` 处的 agent 进行冒烟测试

实现新的 ModelProvider trait

如果该端点不兼容 OpenAI，且不属于任何本地服务器槽位，则需要编写代码。

该 trait 位于 crates/zeroclaw-api/src/model_provider.rs：

#![allow(unused)]
fn main() {
#[async_trait]
pub trait ModelProvider: Send + Sync {
    fn name(&self) -> &str;
    fn supports_streaming(&self) -> bool { true }
    fn supports_streaming_tool_events(&self) -> bool { false }

    async fn chat(
        &self,
        messages: Vec<Message>,
        tools: Vec<ToolSchema>,
        options: ChatOptions,
    ) -> Pin<Box<dyn Stream<Item = Result<StreamEvent>> + Send>>;
}
}

实现模式：

1. 在 crates/zeroclaw-config/src/schema.rs 中定义类型化配置：

   #![allow(unused)]
   fn main() {
   pub struct MyProviderModelProviderConfig {
       #[serde(flatten)]
       pub base: ModelProviderConfig,
       pub endpoint: MyProviderEndpoint,
       // 系列特定字段
   }
   
   pub enum MyProviderEndpoint { Default }
   impl ModelEndpoint for MyProviderEndpoint {
       fn uri(&self) -> &'static str {
           match self { Self::Default => "https://my-provider.example.com/v1" }
       }
   }
   }

2. 在 crates/zeroclaw-config/src/providers.rs 中将该槽位添加到 for_each_model_provider_slot!。每个辅助函数都会自动识别新槽位。

3. 在 crates/zeroclaw-providers/src/myprovider.rs 中添加运行时实现。将 Vec<Message> 转换为传输格式，流式传输响应，并发出 StreamEvent 值。

4. 在 crates/zeroclaw-providers/src/lib.rs::create_provider_with_url_and_options 中接入工厂分支。

5. 如果该 provider 引入了较重的依赖，请在 Cargo.toml 中添加一个 feature flag。

请参阅 anthropic.rs，了解具有完全自定义 wire 格式的提供程序示例。请参阅 compatible.rs，了解 SSE 流式传输的 OpenAI 兼容模式。

故障排除

身份验证错误

• 验证 API 密钥与端点是否匹配（许多厂商使用密钥前缀：sk-、gsk_、sk-ant-）。
• 检查 uri 是否包含协议方案（http:// / https://），如果端点需要，还应包含 /v1 路径。
• 终端节点位于 VPN 或代理之后？请从 ZeroClaw 主机确认路由配置。

未找到模型

• 列出该端点所支持的功能：

  curl -sS "$URI/models" -H `Authorization: Bearer $API_KEY` | jq

连接问题

• curl -I $URI，它有响应吗？
• 防火墙、代理、出站规则？VPS 提供商有时会屏蔽出站高位端口。
• 如果是托管服务，则为供应商状态页面。

网关拒绝 temperature

某些网关（例如代理 claude-opus-4-7 的 LiteLLM proxy）在请求中只要存在 temperature 字段就会返回错误。ZeroClaw 遵循 Option 约定：如果你在配置中未设置 temperature，该字段将被完全省略于请求体之外，由后端自行选择默认值。仅在端点接受该字段时才显式设置 temperature。

另见

• 概览：提供程序模型以及每个代理的分发工作原理
• 配置：完整的 [providers.*] 架构、Azure 类型化配置、区域和 OAuth 变体
• 目录：每个规范化插槽都附带一个完整的 TOML 示例
• 开发 → 插件协议：如果插件比一等 crate 工作得更好