Geração de música

A ferramenta music_generate permite que o agente crie música ou áudio por meio do recurso compartilhado de geração de música com provedores configurados: Google, MiniMax e ComfyUI configurado por workflow atualmente. Para execuções de agente com sessão, o OpenClaw inicia a geração de música como uma tarefa em segundo plano, acompanha-a no ledger de tarefas e então desperta o agente novamente quando a faixa está pronta para que o agente possa avisar o usuário e anexar o áudio finalizado. Em chats de grupo/canal que usam entrega visível somente por ferramenta de mensagem, o agente retransmite o resultado pela ferramenta de mensagem. Se o agente de conclusão escrever apenas uma resposta final privada, o OpenClaw recorre a um envio direto pelo canal com a mídia gerada. O despertar de conclusão avisa explicitamente o agente de que respostas finais normais são privadas nessas rotas.

A ferramenta compartilhada integrada só aparece quando pelo menos um provedor de geração de música está disponível. Se você não vir music_generate nas ferramentas do seu agente, configure agents.defaults.musicGenerationModel ou configure uma chave de API de provedor.

Início rápido

Com provedor compartilhado
Workflow do ComfyUI

Configurar autenticação

Defina uma chave de API para pelo menos um provedor — por exemplo GEMINI_API_KEY ou MINIMAX_API_KEY.

Escolher um modelo padrão (opcional)

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

Pedir ao agente

“Gere uma faixa synthpop animada sobre dirigir à noite por uma cidade de neon.”O agente chama music_generate automaticamente. Não é necessário permitir a ferramenta em uma lista.

Para contextos síncronos diretos sem uma execução de agente com sessão, a ferramenta integrada ainda recorre à geração inline e retorna o caminho final da mídia no resultado da ferramenta.

Configurar o workflow

Configure plugins.entries.comfy.config.music com um workflow JSON e nós de prompt/saída.

Autenticação em nuvem (opcional)

Para o Comfy Cloud, defina COMFY_API_KEY ou COMFY_CLOUD_API_KEY.

Chamar a ferramenta

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

Exemplos de prompts:

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

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

Provedores compatíveis

Provedor	Modelo padrão	Entradas de referência	Controles compatíveis	Autenticação
ComfyUI	`workflow`	Até 1 imagem	Música ou áudio definidos pelo workflow	`COMFY_API_KEY`, `COMFY_CLOUD_API_KEY`
Google	`lyria-3-clip-preview`	Até 10 imagens	`lyrics`, `instrumental`, `format`	`GEMINI_API_KEY`, `GOOGLE_API_KEY`
MiniMax	`music-2.6`	Nenhuma	`lyrics`, `instrumental`, `durationSeconds`, `format=mp3`	`MINIMAX_API_KEY` ou OAuth da MiniMax

Matriz de recursos

O contrato de modo explícito usado por music_generate, testes de contrato e a varredura live compartilhada:

Provedor	`generate`	`edit`	Limite de edição	Lanes live compartilhadas
ComfyUI	✓	✓	1 imagem	Não incluído na varredura compartilhada; coberto por `extensions/comfy/comfy.live.test.ts`
Google	✓	✓	10 imagens	`generate`, `edit`
MiniMax	✓	—	Nenhum	`generate`

Use action: "list" para inspecionar provedores e modelos compartilhados disponíveis em runtime:

/tool music_generate action=list

Use action: "status" para inspecionar a tarefa ativa de música com sessão:

/tool music_generate action=status

Exemplo de geração direta:

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

Parâmetros da ferramenta

prompt

string

obrigatório

Prompt de geração de música. Obrigatório para action: "generate".

action

"generate" | "status" | "list"

padrão:"generate"

"status" retorna a tarefa atual da sessão; "list" inspeciona provedores.

model

string

Sobrescrita de provedor/modelo (por exemplo, google/lyria-3-pro-preview, comfy/workflow).

lyrics

string

Letra opcional quando o provedor oferece suporte a entrada explícita de letra.

instrumental

boolean

Solicita saída apenas instrumental quando o provedor oferece suporte.

image

string

Caminho ou URL de uma única imagem de referência.

images

string[]

Várias imagens de referência (até 10 em provedores compatíveis).

durationSeconds

number

Duração alvo em segundos quando o provedor oferece suporte a dicas de duração.

format

"mp3" | "wav"

Dica de formato de saída quando o provedor oferece suporte.

filename

string

Dica de nome do arquivo de saída.

timeoutMs

number

Timeout opcional da solicitação ao provedor em milissegundos. Quando omitido, o OpenClaw usa agents.defaults.musicGenerationModel.timeoutMs se configurado. Valores abaixo de 10000ms são elevados para 10000ms e informados no resultado da ferramenta.

Nem todos os provedores oferecem suporte a todos os parâmetros. O OpenClaw ainda valida limites estritos, como contagens de entrada, antes do envio. Quando um provedor oferece suporte a duração, mas usa um máximo menor que o valor solicitado, o OpenClaw limita ao valor de duração compatível mais próximo. Dicas opcionais realmente sem suporte são ignoradas com um aviso quando o provedor ou modelo selecionado não consegue atendê-las. Os resultados da ferramenta informam as configurações aplicadas; details.normalization captura qualquer mapeamento de solicitado para aplicado.

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 iniciada/tarefa imediatamente e publica a faixa finalizada posteriormente em uma mensagem de acompanhamento do agente.
Prevenção de duplicatas: enquanto uma tarefa está queued ou running, chamadas music_generate posteriores 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 o acompanhamento voltado ao usuário por conta própria.
Dica de prompt: turnos posteriores de usuário/manuais 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 às cegas.
Fallback sem sessão: contextos diretos/locais sem uma sessão real de agente são executados inline e retornam o resultado final de áudio no mesmo turno.

Ciclo de vida da tarefa

Estado	Significado
`queued`	Tarefa criada, aguardando o provedor aceitá-la.
`running`	O provedor está processando (normalmente de 30 segundos a 3 minutos, dependendo do provedor e da duração).
`succeeded`	Faixa pronta; o agente desperta e a publica na conversa.
`failed`	Erro ou timeout do provedor; o agente desperta com detalhes do erro.

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 provedores

O OpenClaw tenta os provedores nesta ordem:

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

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 de provedores

ComfyUI

Orientado por workflow e depende do grafo configurado mais o mapeamento de nós para campos de prompt/saída. O Plugin comfy incluído se conecta à ferramenta compartilhada music_generate por meio do registro de provedores de geração de música.

Google (Lyria 3)

Usa geração em lote do Lyria 3. O fluxo incluído atual oferece suporte a prompt, texto de letra opcional e imagens de referência opcionais.

MiniMax

Usa o endpoint em lote music_generation. Oferece suporte a prompt, letras opcionais, modo instrumental, direcionamento de duração e saída mp3 por meio de autenticação por chave de API minimax ou OAuth minimax-portal.

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 do recurso compartilhado incluído de música.

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

Modos de recurso do provedor

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

generate para geração apenas 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 flat legados 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 modos deterministicamente.

Testes live

Cobertura live opcional 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 de provedor ausentes de ~/.profile, prefere chaves de API live/env a perfis de autenticação armazenados por padrão e executa tanto a cobertura de generate quanto a de edit declarada quando o provedor habilita o modo de edição. Cobertura hoje:

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

Ative a cobertura live 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 live do Comfy também cobre fluxos de trabalho de imagem e vídeo do comfy quando essas seções estão configuradas.

Relacionado

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

Overview

Plugins

Bundled plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

Geração de música

Início rápido

Provedores compatíveis

Matriz de recursos

Parâmetros da ferramenta

Comportamento assíncrono

Ciclo de vida da tarefa

Configuração

Seleção de modelo

Ordem de seleção de provedores

Observações de provedores

Escolhendo o caminho certo

Modos de recurso do provedor

Testes live

Relacionado

Overview

Plugins

Bundled plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

Documentation Index

​Início rápido

​Provedores compatíveis

​Matriz de recursos

​Parâmetros da ferramenta

​Comportamento assíncrono

​Ciclo de vida da tarefa

​Configuração

​Seleção de modelo

​Ordem de seleção de provedores

​Observações de provedores

​Escolhendo o caminho certo

​Modos de recurso do provedor

​Testes live

​Relacionado

Início rápido

Provedores compatíveis

Matriz de recursos

Parâmetros da ferramenta

Comportamento assíncrono

Ciclo de vida da tarefa

Configuração

Seleção de modelo

Ordem de seleção de provedores

Observações de provedores

Escolhendo o caminho certo

Modos de recurso do provedor

Testes live

Relacionado