跳转至

音乐生成

music_generate 工具通过共享的音乐生成能力创建音乐或音频,该能力由 ComfyUI、fal、Google、MiniMax 和 OpenRouter 提供支持。

Note

music_generate 仅在至少有一个音乐生成提供商可用时才会出现:可以是显式的 agents.defaults.mediaModels.music 配置,也可以是已配置认证的提供商(例如已设置的 API 密钥)。

对于基于会话的代理运行,music_generate 会作为后台任务启动,在其媒体运行时中跟踪进度,然后在曲目就绪时唤醒代理,以便代理告知用户并附加完成的音频。完成代理遵循会话的可见回复契约:配置时会自动发送最终回复,或者当会话要求使用消息工具时,使用 message(action="send")。如果请求方会话处于非活动状态,或其唤醒失败,且生成的音频仍然缺失于回复中,OpenClaw 会发送一个仅包含缺失音频的幂等直接回退。

快速开始

1. 配置认证

为至少一个提供商设置 API 密钥——例如 GEMINI_API_KEY 或 MINIMAX_API_KEY。

2. 选择默认模型(可选)

{
  agents: {
    defaults: {
      mediaModels: {
        music: {
          primary: "google/lyria-3-clip-preview",
        },
      },
    },
  },
}

3. 向代理提问

"生成一首关于在霓虹城市夜间驾驶的欢快合成器流行曲目。"

代理会自动调用 music_generate。无需工具白名单。

在非会话代理运行(直接/本地上下文)中,该工具会内联运行,并在同一次工具结果中返回最终的媒体路径。

1. 配置工作流

使用工作流 JSON 和提示/输出节点配置 plugins.entries.comfy.config.music。

2. 云认证(可选)

对于 Comfy Cloud,设置 COMFY_API_KEY 或 COMFY_CLOUD_API_KEY。

3. 调用工具

/tool music_generate prompt="Warm ambient synth loop with soft tape texture"

示例提示:

Generate a cinematic piano track with soft strings and no vocals.
Generate an energetic chiptune loop about launching a rocket at sunrise.

使用 action: "list" 查看可用的提供商/模型,并使用 action: "status" 查看当前会话后台的音乐任务:

/tool music_generate action=list
/tool music_generate 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
Google 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
Google ✓ ✓ 10 张图像 generate, edit
MiniMax ✓ — 无 generate
OpenRouter ✓ ✓ 1 张图像 generate, edit

工具参数

prompt string (path) 必填
音乐生成提示词。action: "generate" 时需要。
action "generate" | "status" | "list" (path) 默认:generate
"status" 返回当前会话任务;"list" 查看提供商。
model string (path)
提供商/模型覆盖(例如 google/lyria-3-pro-preview、comfy/workflow)。
lyrics string (path)
当提供商支持显式歌词输入时的可选歌词。
instrumental boolean (path)
当提供商支持时,请求仅器乐输出。
image string (path)
单个参考图像路径或 URL。
images string[] (path)
多个参考图像(在支持的提供商上最多 10 个)。
durationSeconds number (path)
目标时长(秒),当提供商支持时长提示时。
format "mp3" | "wav" (path)
输出格式提示,当提供商支持时。
filename string (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 按以下顺序尝试提供商:

  1. 工具调用中的 model 参数。如果设置了该参数,则只尝试此模型。
  2. 配置中的 agents.defaults.mediaModels.music.primary。
  3. 按顺序使用 agents.defaults.mediaModels.music.fallbacks。
  4. 当既未配置主模型(primary)也未配置备用模型(fallback)时,使用已配置的提供商默认值进行自动检测:
  5. 首先使用当前默认的文本模型提供商(如果它也提供音乐生成);
  6. 其余已注册的音乐生成提供商,按提供商 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)的可选实时覆盖:

OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts

等效的仓库包装器,它驱动相同的测试文件:

pnpm test:live:media:music

该实时文件默认优先使用已导出的提供方环境变量,而不是存储的认证 配置,并在提供方启用编辑模式时同时运行 generate 和已声明的 edit 覆盖。当前覆盖范围:

  • google:generate 加 edit
  • fal:仅 generate
  • minimax:仅 generate
  • openrouter:generate 加 edit
  • comfy:独立的 Comfy 实时覆盖,不属于共享提供方遍历

针对捆绑 ComfyUI 音乐路径的可选实时覆盖:

OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts

当这些部分已配置时,Comfy 实时文件还会覆盖 comfy 图像和视频工作流。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw