Génération de musique

L’outil music_generate permet à l’agent de créer de la musique ou de l’audio via la capacité partagée de génération musicale avec des fournisseurs configurés — Google, MiniMax, et ComfyUI configuré par workflow aujourd’hui. Pour les exécutions d’agent adossées à une session, OpenClaw lance la génération musicale comme une tâche en arrière-plan, la suit dans le registre des tâches, puis réveille à nouveau l’agent lorsque la piste est prête afin que l’agent puisse prévenir l’utilisateur et joindre l’audio terminé. Dans les discussions de groupe/canal qui utilisent une livraison visible uniquement via l’outil de message, l’agent relaie le résultat via l’outil de message. Si l’agent de complétion écrit uniquement une réponse finale privée, OpenClaw se rabat sur un envoi direct au canal avec le média généré. Le réveil de complétion avertit explicitement l’agent que les réponses finales normales sont privées dans ces routes.

L’outil partagé intégré n’apparaît que lorsqu’au moins un fournisseur de génération musicale est disponible. Si vous ne voyez pas music_generate dans les outils de votre agent, configurez agents.defaults.musicGenerationModel ou définissez une clé d’API fournisseur.

Démarrage rapide

Shared provider-backed
ComfyUI workflow

Configure auth

Définissez une clé d’API pour au moins un fournisseur — par exemple GEMINI_API_KEY ou MINIMAX_API_KEY.

Pick a default model (optional)

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

Ask the agent

« Génère une piste synthpop entraînante sur une conduite de nuit à travers une ville au néon. »L’agent appelle automatiquement music_generate. Aucune liste d’autorisation d’outils n’est nécessaire.

Pour les contextes synchrones directs sans exécution d’agent adossée à une session, l’outil intégré se rabat tout de même sur une génération en ligne et renvoie le chemin du média final dans le résultat de l’outil.

Configure the workflow

Configurez plugins.entries.comfy.config.music avec un workflow JSON et des nœuds d’invite/de sortie.

Cloud auth (optional)

Pour Comfy Cloud, définissez COMFY_API_KEY ou COMFY_CLOUD_API_KEY.

Call the tool

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

Exemples d’invites :

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

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

Fournisseurs pris en charge

Fournisseur	Modèle par défaut	Entrées de référence	Contrôles pris en charge	Authentification
ComfyUI	`workflow`	Jusqu’à 1 image	Musique ou audio défini par le workflow	`COMFY_API_KEY`, `COMFY_CLOUD_API_KEY`
Google	`lyria-3-clip-preview`	Jusqu’à 10 images	`lyrics`, `instrumental`, `format`	`GEMINI_API_KEY`, `GOOGLE_API_KEY`
MiniMax	`music-2.6`	Aucune	`lyrics`, `instrumental`, `durationSeconds`, `format=mp3`	`MINIMAX_API_KEY` ou OAuth MiniMax

Matrice de capacités

Le contrat de mode explicite utilisé par music_generate, les tests de contrat et le balayage live partagé :

Fournisseur	`generate`	`edit`	Limite de modification	Voies live partagées
ComfyUI	✓	✓	1 image	Non inclus dans le balayage partagé ; couvert par `extensions/comfy/comfy.live.test.ts`
Google	✓	✓	10 images	`generate`, `edit`
MiniMax	✓	—	Aucune	`generate`

Utilisez action: "list" pour inspecter les fournisseurs et modèles partagés disponibles à l’exécution :

/tool music_generate action=list

Utilisez action: "status" pour inspecter la tâche musicale active adossée à une session :

/tool music_generate action=status

Exemple de génération directe :

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

Paramètres de l’outil

prompt

string

requis

Invite de génération musicale. Requise pour action: "generate".

action

"generate" | "status" | "list"

défaut:"generate"

"status" renvoie la tâche de session actuelle ; "list" inspecte les fournisseurs.

model

string

Remplacement fournisseur/modèle (par ex. google/lyria-3-pro-preview, comfy/workflow).

lyrics

string

Paroles facultatives lorsque le fournisseur prend en charge une entrée de paroles explicite.

instrumental

boolean

Demande une sortie uniquement instrumentale lorsque le fournisseur la prend en charge.

image

string

Chemin ou URL d’une seule image de référence.

images

string[]

Plusieurs images de référence (jusqu’à 10 avec les fournisseurs compatibles).

durationSeconds

number

Durée cible en secondes lorsque le fournisseur prend en charge les indications de durée.

format

"mp3" | "wav"

Indication de format de sortie lorsque le fournisseur la prend en charge.

filename

string

Indication de nom de fichier de sortie.

timeoutMs

number

Délai d’expiration facultatif de la requête fournisseur, en millisecondes. S’il est omis, OpenClaw utilise agents.defaults.musicGenerationModel.timeoutMs s’il est configuré. Les valeurs inférieures à 10000ms sont relevées à 10000ms et signalées dans le résultat de l’outil.

Tous les fournisseurs ne prennent pas en charge tous les paramètres. OpenClaw valide tout de même les limites strictes, comme le nombre d’entrées, avant la soumission. Lorsqu’un fournisseur prend en charge la durée mais utilise un maximum plus court que la valeur demandée, OpenClaw contraint à la durée prise en charge la plus proche. Les indications facultatives réellement non prises en charge sont ignorées avec un avertissement lorsque le fournisseur ou le modèle sélectionné ne peut pas les respecter. Les résultats de l’outil signalent les paramètres appliqués ; details.normalization capture toute correspondance entre valeur demandée et valeur appliquée.

Comportement asynchrone

La génération musicale adossée à une session s’exécute comme tâche en arrière-plan :

Tâche en arrière-plan : music_generate crée une tâche en arrière-plan, renvoie immédiatement une réponse démarrée/tâche, et publie la piste terminée plus tard dans un message d’agent de suivi.
Prévention des doublons : tant qu’une tâche est queued ou running, les appels music_generate ultérieurs dans la même session renvoient l’état de la tâche au lieu de lancer une autre génération. Utilisez action: "status" pour vérifier explicitement.
Consultation de l’état : openclaw tasks list ou openclaw tasks show <taskId> inspecte les états en file d’attente, en cours d’exécution et terminaux.
Réveil de complétion : OpenClaw injecte un événement de complétion interne dans la même session afin que le modèle puisse écrire lui-même le suivi visible par l’utilisateur.
Indice d’invite : les tours utilisateur/manuels ultérieurs dans la même session reçoivent un petit indice d’exécution lorsqu’une tâche musicale est déjà en cours, afin que le modèle n’appelle pas aveuglément music_generate à nouveau.
Repli sans session : les contextes directs/locaux sans véritable session d’agent s’exécutent en ligne et renvoient le résultat audio final dans le même tour.

Cycle de vie de la tâche

État	Signification
`queued`	Tâche créée, en attente d’acceptation par le fournisseur.
`running`	Le fournisseur traite la requête (généralement 30 secondes à 3 minutes selon le fournisseur et la durée).
`succeeded`	Piste prête ; l’agent se réveille et la publie dans la conversation.
`failed`	Erreur fournisseur ou délai expiré ; l’agent se réveille avec les détails de l’erreur.

Vérifier l’état depuis la CLI :

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

Configuration

Sélection du modèle

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

Ordre de sélection des fournisseurs

OpenClaw essaie les fournisseurs dans cet ordre :

Paramètre model de l’appel d’outil (si l’agent en spécifie un).
musicGenerationModel.primary depuis la configuration.
musicGenerationModel.fallbacks dans l’ordre.
Détection automatique utilisant uniquement les valeurs par défaut des fournisseurs adossés à une authentification :
- fournisseur par défaut actuel en premier ;
- fournisseurs de génération musicale enregistrés restants dans l’ordre des identifiants de fournisseur.

Si un fournisseur échoue, le candidat suivant est essayé automatiquement. S’ils échouent tous, l’erreur inclut les détails de chaque tentative. Définissez agents.defaults.mediaGenerationAutoProviderFallback: false pour utiliser uniquement les entrées explicites model, primary et fallbacks.

Notes sur les fournisseurs

ComfyUI

Piloté par workflow, et dépend du graphe configuré ainsi que de la correspondance des nœuds pour les champs d’invite/de sortie. Le Plugin comfy inclus s’intègre à l’outil partagé music_generate via le registre des fournisseurs de génération musicale.

Google (Lyria 3)

Utilise la génération par lots Lyria 3. Le flux inclus actuel prend en charge l’invite, le texte de paroles facultatif et les images de référence facultatives.

MiniMax

Utilise le point de terminaison par lots music_generation. Prend en charge l’invite, les paroles facultatives, le mode instrumental, le guidage de durée et la sortie mp3 via une authentification par clé d’API minimax ou OAuth minimax-portal.

Choisir le bon chemin

Adossé à un fournisseur partagé lorsque vous voulez la sélection de modèle, le basculement entre fournisseurs et le flux intégré de tâche/état asynchrone.
Chemin Plugin (ComfyUI) lorsque vous avez besoin d’un graphe de workflow personnalisé ou d’un fournisseur qui ne fait pas partie de la capacité musicale partagée incluse.

Si vous déboguez un comportement propre à ComfyUI, consultez ComfyUI. Si vous déboguez le comportement du fournisseur partagé, commencez par Google (Gemini) ou MiniMax.

Modes de capacité des fournisseurs

Le contrat partagé de génération musicale prend en charge des déclarations de mode explicites :

generate pour la génération à partir d’une invite seule.
edit lorsque la requête inclut une ou plusieurs images de référence.

Les nouvelles implémentations de fournisseur devraient privilégier des blocs de mode explicites :

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

Les champs plats hérités tels que maxInputImages, supportsLyrics et supportsFormat ne suffisent pas à annoncer la prise en charge de la modification. Les fournisseurs devraient déclarer explicitement generate et edit afin que les tests live, les tests de contrat et l’outil partagé music_generate puissent valider la prise en charge des modes de manière déterministe.

Tests live

Couverture live optionnelle pour les fournisseurs inclus partagés :

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

Wrapper du dépôt :

pnpm test:live:media music

Ce fichier live charge les variables d’environnement de fournisseur manquantes depuis ~/.profile, privilégie par défaut les clés d’API live/env par rapport aux profils d’authentification stockés, et exécute à la fois la couverture generate et la couverture edit déclarée lorsque le fournisseur active le mode d’édition. Couverture actuelle :

google : generate plus edit
minimax : generate uniquement
comfy : couverture live Comfy distincte, pas le balayage partagé des fournisseurs

Couverture live optionnelle pour le chemin musical ComfyUI inclus :

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

Le fichier live Comfy couvre aussi les workflows d’image et de vidéo comfy lorsque ces sections sont configurées.

Voir aussi

Tâches en arrière-plan — suivi des tâches pour les exécutions music_generate détachées
ComfyUI
Référence de configuration — configuration musicGenerationModel
Google (Gemini)
MiniMax
Modèles — configuration des modèles et basculement
Vue d’ensemble des outils

Overview

Plugins

Bundled plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

Génération de musique

Démarrage rapide

Fournisseurs pris en charge

Matrice de capacités

Paramètres de l’outil

Comportement asynchrone

Cycle de vie de la tâche

Configuration

Sélection du modèle

Ordre de sélection des fournisseurs

Notes sur les fournisseurs

Choisir le bon chemin

Modes de capacité des fournisseurs

Tests live

Voir aussi

Overview

Plugins

Bundled plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

Documentation Index

​Démarrage rapide

​Fournisseurs pris en charge

​Matrice de capacités

​Paramètres de l’outil

​Comportement asynchrone

​Cycle de vie de la tâche

​Configuration

​Sélection du modèle

​Ordre de sélection des fournisseurs

​Notes sur les fournisseurs

​Choisir le bon chemin

​Modes de capacité des fournisseurs

​Tests live

​Voir aussi

Démarrage rapide

Fournisseurs pris en charge

Matrice de capacités

Paramètres de l’outil

Comportement asynchrone

Cycle de vie de la tâche

Configuration

Sélection du modèle

Ordre de sélection des fournisseurs

Notes sur les fournisseurs

Choisir le bon chemin

Modes de capacité des fournisseurs

Tests live

Voir aussi