Generazione musicale

# Comportamento asincrono

La generazione musicale basata su sessione viene eseguita come attività in background:

• Attività in background: music_generate crea un'attività in background, restituisce subito una risposta di avvio/attività e pubblica la traccia finale più tardi in un messaggio successivo dell'agente.
• Prevenzione dei duplicati: mentre un'attività è queued o running, le chiamate successive a music_generate nella stessa sessione restituiscono lo stato dell'attività invece di avviare un'altra generazione. Usa action: "status" per verificare esplicitamente.
• Ricerca dello stato: openclaw tasks list o openclaw tasks show <taskId> ispeziona lo stato in coda, in esecuzione e terminale.
• Risveglio di completamento: OpenClaw inietta di nuovo un evento di completamento interno nella stessa sessione, così il modello può scrivere autonomamente il follow-up rivolto all'utente.
• Suggerimento nel prompt: i turni utente/manuali successivi nella stessa sessione ricevono un piccolo suggerimento runtime quando un'attività musicale è già in corso, così il modello non chiama di nuovo music_generate alla cieca.
• Fallback senza sessione: i contesti diretti/locali senza una vera sessione dell'agente vengono eseguiti inline e restituiscono il risultato audio finale nello stesso turno.

# Ciclo di vita dell'attività

Controlla lo stato dalla CLI:

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.6"],
      },
    },
  },
}

# Ordine di selezione dei provider

OpenClaw prova i provider in questo ordine:

1. Parametro model dalla chiamata allo 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 basati su autenticazione:
   • prima il provider predefinito corrente;
   • poi i restanti provider registrati di generazione musicale, in ordine di provider-id.

Se un provider fallisce, il candidato successivo viene provato automaticamente. Se tutti falliscono, l'errore include i dettagli di ogni tentativo.

Imposta agents.defaults.mediaGenerationAutoProviderFallback: false per usare solo voci esplicite model, primary e fallbacks.

# Note sui provider

# Scegliere il percorso giusto

• Basato su provider condiviso quando vuoi selezione del modello, failover del provider e il flusso asincrono integrato di attività/stato.
• Percorso Plugin (ComfyUI) quando ti serve un grafo di workflow personalizzato o un provider che non fa parte della funzionalità musicale condivisa inclusa.

Se stai eseguendo il debug di un comportamento specifico di ComfyUI, consulta ComfyUI. Se stai eseguendo il debug del comportamento di un provider condiviso, inizia da Google (Gemini) o MiniMax.

# Modalità delle funzionalità del provider

Il contratto condiviso di generazione musicale supporta dichiarazioni di modalità esplicite:

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

Le nuove implementazioni di provider dovrebbero preferire blocchi di modalità espliciti:

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

I campi flat legacy come maxInputImages, supportsLyrics e supportsFormat non bastano per dichiarare il supporto alla modifica. I provider dovrebbero dichiarare generate ed edit esplicitamente, così i test live, i test di contratto e lo strumento condiviso music_generate possono convalidare il supporto delle modalità in modo deterministico.

# Test live

Copertura live opt-in per i provider condivisi inclusi:

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

Wrapper del repository:

pnpm test:live:media music

Questo file live carica le variabili d'ambiente dei provider mancanti da ~/.profile, preferisce per impostazione predefinita le chiavi API live/env rispetto ai profili di autenticazione memorizzati ed esegue sia la copertura generate sia la copertura edit dichiarata quando il provider abilita la modalità di modifica. Copertura attuale:

• google: generate più edit
• minimax: solo generate
• comfy: copertura separata in ambiente reale di Comfy, non il controllo condiviso dei provider

Copertura in ambiente reale attivabile esplicitamente per il percorso musicale ComfyUI incluso:

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

Il file live di Comfy copre anche i flussi di lavoro di immagini e video comfy quando quelle sezioni sono configurate.

# Correlati

• Attività in background — monitoraggio delle attività per esecuzioni music_generate scollegate
• ComfyUI
• Riferimento di configurazione — configurazione musicGenerationModel
• Google (Gemini)
• MiniMax
• Modelli — configurazione dei modelli e failover
• Panoramica degli strumenti