音楽生成

音楽生成プロンプト。action: "generate" では必須です。

"status" は現在のセッションタスクを返し、"list" はプロバイダーを確認します。

プロバイダー／モデルの上書き（例：google/lyria-3-pro-preview、comfy/workflow）。

プロバイダーが明示的な歌詞入力に対応している場合に使用できる任意の歌詞。

プロバイダーが対応している場合、インストゥルメンタルのみの出力を要求します。

単一の参照画像のパスまたは URL。

複数の参照画像（対応プロバイダーでは最大 10 枚）。

プロバイダーが再生時間の指定に対応している場合の、秒単位の目標再生時間。

プロバイダーが対応している場合の出力形式指定。

プロバイダー要求のタイムアウトは、オペレーター設定でのみ指定できます。設定されている場合、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 を含む完全な状態遷移については、バックグラウンドタスク を参照してください）。ほとんどの音楽生成は、次の状態を遷移します。

CLI から状態を確認します。

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、primary、fallbacks エントリのみを使用するには、agents.defaults.mediaGenerationAutoProviderFallback: false を設定します。

プロバイダーに関する注記

適切なパスの選択

• モデル選択、プロバイダーのフェイルオーバー、組み込みの非同期タスクおよび ステータスフローが必要な場合は、共有プロバイダー経由。
• カスタムワークフローグラフ、または共有のバンドル済み音楽機能に含まれない プロバイダーが必要な場合は、Plugin パス（ComfyUI）。

ComfyUI 固有の動作をデバッグする場合は、 ComfyUI を参照してください。共有プロバイダーの 動作をデバッグする場合は、fal、Google (Gemini)、 MiniMax、または OpenRouter から 始めてください。

プロバイダー機能モード

共有音楽生成コントラクトは、明示的なモード宣言に対応しています。

• プロンプトのみの生成には generate。
• リクエストに1つ以上の参照画像が含まれる場合は edit。

新しいプロバイダー実装では、明示的なモードブロックを使用することを推奨します。

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

maxInputImages、supportsLyrics、supportsFormat などの従来の フラットフィールドだけでは、編集対応を表明するには不十分です。ライブテスト、 コントラクトテスト、共有 music_generate ツールがモード対応を決定論的に 検証できるように、プロバイダーは generate と edit を明示的に 宣言する必要があります。

ライブテスト

共有のバンドル済みプロバイダー（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
• モデル — モデル設定とフェイルオーバー
• ツール概要