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

提供商条目（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。

• 附件仅支持 runtime: "subagent"。ACP 运行时会拒绝它们。
• 文件会在子工作区的 .openclaw/attachments/<uuid>/ 中实体化，并带有 .manifest.json。
• 附件内容会自动从转录持久化中脱敏。
• Base64 输入会通过严格的字母表/填充检查和解码前大小保护进行验证。
• 目录权限为 0700，文件权限为 0600。
• 清理遵循 cleanup 策略：delete 始终移除附件；keep 仅在 retainOnSessionKeep: true 时保留附件。

• 对于自定义身份验证需求，使用 authHeader: true + headers。
• 使用 OPENCLAW_AGENT_DIR（或 PI_CODING_AGENT_DIR，一个旧版环境变量别名）覆盖智能体配置根目录。
• 匹配提供商 ID 的合并优先级：
  • 非空的智能体 models.json baseUrl 值优先。
  • 非空的智能体 apiKey 值仅在该提供商未在当前配置/身份验证配置文件上下文中由 SecretRef 管理时优先。
  • 由 SecretRef 管理的提供商 apiKey 值会从源标记刷新（env 引用使用 ENV_VAR_NAME，file/exec 引用使用 secretref-managed），而不是持久化已解析的密钥。
  • 由 SecretRef 管理的提供商 header 值会从源标记刷新（env 引用使用 secretref-env:ENV_VAR_NAME，file/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、anthropic-messages、google-generative-ai 等）。对于自托管 /v1/chat/completions 后端，例如 MLX、vLLM、SGLang 和大多数 OpenAI 兼容本地服务器，使用 openai-completions。具有 baseUrl 但没有 api 的自定义提供商默认使用 openai-completions；仅当后端支持 /v1/responses 时才设置 openai-responses。
• models.providers.*.apiKey：提供商凭证（优先使用 SecretRef/env 替换）。
• 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 请求超时（秒），包括连接、header、body 和总请求中止处理。
• models.providers.*.injectNumCtxForOpenAICompat：对于 Ollama + openai-completions，向请求注入 options.num_ctx（默认：true）。
• models.providers.*.authHeader：在需要时强制通过 Authorization header 传输凭证。
• models.providers.*.baseUrl：上游 API base URL。
• models.providers.*.headers：用于代理/租户路由的额外静态 header。

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

• request.headers：额外 header（与提供商默认值合并）。值接受 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 时，当 DNS 解析到私有、CGNAT 或类似地址段时，允许通过提供商 HTTP fetch 防护访问 baseUrl 的 HTTPS（操作员为受信任自托管 OpenAI 兼容端点选择加入）。除非显式设置为 false，否则诸如 localhost、127.0.0.1 和 [::1] 的 loopback 模型提供商流 URL 会自动允许；LAN、tailnet 和私有 DNS 主机仍需选择加入。WebSocket 对 header/TLS 使用同一 request，但不使用该 fetch 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：可选的思考负载提示。对于顶层 enable_thinking 使用 "qwen"；对于支持请求级 chat-template kwargs 的 Qwen 系列 OpenAI 兼容服务器（例如 vLLM），对 chat_template_kwargs.enable_thinking 使用 "qwen-chat-template"。

• 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 provider 插件可以通过 openclaw onboard --auth-choice cerebras-api-key 配置它。仅在覆盖默认值时使用显式 provider 配置。

{  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 兼容的内置 provider。快捷方式：openclaw onboard --auth-choice kimi-code-api-key。

参见 本地模型。简要说明：在高性能硬件上通过 LM Studio Responses API 运行大型本地模型；保留托管模型合并作为回退。

{  agents: {    defaults: {      model: { primary: "minimax/MiniMax-M2.7" },      models: {        "minimax/MiniMax-M2.7": { alias: "Minimax" },      },    },  },  models: {    mode: "merge",    providers: {      minimax: {        baseUrl: "https://api.minimax.io/anthropic",        apiKey: "${MINIMAX_API_KEY}",        api: "anthropic-messages",        models: [          {            id: "MiniMax-M2.7",            name: "MiniMax M2.7",            reasoning: true,            input: ["text"],            cost: { input: 0.3, output: 1.2, cacheRead: 0.06, cacheWrite: 0.375 },            contextWindow: 204800,            maxTokens: 131072,          },        ],      },    },  },}

设置 MINIMAX_API_KEY。快捷方式：openclaw onboard --auth-choice minimax-global-api 或 openclaw onboard --auth-choice minimax-cn-api。模型目录默认仅包含 M2.7。在 Anthropic 兼容的流式传输路径上，除非你显式设置 thinking，否则 OpenClaw 默认禁用 MiniMax 思考。/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 会根据端点能力而非仅根据内置 provider 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。z.ai/* 和 z-ai/* 是可接受的别名。快捷方式：openclaw onboard --auth-choice zai-api-key。

• 通用端点：https://api.z.ai/api/paas/v4
• 编码端点（默认）：https://api.z.ai/api/coding/paas/v4
• 对于通用端点，定义一个带基础 URL 覆盖的自定义 provider。