跳轉到主要內容
music_generate 工具會透過共用的音樂生成能力建立音樂或音訊，並由 ComfyUI、fal、Google、MiniMax 和 OpenRouter 支援。
music_generate 只會在至少有一個音樂生成提供者可用時出現：明確的 agents.defaults.musicGenerationModel 設定，或已設定驗證的提供者（例如已設定 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

詢問代理

“生成一首關於夜間開車穿越霓虹城市、節奏明快的 synthpop 曲目。”代理會自動呼叫 music_generate。不需要工具允許清單。
沒有工作階段支援的代理執行時（直接/本機情境），工具會以內嵌方式執行，並在同一個工具結果中傳回最終媒體路徑。
範例提示： 
Generate a cinematic piano track with soft strings and no vocals.

Generate an energetic chiptune loop about launching a rocket at sunrise.
使用 action: "list" 檢查可用的提供者/模型，並使用 action: "status" 檢查作用中的工作階段支援音樂工作： 
/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

​
支援的提供者

提供者預設模型參考輸入支援的控制項驗證
ComfyUIworkflow最多 1 張圖片工作流程定義的音樂或音訊COMFY_API_KEY, COMFY_CLOUD_API_KEY
falfal-ai/minimax-music/v2.6無lyrics, instrumental, durationSeconds, formatFAL_KEY 或 FAL_API_KEY
Googlelyria-3-clip-preview最多 10 張圖片lyrics, instrumental, formatGEMINI_API_KEY, GOOGLE_API_KEY
MiniMaxmusic-2.6無lyrics, instrumental, format（僅 mp3）MINIMAX_API_KEY 或 MiniMax OAuth
OpenRoutergoogle/lyria-3-pro-preview最多 1 張圖片lyrics, instrumental, durationSeconds, formatOPENROUTER_API_KEY
MiniMax 會註冊兩個共用相同模型的提供者 ID：minimax 用於 API 金鑰驗證，minimax-portal 用於 OAuth。模型參照會遵循驗證路徑（minimax/music-2.6 與 minimax-portal/music-2.6）；請參閱 MiniMax。 fal 也會公開 fal-ai/ace-step/prompt-to-audio（wav、無歌詞、無純樂器切換）和 fal-ai/stable-audio-25/text-to-audio（wav、僅提示），以及其預設的 MiniMax 支援模型。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、合約測試和共用即時掃描使用的明確模式合約：
提供者generateedit編輯限制共用即時通道
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.musicGenerationModel.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 字母順序排列。
如果提供者失敗，會自動嘗試下一個候選項。如果全部失敗，錯誤會包含每次嘗試的詳細資料。 將 agents.defaults.mediaGenerationAutoProviderFallback: false 設為只使用明確的 model、primary 和 fallbacks 項目。

​
提供者注意事項

由工作流程驅動，且提示/輸出欄位取決於已設定的圖形與節點對應。 內建的 comfy 外掛會透過音樂生成供應商登錄機制，接入共用的 music_generate 工具。
透過共用的供應商驗證路徑使用 fal 模型端點。內建供應商預設為 fal-ai/minimax-music/v2.6，也會公開 fal-ai/ace-step/prompt-to-audio 與 fal-ai/stable-audio-25/text-to-audio 以供提示轉音訊請求使用。 歌詞與演奏模式僅限 MiniMax 模型；另外兩個模型僅支援提示。
使用 Lyria 3 批次生成。目前的內建流程支援提示、選用歌詞文字， 以及選用參考圖片。預設的 lyria-3-clip-preview 模型僅輸出 mp3； lyria-3-pro-preview 模型也支援 wav。
使用批次 music_generation 端點。支援提示、選用歌詞、演奏模式， 並可透過 minimax API 金鑰驗證或 minimax-portal OAuth 輸出 mp3。 也會公開 music-2.6-free、music-cover 與 music-cover-free 模型。
在啟用串流的情況下使用 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
等效的 repo 包裝命令，會驅動同一個測試檔案： 
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 圖片與影片工作流程。

​
相關