配置 — 自定义提供商和 base URLs

在 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 值优先。
仅当该提供商在当前配置/身份验证配置文件中不是由 SecretRef 管理时，代理中非空的 apiKey 值才优先。
由 SecretRef 管理的提供商 apiKey 值会从源标记刷新（环境变量引用使用 ENV_VAR_NAME，文件/执行/存储引用使用 secretref-managed），而不是持久化已解析的密钥。
由 SecretRef 管理的提供商请求头值会从源标记刷新（环境变量引用使用 secretref-env:ENV_VAR_NAME，文件/执行/存储引用使用 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 请求超时时间（秒），包括连接、请求头、请求体以及总请求中止处理。
models.providers.*.injectNumCtxForOpenAICompat：对于 Ollama + openai-completions，将 options.num_ctx 注入请求（默认：true）。
models.providers.*.authHeader：在需要时强制通过 Authorization 请求头传输凭据。
models.providers.*.baseUrl：上游 API 基础 URL。
models.providers.*.headers：用于代理/租户路由的额外静态请求头。

请求传输覆盖

models.providers.*.request：模型提供商 HTTP 请求的传输覆盖。

request.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`	接受推理强度控制。
`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`	列出端点接受的推理标签。
`reasoningEffortMap`	将 OpenClaw 思考标签映射到端点特定标签。
`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 系列负载。

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：用于定向发现的可选提供商 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