​

Generazione musicale

​

Avvio rapido

​

Generazione supportata da provider condivisi

1. Imposta una chiave API per almeno un provider, ad esempio GEMINI_API_KEY oppure MINIMAX_API_KEY.
2. Facoltativamente imposta il tuo modello preferito:

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

3. Chiedi all’agente: “Genera una traccia synthpop energica su una guida notturna attraverso una città al neon.”

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

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

​

Generazione Comfy guidata da workflow

1. Configura models.providers.comfy.music con un JSON di workflow e nodi prompt/output.
2. Se usi Comfy Cloud, imposta COMFY_API_KEY oppure COMFY_CLOUD_API_KEY.
3. Chiedi all’agente di generare musica oppure chiama direttamente lo strumento.

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

​

Supporto dei provider inclusi condivisi

​

Matrice delle capability dichiarate

/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

​

Parametri dello strumento integrato

​

Comportamento asincrono per il percorso supportato da provider condivisi

• Esecuzioni dell’agente supportate da sessione: music_generate crea un task in background, restituisce immediatamente una risposta di avvio/task e pubblica la traccia completata più tardi in un messaggio di follow-up dell’agente.
• Prevenzione dei duplicati: mentre quel task in background è ancora queued oppure running, le chiamate successive a music_generate nella stessa sessione restituiscono lo stato del task invece di avviare un’altra generazione.
• Ricerca dello stato: usa action: "status" per ispezionare il task musicale attivo supportato da sessione senza avviare una nuova generazione.
• Tracciamento del task: usa openclaw tasks list oppure openclaw tasks show <taskId> per ispezionare lo stato in coda, in esecuzione e terminale della generazione.
• Riattivazione al completamento: OpenClaw inietta un evento interno di completamento nella stessa sessione così il modello può scrivere da solo il follow-up rivolto all’utente.
• Suggerimento nel prompt: i successivi turni utente/manuali nella stessa sessione ricevono un piccolo suggerimento runtime quando un task musicale è già in corso così il modello non richiama alla cieca music_generate.
• Fallback senza sessione: i contesti diretti/locali senza una vera sessione agente continuano a essere eseguiti inline e restituiscono il risultato audio finale nello stesso turno.

​

Ciclo di vita del task

1. queued — task creato, in attesa che il provider lo accetti.
2. running — il provider sta elaborando (tipicamente da 30 secondi a 3 minuti a seconda del provider e della durata).
3. succeeded — traccia pronta; l’agente si riattiva e la pubblica nella conversazione.
4. failed — errore del provider o timeout; l’agente si riattiva con i dettagli dell’errore.

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

​

Configurazione

​

Selezione del modello

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

​

Ordine di selezione del provider

1. parametro model dalla chiamata dello strumento, se l’agente ne specifica uno
2. musicGenerationModel.primary dalla configurazione
3. musicGenerationModel.fallbacks in ordine
4. rilevamento automatico usando solo i valori predefiniti dei provider supportati da auth:
   • prima il provider predefinito corrente
   • poi i restanti provider di generazione musicale registrati in ordine di ID provider

​

Note sui provider

• Google usa la generazione batch Lyria 3. L’attuale flusso incluso supporta prompt, testo facoltativo dei testi e immagini di riferimento facoltative.
• MiniMax usa l’endpoint batch music_generation. L’attuale flusso incluso supporta prompt, testi facoltativi, modalità strumentale, controllo della durata e output mp3.
• Il supporto ComfyUI è guidato da workflow e dipende dal grafo configurato più la mappatura dei nodi per i campi prompt/output.

​

Modalità di capability del provider

• generate per generazione solo da prompt
• edit quando la richiesta include una o più immagini di riferimento

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

​

Scegliere il percorso giusto

• Usa il percorso supportato da provider condivisi quando vuoi selezione del modello, failover del provider e il flusso asincrono integrato task/status.
• Usa un percorso plugin come ComfyUI quando ti serve un grafo di workflow personalizzato o un provider che non fa parte della capability musicale condivisa inclusa.
• Se stai eseguendo il debug di un comportamento specifico di ComfyUI, vedi ComfyUI. Se stai eseguendo il debug di un comportamento del provider condiviso, inizia da Google (Gemini) oppure MiniMax.

​

Test live

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

pnpm test:live:media music

• google: generate più edit
• minimax: solo generate
• comfy: copertura live Comfy separata, non nello sweep dei provider condivisi

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

​

Correlati

• Task in background - tracciamento dei task per esecuzioni music_generate scollegate
• Riferimento configurazione - configurazione musicGenerationModel
• ComfyUI
• Google (Gemini)
• MiniMax
• Models - configurazione del modello e failover
• Panoramica degli strumenti