Skip to main content
music_generate 工具允许 agent 通过已配置的提供方使用共享的音乐生成能力来创建音乐或音频——目前支持 ComfyUI、fal、Google、MiniMax 和 OpenRouter。 对于带会话的 agent 运行，OpenClaw 会将音乐生成作为后台任务启动，在任务账本中跟踪，并在音轨准备好时再次唤醒 agent，这样 agent 就可以告诉用户并附加完成的音频。完成 agent 会遵循会话的正常可见回复模式：如果已配置，则自动发送最终回复；如果会话需要使用消息工具，则使用 message(action="send")。如果请求方会话处于非活动状态，或者其活动唤醒失败，并且完成回复中仍缺少部分已生成音频，OpenClaw 会发送一个幂等的直接回退，只包含缺失的音频。
内置的共享工具只有在至少有一个音乐生成提供方可用时才会出现。如果你在 agent 的工具中看不到 music_generate，请配置 agents.defaults.musicGenerationModel 或设置提供方 API 密钥。

​
快速开始

1

配置认证

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

选择默认模型（可选）

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

向 agent 提问

“生成一首充满活力的合成流行乐，主题是夜间穿行于霓虹城市。”agent 会自动调用 music_generate。无需设置工具白名单。
对于没有基于会话的 agent 运行的直接同步上下文，内置工具仍会回退到内联生成，并在工具结果中返回最终媒体路径。
示例提示词： 
生成一首具有柔和弦乐且无人声的电影感钢琴曲。

生成一段充满活力的芯片音乐循环，主题是在日出时发射火箭。

​
支持的提供方

提供方默认模型参考输入支持的控制项认证
ComfyUIworkflow最多 1 张图片由工作流定义的音乐或音频COMFY_API_KEY, COMFY_CLOUD_API_KEY
falfal-ai/minimax-music/v2.6无lyrics, instrumental, durationSeconds, formatFAL_KEY or FAL_API_KEY
Googlelyria-3-clip-preview最多 10 张图片lyrics, instrumental, formatGEMINI_API_KEY, GOOGLE_API_KEY
MiniMaxmusic-2.6无lyrics, instrumental, format=mp3MINIMAX_API_KEY or MiniMax OAuth
OpenRoutergoogle/lyria-3-pro-preview最多 1 张图片lyrics, instrumental, durationSeconds, formatOPENROUTER_API_KEY

​
能力矩阵

music_generate、契约测试以及共享 live sweep 所使用的显式模式契约：
提供方generateedit编辑限制共享实时通道
ComfyUI✓✓1 张图片不在共享 sweep 中；由 extensions/comfy/comfy.live.test.ts 覆盖
fal✓—无generate
Google✓✓10 张图片generate, edit
MiniMax✓—无generate
OpenRouter✓✓1 张图片generate, edit
使用 action: "list" 在运行时检查可用的共享提供方和模型： 
/tool music_generate action=list
使用 action: "status" 检查当前基于会话的音乐任务： 
/tool music_generate action=status
直接生成示例： 
/tool music_generate prompt="带有黑胶质感和轻柔雨声的梦幻 lo-fi hip hop" instrumental=true

​
工具参数

​
prompt
string
required
音乐生成提示词。对于 action: "generate" 为必填。
​
action
"generate" | "status" | "list"
default:"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
"mp3" | "wav"
当提供方支持时的输出格式提示。
​
filename
string
输出文件名提示。
并非所有提供方都支持所有参数。OpenClaw 仍会在提交前验证诸如输入数量之类的硬性限制。当某个提供方支持时长但其最大值小于请求值时，OpenClaw 会将其夹取到最接近的受支持时长。真正不受支持的可选提示会在所选提供方或模型无法满足时被忽略，并给出警告。工具结果会报告已应用的设置；details.normalization 会记录任何从请求值到应用值的映射。
提供方请求超时时间仅由运维配置决定。OpenClaw 在配置了 agents.defaults.musicGenerationModel.timeoutMs 时使用该值，将低于 120000ms 的值提升到 120000ms，否则默认将提供方请求超时设为 300000ms。

​
异步行为

基于会话的音乐生成会作为后台任务运行：
  • 后台任务： music_generate 会创建一个后台任务，立即返回 started/task 响应，并在稍后的 agent 跟进消息中发布完成后的音轨。
  • 重复防护： 当任务处于 queued 或 running 状态时，同一会话中的后续 music_generate 调用会返回任务状态，而不会启动另一个生成。使用 action: "status" 可显式检查。
  • 状态查询： openclaw tasks list 或 openclaw tasks show <taskId> 可检查 queued、running 和终态。
  • 完成唤醒： OpenClaw 会将内部完成事件注入回同一会话，以便模型自行撰写面向用户的后续消息。
  • 提示提示： 当音乐任务已经在运行时，同一会话中的后续用户/手动轮次会获得一个轻量运行时提示，因此模型不会盲目再次调用 music_generate。
  • 无会话回退： 没有真实 agent 会话的直接/本地上下文会内联运行，并在同一轮返回最终音频结果。

​
任务生命周期

状态含义
queued任务已创建，正在等待提供方接受。
running提供方正在处理（通常需要 30 秒到 3 分钟，具体取决于提供方和时长）。
succeeded音轨已就绪；agent 被唤醒并将其发布到对话中。
failed提供方错误或超时；agent 被唤醒并附带错误详情。
通过 CLI 检查状态： 
openclaw tasks list
openclaw tasks show <taskId>
openclaw tasks cancel <taskId>

​
配置

​
模型选择

{
  agents: {
    defaults: {
      musicGenerationModel: {
        primary: "google/lyria-3-clip-preview",
        fallbacks: ["fal/fal-ai/minimax-music/v2.6", "minimax/music-2.6"],
      },
    },
  },
}

​
提供方选择顺序

OpenClaw 按以下顺序尝试提供方：
  1. 工具调用中的 model 参数（如果 agent 指定了）。
  2. 配置中的 musicGenerationModel.primary。
  3. 按顺序使用 musicGenerationModel.fallbacks。
  4. 仅使用带认证的提供方默认值进行自动检测：
    • 先使用当前默认提供方；
    • 再按 provider-id 顺序使用其余已注册的音乐生成提供方。
如果某个提供方失败，会自动尝试下一个候选项。如果全部失败，错误信息会包含每次尝试的详细信息。 将 agents.defaults.mediaGenerationAutoProviderFallback: false 设为仅使用显式的 model、primary 和 fallbacks 条目。

​
提供方说明

由工作流驱动，并依赖已配置的图结构以及 prompt/output 字段的节点映射。随附的 comfy 插件通过音乐生成提供方注册表接入共享的 music_generate 工具。
通过共享的提供方认证路径使用 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。
使用 Lyria 3 批量生成。当前捆绑流程支持提示词、可选歌词文本以及可选参考图片。
使用批量 music_generation 端点。支持提示词、可选歌词、器乐模式，以及通过 minimax API key 认证或 minimax-portal OAuth 输出 mp3。
使用启用流式传输的 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 之类的旧式扁平字段，不足以声明 edit 支持。提供方 应显式声明 generate 和 edit，这样实时测试、契约 测试以及共享的 music_generate 工具才能确定性地验证模式支持。

​
实时测试

共享打包提供方的可选实时覆盖： 
OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts
仓库包装命令： 
pnpm test:live:media music
此实时文件默认优先使用已导出的提供方环境变量，而不是存储的认证配置，并且在提供方启用 edit 模式时会同时运行 generate 和已声明的 edit 覆盖。当前覆盖情况：
  • google: generate 以及 edit
  • fal: 仅 generate
  • minimax: 仅 generate
  • openrouter: generate 以及 edit
  • comfy: 独立的 Comfy 实时覆盖，不属于共享提供方 sweep
打包的 ComfyUI 音乐路径的可选实时覆盖： 
OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts
当相关部分已配置时，Comfy 实时文件还会覆盖 comfy 图片和视频工作流。

​
相关内容