OpenClawDocs

Search...K

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

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

快速開始

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

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

提示詞範例：

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

生成一段以日出時發射火箭為主題、充滿活力的晶片音樂循環。

使用 action: "list" 檢查可用的供應商／模型，並使用 action: "status" 檢查目前由工作階段支援的音樂工作：

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

直接生成範例：

/tool music_generate prompt="帶有黑膠唱片質感和輕柔雨聲的夢幻低傳真嘻哈" instrumental=true

支援的供應商

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、合約測試與共用即時掃描所使用的明確模式合約：

工具參數

供應商要求逾時僅能由操作者設定。若已設定，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）。大多數音樂執行會經過：

從命令列介面檢查狀態：

openclaw tasks listopenclaw 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）。

若要偵錯 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
• 模型 — 模型設定與容錯移轉
• 工具概覽

Install OpenClawSet up TelegramFix GatewayBuild a plugin

Ask Molty

Ask Molty

Molty

Responses are generated using AI and may contain mistakes.