​

音楽生成

​

クイックスタート

​

共有provider対応の生成

1. 少なくとも1つのproviderにAPIキーを設定します。たとえば GEMINI_API_KEY または MINIMAX_API_KEY です。
2. 必要に応じて、好みのmodelを設定します:

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

3. agentにこう依頼します: 「ネオンの街を夜にドライブすることをテーマにした、アップビートなシンセポップのトラックを生成して。」

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

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

​

Workflow駆動のComfy生成

1. models.providers.comfy.music にworkflow JSONと prompt/output nodeを設定します。
2. Comfy Cloudを使う場合は、COMFY_API_KEY または COMFY_CLOUD_API_KEY を設定します。
3. agentに音楽生成を依頼するか、toolを直接呼び出します。

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

​

共有バンドルproviderサポート

​

宣言されたcapabilityマトリクス

/tool music_generate action=list

/tool music_generate action=status

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

​

組み込みtoolパラメーター

​

共有provider対応経路の非同期動作

• sessionに紐づくagent実行: music_generate はバックグラウンドタスクを作成し、開始済み/task応答をすぐ返し、後でフォローアップagentメッセージとして完成したトラックを投稿します。
• 重複防止: そのバックグラウンドタスクがまだ queued または running の間は、同じsessionで後から呼ばれた music_generate は別の生成を開始せず、task statusを返します。
• status確認: 新しい生成を始めずに、アクティブなsession音楽タスクを確認するには action: "status" を使います。
• task追跡: 生成の queued、running、終了状態を確認するには openclaw tasks list または openclaw tasks show <taskId> を使います。
• 完了wake: OpenClawは同じsessionに内部完了イベントを注入し、model自身がユーザー向けのフォローアップを書けるようにします。
• プロンプトヒント: 同じsessionで後から行うユーザー/手動ターンには、音楽taskがすでに進行中であることを示す小さなruntime hintが付き、modelがむやみに music_generate を再度呼ばないようにします。
• no-sessionフォールバック: 実際のagent sessionがない直接/localコンテキストでは、引き続きインラインで実行し、同じターン内で最終音声結果を返します。

​

Taskライフサイクル

1. queued — taskが作成され、providerが受け付けるのを待っている。
2. running — providerが処理中（通常はproviderとdurationに応じて30秒から3分）。
3. succeeded — トラックの準備完了。agentが起きて会話に投稿する。
4. failed — providerエラーまたはタイムアウト。agentがエラー詳細とともに起きる。

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

​

設定

​

Model選択

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

​

Provider選択順

1. agentが指定した場合、tool callの model パラメーター
2. configの musicGenerationModel.primary
3. 順番どおりの musicGenerationModel.fallbacks
4. 認証済みproviderデフォルトのみを使う自動検出:
   • 現在のデフォルトproviderを最優先
   • 残りの登録済みmusic-generation providerをprovider-id順

​

Providerに関する注記

• GoogleはLyria 3のバッチ生成を使用します。現在のバンドルフローは prompt、任意の歌詞テキスト、任意の参照画像をサポートします。
• MiniMaxはバッチ music_generation endpointを使用します。現在のバンドルフローは prompt、任意の歌詞、instrumental mode、duration調整、 mp3出力をサポートします。
• ComfyUIサポートはworkflow駆動であり、設定されたgraphと prompt/output field向けnode mappingに依存します。

​

Provider capability mode

• promptのみの生成に対する generate
• 1枚以上の参照画像を含むリクエストに対する edit

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

​

適切な経路の選び方

• model選択、provider failover、組み込みの非同期task/statusフローが必要なら、共有provider対応経路を使ってください。
• カスタムworkflow graphや、共有バンドル音楽capabilityに含まれないproviderが必要な場合は、ComfyUIのようなplugin経路を使ってください。
• ComfyUI固有の動作をデバッグする場合は ComfyUI を参照してください。共有provider動作をデバッグする場合は、Google (Gemini) または MiniMax から始めてください。

​

Live test

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

pnpm test:live:media music

• google: generate と edit
• minimax: generate のみ
• comfy: 別個のComfy liveカバレッジであり、共有provider sweepではない

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

​

関連

• Background Tasks - 分離された music_generate 実行のtask追跡
• Configuration Reference - musicGenerationModel config
• ComfyUI
• Google (Gemini)
• MiniMax
• Models - model設定とfailover
• Tools Overview