Generación de música

# Comportamiento asíncrono

La generación musical respaldada por sesión se ejecuta como una tarea en segundo plano:

• Tarea en segundo plano: music_generate crea una tarea en segundo plano, devuelve una respuesta de inicio/tarea inmediatamente y publica la pista terminada más tarde en un mensaje de seguimiento del agente.
• Prevención de duplicados: mientras una tarea está queued o running, las llamadas posteriores a music_generate en la misma sesión devuelven el estado de la tarea en lugar de iniciar otra generación. Usa action: "status" para comprobarlo explícitamente.
• Consulta de estado: openclaw tasks list u openclaw tasks show <taskId> inspecciona los estados en cola, en ejecución y terminales.
• Despertar de finalización: OpenClaw inyecta un evento interno de finalización de vuelta en la misma sesión para que el modelo pueda escribir por sí mismo el seguimiento visible para el usuario.
• Indicación de prompt: los turnos posteriores de usuario/manual en la misma sesión reciben una pequeña indicación de tiempo de ejecución cuando ya hay una tarea musical en curso, para que el modelo no vuelva a llamar a music_generate a ciegas.
• Alternativa sin sesión: los contextos directos/locales sin una sesión real de agente se ejecutan en línea y devuelven el resultado de audio final en el mismo turno.

# Ciclo de vida de la tarea

Comprueba el estado desde la CLI:

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

# Configuración

# Selección de modelo

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

# Orden de selección de proveedor

OpenClaw prueba los proveedores en este orden:

1. Parámetro model de la llamada a la herramienta (si el agente especifica uno).
2. musicGenerationModel.primary de la configuración.
3. musicGenerationModel.fallbacks en orden.
4. Detección automática usando solo valores predeterminados de proveedores respaldados por autenticación:
   • primero el proveedor predeterminado actual;
   • los demás proveedores de generación musical registrados en orden de id de proveedor.

Si un proveedor falla, se prueba automáticamente el siguiente candidato. Si todos fallan, el error incluye detalles de cada intento.

Define agents.defaults.mediaGenerationAutoProviderFallback: false para usar solo entradas explícitas de model, primary y fallbacks.

# Notas de proveedores

# Elegir la ruta adecuada

• Respaldado por proveedor compartido cuando quieres selección de modelo, conmutación por error de proveedor y el flujo integrado asíncrono de tarea/estado.
• Ruta de Plugin (ComfyUI) cuando necesitas un grafo de flujo de trabajo personalizado o un proveedor que no forma parte de la capacidad musical compartida incluida.

Si estás depurando comportamiento específico de ComfyUI, consulta ComfyUI. Si estás depurando comportamiento de proveedor compartido, empieza por Google (Gemini) o MiniMax.

# Modos de capacidad de proveedor

El contrato compartido de generación musical admite declaraciones de modo explícitas:

• generate para generación solo con prompt.
• edit cuando la solicitud incluye una o más imágenes de referencia.

Las nuevas implementaciones de proveedores deberían preferir bloques de modo explícitos:

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

Los campos planos heredados como maxInputImages, supportsLyrics y supportsFormat no bastan para anunciar compatibilidad con edición. Los proveedores deberían declarar generate y edit explícitamente para que las pruebas en vivo, las pruebas de contrato y la herramienta compartida music_generate puedan validar la compatibilidad de modo de forma determinista.

# Pruebas en vivo

Cobertura en vivo opcional para los proveedores compartidos incluidos:

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

Wrapper del repositorio:

pnpm test:live:media music

Este archivo en vivo carga variables de entorno de proveedor faltantes desde ~/.profile, prefiere claves de API en vivo/del entorno antes que perfiles de autenticación almacenados de forma predeterminada, y ejecuta tanto cobertura de generate como de edit declarada cuando el proveedor habilita el modo de edición. Cobertura actual:

• google: generate más edit
• minimax: solo generate
• comfy: cobertura en vivo de Comfy separada, no el barrido compartido de proveedores

Cobertura en vivo opcional para la ruta de música de ComfyUI incluida:

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

El archivo de pruebas en vivo de Comfy también cubre los flujos de trabajo de imagen y video de comfy cuando esas secciones están configuradas.

# Relacionado

• Tareas en segundo plano — seguimiento de tareas para ejecuciones desacopladas de music_generate
• ComfyUI
• Referencia de configuración — configuración de musicGenerationModel
• Google (Gemini)
• MiniMax
• Modelos — configuración de modelos y conmutación por error
• Resumen de herramientas