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-06 18:19:16 +00:00
parent a70cdec5cc
commit 63d7d19dc2
3 changed files with 575 additions and 529 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

File diff suppressed because it is too large Load Diff

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

@ -1,40 +1,35 @@
---
read_when:
- 通过智能体生成音乐或音频时
- 配置音乐生成提供商和模型时
- 了解 `music_generate` 工具参数时
- 通过智能体生成音乐或音频
- 配置音乐生成提供商和模型
- 了解 `music_generate` 工具参数
summary: 使用共享提供商生成音乐，包括基于工作流的插件
title: 音乐生成
x-i18n:
generated_at: "2026-04-06T15:32:12Z"
generated_at: "2026-04-06T18:17:26Z"
model: gpt-5.4
provider: openai
source_hash: 5a2c95d087d6d0b5f4aaaae2fc1f98d683cbb4991d08ed6cabae45c90519ec0c
source_hash: a7af06f64efde518934e1408837a9c4bfc52710a6b5d39225eee9889d7b86030
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. 可选地设置你的首选模型：
1. 为至少一个提供商设置 API 密钥，例如 `GEMINI_API_KEY` 或 `MINIMAX_API_KEY`。
2. 可选：设置你偏好的模型：
```json5
{
@ -48,12 +43,11 @@ MiniMax，以及通过工作流配置的 ComfyUI。
}
```
3. 向智能体提问：_“生成一段关于夜晚驾车穿过霓虹都市的轻快 synthpop 音轨。”_
3. 向智能体提问：_“生成一段关于夜间驾驶穿越霓虹城市的欢快 synthpop 音轨。”_
智能体会自动调用 `music_generate`。不需要工具允许列表。
智能体会自动调用 `music_generate`。无需为工具配置允许列表。
对于没有基于会话的智能体运行的直接同步上下文，内置
工具仍会回退为内联生成，并在工具结果中返回最终媒体路径。
对于没有会话支持的智能体运行的直接同步上下文，内置工具仍会回退为内联生成，并在工具结果中返回最终媒体路径。
示例提示词：
@ -65,15 +59,13 @@ Generate a cinematic piano track with soft strings and no vocals.
Generate an energetic chiptune loop about launching a rocket at sunrise.
```
### 基于工作流的 Comfy 生成
### 工作流驱动的 Comfy 生成
内置的 `comfy` 插件通过
音乐生成提供商注册表接入共享的 `music_generate` 工具。
内置的 `comfy` 插件通过音乐生成提供商注册表接入共享的 `music_generate` 工具。
1. 配置 `models.providers.comfy.music`，包含工作流 JSON 以及
prompt/output 节点。
1. 为 `models.providers.comfy.music` 配置工作流 JSON 以及提示词/输出节点。
2. 如果你使用 Comfy Cloud，请设置 `COMFY_API_KEY` 或 `COMFY_CLOUD_API_KEY`。
3. 请求智能体生成音乐，或直接调用该工具。
3. 向智能体请求音乐，或直接调用该工具。
示例：
@ -83,22 +75,21 @@ 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` |
| 提供商 | 默认模型 | 参考输入 | 支持的控制项 | 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.5+` | 无 | `lyrics`、`instrumental`、`durationSeconds`、`format=mp3` | `MINIMAX_API_KEY` |
### 已声明的能力矩阵
### 声明式能力矩阵
这是 `music_generate`、契约测试
和共享 live 扫描使用的显式模式契约。
这是 `music_generate`、契约测试以及共享实时扫描所使用的显式模式契约。
| 提供商 | `generate` | `edit` | 编辑上限 | 共享 live lane |
| -------- | ---------- | ------ | ---------- | ------------------------------------------------------------------------- |
| 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"` 可在运行时查看可用的共享提供商和模型：
@ -106,7 +97,7 @@ Generate an energetic chiptune loop about launching a rocket at sunrise.
/tool music_generate action=list
```
使用 `action: "status"` 可查看当前基于会话的音乐任务：
使用 `action: "status"` 可查看当前由会话支持的音乐任务状态：
```text
/tool music_generate action=status
@ -120,42 +111,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 | 当提供商支持时长提示时，目标时长（秒） |
| `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 | 当提供商支持时长提示时，以秒为单位的目标时长 |
| `format` | string | 当提供商支持时的输出格式提示（`mp3` 或 `wav`） |
| `filename` | string | 输出文件名提示 |
并非所有提供商都支持所有参数。OpenClaw 仍会在提交前验证诸如输入数量之类的硬性限制，
但如果所选提供商或模型无法满足某些可选提示，这些提示会被忽略，并给出警告。
并非所有提供商都支持所有参数。OpenClaw 在提交前仍会验证输入数量等硬性限制，但当所选提供商或模型无法满足时，不支持的可选提示会被忽略，并附带警告。
## 共享提供商路径的异步行为
## 共享提供商支持路径的异步行为
- 基于会话的智能体运行：`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** —— 音轨已就绪；智能体被唤醒并将其发布到会话中。
4. **failed** —— 提供商错误或超时；智能体会带着错误详情被唤醒。
1. **queued** -- 任务已创建，等待提供商接受。
2. **running** -- 提供商正在处理（通常为 30 秒到 3 分钟，取决于提供商和时长）。
3. **succeeded** -- 音轨已准备好；智能体被唤醒并将其发布到对话中。
4. **failed** -- 提供商错误或超时；智能体被唤醒并附带错误详情。
从 CLI 检查状态：
通过 CLI 查看状态：
```bash
openclaw tasks list
@ -163,7 +153,7 @@ openclaw tasks show <taskId>
openclaw tasks cancel <taskId>
```
重复防护：如果当前会话已有音乐任务处于 `queued` 或 `running` 状态，`music_generate` 会返回现有任务状态，而不是启动新任务。使用 `action: "status"` 可显式检查，而不会触发新生成。
防重复：如果当前会话的音乐任务已处于 `queued` 或 `running` 状态，`music_generate` 会返回现有任务状态，而不是启动新的任务。使用 `action: "status"` 可在不触发新生成的情况下显式查看状态。
## 配置
@ -186,32 +176,27 @@ openclaw tasks cancel <taskId>
生成音乐时，OpenClaw 会按以下顺序尝试提供商：
1. 工具调用中的 `model` 参数（如果智能体显式指定）
1. 工具调用中的 `model` 参数（如果智能体指定了它）
2. 配置中的 `musicGenerationModel.primary`
3. 按顺序使用 `musicGenerationModel.fallbacks`
4. 仅使用基于认证的提供商默认值进行自动检测：
- 先尝试当前默认提供商
- 再按提供商 id 顺序尝试其余已注册的音乐生成提供商
4. 仅使用基于凭证支持的提供商默认值进行自动检测：
- 当前默认提供商优先
- 其余已注册的音乐生成提供商，按 provider id 顺序
如果某个提供商失败，会自动尝试下一个候选项。如果全部失败，
错误中会包含每次尝试的详细信息。
如果某个提供商失败，会自动尝试下一个候选项。如果全部失败，错误中会包含每次尝试的详细信息。
## 提供商说明
- Google 使用 Lyria 3 批量生成。当前内置流程支持
prompt、可选歌词文本和可选参考图像。
- MiniMax 使用批量 `music_generation` 端点。当前内置流程
支持 prompt、可选歌词、器乐模式、时长引导以及
mp3 输出。
- ComfyUI 支持基于工作流驱动，并取决于所配置的图以及
prompt/output 字段的节点映射。
- Google 使用 Lyria 3 批量生成。当前内置流程支持提示词、可选歌词文本和可选参考图片。
- MiniMax 使用批量 `music_generation` 端点。当前内置流程支持提示词、可选歌词、器乐模式、时长控制和 mp3 输出。
- ComfyUI 支持由工作流驱动，取决于已配置的图以及提示词/输出字段的节点映射。
## 提供商能力模式
共享音乐生成契约现在支持显式模式声明：
- `generate` 用于仅基于提示词的生成
- 当请求包含一张或多张参考图像时，使用 `edit`
- 当请求包含一张或多张参考图片时使用 `edit`
新的提供商实现应优先使用显式模式块：
@ -231,49 +216,50 @@ capabilities: {
}
```
旧版平铺字段，例如 `maxInputImages`、`supportsLyrics` 和
`supportsFormat`，不足以宣告编辑支持。提供商应
显式声明 `generate` 和 `edit`，这样 live 测试、契约测试以及
共享的 `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](/zh-CN/providers/comfy)。如果你正在调试共享提供商行为，请从 [Google (Gemini)](/zh-CN/providers/google) 或 [MiniMax](/zh-CN/providers/minimax) 开始。
## Live 测试
## 实时测试
针对共享内置提供商的按需启用 live 覆盖：
共享内置提供商的选择加入式实时覆盖：
```bash
OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts
```
该 live 文件会从 `~/.profile` 加载缺失的提供商环境变量，默认优先使用
live/env API 密钥而不是已存储的认证 profile，并在提供商启用编辑模式时同时运行
`generate` 和已声明的 `edit` 覆盖。
仓库包装命令：
```bash
pnpm test:live:media music
```
此实时测试文件会从 `~/.profile` 加载缺失的提供商环境变量，默认优先使用实时/环境 API 密钥而不是已存储的凭证配置，并在提供商启用编辑模式时同时运行 `generate` 和已声明的 `edit` 覆盖。
当前这意味着：
- `google`：`generate` 加 `edit`
- `minimax`：仅 `generate`
- `comfy`：单独的 Comfy live 覆盖，不属于共享提供商扫描
- `google`: `generate` 加 `edit`
- `minimax`: 仅 `generate`
- `comfy`: 单独的 Comfy 实时覆盖，不属于共享提供商扫描
针对内置 ComfyUI 音乐路径的按需启用 live 覆盖：
内置 ComfyUI 音乐路径的选择加入式实时覆盖：
```bash
OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts
```
当这些部分已配置时，Comfy live 文件也会覆盖 comfy 图像和视频工作流。
Comfy 实时测试文件在相关部分已配置时，也会覆盖 comfy 图像和视频工作流。
## 相关内容
- [后台任务](/zh-CN/automation/tasks) - 用于分离式 `music_generate` 运行的任务跟踪
- [后台任务](/zh-CN/automation/tasks) - 分离式 `music_generate` 运行的任务跟踪
- [配置参考](/zh-CN/gateway/configuration-reference#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)
- [模型](/zh-CN/concepts/models) - 模型配置和故障切换
- [Models](/zh-CN/concepts/models) - 模型配置和故障转移
- [工具概览](/zh-CN/tools)

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

@ -1,45 +1,44 @@
---
read_when:
- 通过智能体生成视频
- 配置视频生成 provider 和模型
- 配置视频生成提供商和模型
- 了解 `video_generate` 工具参数
summary: 使用 12 个 provider 后端根据文本、图像或现有视频生成视频
summary: 使用 12 个提供商后端，通过文本、图像或现有视频生成视频
title: 视频生成
x-i18n:
generated_at: "2026-04-06T15:32:14Z"
generated_at: "2026-04-06T18:17:37Z"
model: gpt-5.4
provider: openai
source_hash: 7d995d91f86f863f5a69c6945043dc430eb186830348a09eeaaad94620767f7d
source_hash: fc8984dfc718a3558b66089b37aea718f3da1ec8cf4f846a017201413c9be6a2
source_path: tools/video-generation.md
workflow: 15
---
# 视频生成
OpenClaw 智能体可以根据文本提示词、参考图像或现有视频生成视频。支持 12 个 provider 后端，每个后端都有不同的模型选项、输入模式和功能集。智能体会根据你的配置和可用的 API 密钥自动选择合适的 provider。
OpenClaw 智能体可以根据文本提示、参考图像或现有视频生成视频。支持 12 个提供商后端，每个后端都有不同的模型选项、输入模式和功能集。智能体会根据你的配置和可用的 API 密钥自动选择合适的提供商。
<Note>
只有在至少有一个视频生成 provider 可用时，`video_generate` 工具才会出现。如果你没有在智能体工具中看到它，请设置 provider API 密钥或配置 `agents.defaults.videoGenerationModel`。
仅当至少有一个视频生成提供商可用时，`video_generate` 工具才会出现。如果你没有在智能体工具中看到它，请设置提供商 API 密钥或配置 `agents.defaults.videoGenerationModel`。
</Note>
OpenClaw 将视频生成视为三种运行时模式：
- `generate`：用于没有参考媒体的 text-to-video 请求
- `imageToVideo`：当请求包含一个或多个参考图像时使用
- `videoToVideo`：当请求包含一个或多个参考视频时使用
- `generate` 用于不包含参考媒体的文生视频请求
- 当请求包含一个或多个参考图像时使用 `imageToVideo`
- 当请求包含一个或多个参考视频时使用 `videoToVideo`
Providers 可以支持这些模式中的任意子集。工具会在提交前验证当前
模式，并在 `action=list` 中报告支持的模式。
提供商可以支持这些模式中的任意子集。该工具会在提交前验证当前模式，并在 `action=list` 中报告支持的模式。
## 快速开始
1. 为任意受支持的 provider 设置 API 密钥：
1. 为任意受支持的提供商设置 API 密钥：
```bash
export GEMINI_API_KEY="your-key"
```
2. 可选地固定一个默认模型：
2. 可选：固定一个默认模型：
```bash
openclaw config set agents.defaults.videoGenerationModel.primary "google/veo-3.1-fast-generate-preview"
@ -47,33 +46,33 @@ openclaw config set agents.defaults.videoGenerationModel.primary "google/veo-3.1
3. 向智能体发出请求：
> 生成一个 5 秒钟的电影感视频：一只友好的龙虾在日落时冲浪。
> 生成一段 5 秒钟、富有电影感的友善龙虾在日落时分冲浪的视频。
智能体会自动调用 `video_generate`。不需要工具 allowlist。
智能体会自动调用 `video_generate`。不需要将工具加入允许列表。
## 生成视频时会发生什么
视频生成是异步的。当智能体在会话中调用 `video_generate` 时：
1. OpenClaw 将请求提交给 provider，并立即返回一个任务 ID。
2. Provider 在后台处理该任务（通常需要 30 秒到 5 分钟，取决于 provider 和分辨率）。
1. OpenClaw 将请求提交给提供商，并立即返回一个任务 ID。
2. 提供商在后台处理该任务（通常为 30 秒到 5 分钟，取决于提供商和分辨率）。
3. 当视频准备就绪后，OpenClaw 会通过内部完成事件唤醒同一个会话。
4. 智能体会将生成完成的视频发布回原始对话中。
4. 智能体会将最终生成的视频发布回原始对话中。
当同一会话中已有任务正在进行时，重复调用 `video_generate` 不会启动新的生成，而是返回当前任务状态。使用 `openclaw tasks list` 或 `openclaw tasks show <taskId>` 可以在 CLI 中检查进度。
当某个任务正在进行时，同一会话中的重复 `video_generate` 调用会返回当前任务状态，而不是启动新的生成。使用 `openclaw tasks list` 或 `openclaw tasks show <taskId>` 可以通过 CLI 检查进度。
在没有会话支持的智能体运行之外（例如直接工具调用），该工具会回退为内联生成，并在同一轮中返回最终媒体路径。
在非会话支持的智能体运行之外（例如直接调用工具），该工具会回退为内联生成，并在同一轮中返回最终媒体路径。
### 任务生命周期
每个 `video_generate` 请求都会经历四种状态：
每个 `video_generate` 请求都会经过四个状态：
1. **queued** -- 任务已创建，等待 provider 接受。
2. **running** -- provider 正在处理（通常需要 30 秒到 5 分钟，取决于 provider 和分辨率）。
3. **succeeded** -- 视频已准备好；智能体会被唤醒并将其发布到对话中。
4. **failed** -- provider 错误或超时；智能体会带着错误详情被唤醒。
1. **queued** -- 任务已创建，等待提供商接受。
2. **running** -- 提供商正在处理中（通常为 30 秒到 5 分钟，取决于提供商和分辨率）。
3. **succeeded** -- 视频已就绪；智能体会被唤醒并将其发布到对话中。
4. **failed** -- 提供商错误或超时；智能体会被唤醒并附带错误详情。
从 CLI 检查状态：
通过 CLI 检查状态：
```bash
openclaw tasks list
@ -81,86 +80,85 @@ openclaw tasks show <taskId>
openclaw tasks cancel <taskId>
```
防止重复：如果当前会话已有视频任务处于 `queued` 或 `running` 状态，`video_generate` 会返回现有任务状态，而不是启动新任务。使用 `action: "status"` 可以显式检查状态，而不触发新的生成。
防止重复：如果当前会话中已有视频任务处于 `queued` 或 `running` 状态，`video_generate` 会返回现有任务状态，而不是启动新任务。使用 `action: "status"` 可以显式检查状态，而不会触发新的生成。
## 支持的 providers
## 支持的提供商
| Provider | 默认模型 | 文本 | 图像参考 | 视频参考 | API 密钥 |
| -------- | ------------------------------- | ---- | ----------------- | ---------------- | ---------------------------------------- |
| Alibaba | `wan2.6-t2v` | Yes | Yes（远程 URL） | Yes（远程 URL） | `MODELSTUDIO_API_KEY` |
| BytePlus（国际版） | `seedance-1-0-lite-t2v-250428` | Yes | 1 张图像 | No | `BYTEPLUS_API_KEY` |
| ComfyUI | `workflow` | Yes | 1 张图像 | No | `COMFY_API_KEY` 或 `COMFY_CLOUD_API_KEY` |
| fal | `fal-ai/minimax/video-01-live` | Yes | 1 张图像 | No | `FAL_KEY` |
| Google | `veo-3.1-fast-generate-preview` | Yes | 1 张图像 | 1 个视频 | `GEMINI_API_KEY` |
| MiniMax | `MiniMax-Hailuo-2.3` | Yes | 1 张图像 | No | `MINIMAX_API_KEY` |
| OpenAI | `sora-2` | Yes | 1 张图像 | 1 个视频 | `OPENAI_API_KEY` |
| Qwen | `wan2.6-t2v` | Yes | Yes（远程 URL） | Yes（远程 URL） | `QWEN_API_KEY` |
| Runway | `gen4.5` | Yes | 1 张图像 | 1 个视频 | `RUNWAYML_API_SECRET` |
| Together | `Wan-AI/Wan2.2-T2V-A14B` | Yes | 1 张图像 | No | `TOGETHER_API_KEY` |
| Vydra | `veo3` | Yes | 1 张图像（`kling`） | No | `VYDRA_API_KEY` |
| xAI | `grok-imagine-video` | Yes | 1 张图像 | 1 个视频 | `XAI_API_KEY` |
| 提供商 | 默认模型 | 文本 | 图像参考 | 视频参考 | API 密钥 |
| ------ | ------------------------------- | ---- | ----------------- | ---------------- | ----------------------------------------- |
| Alibaba | `wan2.6-t2v` | 是 | 是（远程 URL） | 是（远程 URL） | `MODELSTUDIO_API_KEY` |
| BytePlus | `seedance-1-0-lite-t2v-250428` | 是 | 1 张图像 | 否 | `BYTEPLUS_API_KEY` |
| 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` |
| 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` |
| Together | `Wan-AI/Wan2.2-T2V-A14B` | 是 | 1 张图像 | 否 | `TOGETHER_API_KEY` |
| Vydra | `veo3` | 是 | 1 张图像 (`kling`) | 否 | `VYDRA_API_KEY` |
| xAI | `grok-imagine-video` | 是 | 1 张图像 | 1 段视频 | `XAI_API_KEY` |
某些 provider 接受额外的或替代的 API 密钥环境变量。详情请参见各个[provider 页面](#related)。
某些提供商还接受额外或替代的 API 密钥环境变量。详见各个[提供商页面](#related)。
运行 `video_generate action=list` 可在运行时检查可用的 provider、模型和
运行时模式。
运行 `video_generate action=list` 可在运行时查看可用的提供商、模型和运行时模式。
### 声明的能力矩阵
这是 `video_generate`、合约测试和共享 live sweep 所使用的显式模式合约。
这是 `video_generate`、契约测试以及共享实时扫描使用的显式模式契约。
| Provider | `generate` | `imageToVideo` | `videoToVideo` | 当前共享 live lanes |
| -------- | ---------- | -------------- | -------------- | ---------------------------------------------------------------------------------------------------------- |
| Alibaba | Yes | Yes | Yes | `generate`、`imageToVideo`；跳过 `videoToVideo`，因为此 provider 需要远程 `http(s)` 视频 URL |
| BytePlus（国际版） | Yes | Yes | No | `generate`、`imageToVideo` |
| ComfyUI | Yes | Yes | No | 不在共享 sweep 中；特定 workflow 的覆盖由 Comfy 测试负责 |
| fal | Yes | Yes | No | `generate`、`imageToVideo` |
| Google | Yes | Yes | Yes | `generate`、`imageToVideo`、`videoToVideo` |
| MiniMax | Yes | Yes | No | `generate`、`imageToVideo` |
| OpenAI | Yes | Yes | Yes | `generate`、`imageToVideo`、`videoToVideo` |
| Qwen | Yes | Yes | Yes | `generate`、`imageToVideo`；跳过 `videoToVideo`，因为此 provider 需要远程 `http(s)` 视频 URL |
| Runway | Yes | Yes | Yes | `generate`、`imageToVideo`；仅当所选模型为 `runway/gen4_aleph` 时运行 `videoToVideo` |
| Together | Yes | Yes | No | `generate`、`imageToVideo` |
| Vydra | Yes | Yes | No | `generate`、`imageToVideo` |
| xAI | Yes | Yes | Yes | `generate`、`imageToVideo`；跳过 `videoToVideo`，因为此 provider 当前需要远程 MP4 URL |
| 提供商 | `generate` | `imageToVideo` | `videoToVideo` | 当前共享实时通道 |
| ------ | ---------- | -------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| Alibaba | 是 | 是 | 是 | `generate`、`imageToVideo`；`videoToVideo` 已跳过，因为此提供商需要远程 `http(s)` 视频 URL |
| BytePlus | 是 | 是 | 否 | `generate`、`imageToVideo` |
| ComfyUI | 是 | 是 | 否 | 不在共享扫描中；特定于工作流的覆盖由 Comfy 测试负责 |
| fal | 是 | 是 | 否 | `generate`、`imageToVideo` |
| Google | 是 | 是 | 是 | `generate`、`imageToVideo`；共享 `videoToVideo` 已跳过，因为当前基于缓冲区的 Gemini/Veo 扫描不接受该输入 |
| MiniMax | 是 | 是 | 否 | `generate`、`imageToVideo` |
| OpenAI | 是 | 是 | 是 | `generate`、`imageToVideo`；共享 `videoToVideo` 已跳过，因为当前组织/输入路径需要提供商侧的修补/混剪访问 |
| Qwen | 是 | 是 | 是 | `generate`、`imageToVideo`；`videoToVideo` 已跳过，因为此提供商需要远程 `http(s)` 视频 URL |
| Runway | 是 | 是 | 是 | `generate`、`imageToVideo`；`videoToVideo` 仅在所选模型为 `runway/gen4_aleph` 时运行 |
| Together | 是 | 是 | 否 | `generate`、`imageToVideo` |
| 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[] | 多个参考图像（最多 5 个） |
| `video` | string | 单个参考视频（路径或 URL） |
| `videos` | string[] | 多个参考视频（最多 4 个） |
| 参数 | 类型 | 说明 |
| -------- | -------- | ---------------------------- |
| `image` | string | 单个参考图像（路径或 URL） |
| `images` | string[] | 多个参考图像（最多 5 个） |
| `video` | string | 单个参考视频（路径或 URL） |
| `videos` | string[] | 多个参考视频（最多 4 个） |
### 风格控制
| 参数 | 类型 | 描述 |
| 参数 | 类型 | 说明 |
| ----------------- | ------- | ------------------------------------------------------------------------ |
| `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 | 目标时长（秒，会四舍五入到 provider 支持的最近值） |
| `size` | string | 当 provider 支持时使用的尺寸提示 |
| `audio` | boolean | 在支持时启用生成音频 |
| `watermark` | boolean | 在支持时切换 provider 水印 |
| `resolution` | string | `480P`、`720P`、`768P` 或 `1080P` |
| `durationSeconds` | number | 目标时长（单位：秒，会四舍五入到提供商支持的最近值） |
| `size` | string | 当提供商支持时使用的尺寸提示 |
| `audio` | boolean | 在支持时启用生成音频 |
| `watermark` | boolean | 在支持时切换提供商水印 |
### 高级
| 参数 | 类型 | 描述 |
| ---------- | ------ | ----------------------------------------------- |
| `action` | string | `"generate"`（默认）、`"status"` 或 `"list"` |
| `model` | string | provider/model 覆盖（例如 `runway/gen4.5`） |
| `filename` | string | 输出文件名提示 |
| 参数 | 类型 | 说明 |
| ---------- | ------ | ---------------------------------------------- |
| `action` | string | `"generate"`（默认）、`"status"` 或 `"list"` |
| `model` | string | 提供商/模型覆盖（例如 `runway/gen4.5`） |
| `filename` | string | 输出文件名提示 |
并非所有 provider 都支持所有参数。不支持的覆盖会尽力忽略，并在工具结果中报告为警告。硬性能力限制（例如参考输入过多）会在提交前直接失败。
并非所有提供商都支持所有参数。不支持的覆盖项会尽力忽略，并在工具结果中以警告形式报告。硬性能力限制（例如参考输入过多）会在提交前直接失败。
参考输入还会决定运行时模式：
@ -168,25 +166,25 @@ openclaw tasks cancel <taskId>
- 任意图像参考：`imageToVideo`
- 任意视频参考：`videoToVideo`
混合图像与视频参考不是稳定的共享能力表面。
每个请求优先只使用一种参考类型。
混合使用图像和视频参考并不是稳定的共享能力表面。
建议每个请求只使用一种参考类型。
## 操作
- **generate**（默认）-- 根据给定提示词和可选参考输入创建视频。
- **generate**（默认）-- 根据给定提示和可选参考输入创建视频。
- **status** -- 检查当前会话中正在进行的视频任务状态，而不启动新的生成。
- **list** -- 显示可用的 provider、模型及其能力。
- **list** -- 显示可用的提供商、模型及其能力。
## 模型选择
生成视频时，OpenClaw 按以下顺序解析模型：
生成视频时，OpenClaw 会按以下顺序解析模型：
1. **`model` 工具参数** -- 如果智能体在调用中指定了它。
2. **`videoGenerationModel.primary`** -- 来自配置。
3. **`videoGenerationModel.fallbacks`** -- 按顺序尝试。
4. **自动检测** -- 使用具有有效身份验证的 providers，先从当前默认 provider 开始，然后按字母顺序尝试其余 providers。
4. **自动检测** -- 使用具有有效身份验证的提供商，从当前默认提供商开始，然后按字母顺序尝试其余提供商。
如果某个 provider 失败，会自动尝试下一个候选项。如果所有候选项都失败，错误中会包含每次尝试的详情。
如果某个提供商失败，会自动尝试下一个候选项。如果所有候选项都失败，错误中会包含每次尝试的详细信息。
```json5
{
@ -201,28 +199,26 @@ openclaw tasks cancel <taskId>
}
```
## Provider 说明
## 提供商说明
| Provider | 说明 |
| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Alibaba | 使用 DashScope/Model Studio 异步端点。参考图像和视频必须是远程 `http(s)` URL。 |
| BytePlus（国际版） | 仅支持单张参考图像。 |
| ComfyUI | 由 workflow 驱动的本地或云端执行。通过已配置图支持 text-to-video 和 image-to-video。 |
| fal | 对长时间运行任务使用基于队列的流程。仅支持单张参考图像。 |
| Google | 使用 Gemini/Veo。支持一张参考图像或一个参考视频。 |
| MiniMax | 仅支持单张参考图像。 |
| OpenAI | 只会转发 `size` 覆盖。其他风格覆盖（`aspectRatio`、`resolution`、`audio`、`watermark`）会被忽略并附带警告。 |
| Qwen | 与 Alibaba 使用相同的 DashScope 后端。参考输入必须是远程 `http(s)` URL；本地文件会在一开始就被拒绝。 |
| Runway | 通过 data URI 支持本地文件。video-to-video 需要 `runway/gen4_aleph`。纯文本运行暴露 `16:9` 和 `9:16` 宽高比。 |
| Together | 仅支持单张参考图像。 |
| Vydra | 直接使用 `https://www.vydra.ai/api/v1` 以避免丢失身份验证的重定向。`veo3` 内置为仅 text-to-video；`kling` 需要远程图像 URL。 |
| xAI | 支持 text-to-video、image-to-video，以及远程视频编辑/扩展流程。 |
| 提供商 | 说明 |
| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Alibaba | 使用 DashScope/Model Studio 异步端点。参考图像和视频必须是远程 `http(s)` URL。 |
| BytePlus | 仅支持单个图像参考。 |
| ComfyUI | 由工作流驱动的本地或云端执行。通过已配置的图支持文生视频和图生视频。 |
| fal | 对长时间运行任务使用基于队列的流程。仅支持单个图像参考。 |
| Google | 使用 Gemini/Veo。支持一个图像或一个视频参考。 |
| MiniMax | 仅支持单个图像参考。 |
| OpenAI | 仅转发 `size` 覆盖。其他样式覆盖（`aspectRatio`、`resolution`、`audio`、`watermark`）会被忽略，并给出警告。 |
| Qwen | 与 Alibaba 使用相同的 DashScope 后端。参考输入必须是远程 `http(s)` URL；本地文件会在前期直接被拒绝。 |
| Runway | 通过 data URI 支持本地文件。视频转视频需要 `runway/gen4_aleph`。纯文本运行公开 `16:9` 和 `9:16` 宽高比。 |
| Together | 仅支持单个图像参考。 |
| Vydra | 直接使用 `https://www.vydra.ai/api/v1` 以避免身份验证在重定向中丢失。`veo3` 内置为仅文生视频；`kling` 需要远程图像 URL。 |
| xAI | 支持文生视频、图生视频以及远程视频编辑/扩展流程。 |
## Provider 能力模式
## 提供商能力模式
共享视频生成合约现在允许 providers 声明特定模式的
能力，而不是只声明扁平的聚合限制。新的 provider
实现应优先使用显式模式块：
共享视频生成契约现在允许提供商声明特定于模式的能力，而不只是平铺的聚合限制。新的提供商实现应优先使用显式模式块：
```typescript
capabilities: {
@ -246,31 +242,31 @@ capabilities: {
}
```
像 `maxInputImages` 和 `maxInputVideos` 这样的扁平聚合字段，不足以表达变换模式支持。Providers 应显式声明
`generate`、`imageToVideo` 和 `videoToVideo`，这样 live tests、
合约测试和共享 `video_generate` 工具才能以确定性的方式验证模式支持。
像 `maxInputImages` 和 `maxInputVideos` 这样的平铺聚合字段，不足以声明转换模式支持。提供商应显式声明 `generate`、`imageToVideo` 和 `videoToVideo`，以便实时测试、契约测试和共享 `video_generate` 工具能够以确定方式验证模式支持。
## Live tests
## 实时测试
针对共享内置 providers 的选择接入 live 覆盖：
共享内置提供商的可选加入实时覆盖：
```bash
OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts
```
该 live 文件会从 `~/.profile` 加载缺失的 provider 环境变量，默认优先使用
live/env API 密钥而不是已存储的 auth profiles，并运行它能够用本地媒体安全执行的已声明模式：
仓库包装命令：
- 对 sweep 中每个 provider 执行 `generate`
- 当 `capabilities.imageToVideo.enabled` 时执行 `imageToVideo`
- 当 `capabilities.videoToVideo.enabled` 且 provider/model
在共享 sweep 中接受基于缓冲区的本地视频输入时执行 `videoToVideo`
```bash
pnpm test:live:media video
```
目前共享 `videoToVideo` live lane 覆盖：
这个实时测试文件会从 `~/.profile` 加载缺失的提供商环境变量，默认优先使用实时/环境 API 密钥，而不是已存储的认证配置文件，并运行它能够安全地通过本地媒体执行的声明模式：
- `google`
- `openai`
- `runway`，仅当你选择 `runway/gen4_aleph`
- 对扫描中的每个提供商运行 `generate`
- 当 `capabilities.imageToVideo.enabled` 时运行 `imageToVideo`
- 当 `capabilities.videoToVideo.enabled` 且提供商/模型在共享扫描中接受基于缓冲区的本地视频输入时运行 `videoToVideo`
当前共享 `videoToVideo` 实时通道涵盖：
- `runway`，且仅当你选择 `runway/gen4_aleph` 时
## 配置
@ -298,12 +294,12 @@ openclaw config set agents.defaults.videoGenerationModel.primary "qwen/wan2.6-t2
## 相关内容
- [工具概览](/zh-CN/tools)
- [后台任务](/zh-CN/automation/tasks) -- 异步视频生成的任务跟踪
- [后台任务](/zh-CN/automation/tasks) -- 用于异步视频生成的任务跟踪
- [Alibaba Model Studio](/zh-CN/providers/alibaba)
- [BytePlus（国际版）](/zh-CN/concepts/model-providers#byteplus-international)
- [BytePlus](/zh-CN/concepts/model-providers#byteplus-international)
- [ComfyUI](/zh-CN/providers/comfy)
- [fal](/zh-CN/providers/fal)
- [Google（Gemini）](/zh-CN/providers/google)
- [Google (Gemini)](/zh-CN/providers/google)
- [MiniMax](/zh-CN/providers/minimax)
- [OpenAI](/zh-CN/providers/openai)
- [Qwen](/zh-CN/providers/qwen)