openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-21 21:01:54 +00:00
parent 125dfae04d
commit cdd3d2fa9e
7 changed files with 1525 additions and 1511 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

367
docs/zh-CN/concepts/model-providers.md
View File

@ -1,150 +1,149 @@
---
read_when:
- 你需要一份按提供商分别说明的模型设置参考文档
- 你想要模型提供商的示例配置或 CLI 新手引导命令
summary: 模型提供商概览，包含示例配置和 CLI 流程
- 你需要一份按提供商逐一说明的模型设置参考。
- 你想要模型提供商的示例配置或 CLI 新手引导命令。
summary: 模型提供商概览，包含示例配置 + CLI 流程
title: 模型提供商
x-i18n:
generated_at: "2026-04-21T08:24:19Z"
generated_at: "2026-04-21T20:53:28Z"
model: gpt-5.4
provider: openai
source_hash: 6732ab672757579c09395583a0f7d110348c909d4e4ab1d2accad68ad054c636
source_hash: 6cbb8c9caf148c8db124638a036503fc4d4d3cce947ad99cffdf68a137edaab7
source_path: concepts/model-providers.md
workflow: 15
---
# 模型提供商
本页介绍的是 **LLM/模型提供商**（而不是像 WhatsApp/Telegram 这样的聊天渠道）。
关于模型选择规则，请参见 [/concepts/models](/zh-CN/concepts/models)。
本页介绍 **LLM/模型提供商**（不是像 WhatsApp/Telegram 这样的聊天渠道）。
有关模型选择规则，请参见 [/concepts/models](/zh-CN/concepts/models)。
## 快速规则
- 模型引用使用 `provider/model` 格式（示例：`opencode/claude-opus-4-6`）。
- 模型引用使用 `provider/model`（示例：`opencode/claude-opus-4-6`）。
- 如果你设置了 `agents.defaults.models`，它就会成为允许列表。
- CLI 助手：`openclaw onboard`、`openclaw models list`、`openclaw models set <provider/model>`。
- 回退运行时规则、冷却探测和会话覆盖持久化记录在 [/concepts/model-failover](/zh-CN/concepts/model-failover)。
- `models.providers.*.models[].contextWindow` 是原生模型元数据；`models.providers.*.models[].contextTokens` 是运行时生效的上限。
- 提供商插件可以通过 `registerProvider({ catalog })` 注入模型目录；OpenClaw 会在写入 `models.json` 之前将该输出合并到 `models.providers` 中。
- 提供商清单可以声明 `providerAuthEnvVars` 和 `providerAuthAliases`，这样基于通用环境变量的凭证探测和提供商变体就不需要加载插件运行时。当前核心中的其余环境变量映射现在只用于非插件/核心提供商，以及少数通用优先级场景，例如 Anthropic 以 API key 优先的新手引导。
- 提供商插件还可以通过 `normalizeModelId`、`normalizeTransport`、`normalizeConfig`、`applyNativeStreamingUsageCompat`、`resolveConfigApiKey`、`resolveSyntheticAuth`、`shouldDeferSyntheticProfileAuth`、`resolveDynamicModel`、`prepareDynamicModel`、`normalizeResolvedModel`、`contributeResolvedModelCompat`、`capabilities`、`normalizeToolSchemas`、`inspectToolSchemas`、`resolveReasoningOutputMode`、`prepareExtraParams`、`createStreamFn`、`wrapStreamFn`、`resolveTransportTurnState`、`resolveWebSocketSessionPolicy`、`createEmbeddingProvider`、`formatApiKey`、`refreshOAuth`、`buildAuthDoctorHint`、`matchesContextOverflowError`、`classifyFailoverReason`、`isCacheTtlEligible`、`buildMissingAuthMessage`、`suppressBuiltInModel`、`augmentModelCatalog`、`resolveThinkingProfile`、`isBinaryThinking`、`supportsXHighThinking`、`resolveDefaultThinkingLevel`、`applyConfigDefaults`、`isModernModelRef`、`prepareRuntimeAuth`、`resolveUsageAuth`、`fetchUsageSnapshot` 和 `onModelSelected` 来拥有提供商运行时行为。
- 注意：提供商运行时 `capabilities` 是共享运行器元数据（提供商家族、转录/工具行为特性、传输/缓存提示）。它不同于[公开 capability 模型](/zh-CN/plugins/architecture#public-capability-model)，后者描述的是插件注册了什么能力（文本推理、语音等）。
- 内置的 `codex` 提供商与内置 Codex 智能体 harness 配对使用。当你需要 Codex 自有登录、模型发现、原生线程恢复和 app-server 执行时，请使用 `codex/gpt-*`。普通的 `openai/gpt-*` 引用仍然会使用 OpenAI 提供商和标准 OpenClaw 提供商传输。仅使用 Codex 的部署可以通过设置 `agents.defaults.embeddedHarness.fallback: "none"` 来禁用自动 PI 回退；参见 [Codex Harness](/zh-CN/plugins/codex-harness)。
- CLI 辅助命令：`openclaw onboard`、`openclaw models list`、`openclaw models set <provider/model>`。
- 回退运行时规则、冷却探测和会话覆盖持久化记录在 [/concepts/model-failover](/zh-CN/concepts/model-failover) 中。
- `models.providers.*.models[].contextWindow` 是模型原生元数据；`models.providers.*.models[].contextTokens` 是运行时生效的上限。
- 提供商插件可以通过 `registerProvider({ catalog })` 注入模型目录；OpenClaw 会在写入 `models.json` 之前，将该输出合并到 `models.providers` 中。
- 提供商清单可以声明 `providerAuthEnvVars` 和 `providerAuthAliases`，这样通用的基于环境变量的凭证探测和提供商变体就不需要加载插件运行时。当前剩余的核心环境变量映射现在仅用于非插件/核心提供商，以及少数通用优先级场景，例如 Anthropic API 密钥优先的新手引导。
- 提供商插件还可以通过 `normalizeModelId`、`normalizeTransport`、`normalizeConfig`、`applyNativeStreamingUsageCompat`、`resolveConfigApiKey`、`resolveSyntheticAuth`、`shouldDeferSyntheticProfileAuth`、`resolveDynamicModel`、`prepareDynamicModel`、`normalizeResolvedModel`、`contributeResolvedModelCompat`、`capabilities`、`normalizeToolSchemas`、`inspectToolSchemas`、`resolveReasoningOutputMode`、`prepareExtraParams`、`createStreamFn`、`wrapStreamFn`、`resolveTransportTurnState`、`resolveWebSocketSessionPolicy`、`createEmbeddingProvider`、`formatApiKey`、`refreshOAuth`、`buildAuthDoctorHint`、`matchesContextOverflowError`、`classifyFailoverReason`、`isCacheTtlEligible`、`buildMissingAuthMessage`、`suppressBuiltInModel`、`augmentModelCatalog`、`resolveThinkingProfile`、`isBinaryThinking`、`supportsXHighThinking`、`resolveDefaultThinkingLevel`、`applyConfigDefaults`、`isModernModelRef`、`prepareRuntimeAuth`、`resolveUsageAuth`、`fetchUsageSnapshot` 和 `onModelSelected` 来负责提供商运行时行为。
- 注意：提供商运行时 `capabilities` 是共享运行器元数据（提供商家族、转录记录/工具行为差异、传输/缓存提示）。它不同于 [公共能力模型](/zh-CN/plugins/architecture#public-capability-model)，后者描述的是插件注册了什么能力（文本推理、语音等）。
- 内置的 `codex` 提供商与内置 Codex 智能体 harness 配套使用。当你需要 Codex 自有登录、模型发现、原生线程恢复和应用服务器执行时，请使用 `codex/gpt-*`。普通的 `openai/gpt-*` 引用仍然会使用 OpenAI 提供商和标准 OpenClaw 提供商传输。仅使用 Codex 的部署可以通过设置 `agents.defaults.embeddedHarness.fallback: "none"` 禁用自动 PI 回退；参见 [Codex Harness](/zh-CN/plugins/codex-harness)。
## 插件自有的提供商行为
提供商插件现在可以拥有大部分提供商特定逻辑，而 OpenClaw 则保留通用推理循环。
现在，提供商插件可以拥有大多数提供商特定逻辑，而 OpenClaw 保留通用推理循环。
典型划分如下：
典型划分：
- `auth[].run` / `auth[].runNonInteractive`：提供商拥有 `openclaw onboard`、`openclaw models auth` 和无头设置的引导/登录流程
- `wizard.setup` / `wizard.modelPicker`：提供商拥有凭证选择标签、旧版别名、新手引导允许列表提示，以及新手引导/模型选择器中的设置项
- `catalog`：提供商显示在 `models.providers` 中
- `normalizeModelId`：提供商在查找或规范化之前标准化旧版/预览模型 ID
- `normalizeTransport`：提供商在通用模型组装之前标准化传输家族 `api` / `baseUrl`；OpenClaw 会先检查匹配的提供商，然后再检查其他支持该 hook 的提供商插件，直到其中一个实际更改了传输
- `normalizeConfig`：提供商在运行时使用前标准化 `models.providers.<id>` 配置；OpenClaw 会先检查匹配的提供商，然后再检查其他支持该 hook 的提供商插件，直到其中一个实际更改了配置。如果没有提供商 hook 重写配置，内置的 Google 家族助手仍会标准化受支持的 Google 提供商条目。
- `applyNativeStreamingUsageCompat`：提供商对配置提供商应用由端点驱动的原生流式用量兼容性重写
- `resolveConfigApiKey`：提供商为配置提供商解析环境变量标记凭证，而不强制加载完整运行时凭证。`amazon-bedrock` 这里也有一个内置的 AWS 环境变量标记解析器，尽管 Bedrock 运行时凭证使用的是 AWS SDK 默认链。
- `resolveSyntheticAuth`：提供商可以在不持久化明文密钥的情况下公开本地/自托管或其他基于配置的凭证可用性
- `shouldDeferSyntheticProfileAuth`：提供商可以将已存储的合成配置占位凭证标记为低于环境变量/配置支持凭证的优先级
- `resolveDynamicModel`：提供商接受尚未出现在本地静态目录中的模型 ID
- `auth[].run` / `auth[].runNonInteractive`：提供商负责 `openclaw onboard`、`openclaw models auth` 和无头设置的引导/登录流程
- `wizard.setup` / `wizard.modelPicker`：提供商负责凭证选择标签、旧版别名、新手引导允许列表提示，以及新手引导/模型选择器中的设置项
- `catalog`：提供商出现在 `models.providers` 中
- `normalizeModelId`：提供商在查找或规范化之前，规范化旧版/预览模型 id
- `normalizeTransport`：提供商在通用模型组装之前规范化传输族的 `api` / `baseUrl`；OpenClaw 会先检查匹配的提供商，然后检查其他支持该 hook 的提供商插件，直到某个插件实际修改了传输
- `normalizeConfig`：提供商在运行时使用前规范化 `models.providers.<id>` 配置；OpenClaw 会先检查匹配的提供商，然后检查其他支持该 hook 的提供商插件，直到某个插件实际修改了配置。如果没有提供商 hook 重写配置，内置的 Google 家族辅助逻辑仍会规范化受支持的 Google 提供商条目。
- `applyNativeStreamingUsageCompat`：提供商为配置型提供商应用由端点驱动的原生流式使用量兼容性重写
- `resolveConfigApiKey`：提供商为配置型提供商解析环境变量标记凭证，而无需强制加载完整运行时凭证。`amazon-bedrock` 在这里也有一个内置的 AWS 环境变量标记解析器，尽管 Bedrock 运行时凭证使用的是 AWS SDK 默认链。
- `resolveSyntheticAuth`：提供商可以暴露本地/自托管或其他基于配置的可用凭证，而无需持久化明文密钥
- `shouldDeferSyntheticProfileAuth`：提供商可以将已存储的合成配置档占位凭证标记为低于环境变量/配置支持凭证的优先级
- `resolveDynamicModel`：提供商接受尚未出现在本地静态目录中的模型 id
- `prepareDynamicModel`：提供商在重试动态解析之前需要刷新元数据
- `normalizeResolvedModel`：提供商需要重写传输或基础 URL
- `contributeResolvedModelCompat`：即使其供应商模型通过另一个兼容传输到达，提供商也会为其贡献兼容性标志
- `capabilities`：提供商发布转录/工具/提供商家族行为特性
- `normalizeResolvedModel`：提供商需要重写传输或 base URL
- `contributeResolvedModelCompat`：即使供应商模型是通过其他兼容传输接入的，提供商也能为其贡献兼容性标记
- `capabilities`：提供商发布转录记录/工具/提供商家族相关的行为差异
- `normalizeToolSchemas`：提供商在内置运行器看到工具 schema 之前对其进行清理
- `inspectToolSchemas`：提供商在标准化之后暴露传输特定的 schema 警告
- `inspectToolSchemas`：提供商在规范化后暴露传输特定的 schema 警告
- `resolveReasoningOutputMode`：提供商选择原生或带标签的推理输出契约
- `prepareExtraParams`：提供商为每个模型的请求参数设置默认值或进行标准化
- `createStreamFn`：提供商用完全自定义的传输替换正常的流路径
- `prepareExtraParams`：提供商为每个模型的请求参数设置默认值或进行规范化
- `createStreamFn`：提供商用完全自定义的传输替换正常流式路径
- `wrapStreamFn`：提供商应用请求头/请求体/模型兼容性包装器
- `resolveTransportTurnState`：提供商提供逐轮原生传输头或元数据
- `resolveTransportTurnState`：提供商提供每轮原生传输头或元数据
- `resolveWebSocketSessionPolicy`：提供商提供原生 WebSocket 会话头或会话冷却策略
- `createEmbeddingProvider`：当内存嵌入行为应属于提供商插件而不是核心嵌入切换板时，由提供商拥有该行为
- `formatApiKey`：提供商将已存储的凭证配置格式化为传输所期望的运行时 `apiKey` 字符串
- `refreshOAuth`：当共享的 `pi-ai` 刷新器不足时，由提供商拥有 OAuth 刷新
- `buildAuthDoctorHint`：当 OAuth 刷新失败时，提供商追加修复指导
- `matchesContextOverflowError`：提供商识别通用启发式规则会漏掉的、提供商特定的上下文窗口溢出错误
- `createEmbeddingProvider`：当记忆嵌入行为应归属于提供商插件而不是核心嵌入切换板时，由提供商负责
- `formatApiKey`：提供商将已存储的凭证配置档格式化为传输所期望的运行时 `apiKey` 字符串
- `refreshOAuth`：当共享的 `pi-ai` 刷新器不足以处理时，由提供商负责 OAuth 刷新
- `buildAuthDoctorHint`：当 OAuth 刷新失败时，提供商追加修复指引
- `matchesContextOverflowError`：提供商识别通用启发式规则无法发现的提供商特定上下文窗口溢出错误
- `classifyFailoverReason`：提供商将提供商特定的原始传输/API 错误映射为回退原因，例如速率限制或过载
- `isCacheTtlEligible`：提供商决定哪些上游模型 ID 支持提示词缓存 TTL
- `buildMissingAuthMessage`：提供商用提供商特定的恢复提示替换通用凭证存储错误
- `suppressBuiltInModel`：提供商隐藏过时的上游条目，并可在直接解析失败时返回供应商自有错误
- `augmentModelCatalog`：提供商在发现和配置合并之后追加合成/最终目录条目
- `resolveThinkingProfile`：提供商拥有所选模型的精确 `/think` 级别集合、可选显示标签和默认级别
- `isCacheTtlEligible`：提供商决定哪些上游模型 id 支持提示缓存 TTL
- `buildMissingAuthMessage`：提供商用提供商特定的恢复提示替换通用的凭证存储错误
- `suppressBuiltInModel`：提供商隐藏过时的上游条目，并可在直接解析失败时返回由供应商自有的错误
- `augmentModelCatalog`：提供商在发现和配置合并后追加合成/最终目录条目
- `resolveThinkingProfile`：提供商负责所选模型精确的 `/think` 级别集合、可选显示标签和默认级别
- `isBinaryThinking`：用于二元开/关思考 UX 的兼容性 hook
- `supportsXHighThinking`：用于选定 `xhigh` 模型的兼容性 hook
- `resolveDefaultThinkingLevel`：用于默认 `/think` 策略的兼容性 hook
- `applyConfigDefaults`：提供商在基于凭证模式、环境变量或模型家族进行配置具体化时应用提供商特定的全局默认值
- `isModernModelRef`：提供商拥有实时/冒烟测试首选模型匹配逻辑
- `prepareRuntimeAuth`：提供商将已配置的凭证转换为短期有效的运行时令牌
- `resolveUsageAuth`：提供商为 `/usage` 以及相关状态/报告界面解析用量/配额凭证
- `fetchUsageSnapshot`：提供商拥有用量端点的抓取/解析逻辑，而核心仍拥有摘要外壳和格式化
- `onModelSelected`：提供商在模型被选中后运行副作用，例如遥测或提供商自有的会话记账
- `applyConfigDefaults`：提供商在配置具体化期间，基于凭证模式、环境变量或模型家族应用提供商特定的全局默认值
- `isModernModelRef`：提供商负责 live/smoke 首选模型匹配
- `prepareRuntimeAuth`：提供商将已配置凭证转换为短时效运行时令牌
- `resolveUsageAuth`：提供商为 `/usage` 及相关状态/报告界面解析用量/配额凭证
- `fetchUsageSnapshot`：提供商负责用量端点的获取/解析，而核心仍负责摘要外壳和格式化
- `onModelSelected`：提供商在模型选定后运行副作用，例如遥测或提供商自有的会话记账
当前内置示例：
- `anthropic`：Claude 4.6 前向兼容回退、凭证修复提示、用量端点抓取、缓存 TTL/提供商家族元数据，以及具备凭证感知能力的全局配置默认值
- `anthropic`：Claude 4.6 前向兼容回退、凭证修复提示、用量端点获取、缓存 TTL/提供商家族元数据，以及具备凭证感知能力的全局配置默认值
- `amazon-bedrock`：由提供商自有的上下文溢出匹配，以及针对 Bedrock 特有节流/未就绪错误的回退原因分类，外加共享的 `anthropic-by-model` 重放家族，用于 Anthropic 流量上仅限 Claude 的重放策略保护
- `anthropic-vertex`：针对 Anthropic 消息流量的仅限 Claude 的重放策略保护
- `openrouter`：直通模型 ID、请求包装器、提供商 capability 提示、代理 Gemini 流量上的 Gemini thought-signature 清理、通过 `openrouter-thinking` 流家族进行代理推理注入、路由元数据转发，以及缓存 TTL 策略
- `github-copilot`：新手引导/设备登录、前向兼容模型回退、Claude thinking 转录提示、运行时令牌交换，以及用量端点抓取
- `openai`：GPT-5.4 前向兼容回退、直接 OpenAI 传输标准化、具备 Codex 感知能力的缺失凭证提示、Spark 抑制、合成 OpenAI/Codex 目录条目、thinking/实时模型策略、用量令牌别名标准化（`input` / `output` 和 `prompt` / `completion` 家族）、共享的 `openai-responses-defaults` 流家族（用于原生 OpenAI/Codex 包装器）、提供商家族元数据、为 `gpt-image-1` 内置的图像生成提供商注册，以及为 `sora-2` 内置的视频生成提供商注册
- `google` 和 `google-gemini-cli`：Gemini 3.1 前向兼容回退、原生 Gemini 重放校验、引导重放清理、带标签的推理输出模式、现代模型匹配、为 Gemini image-preview 模型内置的图像生成提供商注册，以及为 Veo 模型内置的视频生成提供商注册；此外，Gemini CLI OAuth 还拥有凭证配置令牌格式化、用量令牌解析，以及面向用量界面的配额端点抓取
- `moonshot`：共享传输、插件自有的 thinking 负载标准化
- `kilocode`：共享传输、插件自有的请求头、推理负载标准化、代理 Gemini thought-signature 清理，以及缓存 TTL 策略
- `zai`：GLM-5 前向兼容回退、`tool_stream` 默认值、缓存 TTL 策略、二元 thinking/实时模型策略，以及用量凭证 + 配额抓取；未知的 `glm-5*` ID 会基于内置的 `glm-4.7` 模板合成
- `xai`：原生 Responses 传输标准化、针对 Grok 快速变体的 `/fast` 别名重写、默认 `tool_stream`、xAI 特有的工具 schema / 推理负载清理，以及为 `grok-imagine-video` 内置的视频生成提供商注册
- `mistral`：插件自有的 capability 元数据
- `opencode` 和 `opencode-go`：插件自有的 capability 元数据，以及代理 Gemini thought-signature 清理
- `alibaba`：针对直接 Wan 模型引用（如 `alibaba/wan2.6-t2v`）的插件自有视频生成目录
- `byteplus`：插件自有目录，以及为 Seedance 文生视频/图生视频模型内置的视频生成提供商注册
- `fal`：为托管第三方图像生成 FLUX 图像模型内置的图像生成提供商注册，以及为托管第三方视频模型内置的视频生成提供商注册
- `cloudflare-ai-gateway`、`huggingface`、`kimi`、`nvidia`、`qianfan`、`stepfun`、`synthetic`、`venice`、`vercel-ai-gateway` 和 `volcengine`：仅有插件自有目录
- `qwen`：文本模型的插件自有目录，以及其多模态界面的共享媒体理解和视频生成提供商注册；Qwen 视频生成使用标准 DashScope 视频端点，并配套内置 Wan 模型，如 `wan2.6-t2v` 和 `wan2.7-r2v`
- `runway`：为原生 Runway 基于任务的模型（如 `gen4.5`）提供插件自有的视频生成提供商注册
- `minimax`：插件自有目录、为 Hailuo 视频模型内置的视频生成提供商注册、为 `image-01` 内置的图像生成提供商注册、Anthropic/OpenAI 混合重放策略选择，以及用量凭证/快照逻辑
- `together`：插件自有目录，以及为 Wan 视频模型内置的视频生成提供商注册
- `xiaomi`：插件自有目录，以及用量凭证/快照逻辑
- `anthropic-vertex`：针对 Anthropic-message 流量的仅限 Claude 的重放策略保护
- `openrouter`：透传模型 id、请求包装器、提供商能力提示、代理 Gemini 流量上的 Gemini thought-signature 清理、通过 `openrouter-thinking` 流家族进行的代理推理注入、路由元数据转发，以及缓存 TTL 策略
- `github-copilot`：新手引导/设备登录、前向兼容模型回退、Claude-thinking 转录提示、运行时令牌交换，以及用量端点获取
- `openai`：GPT-5.4 前向兼容回退、直接 OpenAI 传输规范化、具备 Codex 感知能力的缺失凭证提示、Spark 屏蔽、合成 OpenAI/Codex 目录条目、thinking/live-model 策略、用量令牌别名规范化（`input` / `output` 和 `prompt` / `completion` 家族）、用于原生 OpenAI/Codex 包装器的共享 `openai-responses-defaults` 流家族、提供商家族元数据、为 `gpt-image-2` 注册的内置图像生成提供商，以及为 `sora-2` 注册的内置视频生成提供商
- `google` 和 `google-gemini-cli`：Gemini 3.1 前向兼容回退、原生 Gemini 重放校验、引导重放清理、带标签的推理输出模式、现代模型匹配、为 Gemini image-preview 模型注册的内置图像生成提供商，以及为 Veo 模型注册的内置视频生成提供商；Gemini CLI OAuth 还负责凭证配置档令牌格式化、用量令牌解析，以及用于用量界面的配额端点获取
- `moonshot`：共享传输，插件自有的 thinking 负载规范化
- `kilocode`：共享传输、插件自有请求头、推理负载规范化、代理 Gemini thought-signature 清理，以及缓存 TTL 策略
- `zai`：GLM-5 前向兼容回退、`tool_stream` 默认值、缓存 TTL 策略、二元思考/live-model 策略，以及用量凭证 + 配额获取；未知的 `glm-5*` id 会基于内置的 `glm-4.7` 模板进行合成
- `xai`：原生 Responses 传输规范化、针对 Grok 快速变体的 `/fast` 别名重写、默认 `tool_stream`、xAI 特有的工具 schema / 推理负载清理，以及为 `grok-imagine-video` 注册的内置视频生成提供商
- `mistral`：插件自有能力元数据
- `opencode` 和 `opencode-go`：插件自有能力元数据，外加代理 Gemini thought-signature 清理
- `alibaba`：针对直接 Wan 模型引用（例如 `alibaba/wan2.6-t2v`）的插件自有视频生成目录
- `byteplus`：插件自有目录，外加为 Seedance 文生视频/图生视频模型注册的内置视频生成提供商
- `fal`：为托管第三方图像模型注册的内置图像生成提供商（FLUX 图像模型），外加为托管第三方视频模型注册的内置视频生成提供商
- `cloudflare-ai-gateway`、`huggingface`、`kimi`、`nvidia`、`qianfan`、`stepfun`、`synthetic`、`venice`、`vercel-ai-gateway` 和 `volcengine`：仅插件自有目录
- `qwen`：文本模型的插件自有目录，外加针对其多模态能力的共享媒体理解和视频生成提供商注册；Qwen 视频生成使用标准 DashScope 视频端点和内置 Wan 模型，例如 `wan2.6-t2v` 和 `wan2.7-r2v`
- `runway`：针对原生 Runway 任务型模型（例如 `gen4.5`）的插件自有视频生成提供商注册
- `minimax`：插件自有目录、为 Hailuo 视频模型注册的内置视频生成提供商、为 `image-01` 注册的内置图像生成提供商、混合 Anthropic/OpenAI 重放策略选择，以及用量凭证/快照逻辑
- `together`：插件自有目录，外加为 Wan 视频模型注册的内置视频生成提供商
- `xiaomi`：插件自有目录，外加用量凭证/快照逻辑
内置的 `openai` 插件现在同时拥有两个提供商 ID：`openai` 和 `openai-codex`。
内置的 `openai` 插件现在同时负责两个提供商 id：`openai` 和 `openai-codex`。
以上涵盖了仍适配 OpenClaw 常规传输的提供商。若某个提供商需要完全自定义的请求执行器，那就是另一类、更深层的扩展接口。
以上涵盖了仍适合 OpenClaw 常规传输方式的提供商。若某个提供商需要完全自定义的请求执行器，那就是一个单独且更深层的扩展接口。
## API key 轮换
## API 密钥轮换
- 支持为选定提供商进行通用提供商轮换。
- 通过以下方式配置多个 key：
- `OPENCLAW_LIVE_<PROVIDER>_KEY`（单个实时覆盖，最高优先级）
- 支持对选定提供商进行通用提供商轮换。
- 可通过以下方式配置多个密钥：
- `OPENCLAW_LIVE_<PROVIDER>_KEY`（单个 live 覆盖，最高优先级）
- `<PROVIDER>_API_KEYS`（逗号或分号分隔列表）
- `<PROVIDER>_API_KEY`（主 key）
- `<PROVIDER>_API_KEY`（主密钥）
- `<PROVIDER>_API_KEY_*`（编号列表，例如 `<PROVIDER>_API_KEY_1`）
- 对于 Google 提供商，还会将 `GOOGLE_API_KEY` 作为回退项包含在内。
- key 选择顺序会保留优先级并去重数值。
- 仅在收到速率限制响应时，才会使用下一个 key 重试请求（例如 `429`、`rate_limit`、`quota`、`resource exhausted`、`Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded`，或周期性的用量限制消息）。
- 非速率限制失败会立即失败；不会尝试 key 轮换。
- 当所有候选 key 都失败时，返回最后一次尝试的最终错误。
- 对于 Google 提供商，`GOOGLE_API_KEY` 也会作为回退项包含在内。
- 密钥选择顺序会保留优先级并对值去重。
- 只有在收到速率限制响应时，才会使用下一个密钥重试请求（例如 `429`、`rate_limit`、`quota`、`resource exhausted`、`Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded`，或周期性的用量限制消息）。
- 非速率限制失败会立即失败；不会尝试密钥轮换。
- 当所有候选密钥都失败时，返回最后一次尝试的最终错误。
## 内置提供商（pi-ai 目录）
OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要**
`models.providers` 配置；只需设置凭证并选择模型。
OpenClaw 附带 pi‑ai 目录。这些提供商**不需要** `models.providers` 配置；只需设置凭证并选择模型。
### OpenAI
- 提供商：`openai`
- 凭证：`OPENAI_API_KEY`
- 可选轮换：`OPENAI_API_KEYS`、`OPENAI_API_KEY_1`、`OPENAI_API_KEY_2`，以及 `OPENCLAW_LIVE_OPENAI_KEY`（单个覆盖）
- 可选轮换：`OPENAI_API_KEYS`、`OPENAI_API_KEY_1`、`OPENAI_API_KEY_2`，以及 `OPENCLAW_LIVE_OPENAI_KEY`（单一覆盖）
- 示例模型：`openai/gpt-5.4`、`openai/gpt-5.4-pro`
- CLI：`openclaw onboard --auth-choice openai-api-key`
- 默认传输为 `auto`（WebSocket 优先，SSE 回退）
- 默认传输是 `auto`（优先 WebSocket，回退 SSE）
- 可通过 `agents.defaults.models["openai/<model>"].params.transport` 为每个模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`）
- OpenAI Responses WebSocket 预热默认通过 `params.openaiWsWarmup` 启用（`true`/`false`）
- 可通过 `agents.defaults.models["openai/<model>"].params.serviceTier` 启用 OpenAI 优先级处理
- `/fast` 和 `params.fastMode` 会将直接 `openai/*` Responses 请求映射到 `api.openai.com` 上的 `service_tier=priority`
- 当你希望使用显式层级而不是共享的 `/fast` 开关时，请使用 `params.serviceTier`
- 隐藏的 OpenClaw 归因请求头（`originator`、`version`、`User-Agent`）只适用于发往 `api.openai.com` 的原生 OpenAI 流量，不适用于通用 OpenAI 兼容代理
- 原生 OpenAI 路由还会保留 Responses `store`、提示词缓存提示，以及 OpenAI 推理兼容负载整形；代理路由则不会
- `openai/gpt-5.3-codex-spark` 在 OpenClaw 中被有意抑制，因为实时 OpenAI API 会拒绝它；Spark 被视为仅限 Codex
- 当你想使用显式层级而不是共享的 `/fast` 开关时，请使用 `params.serviceTier`
- 隐藏的 OpenClaw 归因请求头（`originator`、`version`、`User-Agent`）仅适用于发往 `api.openai.com` 的原生 OpenAI 流量，不适用于通用 OpenAI 兼容代理
- 原生 OpenAI 路由还会保留 Responses `store`、提示缓存提示和 OpenAI 推理兼容负载整形；代理路由则不会
- `openai/gpt-5.3-codex-spark` 在 OpenClaw 中被有意屏蔽，因为 live OpenAI API 会拒绝它；Spark 被视为仅限 Codex
```json5
{
@ -156,12 +155,12 @@ OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要**
- 提供商：`anthropic`
- 凭证：`ANTHROPIC_API_KEY`
- 可选轮换：`ANTHROPIC_API_KEYS`、`ANTHROPIC_API_KEY_1`、`ANTHROPIC_API_KEY_2`，以及 `OPENCLAW_LIVE_ANTHROPIC_KEY`（单个覆盖）
- 可选轮换：`ANTHROPIC_API_KEYS`、`ANTHROPIC_API_KEY_1`、`ANTHROPIC_API_KEY_2`，以及 `OPENCLAW_LIVE_ANTHROPIC_KEY`（单一覆盖）
- 示例模型：`anthropic/claude-opus-4-6`
- CLI：`openclaw onboard --auth-choice apiKey`
- 直接公共 Anthropic 请求支持共享的 `/fast` 开关和 `params.fastMode`，包括发送到 `api.anthropic.com` 的 API key 和 OAuth 凭证流量；OpenClaw 会将其映射到 Anthropic `service_tier`（`auto` 与 `standard_only`）
- Anthropic 说明：Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 用法再次被允许，因此除非 Anthropic 发布新政策，否则 OpenClaw 将 Claude CLI 复用和 `claude -p` 用法视为该集成已获许可。
- Anthropic setup-token 仍可作为受支持的 OpenClaw 令牌路径使用，但 OpenClaw 现在在可用时更倾向于 Claude CLI 复用和 `claude -p`。
- 直接公共 Anthropic 请求支持共享的 `/fast` 开关和 `params.fastMode`，包括发送到 `api.anthropic.com` 的基于 API 密钥和 OAuth 认证的流量；OpenClaw 会将其映射为 Anthropic `service_tier`（`auto` 与 `standard_only`）
- Anthropic 说明：Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 用法再次被允许，因此除非 Anthropic 发布新政策，否则 OpenClaw 将 Claude CLI 复用和 `claude -p` 用法视为此集成的受支持方式。
- Anthropic setup-token 仍作为受支持的 OpenClaw 令牌路径保留，但 OpenClaw 现在在可用时优先使用 Claude CLI 复用和 `claude -p`。
```json5
{
@ -175,12 +174,12 @@ OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要**
- 凭证：OAuth（ChatGPT）
- 示例模型：`openai-codex/gpt-5.4`
- CLI：`openclaw onboard --auth-choice openai-codex` 或 `openclaw models auth login --provider openai-codex`
- 默认传输为 `auto`（WebSocket 优先，SSE 回退）
- 默认传输是 `auto`（优先 WebSocket，回退 SSE）
- 可通过 `agents.defaults.models["openai-codex/<model>"].params.transport` 为每个模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`）
- `params.serviceTier` 也会在原生 Codex Responses 请求（`chatgpt.com/backend-api`）上传递
- `params.serviceTier` 也会转发到原生 Codex Responses 请求（`chatgpt.com/backend-api`）上
- 隐藏的 OpenClaw 归因请求头（`originator`、`version`、`User-Agent`）仅附加到发往 `chatgpt.com/backend-api` 的原生 Codex 流量，不适用于通用 OpenAI 兼容代理
- 与直接 `openai/*` 共用相同的 `/fast` 开关和 `params.fastMode` 配置；OpenClaw 会将其映射为 `service_tier=priority`
- 当 Codex OAuth 目录暴露 `openai-codex/gpt-5.3-codex-spark` 时，该模型仍可用；是否可用取决于 entitlement
- 与直接 `openai/*` 共享同一个 `/fast` 开关和 `params.fastMode` 配置；OpenClaw 会将其映射到 `service_tier=priority`
- 当 Codex OAuth 目录暴露该模型时，`openai-codex/gpt-5.3-codex-spark` 仍然可用；取决于授权资格
- `openai-codex/gpt-5.4` 保持原生 `contextWindow = 1050000` 和默认运行时 `contextTokens = 272000`；可通过 `models.providers.openai-codex.models[].contextTokens` 覆盖运行时上限
- 策略说明：OpenAI Codex OAuth 明确支持像 OpenClaw 这样的外部工具/工作流。
@ -204,8 +203,8 @@ OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要**
### 其他订阅式托管选项
- [Qwen Cloud](/zh-CN/providers/qwen)：Qwen Cloud 提供商界面，以及 Alibaba DashScope 和 Coding Plan 端点映射
- [MiniMax](/zh-CN/providers/minimax)：MiniMax Coding Plan OAuth 或 API key 访问
- [Qwen Cloud](/zh-CN/providers/qwen)：Qwen Cloud 提供商接口，以及 Alibaba DashScope 和 Coding Plan 端点映射
- [MiniMax](/zh-CN/providers/minimax)：MiniMax Coding Plan OAuth 或 API 密钥访问
- [GLM Models](/zh-CN/providers/glm)：Z.AI Coding Plan 或通用 API 端点
### OpenCode
@ -222,23 +221,21 @@ OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要**
}
```
### Google Gemini（API key）
### Google Gemini（API 密钥）
- 提供商：`google`
- 凭证：`GEMINI_API_KEY`
- 可选轮换：`GEMINI_API_KEYS`、`GEMINI_API_KEY_1`、`GEMINI_API_KEY_2`、`GOOGLE_API_KEY` 回退项，以及 `OPENCLAW_LIVE_GEMINI_KEY`（单个覆盖）
- 可选轮换：`GEMINI_API_KEYS`、`GEMINI_API_KEY_1`、`GEMINI_API_KEY_2`、`GOOGLE_API_KEY` 回退项，以及 `OPENCLAW_LIVE_GEMINI_KEY`（单一覆盖）
- 示例模型：`google/gemini-3.1-pro-preview`、`google/gemini-3-flash-preview`
- 兼容性：使用 `google/gemini-3.1-flash-preview` 的旧版 OpenClaw 配置会被标准化为 `google/gemini-3-flash-preview`
- 兼容性：使用 `google/gemini-3.1-flash-preview` 的旧版 OpenClaw 配置会被规范化为 `google/gemini-3-flash-preview`
- CLI：`openclaw onboard --auth-choice gemini-api-key`
- 直接 Gemini 运行也接受 `agents.defaults.models["google/<model>"].params.cachedContent`
（或旧版 `cached_content`），以转发提供商原生的
`cachedContents/...` 句柄；Gemini 缓存命中会显示为 OpenClaw `cacheRead`
- 直接 Gemini 运行还接受 `agents.defaults.models["google/<model>"].params.cachedContent`（或旧版 `cached_content`），用于转发提供商原生的 `cachedContents/...` 句柄；Gemini 缓存命中会显示为 OpenClaw `cacheRead`
### Google Vertex 和 Gemini CLI
- 提供商：`google-vertex`、`google-gemini-cli`
- 凭证：Vertex 使用 gcloud ADC；Gemini CLI 使用其 OAuth 流程
- 注意：OpenClaw 中的 Gemini CLI OAuth 是非官方集成。一些用户报告称，在使用第三方客户端后遭遇了 Google 账号限制。如果你选择继续，请先查看 Google 条款，并使用非关键账号。
- 注意：OpenClaw 中的 Gemini CLI OAuth 是非官方集成。一些用户报告称，在使用第三方客户端后其 Google 账号受到了限制。请先查看 Google 条款，并在你决定继续时使用非关键账号。
- Gemini CLI OAuth 作为内置 `google` 插件的一部分提供。
- 先安装 Gemini CLI：
- `brew install gemini-cli`
@ -246,10 +243,9 @@ OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要**
- 启用：`openclaw plugins enable google`
- 登录：`openclaw models auth login --provider google-gemini-cli --set-default`
- 默认模型：`google-gemini-cli/gemini-3-flash-preview`
- 注意：你**不需要**将 client id 或 secret 粘贴到 `openclaw.json` 中。CLI 登录流程会将令牌存储在 Gateway 网关主机上的凭证配置中。
- 注意：你**不需要**将 client id 或 secret 粘贴到 `openclaw.json` 中。CLI 登录流程会将令牌存储在 Gateway 网关主机上的凭证配置档中。
- 如果登录后请求失败，请在 Gateway 网关主机上设置 `GOOGLE_CLOUD_PROJECT` 或 `GOOGLE_CLOUD_PROJECT_ID`。
- Gemini CLI JSON 回复会从 `response` 解析；用量会回退到
`stats`，其中 `stats.cached` 会被标准化为 OpenClaw `cacheRead`。
- Gemini CLI JSON 回复从 `response` 解析；用量会回退到 `stats`，其中 `stats.cached` 会被规范化为 OpenClaw `cacheRead`。
### Z.AI（GLM）
@ -257,8 +253,8 @@ OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要**
- 凭证：`ZAI_API_KEY`
- 示例模型：`zai/glm-5.1`
- CLI：`openclaw onboard --auth-choice zai-api-key`
- 别名：`z.ai/*` 和 `z-ai/*` 会被标准化为 `zai/*`
- `zai-api-key` 会自动检测匹配的 Z.AI 端点；`zai-coding-global`、`zai-coding-cn`、`zai-global` 和 `zai-cn` 会强制使用特定界面
- 别名：`z.ai/*` 和 `z-ai/*` 会被规范化为 `zai/*`
- `zai-api-key` 会自动检测匹配的 Z.AI 端点；`zai-coding-global`、`zai-coding-cn`、`zai-global` 和 `zai-cn` 会强制使用特定接口
### Vercel AI Gateway
@ -274,31 +270,26 @@ OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要**
- 示例模型：`kilocode/kilo/auto`
- CLI：`openclaw onboard --auth-choice kilocode-api-key`
- Base URL：`https://api.kilo.ai/api/gateway/`
- 静态回退目录内置 `kilocode/kilo/auto`；实时
`https://api.kilo.ai/api/gateway/models` 发现可以进一步扩展运行时
目录。
- `kilocode/kilo/auto` 背后的精确上游路由由 Kilo Gateway 自行管理，
并非在 OpenClaw 中硬编码。
- 静态回退目录附带 `kilocode/kilo/auto`；实时 `https://api.kilo.ai/api/gateway/models` 发现还可以进一步扩展运行时目录。
- `kilocode/kilo/auto` 背后的精确上游路由由 Kilo Gateway 负责，不是 OpenClaw 中硬编码的。
设置详情请参见 [/providers/kilocode](/zh-CN/providers/kilocode)。
有关设置详情，请参见 [/providers/kilocode](/zh-CN/providers/kilocode)。
### 其他内置提供商插件
- OpenRouter：`openrouter`（`OPENROUTER_API_KEY`）
- 示例模型：`openrouter/auto`
- OpenClaw 仅在请求实际发往 `openrouter.ai` 时才会应用 OpenRouter 文档中说明的应用归因请求头
- OpenRouter 特有的 Anthropic `cache_control` 标记同样只会作用于经过验证的 OpenRouter 路由，而不是任意代理 URL
- OpenRouter 仍走代理风格的 OpenAI 兼容路径，因此仅适用于原生 OpenAI 的请求整形（`serviceTier`、Responses `store`、提示词缓存提示、OpenAI 推理兼容负载）不会被转发
- 基于 Gemini 的 OpenRouter 引用只保留代理 Gemini thought-signature 清理；原生 Gemini 重放校验和引导重写保持关闭
- 只有当请求实际发往 `openrouter.ai` 时，OpenClaw 才会应用 OpenRouter 文档中的应用归因请求头
- OpenRouter 特有的 Anthropic `cache_control` 标记同样只会在已验证的 OpenRouter 路由上启用，而不是任意代理 URL
- OpenRouter 仍然走代理风格的 OpenAI 兼容路径，因此原生仅限 OpenAI 的请求整形（`serviceTier`、Responses `store`、提示缓存提示、OpenAI 推理兼容负载）不会被转发
- 基于 Gemini 的 OpenRouter 引用仅保留代理 Gemini thought-signature 清理；原生 Gemini 重放校验和引导重写保持关闭
- Kilo Gateway：`kilocode`（`KILOCODE_API_KEY`）
- 示例模型：`kilocode/kilo/auto`
- 基于 Gemini 的 Kilo 引用保留相同的代理 Gemini thought-signature
清理路径；`kilocode/kilo/auto` 以及其他不支持代理推理的提示会跳过代理推理注入
- MiniMax：`minimax`（API key）和 `minimax-portal`（OAuth）
- 基于 Gemini 的 Kilo 引用保留相同的代理 Gemini thought-signature 清理路径；`kilocode/kilo/auto` 和其他不支持代理推理的提示会跳过代理推理注入
- MiniMax：`minimax`（API 密钥）和 `minimax-portal`（OAuth）
- 凭证：`minimax` 使用 `MINIMAX_API_KEY`；`minimax-portal` 使用 `MINIMAX_OAUTH_TOKEN` 或 `MINIMAX_API_KEY`
- 示例模型：`minimax/MiniMax-M2.7` 或 `minimax-portal/MiniMax-M2.7`
- MiniMax 新手引导/API key 设置会写入显式的 M2.7 模型定义，并带有
`input: ["text", "image"]`；内置提供商目录会在该提供商配置具体化之前，将聊天引用保持为仅文本
- MiniMax 新手引导/API 密钥设置会写入显式 M2.7 模型定义，并包含 `input: ["text", "image"]`；在该提供商配置具体化之前，内置提供商目录会将聊天引用保持为仅文本
- Moonshot：`moonshot`（`MOONSHOT_API_KEY`）
- 示例模型：`moonshot/kimi-k2.6`
- Kimi Coding：`kimi`（`KIMI_API_KEY` 或 `KIMICODE_API_KEY`）
@ -321,39 +312,32 @@ OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要**
- Cloudflare AI Gateway：`cloudflare-ai-gateway`（`CLOUDFLARE_AI_GATEWAY_API_KEY`）
- Volcengine：`volcengine`（`VOLCANO_ENGINE_API_KEY`）
- 示例模型：`volcengine-plan/ark-code-latest`
- BytePlus：`byteplus`（`BYTEPLUS_API_KEY`）
- BytePlus（国际版）：`byteplus`（`BYTEPLUS_API_KEY`）
- 示例模型：`byteplus-plan/ark-code-latest`
- xAI：`xai`（`XAI_API_KEY`）
- 原生内置 xAI 请求使用 xAI Responses 路径
- `/fast` 或 `params.fastMode: true` 会将 `grok-3`、`grok-3-mini`、
`grok-4` 和 `grok-4-0709` 重写为其 `*-fast` 变体
- `tool_stream` 默认开启；设置
`agents.defaults.models["xai/<model>"].params.tool_stream` 为 `false` 可
关闭
- `/fast` 或 `params.fastMode: true` 会将 `grok-3`、`grok-3-mini`、`grok-4` 和 `grok-4-0709` 重写为它们的 `*-fast` 变体
- `tool_stream` 默认开启；将 `agents.defaults.models["xai/<model>"].params.tool_stream` 设为 `false` 可关闭它
- Mistral：`mistral`（`MISTRAL_API_KEY`）
- 示例模型：`mistral/mistral-large-latest`
- CLI：`openclaw onboard --auth-choice mistral-api-key`
- Groq：`groq`（`GROQ_API_KEY`）
- Cerebras：`cerebras`（`CEREBRAS_API_KEY`）
- Cerebras 上的 GLM 模型使用 ID `zai-glm-4.7` 和 `zai-glm-4.6`。
- Cerebras 上的 GLM 模型使用 id `zai-glm-4.7` 和 `zai-glm-4.6`。
- OpenAI 兼容 Base URL：`https://api.cerebras.ai/v1`。
- GitHub Copilot：`github-copilot`（`COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN`）
- Hugging Face Inference 示例模型：`huggingface/deepseek-ai/DeepSeek-R1`；CLI：`openclaw onboard --auth-choice huggingface-api-key`。参见 [Hugging Face（Inference）](/zh-CN/providers/huggingface)。
## 通过 `models.providers` 使用提供商（自定义/Base URL）
## 通过 `models.providers` 配置的提供商（自定义/Base URL）
使用 `models.providers`（或 `models.json`）添加**自定义**提供商或
OpenAI/Anthropic 兼容代理。
使用 `models.providers`（或 `models.json`）添加**自定义**提供商或 OpenAI/Anthropic 兼容代理。
下方许多内置提供商插件已经发布了默认目录。
只有在你想覆盖默认 Base URL、请求头或模型列表时，才需要显式使用
`models.providers.<id>` 条目。
下面许多内置提供商插件已经发布了默认目录。
只有当你想覆盖默认 Base URL、请求头或模型列表时，才使用显式 `models.providers.<id>` 条目。
### Moonshot AI（Kimi）
Moonshot 作为内置提供商插件提供。默认使用内置提供商，只有在你
需要覆盖 Base URL 或模型元数据时，才添加显式的 `models.providers.moonshot`
条目：
Moonshot 作为内置提供商插件提供。默认使用内置提供商，只有在你需要覆盖 Base URL 或模型元数据时，才添加显式 `models.providers.moonshot` 条目：
- 提供商：`moonshot`
- 凭证：`MOONSHOT_API_KEY`
@ -408,13 +392,13 @@ Kimi Coding 使用 Moonshot AI 的 Anthropic 兼容端点：
}
```
旧版 `kimi/k2p5` 仍然作为兼容模型 ID 被接受。
旧版 `kimi/k2p5` 仍然作为兼容模型 id 被接受。
### Volcano Engine（Doubao）
Volcano Engine（火山引擎）在中国提供对 Doubao 和其他模型的访问。
- 提供商：`volcengine`（coding：`volcengine-plan`）
- 提供商：`volcengine`（编程方案：`volcengine-plan`）
- 凭证：`VOLCANO_ENGINE_API_KEY`
- 示例模型：`volcengine-plan/ark-code-latest`
- CLI：`openclaw onboard --auth-choice volcengine-api-key`
@ -427,12 +411,9 @@ Volcano Engine（火山引擎）在中国提供对 Doubao 和其他模型的访
}
```
新手引导默认使用 coding 界面，但通用 `volcengine/*`
目录会同时注册。
新手引导默认使用编程接口，但通用的 `volcengine/*` 目录会同时注册。
在新手引导/配置模型选择器中，Volcengine 凭证选项会优先显示
`volcengine/*` 和 `volcengine-plan/*` 条目。如果这些模型尚未加载，
OpenClaw 会回退到未筛选目录，而不是显示一个空的提供商范围选择器。
在新手引导/配置模型选择器中，Volcengine 凭证选项会优先显示 `volcengine/*` 和 `volcengine-plan/*` 条目。如果这些模型尚未加载，OpenClaw 会回退到未筛选的目录，而不是显示一个空的提供商范围选择器。
可用模型：
@ -442,7 +423,7 @@ OpenClaw 会回退到未筛选目录，而不是显示一个空的提供商范
- `volcengine/glm-4-7-251222`（GLM 4.7）
- `volcengine/deepseek-v3-2-251201`（DeepSeek V3.2 128K）
Coding 模型（`volcengine-plan`）：
编程模型（`volcengine-plan`）：
- `volcengine-plan/ark-code-latest`
- `volcengine-plan/doubao-seed-code`
@ -454,7 +435,7 @@ Coding 模型（`volcengine-plan`）：
BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问。
- 提供商：`byteplus`（coding：`byteplus-plan`）
- 提供商：`byteplus`（编程方案：`byteplus-plan`）
- 凭证：`BYTEPLUS_API_KEY`
- 示例模型：`byteplus-plan/ark-code-latest`
- CLI：`openclaw onboard --auth-choice byteplus-api-key`
@ -467,12 +448,9 @@ BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问。
}
```
新手引导默认使用 coding 界面，但通用 `byteplus/*`
目录会同时注册。
新手引导默认使用编程接口，但通用的 `byteplus/*` 目录会同时注册。
在新手引导/配置模型选择器中，BytePlus（国际版）凭证选项会优先显示
`byteplus/*` 和 `byteplus-plan/*` 条目。如果这些模型尚未加载，
OpenClaw 会回退到未筛选目录，而不是显示一个空的提供商范围选择器。
在新手引导/配置模型选择器中，BytePlus（国际版）凭证选项会优先显示 `byteplus/*` 和 `byteplus-plan/*` 条目。如果这些模型尚未加载，OpenClaw 会回退到未筛选的目录，而不是显示一个空的提供商范围选择器。
可用模型：
@ -480,7 +458,7 @@ OpenClaw 会回退到未筛选目录，而不是显示一个空的提供商范
- `byteplus/kimi-k2-5-260127`（Kimi K2.5）
- `byteplus/glm-4-7-251222`（GLM 4.7）
Coding 模型（`byteplus-plan`）：
编程模型（`byteplus-plan`）：
- `byteplus-plan/ark-code-latest`
- `byteplus-plan/doubao-seed-code`
@ -522,33 +500,30 @@ MiniMax 通过 `models.providers` 配置，因为它使用自定义端点：
- MiniMax OAuth（Global）：`--auth-choice minimax-global-oauth`
- MiniMax OAuth（CN）：`--auth-choice minimax-cn-oauth`
- MiniMax API key（Global）：`--auth-choice minimax-global-api`
- MiniMax API key（CN）：`--auth-choice minimax-cn-api`
- 凭证：`minimax` 使用 `MINIMAX_API_KEY`；`minimax-portal` 使用 `MINIMAX_OAUTH_TOKEN` 或
`MINIMAX_API_KEY`
- MiniMax API 密钥（Global）：`--auth-choice minimax-global-api`
- MiniMax API 密钥（CN）：`--auth-choice minimax-cn-api`
- 凭证：`minimax` 使用 `MINIMAX_API_KEY`；`minimax-portal` 使用 `MINIMAX_OAUTH_TOKEN` 或 `MINIMAX_API_KEY`
设置详情、模型选项和配置片段请参见 [/providers/minimax](/zh-CN/providers/minimax)。
有关设置详情、模型选项和配置片段，请参见 [/providers/minimax](/zh-CN/providers/minimax)。
在 MiniMax 的 Anthropic 兼容流式路径上，OpenClaw 默认禁用 thinking，
除非你显式设置它，并且 `/fast on` 会将
`MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。
在 MiniMax 的 Anthropic 兼容流式路径上，OpenClaw 默认禁用 thinking，除非你显式设置它；而 `/fast on` 会将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。
插件自有 capability 划分：
插件自有能力划分：
- 文本/聊天默认保持在 `minimax/MiniMax-M2.7`
- 图像生成使用 `minimax/image-01` 或 `minimax-portal/image-01`
- 图像理解在两种 MiniMax 凭证路径上都使用插件自有的 `MiniMax-VL-01`
- Web 搜索保持使用提供商 ID `minimax`
- 图像理解由两个 MiniMax 凭证路径上的插件自有 `MiniMax-VL-01` 负责
- Web 搜索仍使用提供商 id `minimax`
### LM Studio
LM Studio 作为内置提供商插件提供，并使用原生 API：
LM Studio 作为一个使用原生 API 的内置提供商插件提供：
- 提供商：`lmstudio`
- 凭证：`LM_API_TOKEN`
- 默认推理 Base URL：`http://localhost:1234/v1`
然后设置一个模型（请替换为 `http://localhost:1234/api/v1/models` 返回的某个 ID）：
然后设置一个模型（替换为 `http://localhost:1234/api/v1/models` 返回的某个 ID）：
```json5
{
@ -558,16 +533,15 @@ LM Studio 作为内置提供商插件提供，并使用原生 API：
}
```
OpenClaw 使用 LM Studio 原生的 `/api/v1/models` 和 `/api/v1/models/load`
进行发现 + 自动加载，并默认使用 `/v1/chat/completions` 进行推理。
设置和故障排除请参见 [/providers/lmstudio](/zh-CN/providers/lmstudio)。
OpenClaw 使用 LM Studio 原生的 `/api/v1/models` 和 `/api/v1/models/load` 进行发现 + 自动加载，并默认使用 `/v1/chat/completions` 进行推理。
有关设置和故障排除，请参见 [/providers/lmstudio](/zh-CN/providers/lmstudio)。
### Ollama
Ollama 作为内置提供商插件提供，并使用 Ollama 的原生 API：
- 提供商：`ollama`
- 凭证：不需要（本地服务器）
- 凭证：无需（本地服务器）
- 示例模型：`ollama/llama3.3`
- 安装：[https://ollama.com/download](https://ollama.com/download)
@ -584,26 +558,23 @@ ollama pull llama3.3
}
```
当你通过 `OLLAMA_API_KEY` 选择启用时，系统会在本地 `http://127.0.0.1:11434` 检测 Ollama，
并且内置提供商插件会将 Ollama 直接添加到
`openclaw onboard` 和模型选择器中。有关新手引导、云端/本地模式和自定义配置，请参见 [/providers/ollama](/zh-CN/providers/ollama)。
当你通过 `OLLAMA_API_KEY` 明确启用时，系统会在 `http://127.0.0.1:11434` 本地检测 Ollama，并且内置提供商插件会将 Ollama 直接加入 `openclaw onboard` 和模型选择器。有关新手引导、云端/本地模式和自定义配置，请参见 [/providers/ollama](/zh-CN/providers/ollama)。
### vLLM
vLLM 作为内置提供商插件提供，适用于本地/自托管的 OpenAI 兼容
服务器：
vLLM 作为内置提供商插件提供，适用于本地/自托管的 OpenAI 兼容服务器：
- 提供商：`vllm`
- 凭证：可选（取决于你的服务器）
- 默认 Base URL：`http://127.0.0.1:8000/v1`
要在本地选择启用自动发现（如果你的服务器不强制凭证，任意值都可以）：
要在本地启用自动发现（如果你的服务器不强制要求凭证，任意值都可以）：
```bash
export VLLM_API_KEY="vllm-local"
```
然后设置一个模型（请替换为 `/v1/models` 返回的某个 ID）：
然后设置一个模型（替换为 `/v1/models` 返回的某个 ID）：
```json5
{
@ -617,21 +588,19 @@ export VLLM_API_KEY="vllm-local"
### SGLang
SGLang 作为内置提供商插件提供，适用于快速自托管的
OpenAI 兼容服务器：
SGLang 作为内置提供商插件提供，适用于高速自托管的 OpenAI 兼容服务器：
- 提供商：`sglang`
- 凭证：可选（取决于你的服务器）
- 默认 Base URL：`http://127.0.0.1:30000/v1`
要在本地选择启用自动发现（如果你的服务器不强制
凭证，任意值都可以）：
要在本地启用自动发现（如果你的服务器不强制要求凭证，任意值都可以）：
```bash
export SGLANG_API_KEY="sglang-local"
```
然后设置一个模型（请替换为 `/v1/models` 返回的某个 ID）：
然后设置一个模型（替换为 `/v1/models` 返回的某个 ID）：
```json5
{
@ -680,20 +649,18 @@ export SGLANG_API_KEY="sglang-local"
说明：
- 对于自定义提供商，`reasoning`、`input`、`cost`、`contextWindow` 和 `maxTokens` 都是可选项。
如果省略，OpenClaw 默认使用：
- 对于自定义提供商，`reasoning`、`input`、`cost`、`contextWindow` 和 `maxTokens` 都是可选的。
省略时，OpenClaw 默认值为：
- `reasoning: false`
- `input: ["text"]`
- `cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }`
- `contextWindow: 200000`
- `maxTokens: 8192`
- 建议：设置与你的代理/模型限制相匹配的显式值。
- 对于非原生端点上的 `api: "openai-completions"`（任何 host 不是 `api.openai.com` 的非空 `baseUrl`），OpenClaw 会强制设置 `compat.supportsDeveloperRole: false`，以避免提供商因不支持 `developer` 角色而返回 400 错误。
- 代理风格的 OpenAI 兼容路由也会跳过仅适用于原生 OpenAI 的请求
整形：没有 `service_tier`、没有 Responses `store`、没有提示词缓存提示、没有
OpenAI 推理兼容负载整形，也没有隐藏的 OpenClaw 归因请求头。
- 如果 `baseUrl` 为空/省略，OpenClaw 会保留默认的 OpenAI 行为（即解析到 `api.openai.com`）。
- 为了安全起见，即使显式设置了 `compat.supportsDeveloperRole: true`，在非原生 `openai-completions` 端点上仍会被覆盖。
- 建议：设置与你的代理/模型限制一致的显式值。
- 对于非原生端点上的 `api: "openai-completions"`（任何 host 不是 `api.openai.com` 的非空 `baseUrl`），OpenClaw 会强制 `compat.supportsDeveloperRole: false`，以避免提供商因不支持 `developer` 角色而返回 400 错误。
- 代理风格的 OpenAI 兼容路由也会跳过原生 OpenAI 专用的请求整形：没有 `service_tier`，没有 Responses `store`，没有提示缓存提示，没有 OpenAI 推理兼容负载整形，也没有隐藏的 OpenClaw 归因请求头。
- 如果 `baseUrl` 为空或省略，OpenClaw 会保留默认 OpenAI 行为（其解析结果为 `api.openai.com`）。
- 为了安全起见，在非原生 `openai-completions` 端点上，显式的 `compat.supportsDeveloperRole: true` 仍然会被覆盖。
## CLI 示例
@ -710,4 +677,4 @@ openclaw models list
- [Models](/zh-CN/concepts/models) — 模型配置和别名
- [Model Failover](/zh-CN/concepts/model-failover) — 回退链和重试行为
- [Configuration Reference](/zh-CN/gateway/configuration-reference#agent-defaults) — 模型配置键
- [Providers](/zh-CN/providers) — 按提供商分别说明的设置指南
- [Providers](/zh-CN/providers) — 按提供商划分的设置指南

1457
docs/zh-CN/gateway/configuration-reference.md
View File

File diff suppressed because it is too large Load Diff

808
docs/zh-CN/help/testing.md
View File

File diff suppressed because it is too large Load Diff

30
docs/zh-CN/providers/fireworks.md
View File

@ -2,13 +2,13 @@
read_when:
- 你想在 OpenClaw 中使用 Fireworks
- 你需要 Fireworks API 密钥环境变量或默认模型 ID
summary: Fireworks 设置（凭证 + 模型选择）
summary: Fireworks 设置（认证 + 模型选择）
title: Fireworks
x-i18n:
generated_at: "2026-04-21T19:44:01Z"
generated_at: "2026-04-21T20:53:27Z"
model: gpt-5.4
provider: openai
source_hash: fb2268b8d6d58da66c7db7423062d6b308a6f657e2825a406e2b5d1d499afa05
source_hash: 1b2aae346f1fb7e6d649deefe9117d8d8399c0441829cb49132ff5b86a7051ce
source_path: providers/fireworks.md
workflow: 15
---
@ -20,7 +20,7 @@ x-i18n:
| 属性 | 值 |
| ------------- | ------------------------------------------------------ |
| 提供商 | `fireworks` |
| 凭证 | `FIREWORKS_API_KEY` |
| 认证 | `FIREWORKS_API_KEY` |
| API | 与 OpenAI 兼容的 chat/completions |
| 基础 URL | `https://api.fireworks.ai/inference/v1` |
| 默认模型 | `fireworks/accounts/fireworks/routers/kimi-k2p5-turbo` |
@ -28,7 +28,7 @@ x-i18n:
## 入门指南
<Steps>
<Step title="通过新手引导设置 Fireworks 凭证">
<Step title="通过新手引导设置 Fireworks 认证">
```bash
openclaw onboard --auth-choice fireworks-api-key
```
@ -59,17 +59,17 @@ openclaw onboard --non-interactive \
## 内置目录
| 模型引用 | 名称 | 输入 | 上下文 | 最大输出 | 说明 |
| ------------------------------------------------------ | --------------------------- | ---------- | ------- | ---------- | ------------------------------------------ |
| `fireworks/accounts/fireworks/models/kimi-k2p6` | Kimi K2.6 | text,image | 262,144 | 262,144 | Fireworks 上最新的 Kimi 模型 |
| ------------------------------------------------------ | --------------------------- | ---------- | ------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fireworks/accounts/fireworks/models/kimi-k2p6` | Kimi K2.6 | text,image | 262,144 | 262,144 | Fireworks 上最新的 Kimi 模型。Fireworks K2.6 请求已禁用 thinking；如果你需要 Kimi 的 thinking 输出，请直接通过 Moonshot 路由。 |
| `fireworks/accounts/fireworks/routers/kimi-k2p5-turbo` | Kimi K2.5 Turbo（Fire Pass） | text,image | 256,000 | 256,000 | Fireworks 上默认内置的入门模型 |
<Tip>
如果 Fireworks 发布了更新的模型，例如新的 Qwen 或 Gemma 版本，你可以直接使用其 Fireworks 模型 ID 切换到该模型，而无需等待内置目录更新。
如果 Fireworks 发布了更新的模型，例如新的 Qwen 或 Gemma 版本，你可以直接使用其 Fireworks 模型 id 切换到该模型，而无需等待内置目录更新。
</Tip>
## 自定义 Fireworks 模型 ID
## 自定义 Fireworks 模型 id
OpenClaw 也接受动态 Fireworks 模型 ID。使用 Fireworks 显示的精确模型或路由器 ID，并为其添加 `fireworks/` 前缀。
OpenClaw 也接受动态 Fireworks 模型 id。请使用 Fireworks 显示的精确模型或路由 id，并加上 `fireworks/` 前缀。
```json5
{
@ -84,13 +84,13 @@ OpenClaw 也接受动态 Fireworks 模型 ID。使用 Fireworks 显示的精确
```
<AccordionGroup>
<Accordion title="模型 ID 前缀的工作方式">
OpenClaw 中的每个 Fireworks 模型引用都以 `fireworks/` 开头，后面跟着 Fireworks 平台中的精确 ID 或路由路径。例如：
<Accordion title="模型 id 前缀的工作方式">
OpenClaw 中的每个 Fireworks 模型引用都以 `fireworks/` 开头，后接 Fireworks 平台中的精确 id 或路由路径。例如：
- 路由模型：`fireworks/accounts/fireworks/routers/kimi-k2p5-turbo`
- 直接模型：`fireworks/accounts/fireworks/models/<model-name>`
OpenClaw 在构建 API 请求时会去掉 `fireworks/` 前缀，并将剩余路径发送到 Fireworks 端点。
OpenClaw 在构建 API 请求时会去掉 `fireworks/` 前缀，并将其余路径发送到 Fireworks 端点。
</Accordion>
@ -98,7 +98,7 @@ OpenClaw 也接受动态 Fireworks 模型 ID。使用 Fireworks 显示的精确
如果 Gateway 网关 运行在你的交互式 shell 之外，请确保 `FIREWORKS_API_KEY` 对该进程也可用。
<Warning>
如果密钥仅存在于 `~/.profile` 中，那么对于 `launchd`/`systemd` 守护进程它不会起作用，除非该环境也被导入到那里。请在 `~/.openclaw/.env` 中设置该密钥，或通过 `env.shellEnv` 设置，以确保网关进程可以读取它。
仅存在于 `~/.profile` 中的密钥无法帮助 `launchd`/`systemd` 守护进程，除非该环境也被导入到那里。请在 `~/.openclaw/.env` 中设置该密钥，或通过 `env.shellEnv` 设置，以确保 Gateway 网关 进程可以读取它。
</Warning>
</Accordion>
@ -111,6 +111,6 @@ OpenClaw 也接受动态 Fireworks 模型 ID。使用 Fireworks 显示的精确
选择提供商、模型引用和故障切换行为。
</Card>
<Card title="故障排除" href="/zh-CN/help/troubleshooting" icon="wrench">
常规故障排除和常见问题。
一般故障排除和常见问题。
</Card>
</CardGroup>

112
docs/zh-CN/providers/ollama.md
View File

@ -1,21 +1,21 @@
---
read_when:
- 你想通过 Ollama 使用云端或本地模型运行 OpenClaw
- 你需要 Ollama 的设置和配置指导
- 你需要 Ollama 的设置和配置指南
summary: 使用 Ollama（云端和本地模型）运行 OpenClaw
title: Ollama
x-i18n:
generated_at: "2026-04-15T13:38:11Z"
generated_at: "2026-04-21T20:53:29Z"
model: gpt-5.4
provider: openai
source_hash: 098e083e0fc484bddb5270eb630c55d7832039b462d1710372b6afece5cefcdf
source_hash: 197612f2173409d186b915b838e5fdba2f594912672f3c450accb4877e732c9c
source_path: providers/ollama.md
workflow: 15
---
# Ollama
OpenClaw 集成了 Ollama 的原生 API（`/api/chat`），可用于托管云模型以及本地/自托管的 Ollama 服务器。你可以通过三种模式使用 Ollama：通过可访问的 Ollama 主机实现的 `Cloud + Local`、直接连接 `https://ollama.com` 的 `Cloud only`，或连接可访问的 Ollama 主机的 `Local only`。
OpenClaw 集成了 Ollama 的原生 API（`/api/chat`），可用于托管云模型以及本地/自托管的 Ollama 服务器。你可以通过三种模式使用 Ollama：通过可访问的 Ollama 主机实现的 `Cloud + Local`、对接 `https://ollama.com` 的 `Cloud only`，或对接可访问 Ollama 主机的 `Local only`。
<Warning>
**远程 Ollama 用户**：不要在 OpenClaw 中使用 `/v1` 的 OpenAI 兼容 URL（`http://host:11434/v1`）。这会破坏工具调用，模型还可能将原始工具 JSON 作为纯文本输出。请改用原生 Ollama API URL：`baseUrl: "http://host:11434"`（不要加 `/v1`）。
@ -27,7 +27,7 @@ OpenClaw 集成了 Ollama 的原生 API（`/api/chat`），可用于托管云模
<Tabs>
<Tab title="新手引导（推荐）">
**最适合：** 以最快路径完成可用的 Ollama 云端或本地设置。
**最适合：** 以最快方式完成可用的 Ollama 云端或本地设置。
<Steps>
<Step title="运行新手引导">
@ -35,15 +35,15 @@ OpenClaw 集成了 Ollama 的原生 API（`/api/chat`），可用于托管云模
openclaw onboard
```
在提供商列表中选择 **Ollama**。
从提供商列表中选择 **Ollama**。
</Step>
<Step title="选择你的模式">
- **Cloud + Local** — 本地 Ollama 主机加上通过该主机路由的云模型
- **Cloud only** — 通过 `https://ollama.com` 使用托管的 Ollama 模型
- **Cloud + Local** — 本地 Ollama 主机，加上通过该主机路由的云模型
- **Cloud only** — 通过 `https://ollama.com` 使用托管 Ollama 模型
- **Local only** — 仅使用本地模型
</Step>
<Step title="选择模型">
`Cloud only` 会提示输入 `OLLAMA_API_KEY`，并推荐托管云模型的默认值。`Cloud + Local` 和 `Local only` 会要求提供 Ollama 基础 URL、发现可用模型，并在所选本地模型尚不可用时自动拉取。`Cloud + Local` 还会检查该 Ollama 主机是否已登录以启用云访问。
`Cloud only` 会提示输入 `OLLAMA_API_KEY`，并推荐托管云端默认模型。`Cloud + Local` 和 `Local only` 会要求提供 Ollama base URL，发现可用模型，并在所选本地模型尚不可用时自动拉取。`Cloud + Local` 还会检查该 Ollama 主机是否已登录以启用云访问。
</Step>
<Step title="验证模型可用">
```bash
@ -60,7 +60,7 @@ OpenClaw 集成了 Ollama 的原生 API（`/api/chat`），可用于托管云模
--accept-risk
```
也可以选择指定自定义基础 URL 或模型：
你也可以选择指定自定义 base URL 或模型：
```bash
openclaw onboard --non-interactive \
@ -78,10 +78,10 @@ OpenClaw 集成了 Ollama 的原生 API（`/api/chat`），可用于托管云模
<Steps>
<Step title="选择云端或本地">
- **Cloud + Local**：安装 Ollama，使用 `ollama signin` 登录，并通过该主机路由云请求
- **Cloud only**：使用 `https://ollama.com` 并提供 `OLLAMA_API_KEY`
- **Cloud only**：使用带有 `OLLAMA_API_KEY` 的 `https://ollama.com`
- **Local only**：从 [ollama.com/download](https://ollama.com/download) 安装 Ollama
</Step>
<Step title="拉取本地模型（仅限 Local only）">
<Step title="拉取本地模型（仅限本地）">
```bash
ollama pull gemma4
# 或
@ -91,7 +91,7 @@ OpenClaw 集成了 Ollama 的原生 API（`/api/chat`），可用于托管云模
```
</Step>
<Step title="为 OpenClaw 启用 Ollama">
对于 `Cloud only`，请使用真实的 `OLLAMA_API_KEY`。对于基于主机的设置，任意占位值都可以：
对于 `Cloud only`，请使用你真实的 `OLLAMA_API_KEY`。对于基于主机的设置，任意占位值都可以：
```bash
# 云端
@ -104,7 +104,7 @@ OpenClaw 集成了 Ollama 的原生 API（`/api/chat`），可用于托管云模
openclaw config set models.providers.ollama.apiKey "OLLAMA_API_KEY"
```
</Step>
<Step title="检查并设置你的模型">
<Step title="查看并设置你的模型">
```bash
openclaw models list
openclaw models set ollama/gemma4
@ -133,16 +133,18 @@ OpenClaw 集成了 Ollama 的原生 API（`/api/chat`），可用于托管云模
<Tab title="Cloud + Local">
`Cloud + Local` 使用可访问的 Ollama 主机作为本地模型和云模型的统一控制点。这是 Ollama 推荐的混合流程。
在设置时使用 **Cloud + Local**。OpenClaw 会提示输入 Ollama 基础 URL，从该主机发现本地模型，并检查该主机是否已通过 `ollama signin` 登录以启用云访问。当主机已登录时，OpenClaw 还会推荐托管云模型默认值，例如 `kimi-k2.5:cloud`、`minimax-m2.7:cloud` 和 `glm-5.1:cloud`。
在设置期间使用 **Cloud + Local**。OpenClaw 会提示输入 Ollama base URL，从该主机发现本地模型，并检查该主机是否已通过 `ollama signin` 登录以启用云访问。当主机已登录时，OpenClaw 还会推荐托管云端默认模型，例如 `kimi-k2.5:cloud`、`minimax-m2.7:cloud` 和 `glm-5.1:cloud`。
如果该主机尚未登录，OpenClaw 会将设置保持为仅本地模式，直到你运行 `ollama signin`。
如果主机尚未登录，OpenClaw 会将设置保持为仅本地模式，直到你运行 `ollama signin`。
</Tab>
<Tab title="Cloud only">
`Cloud only` 通过 Ollama 的托管 API `https://ollama.com` 运行。
`Cloud only` 对接 Ollama 的托管 API `https://ollama.com`。
在设置时使用 **Cloud only**。OpenClaw 会提示输入 `OLLAMA_API_KEY`，设置 `baseUrl: "https://ollama.com"`，并初始化托管云模型列表。此路径**不**需要本地 Ollama 服务器或 `ollama signin`。
在设置期间使用 **Cloud only**。OpenClaw 会提示输入 `OLLAMA_API_KEY`，设置 `baseUrl: "https://ollama.com"`，并初始化托管云模型列表。此路径**不**需要本地 Ollama 服务器或 `ollama signin`。
`openclaw onboard` 中显示的云模型列表会从 `https://ollama.com/api/tags` 实时加载，最多 500 项，因此选择器反映的是当前托管模型目录，而不是静态预置列表。如果在设置时 `ollama.com` 无法访问或未返回任何模型，OpenClaw 会回退到之前硬编码的推荐项，以便新手引导仍可完成。
</Tab>
@ -156,21 +158,21 @@ OpenClaw 集成了 Ollama 的原生 API（`/api/chat`），可用于托管云模
## 模型发现（隐式 provider）
当你设置了 `OLLAMA_API_KEY`（或身份验证配置）且**没有**定义 `models.providers.ollama` 时，OpenClaw 会从位于 `http://127.0.0.1:11434` 的本地 Ollama 实例中发现模型。
当你设置 `OLLAMA_API_KEY`（或 auth profile），并且**没有**定义 `models.providers.ollama` 时，OpenClaw 会从 `http://127.0.0.1:11434` 上的本地 Ollama 实例发现模型。
| 行为 | 详细信息 |
| 行为 | 详情 |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 目录查询 | 查询 `/api/tags` |
| 能力检测 | 使用尽力而为的 `/api/show` 查询来读取 `contextWindow` 并检测能力（包括视觉） |
| 视觉模型 | 由 `/api/show` 报告具有 `vision` 能力的模型会被标记为支持图像输入（`input: ["text", "image"]`），因此 OpenClaw 会自动将图片注入到提示中 |
| 能力检测 | 使用尽力而为的 `/api/show` 查询来读取 `contextWindow` 并检测能力（包括 vision） |
| 视觉模型 | 由 `/api/show` 报告具有 `vision` 能力的模型会被标记为支持图像（`input: ["text", "image"]`），因此 OpenClaw 会自动将图像注入提示词 |
| 推理检测 | 使用模型名称启发式规则（`r1`、`reasoning`、`think`）标记 `reasoning` |
| Token 限制 | 将 `maxTokens` 设置为 OpenClaw 使用的默认 Ollama 最大 token 上限 |
| 费用 | 将所有费用设置为 `0` |
| 成本 | 所有成本均设置为 `0` |
这样可以避免手动录入模型，同时让目录与本地 Ollama 实例保持一致。
```bash
# 查看有哪些模型可用
# 查看有哪些可用模型
ollama list
openclaw models list
```
@ -181,10 +183,10 @@ openclaw models list
ollama pull mistral
```
新模型会被自动发现并可立即使用。
新模型会被自动发现并可直接使用。
<Note>
如果你显式设置了 `models.providers.ollama`，则会跳过自动发现，你必须手动定义模型。参见下面的显式配置部分。
如果你显式设置了 `models.providers.ollama`，将跳过自动发现，你必须手动定义模型。请参阅下方的显式配置部分。
</Note>
## 配置
@ -198,13 +200,13 @@ ollama pull mistral
```
<Tip>
如果设置了 `OLLAMA_API_KEY`，你可以在 provider 条目中省略 `apiKey`，OpenClaw 会在可用性检查时自动补齐它。
如果设置了 `OLLAMA_API_KEY`，你可以在 provider 条目中省略 `apiKey`，OpenClaw 会在可用性检查时自动填充它。
</Tip>
</Tab>
<Tab title="显式（手动模型）">
当你想使用托管云端设置、Ollama 运行在其他主机/端口、你想强制指定特定上下文窗口或模型列表，或你希望完全手动定义模型时，请使用显式配置。
当你希望使用托管云设置、Ollama 运行在其他主机/端口、你想强制指定特定上下文窗口或模型列表，或者你想完全手动定义模型时，请使用显式配置。
```json5
{
@ -233,7 +235,7 @@ ollama pull mistral
</Tab>
<Tab title="自定义基础 URL">
<Tab title="自定义 base URL">
如果 Ollama 运行在不同的主机或端口上（显式配置会禁用自动发现，因此你需要手动定义模型）：
```json5
@ -243,7 +245,7 @@ ollama pull mistral
ollama: {
apiKey: "ollama-local",
baseUrl: "http://ollama-host:11434", // 不要加 /v1 - 使用原生 Ollama API URL
api: "ollama", // 显式设置以确保使用原生工具调用行为
api: "ollama", // 显式设置以确保原生工具调用行为
},
},
},
@ -251,7 +253,7 @@ ollama pull mistral
```
<Warning>
不要在 URL 中添加 `/v1`。`/v1` 路径使用 OpenAI 兼容模式，而该模式下工具调用并不可靠。请使用不带路径后缀的 Ollama 基础 URL。
不要在 URL 中添加 `/v1`。`/v1` 路径使用 OpenAI 兼容模式，在该模式下工具调用并不可靠。请使用不带路径后缀的 Ollama 基础 URL。
</Warning>
</Tab>
@ -276,15 +278,15 @@ ollama pull mistral
## Ollama Web 搜索
OpenClaw 支持将 **Ollama Web 搜索** 作为内置的 `web_search` provider 使用。
OpenClaw 支持 **Ollama Web 搜索**，作为内置的 `web_search` provider。
| 属性 | 详细信息 |
| 属性 | 详情 |
| ----------- | ----------------------------------------------------------------------------------------------------------------- |
| 主机 | 使用你配置的 Ollama 主机（设置了 `models.providers.ollama.baseUrl` 时使用该值，否则为 `http://127.0.0.1:11434`） |
| 认证 | 无需密钥 |
| 要求 | Ollama 必须正在运行，并且已通过 `ollama signin` 登录 |
在 `openclaw onboard` 或 `openclaw configure --section web` 中选择 **Ollama Web 搜索**，或设置：
在 `openclaw onboard` 或 `openclaw configure --section web` 中选择 **Ollama Web 搜索**，或者设置：
```json5
{
@ -299,7 +301,7 @@ OpenClaw 支持将 **Ollama Web 搜索** 作为内置的 `web_search` provider
```
<Note>
完整的设置和行为细节，请参见 [Ollama Web 搜索](/zh-CN/tools/ollama-search)。
完整的设置与行为细节，请参阅 [Ollama Web 搜索](/zh-CN/tools/ollama-search)。
</Note>
## 高级配置
@ -307,10 +309,10 @@ OpenClaw 支持将 **Ollama Web 搜索** 作为内置的 `web_search` provider
<AccordionGroup>
<Accordion title="旧版 OpenAI 兼容模式">
<Warning>
**在 OpenAI 兼容模式下，工具调用并不可靠。** 仅当你需要通过代理使用 OpenAI 格式，且不依赖原生工具调用行为时，才应使用此模式。
**在 OpenAI 兼容模式下，工具调用并不可靠。** 仅当你需要为代理使用 OpenAI 格式，并且不依赖原生工具调用行为时，才应使用此模式。
</Warning>
如果你需要改用 OpenAI 兼容端点（例如位于仅支持 OpenAI 格式的代理之后），请显式设置 `api: "openai-completions"`：
如果你确实需要改用 OpenAI 兼容端点（例如位于仅支持 OpenAI 格式的代理之后），请显式设置 `api: "openai-completions"`：
```json5
{
@ -328,9 +330,9 @@ OpenClaw 支持将 **Ollama Web 搜索** 作为内置的 `web_search` provider
}
```
在此模式下，可能无法同时支持流式传输和工具调用。你可能需要在模型配置中使用 `params: { streaming: false }` 来禁用流式传输。
此模式可能无法同时支持流式传输和工具调用。你可能需要在模型配置中使用 `params: { streaming: false }` 来禁用流式传输。
当 Ollama 使用 `api: "openai-completions"` 时，OpenClaw 默认会注入 `options.num_ctx`，以避免 Ollama 静默回退到 4096 的上下文窗口。如果你的代理/上游拒绝未知的 `options` 字段，请禁用此行为：
当在 Ollama 中使用 `api: "openai-completions"` 时，OpenClaw 默认会注入 `options.num_ctx`，这样 Ollama 就不会悄悄回退到 4096 的上下文窗口。如果你的代理/上游会拒绝未知的 `options` 字段，请禁用此行为：
```json5
{
@ -351,7 +353,7 @@ OpenClaw 支持将 **Ollama Web 搜索** 作为内置的 `web_search` provider
</Accordion>
<Accordion title="上下文窗口">
对于自动发现的模型，OpenClaw 会在可用时使用 Ollama 报告的上下文窗口；否则，会回退到 OpenClaw 使用的默认 Ollama 上下文窗口。
对于自动发现的模型，OpenClaw 会在可用时使用 Ollama 报告的上下文窗口，否则会回退到 OpenClaw 使用的默认 Ollama 上下文窗口。
你可以在显式 provider 配置中覆盖 `contextWindow` 和 `maxTokens`：
@ -376,29 +378,29 @@ OpenClaw 支持将 **Ollama Web 搜索** 作为内置的 `web_search` provider
</Accordion>
<Accordion title="推理模型">
OpenClaw 默认会将名称中包含 `deepseek-r1`、`reasoning` 或 `think` 的模型视为支持推理的模型。
OpenClaw 默认将名称中包含 `deepseek-r1`、`reasoning` 或 `think` 的模型视为支持推理的模型。
```bash
ollama pull deepseek-r1:32b
```
无需额外配置——OpenClaw 会自动标记它们。
不需要额外配置——OpenClaw 会自动标记它们。
</Accordion>
<Accordion title="模型费用">
Ollama 可免费使用并在本地运行，因此所有模型费用都设置为 $0。这同时适用于自动发现的模型和手动定义的模型。
<Accordion title="模型成本">
Ollama 是免费的，并且在本地运行，因此所有模型成本都设为 $0。这同时适用于自动发现的模型和手动定义的模型。
</Accordion>
<Accordion title="Memory embeddings">
内置的 Ollama 插件会为 [memory search](/zh-CN/concepts/memory) 注册一个 memory embedding provider。它使用已配置的 Ollama 基础 URL 和 API 密钥。
内置的 Ollama 插件会为 [memory search](/zh-CN/concepts/memory) 注册一个记忆嵌入 provider。它使用已配置的 Ollama base URL 和 API key。
| 属性 | 值 |
| ------------- | ------------------- |
| 默认模型 | `nomic-embed-text` |
| 自动拉取 | 是——如果 embedding 模型在本地不存在，则会自动拉取 |
| 自动拉取 | 是 —— 如果嵌入模型尚未在本地存在，将自动拉取 |
要将 Ollama 选为 memory search 的 embedding provider：
要选择 Ollama 作为 memory search 的嵌入 provider：
```json5
{
@ -413,10 +415,10 @@ OpenClaw 支持将 **Ollama Web 搜索** 作为内置的 `web_search` provider
</Accordion>
<Accordion title="流式传输配置">
OpenClaw 的 Ollama 集成默认使用**原生 Ollama API**（`/api/chat`），可同时完整支持流式传输和工具调用。无需任何特殊配置。
OpenClaw 的 Ollama 集成默认使用**原生 Ollama API**（`/api/chat`），可同时完整支持流式传输和工具调用。不需要任何特殊配置。
<Tip>
如果你需要使用 OpenAI 兼容端点，请参阅上面的“旧版 OpenAI 兼容模式”部分。在该模式下，流式传输和工具调用可能无法同时工作。
如果你需要使用 OpenAI 兼容端点，请参阅上方的“旧版 OpenAI 兼容模式”部分。在该模式下，流式传输和工具调用可能无法同时工作。
</Tip>
</Accordion>
@ -426,13 +428,13 @@ OpenClaw 支持将 **Ollama Web 搜索** 作为内置的 `web_search` provider
<AccordionGroup>
<Accordion title="未检测到 Ollama">
请确保 Ollama 正在运行，并且你已设置 `OLLAMA_API_KEY`（或身份验证配置），同时**没有**定义显式的 `models.providers.ollama` 条目：
请确认 Ollama 正在运行，并且你已经设置了 `OLLAMA_API_KEY`（或 auth profile），同时**没有**定义显式的 `models.providers.ollama` 条目：
```bash
ollama serve
```
验证 API 可访问：
验证 API 是否可访问：
```bash
curl http://localhost:11434/api/tags
@ -441,7 +443,7 @@ OpenClaw 支持将 **Ollama Web 搜索** 作为内置的 `web_search` provider
</Accordion>
<Accordion title="没有可用模型">
如果列表中没有你的模型，请在本地拉取该模型，或在 `models.providers.ollama` 中显式定义它。
如果列表中没有你的模型，请在本地拉取该模型，或者在 `models.providers.ollama` 中显式定义它。
```bash
ollama list # 查看已安装的模型
@ -453,7 +455,7 @@ OpenClaw 支持将 **Ollama Web 搜索** 作为内置的 `web_search` provider
</Accordion>
<Accordion title="连接被拒绝">
检查 Ollama 是否在正确的端口上运行：
检查 Ollama 是否运行在正确的端口上：
```bash
# 检查 Ollama 是否正在运行
@ -473,14 +475,14 @@ OpenClaw 支持将 **Ollama Web 搜索** 作为内置的 `web_search` provider
## 相关内容
<CardGroup cols={2}>
<Card title="模型提供商" href="/zh-CN/concepts/model-providers" icon="layers">
<Card title="模型 provider" href="/zh-CN/concepts/model-providers" icon="layers">
所有提供商、模型引用和故障切换行为的概览。
</Card>
<Card title="模型选择" href="/zh-CN/concepts/models" icon="brain">
如何选择和配置模型。
</Card>
<Card title="Ollama Web 搜索" href="/zh-CN/tools/ollama-search" icon="magnifying-glass">
了解 Ollama 驱动的网页搜索的完整设置和行为细节。
由 Ollama 驱动的 Web 搜索的完整设置与行为细节。
</Card>
<Card title="配置" href="/zh-CN/gateway/configuration" icon="gear">
完整的配置参考。

138
docs/zh-CN/providers/openai.md
View File

@ -1,15 +1,15 @@
---
read_when:
- 你想在 OpenClaw 中使用 OpenAI 模型
- 你希望使用 Codex 订阅认证，而不是 API 密钥
- 你想使用 Codex 订阅认证，而不是 API 密钥
- 你需要更严格的 GPT-5 智能体执行行为
summary: 在 OpenClaw 中使用 API 密钥或 Codex 订阅来使用 OpenAI
summary: 在 OpenClaw 中使用 OpenAI 的 API 密钥或 Codex 订阅
title: OpenAI
x-i18n:
generated_at: "2026-04-21T05:16:43Z"
generated_at: "2026-04-21T20:53:31Z"
model: gpt-5.4
provider: openai
source_hash: 172beb28b099e3d71998458408c9a6b32b03790d2b016351f724bc3f0d9d3245
source_hash: 692615b77885c0387d339d47c02ff056ba95d3608aa681882893a46d2a0f723f
source_path: providers/openai.md
workflow: 15
---
@ -19,7 +19,7 @@ x-i18n:
OpenAI 提供用于 GPT 模型的开发者 API。OpenClaw 支持两种认证方式：
- **API 密钥** — 直接访问 OpenAI Platform，并按使用量计费（`openai/*` 模型）
- **Codex 订阅** — 通过 ChatGPT/Codex 登录并使用订阅权限（`openai-codex/*` 模型）
- **Codex 订阅** — 使用 ChatGPT/Codex 登录并通过订阅访问（`openai-codex/*` 模型）
OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OAuth。
@ -74,13 +74,13 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA
```
<Warning>
OpenClaw **不会** 在直接 API 路径上暴露 `openai/gpt-5.3-codex-spark`。实时 OpenAI API 请求会拒绝该模型。Spark 仅限 Codex。
OpenClaw **不会** 在直连 API 路径上暴露 `openai/gpt-5.3-codex-spark`。实时 OpenAI API 请求会拒绝该模型。Spark 仅限 Codex。
</Warning>
</Tab>
<Tab title="Codex 订阅">
**最适合：** 使用你的 ChatGPT/Codex 订阅，而不是单独的 API 密钥。Codex cloud 需要 ChatGPT 登录。
**最适合：** 使用你的 ChatGPT/Codex 订阅，而不是单独的 API 密钥。Codex cloud 需要使用 ChatGPT 登录。
<Steps>
<Step title="运行 Codex OAuth">
@ -111,10 +111,10 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA
| 模型引用 | 路由 | 认证 |
|-----------|-------|------|
| `openai-codex/gpt-5.4` | ChatGPT/Codex OAuth | Codex 登录 |
| `openai-codex/gpt-5.3-codex-spark` | ChatGPT/Codex OAuth | Codex 登录（取决于权限） |
| `openai-codex/gpt-5.3-codex-spark` | ChatGPT/Codex OAuth | Codex 登录（取决于授权资格） |
<Note>
这一路径与 `openai/gpt-5.4` 是刻意分开的。要直接访问 Platform，请使用带 API 密钥的 `openai/*`；要使用 Codex 订阅访问，请使用 `openai-codex/*`。
这一路由刻意与 `openai/gpt-5.4` 分开。使用 API 密钥配合 `openai/*` 进行直接 Platform 访问，使用 `openai-codex/*` 进行 Codex 订阅访问。
</Note>
### 配置示例
@ -126,7 +126,7 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA
```
<Tip>
如果新手引导复用了现有的 Codex CLI 登录，这些凭证仍由 Codex CLI 管理。凭证过期时，OpenClaw 会先重新读取外部 Codex 来源，再将刷新后的凭证写回 Codex 存储。
如果新手引导复用了现有的 Codex CLI 登录，这些凭证将继续由 Codex CLI 管理。凭证过期后，OpenClaw 会先重新读取外部 Codex 来源，再将刷新后的凭证写回 Codex 存储。
</Tip>
### 上下文窗口上限
@ -138,7 +138,7 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA
- 原生 `contextWindow`：`1050000`
- 默认运行时 `contextTokens` 上限：`272000`
在实际使用中，较小的默认上限通常具有更好的延迟和质量表现。你可以使用 `contextTokens` 覆盖它：
较小的默认上限在实践中具有更好的延迟和质量表现。你可以使用 `contextTokens` 覆盖它：
```json5
{
@ -153,7 +153,7 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA
```
<Note>
使用 `contextWindow` 来声明模型的原生元数据。使用 `contextTokens` 来限制运行时上下文预算。
使用 `contextWindow` 声明模型原生元数据。使用 `contextTokens` 限制运行时上下文预算。
</Note>
</Tab>
@ -163,39 +163,53 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA
内置的 `openai` 插件通过 `image_generate` 工具注册图像生成功能。
| 功能 | 值 |
| 能力 | 值 |
| ------------------------- | ---------------------------------- |
| 默认模型 | `openai/gpt-image-1` |
| 默认模型 | `openai/gpt-image-2` |
| 每次请求的最大图像数 | 4 |
| 编辑模式 | 已启用（最多 5 张参考图像） |
| 尺寸覆盖 | 支持 |
| 宽高比 / 分辨率 | 不会转发到 OpenAI Images API |
| 尺寸覆盖 | 支持，包括 2K/4K 尺寸 |
| 宽高比 / 分辨率 | 不会转发给 OpenAI Images API |
```json5
{
agents: {
defaults: {
imageGenerationModel: { primary: "openai/gpt-image-1" },
imageGenerationModel: { primary: "openai/gpt-image-2" },
},
},
}
```
<Note>
有关共享工具参数、提供商选择和故障转移行为，请参阅 [图像生成](/zh-CN/tools/image-generation)。
有关共享工具参数、提供商选择和故障切换行为，请参阅 [图像生成](/zh-CN/tools/image-generation)。
</Note>
`gpt-image-2` 是 OpenAI 文生图和图像编辑的默认模型。`gpt-image-1` 仍可作为显式模型覆盖使用，但新的 OpenAI 图像工作流应使用 `openai/gpt-image-2`。
生成：
```
/tool image_generate model=openai/gpt-image-2 prompt="A polished launch poster for OpenClaw on macOS" size=3840x2160 count=1
```
编辑：
```
/tool image_generate model=openai/gpt-image-2 prompt="Preserve the object shape, change the material to translucent glass" image=/path/to/reference.png size=1024x1536
```
## 视频生成
内置的 `openai` 插件通过 `video_generate` 工具注册视频生成功能。
| 功能 | 值 |
| 能力 | 值 |
| ---------------- | --------------------------------------------------------------------------------- |
| 默认模型 | `openai/sora-2` |
| 模式 | 文生视频、图生视频、单视频编辑 |
| 参考输入 | 1 张图像或 1 个视频 |
| 尺寸覆盖 | 支持 |
| 其他覆盖项 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略，并附带工具警告 |
| 其他覆盖项 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略，并给出工具警告 |
```json5
{
@ -208,18 +222,18 @@ OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OA
```
<Note>
有关共享工具参数、提供商选择和故障转移行为，请参阅 [视频生成](/zh-CN/tools/video-generation)。
有关共享工具参数、提供商选择和故障切换行为，请参阅 [视频生成](/zh-CN/tools/video-generation)。
</Note>
## GPT-5 提示词贡献
OpenClaw 会为 `openai/*` 和 `openai-codex/*` 的 GPT-5 系列运行添加一个 OpenAI 专用的 GPT-5 提示词贡献。它位于内置的 OpenAI 插件中，适用于 `gpt-5`、`gpt-5.2`、`gpt-5.4` 和 `gpt-5.4-mini` 等模型 id，不适用于较旧的 GPT-4.x 模型。
OpenClaw 会为 `openai/*` 和 `openai-codex/*` 的 GPT-5 系列运行添加 OpenAI 专用的 GPT-5 提示词贡献。它位于内置的 OpenAI 插件中，适用于 `gpt-5`、`gpt-5.2`、`gpt-5.4` 和 `gpt-5.4-mini` 等模型 ID，不适用于较旧的 GPT-4.x 模型。
GPT-5 提示词贡献会添加一个带标签的行为契约，用于约束人格持续性、执行安全、工具纪律、输出形态、完成检查和验证。渠道特定的回复行为和静默消息行为仍保留在共享的 OpenClaw 系统提示词和出站投递策略中。对于匹配的模型，GPT-5 指导始终启用。友好互动风格层是独立的，并且可配置。
GPT-5 贡献为人格持久性、执行安全、工具纪律、输出形态、完成检查和验证增加了带标签的行为契约。特定渠道的回复和静默消息行为仍保留在共享的 OpenClaw 系统提示词和出站投递策略中。对于匹配的模型，GPT-5 指导始终启用。友好的交互风格层是独立且可配置的。
| 值 | 效果 |
| ---------------------- | ------------------------------------------- |
| `"friendly"`（默认） | 启用友好互动风格层 |
| `"friendly"`（默认） | 启用友好的交互风格层 |
| `"on"` | `"friendly"` 的别名 |
| `"off"` | 仅禁用友好风格层 |
@ -246,23 +260,23 @@ GPT-5 提示词贡献会添加一个带标签的行为契约，用于约束人
这些值在运行时不区分大小写，因此 `"Off"` 和 `"off"` 都会禁用友好风格层。
</Tip>
## 语音与语音处理
## 语音和语音合成
<AccordionGroup>
<Accordion title="语音合成（TTS）">
内置的 `openai` 插件为 `messages.tts` 接口注册语音合成功能。
内置的 `openai` 插件为 `messages.tts` 接口注册了语音合成功能。
| 设置 | 配置路径 | 默认值 |
|---------|------------|---------|
| 模型 | `messages.tts.providers.openai.model` | `gpt-4o-mini-tts` |
| 音色 | `messages.tts.providers.openai.voice` | `coral` |
| 声音 | `messages.tts.providers.openai.voice` | `coral` |
| 语速 | `messages.tts.providers.openai.speed` | （未设置） |
| 指令 | `messages.tts.providers.openai.instructions` | （未设置，仅 `gpt-4o-mini-tts`） |
| 格式 | `messages.tts.providers.openai.responseFormat` | 语音便笺使用 `opus`，文件使用 `mp3` |
| 格式 | `messages.tts.providers.openai.responseFormat` | 语音便笺为 `opus`，文件为 `mp3` |
| API 密钥 | `messages.tts.providers.openai.apiKey` | 回退到 `OPENAI_API_KEY` |
| Base URL | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` |
可用模型：`gpt-4o-mini-tts`、`tts-1`、`tts-1-hd`。可用音色：`alloy`、`ash`、`ballad`、`cedar`、`coral`、`echo`、`fable`、`juniper`、`marin`、`onyx`、`nova`、`sage`、`shimmer`、`verse`。
可用模型：`gpt-4o-mini-tts`、`tts-1`、`tts-1-hd`。可用声音：`alloy`、`ash`、`ballad`、`cedar`、`coral`、`echo`、`fable`、`juniper`、`marin`、`onyx`、`nova`、`sage`、`shimmer`、`verse`。
```json5
{
@ -277,13 +291,13 @@ GPT-5 提示词贡献会添加一个带标签的行为契约，用于约束人
```
<Note>
设置 `OPENAI_TTS_BASE_URL` 可覆盖 TTS 的 Base URL，而不会影响聊天 API 端点。
设置 `OPENAI_TTS_BASE_URL` 可覆盖 TTS Base URL，而不会影响聊天 API 端点。
</Note>
</Accordion>
<Accordion title="实时转录">
内置的 `openai` 插件为 Voice Call 插件注册实时转录功能。
内置的 `openai` 插件为 Voice Call 插件注册了实时转录功能。
| 设置 | 配置路径 | 默认值 |
|---------|------------|---------|
@ -293,18 +307,18 @@ GPT-5 提示词贡献会添加一个带标签的行为契约，用于约束人
| API 密钥 | `...openai.apiKey` | 回退到 `OPENAI_API_KEY` |
<Note>
使用到 `wss://api.openai.com/v1/realtime` 的 WebSocket 连接，并采用 G.711 u-law 音频。
使用 WebSocket 连接到 `wss://api.openai.com/v1/realtime`，并采用 G.711 u-law 音频。
</Note>
</Accordion>
<Accordion title="实时语音">
内置的 `openai` 插件为 Voice Call 插件注册实时语音功能。
内置的 `openai` 插件为 Voice Call 插件注册了实时语音功能。
| 设置 | 配置路径 | 默认值 |
|---------|------------|---------|
| 模型 | `plugins.entries.voice-call.config.realtime.providers.openai.model` | `gpt-realtime` |
| 音色 | `...openai.voice` | `alloy` |
| 声音 | `...openai.voice` | `alloy` |
| 温度 | `...openai.temperature` | `0.8` |
| VAD 阈值 | `...openai.vadThreshold` | `0.5` |
| 静音时长 | `...openai.silenceDurationMs` | `500` |
@ -320,20 +334,20 @@ GPT-5 提示词贡献会添加一个带标签的行为契约，用于约束人
## 高级配置
<AccordionGroup>
<Accordion title="传输方式（WebSocket 与 SSE）">
对于 `openai/*` 和 `openai-codex/*`，OpenClaw 都默认使用 WebSocket 优先并在失败时回退到 SSE（`"auto"`）。
<Accordion title="传输协议（WebSocket 与 SSE）">
对于 `openai/*` 和 `openai-codex/*`，OpenClaw 都采用 WebSocket 优先，并在失败时回退到 SSE（`"auto"`）。
在 `"auto"` 模式下，OpenClaw 会：
- 在回退到 SSE 之前，对一次早期 WebSocket 失败进行重试
- 发生失败后，将 WebSocket 标记为降级约 60 秒，并在冷却期间使用 SSE
- 为重试和重连附加稳定的会话与轮次标识头
- 在回退到 SSE 之前重试一次早期 WebSocket 失败
- 失败后，将 WebSocket 标记为降级约 60 秒，并在冷却期间使用 SSE
- 为重试和重连附加稳定的会话和轮次身份标头
- 在不同传输变体之间规范化使用量计数器（`input_tokens` / `prompt_tokens`）
| 值 | 行为 |
|-------|----------|
| `"auto"`（默认） | WebSocket 优先，失败回退到 SSE |
| `"sse"` | 强制仅使用 SSE |
| `"websocket"` | 强制仅使用 WebSocket |
| `"auto"`（默认） | WebSocket 优先，SSE 回退 |
| `"sse"` | 仅强制使用 SSE |
| `"websocket"` | 仅强制使用 WebSocket |
```json5
{
@ -356,7 +370,7 @@ GPT-5 提示词贡献会添加一个带标签的行为契约，用于约束人
</Accordion>
<Accordion title="WebSocket 预热">
OpenClaw 默认对 `openai/*` 启用 WebSocket 预热，以降低首轮延迟。
OpenClaw 默认对 `openai/*` 启用 WebSocket 预热，以减少首轮延迟。
```json5
// 禁用预热
@ -397,13 +411,13 @@ GPT-5 提示词贡献会添加一个带标签的行为契约，用于约束人
```
<Note>
会话级覆盖优先于配置。在 Sessions UI 中清除会话覆盖后，该会话会恢复为配置的默认值。
会话覆盖优先于配置。在 Sessions UI 中清除会话覆盖后，会话将返回到已配置的默认值。
</Note>
</Accordion>
<Accordion title="优先处理（service_tier）">
OpenAI 的 API 通过 `service_tier` 提供优先处理能力。你可以在 OpenClaw 中按模型进行设置：
OpenAI 的 API 通过 `service_tier` 提供优先处理。你可以在 OpenClaw 中按模型设置它：
```json5
{
@ -421,21 +435,21 @@ GPT-5 提示词贡献会添加一个带标签的行为契约，用于约束人
支持的值：`auto`、`default`、`flex`、`priority`。
<Warning>
`serviceTier` 仅会转发到原生 OpenAI 端点（`api.openai.com`）和原生 Codex 端点（`chatgpt.com/backend-api`）。如果你通过代理路由任一提供商，OpenClaw 将保持 `service_tier` 不变。
`serviceTier` 仅会转发到原生 OpenAI 端点（`api.openai.com`）和原生 Codex 端点（`chatgpt.com/backend-api`）。如果你通过代理路由任一提供商，OpenClaw 会保持 `service_tier` 不变。
</Warning>
</Accordion>
<Accordion title="服务端压缩（Responses API）">
对于直接 OpenAI Responses 模型（`api.openai.com` 上的 `openai/*`），OpenClaw 会自动启用服务端压缩：
对于直连 OpenAI Responses 模型（`api.openai.com` 上的 `openai/*`），OpenClaw 会自动启用服务端压缩：
- 强制设置 `store: true`（除非模型兼容性设置了 `supportsStore: false`）
- 强制 `store: true`（除非模型兼容性设置了 `supportsStore: false`）
- 注入 `context_management: [{ type: "compaction", compact_threshold: ... }]`
- 默认 `compact_threshold`：`contextWindow` 的 70%（不可用时为 `80000`）
<Tabs>
<Tab title="显式启用">
适用于 Azure OpenAI Responses 等兼容端点：
适用于 Azure OpenAI Responses 这类兼容端点：
```json5
{
@ -487,7 +501,7 @@ GPT-5 提示词贡献会添加一个带标签的行为契约，用于约束人
</Tabs>
<Note>
`responsesServerCompaction` 仅控制 `context_management` 的注入。直接 OpenAI Responses 模型仍会强制设置 `store: true`，除非兼容性设置了 `supportsStore: false`。
`responsesServerCompaction` 仅控制 `context_management` 注入。直连 OpenAI Responses 模型仍会强制 `store: true`，除非兼容性设置了 `supportsStore: false`。
</Note>
</Accordion>
@ -507,31 +521,31 @@ GPT-5 提示词贡献会添加一个带标签的行为契约，用于约束人
使用 `strict-agentic` 时，OpenClaw 会：
- 当工具操作可用时，不再将仅规划的轮次视为成功进展
- 使用“立即执行”的引导重试该轮次
- 对于实质性工作自动启用 `update_plan`
- 如果模型持续规划而不执行，则显式呈现阻塞状态
- 使用“立即行动”的引导重试该轮次
- 对于较大工作自动启用 `update_plan`
- 如果模型持续只做规划而不行动，则显式显示阻塞状态
<Note>
仅适用于 OpenAI 和 Codex 的 GPT-5 系列运行。其他提供商和较旧的模型家族仍保持默认行为。
仅适用于 OpenAI 和 Codex 的 GPT-5 系列运行。其他提供商和较旧模型系列保持默认行为。
</Note>
</Accordion>
<Accordion title="原生路由与 OpenAI 兼容路由">
OpenClaw 会以不同方式处理直接 OpenAI、Codex 和 Azure OpenAI 端点，与通用的 OpenAI 兼容 `/v1` 代理不同：
OpenClaw 会以不同方式处理直连 OpenAI、Codex 和 Azure OpenAI 端点，以及通用的 OpenAI 兼容 `/v1` 代理：
**原生路由**（`openai/*`、`openai-codex/*`、Azure OpenAI）：
- 仅对支持 OpenAI `none` effort 的模型保留 `reasoning: { effort: "none" }`
- 对于拒绝 `reasoning.effort: "none"` 的模型或代理，省略已禁用的 reasoning
- 对拒绝 `reasoning.effort: "none"` 的模型或代理省略禁用的 reasoning
- 默认将工具 schema 设为严格模式
- 仅在已验证的原生主机上附加隐藏归因头
- 保留 OpenAI 专用的请求塑形（`service_tier`、`store`、reasoning 兼容性、提示词缓存提示）
- 仅在已验证的原生主机上附加隐藏归属标头
- 保留 OpenAI 专用的请求整形（`service_tier`、`store`、reasoning 兼容性、提示词缓存提示）
**代理 / 兼容路由：**
- 使用更宽松的兼容行为
- 不会强制严格工具 schema 或原生专用头
- 使用更宽松的兼容性行为
- 不强制严格工具 schema 或仅限原生的标头
Azure OpenAI 使用原生传输和兼容行为，但不会接收隐藏归因头。
Azure OpenAI 使用原生传输和兼容性行为，但不会接收隐藏归属标头。
</Accordion>
</AccordionGroup>
@ -540,7 +554,7 @@ GPT-5 提示词贡献会添加一个带标签的行为契约，用于约束人
<CardGroup cols={2}>
<Card title="模型选择" href="/zh-CN/concepts/model-providers" icon="layers">
选择提供商、模型引用和故障转移行为。
选择提供商、模型引用和故障切换行为。
</Card>
<Card title="图像生成" href="/zh-CN/tools/image-generation" icon="image">
共享图像工具参数和提供商选择。

124
docs/zh-CN/tools/image-generation.md
View File

@ -6,20 +6,20 @@ read_when:
summary: 使用已配置的提供商（OpenAI、Google Gemini、fal、MiniMax、ComfyUI、Vydra）生成和编辑图像
title: 图像生成
x-i18n:
generated_at: "2026-04-06T22:52:16Z"
generated_at: "2026-04-21T20:53:27Z"
model: gpt-5.4
provider: openai
source_hash: 8f7303c199d46e63e88f5f9567478a1025631afb03cb35f44344c12370365e57
source_hash: e365cd23f4f8d8c9ce88d57e65f06ac5ae5285b8b7f9ea37f0b08ab5f6ff7235
source_path: tools/image-generation.md
workflow: 15
---
# 图像生成
`image_generate` 工具让智能体能够使用你已配置的提供商创建和编辑图像。生成的图像会自动作为媒体附件随智能体的回复一并发送。
`image_generate` 工具允许智能体使用你已配置的提供商来创建和编辑图像。生成的图像会作为媒体附件自动随智能体的回复一并发送。
<Note>
只有在至少有一个图像生成提供商可用时，此工具才会显示。如果你在智能体的工具中看不到 `image_generate`，请配置 `agents.defaults.imageGenerationModel` 或设置提供商 API 密钥。
只有在至少有一个图像生成提供商可用时，该工具才会显示。如果你在智能体的工具中看不到 `image_generate`，请配置 `agents.defaults.imageGenerationModel` 或设置提供商 API 密钥。
</Note>
## 快速开始
@ -32,7 +32,7 @@ x-i18n:
agents: {
defaults: {
imageGenerationModel: {
primary: "openai/gpt-image-1",
primary: "openai/gpt-image-2",
},
},
},
@ -41,20 +41,20 @@ x-i18n:
3. 向智能体提问：_“生成一张友好的龙虾吉祥物图像。”_
智能体会自动调用 `image_generate`。无需将工具加入允许列表——当有可用提供商时，它默认启用。
智能体会自动调用 `image_generate`。无需允许工具白名单 —— 只要有可用提供商，它默认就会启用。
## 支持的提供商
| 提供商 | 默认模型 | 编辑支持 | API 密钥 |
| ------ | -------------------------------- | ---------------------------------- | ------------------------------------------------------ |
| OpenAI | `gpt-image-1` | 是（最多 5 张图像） | `OPENAI_API_KEY` |
| Google | `gemini-3.1-flash-image-preview` | 是 | `GEMINI_API_KEY` 或 `GOOGLE_API_KEY` |
| fal | `fal-ai/flux/dev` | 是 | `FAL_KEY` |
| 提供商 | 默认模型 | 编辑支持 | API 密钥 |
| ------ | -------------------------------- | ---------------------------------- | ------------------------------------------------------- |
| OpenAI | `gpt-image-2` | 是（最多 5 张图像） | `OPENAI_API_KEY` |
| Google | `gemini-3.1-flash-image-preview` | 是 | `GEMINI_API_KEY` 或 `GOOGLE_API_KEY` |
| fal | `fal-ai/flux/dev` | 是 | `FAL_KEY` |
| MiniMax | `image-01` | 是（主体参考） | `MINIMAX_API_KEY` 或 MiniMax OAuth（`minimax-portal`） |
| ComfyUI | `workflow` | 是（1 张图像，由工作流配置） | 云端使用 `COMFY_API_KEY` 或 `COMFY_CLOUD_API_KEY` |
| Vydra | `grok-imagine` | 否 | `VYDRA_API_KEY` |
| Vydra | `grok-imagine` | 否 | `VYDRA_API_KEY` |
使用 `action: "list"` 可在运行时查看可用的提供商和模型：
使用 `action: "list"` 可在运行时查看可用提供商和模型：
```
/tool image_generate action=list
@ -62,22 +62,22 @@ x-i18n:
## 工具参数
| 参数 | 类型 | 描述 |
| ------------- | -------- | ----------------------------------------------------------------------------------- |
| `prompt` | string | 图像生成提示词（`action: "generate"` 时必填） |
| `action` | string | `"generate"`（默认）或 `"list"`，用于查看提供商 |
| `model` | string | 提供商/模型覆盖，例如 `openai/gpt-image-1` |
| `image` | string | 编辑模式下的单个参考图像路径或 URL |
| `images` | string[] | 编辑模式下的多个参考图像（最多 5 张） |
| `size` | string | 尺寸提示：`1024x1024`、`1536x1024`、`1024x1536`、`1024x1792`、`1792x1024` |
| `aspectRatio` | string | 宽高比：`1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9`、`21:9` |
| `resolution` | string | 分辨率提示：`1K`、`2K` 或 `4K` |
| `count` | number | 要生成的图像数量（1–4） |
| `filename` | string | 输出文件名提示 |
| 参数 | 类型 | 说明 |
| ------------- | -------- | ------------------------------------------------------------------------------------- |
| `prompt` | string | 图像生成提示词（`action: "generate"` 时必填） |
| `action` | string | `"generate"`（默认）或 `"list"`，用于查看提供商 |
| `model` | string | 提供商/模型覆盖，例如 `openai/gpt-image-2` |
| `image` | string | 编辑模式下的单个参考图像路径或 URL |
| `images` | string[] | 编辑模式下的多个参考图像（最多 5 张） |
| `size` | string | 尺寸提示：`1024x1024`、`1536x1024`、`1024x1536`、`2048x2048`、`3840x2160` |
| `aspectRatio` | string | 宽高比：`1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9`、`21:9` |
| `resolution` | string | 分辨率提示：`1K`、`2K` 或 `4K` |
| `count` | number | 要生成的图像数量（1–4） |
| `filename` | string | 输出文件名提示 |
并非所有提供商都支持全部参数。当回退提供商支持的是接近的几何选项而不是精确请求的选项时，OpenClaw 会在提交前重新映射到最接近的受支持尺寸、宽高比或分辨率。确实不受支持的覆盖项仍会在工具结果中报告。
并非所有提供商都支持所有参数。当回退提供商支持接近的几何选项但不支持你精确请求的值时，OpenClaw 会在提交前重映射为最接近的受支持尺寸、宽高比或分辨率。真正不受支持的覆盖项仍会在工具结果中报告。
工具结果会报告实际应用的设置。当 OpenClaw 在提供商回退期间重新映射几何参数时，返回的 `size`、`aspectRatio` 和 `resolution` 值会反映实际发送的内容，而 `details.normalization` 会记录从请求值到应用值的转换。
工具结果会报告实际应用的设置。当 OpenClaw 在提供商回退期间重映射几何参数时，返回的 `size`、`aspectRatio` 和 `resolution` 值会反映实际发送的内容，而 `details.normalization` 会记录从请求值到应用值的转换。
## 配置
@ -88,7 +88,7 @@ x-i18n:
agents: {
defaults: {
imageGenerationModel: {
primary: "openai/gpt-image-1",
primary: "openai/gpt-image-2",
fallbacks: ["google/gemini-3.1-flash-image-preview", "fal/fal-ai/flux/dev"],
},
},
@ -103,55 +103,81 @@ x-i18n:
1. 工具调用中的 **`model` 参数**（如果智能体指定了）
2. 配置中的 **`imageGenerationModel.primary`**
3. 按顺序使用 **`imageGenerationModel.fallbacks`**
4. **自动检测** —— 仅使用基于认证的提供商默认值：
4. **自动检测** —— 仅使用有凭证支持的提供商默认值：
- 先使用当前默认提供商
- 然后按提供商 ID 顺序使用其余已注册的图像生成提供商
- 再按提供商 ID 顺序使用其余已注册的图像生成提供商
如果某个提供商失败（认证错误、速率限制等），系统会自动尝试下一个候选项。如果全部失败，错误中会包含每次尝试的详细信息。
如果某个提供商失败（凭证错误、速率限制等），会自动尝试下一个候选项。如果全部失败，错误信息会包含每次尝试的详细信息。
说明：
- 自动检测会感知认证状态。只有当 OpenClaw 实际能够验证该提供商时，
该提供商默认值才会进入候选列表。
- 自动检测默认启用。如果你希望图像生成仅使用显式的 `model`、`primary` 和 `fallbacks`
条目，请设置
`agents.defaults.mediaGenerationAutoProviderFallback: false`。
- 使用 `action: "list"` 可查看当前已注册的提供商、它们的
默认模型以及认证环境变量提示。
- 自动检测会感知认证状态。只有当 OpenClaw 实际能够认证该提供商时，该提供商默认值才会进入候选列表。
- 自动检测默认启用。如果你希望图像生成只使用显式的 `model`、`primary` 和 `fallbacks` 条目，请设置 `agents.defaults.mediaGenerationAutoProviderFallback: false`。
- 使用 `action: "list"` 可查看当前已注册的提供商、它们的默认模型以及认证环境变量提示。
### 图像编辑
OpenAI、Google、fal、MiniMax 和 ComfyUI 支持编辑参考图像。传入参考图像路径或 URL：
```
"把这张照片生成为水彩风格版本" + image: "/path/to/photo.jpg"
"Generate a watercolor version of this photo" + image: "/path/to/photo.jpg"
```
OpenAI 和 Google 通过 `images` 参数最多支持 5 张参考图像。fal、MiniMax 和 ComfyUI 支持 1 张。
MiniMax 图像生成可通过两种内置的 MiniMax 认证路径使用：
### OpenAI `gpt-image-2`
OpenAI 图像生成默认使用 `openai/gpt-image-2`。较旧的 `openai/gpt-image-1` 模型仍可显式选择，但新的 OpenAI 图像生成和图像编辑请求应使用 `gpt-image-2`。
`gpt-image-2` 同时支持文生图生成和参考图像编辑，均通过同一个 `image_generate` 工具完成。OpenClaw 会将 `prompt`、`count`、`size` 和参考图像转发给 OpenAI。OpenAI 不会直接接收 `aspectRatio` 或 `resolution`；在可能的情况下，OpenClaw 会将它们映射为受支持的 `size`，否则工具会将其报告为被忽略的覆盖项。
生成一张 4K 横版图像：
```
/tool image_generate action=generate model=openai/gpt-image-2 prompt="A clean editorial poster for OpenClaw image generation" size=3840x2160 count=1
```
生成两张方形图像：
```
/tool image_generate action=generate model=openai/gpt-image-2 prompt="Two visual directions for a calm productivity app icon" size=1024x1024 count=2
```
编辑一张本地参考图像：
```
/tool image_generate action=generate model=openai/gpt-image-2 prompt="Keep the subject, replace the background with a bright studio setup" image=/path/to/reference.png size=1024x1536
```
使用多张参考图像进行编辑：
```
/tool image_generate action=generate model=openai/gpt-image-2 prompt="Combine the character identity from the first image with the color palette from the second" images='["/path/to/character.png","/path/to/palette.jpg"]' size=1536x1024
```
MiniMax 图像生成功能可通过两种内置的 MiniMax 认证路径使用：
- `minimax/image-01`，用于 API 密钥配置
- `minimax-portal/image-01`，用于 OAuth 配置
## 提供商能力
| 能力 | OpenAI | Google | fal | MiniMax | ComfyUI | Vydra |
| --------------------- | -------------------- | -------------------- | ------------------- | -------------------------- | ---------------------------------- | ------- |
| 生成 | 是（最多 4 张） | 是（最多 4 张） | 是（最多 4 张） | 是（最多 9 张） | 是（输出由工作流定义） | 是（1 张） |
| 编辑/参考 | 是（最多 5 张图像） | 是（最多 5 张图像） | 是（1 张图像） | 是（1 张图像，主体参考） | 是（1 张图像，由工作流配置） | 否 |
| 尺寸控制 | 是 | 是 | 是 | 否 | 否 | 否 |
| 宽高比 | 否 | 是 | 是（仅生成） | 是 | 否 | 否 |
| 分辨率（1K/2K/4K） | 否 | 是 | 是 | 否 | 否 | 否 |
| 能力 | OpenAI | Google | fal | MiniMax | ComfyUI | Vydra |
| --------------------- | --------------- | ------------------- | ------------- | -------------------- | --------------------------- | ------- |
| 生成 | 是（最多 4 张） | 是（最多 4 张） | 是（最多 4 张） | 是（最多 9 张） | 是（由工作流定义输出） | 是（1 张） |
| 编辑/参考图 | 是（最多 5 张） | 是（最多 5 张） | 是（1 张） | 是（1 张，主体参考） | 是（1 张，由工作流配置） | 否 |
| 尺寸控制 | 是（最高 4K） | 是 | 是 | 否 | 否 | 否 |
| 宽高比 | 否 | 是 | 是（仅生成） | 是 | 否 | 否 |
| 分辨率（1K/2K/4K） | 否 | 是 | 是 | 否 | 否 | 否 |
## 相关内容
- [工具概览](/zh-CN/tools) — 所有可用的智能体工具
- [fal](/zh-CN/providers/fal) — fal 图像和视频提供商设置
- [ComfyUI](/zh-CN/providers/comfy) — 本地 ComfyUI 和 Comfy Cloud 工作流设置
- [Google (Gemini)](/zh-CN/providers/google) — Gemini 图像提供商设置
- [Google（Gemini）](/zh-CN/providers/google) — Gemini 图像提供商设置
- [MiniMax](/zh-CN/providers/minimax) — MiniMax 图像提供商设置
- [OpenAI](/zh-CN/providers/openai) — OpenAI Images 提供商设置
- [Vydra](/zh-CN/providers/vydra) — Vydra 图像、视频和语音设置
- [配置参考](/zh-CN/gateway/configuration-reference#agent-defaults) — `imageGenerationModel` 配置
- [模型](/zh-CN/concepts/models) — 模型配置和故障转移
- [模型](/zh-CN/concepts/models) — 模型配置与故障转移