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

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

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

CLI 条目（type: "cli"）：

• command：要运行的可执行文件
• args：模板化参数（支持 {{AttachmentPath}}、{{AttachmentUrl}}、{{AttachmentContentType}}、{{AttachmentDir}}、{{AttachmentIndex}}、{{Prompt}}、{{MaxChars}} 等；openclaw doctor --fix 会将已弃用的 {input} 占位符迁移到 {{AttachmentPath}}）。较旧的 {{MediaPath}}、{{MediaUrl}}、{{MediaType}} 和 {{MediaDir}} 别名在其兼容期内仍可使用，但已弃用。

通用字段：

• capabilities：包含 image、audio 和 video 中一项或多项的列表。
• prompt、maxChars、maxBytes、timeoutSeconds、language：每个条目的覆盖配置。
• 当智能体调用显式 image 工具时，匹配的图像模型 timeoutSeconds 条目也会应用。对于图像理解，此超时应用于请求本身，不会因之前的准备工作而缩短。
• 失败时回退到下一个条目。

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

• self：仅当前会话键。
• tree：当前会话 + 当前会话生成的会话（子智能体）。对于读取操作，它还包括当前会话通过环境群组感知所监视的同一智能体群组会话。
• agent：属于当前智能体 ID 的任何会话（如果在同一智能体 ID 下运行按发送者划分的会话，可能包含其他用户）。
• all：任何会话。跨智能体定向仍需要 tools.agentToAgent。
• 沙箱限制：当前会话处于沙箱隔离状态且 agents.defaults.sandbox.sessionToolsVisibility="spawned"（默认值）时，即使 tools.sessions.visibility="all"，可见性也会被强制设为 tree。
• 当不是 all 时，sessions_list 会包含一个精简的 visibility 字段，用于描述生效模式，并警告当前范围之外的某些会话可能会被省略。

• 附件需要 enabled: true。
• 子智能体附件会通过 .manifest.json 实体化到子工作区的 .openclaw/attachments/<uuid>/ 中。
• 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 等自托管 /v1/chat/completions 后端以及大多数兼容 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.*.contextWindow：当模型条目未设置 contextWindow 时，此提供商下模型的默认原生上下文窗口。
• models.providers.*.contextTokens：当模型条目未设置 contextTokens 时，此提供商下模型的默认有效运行时上下文上限。
• 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 请求通过提供商 HTTP 获取保护机制访问私有、CGNAT 或类似范围。自定义/本地提供商基础 URL 已信任已配置的确切源，但元数据/链路本地源除外；若未显式选择启用，这些源仍会被阻止。将其设置为 false 可选择退出确切源信任。WebSocket 对标头/TLS 使用相同的 request，但不使用该获取 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 会同时显示它们。

自定义提供商能力声明

对于内置和目录已知的模型路由，提供商目录拥有 compat。请勿将这些标志复制到配置中：只要已配置的 api 和 baseUrl 仍标识该路由，OpenClaw 就会使用目录行。openclaw doctor --fix 会移除匹配的旧版覆盖值，并报告存在差异的值以供审查。

对于真正的自定义提供商、自定义模型或路由到不同端点的目录模型，仍支持 compat 块。仅设置已经针对该端点验证的能力：

• 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 数。

官方外部 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 使用 cerebras/zai-glm-4.7；直连 Z.AI 使用 zai/glm-4.7。

{  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-M3" },      models: { "synthetic/hf:MiniMaxAI/MiniMax-M3": { alias: "MiniMax M3" } },    },  },  models: {    mode: "merge",    providers: {      synthetic: {        baseUrl: "https://api.synthetic.new/anthropic",        apiKey: "${SYNTHETIC_API_KEY}",        api: "anthropic-messages",        models: [          {            id: "hf:MiniMaxAI/MiniMax-M3",            name: "MiniMax M3",            reasoning: true,            input: ["text", "image"],            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },            contextWindow: 262144,            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 身份验证选项会探测你的密钥，并自动检测它所属的端点（如果检测结果不明确，则回退为提示，默认选择 Global）。此外还提供专用的 CN 和 Coding-Plan 身份验证选项，可供显式选择。
• 对于通用端点，请定义自定义提供商并覆盖基础 URL。