音楽生成

# 非同期動作

セッションに裏付けられた音楽生成はバックグラウンドタスクとして実行されます:

• バックグラウンドタスク: music_generate はバックグラウンドタスクを作成し、開始済み/タスクの応答をただちに返し、後続のエージェントメッセージで完成したトラックを後から投稿します。
• 重複防止: タスクが queued または running の間、同じセッション内で後続の music_generate 呼び出しがあると、別の生成を開始せずにタスクステータスを返します。明示的に確認するには action: "status" を使用します。
• ステータス確認: openclaw tasks list または openclaw tasks show <taskId> は、キュー済み、実行中、終端ステータスを確認します。
• 完了時の起動: OpenClaw は内部の完了イベントを同じセッションに注入し、モデルがユーザー向けのフォローアップを自分で書けるようにします。
• プロンプトヒント: 同じセッションで後続のユーザー/手動ターンが発生した場合、音楽タスクがすでに進行中であれば小さなランタイムヒントを受け取り、モデルが不用意に再度 music_generate を呼び出さないようにします。
• セッションなしのフォールバック: 実際のエージェントセッションがない直接/ローカルコンテキストではインラインで実行され、同じターンで最終オーディオ結果を返します。

# タスクライフサイクル

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 は次の順序でプロバイダーを試します:

1. ツール呼び出しの model パラメーター（エージェントが指定した場合）。
2. 構成の musicGenerationModel.primary。
3. musicGenerationModel.fallbacks を順番に。
4. 認証に裏付けられたプロバイダー既定値のみを使った自動検出:
   • 現在の既定プロバイダーを最初に使用。
   • 残りの登録済み音楽生成プロバイダーをプロバイダー ID 順に使用。

プロバイダーが失敗した場合は、次の候補が自動的に試されます。すべて失敗した場合、エラーには各試行の詳細が含まれます。

明示的な model、primary、fallbacks エントリのみを使用するには、agents.defaults.mediaGenerationAutoProviderFallback: false を設定します。

# プロバイダーノート

# 適切な経路の選択

• 共有プロバイダー利用 は、モデル選択、プロバイダーフェイルオーバー、組み込みの非同期タスク/ステータスフローが必要な場合に使います。
• Plugin パス (ComfyUI) は、カスタムワークフローグラフ、または共有のバンドル音楽機能に含まれないプロバイダーが必要な場合に使います。

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

# プロバイダー機能モード

共有音楽生成契約は明示的なモード宣言に対応しています:

• プロンプトのみの生成には 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 を明示的に宣言する必要があります。

# ライブテスト

共有バンドルプロバイダー向けのオプトインライブカバレッジ:

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

リポジトリラッパー:

pnpm test:live:media music

このライブファイルは、不足しているプロバイダー環境変数を ~/.profile から読み込み、既定では保存済み認証プロファイルよりライブ/env 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 の画像および動画ワークフローも対象にします。

# 関連

• バックグラウンドタスク — 切り離された music_generate 実行のタスク追跡
• ComfyUI
• 設定リファレンス — musicGenerationModel 設定
• Google (Gemini)
• MiniMax
• モデル — モデル設定とフェイルオーバー
• ツール概要