音乐生成

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

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

快速开始¶

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

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

/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

受支持的提供商¶

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、契约测试和共享实时扫描所使用的显式模式契约：

工具参数¶

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 (路径)

当提供商支持时，请求仅器乐输出。

image string (路径)

单个参考图像路径或 URL。

images string[] (路径)

多个参考图像（在支持的提供商上最多 10 个）。

durationSeconds number (路径)

当提供商支持时长提示时，目标时长（秒）。

format "mp3" | "wav" (路径)

当提供商支持时，输出格式提示。

filename string (路径)

输出文件名提示。

提供商请求超时仅为操作员配置。OpenClaw 在配置时使用 agents.defaults.mediaModels.music.timeoutMs，将低于 120000ms 的值提升到 120000ms，否则将提供商请求默认设置为 300000ms。

异步行为¶

基于会话的音乐生成作为后台任务运行：

• 后台任务： music_generate 创建一个后台任务，立即返回已启动/任务响应，并稍后在后续代理消息中发布完成的音轨。
• 重复预防： 当任务处于 queued 或 running 时，同一聊天中后续的 music_generate 调用会返回任务状态，而不是启动另一个生成。使用 action: "status" 显式检查。最近完成的匹配请求也会在 2 分钟内去重。即使直接聊天共享主会话转录，它们也会保留独立任务；完成会返回到请求方对等端。
• 状态查询： 使用带有 action: "status" 的 music_generate。
• 完成唤醒： OpenClaw 将内部完成事件注入回同一会话，以便模型自己撰写面向用户的后续内容。
• 提示词提示： 当音乐任务已在进行中时，同一会话中后续用户/手动轮次会获得一个小型运行时提示，以便模型不会盲目再次调用 music_generate。
• 无会话回退： 没有真实代理会话的直接/本地上下文会内联运行，并在同一轮返回最终音频结果。

任务生命周期¶

媒体运行时报告生成进度：

配置¶

模型选择¶

{
  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. 当未配置主模型或回退模型时，使用已配置的提供商默认值进行自动检测：
5. 如果当前默认文本模型提供商也提供音乐生成，则优先使用它；
6. 其余已注册的音乐生成提供商，按提供商 ID 字母顺序排列。

如果某个提供商失败，会自动尝试下一个候选项。如果全部失败，错误将包含每次尝试的详细信息。 每个失败的候选项都会以 warn 级别记录其提供商、模型和错误。 对于参考图像请求，无法使用图像或接受所提供参考数量的候选项会被跳过。

显式音乐模型配置将回退限制为已配置的列表；OpenClaw 不会追加自动检测到的提供商。

提供商说明¶

选择正确的路径¶

• 共享提供商支持 当你需要模型选择、提供商故障转移以及内置异步任务/状态流程时。
• 插件路径（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 图像和视频工作流。

相关¶

• ComfyUI
• 配置参考 — agents.defaults.mediaModels.music 配置
• Google (Gemini)
• MiniMax
• 模型 — 模型配置和故障转移
• 工具概览
• 媒体概览 — 媒体工具如何协同工作