From 3461d55d4db18d276016fd02cc7d2396f44b8335 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sun, 5 Apr 2026 22:24:32 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/concepts/model-providers.md | 421 +++++++++++++---------- docs/zh-CN/providers/alibaba.md | 78 +++++ docs/zh-CN/providers/fal.md | 97 ++++++ docs/zh-CN/providers/google.md | 65 +++- docs/zh-CN/providers/index.md | 96 +++--- docs/zh-CN/providers/minimax.md | 179 ++++++---- docs/zh-CN/providers/openai.md | 255 ++++++++------ docs/zh-CN/providers/qwen.md | 85 ++--- docs/zh-CN/providers/qwen_modelstudio.md | 115 +++++-- docs/zh-CN/providers/together.md | 66 ++-- docs/zh-CN/providers/xai.md | 81 +++-- docs/zh-CN/tools/image-generation.md | 100 +++--- docs/zh-CN/tools/video-generation.md | 101 +++--- 13 files changed, 1110 insertions(+), 629 deletions(-) create mode 100644 docs/zh-CN/providers/alibaba.md create mode 100644 docs/zh-CN/providers/fal.md diff --git a/docs/zh-CN/concepts/model-providers.md b/docs/zh-CN/concepts/model-providers.md index a740d4912..1f46c28fd 100644 --- a/docs/zh-CN/concepts/model-providers.md +++ b/docs/zh-CN/concepts/model-providers.md @@ -1,142 +1,168 @@ --- read_when: - - 你需要按提供商区分的模型设置参考 + - 你需要按提供商分类的模型设置参考 - 你想查看模型提供商的示例配置或 CLI 新手引导命令 summary: 模型提供商概览，包含示例配置和 CLI 流程 title: 模型提供商 x-i18n: - generated_at: "2026-04-05T18:14:49Z" + generated_at: "2026-04-05T22:24:32Z" model: gpt-5.4 provider: openai - source_hash: 24e6275b0bf137fa8143baa2a1d729439ecec6a0d7c0c14fed78c522f691476f + source_hash: 2d1abbc3c1937637e25d77123b770e56e64d674db5b8521967af1143e59c83ab 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`）。 -- 如果你设置了 `agents.defaults.models`，它就会成为允许列表。 +- 如果你设置了 `agents.defaults.models`，它就会成为 allowlist。 - CLI 助手：`openclaw onboard`、`openclaw models list`、`openclaw models set `。 - 回退运行时规则、冷却探测和会话覆盖持久化记录在 [/concepts/model-failover](/zh-CN/concepts/model-failover) 中。 -- `models.providers.*.models[].contextWindow` 是原生模型元数据；`models.providers.*.models[].contextTokens` 是生效的运行时上限。 +- `models.providers.*.models[].contextWindow` 是原生模型元数据；`models.providers.*.models[].contextTokens` 是运行时实际生效的上限。 - 提供商插件可以通过 `registerProvider({ catalog })` 注入模型目录；OpenClaw 会在写入 `models.json` 之前将该输出合并到 `models.providers` 中。 -- 提供商清单可以声明 `providerAuthEnvVars`，这样基于通用环境变量的认证探测就不需要加载插件运行时。剩余的核心环境变量映射现在仅用于非插件/核心提供商，以及少数通用优先级场景，例如 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`、`isBinaryThinking`、`supportsXHighThinking`、`resolveDefaultThinkingLevel`、`applyConfigDefaults`、`isModernModelRef`、`prepareRuntimeAuth`、`resolveUsageAuth`、`fetchUsageSnapshot` 以及 `onModelSelected` 来接管提供商运行时行为。 -- 注意：提供商运行时 `capabilities` 是共享的运行器元数据（提供商家族、转录/工具差异、传输/缓存提示）。它与[公共能力模型](/zh-CN/plugins/architecture#public-capability-model)不同，后者描述的是插件注册了什么内容（文本推理、语音等）。 +- 提供商清单可以声明 `providerAuthEnvVars`，这样基于通用环境变量的身份验证探测就不需要加载插件运行时。剩余的核心环境变量映射现在只用于非插件/核心提供商，以及少数通用优先级场景，例如 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`、`isBinaryThinking`、`supportsXHighThinking`、 + `resolveDefaultThinkingLevel`、`applyConfigDefaults`、`isModernModelRef`、 + `prepareRuntimeAuth`、`resolveUsageAuth`、`fetchUsageSnapshot`，以及 + `onModelSelected`。 +- 注意：提供商运行时的 `capabilities` 是共享 runner 元数据（提供商家族、转录/工具特性差异、传输/缓存提示）。它不同于[公开能力模型](/zh-CN/plugins/architecture#public-capability-model)，后者描述的是插件注册了什么能力（文本推理、语音等）。 -## 插件自有的提供商行为 +## 提供商自主管理的行为 -现在，提供商插件可以接管大多数提供商特定逻辑，而 OpenClaw 保留通用推理循环。 +现在，提供商插件可以拥有大多数提供商特定逻辑，而 OpenClaw 继续保留通用推理循环。 典型划分如下： - `auth[].run` / `auth[].runNonInteractive`：提供商负责 `openclaw onboard`、`openclaw models auth` 和无头设置的 onboarding/登录流程 -- `wizard.setup` / `wizard.modelPicker`：提供商负责认证选项标签、旧别名、onboarding 允许列表提示，以及 onboarding/模型选择器中的设置项 -- `catalog`：提供商会出现在 `models.providers` 中 -- `normalizeModelId`：提供商会在查找或规范化之前规范旧版/预览模型 ID -- `normalizeTransport`：提供商会在通用模型组装之前规范传输族的 `api` / `baseUrl`；OpenClaw 会先检查匹配的提供商，再检查其他支持此 Hook 的提供商插件，直到某个插件实际更改了传输 -- `normalizeConfig`：提供商会在运行时使用前规范 `models.providers.` 配置；OpenClaw 会先检查匹配的提供商，再检查其他支持此 Hook 的提供商插件，直到某个插件实际更改了配置。如果没有提供商 Hook 重写配置，内置的 Google 系列助手仍会规范受支持的 Google 提供商条目。 -- `applyNativeStreamingUsageCompat`：提供商会对配置提供商应用由端点驱动的原生流式用量兼容重写 -- `resolveConfigApiKey`：提供商会为配置提供商解析环境变量标记认证，而无需强制加载完整运行时认证。`amazon-bedrock` 在这里还内置了 AWS 环境变量标记解析器，尽管 Bedrock 运行时认证使用的是 AWS SDK 默认链。 -- `resolveSyntheticAuth`：提供商可以暴露本地/自托管或其他基于配置的可用认证，而无需持久化明文密钥 -- `shouldDeferSyntheticProfileAuth`：提供商可以将已存储的合成配置档占位符标记为优先级低于环境变量/配置支持的认证 -- `resolveDynamicModel`：提供商可以接受尚未出现在本地静态目录中的模型 ID +- `wizard.setup` / `wizard.modelPicker`：提供商负责身份验证选择标签、旧别名、新手引导 allowlist 提示，以及 onboarding/模型选择器中的设置项 +- `catalog`：提供商显示在 `models.providers` 中 +- `normalizeModelId`：提供商在查找或规范化之前标准化旧版/预览模型 id +- `normalizeTransport`：提供商在通用模型组装前标准化传输家族的 `api` / `baseUrl`；OpenClaw 会先检查匹配的提供商，然后再检查其他具备该 hook 能力的提供商插件，直到某个插件实际修改了传输 +- `normalizeConfig`：提供商在运行时使用前标准化 `models.providers.` 配置；OpenClaw 会先检查匹配的提供商，然后再检查其他具备该 hook 能力的提供商插件，直到某个插件实际修改了配置。如果没有任何提供商 hook 重写该配置，内置的 Google 家族助手仍会标准化受支持的 Google 提供商条目。 +- `applyNativeStreamingUsageCompat`：提供商为配置型提供商应用由端点驱动的原生流式用量兼容性重写 +- `resolveConfigApiKey`：提供商为配置型提供商解析基于环境变量标记的身份验证，而无需强制加载完整运行时身份验证。`amazon-bedrock` 还在这里内置了 AWS 环境变量标记解析器，尽管 Bedrock 运行时身份验证使用的是 AWS SDK 默认链。 +- `resolveSyntheticAuth`：提供商可以暴露本地/自托管或其他基于配置的身份验证可用性，而无需持久化明文密钥 +- `shouldDeferSyntheticProfileAuth`：提供商可以将已存储的 synthetic 配置档占位符标记为低于环境变量/配置支持的身份验证优先级 +- `resolveDynamicModel`：提供商接受本地静态目录中尚不存在的模型 id - `prepareDynamicModel`：提供商在重试动态解析前需要刷新元数据 -- `normalizeResolvedModel`：提供商需要进行传输或基础 URL 重写 -- `contributeResolvedModelCompat`：即使供应商模型是通过另一种兼容传输到达的，提供商也能为其贡献兼容标志 -- `capabilities`：提供商发布转录/工具/提供商家族差异信息 -- `normalizeToolSchemas`：提供商会在嵌入式运行器看到工具模式前对其进行清理 -- `inspectToolSchemas`：提供商会在规范化后暴露特定于传输的模式警告 -- `resolveReasoningOutputMode`：提供商选择原生或带标签的推理输出契约 -- `prepareExtraParams`：提供商为每个模型的请求参数设置默认值或进行规范化 -- `createStreamFn`：提供商使用完全自定义的传输替换常规流路径 +- `normalizeResolvedModel`：提供商需要重写传输或基础 URL +- `contributeResolvedModelCompat`：即使其厂商模型通过另一个兼容传输到达，提供商也可以为其贡献兼容标志 +- `capabilities`：提供商发布转录/工具/提供商家族特性差异 +- `normalizeToolSchemas`：提供商在嵌入式 runner 看到工具 schema 之前先进行清理 +- `inspectToolSchemas`：提供商在标准化之后暴露传输特定的 schema 警告 +- `resolveReasoningOutputMode`：提供商选择原生或带标签的 reasoning 输出契约 +- `prepareExtraParams`：提供商为每个模型默认设置或标准化请求参数 +- `createStreamFn`：提供商用完全自定义的传输替换常规流路径 - `wrapStreamFn`：提供商应用请求头/请求体/模型兼容包装器 -- `resolveTransportTurnState`：提供商为每一轮提供原生传输请求头或元数据 +- `resolveTransportTurnState`：提供商提供每轮的原生传输请求头或元数据 - `resolveWebSocketSessionPolicy`：提供商提供原生 WebSocket 会话请求头或会话冷却策略 -- `createEmbeddingProvider`：当内存嵌入行为更适合归属提供商插件而不是核心嵌入分发器时，由提供商接管 -- `formatApiKey`：提供商将已存储的认证配置档格式化为传输所期望的运行时 `apiKey` 字符串 -- `refreshOAuth`：当共享的 `pi-ai` 刷新器不足时，由提供商负责 OAuth 刷新 -- `buildAuthDoctorHint`：当 OAuth 刷新失败时，由提供商追加修复指导 -- `matchesContextOverflowError`：提供商识别通用启发式规则遗漏的、特定于提供商的上下文窗口溢出错误 -- `classifyFailoverReason`：提供商将特定于提供商的原始传输/API 错误映射为回退原因，例如速率限制或过载 -- `isCacheTtlEligible`：提供商决定哪些上游模型 ID 支持提示缓存 TTL -- `buildMissingAuthMessage`：提供商用特定于提供商的恢复提示替换通用认证存储错误 -- `suppressBuiltInModel`：提供商隐藏过时的上游条目，并且可以在直接解析失败时返回供应商自有错误 -- `augmentModelCatalog`：提供商在发现和配置合并之后追加合成/最终目录条目 -- `isBinaryThinking`：提供商接管二元开/关 thinking 体验 -- `supportsXHighThinking`：提供商让选定模型启用 `xhigh` +- `createEmbeddingProvider`：当内存 embedding 行为更适合放在提供商插件中而不是核心 embedding 切换板中时，由提供商接管 +- `formatApiKey`：提供商将已存储的身份验证配置档格式化为传输所期望的运行时 `apiKey` 字符串 +- `refreshOAuth`：当共享的 `pi-ai` 刷新器不够用时，由提供商接管 OAuth 刷新 +- `buildAuthDoctorHint`：当 OAuth 刷新失败时，提供商追加修复指引 +- `matchesContextOverflowError`：提供商识别通用启发式规则无法发现的提供商特定上下文窗口溢出错误 +- `classifyFailoverReason`：提供商将提供商特定的原始传输/API 错误映射为回退原因，例如速率限制或过载 +- `isCacheTtlEligible`：提供商决定哪些上游模型 id 支持提示缓存 TTL +- `buildMissingAuthMessage`：提供商用提供商特定的恢复提示替换通用身份验证存储错误 +- `suppressBuiltInModel`：提供商隐藏过时的上游条目，并可在直接解析失败时返回厂商自有错误 +- `augmentModelCatalog`：提供商在发现和配置合并后追加 synthetic/最终目录条目 +- `isBinaryThinking`：提供商接管二元开/关 thinking UX +- `supportsXHighThinking`：提供商为选定模型启用 `xhigh` - `resolveDefaultThinkingLevel`：提供商接管某个模型家族的默认 `/think` 策略 -- `applyConfigDefaults`：提供商根据认证模式、环境变量或模型家族，在配置具体化期间应用提供商特定的全局默认值 +- `applyConfigDefaults`：提供商基于身份验证模式、环境变量或模型家族，在配置具体化期间应用提供商特定的全局默认值 - `isModernModelRef`：提供商接管 live/smoke 首选模型匹配 -- `prepareRuntimeAuth`：提供商将已配置凭证转换为短时效运行时令牌 +- `prepareRuntimeAuth`：提供商将已配置的凭证转换为短时效运行时令牌 - `resolveUsageAuth`：提供商为 `/usage` 及相关状态/报告界面解析用量/配额凭证 -- `fetchUsageSnapshot`：提供商接管用量端点获取/解析，而核心仍负责摘要外壳和格式化 -- `onModelSelected`：提供商在模型选定后运行后续副作用，例如遥测或提供商自有的会话簿记 +- `fetchUsageSnapshot`：提供商接管用量端点抓取/解析，而核心仍负责摘要外壳与格式化 +- `onModelSelected`：提供商在选中模型后执行副作用，例如遥测或提供商自主管理的会话记账 当前内置示例： -- `anthropic`：Claude 4.6 前向兼容回退、认证修复提示、用量端点抓取、缓存 TTL/提供商家族元数据，以及具备认证感知的全局配置默认值 -- `amazon-bedrock`：提供商自有的上下文溢出匹配和针对 Bedrock 特有节流/未就绪错误的回退原因分类，外加共享的 `anthropic-by-model` 重放家族，用于 Anthropic 流量上的仅 Claude 重放策略保护 -- `anthropic-vertex`：面向 Anthropic-message 流量的仅 Claude 重放策略保护 -- `openrouter`：透传模型 ID、请求包装器、提供商能力提示、代理 Gemini 流量上的 Gemini thought-signature 清理、通过 `openrouter-thinking` 流家族注入代理推理、路由元数据转发，以及缓存 TTL 策略 -- `github-copilot`：onboarding/设备登录、前向兼容模型回退、Claude-thinking 转录提示、运行时令牌交换，以及用量端点抓取 -- `openai`：GPT-5.4 前向兼容回退、直接 OpenAI 传输规范化、具备 Codex 感知的缺失认证提示、Spark 抑制、合成 OpenAI/Codex 目录条目、thinking/live-model 策略、用量令牌别名规范化（`input` / `output` 和 `prompt` / `completion` 家族）、共享的 `openai-responses-defaults` 流家族用于原生 OpenAI/Codex 包装器，以及提供商家族元数据 -- `google`：Gemini 3.1 前向兼容回退、原生 Gemini 重放验证、引导重放清理、带标签的推理输出模式，以及现代模型匹配 -- `moonshot`：共享传输、插件自有的 thinking 负载规范化 -- `kilocode`：共享传输、插件自有的请求头、推理负载规范化、代理 Gemini thought-signature 清理，以及缓存 TTL 策略 -- `zai`：GLM-5 前向兼容回退、`tool_stream` 默认值、缓存 TTL 策略、二元 thinking/live-model 策略，以及用量认证 + 配额抓取；未知的 `glm-5*` ID 会基于内置的 `glm-4.7` 模板合成 -- `xai`：原生 Responses 传输规范化、针对 Grok 快速变体的 `/fast` 别名重写、默认 `tool_stream`，以及 xAI 特有的工具模式 / 推理负载清理 -- `mistral`：插件自有的能力元数据 -- `opencode` 和 `opencode-go`：插件自有的能力元数据，外加代理 Gemini thought-signature 清理 -- `byteplus`、`cloudflare-ai-gateway`、`huggingface`、`kimi`、`nvidia`、`qianfan`、`stepfun`、`synthetic`、`together`、`venice`、`vercel-ai-gateway` 和 `volcengine`：仅插件自有目录 -- `qwen`：文本模型的插件自有目录，以及用于其多模态界面的共享媒体理解和视频生成提供商注册；Qwen 视频生成使用标准 DashScope 视频端点和内置的 Wan 模型，例如 `wan2.6-t2v` 和 `wan2.7-r2v` -- `minimax`：插件自有目录、混合 Anthropic/OpenAI 重放策略选择，以及用量认证/快照逻辑 -- `xiaomi`：插件自有目录，以及用量认证/快照逻辑 +- `anthropic`：Claude 4.6 前向兼容回退、身份验证修复提示、用量端点抓取、缓存 TTL/提供商家族元数据，以及具备身份验证感知的全局配置默认值 +- `amazon-bedrock`：提供商自主管理 Bedrock 特定限流/未就绪错误的上下文溢出匹配和回退原因分类，外加共享的 `anthropic-by-model` 重放家族，用于 Anthropic 流量上的 Claude 专属重放策略保护 +- `anthropic-vertex`：用于 Anthropic 消息流量上的 Claude 专属重放策略保护 +- `openrouter`：透传模型 id、请求包装器、提供商能力提示、代理 Gemini 流量上的 Gemini thought-signature 清理、通过 `openrouter-thinking` 流家族注入代理 reasoning、路由元数据转发，以及缓存 TTL 策略 +- `github-copilot`：新手引导/设备登录、前向兼容模型回退、Claude thinking 转录提示、运行时令牌交换，以及用量端点抓取 +- `openai`：GPT-5.4 前向兼容回退、直接 OpenAI 传输标准化、具备 Codex 感知的缺失身份验证提示、Spark 抑制、synthetic OpenAI/Codex 目录条目、thinking/live-model 策略、用量令牌别名标准化（`input` / `output` 和 `prompt` / `completion` 家族）、共享的 `openai-responses-defaults` 流家族用于原生 OpenAI/Codex 包装器、提供商家族元数据、为 `gpt-image-1` 内置图片生成提供商注册，以及为 `sora-2` 内置视频生成提供商注册 +- `google`：Gemini 3.1 前向兼容回退、原生 Gemini 重放校验、bootstrap 重放清理、带标签的 reasoning 输出模式、现代模型匹配、为 Gemini image-preview 模型内置图片生成提供商注册，以及为 Veo 模型内置视频生成提供商注册 +- `moonshot`：共享传输、插件自主管理的 thinking 载荷标准化 +- `kilocode`：共享传输、插件自主管理的请求头、reasoning 载荷标准化、代理 Gemini thought-signature 清理，以及缓存 TTL 策略 +- `zai`：GLM-5 前向兼容回退、`tool_stream` 默认值、缓存 TTL 策略、二元 thinking/live-model 策略，以及用量身份验证 + 配额抓取；未知的 `glm-5*` id 会基于内置的 `glm-4.7` 模板进行合成 +- `xai`：原生 Responses 传输标准化、为 Grok 快速变体重写 `/fast` 别名、默认启用 `tool_stream`、xAI 特定的工具 schema / reasoning 载荷清理，以及为 `grok-imagine-video` 内置视频生成提供商注册 +- `mistral`：插件自主管理的能力元数据 +- `opencode` 和 `opencode-go`：插件自主管理的能力元数据，以及代理 Gemini thought-signature 清理 +- `alibaba`：插件自主管理的直接 Wan 模型引用视频生成目录，例如 `alibaba/wan2.6-t2v` +- `byteplus`：插件自主管理的目录，以及为 Seedance 文生视频/图生视频模型内置视频生成提供商注册 +- `fal`：为托管的第三方图像生成模型内置图片生成提供商注册，以及为托管的第三方视频模型内置视频生成提供商注册 +- `cloudflare-ai-gateway`、`huggingface`、`kimi`、`nvidia`、`qianfan`、 + `stepfun`、`synthetic`、`venice`、`vercel-ai-gateway` 和 `volcengine`： + 仅插件自主管理目录 +- `qwen`：文本模型的插件自主管理目录，以及为其多模态能力提供共享的媒体理解和视频生成提供商注册；Qwen 视频生成使用标准 DashScope 视频端点和内置 Wan 模型，例如 `wan2.6-t2v` 和 `wan2.7-r2v` +- `minimax`：插件自主管理目录、为 Hailuo 视频模型内置视频生成提供商注册、为 `image-01` 内置图片生成提供商注册、混合 Anthropic/OpenAI 重放策略选择，以及用量身份验证/快照逻辑 +- `together`：插件自主管理目录，以及为 Wan 视频模型内置视频生成提供商注册 +- `xiaomi`：插件自主管理目录，以及用量身份验证/快照逻辑 -内置的 `openai` 插件现在同时拥有两个提供商 ID：`openai` 和 `openai-codex`。 +内置的 `openai` 插件现在同时拥有两个提供商 id：`openai` 和 +`openai-codex`。 -以上涵盖了仍适配 OpenClaw 常规传输方式的提供商。若某个提供商需要完全自定义的请求执行器，那就是另一层更深入的扩展接口了。 +以上涵盖了仍然适配 OpenClaw 常规传输的提供商。若某个提供商需要完全自定义的请求执行器，那就是另一层更深的扩展接口了。 -## API 密钥轮换 +## API key 轮换 - 支持为选定提供商进行通用提供商轮换。 -- 通过以下方式配置多个密钥： - - `OPENCLAW_LIVE__KEY`（单个 live 覆盖，最高优先级） +- 通过以下方式配置多个 key： + - `OPENCLAW_LIVE__KEY`（单个 live 覆盖项，最高优先级） - `_API_KEYS`（逗号或分号分隔列表） - - `_API_KEY`（主密钥） + - `_API_KEY`（主 key） - `_API_KEY_*`（编号列表，例如 `_API_KEY_1`） -- 对于 Google 提供商，`GOOGLE_API_KEY` 也会作为回退值包含在内。 -- 密钥选择顺序会保留优先级并对值去重。 -- 仅在速率限制响应时，请求才会使用下一个密钥重试（例如 `429`、`rate_limit`、`quota`、`resource exhausted`、`Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 或周期性用量限制消息）。 -- 非速率限制失败会立即失败；不会尝试密钥轮换。 -- 当所有候选密钥都失败时，会返回最后一次尝试的最终错误。 +- 对于 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 都失败时，将返回最后一次尝试的最终错误。 ## 内置提供商（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_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/"].params.transport` 为每个模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`） - OpenAI Responses WebSocket 预热默认通过 `params.openaiWsWarmup` 启用（`true`/`false`） -- 可通过 `agents.defaults.models["openai/"].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 中被有意抑制，因为 live OpenAI API 会拒绝它；Spark 被视为仅限 Codex +- 可以通过 `agents.defaults.models["openai/"].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 reasoning 兼容载荷整形；代理路由则不会 +- `openai/gpt-5.3-codex-spark` 在 OpenClaw 中被有意抑制，因为实时 OpenAI API 会拒绝它；Spark 被视为仅限 Codex ```json5 { @@ -147,12 +173,12 @@ OpenClaw 附带 pi‑ai 目录。这些提供商**不需要** `models.providers` ### Anthropic - 提供商：`anthropic` -- 认证：`ANTHROPIC_API_KEY` -- 可选轮换：`ANTHROPIC_API_KEYS`、`ANTHROPIC_API_KEY_1`、`ANTHROPIC_API_KEY_2`，以及 `OPENCLAW_LIVE_ANTHROPIC_KEY`（单个覆盖） +- 身份验证：`ANTHROPIC_API_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 密钥和 OAuth 认证流量；OpenClaw 会将其映射为 Anthropic `service_tier`（`auto` 与 `standard_only`） -- 计费说明：对于 Anthropic 在 OpenClaw 中的使用，实际区分是 **API 密钥** 或 **带 Extra Usage 的 Claude 订阅**。Anthropic 在 **2026 年 4 月 4 日下午 12:00（PT）/ 晚上 8:00（BST）** 通知 OpenClaw 用户，**OpenClaw** 的 Claude 登录路径会被计为第三方工具链使用，因此需要单独于订阅计费的 **Extra Usage**。我们的本地复现还表明，Anthropic SDK + API 密钥路径不会复现 OpenClaw 标识提示字符串。 +- 直接公共 Anthropic 请求支持共享的 `/fast` 开关和 `params.fastMode`，包括发送到 `api.anthropic.com` 的 API key 和 OAuth 身份验证流量；OpenClaw 会将其映射为 Anthropic `service_tier`（`auto` 与 `standard_only`） +- 计费说明：对于 OpenClaw 中的 Anthropic，实际上的划分是 **API key** 或 **带 Extra Usage 的 Claude 订阅**。Anthropic 于 **2026 年 4 月 4 日太平洋时间中午 12:00 / 英国夏令时间晚上 8:00** 通知 OpenClaw 用户，**OpenClaw** 的 Claude 登录路径会被计为第三方 harness 使用，且需要单独于订阅计费的 **Extra Usage**。我们的本地复现还表明，在 Anthropic SDK + API key 路径上不会复现 OpenClaw 标识提示字符串。 - Anthropic setup-token 现已再次作为旧版/手动 OpenClaw 路径提供。使用它时，请预期 Anthropic 已告知 OpenClaw 用户，此路径需要 **Extra Usage**。 ```json5 @@ -164,17 +190,19 @@ OpenClaw 附带 pi‑ai 目录。这些提供商**不需要** `models.providers` ### OpenAI Code（Codex） - 提供商：`openai-codex` -- 认证：OAuth（ChatGPT） +- 身份验证：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/"].params.transport` 为每个模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`） -- `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 +- `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-codex/gpt-5.4` 保留原生 `contextWindow = 1050000` 和默认运行时 `contextTokens = 272000`；可通过 `models.providers.openai-codex.models[].contextTokens` 覆盖运行时上限 -- 策略说明：OpenAI Codex OAuth 明确支持用于 OpenClaw 这类外部工具/工作流。 +- 策略说明：OpenAI Codex OAuth 明确支持像 OpenClaw 这样的外部工具/工作流。 ```json5 { @@ -196,13 +224,13 @@ OpenClaw 附带 pi‑ai 目录。这些提供商**不需要** `models.providers` ### 其他订阅式托管选项 -- [Qwen Cloud](/zh-CN/providers/qwen)：Qwen Cloud 提供商界面，以及 Alibaba DashScope 和 Coding Plan 端点映射 -- [MiniMax](/zh-CN/providers/minimax)：MiniMax Coding Plan OAuth 或 API 密钥访问 +- [Qwen Cloud](/zh-CN/providers/qwen)：Qwen Cloud 提供商接口，以及 Alibaba DashScope 和 Coding Plan 端点映射 +- [MiniMax](/zh-CN/providers/minimax)：MiniMax Coding Plan OAuth 或 API key 访问 - [GLM Models](/zh-CN/providers/glm)：Z.AI Coding Plan 或通用 API 端点 ### OpenCode -- 认证：`OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`） +- 身份验证：`OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`） - Zen 运行时提供商：`opencode` - Go 运行时提供商：`opencode-go` - 示例模型：`opencode/claude-opus-4-6`、`opencode-go/kimi-k2.5` @@ -214,65 +242,71 @@ OpenClaw 附带 pi‑ai 目录。这些提供商**不需要** `models.providers` } ``` -### Google Gemini（API 密钥） +### Google Gemini（API key） - 提供商：`google` -- 认证：`GEMINI_API_KEY` -- 可选轮换：`GEMINI_API_KEYS`、`GEMINI_API_KEY_1`、`GEMINI_API_KEY_2`、`GOOGLE_API_KEY` 回退，以及 `OPENCLAW_LIVE_GEMINI_KEY`（单个覆盖） +- 身份验证：`GEMINI_API_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/"].params.cachedContent`（或旧版 `cached_content`），以转发提供商原生的 `cachedContents/...` 句柄；Gemini 缓存命中会以 OpenClaw `cacheRead` 形式显示 +- 直接 Gemini 运行也接受 `agents.defaults.models["google/"].params.cachedContent` + （或旧版 `cached_content`），以转发提供商原生的 + `cachedContents/...` 句柄；Gemini 缓存命中会作为 OpenClaw `cacheRead` 显示 ### Google Vertex - 提供商：`google-vertex` -- 认证：gcloud ADC - - Gemini CLI JSON 回复从 `response` 解析；用量会回退到 `stats`，其中 `stats.cached` 会被规范化为 OpenClaw `cacheRead`。 +- 身份验证：gcloud ADC + - Gemini CLI JSON 回复从 `response` 解析；用量回退到 + `stats`，其中 `stats.cached` 会被标准化为 OpenClaw `cacheRead`。 ### Z.AI（GLM） - 提供商：`zai` -- 认证：`ZAI_API_KEY` +- 身份验证：`ZAI_API_KEY` - 示例模型：`zai/glm-5` - 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 网关 +### Vercel AI Gateway - 提供商：`vercel-ai-gateway` -- 认证：`AI_GATEWAY_API_KEY` +- 身份验证：`AI_GATEWAY_API_KEY` - 示例模型：`vercel-ai-gateway/anthropic/claude-opus-4.6` - CLI：`openclaw onboard --auth-choice ai-gateway-api-key` -### Kilo Gateway 网关 +### Kilo Gateway - 提供商：`kilocode` -- 认证：`KILOCODE_API_KEY` +- 身份验证：`KILOCODE_API_KEY` - 示例模型：`kilocode/kilo/auto` - CLI：`openclaw onboard --auth-choice kilocode-api-key` - 基础 URL：`https://api.kilo.ai/api/gateway/` -- 静态回退目录附带 `kilocode/kilo/auto`；live `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` -- 仅当请求实际指向 `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`） +- 仅当请求实际发往 `openrouter.ai` 时，OpenClaw 才会应用 OpenRouter 文档中的应用归因请求头 +- OpenRouter 特定的 Anthropic `cache_control` 标记同样只会应用于经过验证的 OpenRouter 路由，而不是任意代理 URL +- OpenRouter 仍然走代理式 OpenAI 兼容路径，因此不会转发 OpenAI 原生专属请求整形（`serviceTier`、Responses `store`、提示缓存提示、OpenAI reasoning 兼容载荷） +- 基于 Gemini 的 OpenRouter 引用仅保留代理 Gemini thought-signature 清理；原生 Gemini 重放校验和 bootstrap 重写仍保持关闭 +- Kilo Gateway：`kilocode`（`KILOCODE_API_KEY`） - 示例模型：`kilocode/kilo/auto` -- 基于 Gemini 的 Kilo 引用保留相同的代理 Gemini thought-signature 清理路径；`kilocode/kilo/auto` 及其他不支持代理推理提示的路径会跳过代理推理注入 -- MiniMax：`minimax`（API 密钥）和 `minimax-portal`（OAuth） -- 认证：`MINIMAX_API_KEY` 用于 `minimax`；`MINIMAX_OAUTH_TOKEN` 或 `MINIMAX_API_KEY` 用于 `minimax-portal` +- 基于 Gemini 的 Kilo 引用保留相同的代理 Gemini thought-signature 清理路径；`kilocode/kilo/auto` 和其他不支持代理 reasoning 的提示会跳过代理 reasoning 注入 +- MiniMax：`minimax`（API key）和 `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 onboarding/API 密钥设置会写入显式的 M2.7 模型定义，并带有 `input: ["text", "image"]`；在该提供商配置具体化之前，内置提供商目录会将聊天引用保持为仅文本 +- MiniMax 新手引导/API key 设置会写入显式的 M2.7 模型定义，并带有 + `input: ["text", "image"]`；在该提供商配置具体化之前，内置提供商目录会将聊天引用保持为仅文本 - Moonshot：`moonshot`（`MOONSHOT_API_KEY`） - 示例模型：`moonshot/kimi-k2.5` - Kimi Coding：`kimi`（`KIMI_API_KEY` 或 `KIMICODE_API_KEY`） @@ -290,40 +324,44 @@ OpenClaw 附带 pi‑ai 目录。这些提供商**不需要** `models.providers` - Venice：`venice`（`VENICE_API_KEY`） - Xiaomi：`xiaomi`（`XIAOMI_API_KEY`） - 示例模型：`xiaomi/mimo-v2-flash` -- Vercel AI Gateway 网关：`vercel-ai-gateway`（`AI_GATEWAY_API_KEY`） +- Vercel AI Gateway：`vercel-ai-gateway`（`AI_GATEWAY_API_KEY`） - Hugging Face Inference：`huggingface`（`HUGGINGFACE_HUB_TOKEN` 或 `HF_TOKEN`） -- Cloudflare AI Gateway 网关：`cloudflare-ai-gateway`（`CLOUDFLARE_AI_GATEWAY_API_KEY`） +- 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-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/"].params.tool_stream` 设为 `false` 可关闭 + - 原生内置的 xAI 请求使用 xAI Responses 路径 + - `/fast` 或 `params.fastMode: true` 会将 `grok-3`、`grok-3-mini`、 + `grok-4` 和 `grok-4-0709` 重写为其 `*-fast` 变体 + - `tool_stream` 默认开启；将 + `agents.defaults.models["xai/"].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 兼容基础 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)。 +- 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` 使用的提供商（自定义/基础 URL） +## 通过 `models.providers` 配置的提供商（自定义/基础 URL） -使用 `models.providers`（或 `models.json`）添加**自定义**提供商或 OpenAI/Anthropic 兼容代理。 +使用 `models.providers`（或 `models.json`）来添加**自定义**提供商或 +OpenAI/Anthropic 兼容代理。 -下面许多内置提供商插件已经发布了默认目录。 -仅当你想覆盖默认基础 URL、请求头或模型列表时，才使用显式 `models.providers.` 条目。 +下面的许多内置提供商插件已经发布了默认目录。 +只有当你想覆盖默认基础 URL、请求头或模型列表时，才需要显式添加 `models.providers.` 条目。 ### Moonshot AI（Kimi） -Moonshot 作为内置提供商插件提供。默认请使用内置提供商，仅当你需要覆盖基础 URL 或模型元数据时，才添加显式 `models.providers.moonshot` 条目： +Moonshot 作为内置提供商插件提供。默认使用内置提供商，只有在你需要覆盖基础 URL 或模型元数据时，才添加显式的 `models.providers.moonshot` 条目： - 提供商：`moonshot` -- 认证：`MOONSHOT_API_KEY` +- 身份验证：`MOONSHOT_API_KEY` - 示例模型：`moonshot/kimi-k2.5` - CLI：`openclaw onboard --auth-choice moonshot-api-key` 或 `openclaw onboard --auth-choice moonshot-api-key-cn` @@ -362,7 +400,7 @@ Kimi K2 模型 ID： Kimi Coding 使用 Moonshot AI 的 Anthropic 兼容端点： - 提供商：`kimi` -- 认证：`KIMI_API_KEY` +- 身份验证：`KIMI_API_KEY` - 示例模型：`kimi/kimi-code` ```json5 @@ -374,14 +412,14 @@ Kimi Coding 使用 Moonshot AI 的 Anthropic 兼容端点： } ``` -旧版 `kimi/k2p5` 仍然作为兼容模型 ID 被接受。 +旧版 `kimi/k2p5` 仍然作为兼容模型 id 被接受。 ### Volcano Engine（Doubao） -Volcano Engine（火山引擎）为中国用户提供 Doubao 和其他模型的访问。 +Volcano Engine（火山引擎）为中国用户提供对 Doubao 和其他模型的访问。 -- 提供商：`volcengine`（编程：`volcengine-plan`） -- 认证：`VOLCANO_ENGINE_API_KEY` +- 提供商：`volcengine`（编码：`volcengine-plan`） +- 身份验证：`VOLCANO_ENGINE_API_KEY` - 示例模型：`volcengine-plan/ark-code-latest` - CLI：`openclaw onboard --auth-choice volcengine-api-key` @@ -393,9 +431,10 @@ Volcano Engine（火山引擎）为中国用户提供 Doubao 和其他模型的 } ``` -onboarding 默认使用编程界面，但同时也会注册通用 `volcengine/*` 目录。 +新手引导默认使用 coding 接口，但通用 `volcengine/*` +目录会同时注册。 -在 onboarding/配置模型选择器中，Volcengine 认证选项会优先显示 `volcengine/*` 和 `volcengine-plan/*` 两类条目。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示一个空的提供商范围选择器。 +在 onboarding/配置模型选择器中，Volcengine 身份验证选项会优先显示 `volcengine/*` 和 `volcengine-plan/*` 两类条目。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示一个空的提供商范围选择器。 可用模型： @@ -405,7 +444,7 @@ onboarding 默认使用编程界面，但同时也会注册通用 `volcengine/*` - `volcengine/glm-4-7-251222`（GLM 4.7） - `volcengine/deepseek-v3-2-251201`（DeepSeek V3.2 128K） -编程模型（`volcengine-plan`）： +Coding 模型（`volcengine-plan`）： - `volcengine-plan/ark-code-latest` - `volcengine-plan/doubao-seed-code` @@ -417,8 +456,8 @@ onboarding 默认使用编程界面，但同时也会注册通用 `volcengine/*` BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问。 -- 提供商：`byteplus`（编程：`byteplus-plan`） -- 认证：`BYTEPLUS_API_KEY` +- 提供商：`byteplus`（编码：`byteplus-plan`） +- 身份验证：`BYTEPLUS_API_KEY` - 示例模型：`byteplus-plan/ark-code-latest` - CLI：`openclaw onboard --auth-choice byteplus-api-key` @@ -430,9 +469,10 @@ BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问。 } ``` -onboarding 默认使用编程界面，但同时也会注册通用 `byteplus/*` 目录。 +新手引导默认使用 coding 接口，但通用 `byteplus/*` +目录会同时注册。 -在 onboarding/配置模型选择器中，BytePlus 认证选项会优先显示 `byteplus/*` 和 `byteplus-plan/*` 两类条目。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示一个空的提供商范围选择器。 +在 onboarding/配置模型选择器中，BytePlus 身份验证选项会优先显示 `byteplus/*` 和 `byteplus-plan/*` 两类条目。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示一个空的提供商范围选择器。 可用模型： @@ -440,7 +480,7 @@ onboarding 默认使用编程界面，但同时也会注册通用 `byteplus/*` - `byteplus/kimi-k2-5-260127`（Kimi K2.5） - `byteplus/glm-4-7-251222`（GLM 4.7） -编程模型（`byteplus-plan`）： +Coding 模型（`byteplus-plan`）： - `byteplus-plan/ark-code-latest` - `byteplus-plan/doubao-seed-code` @@ -453,7 +493,7 @@ onboarding 默认使用编程界面，但同时也会注册通用 `byteplus/*` Synthetic 通过 `synthetic` 提供商提供 Anthropic 兼容模型： - 提供商：`synthetic` -- 认证：`SYNTHETIC_API_KEY` +- 身份验证：`SYNTHETIC_API_KEY` - 示例模型：`synthetic/hf:MiniMaxAI/MiniMax-M2.5` - CLI：`openclaw onboard --auth-choice synthetic-api-key` @@ -480,29 +520,31 @@ Synthetic 通过 `synthetic` 提供商提供 Anthropic 兼容模型： MiniMax 通过 `models.providers` 配置，因为它使用自定义端点： -- MiniMax OAuth（全球）：`--auth-choice minimax-global-oauth` -- MiniMax OAuth（中国）：`--auth-choice minimax-cn-oauth` -- MiniMax API 密钥（全球）：`--auth-choice minimax-global-api` -- MiniMax API 密钥（中国）：`--auth-choice minimax-cn-api` -- 认证：`MINIMAX_API_KEY` 用于 `minimax`；`MINIMAX_OAUTH_TOKEN` 或 `MINIMAX_API_KEY` 用于 `minimax-portal` +- 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` -设置详情、模型选项和配置片段请参见 [/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`。 -插件自有能力划分： +插件自主管理的能力划分： -- 文本/聊天默认保持在 `minimax/MiniMax-M2.7` -- 图像生成使用 `minimax/image-01` 或 `minimax-portal/image-01` -- 图像理解在两个 MiniMax 认证路径上都使用插件自有的 `MiniMax-VL-01` -- Web 搜索保持在提供商 ID `minimax` +- 文本/聊天默认仍使用 `minimax/MiniMax-M2.7` +- 图片生成使用 `minimax/image-01` 或 `minimax-portal/image-01` +- 图像理解由插件自主管理，在两种 MiniMax 身份验证路径上都使用 `MiniMax-VL-01` +- Web 搜索仍使用提供商 id `minimax` ### Ollama Ollama 作为内置提供商插件提供，并使用 Ollama 原生 API： - 提供商：`ollama` -- 认证：无需（本地服务器） +- 身份验证：无需（本地服务器） - 示例模型：`ollama/llama3.3` - 安装：[https://ollama.com/download](https://ollama.com/download) @@ -519,23 +561,25 @@ ollama pull llama3.3 } ``` -当你通过 `OLLAMA_API_KEY` 选择启用时，Ollama 会在本地 `http://127.0.0.1:11434` 被检测到，内置提供商插件会将 Ollama 直接添加到 `openclaw onboard` 和模型选择器中。关于 onboarding、云端/本地模式和自定义配置，请参见 [/providers/ollama](/zh-CN/providers/ollama)。 +当你通过 `OLLAMA_API_KEY` 选择启用时，系统会在本地 +`http://127.0.0.1:11434` 检测 Ollama，内置提供商插件还会将 Ollama 直接添加到 +`openclaw onboard` 和模型选择器中。有关 onboarding、云端/本地模式和自定义配置，请参阅 [/providers/ollama](/zh-CN/providers/ollama)。 ### vLLM vLLM 作为内置提供商插件提供，用于本地/自托管的 OpenAI 兼容服务器： - 提供商：`vllm` -- 认证：可选（取决于你的服务器） +- 身份验证：可选（取决于你的服务器） - 默认基础 URL：`http://127.0.0.1:8000/v1` -要选择启用本地自动发现（如果你的服务器不强制认证，任意值都可以）： +要在本地启用自动发现（如果你的服务器不强制身份验证，任意值都可以）： ```bash export VLLM_API_KEY="vllm-local" ``` -然后设置一个模型（替换为 `/v1/models` 返回的某个 ID）： +然后设置一个模型（替换为 `/v1/models` 返回的某个 id）： ```json5 { @@ -545,23 +589,24 @@ export VLLM_API_KEY="vllm-local" } ``` -详情请参见 [/providers/vllm](/zh-CN/providers/vllm)。 +详情请参阅 [/providers/vllm](/zh-CN/providers/vllm)。 ### SGLang -SGLang 作为内置提供商插件提供，用于高速自托管的 OpenAI 兼容服务器： +SGLang 作为内置提供商插件提供，用于高性能自托管的 +OpenAI 兼容服务器： - 提供商：`sglang` -- 认证：可选（取决于你的服务器） +- 身份验证：可选（取决于你的服务器） - 默认基础 URL：`http://127.0.0.1:30000/v1` -要选择启用本地自动发现（如果你的服务器不强制认证，任意值都可以）： +要在本地启用自动发现（如果你的服务器不强制身份验证，任意值都可以）： ```bash export SGLANG_API_KEY="sglang-local" ``` -然后设置一个模型（替换为 `/v1/models` 返回的某个 ID）： +然后设置一个模型（替换为 `/v1/models` 返回的某个 id）： ```json5 { @@ -571,7 +616,7 @@ export SGLANG_API_KEY="sglang-local" } ``` -详情请参见 [/providers/sglang](/zh-CN/providers/sglang)。 +详情请参阅 [/providers/sglang](/zh-CN/providers/sglang)。 ### 本地代理（LM Studio、vLLM、LiteLLM 等） @@ -582,7 +627,7 @@ export SGLANG_API_KEY="sglang-local" agents: { defaults: { model: { primary: "lmstudio/my-local-model" }, - models: { "lmstudio/my-local-model": { alias: "本地" } }, + models: { "lmstudio/my-local-model": { alias: "Local" } }, }, }, models: { @@ -594,7 +639,7 @@ export SGLANG_API_KEY="sglang-local" models: [ { id: "my-local-model", - name: "本地模型", + name: "Local Model", reasoning: false, input: ["text"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, @@ -610,18 +655,18 @@ export SGLANG_API_KEY="sglang-local" 说明： -- 对于自定义提供商，`reasoning`、`input`、`cost`、`contextWindow` 和 `maxTokens` 都是可选项。 +- 对于自定义提供商，`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"`（任意非空 `baseUrl`，且其主机不是 `api.openai.com`），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` 仍会被覆盖。 +- 建议：设置与代理/模型限制相匹配的显式值。 +- 对于非原生端点上的 `api: "openai-completions"`（任何非空 `baseUrl` 且其主机不是 `api.openai.com`），OpenClaw 会强制设置 `compat.supportsDeveloperRole: false`，以避免提供商因不支持 `developer` 角色而返回 400 错误。 +- 代理式 OpenAI 兼容路由还会跳过 OpenAI 原生专属的请求整形：没有 `service_tier`、没有 Responses `store`、没有提示缓存提示、没有 OpenAI reasoning 兼容载荷整形，也没有隐藏的 OpenClaw 归因请求头。 +- 如果 `baseUrl` 为空或省略，OpenClaw 会保留默认的 OpenAI 行为（解析到 `api.openai.com`）。 +- 为了安全起见，即使显式设置了 `compat.supportsDeveloperRole: true`，在非原生 `openai-completions` 端点上仍会被覆盖。 ## CLI 示例 @@ -631,11 +676,11 @@ openclaw models set opencode/claude-opus-4-6 openclaw models list ``` -另请参见：[/gateway/configuration](/zh-CN/gateway/configuration) 了解完整配置示例。 +另请参阅：[/gateway/configuration](/zh-CN/gateway/configuration) 获取完整配置示例。 ## 相关内容 -- [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) — 各提供商设置指南 +- [模型](/zh-CN/concepts/models) — 模型配置和别名 +- [模型回退](/zh-CN/concepts/model-failover) — 回退链和重试行为 +- [配置参考](/zh-CN/gateway/configuration-reference#agent-defaults) — 模型配置键 +- [提供商](/zh-CN/providers) — 按提供商分类的设置指南 diff --git a/docs/zh-CN/providers/alibaba.md b/docs/zh-CN/providers/alibaba.md new file mode 100644 index 000000000..4541724be --- /dev/null +++ b/docs/zh-CN/providers/alibaba.md @@ -0,0 +1,78 @@ +--- +read_when: + - 你想在 OpenClaw 中使用 Alibaba Wan 视频生成 + - 你需要为视频生成设置 Model Studio 或 DashScope API 密钥 +summary: OpenClaw 中的 Alibaba Model Studio Wan 视频生成 +title: Alibaba Model Studio +x-i18n: + generated_at: "2026-04-05T22:22:54Z" + model: gpt-5.4 + provider: openai + source_hash: dca1ddd91e884773c3835eebda2da3da2994f82f940bdd26fe94e55cac149058 + source_path: providers/alibaba.md + workflow: 15 +--- + +# Alibaba Model Studio + +OpenClaw 内置了一个 `alibaba` 视频生成提供商，用于 Alibaba Model Studio / DashScope 上的 Wan 模型。 + +- 提供商：`alibaba` +- 首选凭证：`MODELSTUDIO_API_KEY` +- 也接受：`DASHSCOPE_API_KEY`、`QWEN_API_KEY` +- API：DashScope / Model Studio 异步视频生成 + +## 快速开始 + +1. 设置 API 密钥： + +```bash +openclaw onboard --auth-choice qwen-standard-api-key +``` + +2. 设置默认视频模型： + +```json5 +{ + agents: { + defaults: { + videoGenerationModel: { + primary: "alibaba/wan2.6-t2v", + }, + }, + }, +} +``` + +## 内置 Wan 模型 + +内置的 `alibaba` 提供商当前注册了以下模型： + +- `alibaba/wan2.6-t2v` +- `alibaba/wan2.6-i2v` +- `alibaba/wan2.6-r2v` +- `alibaba/wan2.6-r2v-flash` +- `alibaba/wan2.7-r2v` + +## 当前限制 + +- 每次请求最多 **1** 个输出视频 +- 最多 **1** 张输入图片 +- 最多 **4** 个输入视频 +- 最长 **10 秒** 时长 +- 支持 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` +- 参考图片/视频模式当前要求使用 **远程 http(s) URL** + +## 与 Qwen 的关系 + +内置的 `qwen` 提供商也使用 Alibaba 托管的 DashScope 端点来进行 Wan 视频生成。请使用： + +- 当你想使用规范的 Qwen 提供商接口时，使用 `qwen/...` +- 当你想使用供应商直接拥有的 Wan 视频接口时，使用 `alibaba/...` + +## 相关内容 + +- [视频生成](/zh-CN/tools/video-generation) +- [Qwen](/zh-CN/providers/qwen) +- [Qwen / Model Studio](/zh-CN/providers/qwen_modelstudio) +- [配置参考](/zh-CN/gateway/configuration-reference#agent-defaults) diff --git a/docs/zh-CN/providers/fal.md b/docs/zh-CN/providers/fal.md new file mode 100644 index 000000000..022d95ff5 --- /dev/null +++ b/docs/zh-CN/providers/fal.md @@ -0,0 +1,97 @@ +--- +read_when: + - 你想在 OpenClaw 中使用 fal 图像生成 + - 你需要 FAL_KEY 认证流程 + - 你想为 image_generate 或 video_generate 使用 fal 默认值 +summary: 在 OpenClaw 中设置 fal 图像和视频生成 +title: fal +x-i18n: + generated_at: "2026-04-05T22:22:53Z" + model: gpt-5.4 + provider: openai + source_hash: f136abdc36826812c9f1930483df308247de07be2dacab4d4c6c1b32d951602c + source_path: providers/fal.md + workflow: 15 +--- + +# fal + +OpenClaw 内置了一个 `fal` 提供商，用于托管式图像和视频生成。 + +- 提供商：`fal` +- 认证：`FAL_KEY` +- API：fal 模型端点 + +## 快速开始 + +1. 设置 API 密钥： + +```bash +openclaw onboard --auth-choice fal-api-key +``` + +2. 设置默认图像模型： + +```json5 +{ + agents: { + defaults: { + imageGenerationModel: { + primary: "fal/fal-ai/flux/dev", + }, + }, + }, +} +``` + +## 图像生成 + +内置的 `fal` 图像生成提供商默认使用 +`fal/fal-ai/flux/dev`。 + +- 生成：每个请求最多 4 张图像 +- 编辑模式：已启用，支持 1 张参考图像 +- 支持 `size`、`aspectRatio` 和 `resolution` +- 当前编辑限制：fal 图像编辑端点**不**支持 + `aspectRatio` 覆盖 + +要将 fal 用作默认图像提供商： + +```json5 +{ + agents: { + defaults: { + imageGenerationModel: { + primary: "fal/fal-ai/flux/dev", + }, + }, + }, +} +``` + +## 视频生成 + +内置的 `fal` 视频生成提供商默认使用 +`fal/fal-ai/minimax/video-01-live`。 + +- 模式：文生视频和单图参考流程 + +要将 fal 用作默认视频提供商： + +```json5 +{ + agents: { + defaults: { + videoGenerationModel: { + primary: "fal/fal-ai/minimax/video-01-live", + }, + }, + }, +} +``` + +## 相关内容 + +- [图像生成](/zh-CN/tools/image-generation) +- [视频生成](/zh-CN/tools/video-generation) +- [配置参考](/zh-CN/gateway/configuration-reference#agent-defaults) diff --git a/docs/zh-CN/providers/google.md b/docs/zh-CN/providers/google.md index ae545429c..1172b7a98 100644 --- a/docs/zh-CN/providers/google.md +++ b/docs/zh-CN/providers/google.md @@ -1,21 +1,21 @@ --- read_when: - - 你想在 OpenClaw 中使用 Google Gemini 模型 + - 你想将 Google Gemini 模型与 OpenClaw 一起使用 - 你需要 API 密钥认证流程 summary: Google Gemini 设置（API 密钥、图像生成、媒体理解、Web 搜索） title: Google（Gemini） x-i18n: - generated_at: "2026-04-05T18:14:58Z" + generated_at: "2026-04-05T22:22:59Z" model: gpt-5.4 provider: openai - source_hash: 0df5bcbd98e2c1dafea3e9919e9793533ba785120b24f1db12e8e35b1ad23083 + source_hash: c0dc6413ca67e0fe274c7fc1182cf220252aae31266a72e0b251a319d4dd286e source_path: providers/google.md workflow: 15 --- # Google（Gemini） -Google 插件通过 Google AI Studio 提供对 Gemini 模型的访问，以及通过 Gemini Grounding 提供图像生成、媒体理解（图像/音频/视频）和 Web 搜索功能。 +Google 插件通过 Google AI Studio 提供对 Gemini 模型的访问，以及通过 Gemini Grounding 提供图像生成、媒体理解（图像/音频/视频）和 Web 搜索。 - 提供商：`google` - 认证：`GEMINI_API_KEY` 或 `GOOGLE_API_KEY` @@ -52,7 +52,7 @@ openclaw onboard --non-interactive \ ## 功能 -| 功能 | 支持情况 | +| 能力 | 支持情况 | | ---------------------- | ----------------- | | 聊天补全 | 是 | | 图像生成 | 是 | @@ -60,16 +60,16 @@ openclaw onboard --non-interactive \ | 音频转录 | 是 | | 视频理解 | 是 | | Web 搜索（Grounding） | 是 | -| Thinking/推理 | 是（Gemini 3.1+） | +| 思考/推理 | 是（Gemini 3.1+） | ## 直接复用 Gemini 缓存 -对于直接 Gemini API 运行（`api: "google-generative-ai"`），OpenClaw 现在会将已配置的 `cachedContent` 句柄透传到 Gemini 请求中。 +对于直接调用 Gemini API 的运行（`api: "google-generative-ai"`），OpenClaw 现在会将已配置的 `cachedContent` 句柄透传给 Gemini 请求。 -- 使用 `cachedContent` 或旧版 `cached_content` 为每个模型或全局参数进行配置 -- 如果两者都存在，则 `cachedContent` 优先 +- 可使用 `cachedContent` 或旧版 `cached_content` 为每个模型或全局配置参数 +- 如果两者同时存在，则以 `cachedContent` 为准 - 示例值：`cachedContents/prebuilt-context` -- Gemini 缓存命中的用量会从上游 `cachedContentTokenCount` 规范化为 OpenClaw `cacheRead` +- Gemini 的缓存命中用量会从上游的 `cachedContentTokenCount` 规范化为 OpenClaw 的 `cacheRead` 示例： @@ -98,8 +98,49 @@ openclaw onboard --non-interactive \ - 编辑模式：已启用，最多支持 5 张输入图像 - 几何控制：`size`、`aspectRatio` 和 `resolution` -图像生成、媒体理解和 Gemini Grounding 都保持使用 `google` 提供商 ID。 +图像生成、媒体理解和 Gemini Grounding 都保持使用 `google` 提供商 id。 + +要将 Google 用作默认图像提供商： + +```json5 +{ + agents: { + defaults: { + imageGenerationModel: { + primary: "google/gemini-3.1-flash-image-preview", + }, + }, + }, +} +``` + +有关共享工具参数、提供商选择和故障转移行为，请参阅 [Image Generation](/zh-CN/tools/image-generation)。 + +## 视频生成 + +内置的 `google` 插件还会通过共享的 `video_generate` 工具注册视频生成功能。 + +- 默认视频模型：`google/veo-3.1-fast-generate-preview` +- 模式：文生视频、图生视频，以及单视频参考流程 +- 支持 `aspectRatio`、`resolution` 和 `audio` +- 当前时长限制：**4 到 8 秒** + +要将 Google 用作默认视频提供商： + +```json5 +{ + agents: { + defaults: { + videoGenerationModel: { + primary: "google/veo-3.1-fast-generate-preview", + }, + }, + }, +} +``` + +有关共享工具参数、提供商选择和故障转移行为，请参阅 [Video Generation](/zh-CN/tools/video-generation)。 ## 环境说明 -如果 Gateway 网关以守护进程（launchd/systemd）方式运行，请确保 `GEMINI_API_KEY` 对该进程可用（例如，在 `~/.openclaw/.env` 中，或通过 `env.shellEnv`）。 +如果 Gateway 网关 作为守护进程运行（launchd/systemd），请确保该进程可以访问 `GEMINI_API_KEY`（例如，在 `~/.openclaw/.env` 中设置，或通过 `env.shellEnv` 提供）。 diff --git a/docs/zh-CN/providers/index.md b/docs/zh-CN/providers/index.md index 92b08059a..dd8fc25d3 100644 --- a/docs/zh-CN/providers/index.md +++ b/docs/zh-CN/providers/index.md @@ -1,14 +1,14 @@ --- read_when: - 你想选择一个模型提供商 - - 你需要快速了解受支持的 LLM 后端 + - 你需要快速了解支持的 LLM 后端 summary: OpenClaw 支持的模型提供商（LLM） title: 提供商目录 x-i18n: - generated_at: "2026-04-05T08:42:14Z" + generated_at: "2026-04-05T22:22:58Z" model: gpt-5.4 provider: openai - source_hash: 690d17c14576d454ea3cd3dcbc704470da10a2a34adfe681dab7048438f2e193 + source_hash: a13202fc20a64c68e9c7de4f2cd8ad11908029f3fe3300a8e6d69fcb0b6080ba source_path: providers/index.md workflow: 15 --- @@ -17,7 +17,7 @@ x-i18n: OpenClaw 可以使用许多 LLM 提供商。选择一个提供商，完成身份验证，然后将默认模型设置为 `provider/model`。 -在找聊天渠道文档（WhatsApp/Telegram/Discord/Slack/Mattermost（插件）/ 等）？请参阅 [Channels](/channels)。 +在寻找聊天渠道文档（WhatsApp/Telegram/Discord/Slack/Mattermost（插件）/ 等）？请参见 [Channels](/zh-CN/channels)。 ## 快速开始 @@ -32,55 +32,59 @@ OpenClaw 可以使用许多 LLM 提供商。选择一个提供商，完成身份 ## 提供商文档 -- [Amazon Bedrock](/providers/bedrock) -- [Anthropic（API + Claude CLI）](/providers/anthropic) -- [BytePlus（国际版）](/concepts/model-providers#byteplus-international) -- [Chutes](/providers/chutes) -- [Cloudflare AI Gateway](/providers/cloudflare-ai-gateway) -- [DeepSeek](/providers/deepseek) -- [Fireworks](/providers/fireworks) -- [GitHub Copilot](/providers/github-copilot) -- [GLM 模型](/providers/glm) -- [Google（Gemini）](/providers/google) -- [Groq（LPU 推理）](/providers/groq) -- [Hugging Face（推理）](/providers/huggingface) -- [Kilocode](/providers/kilocode) -- [LiteLLM（统一 Gateway 网关）](/providers/litellm) -- [MiniMax](/providers/minimax) -- [Mistral](/providers/mistral) -- [Moonshot AI（Kimi + Kimi Coding）](/providers/moonshot) -- [NVIDIA](/providers/nvidia) -- [Ollama（云端 + 本地模型）](/providers/ollama) -- [OpenAI（API + Codex）](/providers/openai) -- [OpenCode](/providers/opencode) -- [OpenCode Go](/providers/opencode-go) -- [OpenRouter](/providers/openrouter) -- [Perplexity（网页搜索）](/providers/perplexity-provider) -- [Qianfan](/providers/qianfan) -- [Qwen Cloud](/providers/qwen) -- [Qwen / Model Studio（端点详情；`qwen-*` 为规范名称，`modelstudio-*` 为旧版名称）](/providers/qwen_modelstudio) -- [SGLang（本地模型）](/providers/sglang) -- [StepFun](/providers/stepfun) -- [Synthetic](/providers/synthetic) -- [Together AI](/providers/together) -- [Venice（Venice AI，注重隐私）](/providers/venice) -- [Vercel AI Gateway](/providers/vercel-ai-gateway) -- [vLLM（本地模型）](/providers/vllm) -- [Volcengine（Doubao）](/providers/volcengine) -- [xAI](/providers/xai) -- [Xiaomi](/providers/xiaomi) -- [Z.AI](/providers/zai) +- [阿里巴巴 Model Studio](/providers/alibaba) +- [Amazon Bedrock](/zh-CN/providers/bedrock) +- [Anthropic（API + Claude CLI）](/zh-CN/providers/anthropic) +- [BytePlus（国际版）](/zh-CN/concepts/model-providers#byteplus-international) +- [Chutes](/zh-CN/providers/chutes) +- [Cloudflare AI Gateway](/zh-CN/providers/cloudflare-ai-gateway) +- [DeepSeek](/zh-CN/providers/deepseek) +- [fal](/providers/fal) +- [Fireworks](/zh-CN/providers/fireworks) +- [GitHub Copilot](/zh-CN/providers/github-copilot) +- [GLM 模型](/zh-CN/providers/glm) +- [Google（Gemini）](/zh-CN/providers/google) +- [Groq（LPU 推理）](/zh-CN/providers/groq) +- [Hugging Face（推理）](/zh-CN/providers/huggingface) +- [Kilocode](/zh-CN/providers/kilocode) +- [LiteLLM（统一 Gateway 网关）](/zh-CN/providers/litellm) +- [MiniMax](/zh-CN/providers/minimax) +- [Mistral](/zh-CN/providers/mistral) +- [Moonshot AI（Kimi + Kimi Coding）](/zh-CN/providers/moonshot) +- [NVIDIA](/zh-CN/providers/nvidia) +- [Ollama（云端 + 本地模型）](/zh-CN/providers/ollama) +- [OpenAI（API + Codex）](/zh-CN/providers/openai) +- [OpenCode](/zh-CN/providers/opencode) +- [OpenCode Go](/zh-CN/providers/opencode-go) +- [OpenRouter](/zh-CN/providers/openrouter) +- [Perplexity（网页搜索）](/zh-CN/providers/perplexity-provider) +- [Qianfan](/zh-CN/providers/qianfan) +- [Qwen Cloud](/zh-CN/providers/qwen) +- [Qwen / Model Studio（端点详情；`qwen-*` 为规范名称，`modelstudio-*` 为旧版名称）](/zh-CN/providers/qwen_modelstudio) +- [SGLang（本地模型）](/zh-CN/providers/sglang) +- [StepFun](/zh-CN/providers/stepfun) +- [Synthetic](/zh-CN/providers/synthetic) +- [Together AI](/zh-CN/providers/together) +- [Venice（Venice AI，注重隐私）](/zh-CN/providers/venice) +- [Vercel AI Gateway](/zh-CN/providers/vercel-ai-gateway) +- [vLLM（本地模型）](/zh-CN/providers/vllm) +- [Volcengine（Doubao）](/zh-CN/providers/volcengine) +- [xAI](/zh-CN/providers/xai) +- [Xiaomi](/zh-CN/providers/xiaomi) +- [Z.AI](/zh-CN/providers/zai) ## 共享概览页面 -- [其他内置变体](/providers/models#additional-bundled-provider-variants) - Anthropic Vertex、Copilot Proxy 和 Gemini CLI OAuth +- [其他内置变体](/zh-CN/providers/models#additional-bundled-provider-variants) - Anthropic Vertex、Copilot Proxy 和 Gemini CLI OAuth +- [图像生成](/zh-CN/tools/image-generation) - 共享的 `image_generate` 工具、提供商选择和故障切换 +- [视频生成](/zh-CN/tools/video-generation) - 共享的 `video_generate` 工具、提供商选择和故障切换 ## 转录提供商 -- [Deepgram（音频转录）](/providers/deepgram) +- [Deepgram（音频转录）](/zh-CN/providers/deepgram) ## 社区工具 -- [Claude Max API Proxy](/providers/claude-max-api-proxy) - 用于 Claude 订阅凭证的社区代理（使用前请确认 Anthropic 的政策/条款） +- [Claude Max API Proxy](/zh-CN/providers/claude-max-api-proxy) - 用于 Claude 订阅凭证的社区代理（使用前请确认 Anthropic 的政策/条款） -有关完整的提供商目录（xAI、Groq、Mistral 等）和高级配置，请参阅 [模型提供商](/concepts/model-providers)。 +有关完整的提供商目录（xAI、Groq、Mistral 等）和高级配置，请参见 [模型提供商](/zh-CN/concepts/model-providers)。 diff --git a/docs/zh-CN/providers/minimax.md b/docs/zh-CN/providers/minimax.md index 29b59c1d1..94815617a 100644 --- a/docs/zh-CN/providers/minimax.md +++ b/docs/zh-CN/providers/minimax.md @@ -5,10 +5,10 @@ read_when: summary: 在 OpenClaw 中使用 MiniMax 模型 title: MiniMax x-i18n: - generated_at: "2026-04-05T08:42:54Z" + generated_at: "2026-04-05T22:23:23Z" model: gpt-5.4 provider: openai - source_hash: 353e1d9ce1b48c90ccaba6cc0109e839c473ca3e65d0c5d8ba744e9011c2bf45 + source_hash: 32e737d8eb9b9728ec3925f626599bb4be6d0904b6357b29c6f33a315600fef4 source_path: providers/minimax.md workflow: 15 --- @@ -19,14 +19,14 @@ OpenClaw 的 MiniMax 提供商默认使用 **MiniMax M2.7**。 MiniMax 还提供： -- 通过 T2A v2 内置的语音合成 -- 通过 `MiniMax-VL-01` 内置的图像理解 -- 通过 MiniMax Coding Plan 搜索 API 内置的 `web_search` +- 通过 T2A v2 内置语音合成 +- 通过 `MiniMax-VL-01` 内置图像理解 +- 通过 MiniMax Coding Plan 搜索 API 内置 `web_search` -提供商拆分如下： +提供商划分： -- `minimax`：基于 API 密钥的文本提供商，另外内置图像生成、图像理解、语音和网页搜索 -- `minimax-portal`：OAuth 文本提供商，另外内置图像生成和图像理解 +- `minimax`：基于 API 密钥的文本提供商，另含内置图像生成、图像理解、语音和 Web 搜索 +- `minimax-portal`：基于 OAuth 的文本提供商，另含内置图像生成和图像理解 ## 模型阵容 @@ -38,8 +38,8 @@ MiniMax 还提供： MiniMax 插件为 `image_generate` 工具注册了 `image-01` 模型。它支持： -- 具有宽高比控制的**文生图生成**。 -- 具有宽高比控制的**图生图编辑**（主体参考）。 +- 可控制宽高比的**文生图生成**。 +- 可控制宽高比的**图生图编辑**（主体参考）。 - 每次请求最多 **9 张输出图像**。 - 每次编辑请求最多 **1 张参考图像**。 - 支持的宽高比：`1:1`、`16:9`、`4:3`、`3:2`、`2:3`、`3:4`、`9:16`、`21:9`。 @@ -56,37 +56,74 @@ MiniMax 插件为 `image_generate` 工具注册了 `image-01` 模型。它支持 } ``` -该插件对文本模型使用相同的 `MINIMAX_API_KEY` 或 OAuth 身份验证。如果 MiniMax 已经设置完成，则无需额外配置。 +该插件对文本模型使用相同的 `MINIMAX_API_KEY` 或 OAuth 认证。如果 MiniMax 已经设置完成，则无需额外配置。 -`minimax` 和 `minimax-portal` 都会使用相同的 `image-01` 模型注册 `image_generate`。API 密钥配置使用 `MINIMAX_API_KEY`；OAuth 配置则可以改用内置的 `minimax-portal` 身份验证路径。 +`minimax` 和 `minimax-portal` 都使用相同的 `image-01` 模型注册了 `image_generate`。 +基于 API 密钥的设置使用 `MINIMAX_API_KEY`；基于 OAuth 的设置则可以改用 +内置的 `minimax-portal` 认证路径。 -当新手引导或 API 密钥设置写入显式的 `models.providers.minimax` 条目时，OpenClaw 会实体化 `MiniMax-M2.7` 和 `MiniMax-M2.7-highspeed`，并设置 `input: ["text", "image"]`。 +当新手引导或 API 密钥设置写入显式的 `models.providers.minimax` +条目时，OpenClaw 会具体生成 `MiniMax-M2.7` 和 +`MiniMax-M2.7-highspeed`，并带有 `input: ["text", "image"]`。 -内置的 MiniMax 文本目录本身在显式提供商配置存在之前，仍保持仅文本元数据。图像理解则通过插件自有的 `MiniMax-VL-01` 媒体提供商单独暴露。 +内置的 MiniMax 文本目录本身仍然保持为仅文本元数据， +直到该显式提供商配置存在为止。图像理解则通过插件自有的 +`MiniMax-VL-01` 媒体提供商单独公开。 + +有关共享工具参数、提供商选择和故障切换行为，请参见 +[图像生成](/zh-CN/tools/image-generation)。 + +## 视频生成 + +内置的 `minimax` 插件还通过共享的 +`video_generate` 工具注册了视频生成功能。 + +- 默认视频模型：`minimax/MiniMax-Hailuo-2.3` +- 模式：文生视频和单图参考流程 +- 支持 `aspectRatio` 和 `resolution` + +要将 MiniMax 用作默认视频提供商： + +```json5 +{ + agents: { + defaults: { + videoGenerationModel: { + primary: "minimax/MiniMax-Hailuo-2.3", + }, + }, + }, +} +``` + +有关共享工具参数、提供商选择和故障切换行为，请参见 +[视频生成](/zh-CN/tools/video-generation)。 ## 图像理解 MiniMax 插件将图像理解与文本目录分开注册： -- `minimax`：默认图像模型为 `MiniMax-VL-01` -- `minimax-portal`：默认图像模型为 `MiniMax-VL-01` +- `minimax`：默认图像模型 `MiniMax-VL-01` +- `minimax-portal`：默认图像模型 `MiniMax-VL-01` -这就是为什么即使内置文本提供商目录仍显示仅文本的 M2.7 聊天引用，自动媒体路由仍然可以使用 MiniMax 图像理解。 +这就是为什么自动媒体路由即使在内置文本提供商目录仍显示为 +仅文本的 M2.7 聊天引用时，也可以使用 MiniMax 图像理解。 -## 网页搜索 +## Web 搜索 -MiniMax 插件还通过 MiniMax Coding Plan 搜索 API 注册了 `web_search`。 +MiniMax 插件还通过 MiniMax Coding Plan +搜索 API 注册了 `web_search`。 -- 提供商 id：`minimax` +- 提供商 ID：`minimax` - 结构化结果：标题、URL、摘要、相关查询 - 首选环境变量：`MINIMAX_CODE_PLAN_KEY` - 可接受的环境变量别名：`MINIMAX_CODING_API_KEY` -- 兼容性回退：当 `MINIMAX_API_KEY` 已经指向 coding-plan 令牌时使用它 +- 兼容性回退：当 `MINIMAX_API_KEY` 已指向 coding-plan 令牌时使用它 - 区域复用：`plugins.entries.minimax.config.webSearch.region`，然后是 `MINIMAX_API_HOST`，再然后是 MiniMax 提供商基础 URL -- 搜索始终停留在提供商 id `minimax` 上；OAuth 中国区/全球配置仍可通过 `models.providers.minimax-portal.baseUrl` 间接引导区域 +- 搜索始终保留在提供商 ID `minimax` 上；OAuth 中国区 / 全球设置仍可通过 `models.providers.minimax-portal.baseUrl` 间接引导区域 配置位于 `plugins.entries.minimax.config.webSearch.*` 下。 -请参阅 [MiniMax Search](/tools/minimax-search)。 +请参见 [MiniMax 搜索](/zh-CN/tools/minimax-search)。 ## 选择一种设置方式 @@ -94,11 +131,11 @@ MiniMax 插件还通过 MiniMax Coding Plan 搜索 API 注册了 `web_search`。 **最适合：** 通过 OAuth 快速设置 MiniMax Coding Plan，无需 API 密钥。 -使用显式的区域 OAuth 选项完成身份验证： +使用显式的区域 OAuth 选项进行认证： ```bash openclaw onboard --auth-choice minimax-global-oauth -# or +# 或 openclaw onboard --auth-choice minimax-cn-oauth ``` @@ -107,11 +144,11 @@ openclaw onboard --auth-choice minimax-cn-oauth - `minimax-global-oauth`：国际用户（`api.minimax.io`） - `minimax-cn-oauth`：中国用户（`api.minimaxi.com`） -详细信息请参阅 OpenClaw 仓库中 MiniMax 插件包的 README。 +详情请参见 OpenClaw 仓库中的 MiniMax 插件包 README。 ### MiniMax M2.7（API 密钥） -**最适合：** 使用与 Anthropic 兼容的 API 访问托管 MiniMax。 +**最适合：** 使用带有 Anthropic 兼容 API 的托管 MiniMax。 通过 CLI 配置： @@ -119,7 +156,7 @@ openclaw onboard --auth-choice minimax-cn-oauth ```bash openclaw onboard --auth-choice minimax-global-api -# or +# 或 openclaw onboard --auth-choice minimax-cn-api ``` @@ -163,12 +200,16 @@ openclaw onboard --auth-choice minimax-cn-api } ``` -在与 Anthropic 兼容的流式传输路径上，OpenClaw 现在默认会禁用 MiniMax thinking，除非你自己显式设置 `thinking`。MiniMax 的流式端点会以 OpenAI 风格的 delta 分块发出 `reasoning_content`，而不是原生的 Anthropic thinking 块，如果隐式保持启用，可能会将内部推理泄露到可见输出中。 +在 Anthropic 兼容的流式传输路径上，OpenClaw 现在默认禁用 MiniMax +的 thinking，除非你自己明确设置了 `thinking`。MiniMax 的 +流式端点会以 OpenAI 风格的 delta 分块发出 `reasoning_content`， +而不是原生的 Anthropic thinking 块，如果默认隐式启用， +可能会把内部推理泄露到可见输出中。 -### 将 MiniMax M2.7 作为回退模型（示例） +### 将 MiniMax M2.7 用作回退模型（示例） -**最适合：** 将你最强的最新一代模型作为主模型，并在失败时回退到 MiniMax M2.7。 -下面的示例使用 Opus 作为具体主模型；你可以替换为你偏好的最新一代主模型。 +**最适合：** 将你最强的最新一代模型保留为主模型，并在失败时回退到 MiniMax M2.7。 +下面的示例使用 Opus 作为具体主模型；请替换为你偏好的最新一代主模型。 ```json5 { @@ -190,14 +231,14 @@ openclaw onboard --auth-choice minimax-cn-api ## 通过 `openclaw configure` 配置 -使用交互式配置向导设置 MiniMax，而无需手动编辑 JSON： +使用交互式配置向导，无需编辑 JSON 即可设置 MiniMax： 1. 运行 `openclaw configure`。 2. 选择 **Model/auth**。 -3. 选择一个 **MiniMax** 身份验证选项。 +3. 选择一个 **MiniMax** 认证选项。 4. 在提示时选择你的默认模型。 -当前向导/CLI 中可用的 MiniMax 身份验证选项： +向导 / CLI 中当前可用的 MiniMax 认证选项： - `minimax-global-oauth` - `minimax-cn-oauth` @@ -206,49 +247,69 @@ openclaw onboard --auth-choice minimax-cn-api ## 配置选项 -- `models.providers.minimax.baseUrl`：优先使用 `https://api.minimax.io/anthropic`（兼容 Anthropic）；`https://api.minimax.io/v1` 可选，用于兼容 OpenAI 的负载。 -- `models.providers.minimax.api`：优先使用 `anthropic-messages`；`openai-completions` 可选，用于兼容 OpenAI 的负载。 +- `models.providers.minimax.baseUrl`：优先使用 `https://api.minimax.io/anthropic`（Anthropic 兼容）；`https://api.minimax.io/v1` 可选，用于 OpenAI 兼容载荷。 +- `models.providers.minimax.api`：优先使用 `anthropic-messages`；`openai-completions` 可选，用于 OpenAI 兼容载荷。 - `models.providers.minimax.apiKey`：MiniMax API 密钥（`MINIMAX_API_KEY`）。 - `models.providers.minimax.models`：定义 `id`、`name`、`reasoning`、`contextWindow`、`maxTokens`、`cost`。 - `agents.defaults.models`：为你想加入 allowlist 的模型设置别名。 -- `models.mode`：如果你想将 MiniMax 与内置提供商一起添加，请保持为 `merge`。 +- `models.mode`：如果你想在内置模型旁添加 MiniMax，请保持为 `merge`。 ## 说明 -- 模型引用遵循身份验证路径： - - API 密钥配置：`minimax/` - - OAuth 配置：`minimax-portal/` +- 模型引用遵循认证路径： + - API 密钥设置：`minimax/` + - OAuth 设置：`minimax-portal/` - 默认聊天模型：`MiniMax-M2.7` -- 可选聊天模型：`MiniMax-M2.7-highspeed` -- 在 `api: "anthropic-messages"` 上，OpenClaw 会注入 `thinking: { type: "disabled" }`，除非 thinking 已在参数/配置中被显式设置。 -- `/fast on` 或 `params.fastMode: true` 会在与 Anthropic 兼容的流式路径上，将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。 -- 新手引导和直接 API 密钥设置会为两个 M2.7 变体都写入带有 `input: ["text", "image"]` 的显式模型定义 -- 在显式的 MiniMax 提供商配置存在之前，内置提供商目录当前会将聊天引用显示为仅文本元数据 -- Coding Plan 使用量 API：`https://api.minimaxi.com/v1/api/openplatform/coding_plan/remains`（需要 coding plan 密钥）。 -- OpenClaw 会将 MiniMax coding-plan 使用量标准化为与其他提供商相同的 “% left” 显示。MiniMax 原始的 `usage_percent` / `usagePercent` 字段表示的是剩余额度，而不是已消耗额度，因此 OpenClaw 会将其反转。存在基于计数的字段时，会优先使用它们。当 API 返回 `model_remains` 时，OpenClaw 会优先选择聊天模型条目，在需要时从 `start_time` / `end_time` 推导窗口标签，并在计划标签中包含所选模型名称，以便更容易区分 coding-plan 窗口。 -- 使用量快照会将 `minimax`、`minimax-cn` 和 `minimax-portal` 视为同一个 MiniMax 配额面，并优先使用已存储的 MiniMax OAuth，再回退到 Coding Plan 密钥环境变量。 +- 备用聊天模型：`MiniMax-M2.7-highspeed` +- 在 `api: "anthropic-messages"` 下，OpenClaw 会注入 + `thinking: { type: "disabled" }`，除非 thinking 已在 + params / config 中被显式设置。 +- `/fast on` 或 `params.fastMode: true` 会在 Anthropic 兼容流式路径上 + 将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。 +- 新手引导和直接 API 密钥设置会为两个 M2.7 变体写入显式模型定义， + 并带有 `input: ["text", "image"]` +- 在显式 MiniMax 提供商配置存在之前， + 内置提供商目录当前会将聊天引用公开为仅文本元数据 +- Coding Plan 用量 API：`https://api.minimaxi.com/v1/api/openplatform/coding_plan/remains`（需要 coding plan 密钥）。 +- OpenClaw 会将 MiniMax coding-plan 用量标准化为与其他提供商相同的 + “% left” 显示。MiniMax 原始的 `usage_percent` / `usagePercent` + 字段表示的是剩余额度，而不是已消耗额度，因此 OpenClaw 会对其取反。 + 如果存在按次数统计的字段，则优先使用这些字段。当 API 返回 `model_remains` 时， + OpenClaw 会优先选择聊天模型条目，并在需要时从 + `start_time` / `end_time` 推导窗口标签，同时在计划标签中包含所选模型名称， + 以便更容易区分 coding-plan 窗口。 +- 用量快照会将 `minimax`、`minimax-cn` 和 `minimax-portal` 视为 + 同一个 MiniMax 配额面，并优先使用已存储的 MiniMax OAuth， + 然后才回退到 Coding Plan 密钥环境变量。 - 如果你需要精确的成本跟踪，请更新 `models.json` 中的定价值。 -- MiniMax Coding Plan 推荐链接（九折优惠）： [https://platform.minimax.io/subscribe/coding-plan?code=DbXJTRClnb&source=link](https://platform.minimax.io/subscribe/coding-plan?code=DbXJTRClnb&source=link) -- 有关提供商规则，请参阅 [/concepts/model-providers](/concepts/model-providers)。 -- 使用 `openclaw models list` 确认当前提供商 id，然后使用 `openclaw models set minimax/MiniMax-M2.7` 或 `openclaw models set minimax-portal/MiniMax-M2.7` 切换。 +- MiniMax Coding Plan 推荐链接（9 折优惠）：[https://platform.minimax.io/subscribe/coding-plan?code=DbXJTRClnb&source=link](https://platform.minimax.io/subscribe/coding-plan?code=DbXJTRClnb&source=link) +- 有关提供商规则，请参见 [/concepts/model-providers](/zh-CN/concepts/model-providers)。 +- 使用 `openclaw models list` 确认当前提供商 ID，然后通过 + `openclaw models set minimax/MiniMax-M2.7` 或 + `openclaw models set minimax-portal/MiniMax-M2.7` 切换。 ## 故障排除 ### “Unknown model: minimax/MiniMax-M2.7” -这通常意味着**MiniMax 提供商尚未配置**（没有匹配的提供商条目，也没有找到 MiniMax 身份验证配置文件/环境变量密钥）。此检测问题的修复已包含在 **2026.1.12** 中。可通过以下方式修复： +这通常意味着**MiniMax 提供商未配置**（没有匹配的 +provider 条目，也没有找到 MiniMax 认证配置文件 / 环境变量密钥）。 +针对这一检测问题的修复已包含在 **2026.1.12** 中。可通过以下方式修复： - 升级到 **2026.1.12**（或从源码 `main` 运行），然后重启 Gateway 网关。 -- 运行 `openclaw configure` 并选择一个 **MiniMax** 身份验证选项，或 -- 手动添加匹配的 `models.providers.minimax` 或 `models.providers.minimax-portal` 块，或 -- 设置 `MINIMAX_API_KEY`、`MINIMAX_OAUTH_TOKEN` 或 MiniMax 身份验证配置文件，以便注入匹配的提供商。 +- 运行 `openclaw configure` 并选择一个 **MiniMax** 认证选项，或 +- 手动添加匹配的 `models.providers.minimax` 或 + `models.providers.minimax-portal` 配置块，或 +- 设置 `MINIMAX_API_KEY`、`MINIMAX_OAUTH_TOKEN` 或 MiniMax 认证配置文件， + 以便注入匹配的提供商。 -请确保模型 id **区分大小写**： +请确保模型 ID **区分大小写**： - API 密钥路径：`minimax/MiniMax-M2.7` 或 `minimax/MiniMax-M2.7-highspeed` -- OAuth 路径：`minimax-portal/MiniMax-M2.7` 或 `minimax-portal/MiniMax-M2.7-highspeed` +- OAuth 路径：`minimax-portal/MiniMax-M2.7` 或 + `minimax-portal/MiniMax-M2.7-highspeed` -然后使用以下命令重新检查： +然后使用以下命令再次检查： ```bash openclaw models list diff --git a/docs/zh-CN/providers/openai.md b/docs/zh-CN/providers/openai.md index b7539c34d..9f192e1d1 100644 --- a/docs/zh-CN/providers/openai.md +++ b/docs/zh-CN/providers/openai.md @@ -1,30 +1,30 @@ --- read_when: - 你想在 OpenClaw 中使用 OpenAI 模型 - - 你想使用 Codex 订阅认证而不是 API 密钥 + - 你想使用 Codex 订阅凭证而不是 API 密钥 summary: 在 OpenClaw 中通过 API 密钥或 Codex 订阅使用 OpenAI title: OpenAI x-i18n: - generated_at: "2026-04-05T17:49:17Z" + generated_at: "2026-04-05T22:23:53Z" model: gpt-5.4 provider: openai - source_hash: b7da5413b8254015ee85f718356eb2dbcdc8d8f5c0de9f9a637242e6236540b4 + source_hash: 914836e35eb538d8ce758884fe4b0a6f5d0d0cfea483e1fe53f4a08709a16864 source_path: providers/openai.md workflow: 15 --- # OpenAI -OpenAI 为 GPT 模型提供开发者 API。Codex 支持使用 **ChatGPT 登录** 进行订阅访问，或使用 **API 密钥** 登录进行按量计费访问。Codex cloud 需要 ChatGPT 登录。 -OpenAI 明确支持在 OpenClaw 这类外部工具 / 工作流中使用订阅 OAuth。 +OpenAI 为 GPT 模型提供开发者 API。Codex 支持使用 **ChatGPT 登录** 进行订阅访问，或使用 **API 密钥** 登录进行按量计费访问。Codex cloud 需要使用 ChatGPT 登录。 +OpenAI 明确支持在 OpenClaw 这类外部工具/工作流中使用订阅 OAuth。 ## 默认交互风格 OpenClaw 可以为 `openai/*` 和 -`openai-codex/*` 运行添加一个小型 OpenAI 专属提示叠加层。默认情况下，该叠加层会让助手表现得更温暖、 -更具协作性、更简洁、更直接，并带有一点更丰富的情感表达， -同时不会替换 OpenClaw 的基础系统提示。这个友好的叠加层还 -允许在自然合适的情况下偶尔使用 emoji，同时保持整体 +`openai-codex/*` 运行添加一个小型的 OpenAI 专用提示词叠加层。默认情况下，该叠加层会让助手表现得更热情、 +更具协作性、更简洁、更直接，并带有稍强一些的情感表达， +同时不会替换 OpenClaw 的基础系统提示词。这个友好叠加层还 +允许在自然合适的时候偶尔使用 emoji，同时保持整体 输出简洁。 配置键： @@ -33,8 +33,8 @@ OpenClaw 可以为 `openai/*` 和 允许的值： -- `"friendly"`：默认；启用 OpenAI 专属叠加层。 -- `"off"`：禁用叠加层，仅使用 OpenClaw 基础提示。 +- `"friendly"`：默认；启用 OpenAI 专用叠加层。 +- `"off"`：禁用该叠加层，仅使用 OpenClaw 的基础提示词。 作用范围： @@ -42,8 +42,8 @@ OpenClaw 可以为 `openai/*` 和 - 适用于 `openai-codex/*` 模型。 - 不影响其他提供商。 -此行为默认开启。如果你希望它 -在未来本地配置变动后仍然保留，请显式保留 `"friendly"`： +此行为默认开启。如果你希望它在未来本地配置变动后 +仍然保留，请显式保留 `"friendly"`： ```json5 { @@ -59,9 +59,9 @@ OpenClaw 可以为 `openai/*` 和 } ``` -### 禁用 OpenAI 提示叠加层 +### 禁用 OpenAI 提示词叠加层 -如果你想使用未修改的 OpenClaw 基础提示，请将叠加层设置为 `"off"`： +如果你想使用未修改的 OpenClaw 基础提示词，请将叠加层设置为 `"off"`： ```json5 { @@ -77,7 +77,7 @@ OpenClaw 可以为 `openai/*` 和 } ``` -你也可以直接使用配置 CLI 进行设置： +你也可以直接通过配置 CLI 设置它： ```bash openclaw config set plugins.entries.openai.config.personality off @@ -86,13 +86,13 @@ openclaw config set plugins.entries.openai.config.personality off ## 选项 A：OpenAI API 密钥（OpenAI Platform） **最适合：** 直接 API 访问和按量计费。 -从 OpenAI 控制台获取你的 API 密钥。 +可从 OpenAI 控制台获取你的 API 密钥。 ### CLI 设置 ```bash openclaw onboard --auth-choice openai-api-key -# or non-interactive +# 或使用非交互模式 openclaw onboard --openai-api-key "$OPENAI_API_KEY" ``` @@ -105,27 +105,84 @@ openclaw onboard --openai-api-key "$OPENAI_API_KEY" } ``` -OpenAI 当前的 API 模型文档列出了 `gpt-5.4` 和 `gpt-5.4-pro`，用于直接 -OpenAI API 调用。OpenClaw 通过 `openai/*` Responses 路径转发这两者。 -OpenClaw 会有意隐藏过时的 `openai/gpt-5.3-codex-spark` 条目， -因为直接的 OpenAI API 调用会在真实流量中拒绝它。 +OpenAI 当前的 API 模型文档将 `gpt-5.4` 和 `gpt-5.4-pro` 列为可直接 +通过 OpenAI API 使用的模型。OpenClaw 会通过 `openai/*` Responses 路径转发这两个模型。 +OpenClaw 有意隐藏过时的 `openai/gpt-5.3-codex-spark` 条目， +因为直接 OpenAI API 调用在真实流量中会拒绝它。 OpenClaw **不会** 在直接 OpenAI -API 路径上暴露 `openai/gpt-5.3-codex-spark`。`pi-ai` 仍然为该模型内置了一个条目，但真实的 OpenAI API +API 路径上暴露 `openai/gpt-5.3-codex-spark`。`pi-ai` 仍然内置了该模型的一项条目，但实时 OpenAI API 请求目前会拒绝它。在 OpenClaw 中，Spark 被视为仅限 Codex。 +## 图像生成 + +内置的 `openai` 插件还会通过共享的 +`image_generate` 工具注册图像生成功能。 + +- 默认图像模型：`openai/gpt-image-1` +- 生成：每个请求最多 4 张图像 +- 编辑模式：已启用，最多 5 张参考图像 +- 支持 `size` +- 当前 OpenAI 专有限制：OpenClaw 目前不会将 `aspectRatio` 或 + `resolution` 覆盖项转发到 OpenAI Images API + +要将 OpenAI 用作默认图像提供商： + +```json5 +{ + agents: { + defaults: { + imageGenerationModel: { + primary: "openai/gpt-image-1", + }, + }, + }, +} +``` + +有关共享工具参数、 +提供商选择和故障切换行为，请参见 [图像生成](/zh-CN/tools/image-generation)。 + +## 视频生成 + +内置的 `openai` 插件还会通过共享的 +`video_generate` 工具注册视频生成功能。 + +- 默认视频模型：`openai/sora-2` +- 模式：文生视频、图生视频，以及单视频参考/编辑流程 +- 当前限制：1 张图像或 1 个视频参考输入 +- 当前 OpenAI 专有限制：OpenClaw 目前不会将 `aspectRatio` 或 + `resolution` 覆盖项转发到原生 OpenAI 视频 API + +要将 OpenAI 用作默认视频提供商： + +```json5 +{ + agents: { + defaults: { + videoGenerationModel: { + primary: "openai/sora-2", + }, + }, + }, +} +``` + +有关共享工具参数、 +提供商选择和故障切换行为，请参见 [视频生成](/zh-CN/tools/video-generation)。 + ## 选项 B：OpenAI Code（Codex）订阅 -**最适合：** 使用 ChatGPT / Codex 订阅访问，而不是 API 密钥。 +**最适合：** 使用 ChatGPT/Codex 订阅访问，而不是 API 密钥。 Codex cloud 需要 ChatGPT 登录，而 Codex CLI 支持使用 ChatGPT 或 API 密钥登录。 ### CLI 设置（Codex OAuth） ```bash -# Run Codex OAuth in the wizard +# 在向导中运行 Codex OAuth openclaw onboard --auth-choice openai-codex -# Or run OAuth directly +# 或直接运行 OAuth openclaw models auth login --provider openai-codex ``` @@ -137,28 +194,28 @@ openclaw models auth login --provider openai-codex } ``` -OpenAI 当前的 Codex 文档将 `gpt-5.4` 列为当前的 Codex 模型。OpenClaw -会将其映射为 `openai-codex/gpt-5.4`，用于 ChatGPT / Codex OAuth 访问。 +OpenAI 当前的 Codex 文档将 `gpt-5.4` 列为当前 Codex 模型。OpenClaw +会将其映射为 `openai-codex/gpt-5.4`，用于 ChatGPT/Codex OAuth 访问。 -如果新手引导复用了现有的 Codex CLI 登录，这些凭证会继续 -由 Codex CLI 管理。凭证过期时，OpenClaw 会优先重新读取外部 Codex 来源， -并且当提供商能够刷新它时，会将刷新的凭证 -写回 Codex 存储，而不是在单独的 OpenClaw 专用副本中接管它。 +如果新手引导复用了现有的 Codex CLI 登录，这些凭证将继续 +由 Codex CLI 管理。凭证过期时，OpenClaw 会优先重新读取外部 Codex 来源； +当该提供商可以刷新凭证时，会将刷新的凭证写回 +Codex 存储，而不是在 OpenClaw 中单独接管并保存一份副本。 -如果你的 Codex 账户有权使用 Codex Spark，OpenClaw 也支持： +如果你的 Codex 账户有 Codex Spark 权限，OpenClaw 还支持： - `openai-codex/gpt-5.3-codex-spark` -OpenClaw 将 Codex Spark 视为仅限 Codex。它不会公开直接的 +OpenClaw 将 Codex Spark 视为仅限 Codex。它不会暴露直接的 `openai/gpt-5.3-codex-spark` API 密钥路径。 当 `pi-ai` -发现 `openai-codex/gpt-5.3-codex-spark` 时，OpenClaw 也会保留它。请将其视为依赖授权且仍属实验性：Codex Spark 与 GPT-5.4 `/fast` 相互独立，是否可用取决于当前登录的 Codex / +发现 `openai-codex/gpt-5.3-codex-spark` 时，OpenClaw 也会保留它。请将其视为依赖权限且具有实验性质：Codex Spark 与 GPT-5.4 `/fast` 相互独立，其可用性取决于已登录的 Codex / ChatGPT 账户。 ### Codex 上下文窗口上限 -OpenClaw 将 Codex 模型元数据和运行时上下文上限视为两个独立的 +OpenClaw 将 Codex 模型元数据与运行时上下文上限视为两个独立的 值。 对于 `openai-codex/gpt-5.4`： @@ -166,10 +223,10 @@ OpenClaw 将 Codex 模型元数据和运行时上下文上限视为两个独立 - 原生 `contextWindow`：`1050000` - 默认运行时 `contextTokens` 上限：`272000` -这样既能保持模型元数据真实，又能保留在实践中延迟和质量表现更好的较小默认运行时 -窗口。 +这样既能保证模型元数据真实准确，又能保留更小的默认运行时 +窗口，因为它在实践中具有更好的延迟和质量表现。 -如果你想使用不同的有效上限，请设置 `models.providers..models[].contextTokens`： +如果你想使用不同的实际上限，请设置 `models.providers..models[].contextTokens`： ```json5 { @@ -188,50 +245,49 @@ OpenClaw 将 Codex 模型元数据和运行时上下文上限视为两个独立 } ``` -仅当你要声明或覆盖原生模型 -元数据时才使用 `contextWindow`。当你想限制运行时上下文预算时，请使用 `contextTokens`。 +仅当你在声明或覆盖原生模型 +元数据时使用 `contextWindow`。如果你想限制运行时上下文预算，请使用 `contextTokens`。 -### 传输默认值 +### 默认传输方式 OpenClaw 使用 `pi-ai` 进行模型流式传输。对于 `openai/*` 和 -`openai-codex/*`，默认传输方式为 `"auto"`（优先 WebSocket，然后回退到 SSE）。 +`openai-codex/*`，默认传输方式为 `"auto"`（优先 WebSocket，其次 SSE +回退）。 在 `"auto"` 模式下，OpenClaw 还会在回退到 SSE 之前， -对一次早期且可重试的 WebSocket 故障进行重试。 -而强制 `"websocket"` 模式仍会直接暴露传输错误， -而不是通过回退隐藏它们。 +对一次发生得较早且可重试的 WebSocket 失败进行重试。 +强制 `"websocket"` 模式仍会直接暴露传输错误，而不是通过回退将其隐藏。 -在 `"auto"` 模式下，如果连接或回合早期发生 WebSocket 故障，OpenClaw 会将 -该会话的 WebSocket 路径标记为降级状态，持续约 60 秒，并在冷却期间通过 SSE 发送 -后续回合，而不是在不同 -传输之间来回抖动。 +在 `"auto"` 模式下，发生连接失败或首轮早期 WebSocket 失败后，OpenClaw 会将 +该会话的 WebSocket 路径标记为降级状态，持续约 60 秒，并在冷却期间 +通过 SSE 发送后续轮次，而不是在多种传输方式之间反复切换。 对于原生 OpenAI 系列端点（`openai/*`、`openai-codex/*` 和 Azure -OpenAI Responses），OpenClaw 还会将稳定的会话和回合身份状态附加到请求中， -以便重试、重连和 SSE 回退都能与同一 -对话身份保持一致。在原生 OpenAI 系列路由上，这包括稳定的 -会话 / 回合请求身份头，以及匹配的传输元数据。 +OpenAI Responses），OpenClaw 还会将稳定的会话和轮次身份状态附加到 +请求中，以便重试、重连和 SSE 回退都能与同一 +会话身份保持一致。在原生 OpenAI 系列路由中，这包括稳定的 +会话/轮次请求身份标头以及匹配的传输元数据。 -在这些数据到达会话 / 状态界面之前，OpenClaw 还会统一不同传输变体下的 OpenAI 用量计数器。原生 OpenAI / Codex Responses 流量 -可能会将用量报告为 `input_tokens` / `output_tokens` 或 -`prompt_tokens` / `completion_tokens`；对于 `/status`、`/usage` 和会话日志，OpenClaw 将它们视为相同的输入 -和输出计数器。当原生 +在这些信息到达会话/状态界面之前，OpenClaw 还会统一不同传输方式下的 OpenAI 使用量计数器。 +原生 OpenAI/Codex Responses 流量可能将使用量报告为 `input_tokens` / `output_tokens`，也可能是 +`prompt_tokens` / `completion_tokens`；OpenClaw 会将它们视为相同的输入 +和输出计数器，用于 `/status`、`/usage` 和会话日志。当原生 WebSocket 流量省略 `total_tokens`（或报告为 `0`）时，OpenClaw 会回退到 -归一化后的输入 + 输出总数，以便会话 / 状态显示保持有值。 +规范化后的输入 + 输出总数，以便会话/状态显示保持有值。 你可以设置 `agents.defaults.models..params.transport`： - `"sse"`：强制使用 SSE - `"websocket"`：强制使用 WebSocket -- `"auto"`：先尝试 WebSocket，再回退到 SSE +- `"auto"`：先尝试 WebSocket，然后回退到 SSE -对于 `openai/*`（Responses API），当使用 -WebSocket 传输时，OpenClaw 还会默认启用 WebSocket 预热（`openaiWsWarmup: true`）。 +对于 `openai/*`（Responses API），OpenClaw 在使用 +WebSocket 传输时还会默认启用 WebSocket 预热（`openaiWsWarmup: true`）。 相关 OpenAI 文档： -- [Realtime API with WebSocket](https://platform.openai.com/docs/guides/realtime-websocket) -- [Streaming API responses (SSE)](https://platform.openai.com/docs/guides/streaming-responses) +- [使用 WebSocket 的 Realtime API](https://platform.openai.com/docs/guides/realtime-websocket) +- [流式 API 响应（SSE）](https://platform.openai.com/docs/guides/streaming-responses) ```json5 { @@ -252,8 +308,8 @@ WebSocket 传输时，OpenClaw 还会默认启用 WebSocket 预热（`openaiWsWa ### OpenAI WebSocket 预热 -OpenAI 文档将预热描述为可选项。对于 -使用 WebSocket 传输的 `openai/*`，OpenClaw 默认启用它，以减少首回合延迟。 +OpenAI 文档将预热描述为可选项。OpenClaw 默认会为 +`openai/*` 启用它，以减少使用 WebSocket 传输时的首轮延迟。 ### 禁用预热 @@ -293,9 +349,9 @@ OpenAI 文档将预热描述为可选项。对于 ### OpenAI 和 Codex 优先级处理 -OpenAI 的 API 通过 `service_tier=priority` 提供优先级处理。在 +OpenAI 的 API 通过 `service_tier=priority` 提供优先级处理能力。在 OpenClaw 中，设置 `agents.defaults.models["/"].params.serviceTier` -即可在原生 OpenAI / Codex Responses 端点上传递该字段。 +即可在原生 OpenAI/Codex Responses 端点上传递该字段。 ```json5 { @@ -318,31 +374,30 @@ OpenClaw 中，设置 `agents.defaults.models["/"].params.servi } ``` -支持的值包括 `auto`、`default`、`flex` 和 `priority`。 +支持的值有 `auto`、`default`、`flex` 和 `priority`。 -当这些模型指向原生 OpenAI / Codex 端点时， -OpenClaw 会将 `params.serviceTier` 转发到直接的 `openai/*` Responses -请求和 `openai-codex/*` Codex Responses 请求。 +当这些模型指向原生 OpenAI/Codex 端点时，OpenClaw 会将 `params.serviceTier` 转发到直接的 `openai/*` Responses +请求以及 `openai-codex/*` Codex Responses 请求。 重要行为： - 直接 `openai/*` 必须指向 `api.openai.com` - `openai-codex/*` 必须指向 `chatgpt.com/backend-api` -- 如果你通过其他 base URL 或代理来路由任一提供商，OpenClaw 会保持 `service_tier` 原样不动 +- 如果你通过其他 base URL 或代理路由任一提供商，OpenClaw 会保留 `service_tier` 不变 ### OpenAI 快速模式 OpenClaw 为 `openai/*` 和 -`openai-codex/*` 会话都提供了共享的快速模式开关： +`openai-codex/*` 会话提供统一的快速模式开关： -- 聊天 / UI：`/fast status|on|off` +- 聊天/UI：`/fast status|on|off` - 配置：`agents.defaults.models["/"].params.fastMode` 启用快速模式后，OpenClaw 会将其映射为 OpenAI 优先级处理： -- 对 `api.openai.com` 的直接 `openai/*` Responses 调用会发送 `service_tier = "priority"` -- 对 `chatgpt.com/backend-api` 的 `openai-codex/*` Responses 调用也会发送 `service_tier = "priority"` -- 现有负载中的 `service_tier` 值会被保留 +- 发往 `api.openai.com` 的直接 `openai/*` Responses 调用会发送 `service_tier = "priority"` +- 发往 `chatgpt.com/backend-api` 的 `openai-codex/*` Responses 调用也会发送 `service_tier = "priority"` +- 会保留现有负载中的 `service_tier` 值 - 快速模式不会重写 `reasoning` 或 `text.verbosity` 示例： @@ -368,48 +423,48 @@ OpenClaw 为 `openai/*` 和 } ``` -会话覆盖优先于配置。在 Sessions UI -中清除会话覆盖后，会话会恢复为配置的默认值。 +会话覆盖优先于配置。在 Sessions UI 中清除会话覆盖后， +该会话会恢复为配置中的默认值。 -### 原生 OpenAI 与 OpenAI-compatible 路由 +### 原生 OpenAI 与 OpenAI 兼容路由 OpenClaw 对直接 OpenAI、Codex 和 Azure OpenAI 端点的处理方式 -不同于通用的 OpenAI-compatible `/v1` 代理： +与通用 OpenAI 兼容 `/v1` 代理不同： - 原生 `openai/*`、`openai-codex/*` 和 Azure OpenAI 路由会保留 - `reasoning: { effort: "none" }`，当你显式禁用推理时不会改写 -- 原生 OpenAI 系列路由默认将工具 schema 设为严格模式 -- 隐藏的 OpenClaw 归因头（`originator`、`version` 和 + `reasoning: { effort: "none" }`，当你显式禁用推理时不会改写它 +- 原生 OpenAI 系列路由默认将工具 schema 设为 strict 模式 +- 隐藏的 OpenClaw 归因标头（`originator`、`version` 和 `User-Agent`）只会附加到已验证的原生 OpenAI 主机 （`api.openai.com`）和原生 Codex 主机（`chatgpt.com/backend-api`）上 -- 原生 OpenAI / Codex 路由会保留 OpenAI 专属的请求整形，例如 +- 原生 OpenAI/Codex 路由会保留 OpenAI 专属的请求整形，例如 `service_tier`、Responses `store`、OpenAI 推理兼容负载，以及 prompt-cache 提示 -- 代理风格的 OpenAI-compatible 路由会保留更宽松的兼容行为，并且 - 不会强制严格工具 schema、原生专属请求整形或隐藏的 - OpenAI / Codex 归因头 +- 代理风格的 OpenAI 兼容路由会保留更宽松的兼容行为，并且 + 不会强制 strict 工具 schema、原生专属请求整形或隐藏的 + OpenAI/Codex 归因标头 -Azure OpenAI 在传输和兼容行为上仍属于原生路由类别， -但不会收到隐藏的 OpenAI / Codex 归因头。 +Azure OpenAI 在传输和兼容性 +行为方面仍属于原生路由类别，但它不会接收隐藏的 OpenAI/Codex 归因标头。 -这样可以保留当前原生 OpenAI Responses 的行为，而不会把较旧的 -OpenAI-compatible 适配逻辑强加到第三方 `/v1` 后端上。 +这样可以保留当前原生 OpenAI Responses 的行为，同时不会将旧式 +OpenAI 兼容 shim 强加给第三方 `/v1` 后端。 ### OpenAI Responses 服务端压缩 -对于直接 OpenAI Responses 模型（`openai/*` 使用 `api: "openai-responses"` 且 -`baseUrl` 位于 `api.openai.com`），OpenClaw 现在会自动启用 OpenAI 服务端 +对于直接 OpenAI Responses 模型（使用 +`api: "openai-responses"` 且 `baseUrl` 指向 `api.openai.com` 的 `openai/*`），OpenClaw 现在会自动启用 OpenAI 服务端 压缩负载提示： - 强制 `store: true`（除非模型兼容性设置 `supportsStore: false`） - 注入 `context_management: [{ type: "compaction", compact_threshold: ... }]` -默认情况下，`compact_threshold` 为模型 `contextWindow` 的 `70%`（如果不可用则为 `80000`）。 +默认情况下，`compact_threshold` 为模型 `contextWindow` 的 `70%`（若不可用则为 `80000`）。 ### 显式启用服务端压缩 -当你希望在兼容的 -Responses 模型（例如 Azure OpenAI Responses）上强制注入 `context_management` 时，请使用此项： +当你想在兼容的 +Responses 模型上强制注入 `context_management` 时使用此项（例如 Azure OpenAI Responses）： ```json5 { @@ -464,11 +519,11 @@ Responses 模型（例如 Azure OpenAI Responses）上强制注入 `context_mana } ``` -`responsesServerCompaction` 仅控制 `context_management` 注入。 +`responsesServerCompaction` 仅控制 `context_management` 的注入。 直接 OpenAI Responses 模型仍会强制 `store: true`，除非兼容性设置 `supportsStore: false`。 ## 说明 - 模型引用始终使用 `provider/model`（参见 [/concepts/models](/zh-CN/concepts/models)）。 -- 认证细节和复用规则见 [/concepts/oauth](/zh-CN/concepts/oauth)。 +- 凭证详情和复用规则见 [/concepts/oauth](/zh-CN/concepts/oauth)。 diff --git a/docs/zh-CN/providers/qwen.md b/docs/zh-CN/providers/qwen.md index 625ae2bd5..9ae611289 100644 --- a/docs/zh-CN/providers/qwen.md +++ b/docs/zh-CN/providers/qwen.md @@ -1,44 +1,40 @@ --- +read_when: + - 你想在 OpenClaw 中使用 Qwen + - 你之前使用过 Qwen OAuth +summary: 通过 OpenClaw 内置的 qwen 提供商使用 Qwen Cloud +title: Qwen x-i18n: - generated_at: "2026-04-05T17:48:53Z" + generated_at: "2026-04-05T22:23:01Z" model: gpt-5.4 provider: openai - source_hash: 813c4401d02b0a8a2708d30d6c31e4d375036244141d9e55458479f24723e0a5 + source_hash: c1e1022a368513fd09474a2c2b8394911787a6bc5e325868da590a3d32446a34 source_path: providers/qwen.md workflow: 15 --- -summary: "通过 OpenClaw 的内置 qwen 提供商使用 Qwen" -read_when: - -- 你想在 OpenClaw 中使用 Qwen -- 你之前使用过 Qwen OAuth - title: "Qwen" - ---- - # Qwen -**Qwen OAuth 已被移除。** 使用 `portal.qwen.ai` 端点的免费层 OAuth 集成 +**Qwen OAuth 已被移除。** 曾使用 `portal.qwen.ai` 端点的免费层 OAuth 集成 （`qwen-portal`）现已不可用。 -背景请参见 [Issue #49557](https://github.com/openclaw/openclaw/issues/49557)。 +背景信息请参阅 [Issue #49557](https://github.com/openclaw/openclaw/issues/49557)。 ## 推荐：Qwen Cloud -OpenClaw 现在将 Qwen 视为一个一等内置提供商，其规范 ID -为 `qwen`。该内置提供商面向 Qwen Cloud / Alibaba DashScope 和 -Coding Plan 端点，并保留旧版 `modelstudio` ID 作为兼容性别名。 +OpenClaw 现在将 Qwen 视为一等内置提供商，规范 id 为 +`qwen`。该内置提供商面向 Qwen Cloud / Alibaba DashScope 和 +Coding Plan 端点，并保留旧版 `modelstudio` id 作为兼容性别名。 - 提供商：`qwen` - 首选环境变量：`QWEN_API_KEY` - 为兼容性也接受：`MODELSTUDIO_API_KEY`、`DASHSCOPE_API_KEY` - API 风格：兼容 OpenAI -如果你想使用 `qwen3.6-plus`，请优先选择**标准版（按量付费）**端点。 +如果你想使用 `qwen3.6-plus`，建议优先选择**标准版（按量付费）**端点。 Coding Plan 支持可能会落后于公开目录。 ```bash @@ -55,9 +51,9 @@ openclaw onboard --auth-choice qwen-standard-api-key openclaw onboard --auth-choice qwen-standard-api-key-cn ``` -旧版 `modelstudio-*` auth-choice ID 和 `modelstudio/...` 模型引用仍然 -可作为兼容性别名使用，但新的设置流程应优先使用规范的 -`qwen-*` auth-choice ID 和 `qwen/...` 模型引用。 +旧版 `modelstudio-*` auth-choice id 和 `modelstudio/...` 模型引用仍然可用， +作为兼容性别名，但新的设置流程应优先使用规范的 +`qwen-*` auth-choice id 和 `qwen/...` 模型引用。 完成新手引导后，设置默认模型： @@ -74,42 +70,43 @@ openclaw onboard --auth-choice qwen-standard-api-key-cn ## 能力规划 `qwen` 扩展正被定位为完整 Qwen -Cloud 能力面的厂商归属位置，而不仅仅是编码 / 文本模型。 +Cloud 能力面的厂商归属位置，而不仅仅是编码/文本模型。 -- 文本 / 聊天模型：现已内置 -- 工具调用、结构化输出、思考：继承自兼容 OpenAI 的传输层 +- 文本/聊天模型：现已内置 +- 工具调用、结构化输出、思维链：继承自兼容 OpenAI 的传输层 - 图像生成：计划在提供商插件层实现 -- 图像 / 视频理解：现已在标准版端点内置 -- 语音 / 音频：计划在提供商插件层实现 -- Memory 嵌入 / 重排序：计划通过 embedding 适配器表面实现 +- 图像/视频理解：现已在标准版端点内置 +- 语音/音频：计划在提供商插件层实现 +- Memory embeddings/reranking：计划通过 embedding 适配器能力面提供 - 视频生成：现已通过共享视频生成能力内置 ## 多模态附加功能 -`qwen` 扩展现在还公开以下能力： +`qwen` 扩展现在还公开了： -- 通过 `qwen-vl-max-latest` 进行视频理解 -- 通过以下模型进行 Wan 视频生成： +- 通过 `qwen-vl-max-latest` 提供视频理解 +- 通过以下模型提供 Wan 视频生成： - `wan2.6-t2v`（默认） - `wan2.6-i2v` - `wan2.6-r2v` - `wan2.6-r2v-flash` - `wan2.7-r2v` -这些多模态表面使用的是**标准版** DashScope 端点，而不是 +这些多模态能力面使用的是**标准版** DashScope 端点，而不是 Coding Plan 端点。 -- 全球 / 国际版标准版基础 URL：`https://dashscope-intl.aliyuncs.com/compatible-mode/v1` -- 中国区标准版基础 URL：`https://dashscope.aliyuncs.com/compatible-mode/v1` +- 全局/国际版标准版 base URL：`https://dashscope-intl.aliyuncs.com/compatible-mode/v1` +- 中国区标准版 base URL：`https://dashscope.aliyuncs.com/compatible-mode/v1` -对于视频生成，OpenClaw 会在提交任务前，将已配置的 Qwen 区域映射到匹配的 -DashScope AIGC 主机： +对于视频生成，OpenClaw 会先将已配置的 Qwen 区域映射到匹配的 +DashScope AIGC 主机，然后再提交任务： -- 全球 / 国际版：`https://dashscope-intl.aliyuncs.com` +- 全局/国际版：`https://dashscope-intl.aliyuncs.com` - 中国区：`https://dashscope.aliyuncs.com` -这意味着，普通的 `models.providers.qwen.baseUrl` 即使指向 -Coding Plan 或标准版 Qwen 主机之一，也仍会让视频生成使用正确的区域性 DashScope 视频端点。 +这意味着，即使普通的 `models.providers.qwen.baseUrl` 指向 +Coding Plan 或标准版 Qwen 主机之一， +视频生成仍会使用正确地区的 DashScope 视频端点。 对于视频生成，请显式设置默认模型： @@ -123,14 +120,18 @@ Coding Plan 或标准版 Qwen 主机之一，也仍会让视频生成使用正 } ``` -当前内置 Qwen 视频生成限制： +当前内置的 Qwen 视频生成限制： - 每个请求最多 **1** 个输出视频 - 最多 **1** 张输入图像 - 最多 **4** 个输入视频 -- 最长 **10 秒** 时长 +- 时长最长 **10 秒** - 支持 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` -- 参考图像 / 视频模式当前要求使用**远程 http(s) URL**。本地 - 文件路径会被预先拒绝，因为 DashScope 视频端点不接受这些参考内容的本地缓冲区上传。 +- 参考图像/视频模式目前要求使用**远程 http(s) URL**。本地文件路径会被预先拒绝， + 因为 DashScope 视频端点不接受为这些参考上传本地缓冲区。 -端点级详细信息和兼容性说明，请参见 [Qwen / Model Studio](/zh-CN/providers/qwen_modelstudio)。 +有关共享工具参数、提供商选择和故障切换行为，请参阅 +[视频生成](/zh-CN/tools/video-generation)。 + +有关端点级细节和兼容性说明，请参阅 +[Qwen / Model Studio](/zh-CN/providers/qwen_modelstudio)。 diff --git a/docs/zh-CN/providers/qwen_modelstudio.md b/docs/zh-CN/providers/qwen_modelstudio.md index eb8ba7b51..61660bce1 100644 --- a/docs/zh-CN/providers/qwen_modelstudio.md +++ b/docs/zh-CN/providers/qwen_modelstudio.md @@ -1,37 +1,35 @@ --- +read_when: + - 你想了解 Qwen Cloud / Alibaba DashScope 的端点级详细信息 + - 你需要了解 qwen 提供商的环境变量兼容方案 + - 你想使用 Standard（按量付费）或 Coding Plan 端点 +summary: 内置 qwen 提供商及其旧版 modelstudio 兼容层的端点详情 +title: Qwen / Model Studio x-i18n: - generated_at: "2026-04-05T10:06:54Z" + generated_at: "2026-04-05T22:23:11Z" model: gpt-5.4 provider: openai - source_hash: 1066a1d0acebe4ae3500d18c21f7de07f43b9766daf3d13b098936734e9e7a2b + source_hash: f21bf55e7acf51131027a1c1faf5fa85a00757ee40995ea4e1d24935cd310e24 source_path: providers/qwen_modelstudio.md workflow: 15 --- -title: "Qwen / Model Studio" -summary: "内置 qwen 提供商及其旧版 modelstudio 兼容接口的端点细节" -read_when: - -- 你想了解 Qwen Cloud / Alibaba DashScope 的端点级细节 -- 你需要了解 qwen 提供商的环境变量兼容性方案 -- 你想使用 Standard（按量付费）或 Coding Plan 端点 - ---- - # Qwen / Model Studio（Alibaba Cloud） -本页记录了 OpenClaw 内置 `qwen` 提供商背后的端点映射。该提供商会继续让 `modelstudio` 提供商 id、auth-choice id 和模型引用作为兼容性别名正常工作，同时将 `qwen` 作为规范接口。 +本页说明 OpenClaw 内置 `qwen` +提供商背后的端点映射。该提供商会继续让 `modelstudio` 提供商 id、auth-choice id 和 +模型引用作为兼容别名正常工作，同时将 `qwen` 作为规范表面。 -如果你需要 **`qwen3.6-plus`**，请优先选择 **Standard（按量付费）**。Coding -Plan 的可用性可能会落后于公开的 Model Studio 目录，而且在某个模型出现在你的套餐支持模型列表之前，Coding -Plan API 可能会拒绝该模型。 +如果你需要 **`qwen3.6-plus`**，优先选择 **Standard（按量付费）**。Coding +Plan 的可用性可能落后于公开的 Model Studio 目录，并且在某个模型出现在你的套餐支持模型列表之前， +Coding Plan API 可能会拒绝该模型。 - 提供商：`qwen`（旧版别名：`modelstudio`） -- 鉴权：`QWEN_API_KEY` +- 认证：`QWEN_API_KEY` - 也接受：`MODELSTUDIO_API_KEY`、`DASHSCOPE_API_KEY` - API：兼容 OpenAI @@ -43,21 +41,22 @@ Plan API 可能会拒绝该模型。 # 中国端点 openclaw onboard --auth-choice qwen-standard-api-key-cn -# Global/Intl 端点 +# 全球/国际端点 openclaw onboard --auth-choice qwen-standard-api-key ``` -### Coding Plan（订阅） +### Coding Plan（订阅制） ```bash # 中国端点 openclaw onboard --auth-choice qwen-api-key-cn -# Global/Intl 端点 +# 全球/国际端点 openclaw onboard --auth-choice qwen-api-key ``` -旧版 `modelstudio-*` auth-choice id 仍可作为兼容性别名使用，但规范的新手引导 id 是上面显示的 `qwen-*` 选项。 +旧版 `modelstudio-*` auth-choice id 仍可作为兼容别名使用，但 +规范的新手引导 id 是上面显示的 `qwen-*` 选项。 完成新手引导后，设置默认模型： @@ -76,14 +75,19 @@ openclaw onboard --auth-choice qwen-api-key | 套餐 | 区域 | Auth choice | 端点 | | -------------------------- | ------ | -------------------------- | ------------------------------------------------ | | Standard（按量付费） | 中国 | `qwen-standard-api-key-cn` | `dashscope.aliyuncs.com/compatible-mode/v1` | -| Standard（按量付费） | Global | `qwen-standard-api-key` | `dashscope-intl.aliyuncs.com/compatible-mode/v1` | -| Coding Plan（订阅） | 中国 | `qwen-api-key-cn` | `coding.dashscope.aliyuncs.com/v1` | -| Coding Plan（订阅） | Global | `qwen-api-key` | `coding-intl.dashscope.aliyuncs.com/v1` | +| Standard（按量付费） | 全球 | `qwen-standard-api-key` | `dashscope-intl.aliyuncs.com/compatible-mode/v1` | +| Coding Plan（订阅制） | 中国 | `qwen-api-key-cn` | `coding.dashscope.aliyuncs.com/v1` | +| Coding Plan（订阅制） | 全球 | `qwen-api-key` | `coding-intl.dashscope.aliyuncs.com/v1` | -该提供商会根据你的 auth choice 自动选择端点。规范选项使用 `qwen-*` 系列；`modelstudio-*` 仅保留为兼容用途。 -你可以在配置中使用自定义 `baseUrl` 进行覆盖。 +该提供商会根据你的 auth choice 自动选择端点。规范 +选项使用 `qwen-*` 系列；`modelstudio-*` 仅保留用于兼容。 +你可以 +在配置中使用自定义 `baseUrl` 进行覆盖。 -原生 Model Studio 端点会在共享 `openai-completions` 传输上声明流式传输使用兼容性。OpenClaw 现在基于端点能力来判断这一点，因此，面向相同原生主机的 DashScope 兼容自定义提供商 id 也会继承相同的流式传输使用行为，而不再要求必须使用内置 `qwen` 提供商 id。 +原生 Model Studio 端点在共享的 `openai-completions` 传输协议上声明支持流式使用兼容性。 +OpenClaw 现在会根据端点能力来判断这一点，因此，目标指向相同原生主机的 DashScope 兼容自定义提供商 id +也会继承相同的流式使用行为，而不再 +必须特定使用内置 `qwen` 提供商 id。 ## 获取你的 API 密钥 @@ -97,18 +101,20 @@ OpenClaw 当前内置了以下 Qwen 目录： | 模型引用 | 输入 | 上下文 | 说明 | | --------------------------- | ----------- | --------- | -------------------------------------------------- | | `qwen/qwen3.5-plus` | text, image | 1,000,000 | 默认模型 | -| `qwen/qwen3.6-plus` | text, image | 1,000,000 | 需要此模型时优先选择 Standard 端点 | +| `qwen/qwen3.6-plus` | text, image | 1,000,000 | 需要此模型时优先使用 Standard 端点 | | `qwen/qwen3-max-2026-01-23` | text | 262,144 | Qwen Max 系列 | -| `qwen/qwen3-coder-next` | text | 262,144 | Coding | -| `qwen/qwen3-coder-plus` | text | 1,000,000 | Coding | +| `qwen/qwen3-coder-next` | text | 262,144 | 编码 | +| `qwen/qwen3-coder-plus` | text | 1,000,000 | 编码 | | `qwen/MiniMax-M2.5` | text | 1,000,000 | 已启用推理 | | `qwen/glm-5` | text | 202,752 | GLM | | `qwen/glm-4.7` | text | 202,752 | GLM | -| `qwen/kimi-k2.5` | text, image | 262,144 | 通过 Alibaba 提供的 Moonshot AI | +| `qwen/kimi-k2.5` | text, image | 262,144 | Moonshot AI，经由 Alibaba | -即使某个模型出现在内置目录中，其可用性仍可能因端点和计费套餐而异。 +即使某个模型 +出现在内置目录中，其可用性仍可能因端点和计费套餐而异。 -原生流式传输使用兼容性同时适用于 Coding Plan 主机和 Standard DashScope 兼容主机： +原生流式传输使用兼容性同时适用于 Coding Plan 主机和 +Standard DashScope 兼容主机： - `https://coding.dashscope.aliyuncs.com/v1` - `https://coding-intl.dashscope.aliyuncs.com/v1` @@ -117,15 +123,48 @@ OpenClaw 当前内置了以下 Qwen 目录： ## Qwen 3.6 Plus 可用性 -`qwen3.6-plus` 可用于 Standard（按量付费）Model Studio 端点： +`qwen3.6-plus` 可用于 Standard（按量付费）Model Studio +端点： - 中国：`dashscope.aliyuncs.com/compatible-mode/v1` -- Global：`dashscope-intl.aliyuncs.com/compatible-mode/v1` +- 全球：`dashscope-intl.aliyuncs.com/compatible-mode/v1` -如果 Coding Plan 端点对 `qwen3.6-plus` 返回“unsupported model”错误，请切换到 Standard（按量付费），而不是使用 Coding Plan 端点/密钥组合。 +如果 Coding Plan 端点对 +`qwen3.6-plus` 返回“unsupported model”错误，请切换到 Standard（按量付费），而不是继续使用 Coding Plan +端点/密钥组合。 ## 环境说明 如果 Gateway 网关以守护进程（launchd/systemd）方式运行，请确保 -`QWEN_API_KEY` 可供该进程使用（例如在 -`~/.openclaw/.env` 中，或通过 `env.shellEnv`）。 +该进程可以访问 `QWEN_API_KEY`（例如放在 +`~/.openclaw/.env` 中，或通过 `env.shellEnv` 提供）。 + +## Wan 视频生成 + +Standard DashScope 表面也为内置 Wan 视频生成 +提供商提供支持。 + +你可以通过任一前缀来引用同一个 Wan 系列： + +- 规范 Qwen 引用： + - `qwen/wan2.6-t2v` + - `qwen/wan2.6-i2v` + - `qwen/wan2.6-r2v` + - `qwen/wan2.6-r2v-flash` + - `qwen/wan2.7-r2v` +- 直接 Alibaba 引用： + - `alibaba/wan2.6-t2v` + - `alibaba/wan2.6-i2v` + - `alibaba/wan2.6-r2v` + - `alibaba/wan2.6-r2v-flash` + - `alibaba/wan2.7-r2v` + +目前所有 Wan 参考模式都要求图像或 +视频参考使用 **远程 http(s) URL**。本地文件路径会在上传前被拒绝，因为 +DashScope 视频端点在这些模式下不接受本地缓冲区参考资源。 + +## 相关内容 + +- [Qwen](/zh-CN/providers/qwen) +- [Alibaba Model Studio](/providers/alibaba) +- [视频生成](/zh-CN/tools/video-generation) diff --git a/docs/zh-CN/providers/together.md b/docs/zh-CN/providers/together.md index 7f3a54d89..5197ea9c0 100644 --- a/docs/zh-CN/providers/together.md +++ b/docs/zh-CN/providers/together.md @@ -1,30 +1,30 @@ --- read_when: - - 你想在 OpenClaw 中使用 Together AI - - 你需要 API 密钥环境变量或 CLI 认证选项 -summary: Together AI 设置（认证 + 模型选择） + - 你想将 Together AI 与 OpenClaw 搭配使用 + - 你需要 API 密钥环境变量或 CLI 凭证选项 +summary: Together AI 设置（凭证 + 模型选择） title: Together AI x-i18n: - generated_at: "2026-04-05T10:06:56Z" + generated_at: "2026-04-05T22:23:05Z" model: gpt-5.4 provider: openai - source_hash: 22aacbaadf860ce8245bba921dcc5ede9da8fd6fa1bc3cc912551aecc1ba0d71 + source_hash: b68fdc15bfcac8d59e3e0c06a39162abd48d9d41a9a64a0ac622cd8e3f80a595 source_path: providers/together.md workflow: 15 --- # Together AI -[Together AI](https://together.ai) 通过统一 API 提供对领先开源模型的访问，包括 Llama、DeepSeek、Kimi 等。 +[Together AI](https://together.ai) 通过统一的 API 提供对 Llama、DeepSeek、Kimi 等领先开源模型的访问。 - 提供商：`together` -- 认证：`TOGETHER_API_KEY` -- API：兼容 OpenAI +- 凭证：`TOGETHER_API_KEY` +- API：与 OpenAI 兼容 - 基础 URL：`https://api.together.xyz/v1` ## 快速开始 -1. 设置 API 密钥（推荐：为 Gateway 网关存储它）： +1. 设置 API 密钥（推荐：为 Gateway 网关 存储它）： ```bash openclaw onboard --auth-choice together-api-key @@ -55,23 +55,47 @@ openclaw onboard --non-interactive \ ## 环境说明 -如果 Gateway 网关以守护进程方式运行（launchd/systemd），请确保 `TOGETHER_API_KEY` +如果 Gateway 网关 以守护进程（launchd/systemd）方式运行，请确保 `TOGETHER_API_KEY` 对该进程可用（例如，在 `~/.openclaw/.env` 中或通过 -`env.shellEnv` 提供）。 +`env.shellEnv`）。 ## 内置目录 -OpenClaw 当前内置了以下 Together 目录： +OpenClaw 当前内置了以下 Together 模型目录： -| 模型引用 | 名称 | 输入 | 上下文 | 说明 | +| Model ref | Name | Input | Context | Notes | | ------------------------------------------------------------ | -------------------------------------- | ----------- | ---------- | -------------------------------- | -| `together/moonshotai/Kimi-K2.5` | Kimi K2.5 | text, image | 262,144 | 默认模型；已启用推理 | -| `together/zai-org/GLM-4.7` | GLM 4.7 Fp8 | text | 202,752 | 通用文本模型 | -| `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` | Llama 3.3 70B Instruct Turbo | text | 131,072 | 快速指令模型 | -| `together/meta-llama/Llama-4-Scout-17B-16E-Instruct` | Llama 4 Scout 17B 16E Instruct | text, image | 10,000,000 | 多模态 | -| `together/meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8` | Llama 4 Maverick 17B 128E Instruct FP8 | text, image | 20,000,000 | 多模态 | -| `together/deepseek-ai/DeepSeek-V3.1` | DeepSeek V3.1 | text | 131,072 | 通用文本模型 | -| `together/deepseek-ai/DeepSeek-R1` | DeepSeek R1 | text | 131,072 | 推理模型 | -| `together/moonshotai/Kimi-K2-Instruct-0905` | Kimi K2-Instruct 0905 | text | 262,144 | 次要 Kimi 文本模型 | +| `together/moonshotai/Kimi-K2.5` | Kimi K2.5 | 文本、图像 | 262,144 | 默认模型；已启用推理 | +| `together/zai-org/GLM-4.7` | GLM 4.7 Fp8 | 文本 | 202,752 | 通用文本模型 | +| `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` | Llama 3.3 70B Instruct Turbo | 文本 | 131,072 | 快速指令模型 | +| `together/meta-llama/Llama-4-Scout-17B-16E-Instruct` | Llama 4 Scout 17B 16E Instruct | 文本、图像 | 10,000,000 | 多模态 | +| `together/meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8` | Llama 4 Maverick 17B 128E Instruct FP8 | 文本、图像 | 20,000,000 | 多模态 | +| `together/deepseek-ai/DeepSeek-V3.1` | DeepSeek V3.1 | 文本 | 131,072 | 通用文本模型 | +| `together/deepseek-ai/DeepSeek-R1` | DeepSeek R1 | 文本 | 131,072 | 推理模型 | +| `together/moonshotai/Kimi-K2-Instruct-0905` | Kimi K2-Instruct 0905 | 文本 | 262,144 | 次要 Kimi 文本模型 | 新手引导预设会将 `together/moonshotai/Kimi-K2.5` 设置为默认模型。 + +## 视频生成 + +内置的 `together` 插件还通过共享的 `video_generate` 工具注册了视频生成功能。 + +- 默认视频模型：`together/Wan-AI/Wan2.2-T2V-A14B` +- 模式：文生视频和单图参考流程 +- 支持 `aspectRatio` 和 `resolution` + +要将 Together 设为默认视频提供商： + +```json5 +{ + agents: { + defaults: { + videoGenerationModel: { + primary: "together/Wan-AI/Wan2.2-T2V-A14B", + }, + }, + }, +} +``` + +有关共享工具参数、提供商选择和故障转移行为，请参阅[视频生成](/zh-CN/tools/video-generation)。 diff --git a/docs/zh-CN/providers/xai.md b/docs/zh-CN/providers/xai.md index 092ff2b76..278571fb7 100644 --- a/docs/zh-CN/providers/xai.md +++ b/docs/zh-CN/providers/xai.md @@ -1,14 +1,14 @@ --- read_when: - 你想在 OpenClaw 中使用 Grok 模型 - - 你正在配置 xAI 认证或模型 id + - 你正在配置 xAI 身份验证或模型 ID summary: 在 OpenClaw 中使用 xAI Grok 模型 title: xAI x-i18n: - generated_at: "2026-04-05T10:07:15Z" + generated_at: "2026-04-05T22:23:12Z" model: gpt-5.4 provider: openai - source_hash: d11f27b48c69eed6324595977bca3506c7709424eef64cc73899f8d049148b82 + source_hash: 64bc899655427cc10bdc759171c7d1ec25ad9f1e4f9d803f1553d3d586c6d71d source_path: providers/xai.md workflow: 15 --- @@ -35,66 +35,91 @@ openclaw onboard --auth-choice xai-api-key ``` OpenClaw 现在使用 xAI Responses API 作为内置 xAI 传输层。同一个 -`XAI_API_KEY` 也可用于由 Grok 支持的 `web_search`、一等公民 `x_search` +`XAI_API_KEY` 也可用于由 Grok 驱动的 `web_search`、原生的 `x_search`， 以及远程 `code_execution`。 如果你将 xAI 密钥存储在 `plugins.entries.xai.config.webSearch.apiKey` 下， -内置 xAI 模型提供商现在也会将该密钥作为回退复用。 -`code_execution` 调优位于 `plugins.entries.xai.config.codeExecution` 下。 +内置的 xAI 模型提供商现在也会将该密钥作为回退复用。 +`code_execution` 调优配置位于 `plugins.entries.xai.config.codeExecution` 下。 ## 当前内置模型目录 OpenClaw 现在开箱即用地包含以下 xAI 模型系列： -- `grok-3`、`grok-3-fast`、`grok-3-mini`、`grok-3-mini-fast` -- `grok-4`、`grok-4-0709` -- `grok-4-fast`、`grok-4-fast-non-reasoning` -- `grok-4-1-fast`、`grok-4-1-fast-non-reasoning` -- `grok-4.20-beta-latest-reasoning`、`grok-4.20-beta-latest-non-reasoning` +- `grok-3`, `grok-3-fast`, `grok-3-mini`, `grok-3-mini-fast` +- `grok-4`, `grok-4-0709` +- `grok-4-fast`, `grok-4-fast-non-reasoning` +- `grok-4-1-fast`, `grok-4-1-fast-non-reasoning` +- `grok-4.20-beta-latest-reasoning`, `grok-4.20-beta-latest-non-reasoning` - `grok-code-fast-1` -当较新的 `grok-4*` 和 `grok-code-fast*` id -遵循相同的 API 形状时，该插件也会前向解析它们。 +当较新的 `grok-4*` 和 `grok-code-fast*` ID 遵循相同的 API 形态时， +该插件也会转发解析这些 ID。 快速模型说明： -- `grok-4-fast`、`grok-4-1-fast` 以及 `grok-4.20-beta-*` 变体是 - 当前内置目录中支持图像能力的 Grok 引用。 +- `grok-4-fast`、`grok-4-1-fast` 以及 `grok-4.20-beta-*` 变体，是当前内置目录中支持图像能力的 Grok 引用。 - `/fast on` 或 `agents.defaults.models["xai/"].params.fastMode: true` - 会按如下方式重写原生 xAI 请求： + 会将原生 xAI 请求按如下方式重写： - `grok-3` -> `grok-3-fast` - `grok-3-mini` -> `grok-3-mini-fast` - `grok-4` -> `grok-4-fast` - `grok-4-0709` -> `grok-4-fast` -旧版兼容性别名仍会规范化为内置规范 id。例如： +旧版兼容别名仍会规范化为内置的规范 ID。例如： - `grok-4-fast-reasoning` -> `grok-4-fast` - `grok-4-1-fast-reasoning` -> `grok-4-1-fast` - `grok-4.20-reasoning` -> `grok-4.20-beta-latest-reasoning` - `grok-4.20-non-reasoning` -> `grok-4.20-beta-latest-non-reasoning` -## Web 搜索 +## 网页搜索 -内置的 `grok` Web 搜索提供商也使用 `XAI_API_KEY`： +内置的 `grok` 网页搜索提供商也使用 `XAI_API_KEY`： ```bash openclaw config set tools.web.search.provider grok ``` +## 视频生成 + +内置的 `xai` 插件还通过共享的 +`video_generate` 工具注册了视频生成功能。 + +- 默认视频模型：`xai/grok-imagine-video` +- 模式：文生视频、图生视频，以及远程视频编辑/延长流程 +- 支持 `aspectRatio` 和 `resolution` +- 当前限制：不接受本地视频缓冲区；视频参考/编辑输入请使用远程 `http(s)` + URL + +要将 xAI 用作默认视频提供商： + +```json5 +{ + agents: { + defaults: { + videoGenerationModel: { + primary: "xai/grok-imagine-video", + }, + }, + }, +} +``` + +有关共享工具参数、提供商选择和故障切换行为，请参见 [视频生成](/zh-CN/tools/video-generation)。 + ## 已知限制 -- 当前认证仅支持 API 密钥。OpenClaw 还没有 xAI OAuth/设备代码流程。 -- `grok-4.20-multi-agent-experimental-beta-0304` 在常规 xAI 提供商路径上不受支持，因为它需要与标准 OpenClaw xAI 传输层不同的上游 API 表面。 +- 目前身份验证仅支持 API 密钥。OpenClaw 还不支持 xAI OAuth/设备代码流程。 +- `grok-4.20-multi-agent-experimental-beta-0304` 在常规 xAI 提供商路径上不受支持，因为它所需的上游 API 接口与标准 OpenClaw xAI 传输层不同。 ## 说明 -- OpenClaw 会在共享运行器路径上自动应用 xAI 专用的工具 schema 和工具调用兼容性修复。 +- OpenClaw 会在共享运行器路径上自动应用 xAI 专用的工具模式和工具调用兼容性修复。 - 原生 xAI 请求默认使用 `tool_stream: true`。将 - `agents.defaults.models["xai/"].params.tool_stream` 设为 `false` + `agents.defaults.models["xai/"].params.tool_stream` 设置为 `false` 可禁用它。 -- 内置 xAI 包装器会在发送原生 xAI 请求之前， - 去除不受支持的严格工具 schema 标志和 reasoning 负载键。 -- `web_search`、`x_search` 和 `code_execution` 作为 OpenClaw 工具公开。OpenClaw 会在每次工具请求中启用其所需的特定 xAI 内置能力，而不是在每一轮聊天中附加所有原生工具。 +- 内置的 xAI 包装器会在发送原生 xAI 请求前，移除不受支持的严格工具模式标志和推理负载键。 +- `web_search`、`x_search` 和 `code_execution` 会作为 OpenClaw 工具暴露。OpenClaw 会在每次工具请求中启用所需的特定 xAI 内置功能，而不是在每次聊天轮次中附加所有原生工具。 - `x_search` 和 `code_execution` 由内置 xAI 插件负责，而不是硬编码在核心模型运行时中。 -- `code_execution` 是远程 xAI 沙箱执行，不是本地 [`exec`](/zh-CN/tools/exec)。 -- 更广泛的提供商概览请参见[模型提供商](/zh-CN/providers/index)。 +- `code_execution` 是远程 xAI 沙箱执行，不是本地的 [`exec`](/zh-CN/tools/exec)。 +- 关于更广泛的提供商概览，请参见 [模型提供商](/zh-CN/providers/index)。 diff --git a/docs/zh-CN/tools/image-generation.md b/docs/zh-CN/tools/image-generation.md index 3a7537def..b899fd124 100644 --- a/docs/zh-CN/tools/image-generation.md +++ b/docs/zh-CN/tools/image-generation.md @@ -6,20 +6,20 @@ read_when: summary: 使用已配置的提供商（OpenAI、Google Gemini、fal、MiniMax）生成和编辑图像 title: 图像生成 x-i18n: - generated_at: "2026-04-05T10:11:33Z" + generated_at: "2026-04-05T22:23:17Z" model: gpt-5.4 provider: openai - source_hash: d38a8a583997ceff6523ce4f51808c97a2b59fe4e5a34cf79cdcb70d7e83aec2 + source_hash: 7ef7849a002f2328b94d1d55e7e0c8f3a59640ba269657c4184311c316c674fd source_path: tools/image-generation.md workflow: 15 --- # 图像生成 -`image_generate` 工具可让智能体使用你已配置的提供商来创建和编辑图像。生成的图像会作为媒体附件自动包含在智能体的回复中。 +`image_generate` 工具让智能体能够使用你已配置的提供商来创建和编辑图像。生成的图像会作为媒体附件自动随智能体的回复一起发送。 -仅当至少有一个图像生成提供商可用时，该工具才会出现。如果你在智能体工具中看不到 `image_generate`，请配置 `agents.defaults.imageGenerationModel` 或设置提供商 API 密钥。 +只有在至少有一个图像生成提供商可用时，此工具才会显示。如果你在智能体工具中看不到 `image_generate`，请配置 `agents.defaults.imageGenerationModel` 或设置提供商 API 密钥。 ## 快速开始 @@ -31,7 +31,9 @@ x-i18n: { agents: { defaults: { - imageGenerationModel: "openai/gpt-image-1", + imageGenerationModel: { + primary: "openai/gpt-image-1", + }, }, }, } @@ -39,16 +41,16 @@ x-i18n: 3. 向智能体提问：_“生成一张友好的龙虾吉祥物图像。”_ -智能体会自动调用 `image_generate`。无需工具 allow-listing——当提供商可用时，它默认启用。 +智能体会自动调用 `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` | -| MiniMax | `image-01` | 是（主体参考） | `MINIMAX_API_KEY` 或 MiniMax OAuth（`minimax-portal`） | +| 提供商 | 默认模型 | 编辑支持 | 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` | +| MiniMax | `image-01` | 是（主体参考） | `MINIMAX_API_KEY` 或 MiniMax OAuth（`minimax-portal`） | 使用 `action: "list"` 可在运行时查看可用的提供商和模型： @@ -58,20 +60,20 @@ 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-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 | 输出文件名提示 | -并非所有提供商都支持所有参数。该工具会传递各提供商所支持的参数，并忽略其余参数。 +并非所有提供商都支持所有参数。该工具会传递各提供商支持的参数，并忽略其余参数。 ## 配置 @@ -81,10 +83,6 @@ x-i18n: { agents: { defaults: { - // String form: primary model only - imageGenerationModel: "google/gemini-3.1-flash-image-preview", - - // Object form: primary + ordered fallbacks imageGenerationModel: { primary: "openai/gpt-image-1", fallbacks: ["google/gemini-3.1-flash-image-preview", "fal/fal-ai/flux/dev"], @@ -100,45 +98,49 @@ x-i18n: 1. 工具调用中的 **`model` 参数**（如果智能体指定了） 2. 配置中的 **`imageGenerationModel.primary`** -3. 按顺序尝试 **`imageGenerationModel.fallbacks`** -4. **自动检测**——仅使用有认证支持的提供商默认值： - - 先当前默认提供商 +3. 按顺序使用 **`imageGenerationModel.fallbacks`** +4. **自动检测** —— 仅使用有认证支持的提供商默认值： + - 先尝试当前默认提供商 - 再按提供商 id 顺序尝试其余已注册的图像生成提供商 -如果某个提供商失败（认证错误、速率限制等），会自动尝试下一个候选项。如果全部失败，错误信息中会包含每次尝试的详细信息。 +如果某个提供商失败（认证错误、速率限制等），会自动尝试下一个候选项。如果全部失败，错误信息将包含每次尝试的详细信息。 说明： -- 自动检测会感知认证状态。只有当 OpenClaw 实际可以对某个提供商进行认证时，该提供商默认值才会进入候选列表。 +- 自动检测会识别认证状态。只有当 OpenClaw 实际能够认证某个提供商时，该提供商默认值才会进入候选列表。 - 使用 `action: "list"` 可查看当前已注册的提供商、它们的默认模型以及认证环境变量提示。 ### 图像编辑 -OpenAI、Google、fal 和 MiniMax 支持编辑参考图像。传入参考图像路径或 URL： +OpenAI、Google、fal 和 MiniMax 都支持编辑参考图像。传入参考图像路径或 URL： ``` -"把这张照片生成成水彩画版本" + image: "/path/to/photo.jpg" +"Generate a watercolor version of this photo" + image: "/path/to/photo.jpg" ``` OpenAI 和 Google 通过 `images` 参数最多支持 5 张参考图像。fal 和 MiniMax 支持 1 张。 -MiniMax 图像生成可通过两种内置 MiniMax 认证路径使用： +MiniMax 图像生成可通过两种内置的 MiniMax 认证路径使用： -- `minimax/image-01` 用于 API 密钥设置 -- `minimax-portal/image-01` 用于 OAuth 设置 +- `minimax/image-01`，用于 API 密钥配置 +- `minimax-portal/image-01`，用于 OAuth 配置 ## 提供商能力 -| 能力 | OpenAI | Google | fal | MiniMax | -| --------------------- | -------------------- | -------------------- | ------------------- | --------------------------- | -| 生成 | 是（最多 4 张） | 是（最多 4 张） | 是（最多 4 张） | 是（最多 9 张） | -| 编辑/参考 | 是（最多 5 张图像） | 是（最多 5 张图像） | 是（1 张图像） | 是（1 张图像，主体参考） | -| 尺寸控制 | 是 | 是 | 是 | 否 | -| 宽高比 | 否 | 是 | 是（仅生成） | 是 | -| 分辨率（1K/2K/4K） | 否 | 是 | 是 | 否 | +| 能力 | OpenAI | Google | fal | MiniMax | +| --------------------- | -------------------- | -------------------- | ------------------- | -------------------------- | +| 生成 | 是（最多 4 张） | 是（最多 4 张） | 是（最多 4 张） | 是（最多 9 张） | +| 编辑/参考 | 是（最多 5 张图像） | 是（最多 5 张图像） | 是（1 张图像） | 是（1 张图像，主体参考） | +| 尺寸控制 | 是 | 是 | 是 | 否 | +| 宽高比 | 否 | 是 | 是（仅生成） | 是 | +| 分辨率（1K/2K/4K） | 否 | 是 | 是 | 否 | ## 相关内容 -- [工具概览](/zh-CN/tools) — 所有可用的智能体工具 -- [配置参考](/zh-CN/gateway/configuration-reference#agent-defaults) — `imageGenerationModel` 配置 -- [Models](/zh-CN/concepts/models) — 模型配置和故障转移 +- [Tools Overview](/zh-CN/tools) —— 所有可用的智能体工具 +- [fal](/providers/fal) —— fal 图像和视频提供商设置 +- [Google (Gemini)](/zh-CN/providers/google) —— Gemini 图像提供商设置 +- [MiniMax](/zh-CN/providers/minimax) —— MiniMax 图像提供商设置 +- [OpenAI](/zh-CN/providers/openai) —— OpenAI Images 提供商设置 +- [Configuration Reference](/zh-CN/gateway/configuration-reference#agent-defaults) —— `imageGenerationModel` 配置 +- [Models](/zh-CN/concepts/models) —— 模型配置和故障转移 diff --git a/docs/zh-CN/tools/video-generation.md b/docs/zh-CN/tools/video-generation.md index f47e7dced..d7adac492 100644 --- a/docs/zh-CN/tools/video-generation.md +++ b/docs/zh-CN/tools/video-generation.md @@ -6,54 +6,56 @@ read_when: summary: 使用已配置的提供商（如 Alibaba、OpenAI、Google、Qwen 和 MiniMax）生成视频 title: 视频生成 x-i18n: - generated_at: "2026-04-05T22:08:48Z" + generated_at: "2026-04-05T22:23:21Z" model: gpt-5.4 provider: openai - source_hash: 2e2c4e263bdcf96eab5067c93cee6719890b3e05396fc948854ff4926576ca3a + source_hash: 6bcaf4adf187254d1c9fac8a7e3578b863c736149beffb2517381ebe101bffb8 source_path: tools/video-generation.md workflow: 15 --- # 视频生成 -`video_generate` 工具可让智能体使用你已配置的提供商创建视频。生成的视频会作为媒体附件自动随智能体的回复一并发送。 +`video_generate` 工具允许智能体使用你已配置的提供商创建视频。生成的视频会作为媒体附件自动包含在智能体的回复中。 -只有在至少有一个视频生成提供商可用时，此工具才会出现。如果你在智能体工具中看不到 `video_generate`，请配置 `agents.defaults.videoGenerationModel` 或设置提供商 API 密钥。 +只有在至少有一个视频生成提供商可用时，此工具才会显示。如果你在智能体的工具中看不到 `video_generate`，请配置 `agents.defaults.videoGenerationModel` 或设置提供商 API 密钥。 ## 快速开始 1. 为至少一个提供商设置 API 密钥（例如 `OPENAI_API_KEY`、`GEMINI_API_KEY`、`MODELSTUDIO_API_KEY` 或 `QWEN_API_KEY`）。 -2. 可选：设置你偏好的模型： +2. 你也可以选择设置首选模型： ```json5 { agents: { defaults: { - videoGenerationModel: "qwen/wan2.6-t2v", + videoGenerationModel: { + primary: "qwen/wan2.6-t2v", + }, }, }, } ``` -3. 向智能体提问：_“生成一段 5 秒钟的电影感视频，内容是一只友好的龙虾在日落时分冲浪。”_ +3. 向智能体提问：_“生成一个 5 秒钟的电影感视频，内容是一只友善的龙虾在日落时冲浪。”_ -智能体会自动调用 `video_generate`。无需将其加入工具允许列表——当提供商可用时，它默认启用。 +智能体会自动调用 `video_generate`。无需配置工具允许列表——只要有可用提供商，它就会默认启用。 ## 支持的提供商 -| 提供商 | 默认模型 | 参考输入 | API 密钥 | -| ------ | ------------------------------- | ------------------ | ---------------------------------------------------------- | -| Alibaba | `wan2.6-t2v` | 是，远程 URL | `MODELSTUDIO_API_KEY`, `DASHSCOPE_API_KEY`, `QWEN_API_KEY` | -| BytePlus（国际版） | `seedance-1-0-lite-t2v-250428` | 1 张图片 | `BYTEPLUS_API_KEY` | -| fal | `fal-ai/minimax/video-01-live` | 1 张图片 | `FAL_KEY` | -| Google | `veo-3.1-fast-generate-preview` | 1 张图片或 1 个视频 | `GEMINI_API_KEY`, `GOOGLE_API_KEY` | -| MiniMax | `MiniMax-Hailuo-2.3` | 1 张图片 | `MINIMAX_API_KEY` | -| OpenAI | `sora-2` | 1 张图片或 1 个视频 | `OPENAI_API_KEY` | -| Qwen | `wan2.6-t2v` | 是，远程 URL | `QWEN_API_KEY`, `MODELSTUDIO_API_KEY`, `DASHSCOPE_API_KEY` | -| Together | `Wan-AI/Wan2.2-T2V-A14B` | 1 张图片 | `TOGETHER_API_KEY` | -| xAI | `grok-imagine-video` | 1 张图片或 1 个视频 | `XAI_API_KEY` | +| 提供商 | 默认模型 | 参考输入 | API 密钥 | +| -------- | ------------------------------- | ------------------ | ---------------------------------------------------------- | +| Alibaba | `wan2.6-t2v` | 是，远程 URL | `MODELSTUDIO_API_KEY`, `DASHSCOPE_API_KEY`, `QWEN_API_KEY` | +| BytePlus（国际版） | `seedance-1-0-lite-t2v-250428` | 1 张图像 | `BYTEPLUS_API_KEY` | +| fal | `fal-ai/minimax/video-01-live` | 1 张图像 | `FAL_KEY` | +| Google | `veo-3.1-fast-generate-preview` | 1 张图像或 1 个视频 | `GEMINI_API_KEY`, `GOOGLE_API_KEY` | +| MiniMax | `MiniMax-Hailuo-2.3` | 1 张图像 | `MINIMAX_API_KEY` | +| OpenAI | `sora-2` | 1 张图像或 1 个视频 | `OPENAI_API_KEY` | +| Qwen | `wan2.6-t2v` | 是，远程 URL | `QWEN_API_KEY`, `MODELSTUDIO_API_KEY`, `DASHSCOPE_API_KEY` | +| Together | `Wan-AI/Wan2.2-T2V-A14B` | 1 张图像 | `TOGETHER_API_KEY` | +| xAI | `grok-imagine-video` | 1 张图像或 1 个视频 | `XAI_API_KEY` | 使用 `action: "list"` 可在运行时查看可用的提供商和模型： @@ -63,22 +65,22 @@ x-i18n: ## 工具参数 -| 参数 | 类型 | 描述 | -| ----------------- | -------- | ----------------------------------------------------------------------------------- | -| `prompt` | string | 视频生成提示词（`action: "generate"` 时必填） | -| `action` | string | `"generate"`（默认）或 `"list"`，用于查看提供商 | -| `model` | string | 提供商/模型覆盖，例如 `qwen/wan2.6-t2v` | -| `image` | string | 单个参考图片路径或 URL | -| `images` | string[] | 多个参考图片（最多 5 张） | -| `video` | string | 单个参考视频路径或 URL | -| `videos` | string[] | 多个参考视频（最多 4 个） | -| `size` | string | 当提供商支持时的尺寸提示 | +| 参数 | 类型 | 描述 | +| ----------------- | -------- | ------------------------------------------------------------------------------------- | +| `prompt` | string | 视频生成提示词（`action: "generate"` 时必填） | +| `action` | string | `"generate"`（默认）或 `"list"`，用于查看提供商 | +| `model` | string | 提供商/模型覆盖值，例如 `qwen/wan2.6-t2v` | +| `image` | string | 单个参考图像路径或 URL | +| `images` | string[] | 多个参考图像（最多 5 个） | +| `video` | string | 单个参考视频路径或 URL | +| `videos` | string[] | 多个参考视频（最多 4 个） | +| `size` | string | 当提供商支持时使用的尺寸提示 | | `aspectRatio` | string | 宽高比：`1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9`、`21:9` | -| `resolution` | string | 分辨率提示：`480P`、`720P` 或 `1080P` | -| `durationSeconds` | number | 目标时长（秒） | -| `audio` | boolean | 当提供商支持时，启用生成音频 | -| `watermark` | boolean | 当支持时，切换提供商水印 | -| `filename` | string | 输出文件名提示 | +| `resolution` | string | 分辨率提示：`480P`、`720P` 或 `1080P` | +| `durationSeconds` | number | 目标时长（秒） | +| `audio` | boolean | 当提供商支持时，启用生成音频 | +| `watermark` | boolean | 当支持时，切换提供商水印 | +| `filename` | string | 输出文件名提示 | 并非所有提供商都支持所有参数。该工具会在提交请求前验证提供商能力限制。 @@ -103,31 +105,38 @@ x-i18n: 生成视频时，OpenClaw 会按以下顺序尝试提供商： -1. 工具调用中的 **`model` 参数**（如果智能体指定了该参数） +1. 工具调用中的 **`model` 参数**（如果智能体指定了） 2. 配置中的 **`videoGenerationModel.primary`** -3. 按顺序使用 **`videoGenerationModel.fallbacks`** -4. **自动检测** —— 仅使用有凭证支持的默认提供商： +3. 按顺序尝试 **`videoGenerationModel.fallbacks`** +4. **自动检测**——仅使用有凭证支持的提供商默认值： - 先使用当前默认提供商 - - 再按提供商 ID 顺序使用其余已注册的视频生成提供商 + - 再按 provider-id 顺序尝试其余已注册的视频生成提供商 -如果某个提供商失败，会自动尝试下一个候选项。如果全部失败，错误信息会包含每次尝试的详细信息。 +如果某个提供商失败，会自动尝试下一个候选项。如果全部失败，错误信息将包含每次尝试的详细信息。 ## 提供商说明 - Alibaba 使用 DashScope / Model Studio 异步视频端点，目前要求参考资源使用远程 `http(s)` URL。 -- Google 使用 Gemini/Veo，支持单个图片或视频参考输入。 -- MiniMax、Together、BytePlus（国际版）和 fal 当前支持单个图片参考输入。 +- Google 使用 Gemini/Veo，并支持单个图像或视频参考输入。 +- MiniMax、Together、BytePlus（国际版）和 fal 目前支持单个图像参考输入。 - OpenAI 使用原生视频端点，目前默认使用 `sora-2`。 -- Qwen 支持图片/视频参考，但上游 DashScope 视频端点目前要求这些参考使用远程 `http(s)` URL。 -- xAI 使用原生 xAI 视频 API，支持文生视频、图生视频，以及远程视频编辑/扩展流程。 +- Qwen 支持图像/视频参考，但上游 DashScope 视频端点目前要求这些参考使用远程 `http(s)` URL。 +- xAI 使用原生 xAI 视频 API，支持文生视频、图生视频以及远程视频编辑/扩展流程。 ## Qwen 参考输入 -内置的 Qwen 提供商支持文生视频以及图片/视频参考模式，但上游 DashScope 视频端点目前要求参考输入必须为**远程 http(s) URL**。本地文件路径和上传的缓冲区会在前置检查时直接被拒绝，而不是被静默忽略。 +内置的 Qwen 提供商支持文生视频以及图像/视频参考模式，但上游 DashScope 视频端点目前要求参考输入必须是**远程 http(s) URL**。本地文件路径和上传的缓冲区会在前置校验阶段被拒绝，而不会被静默忽略。 ## 相关内容 - [工具概览](/zh-CN/tools) — 所有可用的智能体工具 -- [Qwen](/zh-CN/providers/qwen) — Qwen 专属设置与限制 +- [Alibaba Model Studio](/providers/alibaba) — 直接设置 Wan 提供商 +- [Google（Gemini）](/zh-CN/providers/google) — Veo 提供商设置 +- [MiniMax](/zh-CN/providers/minimax) — Hailuo 提供商设置 +- [OpenAI](/zh-CN/providers/openai) — Sora 提供商设置 +- [Qwen](/zh-CN/providers/qwen) — Qwen 专属设置和限制 +- [Qwen / Model Studio](/zh-CN/providers/qwen_modelstudio) — DashScope 端点级细节 +- [Together AI](/zh-CN/providers/together) — Together Wan 提供商设置 +- [xAI](/zh-CN/providers/xai) — Grok 视频提供商设置 - [配置参考](/zh-CN/gateway/configuration-reference#agent-defaults) — `videoGenerationModel` 配置 -- [模型](/zh-CN/concepts/models) — 模型配置与故障切换 +- [模型](/zh-CN/concepts/models) — 模型配置和故障切换