配置至少一个 Provider API Key 后，OpenClaw Agent 可通过 music_generate 工具自动生成音乐或音频。支持异步后台任务（session-backed 会话）和同步回退（无会话场景），完成后自动发送到原频道。使用 /tool music_generate action=list 运行时查看可用 Provider，action=status 查看当前会话任务状态。Provider 选择按 model 参数 → 配置 primary → fallbacks → 自动检测已认证 Provider 依次尝试。

OpenClaw 音乐生成工具：配置 Google Lyria、MiniMax、fal、ComfyUI 和 OpenRouter

music_generate 工具让 Agent 通过配置好的 Provider 生成音乐或音频。目前内置的共享 Provider 包括 ComfyUI、fal、Google (Lyria 3)、MiniMax 和 OpenRouter。

对于 session-backed 的 Agent 运行，OpenClaw 将音乐生成作为后台任务启动，在任务台账中跟踪，在音轨就绪时唤醒 Agent，由 Agent 通过消息工具将完成的音频发送给用户。如果请求者会话处于非活跃状态且仍有音频未被消息工具送达，OpenClaw 会以幂等方式直接回退发送缺失的音频。完成唤醒会明确警告 Agent，对此路由的正常最终回复是私有的。

内置共享工具仅在至少一个音乐生成 Provider 可用时才会显示。如果 Agent 工具列表中看不到 music_generate，请配置 agents.defaults.musicGenerationModel 或设置 Provider API Key。

快速开始

配置好 Provider 后，告诉 Agent 生成音乐即可。

示例 Prompt：

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

Generate an energetic chiptune loop about launching a rocket at sunrise.

共享 Provider 方式（推荐）

1. 配置认证：为至少一个 Provider 设置 API Key，例如 GEMINI_API_KEY 或 MINIMAX_API_KEY。
2. 设置默认模型（可选）：

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

3. 让 Agent 生成："Generate an upbeat synthpop track about a night drive through a neon city."

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

对于无 session 的直接同步上下文，内置工具会回退为内联生成，并在工具结果中返回最终媒体路径。

ComfyUI workflow 方式

1. 配置 workflow：在 plugins.entries.comfy.config.music 中配置 workflow JSON 和 prompt/output 节点。
2. 云端认证（可选）：Comfy Cloud 需要设置 COMFY_API_KEY 或 COMFY_CLOUD_API_KEY。
3. 调用工具：

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

支持的 Provider

Provider	默认模型	参考输入	支持的参数	认证方式
ComfyUI	workflow	最多 1 张图片	workflow 定义的音乐或音频	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

能力矩阵

music_generate 使用的显式模式契约：

Provider	generate	edit	编辑限制	共享实时测试覆盖
ComfyUI	✓	✓	1 张图片	不在共享 sweep 中，由 extensions/comfy/comfy.live.test.ts 覆盖
fal	✓	—	无	generate
Google	✓	✓	10 张图片	generate, edit
MiniMax	✓	—	无	generate
OpenRouter	✓	✓	1 张图片	generate, edit

运行时查看可用 Provider 和模型：

/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

工具参数

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

并非所有 Provider 都支持所有参数。OpenClaw 在提交前会校验硬限制（如输入数量）。当 Provider 支持时长但最大值小于请求值时，OpenClaw 会钳制到支持的最近时长。完全不支持的可选提示会被忽略并发出警告。工具结果会报告实际应用设置；details.normalization 记录参数请求值与实际应用值的映射。

Provider 请求超时只能在 Operator 配置中设置。OpenClaw 使用 agents.defaults.musicGenerationModel.timeoutMs（如有配置），低于 120000ms 的值自动提升到 120000ms，否则默认 300000ms。

异步行为

Session-backed 的音乐生成作为后台任务运行：

• 后台任务：music_generate 创建一个后台任务，立即返回 started/task 响应，后续在 Agent 消息中发送完成的音轨。
• 防重复：当任务状态为 queued 或 running 时，同一会话后续的 music_generate 调用会返回任务状态，不会启动新生成。使用 action: "status" 显式检查。
• 状态查询：openclaw tasks list 或 openclaw tasks show <taskId> 检查排队、运行中和最终状态。
• 完成唤醒：OpenClaw 向同一会话注入内部完成事件，让模型自己编写面向用户的后续消息。
• 提示提示：同一会话后续的人工请求，如果已有音乐任务在飞行，会收到一个运行时提示，避免模型盲目再次调用 music_generate。
• 无会话回退：直接/本地上下文（无真实 Agent 会话）使用内联方式，在同一轮次返回最终音频结果。

任务生命周期

状态	含义
queued	任务已创建，等待 Provider 接受。
running	Provider 正在处理（通常 30 秒到 3 分钟，取决于 Provider 和时长）。
succeeded	音轨就绪；Agent 被唤醒并发布到会话。
failed	Provider 错误或超时；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"],
      },
    },
  },
}

Provider 选择顺序

OpenClaw 按以下顺序尝试 Provider：

1. model 参数（Agent 在工具调用中指定时）。
2. musicGenerationModel.primary（配置中）。
3. musicGenerationModel.fallbacks（按顺序）。
4. 自动检测：仅使用已认证的 Provider 默认值——先尝试当前默认 Provider，再依次按 Provider ID 顺序尝试其他已注册的音乐生成 Provider。

如果某个 Provider 失败，自动尝试下一个。如果全部失败，错误信息包含每次尝试的详细信息。

设置 agents.defaults.mediaGenerationAutoProviderFallback: false 可仅使用显式的 model、primary 和 fallbacks 条目。

Provider 说明

ComfyUI

由 Workflow 驱动，取决于配置的图形和 prompt/output 节点映射。内置 `comfy` 插件通过音乐生成 Provider 注册表接入共享的 `music_generate` 工具。

fal

通过共享 Provider 认证路径使用 fal 模型端点。内置 Provider 默认使用 `fal-ai/minimax-music/v2.6`，也暴露 `fal-ai/ace-step/prompt-to-audio` 和 `fal-ai/stable-audio-25/text-to-audio` 用于 prompt-to-audio 请求。

Google (Lyria 3)

使用 Lyria 3 批量生成。当前内置流程支持 prompt、可选歌词文本和可选参考图片。

MiniMax

使用批量 `music_generation` 端点。支持 prompt、可选歌词、纯器乐模式，以及通过 `minimax` API Key 认证或 `minimax-portal` OAuth 输出 mp3。

OpenRouter

使用 OpenRouter Chat Completions 音频输出（流式启用）。内置 Provider 默认使用 `google/lyria-3-pro-preview`，也暴露 `openrouter/google/lyria-3-clip-preview`。

如何选择

• 共享 Provider 方式：需要模型选择、Provider 回退、内置异步任务/状态流程时。
• 插件路径（ComfyUI）：需要自定义 workflow 图形或 Provider 不在共享音乐能力中时。

调试 ComfyUI 特定行为，参见 ComfyUI。调试共享 Provider 行为，参考 fal、Google (Gemini)、MiniMax 或 OpenRouter。

Provider 能力模式

共享音乐生成契约支持显式模式声明：

• generate：仅 prompt 生成。
• edit：请求包含一个或多个参考图片时。

新的 Provider 实现应使用显式模式块：

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

传统的平面字段（如 maxInputImages、supportsLyrics、supportsFormat）不足以声明编辑支持。Provider 应显式声明 generate 和 edit，以便实时测试、契约测试和共享的 music_generate 工具能够确定性地验证模式支持。

实时测试

内置共享 Provider 的可选实时覆盖：

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

仓库快捷方式：

pnpm test:live:media music

此实时文件默认优先使用已导出的 Provider 环境变量（而非存储的认证配置），并在 Provider 启用编辑模式时同时运行 generate 和声明的 edit 覆盖。当前覆盖范围：

• google：generate + edit
• fal：仅 generate
• minimax：仅 generate
• openrouter：generate + edit
• comfy：独立的 Comfy 实时覆盖，不在共享 Provider sweep 中

内置 ComfyUI 音乐路径的可选实时覆盖：

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

Comfy 实时文件在相关部分配置了相应章节时，也会覆盖 Comfy 图片和视频 workflow。

相关文档

• 后台任务 — 独立 music_generate 运行的任务追踪
• ComfyUI Provider
• 配置参考 — musicGenerationModel 配置
• Google (Gemini) Provider
• MiniMax Provider
• 模型配置 — 模型配置和回退
• 工具总览

常见问题

music_generate 工具不显示在 Agent 工具列表中怎么办？

确认至少一个音乐生成 Provider 已配置并认证。检查 agents.defaults.musicGenerationModel 是否已设置（或至少设置了一个 Provider 的 API Key）。运行 /tool music_generate action=list 可验证运行时是否有可用 Provider。

音乐生成任务提交后怎么确认完成状态？

在 Agent 会话中，OpenClaw 会在后台任务完成时自动唤醒 Agent 并发送音频。你也可以用 openclaw tasks list 或 openclaw tasks show <taskId> 查看任务状态（queued/running/succeeded/failed）。在会话中用 /tool music_generate action=status 查看当前活跃任务。

生成失败（failed）时怎么排查？

检查 Provider API Key 是否有效、是否有配额限制。查看 Provider 日志（如 openclaw doctor）和任务详情 openclaw tasks show <taskId>。如果使用了 ComfyUI，确认 workflow 配置正确。如果使用共享 Provider，尝试用 /tool music_generate action=list 确认模型是否可用。