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

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-25 20:34:59 +00:00
parent 9f5c3493af
commit 983e96fdb3
3 changed files with 292 additions and 331 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

221
docs/zh-CN/providers/minimax.md
View File

@ -5,10 +5,10 @@ read_when:
summary: 在 OpenClaw 中使用 MiniMax 模型
title: MiniMax
x-i18n:
generated_at: "2026-04-25T19:43:44Z"
generated_at: "2026-04-25T20:33:40Z"
model: gpt-5.4
provider: openai
source_hash: 910dffc160d5acf69fcacaf0009395e5f53509fa2ffe3c20a9128c87013d1b36
source_hash: 8b91f8c4c12c993457fb1535bbb2f3401474a3ec432b24189792a20041e756dc
source_path: providers/minimax.md
workflow: 15
---
@ -24,41 +24,41 @@ MiniMax 还提供：
提供商拆分：
| Provider ID | 鉴权方式 | 能力 |
| ---------------- | ------- | --------------------------------------------------------------- |
| `minimax` | API 密钥 | 文本、图像生成、图像理解、语音、网页搜索 |
| `minimax-portal` | OAuth | 文本、图像生成、图像理解、语音 |
| Provider ID | 认证方式 | 能力 |
| ---------------- | -------- | -------------------------------------------------------------------------------------------------- |
| `minimax` | API key | 文本、图像生成、音乐生成、视频生成、图像理解、语音、网页搜索 |
| `minimax-portal` | OAuth | 文本、图像生成、音乐生成、视频生成、图像理解、语音 |
## 内置目录
| 模型 | 类型 | 描述 |
| ------------------------ | ---------------- | ---------------------------------------- |
| `MiniMax-M2.7` | 聊天（推理） | 默认托管推理模型 |
| `MiniMax-M2.7-highspeed` | 聊天（推理） | 更快的 M2.7 推理层级 |
| `MiniMax-VL-01` | 视觉 | 图像理解模型 |
| `image-01` | 图像生成 | 文生图和图生图编辑 |
| `music-2.6` | 音乐生成 | 默认音乐模型 |
| `music-2.5` | 音乐生成 | 上一代音乐生成层级 |
| `music-2.0` | 音乐生成 | 旧版音乐生成层级 |
| `MiniMax-Hailuo-2.3` | 视频生成 | 文生视频和图像参考流程 |
| 模型 | 类型 | 描述 |
| ------------------------ | ---------------- | ------------------------------ |
| `MiniMax-M2.7` | 聊天（推理） | 默认托管推理模型 |
| `MiniMax-M2.7-highspeed` | 聊天（推理） | 更快的 M2.7 推理层级 |
| `MiniMax-VL-01` | 视觉 | 图像理解模型 |
| `image-01` | 图像生成 | 文生图和图生图编辑 |
| `music-2.6` | 音乐生成 | 默认音乐模型 |
| `music-2.5` | 音乐生成 | 上一代音乐生成层级 |
| `music-2.0` | 音乐生成 | 旧版音乐生成层级 |
| `MiniMax-Hailuo-2.3` | 视频生成 | 文生视频和图像参考工作流 |
## 入门指南
选择你偏好的鉴权方式，并按照设置步骤操作。
选择你偏好的认证方式，并按照设置步骤操作。
<Tabs>
<Tab title="OAuth（Coding Plan）">
**最适合：** 通过 OAuth 快速设置 MiniMax Coding Plan，无需 API 密钥。
<Tab title="OAuth (Coding Plan)">
**最适合：** 通过 OAuth 快速设置 MiniMax Coding Plan，无需 API key。
<Tabs>
<Tab title="国际版">
<Tab title="International">
<Steps>
<Step title="运行新手引导">
```bash
openclaw onboard --auth-choice minimax-global-oauth
```
这会针对 `api.minimax.io` 进行身份验证。
这会针对 `api.minimax.io` 进行认证。
</Step>
<Step title="验证模型可用">
```bash
@ -67,14 +67,14 @@ MiniMax 还提供：
</Step>
</Steps>
</Tab>
<Tab title="中国版">
<Tab title="China">
<Steps>
<Step title="运行新手引导">
```bash
openclaw onboard --auth-choice minimax-cn-oauth
```
这会针对 `api.minimaxi.com` 进行身份验证。
这会针对 `api.minimaxi.com` 进行认证。
</Step>
<Step title="验证模型可用">
```bash
@ -86,7 +86,7 @@ MiniMax 还提供：
</Tabs>
<Note>
OAuth 设置使用 `minimax-portal` provider id。模型引用格式为 `minimax-portal/MiniMax-M2.7`。
OAuth 设置使用 `minimax-portal` provider id。模型引用采用 `minimax-portal/MiniMax-M2.7` 这种格式。
</Note>
<Tip>
@ -95,11 +95,11 @@ MiniMax 还提供：
</Tab>
<Tab title="API 密钥">
<Tab title="API key">
**最适合：** 使用兼容 Anthropic API 的托管 MiniMax。
<Tabs>
<Tab title="国际版">
<Tab title="International">
<Steps>
<Step title="运行新手引导">
```bash
@ -115,7 +115,7 @@ MiniMax 还提供：
</Step>
</Steps>
</Tab>
<Tab title="中国版">
<Tab title="China">
<Steps>
<Step title="运行新手引导">
```bash
@ -173,11 +173,11 @@ MiniMax 还提供：
```
<Warning>
在兼容 Anthropic 的流式传输路径上，除非你自行显式设置 `thinking`，否则 OpenClaw 默认会禁用 MiniMax thinking。MiniMax 的流式端点会以 OpenAI 风格的 delta 分块返回 `reasoning_content`，而不是原生 Anthropic thinking 块；如果在未显式配置的情况下启用，可能会将内部推理泄露到可见输出中。
在兼容 Anthropic 的流式传输路径上，除非你自行显式设置 `thinking`，否则 OpenClaw 默认会禁用 MiniMax thinking。MiniMax 的流式端点会以 OpenAI 风格的 delta 分块而不是原生 Anthropic thinking 块来输出 `reasoning_content`，如果在未显式控制的情况下启用，可能会把内部推理泄露到可见输出中。
</Warning>
<Note>
API 密钥设置使用 `minimax` provider id。模型引用格式为 `minimax/MiniMax-M2.7`。
API-key 设置使用 `minimax` provider id。模型引用采用 `minimax/MiniMax-M2.7` 这种格式。
</Note>
</Tab>
@ -185,7 +185,7 @@ MiniMax 还提供：
## 通过 `openclaw configure` 配置
使用交互式配置向导设置 MiniMax，无需编辑 JSON：
使用交互式配置向导来设置 MiniMax，无需编辑 JSON：
<Steps>
<Step title="启动向导">
@ -193,18 +193,18 @@ MiniMax 还提供：
openclaw configure
```
</Step>
<Step title="选择 Model/auth">
在菜单中选择 **Model/auth**。
<Step title="选择模型/认证">
从菜单中选择 **模型/认证**。
</Step>
<Step title="选择一个 MiniMax 鉴权选项">
选择以下任一可用的 MiniMax 选项：
<Step title="选择一个 MiniMax 认证选项">
从可用的 MiniMax 选项中选择一个：
| Auth choice | 描述 |
| 认证选项 | 描述 |
| --- | --- |
| `minimax-global-oauth` | 国际版 OAuth（Coding Plan） |
| `minimax-cn-oauth` | 中国版 OAuth（Coding Plan） |
| `minimax-global-api` | 国际版 API 密钥 |
| `minimax-cn-api` | 中国版 API 密钥 |
| `minimax-global-api` | 国际版 API key |
| `minimax-cn-api` | 中国版 API key |
</Step>
<Step title="选择你的默认模型">
@ -224,7 +224,7 @@ MiniMax 插件为 `image_generate` 工具注册了 `image-01` 模型。它支持
- 每次编辑请求最多 **1 张参考图像**
- 支持的宽高比：`1:1`、`16:9`、`4:3`、`3:2`、`2:3`、`3:4`、`9:16`、`21:9`
要将 MiniMax 用于图像生成，请将其设置为图像生成提供商：
要使用 MiniMax 进行图像生成，请将其设置为图像生成提供商：
```json5
{
@ -236,28 +236,28 @@ 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-key 设置使用 `MINIMAX_API_KEY`；OAuth 设置则可以改用内置的 `minimax-portal` 认证路径。
图像生成始终使用 MiniMax 的专用图像端点
（`/v1/image_generation`），并忽略 `models.providers.minimax.baseUrl`，
图像生成始终使用 MiniMax 专用的图像端点
(`/v1/image_generation`)，并忽略 `models.providers.minimax.baseUrl`，
因为该字段用于配置聊天 / 兼容 Anthropic 的基础 URL。设置
`MINIMAX_API_HOST=https://api.minimaxi.com` 可将图像生成路由到中国区端点；
默认的全球端点是
`MINIMAX_API_HOST=https://api.minimaxi.com` 可将图像生成路由到
中国区端点；默认的全球端点为
`https://api.minimax.io`。
当新手引导或 API 密钥设置写入显式的 `models.providers.minimax`
当新手引导或 API-key 设置写入显式的 `models.providers.minimax`
条目时，OpenClaw 会将 `MiniMax-M2.7` 和
`MiniMax-M2.7-highspeed` 具体化为纯文本聊天模型。图像理解则通过插件自有的 `MiniMax-VL-01` 媒体提供商单独暴露。
`MiniMax-M2.7-highspeed` 具体化为仅文本的聊天模型。图像理解则通过由插件拥有的 `MiniMax-VL-01` 媒体提供商单独暴露。
<Note>
有关共享工具参数、提供商选择和故障切换行为，请参阅 [图像生成](/zh-CN/tools/image-generation)。
有关共享工具参数、提供商选择和故障转移行为，请参见 [图像生成](/zh-CN/tools/image-generation)。
</Note>
### 文本转语音
内置的 `minimax` 插件还会将 MiniMax T2A v2 注册为
内置的 `minimax` 插件将 MiniMax T2A v2 注册为
`messages.tts` 的语音提供商。
- 默认 TTS 模型：`speech-2.8-hd`
@ -265,39 +265,40 @@ MiniMax 插件为 `image_generate` 工具注册了 `image-01` 模型。它支持
- 支持的内置模型 id 包括 `speech-2.8-hd`、`speech-2.8-turbo`、
`speech-2.6-hd`、`speech-2.6-turbo`、`speech-02-hd`、
`speech-02-turbo`、`speech-01-hd` 和 `speech-01-turbo`。
- 鉴权解析顺序为 `messages.tts.providers.minimax.apiKey`，然后是
`minimax-portal` OAuth / token 鉴权配置文件，然后是 Token Plan 环境变量
（`MINIMAX_OAUTH_TOKEN`、`MINIMAX_CODE_PLAN_KEY`、
- 认证解析顺序为 `messages.tts.providers.minimax.apiKey`，然后是
`minimax-portal` OAuth/token auth profiles，然后是 Token Plan 环境变量
键（`MINIMAX_OAUTH_TOKEN`、`MINIMAX_CODE_PLAN_KEY`、
`MINIMAX_CODING_API_KEY`），最后是 `MINIMAX_API_KEY`。
- 如果未配置 TTS 主机，OpenClaw 会复用已配置的
`minimax-portal` OAuth 主机，并去掉兼容 Anthropic 的路径后缀，
`minimax-portal` OAuth 主机，并去除兼容 Anthropic 的路径后缀，
例如 `/anthropic`。
- 普通音频附件保持为 MP3。
- 常规音频附件保持为 MP3。
- Feishu 和 Telegram 等语音便笺目标会通过 `ffmpeg` 从 MiniMax
MP3 转码为 48 kHz Opus，因为 Feishu / Lark 文件 API 仅接受
MP3 转码为 48kHz Opus，因为 Feishu/Lark 文件 API 仅接受
`file_type: "opus"` 作为原生音频消息。
- MiniMax T2A 接受小数形式的 `speed` 和 `vol`，但 `pitch` 会以整数发送；
OpenClaw 会在发起 API 请求前截断 `pitch` 的小数值。
- MiniMax T2A 接受小数 `speed` 和 `vol`，但 `pitch` 会以整数发送；
OpenClaw 会在 API 请求前截断带小数的 `pitch` 值。
| 设置 | 环境变量 | 默认值 | 描述 |
| ---------------------------------------- | ---------------------- | ----------------------------- | -------------------------------- |
| `messages.tts.providers.minimax.baseUrl` | `MINIMAX_API_HOST` | `https://api.minimax.io` | MiniMax T2A API 主机。 |
| `messages.tts.providers.minimax.model` | `MINIMAX_TTS_MODEL` | `speech-2.8-hd` | TTS 模型 id。 |
| `messages.tts.providers.minimax.voiceId` | `MINIMAX_TTS_VOICE_ID` | `English_expressive_narrator` | 用于语音输出的 voice id。 |
| `messages.tts.providers.minimax.speed` | | `1.0` | 播放速度，`0.5..2.0`。 |
| `messages.tts.providers.minimax.vol` | | `1.0` | 音量，`(0, 10]`。 |
| `messages.tts.providers.minimax.pitch` | | `0` | 整数音高偏移，`-12..12`。 |
| 设置 | 环境变量 | 默认值 | 描述 |
| ---------------------------------------- | ---------------------- | ----------------------------- | ---------------------------- |
| `messages.tts.providers.minimax.baseUrl` | `MINIMAX_API_HOST` | `https://api.minimax.io` | MiniMax T2A API 主机。 |
| `messages.tts.providers.minimax.model` | `MINIMAX_TTS_MODEL` | `speech-2.8-hd` | TTS 模型 id。 |
| `messages.tts.providers.minimax.voiceId` | `MINIMAX_TTS_VOICE_ID` | `English_expressive_narrator` | 用于语音输出的语音 id。 |
| `messages.tts.providers.minimax.speed` | | `1.0` | 播放速度，`0.5..2.0`。 |
| `messages.tts.providers.minimax.vol` | | `1.0` | 音量，`(0, 10]`。 |
| `messages.tts.providers.minimax.pitch` | | `0` | 整数音高偏移，`-12..12`。 |
### 音乐生成
内置的 `minimax` 插件还会通过共享的
`music_generate` 工具注册音乐生成功能。
内置的 MiniMax 插件通过共享的
`music_generate` 工具为 `minimax` 和 `minimax-portal` 都注册了音乐生成能力。
- 默认音乐模型：`minimax/music-2.6`
- 还支持 `minimax/music-2.5` 和 `minimax/music-2.0`
- OAuth 音乐模型：`minimax-portal/music-2.6`
- 也支持 `minimax/music-2.5` 和 `minimax/music-2.0`
- 提示词控制项：`lyrics`、`instrumental`、`durationSeconds`
- 输出格式：`mp3`
- 基于会话的运行会通过共享任务 / 状态流程分离执行，包括 `action: "status"`
- 基于会话的运行会通过共享的任务 / 状态流程分离执行，包括 `action: "status"`
要将 MiniMax 用作默认音乐提供商：
@ -314,16 +315,17 @@ MiniMax 插件为 `image_generate` 工具注册了 `image-01` 模型。它支持
```
<Note>
有关共享工具参数、提供商选择和故障切换行为，请参阅 [音乐生成](/zh-CN/tools/music-generation)。
有关共享工具参数、提供商选择和故障转移行为，请参见 [音乐生成](/zh-CN/tools/music-generation)。
</Note>
### 视频生成
内置的 `minimax` 插件还会通过共享的
`video_generate` 工具注册视频生成功能。
内置的 MiniMax 插件通过共享的
`video_generate` 工具为 `minimax` 和 `minimax-portal` 都注册了视频生成能力。
- 默认视频模型：`minimax/MiniMax-Hailuo-2.3`
- 模式：文生视频和单图参考流程
- OAuth 视频模型：`minimax-portal/MiniMax-Hailuo-2.3`
- 模式：文生视频和单图参考工作流
- 支持 `aspectRatio` 和 `resolution`
要将 MiniMax 用作默认视频提供商：
@ -341,37 +343,38 @@ MiniMax 插件为 `image_generate` 工具注册了 `image-01` 模型。它支持
```
<Note>
有关共享工具参数、提供商选择和故障切换行为，请参阅 [视频生成](/zh-CN/tools/video-generation)。
有关共享工具参数、提供商选择和故障转移行为，请参见 [视频生成](/zh-CN/tools/video-generation)。
</Note>
### 图像理解
MiniMax 插件将图像理解与文本目录分开注册：
MiniMax 插件将图像理解与文本
目录分开注册：
| Provider ID | 默认图像模型 |
| ---------------- | ------------------- |
| `minimax` | `MiniMax-VL-01` |
| `minimax-portal` | `MiniMax-VL-01` |
| Provider ID | 默认图像模型 |
| ---------------- | ----------------- |
| `minimax` | `MiniMax-VL-01` |
| `minimax-portal` | `MiniMax-VL-01` |
这就是为什么自动媒体路由即使在内置文本提供商目录仍然只显示纯文本 M2.7 聊天引用时，也可以使用 MiniMax 图像理解。
这就是为什么即使内置的文本提供商目录仍然显示仅文本的 M2.7 聊天引用，自动媒体路由仍然可以使用 MiniMax 图像理解。
### 网页搜索
MiniMax 插件还通过 MiniMax Coding Plan
搜索 API 注册了 `web_search`。
- provider id：`minimax`
- 提供商 id：`minimax`
- 结构化结果：标题、URL、摘要、相关查询
- 首选环境变量：`MINIMAX_CODE_PLAN_KEY`
- 可接受的环境变量别名：`MINIMAX_CODING_API_KEY`
- 兼容性回退：当 `MINIMAX_API_KEY` 已经指向 coding plan token 时使用它
- 区域复用：`plugins.entries.minimax.config.webSearch.region`，然后 `MINIMAX_API_HOST`，再然后是 MiniMax provider base URL
- 搜索始终保留在 provider id `minimax` 上；OAuth 中国区 / 国际版设置仍然可以通过 `models.providers.minimax-portal.baseUrl` 间接引导区域
- 兼容性回退：如果 `MINIMAX_API_KEY` 已指向 coding-plan token，则使用它
- 区域复用：`plugins.entries.minimax.config.webSearch.region`，然后是 `MINIMAX_API_HOST`，再然后是 MiniMax 提供商基础 URL
- 搜索始终保留在提供商 id `minimax` 上；OAuth 中国区 / 国际版设置仍然可以通过 `models.providers.minimax-portal.baseUrl` 间接引导区域
配置位于 `plugins.entries.minimax.config.webSearch.*` 下。
<Note>
完整的网页搜索配置和用法，请参阅 [MiniMax Search](/zh-CN/tools/minimax-search)。
有关完整的网页搜索配置和用法，请参见 [MiniMax 搜索](/zh-CN/tools/minimax-search)。
</Note>
## 高级配置
@ -382,16 +385,16 @@ MiniMax 插件还通过 MiniMax Coding Plan
| --- | --- |
| `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.apiKey` | MiniMax API key（`MINIMAX_API_KEY`） |
| `models.providers.minimax.models` | 定义 `id`、`name`、`reasoning`、`contextWindow`、`maxTokens`、`cost` |
| `agents.defaults.models` | 为你想加入允许列表的模型设置别名 |
| `models.mode` | 如果你想在内置模型之外添加 MiniMax，请保持为 `merge` |
| `agents.defaults.models` | 为你想加入 allowlist 的模型设置别名 |
| `models.mode` | 如果你想将 MiniMax 与内置模型一起添加，请保持为 `merge` |
</Accordion>
<Accordion title="Thinking 默认值">
在 `api: "anthropic-messages"` 上，除非参数 / 配置中已经显式设置了 thinking，否则 OpenClaw 会注入 `thinking: { type: "disabled" }`。
在 `api: "anthropic-messages"` 下，除非参数 / 配置中已经显式设置了 thinking，否则 OpenClaw 会注入 `thinking: { type: "disabled" }`。
这样可以防止 MiniMax 的流式端点以 OpenAI 风格的 delta 分块发出 `reasoning_content`，从而将内部推理泄露到可见输出中。
这样可以防止 MiniMax 的流式端点以 OpenAI 风格的 delta 分块输出 `reasoning_content`，从而把内部推理泄露到可见输出中。
</Accordion>
@ -400,7 +403,7 @@ MiniMax 插件还通过 MiniMax Coding Plan
</Accordion>
<Accordion title="回退示例">
**最适合：** 将你最新一代中最强的模型保持为主模型，在失败时回退到 MiniMax M2.7。下面的示例使用 Opus 作为具体主模型；你可以替换为自己偏好的最新一代主模型。
**最适合：** 将你最强的最新一代模型保留为主模型，并在失败时回退到 MiniMax M2.7。下面的示例使用 Opus 作为具体主模型；你可以替换为你偏好的最新一代主模型。
```json5
{
@ -422,51 +425,51 @@ MiniMax 插件还通过 MiniMax Coding Plan
</Accordion>
<Accordion title="Coding Plan 使用细节">
<Accordion title="Coding Plan 使用详情">
- Coding Plan 用量 API：`https://api.minimaxi.com/v1/api/openplatform/coding_plan/remains`（需要 coding plan key）。
- 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 key 环境变量。
- 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 key 环境变量。
</Accordion>
</AccordionGroup>
## 说明
- 模型引用遵循鉴权路径：
- API 密钥设置：`minimax/<model>`
- 模型引用遵循认证路径：
- API-key 设置：`minimax/<model>`
- OAuth 设置：`minimax-portal/<model>`
- 默认聊天模型：`MiniMax-M2.7`
- 备用聊天模型：`MiniMax-M2.7-highspeed`
- 新手引导和直接 API 密钥设置会为两个 M2.7 变体写入纯文本模型定义
- 图像理解使用插件自有的 `MiniMax-VL-01` 媒体提供商
- 新手引导和直接 API-key 设置会为两个 M2.7 变体写入仅文本模型定义
- 图像理解使用由插件拥有的 `MiniMax-VL-01` 媒体提供商
- 如果你需要精确的成本跟踪，请更新 `models.json` 中的定价值
- 使用 `openclaw models list` 确认当前 provider id，然后使用 `openclaw models set minimax/MiniMax-M2.7` 或 `openclaw models set minimax-portal/MiniMax-M2.7` 进行切换
- 使用 `openclaw models list` 确认当前的提供商 id，然后通过 `openclaw models set minimax/MiniMax-M2.7` 或 `openclaw models set minimax-portal/MiniMax-M2.7` 进行切换
<Tip>
MiniMax Coding Plan 推荐链接（九折优惠）：[MiniMax Coding Plan](https://platform.minimax.io/subscribe/coding-plan?code=DbXJTRClnb&source=link)
</Tip>
<Note>
有关 provider 规则，请参阅 [模型提供商](/zh-CN/concepts/model-providers)。
有关提供商规则，请参见 [模型提供商](/zh-CN/concepts/model-providers)。
</Note>
## 故障排除
<AccordionGroup>
<Accordion title='"未知模型：minimax/MiniMax-M2.7"'>
这通常意味着 **MiniMax provider 未配置**（没有匹配的 provider 条目，且未找到 MiniMax 鉴权配置文件 / 环境变量密钥）。针对这一检测的修复已包含在 **2026.1.12** 中。可按以下方式修复：
<Accordion title='"Unknown model: minimax/MiniMax-M2.7"'>
这通常意味着 **MiniMax 提供商未配置**（没有匹配的提供商条目，也没有找到 MiniMax auth profile / 环境变量 key）。该检测问题的修复已包含在 **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 鉴权配置文件，以便注入匹配的 provider。
- 运行 `openclaw configure` 并选择一个 **MiniMax** 认证选项，或
- 手动添加匹配的 `models.providers.minimax` 或 `models.providers.minimax-portal` 代码块，或
- 设置 `MINIMAX_API_KEY`、`MINIMAX_OAUTH_TOKEN` 或 MiniMax auth profile，以便注入匹配的提供商。
请确保模型 id **区分大小写**：
- API 密钥路径：`minimax/MiniMax-M2.7` 或 `minimax/MiniMax-M2.7-highspeed`
- API-key 路径：`minimax/MiniMax-M2.7` 或 `minimax/MiniMax-M2.7-highspeed`
- OAuth 路径：`minimax-portal/MiniMax-M2.7` 或 `minimax-portal/MiniMax-M2.7-highspeed`
然后重新检查：
然后使用以下命令重新检查：
```bash
openclaw models list
@ -483,7 +486,7 @@ MiniMax Coding Plan 推荐链接（九折优惠）：[MiniMax Coding Plan](https
<CardGroup cols={2}>
<Card title="模型选择" href="/zh-CN/concepts/model-providers" icon="layers">
选择提供商、模型引用和故障切换行为。
选择提供商、模型引用和故障转移行为。
</Card>
<Card title="图像生成" href="/zh-CN/tools/image-generation" icon="image">
共享图像工具参数和提供商选择。
@ -494,7 +497,7 @@ MiniMax Coding Plan 推荐链接（九折优惠）：[MiniMax Coding Plan](https
<Card title="视频生成" href="/zh-CN/tools/video-generation" icon="video">
共享视频工具参数和提供商选择。
</Card>
<Card title="MiniMax Search" href="/zh-CN/tools/minimax-search" icon="magnifying-glass">
<Card title="MiniMax 搜索" href="/zh-CN/tools/minimax-search" icon="magnifying-glass">
通过 MiniMax Coding Plan 进行网页搜索配置。
</Card>
<Card title="故障排除" href="/zh-CN/help/troubleshooting" icon="wrench">

148
docs/zh-CN/tools/music-generation.md
View File

@ -6,25 +6,25 @@ read_when:
summary: 使用共享提供商生成音乐，包括由工作流支持的插件
title: 音乐生成
x-i18n:
generated_at: "2026-04-25T10:03:58Z"
generated_at: "2026-04-25T20:33:40Z"
model: gpt-5.4
provider: openai
source_hash: fe66c6dfb54c71b1d08a486c574e8a86cf3731d5339b44b9eef121f045c13cb8
source_hash: 1b23ad4c787e404f681c71e48b73d1642d7eeb116c11cc8716ae4f0e7a75677d
source_path: tools/music-generation.md
workflow: 15
---
`music_generate` 工具允许智能体通过共享的音乐生成能力，结合已配置的提供商（如 Google、MiniMax，以及通过工作流配置的 ComfyUI）来创建音乐或音频。
`music_generate` 工具让智能体能够通过共享的音乐生成功能，借助已配置的提供商来创建音乐或音频，例如 Google、MiniMax，以及通过工作流配置的 ComfyUI。
对于基于共享提供商的智能体会话，OpenClaw 会将音乐生成作为后台任务启动，在任务账本中跟踪它，然后在音轨准备就绪后再次唤醒智能体，以便智能体将完成的音频发回原始渠道。
对于由共享提供商支持的智能体会话，OpenClaw 会将音乐生成作为后台任务启动，在任务账本中跟踪它，然后在音轨准备好后再次唤醒智能体，以便智能体将完成的音频发布回原始渠道。
<Note>
只有在至少有一个音乐生成提供商可用时，内置共享工具才会出现。如果你在智能体的工具中看不到 `music_generate`，请配置 `agents.defaults.musicGenerationModel` 或设置提供商 API 密钥。
只有在至少有一个音乐生成提供商可用时，内置共享工具才会出现。如果你在智能体的工具中没有看到 `music_generate`，请配置 `agents.defaults.musicGenerationModel` 或设置提供商 API 密钥。
</Note>
## 快速开始
### 基于共享提供商的生成
### 由共享提供商支持的生成
1. 为至少一个提供商设置 API 密钥，例如 `GEMINI_API_KEY` 或 `MINIMAX_API_KEY`。
2. 可选：设置你偏好的模型：
@ -41,11 +41,11 @@ x-i18n:
}
```
3. 向智能体发出请求：_“生成一首关于夜晚驾车穿过霓虹都市的欢快 synthpop 曲目。”_
3. 让智能体执行：_“生成一首关于夜晚驾车穿过霓虹都市的欢快 synthpop 曲目。”_
智能体会自动调用 `music_generate`。无需设置工具允许列表。
智能体会自动调用 `music_generate`。无需工具允许列表。
对于没有基于会话的智能体运行的直接同步上下文，内置工具仍会回退为内联生成，并在工具结果中返回最终媒体路径。
对于没有由会话支持的智能体运行的直接同步上下文，内置工具仍会回退为内联生成，并在工具结果中返回最终媒体路径。
示例提示词：
@ -61,9 +61,9 @@ Generate an energetic chiptune loop about launching a rocket at sunrise.
内置的 `comfy` 插件通过音乐生成提供商注册表接入共享 `music_generate` 工具。
1. 配置 `plugins.entries.comfy.config.music`，包括工作流 JSON 以及提示词/输出节点。
1. 配置 `plugins.entries.comfy.config.music`，其中包含工作流 JSON 以及提示词/输出节点。
2. 如果你使用 Comfy Cloud，请设置 `COMFY_API_KEY` 或 `COMFY_CLOUD_API_KEY`。
3. 请求智能体生成音乐，或直接调用该工具。
3. 让智能体生成音乐，或直接调用该工具。
示例：
@ -73,29 +73,29 @@ Generate an energetic chiptune loop about launching a rocket at sunrise.
## 共享内置提供商支持
| 提供商 | 默认模型 | 参考输入 | 支持的控制项 | API 密钥 |
| ------ | ---------------------- | -------------- | --------------------------------------------------------- | -------------------------------------- |
| ComfyUI | `workflow` | 最多 1 张图像 | 由工作流定义的音乐或音频 | `COMFY_API_KEY`, `COMFY_CLOUD_API_KEY` |
| Google | `lyria-3-clip-preview` | 最多 10 张图像 | `lyrics`、`instrumental`、`format` | `GEMINI_API_KEY`, `GOOGLE_API_KEY` |
| MiniMax | `music-2.6` | 无 | `lyrics`、`instrumental`、`durationSeconds`、`format=mp3` | `MINIMAX_API_KEY` |
| 提供商 | 默认模型 | 参考输入 | 支持的控制项 | API 密钥 |
| ------ | ---------------------- | -------------- | ---------------------------------------------------- | ---------------------------------------- |
| ComfyUI | `workflow` | 最多 1 张图片 | 由工作流定义的音乐或音频 | `COMFY_API_KEY`, `COMFY_CLOUD_API_KEY` |
| Google | `lyria-3-clip-preview` | 最多 10 张图片 | `lyrics`、`instrumental`、`format` | `GEMINI_API_KEY`, `GOOGLE_API_KEY` |
| MiniMax | `music-2.6` | 无 | `lyrics`、`instrumental`、`durationSeconds`、`format=mp3` | `MINIMAX_API_KEY` 或 MiniMax OAuth |
### 已声明的能力矩阵
这是 `music_generate`、契约测试以及共享实时扫描所使用的显式模式契约。
| 提供商 | `generate` | `edit` | 编辑限制 | 共享实时测试通道 |
| ------ | ---------- | ------ | -------- | -------------------------------------------------------------------------- |
| ComfyUI | 是 | 是 | 1 张图像 | 不在共享扫描中；由 `extensions/comfy/comfy.live.test.ts` 覆盖 |
| Google | 是 | 是 | 10 张图像 | `generate`、`edit` |
| MiniMax | 是 | 否 | 无 | `generate` |
| 提供商 | `generate` | `edit` | 编辑限制 | 共享实时测试通道 |
| ------ | ---------- | ------ | -------- | --------------------------------------------------------------------- |
| ComfyUI | 是 | 是 | 1 张图片 | 不在共享扫描中；由 `extensions/comfy/comfy.live.test.ts` 覆盖 |
| Google | 是 | 是 | 10 张图片 | `generate`、`edit` |
| MiniMax | 是 | 否 | 无 | `generate` |
使用 `action: "list"` 可在运行时检查可用的共享提供商和模型：
使用 `action: "list"` 可在运行时查看可用的共享提供商和模型：
```text
/tool music_generate action=list
```
使用 `action: "status"` 可检查当前基于会话的音乐任务状态：
使用 `action: "status"` 可查看当前由会话支持的音乐任务状态：
```text
/tool music_generate action=status
@ -109,41 +109,41 @@ Generate an energetic chiptune loop about launching a rocket at sunrise.
## 内置工具参数
| 参数 | 类型 | 说明 |
| ----------------- | -------- | ------------------------------------------------------------------------------------------------ |
| `prompt` | string | 音乐生成提示词（`action: "generate"` 时必填） |
| `action` | string | `"generate"`（默认）、用于当前会话任务的 `"status"`，或用于检查提供商的 `"list"` |
| `model` | string | 提供商/模型覆盖值，例如 `google/lyria-3-pro-preview` 或 `comfy/workflow` |
| `lyrics` | string | 当提供商支持显式歌词输入时的可选歌词内容 |
| `instrumental` | boolean | 当提供商支持时，请求仅器乐输出 |
| `image` | string | 单个参考图像路径或 URL |
| `images` | string[] | 多个参考图像（最多 10 张） |
| `durationSeconds` | number | 当提供商支持时，目标时长（秒）提示 |
| `timeoutMs` | number | 可选的提供商请求超时时间（毫秒） |
| `format` | string | 输出格式提示（`mp3` 或 `wav`），前提是提供商支持 |
| `filename` | string | 输出文件名提示 |
| 参数 | 类型 | 描述 |
| ------------------ | -------- | ---------------------------------------------------------------------------------------- |
| `prompt` | string | 音乐生成提示词（`action: "generate"` 时必填） |
| `action` | string | `"generate"`（默认）、用于当前会话任务的 `"status"`，或用于查看提供商的 `"list"` |
| `model` | string | 提供商/模型覆盖，例如 `google/lyria-3-pro-preview` 或 `comfy/workflow` |
| `lyrics` | string | 当提供商支持显式歌词输入时的可选歌词 |
| `instrumental` | boolean | 当提供商支持时，请求仅器乐输出 |
| `image` | string | 单张参考图片路径或 URL |
| `images` | string[] | 多张参考图片（最多 10 张） |
| `durationSeconds` | number | 当提供商支持时，以秒为单位的目标时长提示 |
| `timeoutMs` | number | 可选的提供商请求超时时间（毫秒） |
| `format` | string | 输出格式提示（`mp3` 或 `wav`），当提供商支持时可用 |
| `filename` | string | 输出文件名提示 |
并非所有提供商都支持所有参数。OpenClaw 仍会在提交前验证硬性限制，例如输入数量。当提供商支持时长但其最大值小于请求值时，OpenClaw 会自动将其限制到最接近的受支持时长。对于真正不受支持的可选提示，当所选提供商或模型无法满足时，会忽略这些提示并给出警告。
并非所有提供商都支持所有参数。OpenClaw 仍会在提交前验证硬性限制，例如输入数量。当提供商支持时长但其最大值短于请求值时，OpenClaw 会自动限制到最接近的受支持时长。对于真正不支持的可选提示，当所选提供商或模型无法满足时，会忽略并给出警告。
工具结果会报告已应用的设置。当 OpenClaw 在提供商回退期间限制时长时，返回的 `durationSeconds` 反映的是提交值，而 `details.normalization.durationSeconds` 会显示从请求值到应用值的映射。
工具结果会报告实际应用的设置。当 OpenClaw 在提供商回退期间限制时长时，返回的 `durationSeconds` 反映的是提交值，而 `details.normalization.durationSeconds` 会显示从请求值到实际应用值的映射。
## 共享提供商路径的异步行为
## 共享提供商支持路径的异步行为
- 基于会话的智能体运行：`music_generate` 会创建后台任务，立即返回已启动/任务响应，并稍后通过后续智能体消息发布完成的曲目。
- 防止重复：当该后台任务仍处于 `queued` 或 `running` 状态时，同一会话中后续的 `music_generate` 调用会返回任务状态，而不是启动新的生成任务。
- 状态查询：使用 `action: "status"` 可检查当前基于会话的音乐任务，而不会启动新任务。
- 任务跟踪：使用 `openclaw tasks list` 或 `openclaw tasks show <taskId>` 可检查生成任务的排队、运行中和终态状态。
- 完成唤醒：OpenClaw 会将内部完成事件注入回同一会话，以便模型自行编写面向用户的后续消息。
- 提示词提示：当同一会话中已有音乐任务在进行时，后续用户/手动轮次会收到一个小型运行时提示，以防模型盲目再次调用 `music_generate`。
- 无会话回退：在没有真实智能体会话的直接/本地上下文中，仍会以内联方式运行，并在同一轮中返回最终音频结果。
- 由会话支持的智能体运行：`music_generate` 会创建后台任务，立即返回 started/task 响应，并在之后通过后续智能体消息发布完成的音轨。
- 防重复：当该后台任务仍处于 `queued` 或 `running` 状态时，同一会话中的后续 `music_generate` 调用会返回任务状态，而不是再次启动生成。
- 状态查询：使用 `action: "status"` 可在不启动新任务的情况下查看当前由会话支持的音乐任务。
- 任务跟踪：使用 `openclaw tasks list` 或 `openclaw tasks show <taskId>` 查看该生成任务的排队、运行和终止状态。
- 完成唤醒：OpenClaw 会将一个内部完成事件重新注入同一会话，以便模型自行编写面向用户的后续回复。
- 提示词提示：当某个音乐任务已在执行中时，同一会话中的后续用户/手动轮次会收到一个小型运行时提示，以防模型盲目再次调用 `music_generate`。
- 无会话回退：没有真实智能体会话的直接/本地上下文仍会以内联方式运行，并在同一轮返回最终音频结果。
### 任务生命周期
每个 `music_generate` 请求都会经历四个状态：
每个 `music_generate` 请求都会经历四种状态：
1. **queued** —— 任务已创建，等待提供商接受。
2. **running** —— 提供商正在处理（通常为 30 秒到 3 分钟，取决于提供商和时长）。
3. **succeeded** —— 曲目已准备就绪；智能体被唤醒并将其发布到对话中。
1. **queued** —— 任务已创建，正在等待提供商接受。
2. **running** —— 提供商正在处理中（通常为 30 秒到 3 分钟，取决于提供商和时长）。
3. **succeeded** —— 音轨已就绪；智能体被唤醒并将其发布到对话中。
4. **failed** —— 提供商错误或超时；智能体被唤醒并附带错误详情。
通过 CLI 检查状态：
@ -154,7 +154,7 @@ openclaw tasks show <taskId>
openclaw tasks cancel <taskId>
```
防止重复：如果当前会话的音乐任务已经处于 `queued` 或 `running` 状态，`music_generate` 会返回现有任务状态，而不是启动新任务。使用 `action: "status"` 可显式检查，而不会触发新的生成。
防重复：如果当前会话的音乐任务已经处于 `queued` 或 `running` 状态，`music_generate` 会返回现有任务状态，而不是启动新任务。使用 `action: "status"` 可显式检查状态，而不会触发新的生成。
## 配置
@ -177,12 +177,12 @@ openclaw tasks cancel <taskId>
生成音乐时，OpenClaw 会按以下顺序尝试提供商：
1. 工具调用中的 `model` 参数（如果智能体指定了该参数）
1. 工具调用中的 `model` 参数（如果智能体指定了）
2. 配置中的 `musicGenerationModel.primary`
3. 按顺序尝试 `musicGenerationModel.fallbacks`
4. 仅使用基于凭证的提供商默认值进行自动检测：
- 先尝试当前默认提供商
- 再按提供商 ID 顺序尝试其余已注册的音乐生成提供商
3. 按顺序使用 `musicGenerationModel.fallbacks`
4. 仅使用由鉴权支持的提供商默认值进行自动检测：
- 先使用当前默认提供商
- 然后按 provider-id 顺序使用其余已注册的音乐生成提供商
如果某个提供商失败，会自动尝试下一个候选项。如果全部失败，错误中会包含每次尝试的详情。
@ -190,16 +190,16 @@ openclaw tasks cancel <taskId>
## 提供商说明
- Google 使用 Lyria 3 批量生成。当前内置流程支持提示词、可选歌词文本以及可选参考图像。
- MiniMax 使用批量 `music_generation` 端点。当前内置流程支持提示词、可选歌词、器乐模式、时长控制以及 mp3 输出。
- ComfyUI 支持由工作流驱动，并取决于已配置的图以及提示词/输出字段的节点映射。
- Google 使用 Lyria 3 批量生成。当前内置流程支持提示词、可选歌词文本以及可选参考图片。
- MiniMax 使用批量 `music_generation` 端点。当前内置流程支持提示词、可选歌词、器乐模式、时长引导，以及通过 `minimax` API 密钥认证或 `minimax-portal` OAuth 输出 mp3。
- ComfyUI 支持由工作流驱动，并取决于所配置的图以及提示词/输出字段的节点映射。
## 提供商能力模式
共享音乐生成契约现在支持显式模式声明：
- `generate`：用于仅基于提示词的生成
- `edit`：当请求包含一个或多个参考图像时使用
- `generate` 用于仅基于提示词的生成
- `edit` 用于请求包含一张或多张参考图片时
新的提供商实现应优先使用显式模式块：
@ -219,17 +219,17 @@ capabilities: {
}
```
旧版扁平字段（如 `maxInputImages`、`supportsLyrics` 和 `supportsFormat`）不足以声明编辑支持。提供商应显式声明 `generate` 和 `edit`，以便实时测试、契约测试以及共享 `music_generate` 工具能够以确定性的方式验证模式支持。
旧版扁平字段（例如 `maxInputImages`、`supportsLyrics` 和 `supportsFormat`）不足以声明编辑支持。提供商应显式声明 `generate` 和 `edit`，以便实时测试、契约测试以及共享 `music_generate` 工具能够确定性地验证模式支持。
## 选择正确路径
## 选择合适的路径
- 当你需要模型选择、提供商故障转移以及内置的异步任务/状态流程时，请使用基于共享提供商的路径。
- 当你需要自定义工作流图或使用不属于共享内置音乐能力的提供商时，请使用插件路径，例如 ComfyUI。
- 如果你在调试 ComfyUI 特有行为，请参阅 [ComfyUI](/zh-CN/providers/comfy)。如果你在调试共享提供商行为，请从 [Google (Gemini)](/zh-CN/providers/google) 或 [MiniMax](/zh-CN/providers/minimax) 开始。
- 当你需要模型选择、提供商故障转移以及内置异步任务/状态流时，请使用由共享提供商支持的路径。
- 当你需要自定义工作流图，或需要共享内置音乐能力未包含的提供商时，请使用插件路径，例如 ComfyUI。
- 如果你在调试 ComfyUI 特定行为，请参见 [ComfyUI](/zh-CN/providers/comfy)。如果你在调试共享提供商行为，请先从 [Google (Gemini)](/zh-CN/providers/google) 或 [MiniMax](/zh-CN/providers/minimax) 开始。
## 实时测试
针对共享内置提供商的可选实时覆盖：
为共享内置提供商启用可选实时覆盖：
```bash
OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts
@ -241,28 +241,28 @@ OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.liv
pnpm test:live:media music
```
该实时测试文件会从 `~/.profile` 加载缺失的提供商环境变量，默认优先使用实时/环境 API 密钥，而不是已存储的凭证配置文件，并在提供商启用编辑模式时同时运行 `generate` 和已声明的 `edit` 覆盖。
这个实时测试文件会从 `~/.profile` 加载缺失的提供商环境变量，默认优先使用实时/环境 API 密钥而不是已存储的鉴权配置文件，并在提供商启用编辑模式时同时运行 `generate` 和已声明的 `edit` 覆盖。
目前这意味着：
- `google`：`generate` 加 `edit`
- `minimax`：仅 `generate`
- `comfy`：单独的 Comfy 实时覆盖，不在共享提供商扫描中
- `comfy`：单独的 Comfy 实时覆盖，不属于共享提供商扫描
针对内置 ComfyUI 音乐路径的可选实时覆盖：
为内置 ComfyUI 音乐路径启用可选实时覆盖：
```bash
OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts
```
如果这些部分已配置，Comfy 实时测试文件还会覆盖 comfy 图像和视频工作流。
当这些部分已配置时，Comfy 实时测试文件也会覆盖 Comfy 的图像和视频工作流。
## 相关内容
- [后台任务](/zh-CN/automation/tasks) - 用于分离式 `music_generate` 运行的任务跟踪
- [后台任务](/zh-CN/automation/tasks) - 分离式 `music_generate` 运行的任务跟踪
- [配置参考](/zh-CN/gateway/config-agents#agent-defaults) - `musicGenerationModel` 配置
- [ComfyUI](/zh-CN/providers/comfy)
- [Google（Gemini）](/zh-CN/providers/google)
- [Google (Gemini)](/zh-CN/providers/google)
- [MiniMax](/zh-CN/providers/minimax)
- [Models](/zh-CN/concepts/models) - 模型配置和故障转移
- [Models](/zh-CN/concepts/models) - 模型配置与故障转移
- [工具概览](/zh-CN/tools)

254
docs/zh-CN/tools/video-generation.md
View File

@ -6,10 +6,10 @@ read_when:
summary: 使用 14 个提供商后端从文本、图像或现有视频生成视频
title: 视频生成
x-i18n:
generated_at: "2026-04-25T17:32:16Z"
generated_at: "2026-04-25T20:33:42Z"
model: gpt-5.4
provider: openai
source_hash: f04c9ac25a0ad08036266ab0c61a6ddf41ad944f64aa273ba31e09fc5774ac74
source_hash: 83349231726cd65299733af1605e0d20ea69a50b35021a784943e5c597bf4eeb
source_path: tools/video-generation.md
workflow: 15
---
@ -17,21 +17,20 @@ x-i18n:
OpenClaw 智能体可以根据文本提示、参考图像或现有视频生成视频。支持 14 个提供商后端，每个后端具有不同的模型选项、输入模式和功能集。智能体会根据你的配置和可用的 API 密钥自动选择合适的提供商。
<Note>
只有在至少有一个视频生成提供商可用时，`video_generate` 工具才会显示。如果你在智能体工具中看不到它，请设置提供商 API 密钥或配置 `agents.defaults.videoGenerationModel`。
只有在至少有一个视频生成提供商可用时，`video_generate` 工具才会显示。如果你没有在智能体工具中看到它，请设置提供商 API 密钥或配置 `agents.defaults.videoGenerationModel`。
</Note>
OpenClaw 将视频生成视为三种运行时模式：
- `generate` 用于没有参考媒体的文生视频请求
- `imageToVideo` 用于请求包含一个或多个参考图像时
- `videoToVideo` 用于请求包含一个或多个参考视频时
- `generate`：用于没有参考媒体的文本生成视频请求
- `imageToVideo`：当请求包含一个或多个参考图像时使用
- `videoToVideo`：当请求包含一个或多个参考视频时使用
提供商可以支持这些模式中的任意子集。该工具会在提交前验证当前
模式，并在 `action=list` 中报告支持的模式。
提供商可以支持这些模式中的任意子集。工具会在提交前验证当前激活的模式，并在 `action=list` 中报告支持的模式。
## 快速开始
1. 为任一受支持的提供商设置 API 密钥：
1. 为任意受支持的提供商设置 API 密钥：
```bash
export GEMINI_API_KEY="your-key"
@ -45,39 +44,35 @@ openclaw config set agents.defaults.videoGenerationModel.primary "google/veo-3.1
3. 向智能体发出请求：
> 生成一个 5 秒钟的电影感视频，内容是一只友善的龙虾在日落时冲浪。
> 生成一个 5 秒钟的电影感视频，内容是一只友好的龙虾在日落时冲浪。
智能体会自动调用 `video_generate`。无需配置工具 allowlisting。
智能体会自动调用 `video_generate`。无需对工具进行 allowlisting。
## 当你生成视频时会发生什么
## 生成视频时会发生什么
视频生成是异步的。当智能体在会话中调用 `video_generate` 时：
视频生成是异步的。当智能体在一个会话中调用 `video_generate` 时：
1. OpenClaw 将请求提交给提供商，并立即返回一个任务 ID。
2. 提供商在后台处理该任务（通常为 30 秒到 5 分钟，取决于提供商和分辨率）。
3. 当视频准备好后，OpenClaw 会通过内部完成事件唤醒同一个会话。
4. 智能体会将生成完成的视频发回原始对话中。
1. OpenClaw 会将请求提交给提供商，并立即返回一个任务 ID。
2. 提供商会在后台处理该任务（通常需要 30 秒到 5 分钟，取决于提供商和分辨率）。
3. 当视频准备就绪时，OpenClaw 会通过内部完成事件唤醒同一个会话。
4. 智能体会将生成完成的视频发布回原始对话中。
当任务正在进行时，同一会话中的重复 `video_generate` 调用不会启动新的生成，而是返回当前任务状态。使用 `openclaw tasks list` 或 `openclaw tasks show <taskId>` 可从 CLI 检查进度。
当任务正在进行时，在同一会话中重复调用 `video_generate` 不会启动新的生成，而是返回当前任务状态。使用 `openclaw tasks list` 或 `openclaw tasks show <taskId>` 可通过 CLI 检查进度。
在非会话支持的智能体运行之外（例如，直接工具调用），该工具会回退为内联生成，并在同一轮返回最终媒体路径。
在非基于会话的智能体运行之外（例如直接调用工具时），该工具会回退为内联生成，并在同一轮返回最终媒体路径。
当提供商返回字节数据时，生成的视频文件会保存在 OpenClaw 管理的媒体存储中。
默认的生成视频保存上限遵循视频
媒体限制，而 `agents.defaults.mediaMaxMb` 可将其提高，以支持更大的渲染文件。
当提供商同时返回托管输出 URL 时，如果本地持久化拒绝保存过大的文件，OpenClaw 可以交付该 URL，
而不是让任务失败。
当提供商返回字节数据时，生成的视频文件会保存到由 OpenClaw 管理的媒体存储中。默认的生成视频保存上限遵循视频媒体限制，而 `agents.defaults.mediaMaxMb` 可将其提高以支持更大的渲染结果。当提供商还返回托管输出 URL 时，如果本地持久化因文件过大而被拒绝，OpenClaw 可以改为传递该 URL，而不是让任务失败。
### 任务生命周期
每个 `video_generate` 请求会经历四种状态：
每个 `video_generate` 请求都会经历四种状态：
1. **queued** -- 任务已创建，等待提供商接受。
2. **running** -- 提供商正在处理（通常为 30 秒到 5 分钟，取决于提供商和分辨率）。
3. **succeeded** -- 视频已准备好；智能体被唤醒并将其发送到对话中。
4. **failed** -- 提供商错误或超时；智能体被唤醒并附带错误详情。
1. **queued** -- 任务已创建，正在等待提供商接受。
2. **running** -- 提供商正在处理（通常需要 30 秒到 5 分钟，取决于提供商和分辨率）。
3. **succeeded** -- 视频已准备好；智能体会被唤醒并将其发布到对话中。
4. **failed** -- 提供商错误或超时；智能体会被唤醒并附带错误详情。
从 CLI 检查状态：
通过 CLI 检查状态：
```bash
openclaw tasks list
@ -85,12 +80,12 @@ openclaw tasks show <taskId>
openclaw tasks cancel <taskId>
```
防止重复：如果当前会话已有一个视频任务处于 `queued` 或 `running` 状态，`video_generate` 会返回现有任务状态，而不是启动新任务。使用 `action: "status"` 可显式检查状态，而不会触发新的生成。
重复防护：如果当前会话中已经有一个视频任务处于 `queued` 或 `running` 状态，`video_generate` 会返回现有任务状态，而不是启动新的任务。使用 `action: "status"` 可以显式检查状态，而不会触发新的生成。
## 支持的提供商
| 提供商 | 默认模型 | 文本 | 图像参考 | 视频参考 | API 密钥 |
| ----- | ------------------------------- | ---- | ---------------------------------------------------- | ---------------- | ---------------------------------------- |
| ------ | -------- | ---- | -------- | -------- | -------- |
| Alibaba | `wan2.6-t2v` | 是 | 是（远程 URL） | 是（远程 URL） | `MODELSTUDIO_API_KEY` |
| BytePlus（1.0） | `seedance-1-0-pro-250528` | 是 | 最多 2 张图像（仅限 I2V 模型；首帧 + 末帧） | 否 | `BYTEPLUS_API_KEY` |
| BytePlus Seedance 1.5 | `seedance-1-5-pro-251215` | 是 | 最多 2 张图像（通过 role 指定首帧 + 末帧） | 否 | `BYTEPLUS_API_KEY` |
@ -98,7 +93,7 @@ openclaw tasks cancel <taskId>
| ComfyUI | `workflow` | 是 | 1 张图像 | 否 | `COMFY_API_KEY` 或 `COMFY_CLOUD_API_KEY` |
| fal | `fal-ai/minimax/video-01-live` | 是 | 1 张图像 | 否 | `FAL_KEY` |
| Google | `veo-3.1-fast-generate-preview` | 是 | 1 张图像 | 1 个视频 | `GEMINI_API_KEY` |
| MiniMax | `MiniMax-Hailuo-2.3` | 是 | 1 张图像 | 否 | `MINIMAX_API_KEY` |
| MiniMax | `MiniMax-Hailuo-2.3` | 是 | 1 张图像 | 否 | `MINIMAX_API_KEY` 或 MiniMax OAuth |
| OpenAI | `sora-2` | 是 | 1 张图像 | 1 个视频 | `OPENAI_API_KEY` |
| Qwen | `wan2.6-t2v` | 是 | 是（远程 URL） | 是（远程 URL） | `QWEN_API_KEY` |
| Runway | `gen4.5` | 是 | 1 张图像 | 1 个视频 | `RUNWAYML_API_SECRET` |
@ -106,132 +101,105 @@ openclaw tasks cancel <taskId>
| Vydra | `veo3` | 是 | 1 张图像（`kling`） | 否 | `VYDRA_API_KEY` |
| xAI | `grok-imagine-video` | 是 | 1 张首帧图像或最多 7 张 `reference_image` | 1 个视频 | `XAI_API_KEY` |
某些提供商接受额外或替代的 API 密钥环境变量。详情请参阅各自的[提供商页面](#related)。
某些提供商接受额外或替代的 API 密钥环境变量。详情请参阅各个[提供商页面](#related)。
运行 `video_generate action=list`，可在运行时检查可用提供商、模型和
运行时模式。
运行 `video_generate action=list` 可在运行时检查可用的提供商、模型和运行时模式。
### 声明的能力矩阵
### 已声明的能力矩阵
这是 `video_generate`、契约测试
以及共享实时扫描所使用的显式模式契约。
这是 `video_generate`、契约测试以及共享实时 sweep 使用的显式模式契约。
| 提供商 | `generate` | `imageToVideo` | `videoToVideo` | 当前共享实时通道 |
| -------- | ---------- | -------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| 提供商 | `generate` | `imageToVideo` | `videoToVideo` | 当前共享实时 lanes |
| ------ | ---------- | -------------- | -------------- | ------------------ |
| Alibaba | 是 | 是 | 是 | `generate`、`imageToVideo`；`videoToVideo` 已跳过，因为该提供商需要远程 `http(s)` 视频 URL |
| BytePlus | 是 | 是 | 否 | `generate`、`imageToVideo` |
| ComfyUI | 是 | 是 | 否 | 不在共享扫描中；特定于 workflow 的覆盖由 Comfy 测试负责 |
| ComfyUI | 是 | 是 | 否 | 不在共享 sweep 中；特定于 workflow 的覆盖范围位于 Comfy 测试中 |
| fal | 是 | 是 | 否 | `generate`、`imageToVideo` |
| Google | 是 | 是 | 是 | `generate`、`imageToVideo`；共享 `videoToVideo` 已跳过，因为当前基于缓冲区的 Gemini / Veo 扫描不接受该输入 |
| Google | 是 | 是 | 是 | `generate`、`imageToVideo`；共享 `videoToVideo` 已跳过，因为当前基于缓冲区的 Gemini/Veo sweep 不接受该输入 |
| MiniMax | 是 | 是 | 否 | `generate`、`imageToVideo` |
| OpenAI | 是 | 是 | 是 | `generate`、`imageToVideo`；共享 `videoToVideo` 已跳过，因为当前这个组织 / 输入路径需要提供商侧 inpaint / remix 访问 |
| OpenAI | 是 | 是 | 是 | `generate`、`imageToVideo`；共享 `videoToVideo` 已跳过，因为当前这个组织 / 输入路径需要提供商侧的 inpaint/remix 访问 |
| Qwen | 是 | 是 | 是 | `generate`、`imageToVideo`；`videoToVideo` 已跳过，因为该提供商需要远程 `http(s)` 视频 URL |
| Runway | 是 | 是 | 是 | `generate`、`imageToVideo`；仅当所选模型为 `runway/gen4_aleph` 时才运行 `videoToVideo` |
| Together | 是 | 是 | 否 | `generate`、`imageToVideo` |
| Vydra | 是 | 是 | 否 | `generate`；共享 `imageToVideo` 已跳过，因为内置 `veo3` 仅支持文本，而内置 `kling` 需要远程图像 URL |
| Vydra | 是 | 是 | 否 | `generate`；共享 `imageToVideo` 已跳过，因为内置的 `veo3` 仅支持文本，且内置的 `kling` 需要远程图像 URL |
| xAI | 是 | 是 | 是 | `generate`、`imageToVideo`；`videoToVideo` 已跳过，因为该提供商当前需要远程 MP4 URL |
## 工具参数
### 必填
### 必需参数
| 参数 | 类型 | 说明 |
| --------- | ------ | ----------------------------------------------------------------------------- |
| `prompt` | string | 要生成视频的文本描述（`action: "generate"` 时必填） |
| 参数 | 类型 | 描述 |
| ---- | ---- | ---- |
| `prompt` | string | 要生成的视频的文本描述（`action: "generate"` 时必需） |
### 内容输入
| 参数 | 类型 | 说明 |
| ------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| 参数 | 类型 | 描述 |
| ---- | ---- | ---- |
| `image` | string | 单个参考图像（路径或 URL） |
| `images` | string[] | 多个参考图像（最多 9 张） |
| `imageRoles` | string[] | 可选的逐位置角色提示，与合并后的图像列表并行。规范值：`first_frame`、`last_frame`、`reference_image` |
| `imageRoles` | string[] | 与合并后的图像列表按位置对应的可选角色提示。规范值：`first_frame`、`last_frame`、`reference_image` |
| `video` | string | 单个参考视频（路径或 URL） |
| `videos` | string[] | 多个参考视频（最多 4 个） |
| `videoRoles` | string[] | 可选的逐位置角色提示，与合并后的视频列表并行。规范值：`reference_video` |
| `audioRef` | string | 单个参考音频（路径或 URL）。当提供商支持音频输入时，可用于背景音乐或语音参考等场景 |
| `videoRoles` | string[] | 与合并后的视频列表按位置对应的可选角色提示。规范值：`reference_video` |
| `audioRef` | string | 单个参考音频（路径或 URL）。例如在提供商支持音频输入时，用作背景音乐或语音参考 |
| `audioRefs` | string[] | 多个参考音频（最多 3 个） |
| `audioRoles` | string[] | 可选的逐位置角色提示，与合并后的音频列表并行。规范值：`reference_audio` |
| `audioRoles` | string[] | 与合并后的音频列表按位置对应的可选角色提示。规范值：`reference_audio` |
角色提示会按原样转发给提供商。规范值来自
`VideoGenerationAssetRole` 联合类型，但提供商可能接受额外的
角色字符串。`*Roles` 数组的条目数不能多于
对应的参考列表；这类 off-by-one 错误会以清晰的错误信息失败。
使用空字符串可让某个位置保持未设置。对于 xAI，将每个图像角色都设为
`reference_image` 可使用其 `reference_images` 生成模式；如果是单图 image-to-video，
则省略该角色或使用 `first_frame`。
角色提示会按原样转发给提供商。规范值来自 `VideoGenerationAssetRole` 联合类型，但提供商也可能接受其他角色字符串。`*Roles` 数组的条目数不得多于对应的参考列表；如果出现多一位或少一位之类的错误，会以清晰的错误信息失败。使用空字符串可让某个位置保持未设置。对于 xAI，将每个图像角色都设置为 `reference_image` 可使用其 `reference_images` 生成模式；对于单图像图生视频，请省略该角色或使用 `first_frame`。
### 风格控制
| 参数 | 类型 | 说明 |
| ----------------- | ------- | --------------------------------------------------------------------------------------- |
| 参数 | 类型 | 描述 |
| ---- | ---- | ---- |
| `aspectRatio` | string | `1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9`、`21:9` 或 `adaptive` |
| `resolution` | string | `480P`、`720P`、`768P` 或 `1080P` |
| `durationSeconds` | number | 目标时长（秒）（会四舍五入到最接近的提供商支持值） |
| `size` | string | 当提供商支持时使用的尺寸提示 |
| `audio` | boolean | 在支持时启用输出中的生成音频。与 `audioRef*`（输入）不同 |
| `audio` | boolean | 在支持时为输出启用生成音频。与 `audioRef*`（输入）不同 |
| `watermark` | boolean | 在支持时切换提供商水印 |
`adaptive` 是一个提供商特定的哨兵值：它会按原样转发给
那些在其能力声明中包含 `adaptive` 的提供商（例如 BytePlus
Seedance 会用它根据输入图像
尺寸自动检测比例）。未声明该值的提供商会通过
工具结果中的 `details.ignoredOverrides` 显示此值，从而让该丢弃行为可见。
`adaptive` 是一个特定于提供商的哨兵值：它会按原样转发给在其能力声明中包含 `adaptive` 的提供商（例如 BytePlus Seedance 会用它根据输入图像尺寸自动检测比例）。对于未声明该能力的提供商，工具结果会通过 `details.ignoredOverrides` 显示该值，以便明确知道该覆盖项已被丢弃。
### 高级
### 高级参数
| 参数 | 类型 | 说明 |
| ----------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 参数 | 类型 | 描述 |
| ---- | ---- | ---- |
| `action` | string | `"generate"`（默认）、`"status"` 或 `"list"` |
| `model` | string | 提供商 / 模型覆盖（例如 `runway/gen4.5`） |
| `filename` | string | 输出文件名提示 |
| `timeoutMs` | number | 可选的提供商请求超时时间（毫秒） |
| `providerOptions` | object | 以 JSON 对象形式传递的提供商特定选项（例如 `{"seed": 42, "draft": true}`）。声明了类型化 schema 的提供商会验证键名和类型；未知键名或类型不匹配会在回退期间跳过该候选项。未声明 schema 的提供商会按原样接收这些选项。运行 `video_generate action=list` 可查看各提供商接受哪些选项 |
| `timeoutMs` | number | 可选的提供商请求超时（毫秒） |
| `providerOptions` | object | 以 JSON 对象形式传递的提供商特定选项（例如 `{"seed": 42, "draft": true}`）。声明了类型化 schema 的提供商会验证键名和类型；未知键名或类型不匹配会导致该候选项在回退时被跳过。未声明 schema 的提供商会按原样接收这些选项。运行 `video_generate action=list` 可查看各提供商接受哪些选项 |
并非所有提供商都支持所有参数。OpenClaw 已经会将时长规范化为最接近的提供商支持值，并且当回退提供商暴露出不同的控制面时，它还会重映射诸如 size 到 aspect-ratio 的几何提示。真正不受支持的覆盖项会尽力忽略，并在工具结果中作为警告报告。硬性能力限制（例如参考输入过多）会在提交前失败。
并非所有提供商都支持所有参数。OpenClaw 已经会将时长规范化为最接近的提供商支持值，并且当回退提供商暴露出不同的控制接口时，也会重映射已翻译的几何提示，例如 size 到 aspect ratio。真正不受支持的覆盖项会尽最大努力被忽略，并在工具结果中作为警告报告。硬性能力限制（例如参考输入过多）会在提交前直接失败。
工具结果会报告实际应用的设置。当 OpenClaw 在提供商回退期间重映射时长或几何设置时，返回的 `durationSeconds`、`size`、`aspectRatio` 和 `resolution` 值反映的是实际提交的内容，而 `details.normalization` 会记录从请求值到应用值的转换。
工具结果会报告实际应用的设置。当 OpenClaw 在提供商回退期间重映射时长或几何参数时，返回的 `durationSeconds`、`size`、`aspectRatio` 和 `resolution` 值会反映实际提交的内容，而 `details.normalization` 会记录从请求值到应用值的转换。
参考输入也会决定运行时模式：
- 无参考媒体：`generate`
- 有任意图像参考：`imageToVideo`
- 有任意视频参考：`videoToVideo`
- 参考音频输入不会改变解析后的模式；它们是在图像 / 视频参考所选模式之上附加应用的，并且只对声明了 `maxInputAudios` 的提供商有效
- 任意图像参考：`imageToVideo`
- 任意视频参考：`videoToVideo`
- 参考音频输入不会改变已解析的模式；它们会叠加在图像 / 视频参考所选择的模式之上，并且仅适用于声明了 `maxInputAudios` 的提供商
混合使用图像和视频参考并不是稳定的共享能力面。
建议每个请求只使用一种参考类型。
图像参考和视频参考混合使用并不是一个稳定的共享能力接口。
建议每次请求只使用一种参考类型。
#### 回退和类型化选项
某些能力检查是在回退层而不是
工具边界处应用的，这样超出主提供商限制的请求
仍然可以在有能力的回退提供商上运行：
某些能力检查是在回退层而不是工具边界执行的，这样即使请求超出了主提供商的限制，也仍然可以在具备能力的回退提供商上运行：
- 如果活动候选项未声明 `maxInputAudios`（或将其声明为
`0`），当请求包含音频参考时会跳过该候选项，并尝试
下一个候选项。
- 如果活动候选项的 `maxDurationSeconds` 小于请求的
`durationSeconds`，并且该候选项未声明
`supportedDurationSeconds` 列表，则会被跳过。
- 如果请求包含 `providerOptions`，且活动候选项
显式声明了类型化的 `providerOptions` schema，那么当提供的键名不在 schema 中或值类型
不匹配时，该候选项会被跳过。尚未声明 schema 的提供商会按原样接收
这些选项（向后兼容的直通行为）。提供商也可以
通过声明空 schema
（`capabilities.providerOptions: {}`）显式选择不接受任何提供商选项，这会导致与
类型不匹配相同的跳过行为。
- 如果当前候选项未声明 `maxInputAudios`（或将其声明为 `0`），并且请求中包含音频参考，则该候选项会被跳过，并尝试下一个候选项。
- 如果当前候选项的 `maxDurationSeconds` 低于请求的 `durationSeconds`，并且该候选项未声明 `supportedDurationSeconds` 列表，则该候选项会被跳过。
- 如果请求包含 `providerOptions`，并且当前候选项显式声明了类型化的 `providerOptions` schema，那么当提供的键名不在 schema 中或值类型不匹配时，该候选项会被跳过。尚未声明 schema 的提供商会按原样接收这些选项（向后兼容的透传）。提供商也可以通过声明空 schema（`capabilities.providerOptions: {}`）来显式拒绝所有 provider 选项，这会导致与类型不匹配相同的跳过行为。
请求中的第一个跳过原因会以 `warn` 级别记录，因此运维人员可以看到
主提供商何时被略过；后续跳过则记录为
`debug`，以避免较长的回退链产生过多日志。如果每个候选项都被跳过，
汇总错误会包含每一项的跳过原因。
请求中的第一个跳过原因会以 `warn` 级别记录，这样运维人员就能看到为什么主提供商被跳过；后续跳过原因则以 `debug` 级别记录，以避免长回退链产生过多噪音。如果所有候选项都被跳过，汇总错误会包含每个候选项的跳过原因。
## 操作
- **generate**（默认）-- 根据给定提示和可选参考输入创建视频。
- **generate**（默认）-- 根据给定提示词和可选参考输入创建视频。
- **status** -- 检查当前会话中正在进行的视频任务状态，而不启动新的生成。
- **list** -- 显示可用提供商、模型及其能力。
- **list** -- 显示可用的提供商、模型及其能力。
## 模型选择
@ -240,12 +208,11 @@ Seedance 会用它根据输入图像
1. **`model` 工具参数** -- 如果智能体在调用中指定了它。
2. **`videoGenerationModel.primary`** -- 来自配置。
3. **`videoGenerationModel.fallbacks`** -- 按顺序尝试。
4. **自动检测** -- 使用具有有效凭证验证的提供商，先从当前默认提供商开始，然后按字母顺序尝试其余提供商。
4. **自动检测** -- 使用具有有效认证信息的提供商，先从当前默认提供商开始，然后按字母顺序尝试其余提供商。
如果某个提供商失败，会自动尝试下一个候选项。如果所有候选项都失败，错误中会包含每次尝试的详情。
如果某个提供商失败，会自动尝试下一个候选项。如果所有候选项都失败，错误信息会包含每次尝试的详细信息。
如果你希望视频生成只使用显式的 `model`、`primary` 和 `fallbacks`
条目，请设置 `agents.defaults.mediaGenerationAutoProviderFallback: false`。
如果你希望视频生成仅使用显式的 `model`、`primary` 和 `fallbacks` 条目，请设置 `agents.defaults.mediaGenerationAutoProviderFallback: false`。
```json5
{
@ -267,81 +234,79 @@ Seedance 会用它根据输入图像
使用 DashScope / Model Studio 异步端点。参考图像和视频必须是远程 `http(s)` URL。
</Accordion>
<Accordion title="BytePlus（1.0）">
<Accordion title="BytePlus (1.0)">
提供商 id：`byteplus`。
模型：`seedance-1-0-pro-250528`（默认）、`seedance-1-0-pro-t2v-250528`、`seedance-1-0-pro-fast-251015`、`seedance-1-0-lite-t2v-250428`、`seedance-1-0-lite-i2v-250428`。
T2V 模型（`*-t2v-*`）不接受图像输入；I2V 模型和通用 `*-pro-*` 模型支持单个参考图像（首帧）。可按位置传递图像，或设置 `role: "first_frame"`。当提供图像时，T2V 模型 ID 会自动切换为对应的 I2V 变体。
T2V 模型（`*-t2v-*`）不接受图像输入；I2V 模型和通用 `*-pro-*` 模型支持单张参考图像（首帧）。可按位置传入图像，或设置 `role: "first_frame"`。当提供图像时，T2V 模型 ID 会自动切换为对应的 I2V 变体。
支持的 `providerOptions` 键名：`seed`（number）、`draft`（boolean —— 强制为 480p）、`camera_fixed`（boolean）。
支持的 `providerOptions` 键名：`seed`（number）、`draft`（boolean — 强制 480p）、`camera_fixed`（boolean）。
</Accordion>
<Accordion title="BytePlus Seedance 1.5">
需要 [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark) 插件。提供商 id：`byteplus-seedance15`。模型：`seedance-1-5-pro-251215`。
使用统一的 `content[]` API。最多支持 2 张输入图像（`first_frame` + `last_frame`）。所有输入都必须是远程 `https://` URL。请在每张图像上设置 `role: "first_frame"` / `"last_frame"`，或按位置传递图像。
使用统一的 `content[]` API。最多支持 2 张输入图像（`first_frame` + `last_frame`）。所有输入都必须是远程 `https://` URL。为每张图像设置 `role: "first_frame"` / `"last_frame"`，或按位置传入图像。
`aspectRatio: "adaptive"` 会根据输入图像自动检测比例。`audio: true` 会映射到 `generate_audio`。`providerOptions.seed`（number）会被转发。
`aspectRatio: "adaptive"` 会根据输入图像自动检测比例。`audio: true` 会映射为 `generate_audio`。`providerOptions.seed`（number）会被转发。
</Accordion>
<Accordion title="BytePlus Seedance 2.0">
需要 [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark) 插件。提供商 id：`byteplus-seedance2`。模型：`dreamina-seedance-2-0-260128`、`dreamina-seedance-2-0-fast-260128`。
使用统一的 `content[]` API。最多支持 9 张参考图像、3 个参考视频和 3 个参考音频。所有输入都必须是远程 `https://` URL。请为每个资源设置 `role` —— 支持的值为：`"first_frame"`、`"last_frame"`、`"reference_image"`、`"reference_video"`、`"reference_audio"`。
使用统一的 `content[]` API。最多支持 9 张参考图像、3 个参考视频和 3 个参考音频。所有输入都必须是远程 `https://` URL。为每个资源设置 `role` —— 支持的值：`"first_frame"`、`"last_frame"`、`"reference_image"`、`"reference_video"`、`"reference_audio"`。
`aspectRatio: "adaptive"` 会根据输入图像自动检测比例。`audio: true` 会映射到 `generate_audio`。`providerOptions.seed`（number）会被转发。
`aspectRatio: "adaptive"` 会根据输入图像自动检测比例。`audio: true` 会映射为 `generate_audio`。`providerOptions.seed`（number）会被转发。
</Accordion>
<Accordion title="ComfyUI">
基于工作流的本地或云端执行。通过已配置图表支持文生视频和图生视频。
由 workflow 驱动的本地或云端执行。通过已配置的图表支持文本生成视频和图像生成视频。
</Accordion>
<Accordion title="fal">
对长时间运行任务使用基于队列的流程。仅支持单张参考图像。
对长时间运行的任务使用基于队列的流程。仅支持单张图像参考。
</Accordion>
<Accordion title="Google（Gemini / Veo）">
支持一张图像或一个视频参考。
<Accordion title="Google (Gemini / Veo)">
支持一个图像参考或一个视频参考。
</Accordion>
<Accordion title="MiniMax">
仅支持单张参考图像。
仅支持单张图像参考。
</Accordion>
<Accordion title="OpenAI">
仅转发 `size` 覆盖项。其他风格覆盖项（`aspectRatio`、`resolution`、`audio`、`watermark`）会被忽略，并给出警告。
仅转发 `size` 覆盖项。其他风格覆盖项（`aspectRatio`、`resolution`、`audio`、`watermark`）会被忽略并给出警告。
</Accordion>
<Accordion title="Qwen">
与 Alibaba 使用相同的 DashScope 后端。参考输入必须是远程 `http(s)` URL；本地文件会在前置检查时被拒绝。
与 Alibaba 使用相同的 DashScope 后端。参考输入必须是远程 `http(s)` URL；本地文件会在前置阶段被拒绝。
</Accordion>
<Accordion title="Runway">
通过 data URI 支持本地文件。视频转视频需要 `runway/gen4_aleph`。纯文本运行暴露 `16:9` 和 `9:16` 两种宽高比。
通过 data URI 支持本地文件。视频生成视频需要 `runway/gen4_aleph`。纯文本运行支持 `16:9` 和 `9:16` 宽高比。
</Accordion>
<Accordion title="Together">
仅支持单张参考图像。
仅支持单张图像参考。
</Accordion>
<Accordion title="Vydra">
直接使用 `https://www.vydra.ai/api/v1` 以避免凭证验证在重定向过程中丢失。内置 `veo3` 仅支持文生视频；`kling` 需要远程图像 URL。
直接使用 `https://www.vydra.ai/api/v1` 以避免认证信息在重定向中丢失。内置 `veo3` 仅支持文本生成视频；`kling` 需要远程图像 URL。
</Accordion>
<Accordion title="xAI">
支持文生视频、单张首帧图像的图生视频、通过 xAI `reference_images` 使用最多 7 个 `reference_image` 输入，以及远程视频编辑 / 扩展流程。
支持文本生成视频、单张首帧图像生成视频、通过 xAI `reference_images` 最多使用 7 个 `reference_image` 输入，以及远程视频编辑 / 扩展流程。
</Accordion>
</AccordionGroup>
## 提供商能力模式
共享视频生成契约现在允许提供商声明按模式区分的
能力，而不只是扁平的聚合限制。新的提供商
实现应优先使用显式模式块：
共享视频生成契约现在允许提供商声明特定于模式的能力，而不再仅仅是扁平化的聚合限制。新的提供商实现应优先使用显式模式块：
```typescript
capabilities: {
@ -365,14 +330,11 @@ capabilities: {
}
```
像 `maxInputImages` 和 `maxInputVideos` 这样的扁平聚合字段
不足以声明转换模式支持。提供商应显式声明
`generate`、`imageToVideo` 和 `videoToVideo`，这样实时测试、
契约测试以及共享的 `video_generate` 工具才能以确定性的方式验证模式支持。
像 `maxInputImages` 和 `maxInputVideos` 这样的扁平聚合字段，不足以表明支持变换模式。提供商应显式声明 `generate`、`imageToVideo` 和 `videoToVideo`，这样实时测试、契约测试以及共享的 `video_generate` 工具才能以确定性的方式验证模式支持情况。
## 实时测试
针对共享内置提供商的可选加入式实时覆盖：
为共享内置提供商启用可选的实时覆盖：
```bash
OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts
@ -384,31 +346,27 @@ OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.liv
pnpm test:live:media video
```
此实时文件会从 `~/.profile` 加载缺失的提供商环境变量，默认优先使用
实时 / 环境 API 密钥而不是已存储的 auth profiles，并默认运行一个
发布安全的冒烟测试：
此实时测试文件会从 `~/.profile` 加载缺失的提供商环境变量，默认优先使用实时 / 环境 API 密钥，而不是已存储的认证配置文件，并且默认运行一个适合发布的 smoke 测试：
- 对扫描中的每个非 FAL 提供商运行 `generate`
- 对 sweep 中每个非 FAL 提供商运行 `generate`
- 使用一秒钟的龙虾提示词
- 每个提供商的操作上限由 `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS`
控制（默认值为 `180000`）
- 每个提供商的操作上限由 `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` 控制
（默认值为 `180000`）
FAL 为可选加入，因为提供商侧队列延迟可能主导发布时间：
FAL 是选择性启用的，因为提供商侧的队列延迟可能会主导发布时间：
```bash
pnpm test:live:media video --video-providers fal
```
设置 `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`，还可运行共享扫描能够安全使用本地媒体执行的已声明转换
模式：
设置 `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`，还会运行共享 sweep 能够安全使用本地媒体进行测试的已声明变换模式：
- 当 `capabilities.imageToVideo.enabled` 为真时运行 `imageToVideo`
- 当 `capabilities.videoToVideo.enabled` 为真且该提供商 / 模型
在共享扫描中接受基于缓冲区的本地视频输入时运行 `videoToVideo`
- 当 `capabilities.imageToVideo.enabled` 时运行 `imageToVideo`
- 当 `capabilities.videoToVideo.enabled` 且提供商 / 模型在共享 sweep 中接受基于缓冲区的本地视频输入时运行 `videoToVideo`
目前共享的 `videoToVideo` 实时通道覆盖：
目前，共享 `videoToVideo` 实时 lane 覆盖：
- 仅 `runway`，且前提是你选择了 `runway/gen4_aleph`
- 仅 `runway`，并且你选择了 `runway/gen4_aleph` 时
## 配置