Tools

音樂生成

music_generate 工具讓代理程式透過已設定提供者的共用音樂生成能力建立音樂或音訊，目前支援 Google、MiniMax，以及透過工作流程設定的 ComfyUI。

對於以工作階段支援的代理程式執行，OpenClaw 會將音樂生成啟動為背景任務，在任務帳本中追蹤它，然後在曲目準備好時再次喚醒代理程式，讓代理程式可以告知使用者並附上完成的音訊。在使用僅訊息工具可見傳遞的群組/頻道聊天中，代理程式會透過訊息工具轉送結果。如果完成代理程式只寫入私人最終回覆，OpenClaw 會改用直接頻道傳送來傳送生成的媒體。完成喚醒會明確警告代理程式，在這些路由中一般的最終回覆是私人的。

快速開始

Shared provider-backed

Configure auth

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

Pick a default model (optional)

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

Ask the agent

"Generate an upbeat synthpop track about a night drive through a neon city."

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

對於沒有以工作階段支援的代理程式執行的直接同步情境，內建工具仍會退回到行內生成，並在工具結果中傳回最終媒體路徑。

ComfyUI workflow

Configure the workflow

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

Cloud auth (optional)

對於 Comfy Cloud，請設定 COMFY_API_KEY 或 COMFY_CLOUD_API_KEY。

Call the tool

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

範例提示：

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

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

支援的提供者

提供者	預設模型	參考輸入	支援的控制項	身分驗證
ComfyUI	`workflow`	最多 1 張圖片	工作流程定義的音樂或音訊	`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.6`	無	`lyrics`, `instrumental`, `durationSeconds`, `format=mp3`	`MINIMAX_API_KEY` 或 MiniMax OAuth

能力矩陣

music_generate、契約測試，以及共用即時掃描使用的明確模式契約：

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

使用 action: "list" 在執行階段檢查可用的共用提供者和模型：

/tool music_generate action=list

使用 action: "status" 檢查作用中的以工作階段支援的音樂任務：

/tool music_generate action=status

直接生成範例：

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

工具參數

promptstringrequired

音樂生成提示。action: "generate" 必填。

action"generate" | "status" | "list"

"status" 會傳回目前的工作階段任務；"list" 會檢查提供者。

modelstring

提供者/模型覆寫（例如 google/lyria-3-pro-preview、comfy/workflow）。

lyricsstring

當提供者支援明確的歌詞輸入時，可選擇提供歌詞。

instrumentalboolean

當提供者支援時，要求僅器樂輸出。

imagestring

單一參考圖片路徑或 URL。

imagesstring[]

多張參考圖片（在支援的提供者上最多 10 張）。

durationSecondsnumber

當提供者支援時，以秒為單位的目標持續時間提示。

format"mp3" | "wav"

當提供者支援時的輸出格式提示。

filenamestring

timeoutMsnumber

非同步行為

以工作階段支援的音樂生成會以背景任務執行：

背景任務： music_generate 會建立背景任務，立即傳回已開始/任務回應，並稍後在後續代理程式訊息中發布完成的曲目。
防止重複： 當任務為 queued 或 running 時，同一工作階段中後續的 music_generate 呼叫會傳回任務狀態，而不是啟動另一個生成。使用 action: "status" 明確檢查。
狀態查詢： openclaw tasks list 或 openclaw tasks show <taskId> 會檢查已排佇、執行中和終端狀態。
完成喚醒： OpenClaw 會將內部完成事件注入回同一工作階段，讓模型可以自行寫入面向使用者的後續訊息。
提示提示： 同一工作階段中稍後的使用者/手動回合，會在已有音樂任務進行中時取得小型執行階段提示，讓模型不會盲目再次呼叫 music_generate。
無工作階段退回： 沒有真實代理程式工作階段的直接/本機情境會行內執行，並在同一回合傳回最終音訊結果。

任務生命週期

狀態	意義
`queued`	任務已建立，正在等待提供者接受。
`running`	提供者正在處理（通常為 30 秒到 3 分鐘，視提供者與時長而定）。
`succeeded`	音軌已就緒；代理程式會喚醒並將它發布到對話中。
`failed`	提供者錯誤或逾時；代理程式會帶著錯誤詳細資料喚醒。

從 CLI 檢查狀態：

openclaw tasks list
openclaw tasks show <taskId>
openclaw tasks cancel <taskId>

設定

模型選擇

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

提供者選擇順序

OpenClaw 會依照以下順序嘗試提供者：

工具呼叫中的 model 參數（如果代理程式有指定）。
設定中的 musicGenerationModel.primary。
依序使用 musicGenerationModel.fallbacks。
僅使用具備驗證支援的提供者預設值進行自動偵測：
- 目前的預設提供者優先；
- 其餘已註冊的音樂生成提供者，依提供者 ID 順序。

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

設定 agents.defaults.mediaGenerationAutoProviderFallback: false 可只使用明確的 model、primary 與 fallbacks 項目。

提供者注意事項

ComfyUI

由工作流程驅動，並依賴已設定的圖表加上用於提示/輸出欄位的節點對應。內建的 comfy Plugin 會透過音樂生成提供者登錄檔接入共用的 music_generate 工具。

Google (Lyria 3)

使用 Lyria 3 批次生成。目前的內建流程支援提示、選用歌詞文字，以及選用參考圖片。

MiniMax

使用批次 music_generation 端點。透過 minimax API 金鑰驗證或 minimax-portal OAuth，支援提示、選用歌詞、純器樂模式、時長引導，以及 mp3 輸出。

選擇正確路徑

當你需要模型選擇、提供者容錯移轉，以及內建非同步任務/狀態流程時，使用共用的提供者支援路徑。
當你需要自訂工作流程圖，或需要不屬於共用內建音樂能力的提供者時，使用 Plugin 路徑 (ComfyUI)。

如果你正在偵錯 ComfyUI 專屬行為，請參閱 ComfyUI。如果你正在偵錯共用提供者行為，請從 Google (Gemini) 或 MiniMax 開始。

提供者能力模式

共用的音樂生成合約支援明確的模式宣告：

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 工具能以決定性的方式驗證模式支援。

即時測試

共用內建提供者的選用即時涵蓋範圍：

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

Repo 包裝器：

pnpm test:live:media music

這個即時檔案會從 ~/.profile 載入缺少的提供者環境變數，預設優先使用即時/環境 API 金鑰，而不是已儲存的驗證設定檔，並且在提供者啟用編輯模式時，同時執行 generate 與已宣告的 edit 涵蓋範圍。目前涵蓋範圍：

google：generate 加上 edit
minimax：僅 generate
comfy：獨立的 Comfy 即時測試涵蓋範圍，而不是共用的提供者掃描

隨附 ComfyUI 音樂路徑的選用即時測試涵蓋範圍：

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

當已設定對應區段時，Comfy 即時測試檔案也會涵蓋 Comfy 圖片和影片工作流程。

音樂生成

快速開始

Shared provider-backed

Configure auth

Pick a default model (optional)

Ask the agent

ComfyUI workflow

Configure the workflow

Cloud auth (optional)

Call the tool

支援的提供者

能力矩陣

工具參數

非同步行為

任務生命週期

設定

模型選擇

提供者選擇順序

提供者注意事項

選擇正確路徑

提供者能力模式

即時測試

相關

Ask OpenClaw

# 快速開始

Shared provider-backed

Configure auth

Pick a default model (optional)

Ask the agent

ComfyUI workflow

Configure the workflow

Cloud auth (optional)

Call the tool

# 支援的提供者

# 能力矩陣

# 工具參數

# 非同步行為

# 任務生命週期

# 設定

# 模型選擇

# 提供者選擇順序

# 提供者注意事項

# 選擇正確路徑

# 提供者能力模式

# 即時測試

# 相關

快速開始

支援的提供者

能力矩陣

工具參數

非同步行為

任務生命週期

設定

模型選擇

提供者選擇順序

提供者注意事項

選擇正確路徑

提供者能力模式

即時測試

相關