音樂生成

music_generate 工具會透過共用的音樂生成功能建立音樂或音訊，後端支援 ComfyUI、fal、Google、MiniMax 與 OpenRouter。

只有在至少有一個音樂生成提供者可用時，才會顯示 music_generate：明確的 agents.defaults.mediaModels.music 設定，或已設定驗證的提供者（例如已設定 API 金鑰）。

對於以工作階段為基礎的代理程式執行，music_generate 會以背景工作啟動、在工作帳本中追蹤進度，並在音軌就緒時喚醒代理程式，讓它通知使用者並附上完成的音訊。完成代理程式會遵循工作階段的可見回覆合約：設定時自動傳送最終回覆，或在工作階段要求使用訊息工具時使用 message(action="send")。如果請求者的工作階段未啟用，或喚醒失敗，且回覆中仍缺少生成的音訊，OpenClaw 會傳送僅包含缺漏音訊的冪等直接備援訊息。

​

快速開始

共用提供者後端

1. 設定驗證

   為至少一個提供者設定 API 金鑰，例如 GEMINI_API_KEY 或 MINIMAX_API_KEY。

2. 選擇預設模型（選用）

   {
     agents: {
       defaults: {
         musicGenerationModel: {
           primary: "google/lyria-3-clip-preview",
         },
       },
     },
   }
   
3. 向代理程式提出要求

   「生成一首關於夜間駕車穿越霓虹城市、節奏輕快的合成器流行音樂。」

   代理程式會自動呼叫 music_generate，不需要將工具加入允許清單。

如果不是以工作階段為基礎的代理程式執行（直接／本機情境），工具會內嵌執行，並在相同的工具結果中傳回最終媒體路徑。

ComfyUI 工作流程

1. 設定工作流程

   使用工作流程 JSON 及提示詞／輸出節點設定 plugins.entries.comfy.config.music。

2. 雲端驗證（選用）

   若使用 Comfy Cloud，請設定 COMFY_API_KEY 或 COMFY_CLOUD_API_KEY。

3. 呼叫工具

   /tool music_generate prompt="帶有柔和磁帶質感的溫暖環境合成器循環樂段"
   

提示詞範例：

生成一首帶有柔和弦樂且無人聲的電影感鋼琴曲。

生成一段關於在日出時發射火箭、充滿活力的晶片音樂循環樂段。

使用 action: "list" 檢查可用的提供者／模型，並使用 action: "status" 檢查以工作階段為基礎且目前啟用的音樂工作：

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

直接生成範例：

/tool music_generate prompt="帶有黑膠質感與柔和雨聲的夢幻 lo-fi 嘻哈音樂" instrumental=true

​

支援的提供者

提供者	預設模型	參考輸入	支援的控制項	驗證
ComfyUI	workflow	最多 1 張圖片	由工作流程定義的音樂或音訊	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

MiniMax 會註冊兩個共用相同模型的提供者 ID：minimax 用於 API 金鑰驗證，minimax-portal 用於 OAuth。模型參照會依循驗證路徑（minimax/music-2.6 與 minimax-portal/music-2.6）；請參閱 MiniMax。

除了預設的 MiniMax 後端模型外，fal 也提供 fal-ai/ace-step/prompt-to-audio（wav、無歌詞、無純器樂切換選項）與 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、合約測試與共用即時掃描所使用的明確模式合約：

提供者	generate	edit	編輯限制	共用即時測試通道
ComfyUI	✓	✓	1 張圖片	不包含在共用掃描中；由 extensions/comfy/comfy.live.test.ts 涵蓋
fal	✓	—	無	generate
Google	✓	✓	10 張圖片	generate、edit
MiniMax	✓	—	無	generate
OpenRouter	✓	✓	1 張圖片	generate、edit

​

工具參數

prompt · string · 必填

音樂生成提示詞。action: "generate" 必須提供此參數。

action · "generate" | "status" | "list" · 預設值: "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.mediaModels.music.timeoutMs，將低於 120000ms 的值提高至 120000ms；否則，提供者要求的預設逾時為 300000ms。

​

非同步行為

以工作階段為基礎的音樂生成會以背景工作執行：

• 背景工作：music_generate 會建立背景工作、立即傳回已啟動／工作回應，並於稍後在後續代理程式訊息中張貼完成的音軌。
• **防止重複：**工作處於 queued 或 running 狀態時，同一工作階段中後續的 music_generate 呼叫會傳回工作狀態，而不是啟動另一個生成工作。使用 action: "status" 可明確檢查。最近完成且相符的要求也會在 2 分鐘內進行去重。
• 狀態查詢：openclaw tasks list 或 openclaw tasks show <taskId> 會檢查已排入佇列、執行中及終止狀態。
• **完成喚醒：**OpenClaw 會將內部完成事件注入回相同的工作階段，讓模型自行撰寫面向使用者的後續回覆。
• **提示詞提醒：**如果音樂工作已在執行，同一工作階段中後續的使用者／手動回合會收到簡短的執行階段提示，避免模型盲目地再次呼叫 music_generate。
• **無工作階段備援：**沒有實際代理程式工作階段的直接／本機情境會內嵌執行，並在相同回合中傳回最終音訊結果。

​

工作生命週期

音樂工作會呈現與一般工作登錄檔相同的狀態（如需包含 timed_out、cancelled 與 lost 在內的完整狀態機，請參閱背景工作）。大多數音樂執行會經過：

狀態	意義
queued	工作已建立，正在等待提供者接受。
running	提供者正在處理（通常需要 30 秒至 3 分鐘，視提供者與時長而定）。
succeeded	音軌已就緒；代理程式會被喚醒並將其張貼至對話。
failed	提供者發生錯誤或逾時；代理程式會被喚醒並取得錯誤詳細資料。

從命令列介面檢查狀態：

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 參數（如果代理程式有指定）。
2. 設定中的 musicGenerationModel.primary。
3. 依序使用 musicGenerationModel.fallbacks。
4. 僅使用具備驗證資訊的提供者預設值進行自動偵測：
   • 如果目前的預設文字模型提供者也提供音樂生成功能，則優先使用；
   • 其餘已註冊的音樂生成提供者，依提供者 ID 的字母順序排列。

如果提供者失敗，系統會自動嘗試下一個候選項目。如果全部失敗，錯誤會包含每次嘗試的詳細資料。

一律啟用已驗證提供者之間的自動備援。每次呼叫指定的 model 仍具有最高決定權。

​

提供者注意事項

ComfyUI

由工作流程驅動，並取決於已設定的圖形以及提示詞／輸出欄位的節點對應。 內建的 comfy 外掛會透過音樂生成提供者登錄檔，接入共用的 music_generate 工具。

fal

透過共用的提供者驗證路徑使用 fal 模型端點。內建提供者預設使用 fal-ai/minimax-music/v2.6，並且也公開 fal-ai/ace-step/prompt-to-audio 和 fal-ai/stable-audio-25/text-to-audio，以處理提示詞轉音訊請求。 歌詞與純音樂模式僅適用於 MiniMax 模型；另外兩個模型僅支援提示詞。

Google (Lyria 3)

使用 Lyria 3 批次生成。目前的內建流程支援提示詞、選用的歌詞文字，以及選用的參考圖片。 預設的 lyria-3-clip-preview 模型僅輸出 mp3； lyria-3-pro-preview 模型也支援 wav。

MiniMax

使用批次 music_generation 端點。支援提示詞、選用的歌詞、純音樂模式， 以及透過 minimax API 金鑰驗證或 minimax-portal OAuth 輸出 mp3。也公開 music-2.6-free、 music-cover 和 music-cover-free 模型。

OpenRouter

使用已啟用串流的 OpenRouter 聊天補全音訊輸出。內建提供者預設使用 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 等舊版扁平欄位，不足以表明支援編輯。提供者應明確宣告 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 圖片和影片工作流程。

​

相關內容

• 背景任務 — 追蹤分離執行的 music_generate 任務
• ComfyUI
• 設定參考 — musicGenerationModel 設定
• Google (Gemini)
• MiniMax
• 模型 — 模型設定與容錯移轉
• 工具概覽