配置——工具和自定义提供商

提供商条目（type: "provider" 或省略）：

• provider：API 提供商 ID（openai、anthropic、google/gemini、groq 等）
• model：模型 ID 覆盖值
• profile / preferredProfile：选择 auth-profiles.json 配置文件

CLI 条目（type: "cli"）：

• command：要运行的可执行文件
• args：模板化参数（支持 {{MediaPath}}、{{Prompt}}、{{MaxChars}} 等；openclaw doctor --fix 会将已弃用的 {input} 占位符迁移为 {{MediaPath}}）

通用字段：

• capabilities：可选列表（image、audio、video）。每个提供商插件都会声明自己的默认能力集；例如，内置的 openai 提供商默认为图像和音频，anthropic/minimax 默认为图像，google 默认为图像、音频和视频，而 groq 默认为音频。
• prompt、maxChars、maxBytes、timeoutSeconds、language：各条目的覆盖值。
• 当智能体显式调用 image 工具时，tools.media.image.timeoutSeconds 以及对应图像模型条目中的 timeoutSeconds 也会生效。对于图像理解，此超时适用于请求本身，不会因之前的准备工作而缩短。
• 失败时会回退到下一个条目。

提供商身份验证遵循标准顺序：auth-profiles.json → 环境变量 → models.providers.*.apiKey。

异步完成字段：

• asyncCompletion.directSend：已弃用的兼容性标志。已完成的异步媒体任务仍由请求方会话协调，以便智能体接收结果、决定如何告知用户，并在来源交付需要时使用消息工具。

• self：仅限当前会话键。
• tree：当前会话及由当前会话派生的会话（子智能体）。
• agent：属于当前智能体 ID 的任何会话（如果你在同一个智能体 ID 下按发送者运行会话，可能包括其他用户）。
• all：任何会话。以其他智能体为目标仍需要 tools.agentToAgent。
• 沙箱限制：当当前会话处于沙箱隔离状态，并且 agents.defaults.sandbox.sessionToolsVisibility="spawned"（默认值）时，即使 tools.sessions.visibility="all"，可见性也会被强制设为 tree。
• 当值不是 all 时，sessions_list 会包含一个简洁的 visibility 字段， 用于说明实际生效的模式，并警告当前范围之外的某些会话可能会被 省略。

• 附件要求设置 enabled: true。
• 子智能体附件会被写入子工作区的 .openclaw/attachments/<uuid>/，并带有 .manifest.json。
• ACP 附件仅支持图像；通过相同的文件数量、单文件字节数和总字节数限制后，附件会以内联方式转发给 ACP 运行时。
• 附件内容会自动从持久化的转录记录中删减。
• Base64 输入会接受严格的字母表和填充检查，并在解码前执行大小防护。
• 子智能体附件目录的文件权限为 0700，文件的权限为 0600。
• 子智能体清理遵循 cleanup 策略：delete 始终删除附件；仅当 retainOnSessionKeep: true 时，keep 才会保留附件。

• 对于自定义身份验证需求，请使用 authHeader: true + headers。
• 使用 OPENCLAW_AGENT_DIR 覆盖智能体配置根目录。
• 匹配提供商 ID 时的合并优先级：
  • 智能体 models.json 中的非空 baseUrl 值优先。
  • 仅当该提供商在当前配置/身份验证配置文件上下文中不由 SecretRef 管理时，智能体中的非空 apiKey 值才优先。
  • 由 SecretRef 管理的提供商 apiKey 值会根据来源标记刷新（环境变量引用使用 ENV_VAR_NAME，文件/exec 引用使用 secretref-managed），而不是持久化已解析的密钥。
  • 由 SecretRef 管理的提供商标头值会根据来源标记刷新（环境变量引用使用 secretref-env:ENV_VAR_NAME，文件/exec 引用使用 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、azure-openai-responses）。对于 MLX、vLLM、SGLang 以及大多数兼容 OpenAI 的本地服务器等自托管 /v1/chat/completions 后端，请使用 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.*.contextWindow：当模型条目未设置 contextWindow 时，此提供商下模型的默认原生上下文窗口。
• models.providers.*.contextTokens：当模型条目未设置 contextTokens 时，此提供商下模型的默认实际运行时上下文上限。
• models.providers.*.maxTokens：当模型条目未设置 maxTokens 时，此提供商下模型的默认输出令牌上限。
• 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 请求通过提供商 HTTP 获取防护访问私有、CGNAT 或类似地址范围。自定义/本地提供商的基础 URL 已默认信任精确配置的源，但元数据/链路本地源除外；这些源在未明确选择启用时仍会被阻止。将此项设为 false 可停用精确源信任。WebSocket 使用相同的 request 配置处理标头/TLS，但不受该获取操作的 SSRF 防护限制。默认值为 false。

• models.providers.*.models：显式提供商模型目录条目。
• models.providers.*.models.*.input：模型输入模态。纯文本模型使用 ["text"]，原生图像/视觉模型使用 ["text", "image"]。仅当所选模型标记为支持图像时，图像附件才会注入智能体轮次。
• models.providers.*.models.*.contextWindow：原生模型上下文窗口元数据。它会覆盖该模型的提供商级 contextWindow。
• models.providers.*.models.*.contextTokens：可选的运行时上下文上限。它会覆盖提供商级 contextTokens；当你希望实际上下文预算小于模型的原生 contextWindow 时使用此项；当两个值不同时，openclaw models list 会同时显示它们。
• models.providers.*.models.*.compat.supportsDeveloperRole：可选的兼容性提示。对于具有非空、非原生 baseUrl（主机不是 api.openai.com）的 api: "openai-completions"，OpenClaw 会在运行时强制将此项设为 false。baseUrl 为空或省略时会保留 OpenAI 的默认行为。
• models.providers.*.models.*.compat.requiresStringContent：针对仅支持字符串的 OpenAI 兼容聊天端点的可选兼容性提示。设为 true 时，OpenClaw 会在发送请求前将纯文本 messages[].content 数组展平为普通字符串。
• models.providers.*.models.*.compat.strictMessageKeys：针对严格的 OpenAI 兼容聊天端点的可选兼容性提示。设为 true 时，OpenClaw 会在发送请求前将传出的 Chat Completions 消息对象精简为 role 和 content。
• models.providers.*.models.*.compat.thinkingFormat：可选的思考载荷提示。对于 Together 风格的 reasoning.enabled，使用 "together"；对于顶层 enable_thinking，使用 "qwen"；对于 Qwen 系列且兼容 OpenAI、支持请求级聊天模板关键字参数的服务器（如 vLLM）上的 chat_template_kwargs.enable_thinking，使用 "qwen-chat-template"。配置的 vLLM Qwen 模型会为这些格式提供二元 /think 选项（off、on）。
• models.providers.*.models.*.compat.requiresReasoningContentOnAssistantMessages：针对 DeepSeek 风格 Chat Completions 后端的可选兼容性提示，这类后端要求重放时先前的智能体助手消息保留 reasoning_content。设为 true 时，OpenClaw 会在传出的智能体助手消息中保留该字段。连接自定义的 DeepSeek 兼容代理时，如果该代理会拒绝移除了推理内容的请求，请使用此项。默认值为 false。

• 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：已发现模型的后备最大输出令牌数。

官方外部 cerebras 提供商插件可通过 openclaw onboard --auth-choice cerebras-api-key 完成配置。仅在需要覆盖默认值时才使用显式提供商配置。

{  env: { CEREBRAS_API_KEY: "sk-..." },  agents: {    defaults: {      model: {        primary: "cerebras/zai-glm-4.7",        fallbacks: ["cerebras/gpt-oss-120b"],      },      models: {        "cerebras/zai-glm-4.7": { alias: "GLM 4.7 (Cerebras)" },        "cerebras/gpt-oss-120b": { alias: "GPT OSS 120B (Cerebras)" },      },    },  },  models: {    mode: "merge",    providers: {      cerebras: {        baseUrl: "https://api.cerebras.ai/v1",        apiKey: "${CEREBRAS_API_KEY}",        api: "openai-completions",        models: [          { id: "zai-glm-4.7", name: "GLM 4.7 (Cerebras)" },          { id: "gpt-oss-120b", name: "GPT OSS 120B (Cerebras)" },        ],      },    },  },}

使用 cerebras/zai-glm-4.7 可通过 Cerebras 使用该模型；使用 zai/glm-4.7 可直接通过 Z.AI 使用。

{  env: { KIMI_API_KEY: "sk-..." },  agents: {    defaults: {      model: { primary: "kimi/kimi-for-coding" },      models: { "kimi/kimi-for-coding": { alias: "Kimi Code" } },    },  },}

兼容 Anthropic 的内置提供商。快捷方式：openclaw onboard --auth-choice kimi-code-api-key。

请参阅本地模型。简而言之：在高性能硬件上通过 LM Studio Responses API 运行大型本地模型；同时合并托管模型以供回退。

{  agents: {    defaults: {      model: { primary: "minimax/MiniMax-M3" },      models: {        "minimax/MiniMax-M3": { alias: "Minimax" },      },    },  },  models: {    mode: "merge",    providers: {      minimax: {        baseUrl: "https://api.minimax.io/anthropic",        apiKey: "${MINIMAX_API_KEY}",        api: "anthropic-messages",        models: [          {            id: "MiniMax-M3",            name: "MiniMax M3",            reasoning: true,            input: ["text", "image"],            cost: { input: 0.6, output: 2.4, cacheRead: 0.12, cacheWrite: 0 },            contextWindow: 1000000,            maxTokens: 131072,          },        ],      },    },  },}

设置 MINIMAX_API_KEY。快捷方式：openclaw onboard --auth-choice minimax-global-api 或 openclaw onboard --auth-choice minimax-cn-api。模型目录默认使用 M3，同时也包含 M2.7 变体。在 Anthropic 兼容的流式传输路径上，除非你自行显式设置 thinking，否则 OpenClaw 默认禁用 MiniMax M2.x 的思考功能；MiniMax-M3（以及 M3.x）默认保持提供商的省略式/自适应思考路径。/fast on 或 params.fastMode: true 会将 MiniMax-M2.7 重写为 MiniMax-M2.7-highspeed。

{  env: { MOONSHOT_API_KEY: "sk-..." },  agents: {    defaults: {      model: { primary: "moonshot/kimi-k2.6" },      models: { "moonshot/kimi-k2.6": { alias: "Kimi K2.6" } },    },  },  models: {    mode: "merge",    providers: {      moonshot: {        baseUrl: "https://api.moonshot.ai/v1",        apiKey: "${MOONSHOT_API_KEY}",        api: "openai-completions",        models: [          {            id: "kimi-k2.6",            name: "Kimi K2.6",            reasoning: false,            input: ["text", "image"],            cost: { input: 0.95, output: 4, cacheRead: 0.16, cacheWrite: 0 },            contextWindow: 262144,            maxTokens: 262144,          },        ],      },    },  },}

对于中国区端点，请使用 baseUrl: "https://api.moonshot.cn/v1" 或 openclaw onboard --auth-choice moonshot-api-key-cn。

Moonshot 原生端点会声明其在共享 openai-completions 传输协议上兼容流式用量信息，OpenClaw 会根据端点能力而不是仅根据内置提供商 ID 启用该功能。

{  agents: {    defaults: {      model: { primary: "opencode/claude-opus-4-6" },      models: { "opencode/claude-opus-4-6": { alias: "Opus" } },    },  },}

设置 OPENCODE_API_KEY（或 OPENCODE_ZEN_API_KEY）。Zen 目录使用 opencode/... 引用，Go 目录使用 opencode-go/... 引用。快捷方式：openclaw onboard --auth-choice opencode-zen 或 openclaw onboard --auth-choice opencode-go。

{  env: { SYNTHETIC_API_KEY: "sk-..." },  agents: {    defaults: {      model: { primary: "synthetic/hf:MiniMaxAI/MiniMax-M2.5" },      models: { "synthetic/hf:MiniMaxAI/MiniMax-M2.5": { alias: "MiniMax M2.5" } },    },  },  models: {    mode: "merge",    providers: {      synthetic: {        baseUrl: "https://api.synthetic.new/anthropic",        apiKey: "${SYNTHETIC_API_KEY}",        api: "anthropic-messages",        models: [          {            id: "hf:MiniMaxAI/MiniMax-M2.5",            name: "MiniMax M2.5",            reasoning: true,            input: ["text"],            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },            contextWindow: 192000,            maxTokens: 65536,          },        ],      },    },  },}

基础 URL 应省略 /v1（Anthropic 客户端会自动附加它）。快捷方式：openclaw onboard --auth-choice synthetic-api-key。

{  agents: {    defaults: {      model: { primary: "zai/glm-4.7" },      models: { "zai/glm-4.7": {} },    },  },}

设置 ZAI_API_KEY。模型引用使用规范的 zai/* 提供商 ID。快捷方式：openclaw onboard --auth-choice zai-api-key。

• 通用端点：https://api.z.ai/api/paas/v4
• 编程端点：https://api.z.ai/api/coding/paas/v4
• 默认的 zai-api-key 身份验证选项会探测你的密钥并自动检测其所属端点（如果检测结果不确定，则回退到提示，默认选择全球端点）。此外还提供专用的中国区和编程套餐身份验证选项，供你显式选择。
• 对于通用端点，请定义自定义提供商并覆盖基础 URL。