音乐生成
music_generate 工具通过共享的音乐生成能力创建音乐或音频,该能力由 ComfyUI、fal、Google、MiniMax 和 OpenRouter 提供支持。
Note
music_generate 仅在至少有一个音乐生成提供商可用时才会出现:可以是显式的 agents.defaults.mediaModels.music 配置,也可以是已配置认证的提供商(例如已设置的 API 密钥)。
对于基于会话的代理运行,music_generate 会作为后台任务启动,在其媒体运行时中跟踪进度,然后在曲目就绪时唤醒代理,以便代理告知用户并附加完成的音频。完成代理遵循会话的可见回复契约:配置时会自动发送最终回复,或者当会话要求使用消息工具时,使用 message(action="send")。如果请求方会话处于非活动状态,或其唤醒失败,且生成的音频仍然缺失于回复中,OpenClaw 会发送一个仅包含缺失音频的幂等直接回退。
快速开始¶
示例提示:
使用 action: "list" 查看可用的提供商/模型,并使用 action: "status" 查看当前会话后台的音乐任务:
直接生成示例:
/tool music_generate prompt="Dreamy lo-fi hip hop with vinyl texture and gentle rain" instrumental=true
受支持的提供商¶
| 提供商 | 默认模型 | 参考输入 | 支持的控制参数 | 认证 |
|---|---|---|---|---|
| ComfyUI | workflow |
最多 1 张图像 | 由工作流定义的音乐或音频 | COMFY_API_KEY, COMFY_CLOUD_API_KEY |
| fal | fal-ai/minimax-music/v2.6 |
无 | lyrics, instrumental, durationSeconds, format |
FAL_KEY 或 FAL_API_KEY |
lyria-3-clip-preview |
最多 10 张图像 | lyrics, instrumental, format |
GEMINI_API_KEY, GOOGLE_API_KEY |
|
| MiniMax | music-2.6 |
无 | lyrics, instrumental, format(仅 mp3) |
MINIMAX_API_KEY 或 MiniMax OAuth |
| OpenRouter | google/lyria-3-pro-preview |
最多 1 张图像 | lyrics, instrumental, durationSeconds, format |
OPENROUTER_API_KEY |
MiniMax 注册了两个共享相同模型的提供商 ID:minimax 用于 API 密钥认证,minimax-portal 用于 OAuth。模型引用遵循认证路径(minimax/music-2.6 与 minimax-portal/music-2.6);参见 MiniMax。
fal 还在其默认的 MiniMax 支撑模型之外,提供了 fal-ai/ace-step/prompt-to-audio(wav,无歌词,无 instrumental 开关)和 fal-ai/stable-audio-25/text-to-audio(wav,仅提示词)。Google 的默认 lyria-3-clip-preview 仅输出 mp3;lyria-3-pro-preview 还支持 wav。MiniMax 还提供 music-2.6-free、music-cover 和 music-cover-free。OpenRouter 还提供 google/lyria-3-clip-preview。
能力矩阵¶
music_generate、契约测试和共享实时扫描所使用的显式模式契约:
| 提供商 | generate |
edit |
编辑限制 | 共享实时通道 |
|---|---|---|---|---|
| ComfyUI | ✓ | ✓ | 1 张图像 | 不在共享实时扫描范围内;由 extensions/comfy/comfy.live.test.ts 覆盖 |
| fal | ✓ | — | 无 | generate |
| ✓ | ✓ | 10 张图像 | generate, edit |
|
| MiniMax | ✓ | — | 无 | generate |
| OpenRouter | ✓ | ✓ | 1 张图像 | generate, edit |
工具参数¶
promptstring (path) 必填- 音乐生成提示词。
action: "generate"时需要。 action"generate" | "status" | "list" (path) 默认:generate"status"返回当前会话任务;"list"查看提供商。modelstring (path)- 提供商/模型覆盖(例如
google/lyria-3-pro-preview、comfy/workflow)。 lyricsstring (path)- 当提供商支持显式歌词输入时的可选歌词。
instrumentalboolean (path)- 当提供商支持时,请求仅器乐输出。
imagestring (path)- 单个参考图像路径或 URL。
imagesstring[] (path)- 多个参考图像(在支持的提供商上最多 10 个)。
durationSecondsnumber (path)- 目标时长(秒),当提供商支持时长提示时。
format"mp3" | "wav" (path)- 输出格式提示,当提供商支持时。
filenamestring (path)- 输出文件名提示。
Note
并非所有提供商都支持所有参数。OpenClaw 仍会在提交前验证硬限制(例如输入数量)。
当提供商支持时长参数但最大时长小于请求值时,OpenClaw 会将其限制为最接近的受支持时长。
当所选提供商或模型无法满足某些可选提示时,这些真正不受支持的可选提示会被忽略并发出警告。
工具结果会报告实际应用的设置;details.normalization 会记录从请求到实际应用的映射。
提供商请求超时只能由操作者配置。当配置了 agents.defaults.mediaModels.music.timeoutMs
时,OpenClaw 会使用该值,将低于 120000ms 的值提高到 120000ms;否则提供商请求默认
为 300000ms。
异步行为¶
基于会话(session-backed)的音乐生成以后台任务方式运行:
- 后台任务:
music_generate创建后台任务,立即返回“已开始/任务”响应,并在后续的 agent 消息中发布完成的音轨。 - 重复防止: 当任务处于
queued或running状态时,同一聊天中后续的music_generate调用会返回任务状态,而不会开始另一次生成。请使用action: "status"显式检查。最近完成的匹配请求也会在 2 分钟内进行去重。直接聊天即使共享主会话记录,也会保留独立任务;完成结果会返回给请求方。 - 状态查询: 使用带
action: "status"的music_generate。 - 完成唤醒: OpenClaw 会在同一会话中注入一个内部完成事件,以便模型自行编写面向用户的后续消息。
- Prompt 提示: 当音乐任务已在执行中时,同一会话中后续的用户/手动轮次会收到一个小的运行时提示,以免模型盲目地再次调用
music_generate。 - 无会话回退: 没有真实 agent 会话的直接/本地上下文会以内联方式运行,并在同一轮中返回最终音频结果。
任务生命周期¶
媒体运行时会报告生成进度:
| 状态 | 含义 |
|---|---|
queued |
任务已创建,等待提供商接受。 |
running |
提供商正在处理(通常需要 30 秒到 3 分钟,具体取决于提供商和时长)。 |
succeeded |
音轨已就绪;agent 被唤醒并将其发布到对话中。 |
failed |
提供商错误或超时;agent 被唤醒并带有错误详情。 |
配置¶
模型选择¶
{
agents: {
defaults: {
mediaModels: {
music: {
primary: "google/lyria-3-clip-preview",
fallbacks: ["fal/fal-ai/minimax-music/v2.6", "minimax/music-2.6"],
},
},
},
},
}
提供商选择顺序¶
对于 music_generate,OpenClaw 按以下顺序尝试提供商:
- 工具调用中的
model参数。如果设置了该参数,则只尝试此模型。 - 配置中的
agents.defaults.mediaModels.music.primary。 - 按顺序使用
agents.defaults.mediaModels.music.fallbacks。 - 当既未配置主模型(primary)也未配置备用模型(fallback)时,使用已配置的提供商默认值进行自动检测:
- 首先使用当前默认的文本模型提供商(如果它也提供音乐生成);
- 其余已注册的音乐生成提供商,按提供商 ID 的字母顺序排列。
如果某个提供商失败,会自动尝试下一个候选。如果全部失败,错误信息会包含每次尝试的详细信息。
每个失败的候选都会在 warn 级别记录其提供商、模型和错误。
对于参考图像请求,无法使用图像或无法接受所提供的参考图像数量的候选会被跳过。
显式音乐模型配置会将回退限制为已配置的列表;OpenClaw 不会追加自动检测到的提供商。
提供商说明¶
ComfyUI
工作流驱动,依赖于已配置的图以及 prompt/输出字段的节点映射。comfy 插件通过音乐生成提供商注册表接入共享的 music_generate 工具。
fal
通过共享的提供商认证路径使用 fal 模型端点。内置提供商默认使用 fal-ai/minimax-music/v2.6,并且还为 prompt-to-audio 请求提供 fal-ai/ace-step/prompt-to-audio 和 fal-ai/stable-audio-25/text-to-audio。歌词和器乐模式仅限 MiniMax 模型;另外两个模型仅支持 prompt。
Google (Lyria 3)
使用 Lyria 3 批量生成。当前内置流程支持 prompt、可选的歌词文本以及可选的参考图像。默认的 lyria-3-clip-preview 模型仅输出 mp3;lyria-3-pro-preview 模型还支持 wav。
MiniMax
使用批量的 music_generation 端点。支持 prompt、可选歌词、器乐模式,以及通过 minimax API 密钥认证或 minimax-portal OAuth 输出 mp3。同时还提供 music-2.6-free、music-cover 和 music-cover-free 模型。
OpenRouter
使用 OpenRouter chat completions 的音频输出,并启用流式传输。内置提供商默认使用 google/lyria-3-pro-preview,同时还提供 openrouter/google/lyria-3-clip-preview。
选择正确路径¶
- 共享提供方支持 当你需要模型选择、提供方 故障转移以及内置异步任务/状态流程时。
- 插件路径(ComfyUI) 当你需要自定义工作流图或一个 不属于共享捆绑音乐能力的提供方时。
如果你正在调试 ComfyUI 特定行为,请参阅 ComfyUI。如果你正在调试共享提供方 行为,请从 fal、Google (Gemini)、 MiniMax 或 OpenRouter 开始。
提供方能力模式¶
共享音乐生成契约支持显式模式声明:
generate用于仅提示词生成。edit当请求包含一个或多个参考图像时。
新的提供方实现应优先使用显式模式块:
capabilities: {
generate: {
maxTracks: 1,
supportsLyrics: true,
supportsFormat: true,
},
edit: {
enabled: true,
maxTracks: 1,
maxInputImages: 1,
supportsFormat: true,
},
}
诸如 maxInputImages、supportsLyrics 和
supportsFormat 之类的旧版扁平字段不足以声明编辑支持。提供方
应显式声明 generate 和 edit,以便实时测试、契约
测试和共享的 music_generate 工具能够确定性地验证模式支持。
实时测试¶
针对共享捆绑提供方(fal、Google、MiniMax、 OpenRouter)的可选实时覆盖:
等效的仓库包装器,它驱动相同的测试文件:
该实时文件默认优先使用已导出的提供方环境变量,而不是存储的认证
配置,并在提供方启用编辑模式时同时运行 generate 和已声明的 edit 覆盖。当前覆盖范围:
google:generate加editfal:仅generateminimax:仅generateopenrouter:generate加editcomfy:独立的 Comfy 实时覆盖,不属于共享提供方遍历
针对捆绑 ComfyUI 音乐路径的可选实时覆盖:
当这些部分已配置时,Comfy 实时文件还会覆盖 comfy 图像和视频工作流。
相关¶
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw