Appearance
OpenClaw video_generate 工具支持 16 种视频生成 Provider，可通过文本、图片或视频参考生成视频。视频生成是异步任务：提交后立即返回任务 ID，Provider 后台处理后自动唤醒 Agent 发送结果。使用 openclaw tasks list 查看进度。关键配置：agents.defaults.videoGenerationModel 设主模型和 fallback 链；如果工具不可见，先设 Provider API Key 或配置默认模型。
OpenClaw 视频生成工具：16 种 Provider 配置与参数指南
OpenClaw 的 video_generate 工具让 Agent 通过文本提示、参考图片或视频生成视频，支持 16 种 Provider 后端。Agent 根据配置和可用 API Key 自动选择合适的 Provider。
INFO
video_generate 工具仅在至少一个视频生成 Provider 可用时出现。如果工具不在 Agent 工具列表里，请设置 Provider API Key 或配置 agents.defaults.videoGenerationModel。
OpenClaw 把视频生成分为三种运行时模式：
generate- 纯文本生成视频，无参考媒体。imageToVideo- 请求包含一张或多张参考图片。videoToVideo- 请求包含一段或多段参考视频。
Provider 可以支持任意子集。工具会在提交前验证当前模式是否有效，并在 action=list 中报告支持的模式。
快速开始：配置 Key 并测试视频生成
设置 API Key
给任意支持的 Provider 设置 API Key：
```bash
export GEMINI_API_KEY="your-key"
```
可选：指定默认模型
```bash
openclaw config set agents.defaults.videoGenerationModel.primary "google/veo-3.1-fast-generate-preview"
```
让 Agent 生成视频
输入提示词：
> "生成一段 5 秒的龙虾在夕阳下冲浪的电影级视频。"
Agent 会自动调用 `video_generate`，无需手动开启工具权限。
异步生成的工作原理
视频生成是异步的。当 Agent 在 Session 中调用 video_generate 时：
- OpenClaw 向 Provider 提交请求，立即返回一个任务 ID。
- Provider 在后台处理（通常 30 秒到几分钟，取决于 Provider 和分辨率；队列式慢速 Provider 可能跑满配置的超时时间）。
- 视频就绪后，OpenClaw 通过内部完成事件唤醒同一个 Session。
- Agent 通过消息工具通知用户并附加生成的视频。如果请求的 Session 不活跃，且某些生成的视频仍未通过消息工具送达，OpenClaw 会直接发送一个幂等回退，只发送缺失的视频。
任务进行中时，同一 Session 中重复调用 video_generate 会返回当前任务状态，而不是启动另一个生成。用 openclaw tasks list 或 openclaw tasks show <taskId> 从 CLI 检查进度。
在非 Session 支持的 Agent 运行中（例如直接工具调用），工具会回退到同步生成，并在同一轮返回最终的媒体路径。
生成的视频文件保存在 OpenClaw 管理的媒体存储中。默认生成视频的存储上限遵循视频媒体限制，agents.defaults.mediaMaxMb 可为更大的渲染结果提高上限。当 Provider 也返回托管输出 URL 时，如果本地存储因文件过大拒绝保存，OpenClaw 可以投递那个 URL 而不是让任务失败。
任务生命周期
| 状态 | 含义 |
|---|---|
queued | 任务已创建，等待 Provider 接受。 |
running | Provider 正在处理（通常 30 秒到几分钟，取决于 Provider 和分辨率）。 |
succeeded | 视频就绪；Agent 被唤醒并发布到对话中。 |
failed | Provider 错误或超时；Agent 被唤醒并显示错误详情。 |
从 CLI 查看状态：
bash
openclaw tasks list
openclaw tasks show <taskId>
openclaw tasks cancel <taskId>如果当前 Session 中已有 queued 或 running 的视频任务，video_generate 会返回现有任务状态而不是开始新生成。用 action: "status" 显式检查而不触发新生成。
支持的 16 种 Provider 列表与能力对比
| Provider | 默认模型 | 文生视频 | 图片参考 | 视频参考 | 认证方式 |
|---|---|---|---|---|---|
| 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 张图片 (第一帧 + 最后一帧 via role) | - | BYTEPLUS_API_KEY |
| BytePlus Seedance 2.0 | dreamina-seedance-2-0-260128 | ✓ | 最多 9 张参考图片 | 最多 3 段视频 | BYTEPLUS_API_KEY |
| ComfyUI | workflow | ✓ | 1 张图片 | - | COMFY_API_KEY 或 COMFY_CLOUD_API_KEY |
| DeepInfra | Pixverse/Pixverse-T2V | ✓ | - | - | DEEPINFRA_API_KEY |
| fal | fal-ai/minimax/video-01-live | ✓ | 1 张图片；Seedance 参考转视频最多 9 张 | 使用 Seedance 参考转视频最多 3 段视频 | FAL_KEY |
veo-3.1-fast-generate-preview | ✓ | 1 张图片 | 1 段视频 | GEMINI_API_KEY | |
| MiniMax | MiniMax-Hailuo-2.3 | ✓ | 1 张图片 | - | MINIMAX_API_KEY 或 MiniMax OAuth |
| OpenAI | sora-2 | ✓ | 1 张图片 | 1 段视频 | OPENAI_API_KEY |
| OpenRouter | google/veo-3.1-fast | ✓ | 最多 4 张图片 (第一帧/最后一帧或参考) | - | OPENROUTER_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 张第一帧图片或最多 7 张 reference_image | 1 段视频 | XAI_API_KEY |
部分 Provider 接受其他或替代的 API Key 环境变量。详见各 Provider 页面。
运行时检查可用 Provider、模型和模式：
video_generate action=list能力矩阵
视频生成工具使用的显式模式协议、契约测试和共享的实时扫测中：
| Provider | generate | imageToVideo | videoToVideo | 当前共享实时测试的覆盖范围 |
|---|---|---|---|---|
| Alibaba | ✓ | ✓ | ✓ | generate, imageToVideo；videoToVideo 跳过，因为此 Provider 需要远程 http(s) 视频 URL |
| BytePlus | ✓ | ✓ | - | generate, imageToVideo |
| ComfyUI | ✓ | ✓ | - | 不在共享扫测中；该 workflow 的覆盖范围在 Comfy 测试中 |
| DeepInfra | ✓ | - | - | generate；本机 DeepInfra 视频 schema 是 bundled 契约中的文本到视频 |
| fal | ✓ | ✓ | ✓ | generate, imageToVideo；videoToVideo 仅当使用 Seedance 参考转视频 |
| ✓ | ✓ | ✓ | generate, imageToVideo；共享 videoToVideo 跳过，因为当前 buffer 驱动的 Gemini/Veo 扫测不接受该输入 | |
| MiniMax | ✓ | ✓ | - | generate, imageToVideo |
| OpenAI | ✓ | ✓ | ✓ | generate, imageToVideo；共享 videoToVideo 跳过，因为此组织/输入路径当前需要 Provider 侧的 inpaint/remix 访问 |
| OpenRouter | ✓ | ✓ | - | generate, imageToVideo |
| Qwen | ✓ | ✓ | ✓ | generate, imageToVideo；videoToVideo 跳过，因为此 Provider 需要远程 http(s) 视频 URL |
| Runway | ✓ | ✓ | ✓ | generate, imageToVideo；videoToVideo 仅在选定模型是 runway/gen4_aleph 时运行 |
| Together | ✓ | ✓ | - | generate, imageToVideo |
| Vydra | ✓ | ✓ | - | generate；共享 imageToVideo 跳过，因为 bundled veo3 是纯文本、bundled kling 需要远程图片 URL |
| xAI | ✓ | ✓ | ✓ | generate, imageToVideo；videoToVideo 跳过，因为此 Provider 当前需要远程 MP4 URL |
工具参数：prompt、参考图片/视频与风格控制
必填
prompt string (必填)
视频的文字描述。action: "generate" 时必填。
内容输入
image string
images string[]
imageRoles string[]
可选的位置角色提示，与合并后的图片列表平行。 规范值：first_frame, last_frame, reference_image。
video string
videos string[]
videoRoles string[]
可选的位置角色提示，与合并后的视频列表平行。 规范值：reference_video。
audioRef string
单段参考音频（本地路径或 URL）。用于 Provider 支持时的背景音乐或语音参考。
audioRefs string[]
audioRoles string[]
可选的位置角色提示，与合并后的音频列表平行。 规范值：reference_audio。
INFO
角色提示会原样传递给 Provider。规范值来自 VideoGenerationAssetRole 联合类型，但 Provider 可能接受其他角色字符串。*Roles 数组的元素数不能超过对应的参考列表；索引不匹配会返回明确错误。用空字符串留空。对于 xAI，把所有图片角色设为 reference_image 以使用其 reference_images 生成模式；省略角色或使用 first_frame 进行单图片的图生视频。
风格控制
aspectRatio string
宽高比提示，如 1:1, 16:9, 9:16, adaptive，或 Provider 特定值。OpenClaw 会按 Provider 归一化或忽略不支持的值。
resolution string
durationSeconds number
目标时长，单位秒（会四舍五入到 Provider 支持的最接近值）。
size string
audio boolean
启用生成音频，当 Provider 支持时。与 audioRef*（输入）不同。
watermark boolean
adaptive 是 Provider 特定的标记：它会原样传递给那些声明支持 adaptive 的 Provider（例如 BytePlus Seedance 会用它从输入图片尺寸自动检测比例）。不声明此能力的 Provider 会在工具结果中的 details.ignoredOverrides 里暴露该值，以便看到它被丢弃。
高级
action
"status" 返回当前 Session 的任务状态；"list" 检查 Provider 能力。
model string
filename string
timeoutMs number
providerOptions object
以 JSON 对象形式传递给 Provider 的特定选项，如 {"seed": 42, "draft": true}。 声明了类型化 schema 的 Provider 会验证键和类型；未知键或类型不匹配会在回退时跳过该候选。无声明 schema 的 Provider 会按其原样接收选项。运行 video_generate action=list 查看每个 Provider 接受什么。
INFO
并非所有 Provider 都支持所有参数。OpenClaw 将时长归一化到 Provider 支持的最接近值，并在回退 Provider 暴露不同控制表面时重新映射已翻译的几何提示（如尺寸到宽高比）。真正不支持的覆盖项会被尽力忽略，并在工具结果中报告为警告。硬性能力限制（如参考输入过多）会在提交前失败。工具结果报告应用的设置；details.normalization 捕获请求到应用的转换关系。
参考输入决定运行时模式：
- 无参考媒体 →
generate - 有任何图片参考 →
imageToVideo - 有任何视频参考 →
videoToVideo - 参考音频输入 不 改变解析出的模式；它们叠加在图片/视频参考选择的模式之上，且仅对声明了
maxInputAudios的 Provider 有效。
混用图片和视频参考不是一个稳定的共享能力表面。每个请求最好只使用一种参考类型。
回退与类型化选项
部分能力检查是在回退层而非工具边界应用的，因此超过主要 Provider 限制的请求仍可以在有能力的回退 Provider 上运行：
- 当请求包含音频参考时，跳过声明
maxInputAudios为null或0的候选；尝试下一个。 - 当请求的
durationSeconds大于候选的maxDurationSeconds且未声明supportedDurationSeconds列表时 → 跳过。 - 请求包含
providerOptions且候选显式声明了类型化providerOptionsschema 时 → 如果提供的键不在 schema 中或值类型不匹配则跳过。无声明 schema 的 Provider 接收选项不变（向后兼容的直通）。Provider 可以通过声明空 schema（capabilities.providerOptions: {}）来选择退出所有 provider 选项，这会导致与类型不匹配相同的跳过。
请求中第一个跳过原因会在 warn 级别记录，以便操作员看到主要 Provider 被跳过；后续跳过在 debug 级别记录，以保持长的回退链安静。如果所有候选都跳过，聚合错误会包含每个候选的跳过原因。
操作
| 操作 | 功能 |
|---|---|
generate | 默认。根据提示和可选的参考输入生成视频。 |
status | 检查当前 Session 中正在进行的视频任务的状态，不触发新的生成。 |
list | 显示可用的 Provider、模型及其能力。 |
模型选择顺序
OpenClaw 按以下顺序解析模型：
model工具参数 - 如果 Agent 在调用中指定。- 配置中的
videoGenerationModel.primary。 - 按顺序
videoGenerationModel.fallbacks。 - 自动检测 - 从当前默认 Provider 开始，按字母顺序遍历有有效认证的 Provider。
如果某个 Provider 失败，自动尝试下一个候选。如果所有候选都失败，错误包含每次尝试的详细原因。
设置 agents.defaults.mediaGenerationAutoProviderFallback: false 以只使用显式的 model、primary 和 fallbacks 条目。
json5
{
agents: {
defaults: {
videoGenerationModel: {
primary: "google/veo-3.1-fast-generate-preview",
fallbacks: ["runway/gen4.5", "qwen/wan2.6-t2v"],
},
},
},
}各 Provider 的特定说明和注意事项
Alibaba
使用 DashScope / Model Studio 异步端点。参考图片和视频必须是远程 `http(s)` URL。
BytePlus (1.0)
Provider 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 变体。
支持的 `providerOptions` 键：`seed`（number）、`draft`（boolean - 强制 480p）、`camera_fixed`（boolean）。
BytePlus Seedance 1.5
需要 [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark) 插件。Provider ID：`byteplus-seedance15`。模型：`seedance-1-5-pro-251215`。
使用统一 `content[]` API。最多支持 2 张输入图片（`first_frame` + `last_frame`）。所有输入必须是远程 `https://` URL。为每张图片设置 `role: "first_frame"` / `"last_frame"`，或通过位置传递图片。
`aspectRatio: "adaptive"` 从输入图片自动检测比例。`audio: true` 映射到 `generate_audio`。`providerOptions.seed`（number）会原样传递。
BytePlus Seedance 2.0
需要 [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark) 插件。Provider 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"`。
`aspectRatio: "adaptive"` 从输入图片自动检测比例。`audio: true` 映射到 `generate_audio`。`providerOptions.seed`（number）会原样传递。
ComfyUI
Workflow 驱动的本地或云端执行。通过配置的图（graph）支持文生视频和图生视频。
fal
使用队列驱动的流程处理长时间运行的任务。OpenClaw 默认等待最多 20 分钟才把进行中的 fal 队列任务视为超时。大多数 fal 视频模型接受一张图片参考。Seedance 2.0 参考转视频模型最多接受 9 张图片、3 段视频和 3 段音频参考，参考文件总数不超过 12。
Google (Gemini / Veo)
支持一张图片或一段视频参考。生成音频的请求在 Gemini API 路径上会被忽略并给出警告，因为该 API 对当前 Veo 视频生成拒绝 `generateAudio` 参数。
MiniMax
仅支持一张图片参考。MiniMax 接受 `768P` 和 `1080P` 分辨率；像 `720P` 这样的请求会在提交前被归一化到最接近的支持值。
OpenAI
只会转发 `size` 覆盖项。其他风格覆盖项（`aspectRatio`、`resolution`、`audio`、`watermark`）会被忽略并给出警告。
OpenRouter
使用 OpenRouter 的异步 `/videos` API。OpenClaw 提交任务、轮询 `polling_url`、下载 `unsigned_urls` 或文档中记载的任务内容端点。bundled 的 `google/veo-3.1-fast` 默认值宣称支持 4/6/8 秒时长、`720P`/`1080P` 分辨率和 `16:9`/`9:16` 宽高比。
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` 是 bundled 的纯文生视频模型；`kling` 需要远程图片 URL。
xAI
支持文生视频、单张第一帧图片的图生视频、通过 xAI `reference_images` 最多 7 个 `reference_image` 输入，以及远程视频编辑/扩展流程。
Provider 能力模式
共享的视频生成协议支持基于模式（mode-specific）的能力声明，而不仅仅是平面聚合的限制。新 Provider 实现应优先使用显式模式块：
typescript
capabilities: {
generate: {
maxVideos: 1,
maxDurationSeconds: 10,
supportsResolution: true,
},
imageToVideo: {
enabled: true,
maxVideos: 1,
maxInputImages: 1,
maxInputImagesByModel: { "provider/reference-to-video": 9 },
maxDurationSeconds: 5,
},
videoToVideo: {
enabled: true,
maxVideos: 1,
maxInputVideos: 1,
maxDurationSeconds: 5,
},
}像 maxInputImages 和 maxInputVideos 这样的平面聚合字段不足以声明转换模式支持。Provider 应显式声明 generate、imageToVideo 和 videoToVideo，以便实时测试、契约测试和共享的 video_generate 工具能确定性地验证模式支持。
当 Provider 的某个模型比其他模型有更广的参考输入支持时，使用 maxInputImagesByModel、maxInputVideosByModel 或 maxInputAudiosByModel，而不是提高模式级的上限。
实时测试
共享 bundled Provider 的 opt-in 实时覆盖测试：
bash
OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts仓库包装命令：
bash
pnpm test:live:media video此实时文件默认使用已导出的 Provider 环境变量（优先于存储的认证配置文件），并默认运行一个对发布安全的冒烟测试：
- 为扫测中每个非 FAL Provider 运行
generate。 - 提示词为“一秒的龙虾”。
- 每个 Provider 的操作上限来自
OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS（默认180000）。
FAL 是 opt-in 的，因为 Provider 端队列延迟会显著影响发布节奏：
bash
pnpm test:live:media video --video-providers fal设置 OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1 以同时运行共享扫测能安全使用本地媒体进行的已声明转换模式：
imageToVideo当capabilities.imageToVideo.enabled时。videoToVideo当capabilities.videoToVideo.enabled且 Provider/模型在共享扫测中接受 buffer 驱动的本地视频输入时。
目前共享的 videoToVideo 实时测试路径仅在选定 runway/gen4_aleph 时覆盖 Runway。
配置
在 OpenClaw 配置中设置默认视频生成模型：
json5
{
agents: {
defaults: {
videoGenerationModel: {
primary: "qwen/wan2.6-t2v",
fallbacks: ["qwen/wan2.6-r2v-flash"],
},
},
},
}或通过 CLI：
bash
openclaw config set agents.defaults.videoGenerationModel.primary "qwen/wan2.6-t2v"延伸阅读
- Alibaba Model Studio
- 背景任务 - 异步视频生成的任务跟踪
- BytePlus
- ComfyUI
- 配置参考
- fal
- Google (Gemini)
- MiniMax
- 模型
- OpenAI
- Qwen
- Runway
- Together AI
- 工具总览
- Vydra
- xAI
常见问题
为什么视频生成工具不显示在 Agent 工具列表中？
至少需要配置一个 Provider 的 API Key，video_generate 工具才会出现。设置 GEMINI_API_KEY、OPENAI_API_KEY 或其他任意一个支持的 Provider 的环境变量即可。另外也可以配置 agents.defaults.videoGenerationModel 让系统知道用哪个模型。
xAI 的视频编辑和图片参考应该怎么传参数？
xAI 支持文生视频、单张第一帧图片的图生视频，以及最多 7 个 reference_image 输入。把所有图片的 role 设为 "reference_image" 以使用 reference_images 生成模式；如果只传一张图片且希望作为第一帧，则不设 role 或设为 "first_frame"。
配置了 fallbacks，但视频生成始终用自动检测的 Provider，怎么回事？
检查 agents.defaults.mediaGenerationAutoProviderFallback 配置。默认是 true，意味着如果 primary 和 fallbacks 都配置了但都失败，系统还会自动检测其他有认证的 Provider。如果希望只使用显式配置的模型链，把该值设为 false 即可。