音乐生成

music_generate 工具让 Agent 通过配置好的 Provider 生成音乐或音频，支持 Google、MiniMax 和 ComfyUI 三种后端。

对于共享 Provider 的 Agent 会话，OpenClaw 将音乐生成作为后台任务异步执行，完成后主动唤醒 Agent，在原频道发送生成的音频文件。

只有在至少一个音乐生成 Provider 可用时，music_generate 才会出现在 Agent 工具列表中。如果看不到该工具，请配置 agents.defaults.musicGenerationModel 或设置 Provider API Key。

快速开始

通过共享 Provider 生成

1. 为至少一个 Provider 设置 API Key（如 GEMINI_API_KEY 或 MINIMAX_API_KEY）
2. 可选：设置首选模型：

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

3. 告诉 Agent："生成一首赛博朋克风格的夜间驾车电子乐。"

Agent 自动调用 music_generate，无需手动开启工具权限。

示例 Prompt：

Generate a cinematic piano track with soft strings and no vocals.

/tool music_generate prompt="Dreamy lo-fi hip hop with vinyl texture and gentle rain" instrumental=true

通过 ComfyUI workflow 生成

1. 在 models.providers.comfy.music 中配置 workflow JSON 和节点
2. 如使用 Comfy Cloud，设置 COMFY_API_KEY 或 COMFY_CLOUD_API_KEY
3. 直接让 Agent 生成音乐

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

内置 Provider 支持

Provider	默认模型	参考输入	支持参数	API Key
ComfyUI	workflow	最多 1 张图片	Workflow 定义	COMFY_API_KEY、COMFY_CLOUD_API_KEY
Google	lyria-3-clip-preview	最多 10 张图片	lyrics、instrumental、format	GEMINI_API_KEY、GOOGLE_API_KEY
MiniMax	music-2.5+	无	lyrics、instrumental、durationSeconds、format=mp3	MINIMAX_API_KEY

运行时查看可用 Provider：

/tool music_generate action=list

查看当前后台音乐任务状态：

/tool music_generate action=status

工具参数

参数	类型	说明
prompt	string	音乐生成提示词（action: "generate" 时必填）
action	string	"generate"（默认）、"status" 或 "list"
model	string	覆盖 Provider/模型，如 google/lyria-3-pro-preview
lyrics	string	歌词文本（Provider 支持时可选）
instrumental	boolean	请求纯器乐输出
image	string	参考图路径或 URL（单张）
images	string[]	参考图（多张，最多 10 张）
durationSeconds	number	目标时长（Provider 支持时）
format	string	输出格式提示（mp3 或 wav）
filename	string	输出文件名提示

不支持的参数会被忽略并在结果中告警。

异步任务机制

• Session-backed：music_generate 创建后台任务，立即返回已启动状态，完成后在原频道发送音频
• 防重复：后台任务运行期间，再次调用 music_generate 返回任务状态而非启动新任务
• 状态查询：action: "status" 查看当前会话的后台音乐任务
• 任务追踪：openclaw tasks list 或 openclaw tasks show <taskId>
• 无 Session 回退：非 Agent 直接调用时同步生成并返回结果

配置

{
  agents: {
    defaults: {
      musicGenerationModel: {
        primary: "google/lyria-3-clip-preview",
        fallbacks: ["minimax/music-2.5+"],
      },
    },
  },
}

延伸阅读

• ComfyUI Provider
• Google Gemini Provider
• MiniMax Provider
• 配置参考
• 工具总览