OpenClawDocs

Search...K

Lo strumento music_generate crea musica o audio tramite la funzionalità condivisa di generazione musicale, supportata da ComfyUI, fal, Google, MiniMax e OpenRouter.

Per le esecuzioni dell'agente associate a una sessione, music_generate avvia un'attività in background, ne monitora l'avanzamento nel registro delle attività, quindi riattiva l'agente quando la traccia è pronta, in modo che possa informare l'utente e allegare l'audio completato. L'agente di completamento segue il contratto della sessione per le risposte visibili: risposta finale automatica quando configurata oppure message(action="send") quando la sessione richiede lo strumento di messaggistica. Se la sessione del richiedente è inattiva o la sua riattivazione non riesce e l'audio generato non è ancora presente nella risposta, OpenClaw invia un fallback diretto idempotente contenente solo l'audio mancante.

Avvio rapido

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

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

Esempi di prompt:

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

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

Usa action: "list" per esaminare i provider/modelli disponibili e action: "status" per esaminare l'attività musicale attiva associata alla sessione:

/tool music_generate action=list/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

Provider supportati

MiniMax registra due ID provider che condividono gli stessi modelli: minimax per l'autenticazione tramite chiave API e minimax-portal per OAuth. I riferimenti ai modelli seguono il percorso di autenticazione (minimax/music-2.6 rispetto a minimax-portal/music-2.6); consulta MiniMax.

fal espone anche fal-ai/ace-step/prompt-to-audio (wav, senza testo, senza opzione per la modalità strumentale) e fal-ai/stable-audio-25/text-to-audio (wav, solo prompt), oltre al modello predefinito basato su MiniMax. Il modello predefinito di Google lyria-3-clip-preview produce solo mp3; lyria-3-pro-preview supporta anche wav. MiniMax espone inoltre music-2.6-free, music-cover e music-cover-free. OpenRouter espone anche google/lyria-3-clip-preview.

Matrice delle funzionalità

Il contratto esplicito delle modalità usato da music_generate, dai test del contratto e dalla verifica live condivisa:

Parametri dello strumento

I timeout delle richieste ai provider sono esclusivamente una configurazione dell'operatore. OpenClaw usa agents.defaults.musicGenerationModel.timeoutMs quando è configurato, aumenta i valori inferiori a 120000ms fino a 120000ms e, in caso contrario, imposta per le richieste ai provider un valore predefinito di 300000ms.

Comportamento asincrono

La generazione musicale associata a una sessione viene eseguita come attività in background:

• Attività in background: music_generate crea un'attività in background, restituisce immediatamente una risposta di avvio/attività e pubblica successivamente la traccia completata in un messaggio di follow-up dell'agente.
• Prevenzione dei duplicati: mentre un'attività è queued o running, le successive chiamate a music_generate nella stessa sessione restituiscono lo stato dell'attività invece di avviare un'altra generazione. Usa action: "status" per eseguire un controllo esplicito. Anche una richiesta corrispondente completata di recente viene deduplicata per 2 minuti.
• Consultazione dello stato: openclaw tasks list o openclaw tasks show <taskId> esamina gli stati in coda, in esecuzione e terminali.
• Riattivazione al completamento: OpenClaw inserisce nuovamente un evento interno di completamento nella stessa sessione, affinché il modello possa scrivere autonomamente il follow-up rivolto all'utente.
• Indicazione nel prompt: i successivi turni utente/manuali nella stessa sessione ricevono una breve indicazione di runtime quando è già in corso un'attività musicale, affinché il modello non chiami nuovamente music_generate senza verificarlo.
• Fallback senza sessione: i contesti diretti/locali senza una vera sessione dell'agente vengono eseguiti in linea e restituiscono il risultato audio finale nello stesso turno.

Ciclo di vita dell'attività

L'attività musicale espone gli stessi stati del registro generale delle attività (consulta Attività in background per la macchina a stati completa, inclusi timed_out, cancelled e lost). La maggior parte delle esecuzioni musicali attraversa:

Controlla lo stato dalla CLI:

openclaw tasks listopenclaw 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 della chiamata allo strumento (se l'agente ne specifica uno).
2. musicGenerationModel.primary dalla configurazione.
3. musicGenerationModel.fallbacks nell'ordine indicato.
4. Rilevamento automatico usando esclusivamente i valori predefiniti dei provider con autenticazione configurata:
   • prima il provider predefinito corrente del modello testuale, se offre anche la generazione musicale;
   • quindi i restanti provider di generazione musicale registrati, in ordine alfabetico per ID provider.

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

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

Note sui provider

Scelta del percorso corretto

• Basato su provider condivisi quando desideri la selezione del modello, il failover dei provider e il flusso asincrono integrato per attività e stato.
• Percorso Plugin (ComfyUI) quando hai bisogno di un grafo del flusso di lavoro personalizzato o di un provider che non fa parte della funzionalità musicale condivisa inclusa.

Se stai eseguendo il debug di comportamenti specifici di ComfyUI, consulta ComfyUI. Se stai eseguendo il debug del comportamento dei provider condivisi, inizia da fal, Google (Gemini), MiniMax o OpenRouter.

Modalità delle funzionalità 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 piatti legacy come maxInputImages, supportsLyrics e supportsFormat non sono sufficienti per dichiarare il supporto alla modifica. I provider dovrebbero dichiarare esplicitamente generate ed edit, affinché i test live, i test del contratto e lo strumento condiviso music_generate possano convalidare il supporto delle modalità in modo deterministico.

Test live

Copertura live facoltativa per i provider condivisi inclusi (fal, Google, MiniMax, OpenRouter):

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

Wrapper equivalente del repository, che esegue lo stesso file di test:

pnpm test:live:media:music

Per impostazione predefinita, questo file live utilizza le variabili di ambiente dei provider già esportate prima dei profili di autenticazione memorizzati ed esegue la copertura sia di generate sia di edit quando il provider abilita la modalità di modifica. Copertura attuale:

• google: generate più edit
• fal: solo generate
• minimax: solo generate
• openrouter: generate più edit
• comfy: copertura live Comfy separata, non inclusa nella verifica condivisa dei provider

Copertura live facoltativa 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 Comfy copre anche i flussi di lavoro per immagini e video di Comfy quando le relative sezioni sono configurate.

Contenuti correlati

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

Install OpenClawSet up TelegramFix GatewayBuild a plugin

Ask Molty

Ask Molty

Molty

Responses are generated using AI and may contain mistakes.