配置 — 自定义提供商和基础 URL
在 models.providers 下注册自定义提供商、自定义 baseUrl 对网络信任的含义,以及完整的提供商字段参考。有关完整配置示例,请参阅 提供商示例。
自定义提供商和基础 URL¶
提供商插件会发布自己的模型目录条目。通过配置中的 models.providers 或 ~/.openclaw/agents/<agentId>/agent/models.json 添加自定义提供商。
配置自定义/本地提供商的 baseUrl 也是模型 HTTP 请求的精确网络信任决策:OpenClaw 通过受保护的 fetch 路径允许该精确的 scheme://host:port 源,无需添加单独的配置选项,也不会信任其他私有源。
{
models: {
mode: "merge", // merge (default) | replace
providers: {
"custom-proxy": {
baseUrl: "http://localhost:4000/v1",
apiKey: "LITELLM_KEY",
api: "openai-completions", // openai-completions | openai-responses | anthropic-messages | google-generative-ai | etc.
models: [
{
id: "llama-3.1-8b",
name: "Llama 3.1 8B",
reasoning: false,
input: ["text"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 128000,
contextTokens: 96000,
maxTokens: 32000,
},
],
},
},
},
}
身份验证和合并优先级
- 对于自定义身份验证需求,使用
authHeader: true+headers。 - 使用
OPENCLAW_AGENT_DIR覆盖代理配置根目录。 - 对于匹配的提供商 ID,合并优先级如下:
- 非空的代理
models.json中的baseUrl值优先。 - 非空的代理
apiKey值仅在当前配置/身份验证配置文件上下文中该提供商未由 SecretRef 管理时优先。 - 由 SecretRef 管理的提供商
apiKey值会从源标记刷新(环境引用使用ENV_VAR_NAME,文件/exec/store 引用使用secretref-managed),而不是持久化已解析的机密。 - 由 SecretRef 管理的提供商 header 值会从源标记刷新(环境引用使用
secretref-env:ENV_VAR_NAME,文件/exec/store 引用使用secretref-managed)。 - 为空或缺失的代理
apiKey/baseUrl会回退到配置中的models.providers。 - 匹配的模型
contextWindow/maxTokens:当显式配置值存在且有效(正有限数)时优先;否则使用隐式/生成的目录值。 - 匹配的模型
contextTokens遵循相同的显式优先、否则隐式规则;使用它来限制有效上下文,而不更改原生模型元数据。 - 提供商插件目录作为生成的插件拥有的目录分片存储在代理的插件状态下。
- 当希望配置完全重写
models.json并跳过合并插件拥有的目录分片时,使用models.mode: "replace"。 - 标记持久化以源为权威:标记从活动源配置快照(解析前)写入,而不是从已解析的运行时机密值写入。
提供商字段详情¶
顶层目录
models.mode:提供商目录行为(merge或replace)。models.providers:以提供商 ID 为键的自定义提供商映射。- 安全编辑:对于增量更新,使用
openclaw config set models.providers.<id> '<json>' --strict-json --merge或openclaw config set models.providers.<id>.models '<json-array>' --strict-json --merge。除非传入--replace,否则config set会拒绝破坏性替换。
提供商连接和身份验证
models.providers.*.api:请求适配器(openai-completions、openai-responses、openai-chatgpt-responses、anthropic-messages、google-generative-ai、google-vertex、github-copilot、bedrock-converse-stream、ollama、pi-messages、azure-openai-responses)。pi-messages使用提供商拥有的原生消息传输,由 Radius 插件 提供。对于自托管的/v1/chat/completions后端(例如 MLX、vLLM、SGLang 以及大多数 OpenAI 兼容本地服务器),使用openai-completions。具有baseUrl但没有api的自定义提供商默认使用openai-completions;仅当后端支持/v1/responses时设置openai-responses。models.providers.*.apiKey:提供商凭据(优先使用 SecretRef/环境变量替换)。models.providers.*.auth:身份验证策略(api-key、token、oauth、aws-sdk)。models.providers.*.maxTokens:当模型条目未设置maxTokens时,该提供商下模型的默认输出 token 上限。models.providers.*.timeoutSeconds:可选的按提供商的模型 HTTP 请求超时时间(秒),包括连接、headers、body 和总请求中止处理。models.providers.*.injectNumCtxForOpenAICompat:对于 Ollama +openai-completions,将options.num_ctx注入请求(默认:true)。models.providers.*.authHeader:在需要时强制通过Authorizationheader 传输凭据。models.providers.*.baseUrl:上游 API 基础 URL。models.providers.*.headers:用于代理/租户路由的额外静态 headers。
请求传输覆盖
models.providers.*.request:模型提供商 HTTP 请求的传输覆盖。
request.headers:额外 headers(与提供商默认值合并)。值接受 SecretRef。request.auth:身份验证策略覆盖。模式:"provider-default"(使用提供商内置身份验证)、"authorization-bearer"(配合token)、"header"(配合headerName、value,可选prefix)。request.proxy:HTTP 代理覆盖。模式:"env-proxy"(使用HTTP_PROXY/HTTPS_PROXY环境变量)、"explicit-proxy"(配合url)。两种模式都接受可选的tls子对象。request.tls:直接连接的 TLS 覆盖。字段:ca、cert、key、passphrase(均接受 SecretRef)、serverName、insecureSkipVerify。request.allowPrivateNetwork:当为true时,允许受保护的模型提供商 HTTP 和 WebSocket 请求通过共享私有网络策略访问私有、CGNAT 或类似范围。自定义/本地提供商基础 URL 已经信任精确配置的源,但元数据、链路本地和本地使用 NAT64(64:ff9b:1::/48)源除外,这些源在没有显式选择加入时仍会被阻止。将其设置为false可退出精确源信任。默认false。
模型目录条目
models.providers.*.models:显式的提供商模型目录条目和元数据覆盖。在合并模式下,这些行不会限制符合条件的提供商发现。使用agents.defaults.modelPolicy.allow(或按代理的策略)来限制选择,或使用models.mode: "replace"仅使用已配置清单而不进行发现。models.providers.*.models.*.input:模型输入模态。纯文本模型使用["text"],原生图像/视觉模型使用["text", "image"]。只有当所选模型被标记为支持图像时,图像附件才会注入到代理轮次中。models.providers.*.models.*.contextWindow:该模型的原生上下文窗口元数据。models.providers.*.models.*.contextTokens:该模型可选的活跃输入上限;当你希望有效预算不同于模型原生contextWindow时使用它;当两者不同时,openclaw models list会同时显示两者。
自定义提供商能力声明¶
提供商目录负责捆绑和目录已知模型路由的 compat。不要将这些标志复制到配置中:当配置的 api 和 baseUrl 仍能识别该路由时,OpenClaw 会使用目录行。openclaw doctor --fix 会移除匹配的旧版覆盖,并报告存在差异的值以供审查。
对于真正的自定义提供商、自定义模型,或路由到不同端点的目录模型,compat 块仍然受支持。只设置已针对该端点验证过的能力:
| 自定义路由键 | 运行时契约 |
|---|---|
supportsStore |
接受 OpenAI store 请求字段。 |
supportsPromptCacheKey |
接受 OpenAI 提示缓存/会话亲和性键。 |
supportsDeveloperRole |
接受 developer 消息,而不要求 system。 |
supportsReasoningEffort |
接受推理强度控制。自定义 openai-completions 路由默认会为标记为 reasoning: true 的模型启用此项;设置 false 可退出。 |
supportsTemperature |
接受此模型和适配器的 temperature。 |
supportsUsageInStreaming |
在流式响应中发出用量元数据。 |
supportsInstructions |
仅 Responses API:接受通过顶层 instructions 而不是嵌入在 input 中传递的系统提示。仅原生 OpenAI 和 xAI 的主路由默认为 true——这两个路由具有已确认的契约证据。其他所有路由,无论是捆绑的还是自定义的,默认均为 false;在针对该端点验证后显式设置。 |
supportsTools |
支持结构化工具/函数调用。设置 false 可禁用工具。 |
supportsStrictMode |
接受 strict 工具字段。在兼容的 Completions 和 Responses 路由上,true 允许显式 strict: false,以便可选工具参数保持可选。 |
requiresStringContent |
要求 Chat Completions 消息内容为纯字符串。 |
strictMessageKeys |
要求发出的消息仅包含已接受的键。 |
visibleReasoningDetailTypes |
指定可在转录中安全显示的推理详情块类型。 |
supportedReasoningEfforts |
列出端点接受的推理标签。请求会被限制在此阶梯内。未知模型默认为 low、medium 和 high。 |
reasoningEffortMap |
将 OpenClaw 思考标签映射到端点特定标签。自定义 Completions 路由默认在 off 时省略强度;显式的 off 映射可以发送端点接受的禁用值。 |
maxTokensField |
选择 max_tokens 或 max_completion_tokens。 |
thinkingFormat |
选择端点的推理负载方言。 |
requiresToolResultName |
要求工具结果消息包含工具名称。 |
requiresAssistantAfterToolResult |
要求工具结果之后包含助手消息。 |
requiresThinkingAsText |
以文本形式重放推理,而不是结构化内容。 |
requiresReasoningContentOnAssistantMessages |
在重放期间保留 DeepSeek 风格的 reasoning_content。 |
toolSchemaProfile |
选择工具模式规范化配置文件。自定义模型条目识别 llamacpp 和 gemini。llamacpp 配置文件会移除大于或等于 2000 的 pattern 和 maxLength 值;内置 llama-cpp、ollama 和 lmstudio 提供商会自动应用相同的清理器。指向 llama-server 的自定义提供商 ID 必须显式选择它。参见 llama.cpp 示例。 |
unsupportedToolSchemaKeywords |
在发送工具模式之前,移除端点拒绝的指定 JSON Schema 关键字。对于超出配置文件目标转换的端点特定缺口,请使用此项。 |
toolCallArgumentsEncoding |
选择端点的工具调用参数编码。 |
requiresOpenAiAnthropicToolPayload |
将 OpenAI 格式的工具调用转换为 Anthropic 系列负载。 |
升级后,现有自定义 openai-completions 模型如果带有 reasoning: true,除非显式退出,否则在启用思考时开始发送 reasoning_effort。如果服务器拒绝该字段,请求错误会指明补救措施:在 models.providers.<provider>.models 中的该条目上设置 compat.supportsReasoningEffort: false。有关强度映射和 /think off 行为,参见 自定义端点思考。
未知远程 openai-completions 端点默认 supportsUsageInStreaming: false,因此 OpenClaw 不会请求 stream_options.include_usage。回环端点以及捆绑的 llama.cpp、LM Studio、Ollama 和 vLLM 提供商已经请求或收集用量。对于支持此选项的自定义远程服务器,请在每个模型条目上设置 compat.supportsUsageInStreaming: true。启用此选项后,Ollama /v1 和 LM Studio 会返回流式用量。
当成功的流未返回用量时,OpenClaw 会将提供商上下文用量标记为不可用,以便压缩使用内容估算,而不是将缺失的计数视为零。估算值是近似的;无法从缺失的用量记录中恢复令牌和成本核算。禁用流式用量的自定义远程端点还会每个模型记录一次 <provider>/<model> returned no token usage,并附带上述配置提示。
Amazon Bedrock 发现
plugins.entries.amazon-bedrock.config.discovery: Bedrock 自动发现设置根。plugins.entries.amazon-bedrock.config.discovery.enabled: 开启或关闭隐式发现。plugins.entries.amazon-bedrock.config.discovery.region: 用于发现的 AWS 区域。plugins.entries.amazon-bedrock.config.discovery.providerFilter: 用于定向发现的可选 provider-id 过滤器。plugins.entries.amazon-bedrock.config.discovery.refreshInterval: 发现刷新的轮询间隔。plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow: 已发现模型的后备上下文窗口。plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens: 已发现模型的后备最大输出 Token 数。
交互式自定义提供商引导会针对已知的视觉模型 ID 模式推断是否支持图像输入,包括 GPT-4o/GPT-4.1/GPT-5+、o1/o3/o4 推理系列、Claude、Gemini、任何以 -vl 结尾的 ID(Qwen-VL 及类似模型),以及 LLaVA、Pixtral、InternVL、Mllama、MiniCPM-V 和 GLM-4V 等命名系列;对于已知的纯文本系列(Llama、DeepSeek、Mistral/Mixtral、Kimi/Moonshot、Codestral、Devstral、Phi、QwQ、CodeLlama,以及不带 vl/vision 后缀的裸 Qwen ID),它会跳过额外提问。未知模型 ID 仍会提示是否支持图像。非交互式引导使用相同的推断;传入 --custom-image-input 可强制使用支持图像的元数据,或传入 --custom-text-input 强制使用纯文本元数据。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw