Geração de música

A ferramenta music_generate permite que o agente crie música ou áudio por meio da capacidade compartilhada de geração de música com provedores configurados — ComfyUI, fal, Google, MiniMax e OpenRouter atualmente. Para execuções de agente com sessão, o OpenClaw inicia a geração de música como uma tarefa em segundo plano, a rastreia no livro-razão 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. O agente de conclusão segue o modo normal de resposta visível da sessão: entrega automática da resposta final quando configurada, ou message(action="send") quando a sessão exige a ferramenta de mensagem. Se a sessão solicitante estiver inativa ou sua ativação falhar, e ainda faltar algum áudio gerado na resposta de conclusão, o OpenClaw envia um fallback direto idempotente com apenas o áudio ausente.

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

Shared provider-backed
ComfyUI workflow

Configure auth

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

Pick a default model (optional)

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

Ask the agent

“Generate an upbeat synthpop track about a night drive through a neon city.”O agente chama music_generate automaticamente. Não é necessário colocar a ferramenta em uma lista de permissões.

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

Configure the workflow

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

Cloud auth (optional)

Para Comfy Cloud, defina COMFY_API_KEY ou COMFY_CLOUD_API_KEY.

Call the tool

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

Prompts de exemplo:

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 definido pelo workflow	`COMFY_API_KEY`, `COMFY_CLOUD_API_KEY`
fal	`fal-ai/minimax-music/v2.6`	Nenhuma	`lyrics`, `instrumental`, `durationSeconds`, `format`	`FAL_KEY` ou `FAL_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`, `format=mp3`	`MINIMAX_API_KEY` ou OAuth da MiniMax
OpenRouter	`google/lyria-3-pro-preview`	Até 1 imagem	`lyrics`, `instrumental`, `durationSeconds`, `format`	`OPENROUTER_API_KEY`

Matriz de capacidades

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	Raias live compartilhadas
ComfyUI	✓	✓	1 imagem	Não está na varredura compartilhada; coberto por `extensions/comfy/comfy.live.test.ts`
fal	✓	—	Nenhum	`generate`
Google	✓	✓	10 imagens	`generate`, `edit`
MiniMax	✓	—	Nenhum	`generate`
OpenRouter	✓	✓	1 imagem	`generate`, `edit`

Use action: "list" para inspecionar provedores e modelos compartilhados disponíveis em tempo de execução:

/tool music_generate action=list

Use action: "status" para inspecionar a tarefa de música ativa 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

Substituição 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 de arquivo de saída.

Nem todos os provedores oferecem suporte a todos os parâmetros. O OpenClaw ainda valida limites rígidos, 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 incompatíveis são ignoradas com um aviso quando o provedor ou modelo selecionado não consegue honrá-las. Os resultados da ferramenta informam as configurações aplicadas; details.normalization captura qualquer mapeamento de solicitado para aplicado.

Tempos limite de solicitação de provedor são apenas configuração do operador. O OpenClaw usa agents.defaults.musicGenerationModel.timeoutMs quando configurado, eleva valores abaixo de 120000ms para 120000ms e, caso contrário, usa como padrão 300000ms para solicitações de provedor.

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 iniciada/de tarefa imediatamente e publica a faixa finalizada depois em uma mensagem de acompanhamento do agente.
Prevenção de duplicatas: enquanto uma tarefa estiver 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.
Ativação 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 tempo limite 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: ["fal/fal-ai/minimax-music/v2.6", "minimax/music-2.6"],
      },
    },
  },
}

Ordem de seleção de provedor

O OpenClaw tenta provedores nesta ordem:

Parâmetro model da chamada da ferramenta (se o agente especificar um).
musicGenerationModel.primary da configuração.
musicGenerationModel.fallbacks em ordem.
Detecção automática usando apenas padrões de provedor com autenticação:
- provedor padrão atual primeiro;
- provedores restantes 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

ComfyUI

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

fal

Usa endpoints de modelo da fal pelo caminho compartilhado de autenticação de provedor. O provedor integrado usa como padrão fal-ai/minimax-music/v2.6 e também expõe fal-ai/ace-step/prompt-to-audio e fal-ai/stable-audio-25/text-to-audio para solicitações de prompt para áudio.

Google (Lyria 3)

Usa geração em lote do Lyria 3. O fluxo integrado 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, letra opcional, modo instrumental e saída mp3 por meio de autenticação com chave de API minimax ou OAuth minimax-portal.

OpenRouter

Usa saída de áudio de conclusões de chat do OpenRouter com streaming habilitado. O provedor integrado usa como padrão google/lyria-3-pro-preview e também expõe openrouter/google/lyria-3-clip-preview.

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 um comportamento específico do ComfyUI, consulte ComfyUI. Se você estiver depurando um comportamento compartilhado de provedor, comece com fal, Google (Gemini), MiniMax ou OpenRouter.

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 provedores 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 planos 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 de forma determinística.

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 repo:

pnpm test:live:media music

Esse arquivo live usa, por padrão, as variáveis de ambiente de provedor já exportadas antes dos perfis de autenticação armazenados, e executa a cobertura de generate e de edit declarado quando o provedor habilita o modo de edição. Cobertura atual:

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

Cobertura live 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 live 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 destacadas de music_generate
ComfyUI
Referência de configuração — configuração musicGenerationModel
Google (Gemini)
MiniMax
Modelos — configuração de modelo e failover
Visão geral das ferramentas

​Início rápido

​Provedores compatíveis

​Matriz de capacidades

​Parâmetros da ferramenta

​Comportamento assíncrono

​Ciclo de vida da tarefa

​Configuração

​Seleção de modelo

​Ordem de seleção de provedor

​Observações sobre provedores

​Escolhendo o caminho certo

​Modos de capacidade do provedor

​Testes live

​Relacionados

Início rápido

Provedores compatíveis

Matriz de capacidades

Parâmetros da ferramenta

Comportamento assíncrono

Ciclo de vida da tarefa

Configuração

Seleção de modelo

Ordem de seleção de provedor

Observações sobre provedores

Escolhendo o caminho certo

Modos de capacidade do provedor

Testes live

Relacionados