音楽生成

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

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

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

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

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

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

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

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

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

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

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 が優先されます。

プロバイダーに関する注意事項

適切なパスの選択

• モデルの選択、プロバイダーのフェイルオーバー、および組み込みの非同期タスク／ステータスフローが必要な場合は、共有プロバイダー基盤。
• カスタムワークフローグラフ、または共有のバンドル済み音楽機能に含まれないプロバイダーが必要な場合は、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
• モデル — モデルの設定とフェイルオーバー
• ツールの概要