Vai al contenuto principale
Lo strumento music_generate consente all’agente di creare musica o audio tramite la funzionalità condivisa di generazione musicale con provider configurati: ComfyUI, fal, Google, MiniMax e OpenRouter al momento. Per le esecuzioni dell’agente basate su sessione, OpenClaw avvia la generazione musicale come attività in background, la traccia nel registro delle attività, quindi riattiva di nuovo l’agente quando la traccia è pronta, così l’agente può informare l’utente e allegare l’audio completato. L’agente di completamento segue la normale modalità di risposta visibile della sessione: consegna automatica della risposta finale quando configurata, oppure message(action="send") quando la sessione richiede lo strumento per i messaggi. Se la sessione richiedente è inattiva o la sua riattivazione attiva non riesce, e nella risposta di completamento manca ancora parte dell’audio generato, OpenClaw invia un fallback diretto idempotente con solo l’audio mancante.
Lo strumento condiviso integrato appare solo quando è disponibile almeno un provider di generazione musicale. Se non vedi music_generate negli strumenti del tuo agente, configura agents.defaults.musicGenerationModel oppure imposta una chiave API del provider.

​
Avvio rapido

1

Configura l'autenticazione

Imposta una chiave API per almeno un provider, ad esempio GEMINI_API_KEY o MINIMAX_API_KEY.
2

Scegli un modello predefinito (opzionale)

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

Chiedi all'agente

“Generate an upbeat synthpop track about a night drive through a neon city.”L’agente chiama automaticamente music_generate. Non serve alcun elenco di strumenti consentiti.
Per contesti sincroni diretti senza un’esecuzione dell’agente basata su sessione, lo strumento integrato ripiega comunque sulla generazione inline e restituisce il percorso del media finale nel risultato dello strumento.
Prompt di esempio: 
Generate a cinematic piano track with soft strings and no vocals.

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

​
Provider supportati

ProviderModello predefinitoInput di riferimentoControlli supportatiAutenticazione
ComfyUIworkflowFino a 1 immagineMusica o audio definiti dal workflowCOMFY_API_KEY, COMFY_CLOUD_API_KEY
falfal-ai/minimax-music/v2.6Nessunolyrics, instrumental, durationSeconds, formatFAL_KEY o FAL_API_KEY
Googlelyria-3-clip-previewFino a 10 immaginilyrics, instrumental, formatGEMINI_API_KEY, GOOGLE_API_KEY
MiniMaxmusic-2.6Nessunolyrics, instrumental, format=mp3MINIMAX_API_KEY o OAuth MiniMax
OpenRoutergoogle/lyria-3-pro-previewFino a 1 immaginelyrics, instrumental, durationSeconds, formatOPENROUTER_API_KEY

​
Matrice delle funzionalità

Il contratto di modalità esplicito usato da music_generate, dai test di contratto e dalla sweep live condivisa:
ProvidergenerateeditLimite di modificaLane live condivise
ComfyUI✓✓1 immagineNon nella sweep condivisa; coperto da extensions/comfy/comfy.live.test.ts
fal✓—Nessunogenerate
Google✓✓10 immaginigenerate, edit
MiniMax✓—Nessunogenerate
OpenRouter✓✓1 immaginegenerate, edit
Usa action: "list" per ispezionare i provider e i modelli condivisi disponibili a runtime: 
/tool music_generate action=list
Usa action: "status" per ispezionare l’attività musicale attiva basata su sessione: 
/tool music_generate action=status
Esempio di generazione diretta: 
/tool music_generate prompt="Dreamy lo-fi hip hop with vinyl texture and gentle rain" instrumental=true

​
Parametri dello strumento

​
prompt
string
obbligatorio
Prompt per la generazione musicale. Richiesto per action: "generate".
​
action
"generate" | "status" | "list"
predefinito:"generate"
"status" restituisce l’attività corrente della sessione; "list" ispeziona i provider.
​
model
string
Override provider/modello (ad es. google/lyria-3-pro-preview, comfy/workflow).
​
lyrics
string
Testi opzionali quando il provider supporta input esplicito per i testi.
​
instrumental
boolean
Richiede output solo strumentale quando il provider lo supporta.
​
image
string
Singolo percorso o URL di immagine di riferimento.
​
images
string[]
Più immagini di riferimento (fino a 10 sui provider che le supportano).
​
durationSeconds
number
Durata target in secondi quando il provider supporta suggerimenti di durata.
​
format
"mp3" | "wav"
Suggerimento sul formato di output quando il provider lo supporta.
​
filename
string
Suggerimento sul nome del file di output.
Non tutti i provider supportano tutti i parametri. OpenClaw valida comunque i limiti rigidi, come il numero di input, prima dell’invio. Quando un provider supporta la durata ma usa un massimo inferiore al valore richiesto, OpenClaw limita al valore di durata supportato più vicino. I suggerimenti opzionali davvero non supportati vengono ignorati con un avviso quando il provider o modello selezionato non può rispettarli. I risultati dello strumento riportano le impostazioni applicate; details.normalization registra eventuali mappature da richiesto ad applicato.
I timeout delle richieste ai provider sono solo configurazione dell’operatore. OpenClaw usa agents.defaults.musicGenerationModel.timeoutMs quando configurato, aumenta i valori sotto 120000ms a 120000ms e altrimenti imposta come predefinito per le richieste ai provider 300000ms.

​
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 completata 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 controllare esplicitamente.
  • Ricerca dello stato: openclaw tasks list o openclaw tasks show <taskId> ispeziona lo stato in coda, in esecuzione e terminale.
  • Riattivazione al completamento: OpenClaw inietta un evento interno di completamento nella stessa sessione, così il modello può scrivere da sé il messaggio successivo rivolto all’utente.
  • Suggerimento nel prompt: i turni utente/manuali successivi nella stessa sessione ricevono un piccolo suggerimento di 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à

StatoSignificato
queuedAttività creata, in attesa che il provider la accetti.
runningIl provider sta elaborando (di solito da 30 secondi a 3 minuti in base a provider e durata).
succeededTraccia pronta; l’agente si riattiva e la pubblica nella conversazione.
failedErrore o timeout del provider; l’agente si riattiva con i dettagli dell’errore.
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: ["fal/fal-ai/minimax-music/v2.6", "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 provider di generazione musicale registrati rimanenti 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

Basato su workflow e dipende dal grafo configurato più la mappatura dei nodi per i campi prompt/output. Il Plugin comfy integrato si collega allo strumento condiviso music_generate tramite il registro dei provider di generazione musicale.
Usa gli endpoint dei modelli fal tramite il percorso di autenticazione condiviso del provider. Il provider integrato usa come predefinito fal-ai/minimax-music/v2.6 ed espone anche fal-ai/ace-step/prompt-to-audio e fal-ai/stable-audio-25/text-to-audio per richieste prompt-to-audio.
Usa la generazione batch di Lyria 3. Il flusso integrato corrente supporta prompt, testo opzionale per i testi e immagini di riferimento opzionali.
Usa l’endpoint batch music_generation. Supporta prompt, testi opzionali, modalità strumentale e output mp3 tramite autenticazione con chiave API minimax oppure OAuth minimax-portal.
Usa l’output audio delle chat completions di OpenRouter con streaming abilitato. Il provider integrato usa come predefinito google/lyria-3-pro-preview ed espone anche openrouter/google/lyria-3-clip-preview.

​
Scegliere il percorso giusto

  • Basato su provider condiviso quando vuoi selezione del modello, failover dei provider e il flusso asincrono integrato attività/stato.
  • Percorso Plugin (ComfyUI) quando ti serve un grafo di workflow personalizzato o un provider che non fa parte della funzionalità musicale condivisa integrata.
Se stai eseguendo il debug di un comportamento specifico di ComfyUI, consulta ComfyUI. Se stai eseguendo il debug del comportamento condiviso dei provider, inizia da fal, Google (Gemini), MiniMax o OpenRouter.

​
Modalità delle capacità dei provider

Il contratto condiviso per la generazione musicale supporta dichiarazioni esplicite delle modalità:
  • generate per la generazione basata solo su prompt.
  • edit quando la richiesta include una o più immagini di riferimento.
Le nuove implementazioni dei 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 sono sufficienti per dichiarare il supporto a edit. 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 nel bundle: 
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 usa per impostazione predefinita le variabili d’ambiente dei provider già esportate prima dei profili di autenticazione salvati, ed esegue la copertura sia di generate sia di edit dichiarata quando il provider abilita la modalità edit. Copertura attuale:
  • google: generate più edit
  • fal: solo generate
  • minimax: solo generate
  • openrouter: generate più edit
  • comfy: copertura live separata di Comfy, non lo sweep condiviso dei provider
Copertura live opt-in per il percorso musicale ComfyUI incluso nel bundle: 
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 workflow di immagini e video di comfy quando tali sezioni sono configurate.

​
Correlati