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

提供商条目（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 → image，google → image+audio+video，groq → audio。
• 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_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、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/环境变量替换）。
• 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 时，如果 DNS 解析到私有、CGNAT 或类似范围，则通过提供商 HTTP 获取保护允许对 baseUrl 使用 HTTPS（操作员为可信自托管 OpenAI 兼容端点选择加入）。local loopback 模型提供商流 URL（例如 localhost、127.0.0.1 和 [::1]）会自动允许，除非此项显式设置为 false；LAN、tailnet 和私有 DNS 主机仍需选择加入。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 会在两者不同时显示这两个值。
• 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 数组展平为普通字符串。

• 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 provider 插件可通过 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-code" },
      models: { "kimi/kimi-code": { alias: "Kimi Code" } },
    },
  },
}

Anthropic 兼容的内置提供商。快捷方式：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 会依据端点能力判断，而不只看内置提供商 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 覆盖的自定义提供商。