音乐生成

​

快速开始

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

/tool music_generate prompt="温暖的氛围感合成器循环，带有柔和磁带质感"

生成一首具有柔和弦乐且无人声的电影感钢琴曲。

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

/tool music_generate action=list
/tool music_generate action=status

/tool music_generate prompt="梦幻的 lo-fi 嘻哈，带有黑胶质感和轻柔雨声" instrumental=true

​

支持的提供方

​

能力矩阵

​

工具参数

​

异步行为

• 后台任务： music_generate 会创建一个后台任务，立即返回一个已开始/任务响应，并在稍后的后续 agent 消息中发布完成的音轨。
• 重复防止： 当任务处于 queued 或 running 状态时，同一会话中后续的 music_generate 调用会返回任务状态，而不会启动另一个生成。使用 action: "status" 可显式检查。最近完成的匹配请求也会在 2 分钟内去重。
• 状态查询： openclaw tasks list 或 openclaw tasks show <taskId> 可检查排队中、运行中以及终态状态。
• 完成唤醒： OpenClaw 会将一个内部完成事件注入回同一会话，因此模型可以自己编写面向用户的后续内容。
• 提示线索： 当音乐任务已经在运行中时，同一会话中后续的用户/手动轮次会得到一个较小的运行时提示，这样模型就不会再次盲目调用 music_generate。
• 无会话回退： 没有真实 agent 会话的直接/本地上下文会以内联方式运行，并在同一轮返回最终音频结果。

​

任务生命周期

openclaw tasks list
openclaw tasks show <taskId>
openclaw tasks cancel <taskId>

​

配置

​

模型选择

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

​

提供方选择顺序

1. 工具调用中的 model 参数（如果代理指定了该参数）。
2. 配置中的 agents.defaults.mediaModels.music.primary。
3. 按顺序使用 agents.defaults.mediaModels.music.fallbacks。
4. 仅使用基于认证的提供方默认值进行自动检测：
   • 首先使用当前默认的文本模型提供方，前提是该提供方也提供音乐生成；
   • 然后按提供方 ID 的字母顺序使用其余已注册的音乐生成提供方。

​

提供方说明

​

选择合适的路径

• 基于共享提供方：当你需要模型选择、提供方故障切换以及内置的异步任务／状态流程时。
• 插件路径（ComfyUI）：当你需要自定义工作流图，或者需要不属于共享打包音乐能力一部分的提供方时。

​

提供商能力模式

• generate：用于仅基于提示词的生成。
• edit：用于请求中包含一个或多个参考图片时。

capabilities: {
  generate: {
    maxTracks: 1,
    supportsLyrics: true,
    supportsFormat: true,
  },
  edit: {
    enabled: true,
    maxTracks: 1,
    maxInputImages: 1,
    supportsFormat: true,
  },
}

​

实时测试

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

pnpm test:live:media:music

• google：generate 以及 edit
• fal：仅 generate
• minimax：仅 generate
• openrouter：generate 以及 edit
• comfy：独立的 Comfy 实时覆盖，不属于共享提供方 sweep

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

​

相关内容

• 后台任务 — 用于分离的 music_generate 运行的任务跟踪
• ComfyUI
• 配置参考 — agents.defaults.mediaModels.music 配置
• Google (Gemini)
• MiniMax
• 模型 — 模型配置和故障切换
• 工具概览。