Geração de música

# Comportamento assíncrono

A geração de música com sessão é executada como uma tarefa em segundo plano:

• Tarefa em segundo plano: music_generate cria uma tarefa em segundo plano, retorna uma resposta de início/tarefa imediatamente e publica a faixa finalizada depois em uma mensagem de acompanhamento do agente.
• Prevenção de duplicidade: enquanto uma tarefa está queued ou running, chamadas posteriores de music_generate na mesma sessão retornam o status da tarefa em vez de iniciar outra geração. Use action: "status" para verificar explicitamente.
• Consulta de status: openclaw tasks list ou openclaw tasks show <taskId> inspeciona status em fila, em execução e terminal.
• Despertar de conclusão: o OpenClaw injeta um evento interno de conclusão de volta na mesma sessão para que o modelo possa escrever ele mesmo o acompanhamento voltado ao usuário.
• Dica de prompt: turnos posteriores de usuário/manual na mesma sessão recebem uma pequena dica de runtime quando uma tarefa de música já está em andamento, para que o modelo não chame music_generate novamente sem critério.
• Fallback sem sessão: contextos diretos/locais sem uma sessão real de agente executam inline e retornam o resultado final de áudio no mesmo turno.

# Ciclo de vida da tarefa

Verifique o status pela CLI:

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

# Configuração

# Seleção de modelo

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

# Ordem de seleção de provedor

O OpenClaw tenta provedores nesta ordem:

1. Parâmetro model da chamada de ferramenta (se o agente especificar um).
2. musicGenerationModel.primary da configuração.
3. musicGenerationModel.fallbacks em ordem.
4. Detecção automática usando apenas padrões de provedor baseados em autenticação:
   • provedor padrão atual primeiro;
   • demais provedores de geração de música registrados em ordem de ID de provedor.

Se um provedor falhar, o próximo candidato é tentado automaticamente. Se todos falharem, o erro inclui detalhes de cada tentativa.

Defina agents.defaults.mediaGenerationAutoProviderFallback: false para usar apenas entradas explícitas de model, primary e fallbacks.

# Observações sobre provedores

# Escolhendo o caminho certo

• Com provedor compartilhado quando você quer seleção de modelo, failover de provedor e o fluxo assíncrono integrado de tarefa/status.
• Caminho de Plugin (ComfyUI) quando você precisa de um grafo de workflow personalizado ou de um provedor que não faz parte da capacidade compartilhada integrada de música.

Se você estiver depurando comportamento específico do ComfyUI, consulte ComfyUI. Se você estiver depurando comportamento de provedor compartilhado, comece com Google (Gemini) ou MiniMax.

# Modos de capacidade do provedor

O contrato compartilhado de geração de música oferece suporte a declarações explícitas de modo:

• generate para geração somente por prompt.
• edit quando a solicitação inclui uma ou mais imagens de referência.

Novas implementações de provedor devem preferir blocos de modo explícitos:

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

Campos legados planos, como maxInputImages, supportsLyrics e supportsFormat, não são suficientes para anunciar suporte a edição. Provedores devem declarar generate e edit explicitamente para que testes live, testes de contrato e a ferramenta compartilhada music_generate possam validar o suporte a modo de forma determinística.

# Testes live

Cobertura live opt-in para os provedores compartilhados incluídos:

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

Wrapper do repositório:

pnpm test:live:media music

Este arquivo live carrega variáveis de ambiente ausentes do provedor a partir de ~/.profile, prefere chaves de API live/env em vez de perfis de autenticação armazenados por padrão e executa cobertura tanto de generate quanto de edit declarado quando o provedor habilita o modo de edição. Cobertura hoje:

• google: generate mais edit
• minimax: apenas generate
• comfy: cobertura ao vivo separada do Comfy, não a varredura compartilhada de provedores

Cobertura ao vivo opcional para o caminho de música ComfyUI incluído:

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

O arquivo ao vivo do Comfy também cobre fluxos de trabalho de imagem e vídeo do comfy quando essas seções estão configuradas.

# Relacionados

• Tarefas em segundo plano — rastreamento de tarefas para execuções music_generate desvinculadas
• ComfyUI
• Referência de configuração — configuração musicGenerationModel
• Google (Gemini)
• MiniMax
• Modelos — configuração de modelos e failover
• Visão geral de ferramentas