音楽生成

音楽生成プロンプト。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 はプロンプトのみの生成用です。
• edit はリクエストに 1 つ以上の参照画像が含まれる場合に使用します。

新しいプロバイダー実装では、明示的なモードブロックを優先してください。

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
• モデル — モデル構成とフェイルオーバー
• ツール概要