chore(i18n): refresh pt-BR translations

This commit is contained in:
openclaw-docs-i18n[bot] 2026-05-05 06:17:18 +00:00
parent c459529095
commit 35a3b5f4c2
5 changed files with 485 additions and 474 deletions

View File

@ -1,24 +1,24 @@
---
read_when:
- Você quer tarefas agendadas e ativações
- Você está depurando a execução do Cron e os logs
summary: Referência da CLI para `openclaw cron` (agendar e executar trabalhos em segundo plano)
- Você está depurando a execução do Cron e os registros
summary: Referência da CLI para `openclaw cron` (agendar e executar tarefas em segundo plano)
title: Cron
x-i18n:
generated_at: "2026-05-02T05:43:01Z"
generated_at: "2026-05-05T06:15:57Z"
model: gpt-5.5
provider: openai
source_hash: 298ac3fc868462eb301febbc1aa5296d8087cad7fdc466870487081444c5856f
source_hash: 804efac75b8653b03cec197247be847498e084b50b00fb7bd3fbd94067ef25d4
source_path: cli/cron.md
workflow: 16
---
# `openclaw cron`
Gerencie tarefas cron para o agendador do Gateway.
Gerencie jobs de Cron para o agendador do Gateway.
<Tip>
Execute `openclaw cron --help` para ver toda a superfície de comandos. Consulte [Tarefas cron](/pt-BR/automation/cron-jobs) para o guia conceitual.
Execute `openclaw cron --help` para ver toda a superfície de comandos. Consulte [Jobs de Cron](/pt-BR/automation/cron-jobs) para o guia conceitual.
</Tip>
## Sessões
@ -28,142 +28,140 @@ Execute `openclaw cron --help` para ver toda a superfície de comandos. Consulte
<AccordionGroup>
<Accordion title="Chaves de sessão">
- `main` vincula à sessão principal do agente.
- `isolated` cria uma transcrição e um id de sessão novos para cada execução.
- `isolated` cria uma transcrição e um ID de sessão novos para cada execução.
- `current` vincula à sessão ativa no momento da criação.
- `session:<id>` fixa uma chave de sessão persistente explícita.
</Accordion>
<Accordion title="Semântica de sessão isolada">
Execuções isoladas redefinem o contexto de conversa ambiente. Roteamento de canal e grupo, política de envio/fila, elevação, origem e vinculação de runtime ACP são redefinidos para a nova execução. Preferências seguras e substituições explícitas de modelo ou autenticação selecionadas pelo usuário podem ser mantidas entre execuções.
Execuções isoladas redefinem o contexto de conversa ambiente. Roteamento de canal e grupo, política de envio/fila, elevação, origem e vinculação de runtime ACP são redefinidos para a nova execução. Preferências seguras e substituições explícitas de modelo ou autenticação selecionadas pelo usuário podem ser preservadas entre execuções.
</Accordion>
</AccordionGroup>
## Entrega
`openclaw cron list` e `openclaw cron show <job-id>` mostram uma prévia da rota de entrega resolvida. Para `channel: "last"`, a prévia mostra se a rota foi resolvida a partir da sessão principal ou atual, ou se falhará em modo fechado.
`openclaw cron list` e `openclaw cron show <job-id>` mostram uma prévia da rota de entrega resolvida. Para `channel: "last"`, a prévia mostra se a rota foi resolvida a partir da sessão principal ou atual, ou se falhará fechada.
Destinos prefixados por provedor podem desambiguar canais de anúncio não resolvidos. Por exemplo, `to: "telegram:123"` seleciona Telegram quando `delivery.channel` é omitido ou `last`. Somente prefixos anunciados pelo plugin carregado são seletores de provedor. Se `delivery.channel` for explícito, o prefixo deve corresponder a esse canal; `channel: "whatsapp"` com `to: "telegram:123"` é rejeitado. Prefixos de serviço como `imessage:` e `sms:` continuam sendo sintaxe de destino pertencente ao canal.
Destinos com prefixo de provedor podem desambiguar canais de anúncio não resolvidos. Por exemplo, `to: "telegram:123"` seleciona Telegram quando `delivery.channel` é omitido ou é `last`. Somente prefixos anunciados pelo plugin carregado são seletores de provedor. Se `delivery.channel` for explícito, o prefixo deve corresponder a esse canal; `channel: "whatsapp"` com `to: "telegram:123"` é rejeitado. Prefixos de serviço como `imessage:` e `sms:` permanecem como sintaxe de destino pertencente ao canal.
<Note>
Tarefas `cron add` isoladas usam entrega `--announce` por padrão. Use `--no-deliver` para manter a saída interna. `--deliver` permanece como um alias obsoleto para `--announce`.
Jobs isolados de `cron add` usam entrega `--announce` por padrão. Use `--no-deliver` para manter a saída interna. `--deliver` permanece como um alias obsoleto de `--announce`.
</Note>
### Propriedade da entrega
A entrega de chat de cron isolado é compartilhada entre o agente e o executor:
A entrega de chat de Cron isolado é compartilhada entre o agente e o executor:
- O agente pode enviar diretamente usando a ferramenta `message` quando uma rota de chat está disponível.
- `announce` faz a entrega final de fallback apenas quando o agente não enviou diretamente para o destino resolvido.
- `announce` entrega o fallback da resposta final somente quando o agente não enviou diretamente ao destino resolvido.
- `webhook` publica o payload concluído em uma URL.
- `none` desabilita a entrega de fallback do executor.
- `none` desativa a entrega de fallback do executor.
`--announce` é a entrega de fallback do executor para a resposta final. `--no-deliver` desabilita esse fallback, mas não remove a ferramenta `message` do agente quando uma rota de chat está disponível.
`--announce` é a entrega de fallback do executor para a resposta final. `--no-deliver` desativa esse fallback, mas não remove a ferramenta `message` do agente quando uma rota de chat está disponível.
Lembretes criados a partir de um chat ativo preservam o destino de entrega do chat ao vivo para entrega de anúncio de fallback. Chaves de sessão internas podem estar em minúsculas; não as use como fonte de verdade para IDs de provedor sensíveis a maiúsculas e minúsculas, como IDs de sala do Matrix.
Lembretes criados a partir de um chat ativo preservam o destino de entrega do chat ao vivo para entrega de anúncio de fallback. Chaves de sessão internas podem estar em minúsculas; não as use como fonte da verdade para IDs de provedor sensíveis a maiúsculas e minúsculas, como IDs de salas do Matrix.
### Entrega de falhas
### Entrega de falha
Notificações de falha são resolvidas nesta ordem:
1. `delivery.failureDestination` na tarefa.
1. `delivery.failureDestination` no job.
2. `cron.failureDestination` global.
3. O destino principal de anúncio da tarefa (quando nenhum destino de falha explícito está definido).
3. O destino de anúncio primário do job (quando nenhum destino de falha explícito está definido).
<Note>
Tarefas de sessão principal só podem usar `delivery.failureDestination` quando o modo de entrega principal é `webhook`. Tarefas isoladas o aceitam em todos os modos.
Jobs de sessão principal só podem usar `delivery.failureDestination` quando o modo de entrega primário é `webhook`. Jobs isolados o aceitam em todos os modos.
</Note>
Observação: execuções de cron isolado tratam falhas de agente no nível da execução como erros de tarefa mesmo quando
nenhum payload de resposta é produzido, portanto falhas de modelo/provedor ainda incrementam contadores
de erro e acionam notificações de falha.
Observação: execuções isoladas de Cron tratam falhas de agente no nível da execução como erros de job mesmo quando nenhum payload de resposta é produzido, então falhas de modelo/provedor ainda incrementam contadores de erro e acionam notificações de falha.
## Agendamento
### Tarefas de execução única
### Jobs únicos
`--at <datetime>` agenda uma execução única. Datas e horas sem deslocamento são tratadas como UTC, a menos que você também passe `--tz <iana>`, que interpreta o horário de relógio na timezone informada.
`--at <datetime>` agenda uma execução única. Datas e horas sem offset são tratadas como UTC, a menos que você também passe `--tz <iana>`, que interpreta o horário de relógio na timezone fornecida.
<Note>
Tarefas de execução única são excluídas após sucesso por padrão. Use `--keep-after-run` para preservá-las.
Jobs únicos são excluídos após o sucesso por padrão. Use `--keep-after-run` para preservá-los.
</Note>
### Tarefas recorrentes
### Jobs recorrentes
Tarefas recorrentes usam backoff exponencial de nova tentativa após erros consecutivos: 30s, 1m, 5m, 15m, 60m. A agenda volta ao normal após a próxima execução bem-sucedida.
Jobs recorrentes usam backoff exponencial de nova tentativa após erros consecutivos: 30s, 1m, 5m, 15m, 60m. O agendamento volta ao normal após a próxima execução bem-sucedida.
Execuções ignoradas são rastreadas separadamente de erros de execução. Elas não afetam o backoff de nova tentativa, mas `openclaw cron edit <job-id> --failure-alert-include-skipped` pode fazer alertas de falha incluírem notificações repetidas de execução ignorada.
Execuções ignoradas são rastreadas separadamente dos erros de execução. Elas não afetam o backoff de nova tentativa, mas `openclaw cron edit <job-id> --failure-alert-include-skipped` pode incluir notificações repetidas de execuções ignoradas nos alertas de falha.
Para tarefas isoladas que têm como destino um provedor de modelo configurado localmente, o cron executa um preflight leve do provedor antes de iniciar o turno do agente. Provedores `api: "ollama"` em loopback, rede privada e `.local` são sondados em `/api/tags`; provedores locais compatíveis com OpenAI, como vLLM, SGLang e LM Studio, são sondados em `/models`. Se o endpoint estiver inacessível, a execução é registrada como `skipped` e tentada novamente em uma agenda posterior; endpoints inativos correspondentes são armazenados em cache por 5 minutos para evitar que muitas tarefas sobrecarreguem o mesmo servidor local.
Para jobs isolados que têm como destino um provedor de modelo local configurado, o Cron executa uma pré-verificação leve do provedor antes de iniciar o turno do agente. Provedores `api: "ollama"` em loopback, rede privada e `.local` são verificados em `/api/tags`; provedores locais compatíveis com OpenAI, como vLLM, SGLang e LM Studio, são verificados em `/models`. Se o endpoint estiver inacessível, a execução é registrada como `skipped` e tentada novamente em um agendamento posterior; endpoints inativos correspondentes são armazenados em cache por 5 minutos para evitar que muitos jobs sobrecarreguem o mesmo servidor local.
Observação: definições de tarefas cron ficam em `jobs.json`, enquanto o estado de runtime pendente fica em `jobs-state.json`. Se `jobs.json` for editado externamente, o Gateway recarrega agendas alteradas e limpa slots pendentes obsoletos; regravações apenas de formatação não limpam o slot pendente.
Observação: definições de jobs de Cron ficam em `jobs.json`, enquanto o estado de runtime pendente fica em `jobs-state.json`. Se `jobs.json` for editado externamente, o Gateway recarrega agendamentos alterados e limpa slots pendentes obsoletos; regravações apenas de formatação não limpam o slot pendente.
### Execuções manuais
`openclaw cron run` retorna assim que a execução manual é enfileirada. Respostas bem-sucedidas incluem `{ ok: true, enqueued: true, runId }`. Use `openclaw cron runs --id <job-id>` para acompanhar o resultado eventual.
<Note>
`openclaw cron run <job-id>` força a execução por padrão. Use `--due` para manter o comportamento antigo de "executar somente se estiver vencida".
`openclaw cron run <job-id>` força a execução por padrão. Use `--due` para manter o comportamento antigo de "executar somente se estiver vencido".
</Note>
## Modelos
`cron add|edit --model <ref>` seleciona um modelo permitido para a tarefa.
`cron add|edit --model <ref>` seleciona um modelo permitido para o job.
<Warning>
Se o modelo não for permitido ou não puder ser resolvido, o cron falha a execução com um erro de validação explícito, em vez de recorrer ao agente da tarefa ou à seleção de modelo padrão.
Se o modelo não for permitido ou não puder ser resolvido, o Cron falha a execução com um erro de validação explícito em vez de recorrer ao agente do job ou à seleção de modelo padrão.
</Warning>
Cron `--model` é um **primário da tarefa**, não uma substituição de `/model` de sessão de chat. Isso significa:
`--model` do Cron é um **primário do job**, não uma substituição `/model` de sessão de chat. Isso significa:
- Fallbacks de modelo configurados ainda se aplicam quando o modelo da tarefa selecionado falha.
- `fallbacks` no payload por tarefa substitui a lista de fallbacks configurada quando presente.
- Uma lista de fallbacks por tarefa vazia (`fallbacks: []` no payload/API da tarefa) torna a execução cron estrita.
- Quando uma tarefa tem `--model`, mas nenhuma lista de fallbacks está configurada, o OpenClaw passa uma substituição de fallback vazia explícita para que o primário do agente não seja anexado como destino oculto de nova tentativa.
- Fallbacks de modelo configurados ainda se aplicam quando o modelo selecionado do job falha.
- `fallbacks` no payload por job substitui a lista de fallback configurada quando presente.
- Uma lista de fallback vazia por job (`fallbacks: []` no payload/API do job) torna a execução do Cron estrita.
- Quando um job tem `--model`, mas nenhuma lista de fallback está configurada, o OpenClaw passa uma substituição explícita de fallback vazia para que o primário do agente não seja anexado como um destino oculto de nova tentativa.
### Precedência de modelo de cron isolado
### Precedência de modelo do Cron isolado
O cron isolado resolve o modelo ativo nesta ordem:
O Cron isolado resolve o modelo ativo nesta ordem:
1. Substituição de hook do Gmail.
2. `--model` por tarefa.
3. Substituição de modelo de sessão cron armazenada (quando o usuário selecionou uma).
1. Substituição do hook do Gmail.
2. `--model` por job.
3. Substituição de modelo armazenada da sessão de Cron (quando o usuário selecionou uma).
4. Seleção de modelo do agente ou padrão.
### Modo rápido
O modo rápido de cron isolado segue a seleção de modelo ao vivo resolvida. A configuração de modelo `params.fastMode` se aplica por padrão, mas uma substituição `fastMode` de sessão armazenada ainda prevalece sobre a configuração.
O modo rápido do Cron isolado segue a seleção de modelo ao vivo resolvida. A configuração de modelo `params.fastMode` se aplica por padrão, mas uma substituição `fastMode` de sessão armazenada ainda tem precedência sobre a configuração.
### Novas tentativas de troca de modelo ao vivo
Se uma execução isolada lançar `LiveSessionModelSwitchError`, o cron persiste o provedor e o modelo trocados (e a substituição de perfil de autenticação trocada quando presente) para a execução ativa antes de tentar novamente. O loop externo de novas tentativas é limitado a duas tentativas de troca após a tentativa inicial e então aborta, em vez de ficar em loop para sempre.
Se uma execução isolada lançar `LiveSessionModelSwitchError`, o Cron persiste o provedor e o modelo trocados (e a substituição de perfil de autenticação trocada, quando presente) para a execução ativa antes de tentar novamente. O loop externo de nova tentativa é limitado a duas novas tentativas de troca após a tentativa inicial e então aborta em vez de repetir para sempre.
## Saída de execução e negações
## Saída da execução e recusas
### Supressão de confirmação obsoleta
Turnos de cron isolado suprimem respostas obsoletas que contêm apenas confirmação. Se o primeiro resultado for apenas uma atualização de status intermediária e nenhuma execução de subagente descendente for responsável pela resposta eventual, o cron solicita novamente uma vez o resultado real antes da entrega.
Turnos de Cron isolado suprimem respostas obsoletas que são apenas confirmações. Se o primeiro resultado for apenas uma atualização de status provisória e nenhuma execução de subagente descendente for responsável pela resposta eventual, o Cron solicita novamente uma vez pelo resultado real antes da entrega.
### Supressão de token silencioso
Se uma execução de cron isolado retornar apenas o token silencioso (`NO_REPLY` ou `no_reply`), o cron suprime tanto a entrega direta de saída quanto o caminho de resumo enfileirado de fallback, para que nada seja publicado de volta no chat.
Se uma execução isolada de Cron retornar apenas o token silencioso (`NO_REPLY` ou `no_reply`), o Cron suprime tanto a entrega direta de saída quanto o caminho de resumo enfileirado de fallback, então nada é publicado de volta no chat.
### Negações estruturadas
### Recusas estruturadas
Execuções de cron isolado preferem metadados estruturados de negação de execução da execução incorporada e então recorrem a marcadores de negação conhecidos na saída final, como `SYSTEM_RUN_DENIED`, `INVALID_REQUEST` e frases de recusa de vinculação de aprovação.
Execuções isoladas de Cron preferem metadados estruturados de recusa de execução da execução incorporada e então recorrem a marcadores de recusa conhecidos na saída final, como `SYSTEM_RUN_DENIED`, `INVALID_REQUEST` e frases de recusa de vinculação de aprovação.
`cron list` e o histórico de execuções exibem o motivo da negação em vez de relatar um comando bloqueado como `ok`.
`cron list` e o histórico de execuções expõem o motivo da recusa em vez de relatar um comando bloqueado como `ok`.
## Retenção
Retenção e poda são controladas na configuração:
Retenção e limpeza são controladas na configuração:
- `cron.sessionRetention` (padrão `24h`) poda sessões de execução isolada concluídas.
- `cron.runLog.maxBytes` e `cron.runLog.keepLines` podam `~/.openclaw/cron/runs/<jobId>.jsonl`.
- `cron.sessionRetention` (padrão `24h`) limpa sessões concluídas de execuções isoladas.
- `cron.runLog.maxBytes` e `cron.runLog.keepLines` limpam `~/.openclaw/cron/runs/<jobId>.jsonl`.
## Migrando tarefas antigas
## Migrando jobs antigos
<Note>
Se você tiver tarefas cron de antes do formato atual de entrega e armazenamento, execute `openclaw doctor --fix`. O Doctor normaliza campos cron legados (`jobId`, `schedule.cron`, campos de entrega de nível superior incluindo `threadId` legado, aliases de entrega `provider` de payload) e migra tarefas simples de fallback de webhook `notify: true` para entrega webhook explícita quando `cron.webhook` está configurado.
Se você tem jobs de Cron de antes do formato atual de entrega e armazenamento, execute `openclaw doctor --fix`. O Doctor normaliza campos legados de Cron (`jobId`, `schedule.cron`, campos de entrega de nível superior incluindo `threadId` legado, aliases de entrega `provider` no payload) e migra jobs simples de fallback de webhook `notify: true` para entrega explícita por webhook quando `cron.webhook` está configurado.
</Note>
## Edições comuns
@ -174,31 +172,31 @@ Atualize configurações de entrega sem alterar a mensagem:
openclaw cron edit <job-id> --announce --channel telegram --to "123456789"
```
Desabilite a entrega para uma tarefa isolada:
Desative a entrega para um job isolado:
```bash
openclaw cron edit <job-id> --no-deliver
```
Habilite contexto leve de bootstrap para uma tarefa isolada:
Ative contexto leve de bootstrap para um job isolado:
```bash
openclaw cron edit <job-id> --light-context
```
Anuncie em um canal específico:
Anuncie para um canal específico:
```bash
openclaw cron edit <job-id> --announce --channel slack --to "channel:C1234567890"
```
Anuncie em um tópico de fórum do Telegram:
Anuncie para um tópico de fórum do Telegram:
```bash
openclaw cron edit <job-id> --announce --channel telegram --to "-1001234567890" --thread-id 42
```
Crie uma tarefa isolada com contexto leve de bootstrap:
Crie um job isolado com contexto leve de bootstrap:
```bash
openclaw cron add \
@ -210,7 +208,7 @@ openclaw cron add \
--no-deliver
```
`--light-context` se aplica apenas a tarefas de turno de agente isoladas. Para execuções cron, o modo leve mantém o contexto de bootstrap vazio em vez de injetar o conjunto completo de bootstrap do espaço de trabalho.
`--light-context` se aplica somente a jobs isolados de turno de agente. Para execuções de Cron, o modo leve mantém o contexto de bootstrap vazio em vez de injetar o conjunto completo de bootstrap do workspace.
## Comandos administrativos comuns
@ -218,13 +216,16 @@ Execução manual e inspeção:
```bash
openclaw cron list
openclaw cron list --agent ops
openclaw cron show <job-id>
openclaw cron run <job-id>
openclaw cron run <job-id> --due
openclaw cron runs --id <job-id> --limit 50
```
Entradas de `cron runs` incluem diagnósticos de entrega com o destino cron pretendido, o destino resolvido, envios pela ferramenta de mensagem, uso de fallback e estado entregue.
`openclaw cron list` mostra todos os jobs correspondentes por padrão. Passe `--agent <id>` para mostrar somente jobs cujo ID de agente normalizado efetivo corresponda; jobs sem um ID de agente armazenado contam como o agente padrão configurado.
Entradas de `cron runs` incluem diagnósticos de entrega com o destino pretendido do Cron, o destino resolvido, envios pela ferramenta de mensagem, uso de fallback e estado entregue.
Redirecionamento de agente e sessão:
@ -235,7 +236,7 @@ openclaw cron edit <job-id> --session current
openclaw cron edit <job-id> --session "session:daily-brief"
```
`openclaw cron add` avisa quando `--agent` é omitido em tarefas de turno de agente e recorre ao agente padrão (`main`). Passe `--agent <id>` no momento da criação para fixar um agente específico.
`openclaw cron add` avisa quando `--agent` é omitido em jobs de turno de agente e recorre ao agente padrão (`main`). Passe `--agent <id>` no momento da criação para fixar um agente específico.
Ajustes de entrega:
@ -246,7 +247,7 @@ openclaw cron edit <job-id> --no-best-effort-deliver
openclaw cron edit <job-id> --no-deliver
```
## Relacionado
## Relacionados
- [Referência da CLI](/pt-BR/cli)
- [Tarefas agendadas](/pt-BR/automation/cron-jobs)

View File

@ -1,14 +1,14 @@
---
read_when:
- Você quer um diagnóstico rápido da integridade do canal + destinatários recentes da sessão
- Você quer um status “all” para depuração que possa ser colado
- Você quer um status “all” que possa ser colado para depuração
summary: Referência da CLI para `openclaw status` (diagnósticos, sondagens, instantâneos de uso)
title: Status
x-i18n:
generated_at: "2026-04-30T09:43:11Z"
generated_at: "2026-05-05T06:15:56Z"
model: gpt-5.5
provider: openai
source_hash: a85613e1830dc24253847e6517d3e155c175bb39ff6b01031ac5cb4291e276fa
source_hash: 5025ed99d351a43adc60b6896349366b225fd7ecb8ab422dba376f2d157f0033
source_path: cli/status.md
workflow: 16
---
@ -24,25 +24,26 @@ openclaw status --deep
openclaw status --usage
```
Notas:
Observações:
- `--deep` executa sondagens ao vivo (WhatsApp Web + Telegram + Discord + Slack + Signal).
- `openclaw status` simples permanece no caminho rápido somente leitura e marca a memória como `not checked` em vez de indisponível quando pula a inspeção de memória. Auditoria de segurança pesada, compatibilidade de plugins e sondagens de vetores de memória ficam para `openclaw status --all`, `openclaw status --deep`, `openclaw security audit` e `openclaw memory status --deep`.
- `status --json --all` relata detalhes de memória do runtime do Plugin de memória ativo selecionado por `plugins.slots.memory`. Plugins de memória personalizados podem deixar o `agents.defaults.memorySearch.enabled` integrado desabilitado e ainda relatar seus próprios arquivos, chunks, vetores e estado de FTS.
- `--deep` executa verificações ao vivo (WhatsApp Web + Telegram + Discord + Slack + Signal).
- `openclaw status` simples permanece no caminho rápido somente leitura e marca a memória como `not checked` em vez de indisponível quando pula a inspeção de memória. Auditoria de segurança pesada, compatibilidade de Plugin e verificações de vetor de memória ficam para `openclaw status --all`, `openclaw status --deep`, `openclaw security audit` e `openclaw memory status --deep`.
- `status --json --all` relata detalhes de memória do runtime do Plugin de memória ativo selecionado por `plugins.slots.memory`. Plugins de memória personalizados podem deixar `agents.defaults.memorySearch.enabled` integrado desativado e ainda relatar seus próprios arquivos, fragmentos, vetor e estado de FTS.
- `--usage` imprime janelas normalizadas de uso do provedor como `X% left`.
- A saída de status da sessão separa `Execution:` de `Runtime:`. `Execution` é o caminho de sandbox (`direct`, `docker/*`), enquanto `Runtime` informa se a sessão está usando `OpenClaw Pi Default`, `OpenAI Codex`, um backend de CLI ou um backend ACP, como `codex (acp/acpx)`. Consulte [Runtimes de agentes](/pt-BR/concepts/agent-runtimes) para ver a distinção entre provedor/modelo/runtime.
- Os campos brutos `usage_percent` / `usagePercent` do MiniMax são a cota restante, então o OpenClaw os inverte antes da exibição; campos baseados em contagem prevalecem quando presentes. Respostas de `model_remains` dão preferência à entrada de modelo de chat, derivam o rótulo da janela a partir de timestamps quando necessário e incluem o nome do modelo no rótulo do plano.
- Quando o snapshot da sessão atual é esparso, `/status` pode preencher contadores de tokens e cache a partir do log de uso da transcrição mais recente. Valores ao vivo existentes e não zero ainda prevalecem sobre valores de fallback da transcrição.
- O fallback da transcrição também pode recuperar o rótulo do modelo de runtime ativo quando a entrada da sessão ao vivo não o contém. Se esse modelo da transcrição for diferente do modelo selecionado, o status resolve a janela de contexto em relação ao modelo de runtime recuperado, em vez do selecionado.
- Para contabilização do tamanho do prompt, o fallback da transcrição prefere o total maior orientado a prompt quando os metadados da sessão estão ausentes ou são menores, para que sessões de provedores personalizados não caiam para exibições de `0` tokens.
- A saída inclui stores de sessão por agente quando vários agentes estão configurados.
- A visão geral inclui o status de instalação/runtime do Gateway + serviço de host do node quando disponível.
- A visão geral inclui canal de atualização + SHA do git (para checkouts de código-fonte).
- A saída de status da sessão separa `Execution:` de `Runtime:`. `Execution` é o caminho do sandbox (`direct`, `docker/*`), enquanto `Runtime` informa se a sessão está usando `OpenClaw Pi Default`, `OpenAI Codex`, um backend de CLI ou um backend de ACP, como `codex (acp/acpx)`. Consulte [Runtimes de agentes](/pt-BR/concepts/agent-runtimes) para a distinção entre provedor/modelo/runtime.
- Os campos brutos `usage_percent` / `usagePercent` da MiniMax são a cota restante, então o OpenClaw os inverte antes da exibição; campos baseados em contagem prevalecem quando presentes. Respostas de `model_remains` preferem a entrada do modelo de chat, derivam o rótulo da janela de carimbos de data/hora quando necessário e incluem o nome do modelo no rótulo do plano.
- Quando o snapshot da sessão atual é esparso, `/status` pode preencher retroativamente os contadores de tokens e cache a partir do log de uso da transcrição mais recente. Valores ao vivo existentes e diferentes de zero ainda prevalecem sobre valores de fallback da transcrição.
- `/status` inclui tempo de atividade compacto do processo do Gateway e tempo de atividade do sistema host.
- O fallback da transcrição também pode recuperar o rótulo do modelo de runtime ativo quando a entrada da sessão ao vivo não o contém. Se esse modelo da transcrição for diferente do modelo selecionado, o status resolve a janela de contexto usando o modelo de runtime recuperado em vez do selecionado.
- Para contabilização de tamanho do prompt, o fallback da transcrição prefere o maior total orientado a prompt quando os metadados da sessão estão ausentes ou são menores, para que sessões de provedores personalizados não sejam reduzidas a exibições de `0` token.
- A saída inclui armazenamentos de sessão por agente quando vários agentes estão configurados.
- A visão geral inclui o status de instalação/runtime do serviço do Gateway + host do Node quando disponível.
- A visão geral inclui o canal de atualização + SHA do git (para checkouts de código-fonte).
- Informações de atualização aparecem na Visão geral; se houver uma atualização disponível, o status imprime uma dica para executar `openclaw update` (consulte [Atualização](/pt-BR/install/updating)).
- Superfícies de status somente leitura (`status`, `status --json`, `status --all`) resolvem SecretRefs compatíveis para seus caminhos de configuração direcionados quando possível.
- Se um SecretRef de canal compatível estiver configurado, mas indisponível no caminho do comando atual, o status permanece somente leitura e relata saída degradada em vez de travar. A saída humana mostra avisos como “token configurado indisponível neste caminho de comando”, e a saída JSON inclui `secretDiagnostics`.
- Quando a resolução de SecretRef local ao comando é bem-sucedida, o status prefere o snapshot resolvido e limpa marcadores transitórios de “secret indisponível” do canal na saída final.
- `status --all` inclui uma linha de visão geral de Segredos e uma seção de diagnóstico que resume diagnósticos de segredos (truncados para facilitar a leitura) sem interromper a geração do relatório.
- Se uma SecretRef de canal compatível estiver configurada, mas indisponível no caminho do comando atual, o status permanece somente leitura e relata saída degradada em vez de falhar. A saída humana mostra avisos como “token configurado indisponível neste caminho de comando”, e a saída JSON inclui `secretDiagnostics`.
- Quando a resolução de SecretRef local ao comando é bem-sucedida, o status prefere o snapshot resolvido e limpa marcadores transitórios de “segredo indisponível” do canal na saída final.
- `status --all` inclui uma linha de visão geral de Segredos e uma seção de diagnóstico que resume diagnósticos de segredo (truncados para legibilidade) sem interromper a geração do relatório.
## Relacionado

View File

@ -1,22 +1,22 @@
---
read_when:
- Procurando uma visão geral dos recursos de mídia do OpenClaw
- Decidindo qual provedor de mídia configurar
- Como decidir qual provedor de mídia configurar
- Entendendo como funciona a geração assíncrona de mídia
sidebarTitle: Media overview
summary: Visão geral dos recursos de imagem, vídeo, música, fala e compreensão de mídia
title: Visão geral da mídia
summary: Visão geral das capacidades de imagem, vídeo, música, fala e compreensão de mídia
title: Visão geral de mídia
x-i18n:
generated_at: "2026-05-05T05:44:48Z"
generated_at: "2026-05-05T06:15:57Z"
model: gpt-5.5
provider: openai
source_hash: c57781188ca8a2dbcf378ef82dcea6645c56ed5c5dbb3222c9e4b58ab1398bf1
source_hash: fd02d4418fe294fda5f1437dd3a07c4aeb4de3b46a1b70bfe36914bc27123cc4
source_path: tools/media-overview.md
workflow: 16
---
O OpenClaw gera imagens, vídeos e música, entende mídia recebida
(imagens, áudio, vídeo) e fala respostas em voz alta com síntese de fala. Todos
OpenClaw gera imagens, vídeos e música, entende mídia recebida
(imagens, áudio, vídeo) e fala respostas em voz alta com texto para fala. Todos
os recursos de mídia são orientados por ferramentas: o agente decide quando usá-los com base
na conversa, e cada ferramenta só aparece quando pelo menos um provedor de suporte
está configurado.
@ -24,122 +24,122 @@ está configurado.
## Recursos
<CardGroup cols={2}>
<Card title="Image generation" href="/pt-BR/tools/image-generation" icon="image">
<Card title="Geração de imagens" href="/pt-BR/tools/image-generation" icon="image">
Crie e edite imagens a partir de prompts de texto ou imagens de referência via
`image_generate`. Síncrono — conclui junto com a resposta.
</Card>
<Card title="Video generation" href="/pt-BR/tools/video-generation" icon="video">
<Card title="Geração de vídeos" href="/pt-BR/tools/video-generation" icon="video">
Texto para vídeo, imagem para vídeo e vídeo para vídeo via `video_generate`.
Assíncrono — executa em segundo plano e publica o resultado quando estiver pronto.
Assíncrono — roda em segundo plano e publica o resultado quando estiver pronto.
</Card>
<Card title="Music generation" href="/pt-BR/tools/music-generation" icon="music">
Gere música ou faixas de áudio via `music_generate`. Assíncrono em provedores
compartilhados; o caminho de workflow do ComfyUI executa de forma síncrona.
<Card title="Geração de música" href="/pt-BR/tools/music-generation" icon="music">
Gere música ou faixas de áudio via `music_generate`. Assíncrono em
provedores compartilhados; o caminho de workflow do ComfyUI roda de forma síncrona.
</Card>
<Card title="Text-to-speech" href="/pt-BR/tools/tts" icon="microphone">
Converta respostas de saída em áudio falado via a ferramenta `tts` mais a
<Card title="Texto para fala" href="/pt-BR/tools/tts" icon="microphone">
Converta respostas enviadas em áudio falado via a ferramenta `tts` mais a
configuração `messages.tts`. Síncrono.
</Card>
<Card title="Media understanding" href="/pt-BR/nodes/media-understanding" icon="eye">
<Card title="Entendimento de mídia" href="/pt-BR/nodes/media-understanding" icon="eye">
Resuma imagens, áudio e vídeo recebidos usando provedores de modelo com
capacidade de visão e Plugins dedicados de compreensão de mídia.
capacidade de visão e plugins dedicados de entendimento de mídia.
</Card>
<Card title="Speech-to-text" href="/pt-BR/nodes/audio" icon="ear-listen">
Transcreva mensagens de voz recebidas por meio de provedores de STT em lote ou de
STT por streaming de Chamada de voz.
<Card title="Fala para texto" href="/pt-BR/nodes/audio" icon="ear-listen">
Transcreva mensagens de voz recebidas por meio de provedores de STT em lote ou STT
por streaming de chamada de voz.
</Card>
</CardGroup>
## Matriz de recursos por provedor
| Provedor | Imagem | Vídeo | Música | TTS | STT | Voz em tempo real | Compreensão de mídia |
| ----------- | :----: | :---: | :----: | :-: | :-: | :---------------: | :------------------: |
| Alibaba | | ✓ | | | | | |
| BytePlus | | ✓ | | | | | |
| ComfyUI | ✓ | ✓ | ✓ | | | | |
| DeepInfra | ✓ | ✓ | | ✓ | ✓ | | ✓ |
| Deepgram | | | | | ✓ | ✓ | |
| ElevenLabs | | | | ✓ | ✓ | | |
| fal | ✓ | ✓ | | | | | |
| Google | ✓ | ✓ | ✓ | ✓ | | ✓ | ✓ |
| Gradium | | | | ✓ | | | |
| CLI local | | | | ✓ | | | |
| Microsoft | | | | ✓ | | | |
| MiniMax | ✓ | ✓ | ✓ | ✓ | | | |
| Mistral | | | | | ✓ | | |
| OpenAI | ✓ | ✓ | | ✓ | ✓ | ✓ | ✓ |
| OpenRouter | ✓ | ✓ | | ✓ | | | ✓ |
| Qwen | | ✓ | | | | | |
| Runway | | ✓ | | | | | |
| SenseAudio | | | | | ✓ | | |
| Together | | ✓ | | | | | |
| Vydra | ✓ | ✓ | | ✓ | | | |
| xAI | ✓ | ✓ | | ✓ | ✓ | | ✓ |
| Xiaomi MiMo | ✓ | | | ✓ | | | ✓ |
| Provedor | Imagem | Vídeo | Música | TTS | STT | Voz em tempo real | Entendimento de mídia |
| ----------- | :----: | :---: | :----: | :-: | :-: | :---------------: | :-------------------: |
| Alibaba | | ✓ | | | | | |
| BytePlus | | ✓ | | | | | |
| ComfyUI | ✓ | ✓ | ✓ | | | | |
| DeepInfra | ✓ | ✓ | | ✓ | ✓ | | ✓ |
| Deepgram | | | | | ✓ | ✓ | |
| ElevenLabs | | | | ✓ | ✓ | | |
| fal | ✓ | ✓ | | | | | |
| Google | ✓ | ✓ | ✓ | ✓ | | ✓ | ✓ |
| Gradium | | | | ✓ | | | |
| Local CLI | | | | ✓ | | | |
| Microsoft | | | | ✓ | | | |
| MiniMax | ✓ | ✓ | ✓ | ✓ | | | |
| Mistral | | | | | ✓ | | |
| OpenAI | ✓ | ✓ | | ✓ | ✓ | ✓ | ✓ |
| OpenRouter | ✓ | ✓ | | ✓ | | | ✓ |
| Qwen | | ✓ | | | | | |
| Runway | | ✓ | | | | | |
| SenseAudio | | | | | ✓ | | |
| Together | | ✓ | | | | | |
| Vydra | ✓ | ✓ | | ✓ | | | |
| xAI | ✓ | ✓ | | ✓ | ✓ | | ✓ |
| Xiaomi MiMo | ✓ | | | ✓ | | | ✓ |
<Note>
A compreensão de mídia usa qualquer modelo com capacidade de visão ou áudio registrado
na sua configuração de provedor. A matriz acima lista provedores com suporte
dedicado de compreensão de mídia; a maioria dos provedores de LLM multimodal (Anthropic, Google,
O entendimento de mídia usa qualquer modelo com capacidade de visão ou áudio registrado
na configuração do seu provedor. A matriz acima lista provedores com suporte dedicado
a entendimento de mídia; a maioria dos provedores de LLM multimodais (Anthropic, Google,
OpenAI etc.) também consegue entender mídia recebida quando configurada como o modelo de
resposta ativo.
</Note>
## Assíncrono vs. síncrono
| Recurso | Modo | Motivo |
| ---------------- | ----------- | ----------------------------------------------------------------- |
| Imagem | Síncrono | Respostas do provedor retornam em segundos; conclui junto com a resposta. |
| Síntese de fala | Síncrono | Respostas do provedor retornam em segundos; anexadas ao áudio da resposta. |
| Vídeo | Assíncrono | O processamento do provedor leva de 30 s a vários minutos. |
| Música (compartilhado) | Assíncrono | Mesma característica de processamento do provedor que vídeo. |
| Música (ComfyUI) | Síncrono | O workflow local executa junto com o servidor ComfyUI configurado. |
| Recurso | Modo | Motivo |
| ---------------- | ------------ | ---------------------------------------------------------------------------------------------------- |
| Imagem | Síncrono | As respostas do provedor retornam em segundos; conclui junto com a resposta. |
| Texto para fala | Síncrono | As respostas do provedor retornam em segundos; anexadas ao áudio da resposta. |
| Vídeo | Assíncrono | O processamento do provedor leva de 30 s a vários minutos; filas lentas podem rodar até o timeout configurado. |
| Música (compartilhada) | Assíncrono | Mesma característica de processamento do provedor que vídeo. |
| Música (ComfyUI) | Síncrono | O workflow local roda de forma inline contra o servidor ComfyUI configurado. |
Para ferramentas assíncronas, o OpenClaw envia a solicitação ao provedor, retorna um id de tarefa
imediatamente e acompanha o job no livro-razão de tarefas. O agente continua
respondendo a outras mensagens enquanto o job executa. Quando o provedor termina,
Para ferramentas assíncronas, o OpenClaw envia a solicitação ao provedor, retorna um id
de tarefa imediatamente e acompanha o job no ledger de tarefas. O agente continua
respondendo a outras mensagens enquanto o job roda. Quando o provedor termina,
o OpenClaw desperta o agente com os caminhos da mídia gerada para que ele possa avisar o
usuário e, quando exigido pela política de entrega da origem, retransmitir o resultado pela
ferramenta de mensagem. Para rotas de grupo/canal somente com ferramenta de mensagem, o OpenClaw trata
evidência ausente de entrega por ferramenta de mensagem como uma tentativa de conclusão com falha e envia
o fallback da mídia gerada diretamente ao canal original.
a ausência de evidência de entrega pela ferramenta de mensagem como uma tentativa de conclusão com falha e envia
o fallback de mídia gerada diretamente ao canal original.
## Transcrição de fala e Chamada de voz
## Fala para texto e chamada de voz
Deepgram, DeepInfra, ElevenLabs, Mistral, OpenAI, SenseAudio e xAI conseguem transcrever
áudio recebido pelo caminho em lote `tools.media.audio` quando configurados.
Plugins de canal que fazem preflight de uma nota de voz para controle de menção ou análise de
comando marcam o anexo transcrito no contexto recebido, para que a etapa compartilhada de
compreensão de mídia reutilize essa transcrição em vez de fazer uma segunda
chamada de STT para o mesmo áudio.
Plugins de canal que fazem preflight de uma nota de voz para controle de menções ou análise de
comandos marcam o anexo transcrito no contexto recebido, para que a etapa compartilhada de
entendimento de mídia reutilize essa transcrição em vez de fazer uma segunda
chamada STT para o mesmo áudio.
Deepgram, ElevenLabs, Mistral, OpenAI e xAI também registram provedores de STT por
streaming de Chamada de voz, para que áudio telefônico ao vivo possa ser encaminhado ao fornecedor
selecionado sem esperar por uma gravação concluída.
Deepgram, ElevenLabs, Mistral, OpenAI e xAI também registram provedores de STT por streaming
de chamada de voz, para que áudio telefônico ao vivo possa ser encaminhado ao fornecedor selecionado
sem aguardar uma gravação concluída.
## Mapeamentos de provedores (como fornecedores se dividem entre superfícies)
## Mapeamentos de provedores (como os fornecedores se dividem entre superfícies)
<AccordionGroup>
<Accordion title="Google">
Superfícies de imagem, vídeo, música, TTS em lote, voz em tempo real de backend e
compreensão de mídia.
entendimento de mídia.
</Accordion>
<Accordion title="OpenAI">
Superfícies de imagem, vídeo, TTS em lote, STT em lote, STT por streaming de Chamada de voz, voz em tempo real de backend
Superfícies de imagem, vídeo, TTS em lote, STT em lote, STT por streaming de chamada de voz, voz em tempo real de backend
e embeddings de memória.
</Accordion>
<Accordion title="DeepInfra">
Superfícies de roteamento de chat/modelo, geração/edição de imagens, texto para vídeo, TTS em lote,
STT em lote, compreensão de mídia de imagem e embeddings de memória.
Modelos nativos da DeepInfra de rerank/classificação/detecção de objetos não são
STT em lote, entendimento de mídia de imagem e embeddings de memória.
Modelos nativos da DeepInfra de reranqueamento/classificação/detecção de objetos não são
registrados até que o OpenClaw tenha contratos de provedor dedicados para essas
categorias.
</Accordion>
<Accordion title="xAI">
Imagem, vídeo, busca, execução de código, TTS em lote, STT em lote e STT por streaming de Chamada de voz.
A voz em tempo real da xAI é um recurso upstream, mas não é
registrada no OpenClaw até que o contrato compartilhado de voz em tempo real consiga
representá-la.
Imagem, vídeo, busca, execução de código, TTS em lote, STT em lote e STT por streaming de chamada de voz.
Voz em tempo real da xAI é um recurso upstream, mas não é
registrado no OpenClaw até que o contrato compartilhado de voz em tempo real possa
representá-lo.
</Accordion>
</AccordionGroup>
@ -148,6 +148,6 @@ selecionado sem esperar por uma gravação concluída.
- [Geração de imagens](/pt-BR/tools/image-generation)
- [Geração de vídeos](/pt-BR/tools/video-generation)
- [Geração de música](/pt-BR/tools/music-generation)
- [Síntese de fala](/pt-BR/tools/tts)
- [Compreensão de mídia](/pt-BR/nodes/media-understanding)
- [Texto para fala](/pt-BR/tools/tts)
- [Entendimento de mídia](/pt-BR/nodes/media-understanding)
- [Nós de áudio](/pt-BR/nodes/audio)

View File

@ -1,42 +1,42 @@
---
read_when:
- Usando ou configurando comandos de chat
- Depuração de roteamento de comandos ou permissões
- Usar ou configurar comandos de chat
- Depuração do roteamento de comandos ou das permissões
sidebarTitle: Slash commands
summary: 'Comandos de barra: texto versus nativo, configuração e comandos compatíveis'
summary: 'Comandos de barra: texto vs nativos, configuração e comandos compatíveis'
title: Comandos de barra
x-i18n:
generated_at: "2026-05-04T05:55:26Z"
generated_at: "2026-05-05T06:15:55Z"
model: gpt-5.5
provider: openai
source_hash: 49eb41674c8d0a01dbd28a2df783eb9aba3dde18d8425951a266cede825e9a84
source_hash: 8a0234bd94cafe242fc692a5b9d457047e483e2a434cc92ab26046e6ddec55ce
source_path: tools/slash-commands.md
workflow: 16
---
Os comandos são gerenciados pelo Gateway. A maioria dos comandos deve ser enviada como uma mensagem **independente** que começa com `/`. O comando de chat bash somente do host usa `! <cmd>` (com `/bash <cmd>` como alias).
Os comandos são tratados pelo Gateway. A maioria dos comandos deve ser enviada como uma mensagem **independente** que começa com `/`. O comando de chat bash somente do host usa `! <cmd>` (com `/bash <cmd>` como alias).
Quando uma conversa ou thread está vinculada a uma sessão ACP, o texto normal de acompanhamento é roteado para esse harness ACP. Os comandos de gerenciamento do Gateway ainda permanecem locais: `/acp ...` sempre chega ao manipulador de comandos ACP do OpenClaw, e `/status` mais `/unfocus` permanecem locais sempre que o gerenciamento de comandos está habilitado para a superfície.
Quando uma conversa ou thread está vinculada a uma sessão ACP, o texto normal de acompanhamento é roteado para esse harness ACP. Os comandos de gerenciamento do Gateway continuam locais: `/acp ...` sempre chega ao manipulador de comandos ACP do OpenClaw, e `/status` mais `/unfocus` permanecem locais sempre que o tratamento de comandos está habilitado para a superfície.
Há dois sistemas relacionados:
<AccordionGroup>
<Accordion title="Comandos">
<Accordion title="Commands">
Mensagens `/...` independentes.
</Accordion>
<Accordion title="Diretivas">
<Accordion title="Directives">
`/think`, `/fast`, `/verbose`, `/trace`, `/reasoning`, `/elevated`, `/exec`, `/model`, `/queue`.
- As diretivas são removidas da mensagem antes que o modelo a veja.
- Em mensagens normais de chat (não apenas diretivas), elas são tratadas como "dicas inline" e **não** persistem as configurações da sessão.
- Em mensagens somente de diretivas (a mensagem contém apenas diretivas), elas persistem na sessão e respondem com uma confirmação.
- As diretivas só são aplicadas para **remetentes autorizados**. Se `commands.allowFrom` estiver definido, ele é a única lista de permissões usada; caso contrário, a autorização vem das listas de permissões/pareamento do canal mais `commands.useAccessGroups`. Remetentes não autorizados veem as diretivas tratadas como texto simples.
- As diretivas são removidas da mensagem antes de o modelo vê-la.
- Em mensagens de chat normais (não apenas diretivas), elas são tratadas como "dicas inline" e **não** persistem as configurações da sessão.
- Em mensagens somente com diretivas (a mensagem contém apenas diretivas), elas persistem na sessão e respondem com uma confirmação.
- Diretivas são aplicadas apenas para **remetentes autorizados**. Se `commands.allowFrom` estiver definido, ele será a única lista de permissão usada; caso contrário, a autorização vem das listas de permissão/pareamento do canal mais `commands.useAccessGroups`. Remetentes não autorizados veem as diretivas tratadas como texto simples.
</Accordion>
<Accordion title="Atalhos inline">
Apenas remetentes em lista de permissões/autorizados: `/help`, `/commands`, `/status`, `/whoami` (`/id`).
<Accordion title="Inline shortcuts">
Apenas remetentes permitidos/autorizados: `/help`, `/commands`, `/status`, `/whoami` (`/id`).
Eles são executados imediatamente, são removidos antes que o modelo veja a mensagem, e o texto restante continua pelo fluxo normal.
Eles são executados imediatamente, são removidos antes de o modelo ver a mensagem, e o texto restante continua pelo fluxo normal.
</Accordion>
</AccordionGroup>
@ -69,20 +69,20 @@ Há dois sistemas relacionados:
```
<ParamField path="commands.text" type="boolean" default="true">
Habilita a análise de `/...` em mensagens de chat. Em superfícies sem comandos nativos (WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams), comandos de texto ainda funcionam mesmo se você definir isto como `false`.
Habilita o parsing de `/...` em mensagens de chat. Em superfícies sem comandos nativos (WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams), comandos de texto ainda funcionam mesmo que você defina isto como `false`.
</ParamField>
<ParamField path="commands.native" type='boolean | "auto"' default='"auto"'>
Registra comandos nativos. Auto: ativado para Discord/Telegram; desativado para Slack (até você adicionar comandos de barra); ignorado para provedores sem suporte nativo. Defina `channels.discord.commands.native`, `channels.telegram.commands.native` ou `channels.slack.commands.native` para sobrescrever por provedor (bool ou `"auto"`). No Discord, `false` ignora o registro de comandos de barra e a limpeza durante a inicialização; comandos registrados anteriormente podem permanecer visíveis até você removê-los do app do Discord. Comandos do Slack são gerenciados no app do Slack e não são removidos automaticamente.
Registra comandos nativos. Auto: ativado para Discord/Telegram; desativado para Slack (até você adicionar comandos slash); ignorado para provedores sem suporte nativo. Defina `channels.discord.commands.native`, `channels.telegram.commands.native` ou `channels.slack.commands.native` para substituir por provedor (bool ou `"auto"`). No Discord, `false` ignora o registro e a limpeza de comandos slash durante a inicialização; comandos registrados anteriormente podem permanecer visíveis até você removê-los do app do Discord. Comandos do Slack são gerenciados no app do Slack e não são removidos automaticamente.
</ParamField>
No Discord, as especificações de comandos nativos podem incluir `descriptionLocalizations`, que o OpenClaw publica como `description_localizations` do Discord e inclui nas comparações de reconciliação.
No Discord, especificações de comandos nativos podem incluir `descriptionLocalizations`, que o OpenClaw publica como `description_localizations` do Discord e inclui nas comparações de reconciliação.
<ParamField path="commands.nativeSkills" type='boolean | "auto"' default='"auto"'>
Registra comandos de **skill** nativamente quando houver suporte. Auto: ativado para Discord/Telegram; desativado para Slack (o Slack exige a criação de um comando de barra por skill). Defina `channels.discord.commands.nativeSkills`, `channels.telegram.commands.nativeSkills` ou `channels.slack.commands.nativeSkills` para sobrescrever por provedor (bool ou `"auto"`).
Registra comandos de **skill** nativamente quando houver suporte. Auto: ativado para Discord/Telegram; desativado para Slack (o Slack exige a criação de um comando slash por skill). Defina `channels.discord.commands.nativeSkills`, `channels.telegram.commands.nativeSkills` ou `channels.slack.commands.nativeSkills` para substituir por provedor (bool ou `"auto"`).
</ParamField>
<ParamField path="commands.bash" type="boolean" default="false">
Habilita `! <cmd>` para executar comandos de shell do host (`/bash <cmd>` é um alias; requer listas de permissões `tools.elevated`).
Habilita `! <cmd>` para executar comandos de shell do host (`/bash <cmd>` é um alias; requer listas de permissão `tools.elevated`).
</ParamField>
<ParamField path="commands.bashForegroundMs" type="number" default="2000">
Controla por quanto tempo o bash espera antes de alternar para o modo em segundo plano (`0` envia imediatamente para segundo plano).
Controla por quanto tempo o bash espera antes de alternar para o modo em segundo plano (`0` coloca em segundo plano imediatamente).
</ParamField>
<ParamField path="commands.config" type="boolean" default="false">
Habilita `/config` (lê/grava `openclaw.json`).
@ -91,19 +91,19 @@ No Discord, as especificações de comandos nativos podem incluir `descriptionLo
Habilita `/mcp` (lê/grava a configuração MCP gerenciada pelo OpenClaw em `mcp.servers`).
</ParamField>
<ParamField path="commands.plugins" type="boolean" default="false">
Habilita `/plugins` (descoberta/status de Plugin mais controles de instalação e ativação/desativação).
Habilita `/plugins` (descoberta/status de plugins mais controles de instalação e ativação/desativação).
</ParamField>
<ParamField path="commands.debug" type="boolean" default="false">
Habilita `/debug` (sobrescritas somente em runtime).
Habilita `/debug` (substituições somente em runtime).
</ParamField>
<ParamField path="commands.restart" type="boolean" default="true">
Habilita `/restart` mais ações de ferramenta para reiniciar o Gateway.
Habilita `/restart` mais ações de ferramenta para reiniciar o gateway.
</ParamField>
<ParamField path="commands.ownerAllowFrom" type="string[]">
Define a lista explícita de permissões de proprietário para superfícies de comando/ferramenta somente de proprietário. Esta é a conta do operador humano que pode aprovar ações perigosas e executar comandos como `/diagnostics`, `/export-trajectory` e `/config`. Ela é separada de `commands.allowFrom` e do acesso por pareamento de DM.
Define a lista de permissão explícita de proprietário para superfícies de comando/ferramenta somente de proprietário. Esta é a conta do operador humano que pode aprovar ações perigosas e executar comandos como `/diagnostics`, `/export-trajectory` e `/config`. Ela é separada de `commands.allowFrom` e do acesso de pareamento por DM.
</ParamField>
<ParamField path="channels.<channel>.commands.enforceOwnerForCommands" type="boolean" default="false">
Por canal: faz com que comandos somente de proprietário exijam **identidade de proprietário** para serem executados nessa superfície. Quando `true`, o remetente deve corresponder a um candidato de proprietário resolvido (por exemplo, uma entrada em `commands.ownerAllowFrom` ou metadados de proprietário nativos do provedor) ou ter escopo interno `operator.admin` em um canal interno de mensagens. Uma entrada curinga em `allowFrom` do canal, ou uma lista vazia/não resolvida de candidatos a proprietário, **não** é suficiente — comandos somente de proprietário falham de forma fechada nesse canal. Deixe isto desativado se você quiser que comandos somente de proprietário sejam protegidos apenas por `ownerAllowFrom` e pelas listas de permissões padrão de comandos.
Por canal: faz com que comandos somente de proprietário exijam **identidade de proprietário** para serem executados nessa superfície. Quando `true`, o remetente deve corresponder a um candidato a proprietário resolvido (por exemplo, uma entrada em `commands.ownerAllowFrom` ou metadados de proprietário nativos do provedor) ou ter o escopo interno `operator.admin` em um canal de mensagens interno. Uma entrada curinga em `allowFrom` do canal, ou uma lista vazia/não resolvida de candidatos a proprietário, **não** é suficiente — comandos somente de proprietário falham fechados nesse canal. Deixe isto desativado se você quiser que comandos somente de proprietário sejam protegidos apenas por `ownerAllowFrom` e pelas listas de permissão de comandos padrão.
</ParamField>
<ParamField path="commands.ownerDisplay" type='"raw" | "hash"'>
Controla como ids de proprietário aparecem no prompt do sistema.
@ -112,65 +112,65 @@ No Discord, as especificações de comandos nativos podem incluir `descriptionLo
Opcionalmente define o segredo HMAC usado quando `commands.ownerDisplay="hash"`.
</ParamField>
<ParamField path="commands.allowFrom" type="object">
Lista de permissões por provedor para autorização de comandos. Quando configurada, ela é a única fonte de autorização para comandos e diretivas (listas de permissões/pareamento de canal e `commands.useAccessGroups` são ignorados). Use `"*"` para um padrão global; chaves específicas de provedor o sobrescrevem.
Lista de permissão por provedor para autorização de comandos. Quando configurada, ela é a única fonte de autorização para comandos e diretivas (listas de permissão/pareamento de canais e `commands.useAccessGroups` são ignorados). Use `"*"` para um padrão global; chaves específicas de provedor o substituem.
</ParamField>
<ParamField path="commands.useAccessGroups" type="boolean" default="true">
Aplica listas de permissões/políticas para comandos quando `commands.allowFrom` não está definido.
Impõe listas de permissão/políticas para comandos quando `commands.allowFrom` não está definido.
</ParamField>
## Lista de comandos
Fonte da verdade atual:
- comandos integrados principais vêm de `src/auto-reply/commands-registry.shared.ts`
- comandos dock gerados vêm de `src/auto-reply/commands-registry.data.ts`
- comandos de Plugin vêm de chamadas `registerCommand()` de Plugin
- a disponibilidade real no seu gateway ainda depende de flags de configuração, superfície de canal e Plugins instalados/habilitados
- comandos internos do core vêm de `src/auto-reply/commands-registry.shared.ts`
- comandos de dock gerados vêm de `src/auto-reply/commands-registry.data.ts`
- comandos de plugins vêm de chamadas `registerCommand()` de plugins
- a disponibilidade real no seu gateway ainda depende de flags de configuração, superfície do canal e plugins instalados/habilitados
### Comandos integrados principais
### Comandos internos do core
<AccordionGroup>
<Accordion title="Sessões e execuções">
<Accordion title="Sessions and runs">
- `/new [model]` inicia uma nova sessão; `/reset` é o alias de redefinição.
- A Control UI intercepta `/new` digitado para criar e alternar para uma nova sessão de dashboard; `/reset` digitado ainda executa a redefinição in-place do Gateway.
- `/reset soft [message]` mantém a transcrição atual, descarta ids de sessão reutilizados do backend CLI e executa novamente o carregamento de inicialização/prompt do sistema in-place.
- A Control UI intercepta `/new` digitado para criar e alternar para uma nova sessão de dashboard; `/reset` digitado ainda executa a redefinição no local do Gateway.
- `/reset soft [message]` mantém a transcrição atual, descarta ids de sessão de backend CLI reutilizados e reexecuta o carregamento de inicialização/prompt do sistema no local.
- `/compact [instructions]` compacta o contexto da sessão. Consulte [Compaction](/pt-BR/concepts/compaction).
- `/stop` aborta a execução atual.
- `/session idle <duration|off>` e `/session max-age <duration|off>` gerenciam a expiração de vínculo de thread.
- `/session idle <duration|off>` e `/session max-age <duration|off>` gerenciam a expiração do vínculo de thread.
- `/export-session [path]` exporta a sessão atual para HTML. Alias: `/export`.
- `/export-trajectory [path]` solicita aprovação de exec e depois exporta um [pacote de trajetória](/pt-BR/tools/trajectory) JSONL para a sessão atual. Use quando precisar da linha do tempo de prompt, ferramenta e transcrição para uma sessão do OpenClaw. Em chats de grupo, o prompt de aprovação e o resultado da exportação vão para o proprietário em privado. Alias: `/trajectory`.
- `/export-trajectory [path]` solicita aprovação de exec e, em seguida, exporta um [pacote de trajetória](/pt-BR/tools/trajectory) JSONL para a sessão atual. Use-o quando você precisar da linha do tempo de prompt, ferramenta e transcrição para uma sessão do OpenClaw. Em chats de grupo, o prompt de aprovação e o resultado da exportação vão para o proprietário em privado. Alias: `/trajectory`.
</Accordion>
<Accordion title="Controles de modelo e execução">
- `/think <level>` define o nível de pensamento. As opções vêm do perfil de provedor do modelo ativo; níveis comuns são `off`, `minimal`, `low`, `medium` e `high`, com níveis personalizados como `xhigh`, `adaptive`, `max` ou binário `on` apenas onde houver suporte. Aliases: `/thinking`, `/t`.
<Accordion title="Model and run controls">
- `/think <level>` define o nível de raciocínio. As opções vêm do perfil de provedor do modelo ativo; níveis comuns são `off`, `minimal`, `low`, `medium` e `high`, com níveis personalizados como `xhigh`, `adaptive`, `max` ou binário `on` apenas onde houver suporte. Aliases: `/thinking`, `/t`.
- `/verbose on|off|full` alterna a saída detalhada. Alias: `/v`.
- `/trace on|off` alterna a saída de trace de Plugin para a sessão atual.
- `/trace on|off` alterna a saída de trace de plugin para a sessão atual.
- `/fast [status|on|off]` mostra ou define o modo rápido.
- `/reasoning [on|off|stream]` alterna a visibilidade do raciocínio. Alias: `/reason`.
- `/elevated [on|off|ask|full]` alterna o modo elevado. Alias: `/elev`.
- `/exec host=<auto|sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>` mostra ou define os padrões de exec.
- `/exec host=<auto|sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>` mostra ou define padrões de exec.
- `/model [name|#|status]` mostra ou define o modelo.
- `/models [provider] [page] [limit=<n>|size=<n>|all]` lista provedores configurados/disponíveis por autenticação ou modelos de um provedor; adicione `all` para navegar pelo catálogo completo desse provedor.
- `/queue <mode>` gerencia o comportamento da fila (`steer`, `queue` legado, `followup`, `collect`, `steer-backlog`, `interrupt`) mais opções como `debounce:0.5s cap:25 drop:summarize`; `/queue default` ou `/queue reset` limpa a sobrescrita da sessão. Consulte [Fila de comandos](/pt-BR/concepts/queue) e [Fila de direcionamento](/pt-BR/concepts/queue-steering).
- `/steer <message>` injeta orientação na execução ativa para a sessão atual, independentemente do modo `/queue`. Ele não inicia uma nova execução quando a sessão está ociosa. Alias: `/tell`. Consulte [Steer](/pt-BR/tools/steer).
- `/models [provider] [page] [limit=<n>|size=<n>|all]` lista provedores ou modelos configurados/com autenticação disponível para um provedor; adicione `all` para navegar pelo catálogo completo desse provedor.
- `/queue <mode>` gerencia o comportamento da fila (`steer`, legado `queue`, `followup`, `collect`, `steer-backlog`, `interrupt`) mais opções como `debounce:0.5s cap:25 drop:summarize`; `/queue default` ou `/queue reset` limpa a substituição da sessão. Consulte [Fila de comandos](/pt-BR/concepts/queue) e [Fila de direcionamento](/pt-BR/concepts/queue-steering).
- `/steer <message>` injeta orientação na execução ativa para a sessão atual, independentemente do modo `/queue`. Ele não inicia uma nova execução quando a sessão está ociosa. Alias: `/tell`. Consulte [Direcionar](/pt-BR/tools/steer).
</Accordion>
<Accordion title="Descoberta e status">
<Accordion title="Discovery and status">
- `/help` mostra o resumo curto de ajuda.
- `/commands` mostra o catálogo de comandos gerado.
- `/tools [compact|verbose]` mostra o que o agente atual pode usar agora.
- `/status` mostra o status de execução/runtime, incluindo rótulos `Execution`/`Runtime` e uso/cota de provedor quando disponível.
- `/diagnostics [note]` é o fluxo de relatório de suporte somente de proprietário para bugs do Gateway e execuções do harness Codex. Ele solicita aprovação explícita de exec todas as vezes antes de executar `openclaw gateway diagnostics export --json`; não aprove diagnósticos com uma regra allow-all. Após a aprovação, ele envia um relatório colável com o caminho do pacote local, resumo do manifesto, notas de privacidade e ids de sessão relevantes. Em chats de grupo, o prompt de aprovação e o relatório vão para o proprietário em privado. Quando a sessão ativa usa o harness OpenAI Codex, a mesma aprovação também envia feedback relevante do Codex para servidores da OpenAI e a resposta concluída lista os ids de sessão do OpenClaw, ids de thread do Codex e comandos `codex resume <thread-id>`. Consulte [Exportação de Diagnósticos](/pt-BR/gateway/diagnostics).
- `/status` mostra status de execução/runtime, uptime do Gateway e do sistema, além de uso/cota do provedor quando disponível.
- `/diagnostics [note]` é o fluxo de relatório de suporte somente do proprietário para bugs do Gateway e execuções do harness Codex. Ele solicita aprovação explícita de exec todas as vezes antes de executar `openclaw gateway diagnostics export --json`; não aprove diagnósticos com uma regra de permitir tudo. Após a aprovação, ele envia um relatório colável com o caminho do pacote local, resumo do manifesto, notas de privacidade e ids de sessão relevantes. Em chats de grupo, o prompt de aprovação e o relatório vão para o proprietário em privado. Quando a sessão ativa usa o harness OpenAI Codex, a mesma aprovação também envia feedback relevante do Codex para servidores da OpenAI, e a resposta concluída lista os ids de sessão do OpenClaw, ids de thread do Codex e comandos `codex resume <thread-id>`. Consulte [Exportação de diagnósticos](/pt-BR/gateway/diagnostics).
- `/crestodian <request>` executa o auxiliar de configuração e reparo Crestodian a partir de uma DM do proprietário.
- `/tasks` lista tarefas em segundo plano ativas/recentes para a sessão atual.
- `/context [list|detail|json]` explica como o contexto é montado.
- `/whoami` mostra seu id de remetente. Alias: `/id`.
- `/usage off|tokens|full|cost` controla o rodapé de uso por resposta ou imprime um resumo local de custos.
- `/usage off|tokens|full|cost` controla o rodapé de uso por resposta ou imprime um resumo local de custo.
</Accordion>
<Accordion title="Skills, listas de permissões, aprovações">
- `/skill <name> [input]` executa uma skill pelo nome.
- `/allowlist [list|add|remove] ...` gerencia entradas da lista de permissões. Somente texto.
<Accordion title="Skills, allowlists, approvals">
- `/skill <name> [input]` executa uma skill por nome.
- `/allowlist [list|add|remove] ...` gerencia entradas da lista de permissão. Somente texto.
- `/approve <id> <decision>` resolve prompts de aprovação de exec.
- `/btw <question>` faz uma pergunta paralela sem alterar o contexto futuro da sessão. Alias: `/side`. Consulte [BTW](/pt-BR/tools/btw).
@ -178,59 +178,61 @@ Fonte da verdade atual:
<Accordion title="Subagentes e ACP">
- `/subagents list|kill|log|info|send|steer|spawn` gerencia execuções de subagentes para a sessão atual.
- `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` gerencia sessões ACP e opções de runtime.
- `/focus <target>` vincula a thread atual do Discord ou o tópico/conversa do Telegram a um destino de sessão.
- `/focus <target>` vincula o thread atual do Discord ou o tópico/conversa do Telegram a um destino de sessão.
- `/unfocus` remove o vínculo atual.
- `/agents` lista agentes vinculados à thread para a sessão atual.
- `/kill <id|#|all>` aborta um ou todos os subagentes em execução.
- `/subagents steer <id|#> <message>` envia orientação para um subagente em execução. Consulte [Orientar](/pt-BR/tools/steer).
- `/agents` lista agentes vinculados ao thread para a sessão atual.
- `/kill <id|#|all>` interrompe um ou todos os subagentes em execução.
- `/subagents steer <id|#> <message>` envia direcionamento para um subagente em execução. Consulte [Direcionar](/pt-BR/tools/steer).
</Accordion>
<Accordion title="Gravações somente pelo owner e administração">
- `/config show|get|set|unset` lê ou grava `openclaw.json`. Somente pelo owner. Requer `commands.config: true`.
- `/mcp show|get|set|unset` lê ou grava a configuração de servidor MCP gerenciada pelo OpenClaw em `mcp.servers`. Somente pelo owner. Requer `commands.mcp: true`.
- `/plugins list|inspect|show|get|install|enable|disable` inspeciona ou altera o estado de plugins. `/plugin` é um alias. Somente pelo owner para gravações. Requer `commands.plugins: true`.
- `/debug show|set|unset|reset` gerencia substituições de configuração somente de runtime. Somente pelo owner. Requer `commands.debug: true`.
<Accordion title="Gravações somente pelo proprietário e administração">
- `/config show|get|set|unset` lê ou grava `openclaw.json`. Somente proprietário. Exige `commands.config: true`.
- `/mcp show|get|set|unset` lê ou grava a configuração de servidor MCP gerenciada pelo OpenClaw em `mcp.servers`. Somente proprietário. Exige `commands.mcp: true`.
- `/plugins list|inspect|show|get|install|enable|disable` inspeciona ou altera o estado de plugins. `/plugin` é um alias. Gravações somente pelo proprietário. Exige `commands.plugins: true`.
- `/debug show|set|unset|reset` gerencia substituições de configuração apenas de runtime. Somente proprietário. Exige `commands.debug: true`.
- `/restart` reinicia o OpenClaw quando habilitado. Padrão: habilitado; defina `commands.restart: false` para desabilitar.
- `/send on|off|inherit` define a política de envio. Somente pelo owner.
- `/send on|off|inherit` define a política de envio. Somente proprietário.
</Accordion>
<Accordion title="Voz, TTS e controle de canal">
<Accordion title="Voz, TTS, controle de canal">
- `/tts on|off|status|chat|latest|provider|limit|summary|audio|help` controla TTS. Consulte [TTS](/pt-BR/tools/tts).
- `/activation mention|always` define o modo de ativação em grupo.
- `/bash <command>` executa um comando shell no host. Somente texto. Alias: `! <command>`. Requer `commands.bash: true` mais allowlists de `tools.elevated`.
- `!poll [sessionId]` verifica um job bash em segundo plano.
- `!stop [sessionId]` interrompe um job bash em segundo plano.
- `/bash <command>` executa um comando de shell do host. Somente texto. Alias: `! <command>`. Exige `commands.bash: true` mais allowlists de `tools.elevated`.
- `!poll [sessionId]` verifica uma tarefa bash em segundo plano.
- `!stop [sessionId]` interrompe uma tarefa bash em segundo plano.
</Accordion>
</AccordionGroup>
### Comandos dock gerados
### Comandos de encaixe gerados
Comandos dock alternam a rota de resposta da sessão atual para outro canal vinculado. Consulte [Ancoragem de canal](/pt-BR/concepts/channel-docking) para configuração, exemplos e solução de problemas.
Comandos de encaixe alternam a rota de resposta da sessão atual para outro
canal vinculado. Consulte [Encaixe de canais](/pt-BR/concepts/channel-docking) para configuração,
exemplos e solução de problemas.
Comandos dock são gerados a partir de plugins de canal com suporte a comandos nativos. Conjunto integrado atual:
Comandos de encaixe são gerados a partir de plugins de canal com suporte a comandos nativos. Conjunto empacotado atual:
- `/dock-discord` (alias: `/dock_discord`)
- `/dock-mattermost` (alias: `/dock_mattermost`)
- `/dock-slack` (alias: `/dock_slack`)
- `/dock-telegram` (alias: `/dock_telegram`)
Use comandos dock em um chat direto para alternar a rota de resposta da sessão atual para outro canal vinculado. O agente mantém o mesmo contexto de sessão, mas respostas futuras dessa sessão são entregues ao par de canal selecionado.
Use comandos de encaixe em uma conversa direta para alternar a rota de resposta da sessão atual para outro canal vinculado. O agente mantém o mesmo contexto de sessão, mas as respostas futuras dessa sessão são entregues ao par do canal selecionado.
Comandos dock exigem `session.identityLinks`. O remetente de origem e o par de destino devem estar no mesmo grupo de identidade, por exemplo `["telegram:123", "discord:456"]`. Se um usuário do Telegram com id `123` enviar `/dock_discord`, o OpenClaw armazena `lastChannel: "discord"` e `lastTo: "456"` na sessão ativa. Se o remetente não estiver vinculado a um par do Discord, o comando responde com uma dica de configuração em vez de cair no chat normal.
Comandos de encaixe exigem `session.identityLinks`. O remetente de origem e o par de destino devem estar no mesmo grupo de identidades, por exemplo `["telegram:123", "discord:456"]`. Se um usuário do Telegram com id `123` enviar `/dock_discord`, o OpenClaw armazena `lastChannel: "discord"` e `lastTo: "456"` na sessão ativa. Se o remetente não estiver vinculado a um par do Discord, o comando responde com uma dica de configuração em vez de seguir para o chat normal.
A ancoragem altera apenas a rota da sessão ativa. Ela não cria contas de canal, concede acesso, contorna allowlists de canal nem move o histórico de transcrição para outra sessão. Use `/dock-telegram`, `/dock-slack`, `/dock-mattermost` ou outro comando dock gerado para alternar a rota novamente.
O encaixe altera apenas a rota da sessão ativa. Ele não cria contas de canal, concede acesso, ignora allowlists de canais nem move o histórico de transcrição para outra sessão. Use `/dock-telegram`, `/dock-slack`, `/dock-mattermost` ou outro comando de encaixe gerado para alternar a rota novamente.
### Comandos de plugins integrados
### Comandos de plugins empacotados
Plugins integrados podem adicionar mais comandos de barra. Comandos integrados atuais neste repo:
Plugins empacotados podem adicionar mais comandos de barra. Comandos empacotados atuais neste repositório:
- `/dreaming [on|off|status|help]` alterna o dreaming de memória. Consulte [Dreaming](/pt-BR/concepts/dreaming).
- `/pair [qr|status|pending|approve|cleanup|notify]` gerencia o fluxo de pareamento/configuração de dispositivo. Consulte [Pareamento](/pt-BR/channels/pairing).
- `/phone status|arm <camera|screen|writes|all> [duration]|disarm` arma temporariamente comandos de node de telefone de alto risco.
- `/dreaming [on|off|status|help]` alterna Dreaming de memória. Consulte [Dreaming](/pt-BR/concepts/dreaming).
- `/pair [qr|status|pending|approve|cleanup|notify]` gerencia o fluxo de emparelhamento/configuração de dispositivos. Consulte [Emparelhamento](/pt-BR/channels/pairing).
- `/phone status|arm <camera|screen|writes|all> [duration]|disarm` arma temporariamente comandos de Node de telefone de alto risco.
- `/voice status|list [limit]|set <voiceId|name>` gerencia a configuração de voz do Talk. No Discord, o nome do comando nativo é `/talkvoice`.
- `/card ...` envia predefinições de rich card do LINE. Consulte [LINE](/pt-BR/channels/line).
- `/codex status|models|threads|resume|compact|review|diagnostics|account|mcp|skills` inspeciona e controla o harness app-server integrado do Codex. Consulte [Harness do Codex](/pt-BR/plugins/codex-harness).
- `/card ...` envia predefinições de cartão rico do LINE. Consulte [LINE](/pt-BR/channels/line).
- `/codex status|models|threads|resume|compact|review|diagnostics|account|mcp|skills` inspeciona e controla o harness de servidor de app Codex empacotado. Consulte [Harness Codex](/pt-BR/plugins/codex-harness).
- Comandos somente do QQBot:
- `/bot-ping`
- `/bot-version`
@ -238,67 +240,67 @@ Plugins integrados podem adicionar mais comandos de barra. Comandos integrados a
- `/bot-upgrade`
- `/bot-logs`
### Comandos de skill dinâmicos
### Comandos dinâmicos de Skills
Skills invocáveis pelo usuário também são expostas como comandos de barra:
- `/skill <name> [input]` sempre funciona como o ponto de entrada genérico.
- skills também podem aparecer como comandos diretos, como `/prose`, quando a skill/plugin os registra.
- o registro nativo de comandos de skill é controlado por `commands.nativeSkills` e `channels.<provider>.commands.nativeSkills`.
- especificações de comando podem fornecer `descriptionLocalizations` para superfícies nativas que aceitam descrições localizadas, incluindo Discord.
- Skills também podem aparecer como comandos diretos, como `/prose`, quando a skill/plugin os registra.
- o registro de comandos nativos de Skills é controlado por `commands.nativeSkills` e `channels.<provider>.commands.nativeSkills`.
- especificações de comando podem fornecer `descriptionLocalizations` para superfícies nativas que dão suporte a descrições localizadas, incluindo Discord.
<AccordionGroup>
<Accordion title="Notas de argumentos e parser">
<Accordion title="Observações sobre argumentos e parser">
- Comandos aceitam um `:` opcional entre o comando e os argumentos (por exemplo, `/think: high`, `/send: on`, `/help:`).
- `/new <model>` aceita um alias de modelo, `provider/model` ou um nome de provider (correspondência aproximada); se não houver correspondência, o texto será tratado como o corpo da mensagem.
- Para uma análise completa de uso por provider, use `openclaw status --usage`.
- `/new <model>` aceita um alias de modelo, `provider/model` ou um nome de provedor (correspondência aproximada); se não houver correspondência, o texto é tratado como o corpo da mensagem.
- Para o detalhamento completo de uso por provedor, use `openclaw status --usage`.
- `/allowlist add|remove` exige `commands.config=true` e respeita `configWrites` do canal.
- Em canais com várias contas, `/allowlist --account <id>` direcionado à configuração e `/config set channels.<provider>.accounts.<id>...` também respeitam o `configWrites` da conta de destino.
- `/usage` controla o rodapé de uso por resposta; `/usage cost` imprime um resumo de custo local a partir dos logs de sessão do OpenClaw.
- `/restart` é habilitado por padrão; defina `commands.restart: false` para desabilitá-lo.
- `/plugins install <spec>` aceita as mesmas especificações de plugin que `openclaw plugins install`: caminho local/archive, pacote npm, `git:<repo>` ou `clawhub:<pkg>`, depois solicita uma reinicialização do Gateway porque os módulos de origem do plugin mudaram.
- `/plugins enable|disable` atualiza a configuração de plugin e aciona o recarregamento de plugin do Gateway para novas interações de agente.
- `/usage` controla o rodapé de uso por resposta; `/usage cost` imprime um resumo local de custos a partir dos logs de sessão do OpenClaw.
- `/restart` é habilitado por padrão; defina `commands.restart: false` para desabilitar.
- `/plugins install <spec>` aceita as mesmas especificações de Plugin que `openclaw plugins install`: caminho/arquivo local, pacote npm, `git:<repo>` ou `clawhub:<pkg>`, então solicita uma reinicialização do Gateway porque os módulos de origem do Plugin mudaram.
- `/plugins enable|disable` atualiza a configuração do Plugin e aciona o recarregamento de plugins do Gateway para novas interações do agente.
</Accordion>
<Accordion title="Comportamento específico de canal">
- Comando nativo somente do Discord: `/vc join|leave|status` controla canais de voz (não disponível como texto). `join` exige uma guilda e um canal de voz/palco selecionado. Requer `channels.discord.voice` e comandos nativos.
<Accordion title="Comportamento específico do canal">
- Comando nativo somente do Discord: `/vc join|leave|status` controla canais de voz (não disponível como texto). `join` exige um servidor e canal de voz/palco selecionado. Exige `channels.discord.voice` e comandos nativos.
- Comandos de vinculação de thread do Discord (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`) exigem que vínculos efetivos de thread estejam habilitados (`session.threadBindings.enabled` e/ou `channels.discord.threadBindings.enabled`).
- Referência de comandos ACP e comportamento de runtime: [Agentes ACP](/pt-BR/tools/acp-agents).
</Accordion>
<Accordion title="Segurança de verbose / trace / fast / reasoning">
- `/verbose` é destinado a depuração e visibilidade extra; mantenha **desligado** no uso normal.
- `/trace` é mais restrito que `/verbose`: revela apenas linhas de trace/debug pertencentes a plugins e mantém desligado o ruído verbose normal de ferramentas.
- `/fast on|off` persiste uma substituição de sessão. Use a opção `inherit` da UI de Sessões para limpá-la e voltar aos padrões de configuração.
- `/fast` é específico do provider: OpenAI/OpenAI Codex o mapeiam para `service_tier=priority` em endpoints nativos de Responses, enquanto solicitações públicas diretas à Anthropic, incluindo tráfego autenticado por OAuth enviado para `api.anthropic.com`, o mapeiam para `service_tier=auto` ou `standard_only`. Consulte [OpenAI](/pt-BR/providers/openai) e [Anthropic](/pt-BR/providers/anthropic).
- Resumos de falhas de ferramenta ainda são exibidos quando relevantes, mas o texto detalhado da falha só é incluído quando `/verbose` está `on` ou `full`.
- `/reasoning`, `/verbose` e `/trace` são arriscados em configurações de grupo: podem revelar raciocínio interno, saída de ferramentas ou diagnósticos de plugin que você não pretendia expor. Prefira mantê-los desligados, especialmente em chats em grupo.
<Accordion title="Segurança de detalhado / trace / rápido / raciocínio">
- `/verbose` serve para depuração e visibilidade extra; mantenha-o **desligado** no uso normal.
- `/trace` é mais restrito que `/verbose`: ele revela apenas linhas de trace/depuração de propriedade do Plugin e mantém desligada a verbosidade normal de ferramentas.
- `/fast on|off` persiste uma substituição de sessão. Use a opção `inherit` da UI de Sessões para limpá-la e voltar aos padrões da configuração.
- `/fast` é específico do provedor: OpenAI/OpenAI Codex o mapeiam para `service_tier=priority` em endpoints Responses nativos, enquanto solicitações públicas diretas da Anthropic, incluindo tráfego autenticado por OAuth enviado para `api.anthropic.com`, o mapeiam para `service_tier=auto` ou `standard_only`. Consulte [OpenAI](/pt-BR/providers/openai) e [Anthropic](/pt-BR/providers/anthropic).
- Resumos de falhas de ferramentas ainda são mostrados quando relevantes, mas o texto detalhado da falha só é incluído quando `/verbose` está `on` ou `full`.
- `/reasoning`, `/verbose` e `/trace` são arriscados em contextos de grupo: eles podem revelar raciocínio interno, saída de ferramentas ou diagnósticos de plugins que você não pretendia expor. Prefira deixá-los desligados, especialmente em chats de grupo.
</Accordion>
<Accordion title="Troca de modelo">
- `/model` persiste o novo modelo da sessão imediatamente.
- Se o agente estiver ocioso, a próxima execução o usa imediatamente.
- Se uma execução já estiver ativa, o OpenClaw marca uma troca ao vivo como pendente e só reinicia no novo modelo em um ponto limpo de nova tentativa.
- Se a atividade de ferramenta ou a saída de resposta já tiver começado, a troca pendente pode permanecer na fila até uma oportunidade posterior de nova tentativa ou até o próximo turno do usuário.
- Se a atividade de ferramentas ou a saída de resposta já tiver começado, a troca pendente pode permanecer na fila até uma oportunidade posterior de nova tentativa ou a próxima interação do usuário.
- Na TUI local, `/crestodian [request]` retorna da TUI normal do agente para o Crestodian. Isso é separado do modo de resgate de canal de mensagens e não concede autoridade remota de configuração.
</Accordion>
<Accordion title="Caminho rápido e atalhos inline">
- **Caminho rápido:** mensagens somente de comando de remetentes na allowlist são tratadas imediatamente (contornam fila + modelo).
- **Gate por menção em grupo:** mensagens somente de comando de remetentes na allowlist contornam requisitos de menção.
- **Caminho rápido:** mensagens somente de comando de remetentes na allowlist são processadas imediatamente (ignora fila + modelo).
- **Bloqueio por menção em grupo:** mensagens somente de comando de remetentes na allowlist ignoram requisitos de menção.
- **Atalhos inline (somente remetentes na allowlist):** certos comandos também funcionam quando incorporados em uma mensagem normal e são removidos antes que o modelo veja o texto restante.
- Exemplo: `hey /status` aciona uma resposta de status, e o texto restante continua pelo fluxo normal.
- Atualmente: `/help`, `/commands`, `/status`, `/whoami` (`/id`).
- Mensagens somente de comando não autorizadas são ignoradas silenciosamente, e tokens inline `/...` são tratados como texto simples.
- Mensagens somente de comando não autorizadas são ignoradas silenciosamente, e tokens inline `/...` são tratados como texto comum.
</Accordion>
<Accordion title="Comandos de skill e argumentos nativos">
- **Comandos de skill:** skills `user-invocable` são expostas como comandos de barra. Nomes são sanitizados para `a-z0-9_` (máx. 32 caracteres); colisões recebem sufixos numéricos (por exemplo, `_2`).
- `/skill <name> [input]` executa uma skill pelo nome (útil quando limites de comando nativo impedem comandos por skill).
- Por padrão, comandos de skill são encaminhados ao modelo como uma solicitação normal.
- Skills podem declarar opcionalmente `command-dispatch: tool` para rotear o comando diretamente para uma ferramenta (determinístico, sem modelo).
- Exemplo: `/prose` (plugin OpenProse) — consulte [OpenProse](/pt-BR/prose).
- **Argumentos de comando nativo:** Discord usa autocomplete para opções dinâmicas (e menus de botão quando você omite argumentos obrigatórios). Telegram e Slack mostram um menu de botão quando um comando aceita escolhas e você omite o argumento. Escolhas dinâmicas são resolvidas em relação ao modelo da sessão de destino, então opções específicas de modelo, como níveis de `/think`, seguem a substituição de `/model` dessa sessão.
<Accordion title="Comandos de Skills e argumentos nativos">
- **Comandos de Skills:** Skills `user-invocable` são expostas como comandos de barra. Os nomes são sanitizados para `a-z0-9_` (máx. 32 caracteres); colisões recebem sufixos numéricos (por exemplo, `_2`).
- `/skill <name> [input]` executa uma skill pelo nome (útil quando limites de comandos nativos impedem comandos por skill).
- Por padrão, comandos de Skills são encaminhados ao modelo como uma solicitação normal.
- Skills podem opcionalmente declarar `command-dispatch: tool` para rotear o comando diretamente para uma ferramenta (determinístico, sem modelo).
- Exemplo: `/prose` (Plugin OpenProse) — consulte [OpenProse](/pt-BR/prose).
- **Argumentos de comando nativo:** Discord usa preenchimento automático para opções dinâmicas (e menus de botões quando você omite argumentos obrigatórios). Telegram e Slack mostram um menu de botões quando um comando dá suporte a escolhas e você omite o argumento. Escolhas dinâmicas são resolvidas com base no modelo da sessão de destino, então opções específicas de modelo, como níveis de `/think`, seguem a substituição de `/model` dessa sessão.
</Accordion>
</AccordionGroup>
@ -307,19 +309,19 @@ Skills invocáveis pelo usuário também são expostas como comandos de barra:
`/tools` responde a uma pergunta de runtime, não a uma pergunta de configuração: **o que este agente pode usar agora nesta conversa**.
- O `/tools` padrão é compacto e otimizado para leitura rápida.
- O `/tools` padrão é compacto e otimizado para varredura rápida.
- `/tools verbose` adiciona descrições curtas.
- Superfícies de comando nativo que aceitam argumentos expõem o mesmo seletor de modo que `compact|verbose`.
- Os resultados têm escopo de sessão, portanto alterar agente, canal, thread, autorização do remetente ou modelo pode alterar a saída.
- `/tools` inclui ferramentas realmente acessíveis em runtime, incluindo ferramentas core, ferramentas de plugins conectados e ferramentas pertencentes ao canal.
- Superfícies de comando nativo que dão suporte a argumentos expõem a mesma troca de modo como `compact|verbose`.
- Os resultados têm escopo de sessão, então alterar agente, canal, thread, autorização do remetente ou modelo pode alterar a saída.
- `/tools` inclui ferramentas que são realmente acessíveis em runtime, incluindo ferramentas principais, ferramentas de Plugin conectadas e ferramentas de propriedade do canal.
Para edição de perfil e substituições, use o painel Tools da Control UI ou superfícies de configuração/catálogo em vez de tratar `/tools` como um catálogo estático.
Para edição de perfil e substituições, use o painel Ferramentas da UI de Controle ou superfícies de configuração/catálogo em vez de tratar `/tools` como um catálogo estático.
## Superfícies de uso (o que aparece onde)
- **Uso/cota do provedor** (exemplo: "Claude 80% restante") aparece em `/status` para o provedor de modelo atual quando o rastreamento de uso está habilitado. OpenClaw normaliza as janelas do provedor para `% restante`; para MiniMax, campos percentuais somente de restante são invertidos antes da exibição, e respostas `model_remains` preferem a entrada do modelo de chat mais um rótulo de plano marcado com o modelo.
- **Linhas de tokens/cache** em `/status` podem recorrer à entrada de uso mais recente da transcrição quando o instantâneo da sessão ao vivo está esparso. Valores ao vivo existentes e diferentes de zero ainda prevalecem, e o fallback da transcrição também pode recuperar o rótulo do modelo de runtime ativo mais um total maior orientado a prompt quando os totais armazenados estão ausentes ou menores.
- **Execução vs runtime:** `/status` relata `Execution` para o caminho efetivo do sandbox e `Runtime` para quem está realmente executando a sessão: `OpenClaw Pi Default`, `OpenAI Codex`, um backend de CLI ou um backend de ACP.
- **Uso/cota do provedor** (exemplo: "Claude 80% restante") aparece em `/status` para o provedor do modelo atual quando o rastreamento de uso está habilitado. O OpenClaw normaliza as janelas do provedor para `% restante`; para MiniMax, campos percentuais somente de restante são invertidos antes da exibição, e respostas `model_remains` preferem a entrada do modelo de chat mais um rótulo de plano com tag de modelo.
- **Linhas de tokens/cache** em `/status` podem recorrer à entrada de uso mais recente da transcrição quando o snapshot da sessão em tempo real é esparso. Valores em tempo real não zero existentes ainda têm prioridade, e o fallback da transcrição também pode recuperar o rótulo do modelo de runtime ativo mais um total maior orientado a prompt quando os totais armazenados estão ausentes ou são menores.
- **Execução vs runtime:** `/status` relata `Execution` para o caminho efetivo do sandbox e `Runtime` para quem está realmente executando a sessão: `OpenClaw Pi Default`, `OpenAI Codex`, um backend de CLI ou um backend ACP.
- **Tokens/custo por resposta** é controlado por `/usage off|tokens|full` (anexado às respostas normais).
- `/model status` trata de **modelos/autenticação/endpoints**, não de uso.
@ -341,13 +343,13 @@ Exemplos:
Observações:
- `/model` e `/model list` mostram um seletor compacto e numerado (família do modelo + provedores disponíveis).
- No Discord, `/model` e `/models` abrem um seletor interativo com menus suspensos de provedor e modelo, além de uma etapa de envio.
- No Discord, `/model` e `/models` abrem um seletor interativo com menus suspensos de provedor e modelo, além de uma etapa de Enviar.
- `/model <#>` seleciona a partir desse seletor (e prefere o provedor atual quando possível).
- `/model status` mostra a visualização detalhada, incluindo o endpoint do provedor configurado (`baseUrl`) e o modo de API (`api`) quando disponíveis.
- `/model status` mostra a visualização detalhada, incluindo o endpoint configurado do provedor (`baseUrl`) e o modo de API (`api`) quando disponíveis.
## Substituições de depuração
`/debug` permite definir substituições de configuração **somente em runtime** (memória, não disco). Somente proprietário. Desabilitado por padrão; habilite com `commands.debug: true`.
`/debug` permite definir substituições de configuração **somente de runtime** (memória, não disco). Somente proprietário. Desabilitado por padrão; habilite com `commands.debug: true`.
Exemplos:
@ -360,12 +362,12 @@ Exemplos:
```
<Note>
As substituições se aplicam imediatamente a novas leituras de configuração, mas **não** gravam em `openclaw.json`. Use `/debug reset` para limpar todas as substituições e retornar à configuração em disco.
As substituições são aplicadas imediatamente a novas leituras de configuração, mas **não** são gravadas em `openclaw.json`. Use `/debug reset` para limpar todas as substituições e retornar à configuração em disco.
</Note>
## Saída de rastreamento de Plugin
`/trace` permite alternar **linhas de rastreamento/depuração de Plugin com escopo de sessão** sem ativar o modo detalhado completo.
`/trace` permite alternar **linhas de rastreamento/depuração de Plugin com escopo de sessão** sem ativar o modo verboso completo.
Exemplos:
@ -377,12 +379,12 @@ Exemplos:
Observações:
- `/trace` sem argumento mostra o estado de rastreamento da sessão atual.
- `/trace` sem argumento mostra o estado atual de rastreamento da sessão.
- `/trace on` habilita linhas de rastreamento de Plugin para a sessão atual.
- `/trace off` as desabilita novamente.
- Linhas de rastreamento de Plugin podem aparecer em `/status` e como uma mensagem diagnóstica de acompanhamento após a resposta normal do assistente.
- `/trace` não substitui `/debug`; `/debug` ainda gerencia substituições de configuração somente em runtime.
- `/trace` não substitui `/verbose`; a saída detalhada normal de ferramentas/status ainda pertence a `/verbose`.
- `/trace` não substitui `/debug`; `/debug` ainda gerencia substituições de configuração somente de runtime.
- `/trace` não substitui `/verbose`; a saída verbosa normal de ferramentas/status ainda pertence a `/verbose`.
## Atualizações de configuração
@ -404,7 +406,7 @@ A configuração é validada antes da gravação; alterações inválidas são r
## Atualizações de MCP
`/mcp` grava definições de servidores MCP gerenciadas pelo OpenClaw em `mcp.servers`. Somente proprietário. Desabilitado por padrão; habilite com `commands.mcp: true`.
`/mcp` grava definições de servidor MCP gerenciadas pelo OpenClaw em `mcp.servers`. Somente proprietário. Desabilitado por padrão; habilite com `commands.mcp: true`.
Exemplos:
@ -416,7 +418,7 @@ Exemplos:
```
<Note>
`/mcp` armazena a configuração na configuração do OpenClaw, não em configurações de projeto pertencentes ao Pi. Adaptadores de runtime decidem quais transportes são realmente executáveis.
`/mcp` armazena a configuração na configuração do OpenClaw, não nas configurações de projeto pertencentes ao Pi. Adaptadores de runtime decidem quais transportes são realmente executáveis.
</Note>
## Atualizações de Plugin
@ -434,10 +436,10 @@ Exemplos:
```
<Note>
- `/plugins list` e `/plugins show` usam descoberta real de Plugin no workspace atual mais a configuração em disco.
- `/plugins install` instala a partir de ClawHub, npm, git, diretórios locais e arquivos compactados.
- `/plugins enable|disable` atualiza apenas a configuração do Plugin; ele não instala nem desinstala Plugins.
- Alterações de habilitação e desabilitação recarregam a quente as superfícies de runtime de Plugin do Gateway para novas rodadas de agente; a instalação solicita uma reinicialização do Gateway porque os módulos-fonte do Plugin mudaram.
- `/plugins list` e `/plugins show` usam descoberta real de Plugins no workspace atual mais a configuração em disco.
- `/plugins install` instala a partir do ClawHub, npm, git, diretórios locais e arquivos compactados.
- `/plugins enable|disable` atualiza apenas a configuração de Plugin; não instala nem desinstala Plugins.
- Alterações de habilitação e desabilitação recarregam a quente as superfícies de runtime de Plugin do Gateway para novas interações do agente; a instalação solicita uma reinicialização do Gateway porque os módulos-fonte do Plugin foram alterados.
</Note>
@ -449,12 +451,12 @@ Exemplos:
- **Comandos nativos** usam sessões isoladas:
- Discord: `agent:<agentId>:discord:slash:<userId>`
- Slack: `agent:<agentId>:slack:slash:<userId>` (prefixo configurável via `channels.slack.slashCommand.sessionPrefix`)
- Telegram: `telegram:slash:<userId>` (direciona para a sessão de chat via `CommandTargetSessionKey`)
- **`/stop`** direciona para a sessão de chat ativa para que possa interromper a execução atual.
- Telegram: `telegram:slash:<userId>` (aponta para a sessão de chat via `CommandTargetSessionKey`)
- **`/stop`** aponta para a sessão de chat ativa para que ela possa abortar a execução atual.
</Accordion>
<Accordion title="Especificidades do Slack">
`channels.slack.slashCommand` ainda é compatível com um único comando no estilo `/openclaw`. Se você habilitar `commands.native`, deverá criar um comando de barra do Slack por comando integrado (mesmos nomes de `/help`). Menus de argumentos de comando para Slack são entregues como botões efêmeros do Block Kit.
`channels.slack.slashCommand` ainda é compatível com um único comando no estilo `/openclaw`. Se você habilitar `commands.native`, deverá criar um comando de barra do Slack por comando integrado (mesmos nomes que `/help`). Menus de argumentos de comando para Slack são entregues como botões efêmeros do Block Kit.
Exceção nativa do Slack: registre `/agentstatus` (não `/status`) porque o Slack reserva `/status`. O texto `/status` ainda funciona em mensagens do Slack.
@ -465,13 +467,13 @@ Exemplos:
`/btw` é uma **pergunta paralela** rápida sobre a sessão atual. `/side` é um alias.
Diferente do chat normal:
Ao contrário do chat normal:
- usa a sessão atual como contexto de fundo,
- executa como uma chamada única separada **sem ferramentas**,
- não altera o contexto futuro da sessão,
- não é gravado no histórico de transcrição,
- é entregue como um resultado paralelo ao vivo em vez de uma mensagem normal do assistente.
- é entregue como um resultado paralelo em tempo real em vez de uma mensagem normal do assistente.
Isso torna `/btw` útil quando você quer um esclarecimento temporário enquanto a tarefa principal continua em andamento.
@ -486,6 +488,6 @@ Consulte [Perguntas paralelas BTW](/pt-BR/tools/btw) para ver o comportamento co
## Relacionado
- [Criação de Skills](/pt-BR/tools/creating-skills)
- [Criando Skills](/pt-BR/tools/creating-skills)
- [Skills](/pt-BR/tools/skills)
- [Configuração de Skills](/pt-BR/tools/skills-config)

View File

@ -1,33 +1,33 @@
---
read_when:
- Gerando vídeos por meio do agente
- Configurando provedores e modelos de geração de vídeo
- Compreendendo os parâmetros da ferramenta video_generate
- Gerando vídeos pelo agente
- Configuração de provedores e modelos de geração de vídeo
- Entendendo os parâmetros da ferramenta video_generate
sidebarTitle: Video generation
summary: Gere vídeos via video_generate a partir de referências de texto, imagem ou vídeo em 16 serviços de provedores
summary: Gere vídeos por meio de video_generate a partir de referências de texto, imagem ou vídeo em 16 backends de provedores
title: Geração de vídeo
x-i18n:
generated_at: "2026-05-05T05:45:03Z"
generated_at: "2026-05-05T06:15:55Z"
model: gpt-5.5
provider: openai
source_hash: 8fd0f7922787d14736e57c9b5ea895de5bb8e126b2c73a397845ee14e1829f0b
source_hash: a86a820cc9f27baf4b17954d7ded7c2b7ff9eb456e7e75c3b2e7a7653cd675fd
source_path: tools/video-generation.md
workflow: 16
---
OpenClaw agents podem gerar vídeos a partir de prompts de texto, imagens de referência ou
Os agentes do OpenClaw podem gerar vídeos a partir de prompts de texto, imagens de referência ou
vídeos existentes. Dezesseis backends de provedores são compatíveis, cada um com
diferentes opções de modelo, modos de entrada e conjuntos de recursos. O agent escolhe o
diferentes opções de modelo, modos de entrada e conjuntos de recursos. O agente escolhe o
provedor certo automaticamente com base na sua configuração e nas chaves de API
disponíveis.
<Note>
A ferramenta `video_generate` só aparece quando pelo menos um provedor de geração de vídeo
está disponível. Se você não a vir nas ferramentas do seu agent, defina uma
está disponível. Se você não a vir nas ferramentas do seu agente, defina uma
chave de API de provedor ou configure `agents.defaults.videoGenerationModel`.
</Note>
OpenClaw trata a geração de vídeo como três modos de runtime:
O OpenClaw trata a geração de vídeo como três modos de runtime:
- `generate` — solicitações de texto para vídeo sem mídia de referência.
- `imageToVideo` — a solicitação inclui uma ou mais imagens de referência.
@ -52,51 +52,51 @@ modo ativo antes do envio e informa os modos compatíveis em `action=list`.
openclaw config set agents.defaults.videoGenerationModel.primary "google/veo-3.1-fast-generate-preview"
```
</Step>
<Step title="Pedir ao agent">
<Step title="Pedir ao agente">
> Gere um vídeo cinematográfico de 5 segundos de uma lagosta amigável surfando ao pôr do sol.
O agent chama `video_generate` automaticamente. Nenhuma lista de permissões de ferramentas
é necessária.
O agente chama `video_generate` automaticamente. Não é necessário colocar a ferramenta
em uma allowlist.
</Step>
</Steps>
## Como a geração assíncrona funciona
A geração de vídeo é assíncrona. Quando o agent chama `video_generate` em uma
A geração de vídeo é assíncrona. Quando o agente chama `video_generate` em uma
sessão:
1. OpenClaw envia a solicitação ao provedor e retorna imediatamente um ID de tarefa.
2. O provedor processa o trabalho em segundo plano (normalmente de 30 segundos a 5 minutos, dependendo do provedor e da resolução).
3. Quando o vídeo fica pronto, OpenClaw reativa a mesma sessão com um evento interno de conclusão.
4. O agent informa o usuário e anexa o vídeo finalizado. Em chats de grupo/canal
que usam entrega visível somente por ferramenta de mensagem, o agent retransmite o
resultado pela ferramenta de mensagem em vez de OpenClaw publicá-lo diretamente.
1. O OpenClaw envia a solicitação ao provedor e retorna imediatamente um id de tarefa.
2. O provedor processa o trabalho em segundo plano (normalmente de 30 segundos a vários minutos, dependendo do provedor e da resolução; provedores lentos baseados em fila podem executar até o tempo limite configurado).
3. Quando o vídeo fica pronto, o OpenClaw desperta a mesma sessão com um evento interno de conclusão.
4. O agente informa o usuário e anexa o vídeo 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 em vez de o OpenClaw publicá-lo diretamente.
Enquanto um trabalho está em andamento, chamadas duplicadas a `video_generate` na mesma
sessão retornam o status atual da tarefa em vez de iniciar outra
Enquanto um trabalho está em andamento, chamadas duplicadas de `video_generate` na mesma
sessão retornam o status da tarefa atual em vez de iniciar outra
geração. Use `openclaw tasks list` ou `openclaw tasks show <taskId>` para
verificar o progresso pela CLI.
Fora de execuções de agent com sessão (por exemplo, invocações diretas de ferramentas),
a ferramenta recorre à geração inline e retorna o caminho da mídia final
Fora de execuções de agente com sessão (por exemplo, invocações diretas de ferramenta),
a ferramenta volta para a geração inline e retorna o caminho final da mídia
no mesmo turno.
Arquivos de vídeo gerados são salvos no armazenamento de mídia gerenciado pelo OpenClaw quando
o provedor retorna bytes. O limite padrão de salvamento de vídeos gerados segue
o provedor retorna bytes. O limite padrão de salvamento de vídeo gerado segue
o limite de mídia de vídeo, e `agents.defaults.mediaMaxMb` o aumenta para
renderizações maiores. Quando um provedor também retorna uma URL de saída hospedada, OpenClaw
renders maiores. Quando um provedor também retorna uma URL de saída hospedada, o OpenClaw
pode entregar essa URL em vez de falhar a tarefa se a persistência local
rejeitar um arquivo grande demais.
### 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 5 minutos, dependendo do provedor e da resolução). |
| `succeeded` | Vídeo pronto; o agent desperta e o publica na conversa. |
| `failed` | Erro ou timeout do provedor; o agent desperta com detalhes do erro. |
| Estado | Significado |
| ----------- | ------------------------------------------------------------------------------------------------------ |
| `queued` | Tarefa criada, aguardando o provedor aceitá-la. |
| `running` | O provedor está processando (normalmente de 30 segundos a vários minutos, dependendo do provedor e da resolução). |
| `succeeded` | Vídeo pronto; o agente desperta e o publica na conversa. |
| `failed` | Erro do provedor ou tempo limite; o agente desperta com detalhes do erro. |
Verifique o status pela CLI:
@ -107,84 +107,84 @@ openclaw tasks cancel <taskId>
```
Se uma tarefa de vídeo já estiver `queued` ou `running` para a sessão atual,
`video_generate` retorna o status da tarefa existente em vez de iniciar uma nova
`video_generate` retorna o status da tarefa existente em vez de iniciar uma nova
tarefa. Use `action: "status"` para verificar explicitamente sem acionar uma nova
geração.
## Provedores compatíveis
| Provedor | Modelo padrão | Texto | Ref. de imagem | Ref. de vídeo | Autenticação |
| --------------------- | ------------------------------ | :---: | --------------------------------------------------- | --------------------------------------------- | --------------------------------------- |
| Alibaba | `wan2.6-t2v` | ✓ | Sim (URL remota) | Sim (URL remota) | `MODELSTUDIO_API_KEY` |
| BytePlus (1.0) | `seedance-1-0-pro-250528` | ✓ | Até 2 imagens (somente modelos I2V; primeiro + último quadro) | — | `BYTEPLUS_API_KEY` |
| BytePlus Seedance 1.5 | `seedance-1-5-pro-251215` | ✓ | Até 2 imagens (primeiro + último quadro via função) | — | `BYTEPLUS_API_KEY` |
| BytePlus Seedance 2.0 | `dreamina-seedance-2-0-260128` | ✓ | Até 9 imagens de referência | Até 3 vídeos | `BYTEPLUS_API_KEY` |
| ComfyUI | `workflow` | ✓ | 1 imagem | — | `COMFY_API_KEY` ou `COMFY_CLOUD_API_KEY` |
| DeepInfra | `Pixverse/Pixverse-T2V` | ✓ | — | — | `DEEPINFRA_API_KEY` |
| fal | `fal-ai/minimax/video-01-live` | ✓ | 1 imagem; até 9 com Seedance referência para vídeo | Até 3 vídeos com Seedance referência para vídeo | `FAL_KEY` |
| Google | `veo-3.1-fast-generate-preview` | ✓ | 1 imagem | 1 vídeo | `GEMINI_API_KEY` |
| MiniMax | `MiniMax-Hailuo-2.3` | ✓ | 1 imagem | — | `MINIMAX_API_KEY` ou OAuth da MiniMax |
| OpenAI | `sora-2` | ✓ | 1 imagem | 1 vídeo | `OPENAI_API_KEY` |
| OpenRouter | `google/veo-3.1-fast` | ✓ | Até 4 imagens (primeiro/último quadro ou referências) | — | `OPENROUTER_API_KEY` |
| Qwen | `wan2.6-t2v` | ✓ | Sim (URL remota) | Sim (URL remota) | `QWEN_API_KEY` |
| Runway | `gen4.5` | ✓ | 1 imagem | 1 vídeo | `RUNWAYML_API_SECRET` |
| Together | `Wan-AI/Wan2.2-T2V-A14B` | ✓ | 1 imagem | — | `TOGETHER_API_KEY` |
| Vydra | `veo3` | ✓ | 1 imagem (`kling`) | — | `VYDRA_API_KEY` |
| xAI | `grok-imagine-video` | ✓ | 1 imagem de primeiro quadro ou até 7 `reference_image`s | 1 vídeo | `XAI_API_KEY` |
| Provedor | Modelo padrão | Texto | Ref. de imagem | Ref. de vídeo | Autenticação |
| --------------------- | ------------------------------- | :--: | ---------------------------------------------------- | ----------------------------------------------- | ---------------------------------------- |
| Alibaba | `wan2.6-t2v` | ✓ | Sim (URL remota) | Sim (URL remota) | `MODELSTUDIO_API_KEY` |
| BytePlus (1.0) | `seedance-1-0-pro-250528` | ✓ | Até 2 imagens (somente modelos I2V; primeiro + último quadro) | — | `BYTEPLUS_API_KEY` |
| BytePlus Seedance 1.5 | `seedance-1-5-pro-251215` | ✓ | Até 2 imagens (primeiro + último quadro via função) | — | `BYTEPLUS_API_KEY` |
| BytePlus Seedance 2.0 | `dreamina-seedance-2-0-260128` | ✓ | Até 9 imagens de referência | Até 3 vídeos | `BYTEPLUS_API_KEY` |
| ComfyUI | `workflow` | ✓ | 1 imagem | — | `COMFY_API_KEY` ou `COMFY_CLOUD_API_KEY` |
| DeepInfra | `Pixverse/Pixverse-T2V` | ✓ | — | — | `DEEPINFRA_API_KEY` |
| fal | `fal-ai/minimax/video-01-live` | ✓ | 1 imagem; até 9 com Seedance reference-to-video | Até 3 vídeos com Seedance reference-to-video | `FAL_KEY` |
| Google | `veo-3.1-fast-generate-preview` | ✓ | 1 imagem | 1 vídeo | `GEMINI_API_KEY` |
| MiniMax | `MiniMax-Hailuo-2.3` | ✓ | 1 imagem | — | `MINIMAX_API_KEY` ou OAuth da MiniMax |
| OpenAI | `sora-2` | ✓ | 1 imagem | 1 vídeo | `OPENAI_API_KEY` |
| OpenRouter | `google/veo-3.1-fast` | ✓ | Até 4 imagens (primeiro/último quadro ou referências) | — | `OPENROUTER_API_KEY` |
| Qwen | `wan2.6-t2v` | ✓ | Sim (URL remota) | Sim (URL remota) | `QWEN_API_KEY` |
| Runway | `gen4.5` | ✓ | 1 imagem | 1 vídeo | `RUNWAYML_API_SECRET` |
| Together | `Wan-AI/Wan2.2-T2V-A14B` | ✓ | 1 imagem | — | `TOGETHER_API_KEY` |
| Vydra | `veo3` | ✓ | 1 imagem (`kling`) | — | `VYDRA_API_KEY` |
| xAI | `grok-imagine-video` | ✓ | 1 imagem de primeiro quadro ou até 7 `reference_image`s | 1 vídeo | `XAI_API_KEY` |
Alguns provedores aceitam variáveis de ambiente de chave de API adicionais ou alternativas. Consulte
as [páginas de provedores](#related) individuais para obter detalhes.
Alguns provedores aceitam variáveis de ambiente de chave de API adicionais ou alternativas. Veja
as [páginas de provedores](#related) individuais para detalhes.
Execute `video_generate action=list` para inspecionar provedores, modelos e
modos de runtime disponíveis em runtime.
modos de runtime disponíveis em tempo de execução.
### Matriz de capacidades
O contrato de modo explícito usado por `video_generate`, testes de contrato e
a varredura ao vivo compartilhada:
O contrato explícito de modo usado por `video_generate`, testes de contrato e
a varredura live compartilhada:
| Provedor | `generate` | `imageToVideo` | `videoToVideo` | Faixas ao vivo compartilhadas hoje |
| Provedor | `generate` | `imageToVideo` | `videoToVideo` | Lanes live compartilhadas hoje |
| ---------- | :--------: | :------------: | :------------: | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Alibaba | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` ignorado porque este provedor precisa de URLs de vídeo `http(s)` remotas |
| Alibaba | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` ignorado porque este provedor precisa de URLs de vídeo `http(s)` remotas |
| BytePlus | ✓ | ✓ | — | `generate`, `imageToVideo` |
| ComfyUI | ✓ | ✓ | — | Não está na varredura compartilhada; a cobertura específica de workflow fica com os testes do Comfy |
| DeepInfra | ✓ | — | — | `generate`; esquemas de vídeo nativos da DeepInfra são texto para vídeo no contrato incluído |
| fal | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` somente ao usar Seedance referência para vídeo |
| DeepInfra | ✓ | — | — | `generate`; esquemas de vídeo nativos da DeepInfra são de texto para vídeo no contrato empacotado |
| fal | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` somente ao usar Seedance reference-to-video |
| Google | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` compartilhado ignorado porque a varredura atual Gemini/Veo baseada em buffer não aceita essa entrada |
| MiniMax | ✓ | ✓ | — | `generate`, `imageToVideo` |
| OpenAI | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` compartilhado ignorado porque este caminho de organização/entrada atualmente precisa de acesso a inpaint/remix no lado do provedor |
| OpenAI | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` compartilhado ignorado porque este caminho de org/entrada atualmente precisa de acesso a inpaint/remix no lado do provedor |
| OpenRouter | ✓ | ✓ | — | `generate`, `imageToVideo` |
| Qwen | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` ignorado porque este provedor precisa de URLs de vídeo `http(s)` remotas |
| Runway | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` é executado somente quando o modelo selecionado é `runway/gen4_aleph` |
| Qwen | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` ignorado porque este provedor precisa de URLs de vídeo `http(s)` remotas |
| Runway | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` executa somente quando o modelo selecionado é `runway/gen4_aleph` |
| Together | ✓ | ✓ | — | `generate`, `imageToVideo` |
| Vydra | ✓ | ✓ | — | `generate`; `imageToVideo` compartilhado ignorado porque o `veo3` incluído é somente texto e o `kling` incluído exige uma URL de imagem remota |
| xAI | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` ignorado porque este provedor atualmente precisa de uma URL MP4 remota |
| Vydra | ✓ | ✓ | — | `generate`; `imageToVideo` compartilhado ignorado porque o `veo3` empacotado é somente texto e o `kling` empacotado exige uma URL de imagem remota |
| xAI | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` ignorado porque este provedor atualmente precisa de uma URL MP4 remota |
## Parâmetros da ferramenta
### Obrigatório
<ParamField path="prompt" type="string" required>
Descrição textual do vídeo a gerar. Obrigatório para `action: "generate"`.
Descrição em texto do vídeo a gerar. Obrigatório para `action: "generate"`.
</ParamField>
### Entradas de conteúdo
<ParamField path="image" type="string">Imagem de referência única (caminho ou URL).</ParamField>
<ParamField path="image" type="string">Uma única imagem de referência (caminho ou URL).</ParamField>
<ParamField path="images" type="string[]">Várias imagens de referência (até 9).</ParamField>
<ParamField path="imageRoles" type="string[]">
Dicas opcionais de função por posição, paralelas à lista combinada de imagens.
Valores canônicos: `first_frame`, `last_frame`, `reference_image`.
</ParamField>
<ParamField path="video" type="string">Vídeo de referência único (caminho ou URL).</ParamField>
<ParamField path="video" type="string">Um único vídeo de referência (caminho ou URL).</ParamField>
<ParamField path="videos" type="string[]">Vários vídeos de referência (até 4).</ParamField>
<ParamField path="videoRoles" type="string[]">
Dicas opcionais de função por posição, paralelas à lista combinada de vídeos.
Valor canônico: `reference_video`.
</ParamField>
<ParamField path="audioRef" type="string">
Áudio de referência único (caminho ou URL). Usado para música de fundo ou
referência de voz quando o provedor aceita entradas de áudio.
Um único áudio de referência (caminho ou URL). Usado para música de fundo ou
referência de voz quando o provedor oferece suporte a entradas de áudio.
</ParamField>
<ParamField path="audioRefs" type="string[]">Vários áudios de referência (até 3).</ParamField>
<ParamField path="audioRoles" type="string[]">
@ -193,13 +193,13 @@ Valor canônico: `reference_audio`.
</ParamField>
<Note>
As dicas de função são encaminhadas ao provedor como estão. Os valores canônicos vêm da
As dicas de função são encaminhadas ao provedor sem alterações. Os valores canônicos vêm da
união `VideoGenerationAssetRole`, mas os provedores podem aceitar strings de
função adicionais. As matrizes `*Roles` não devem ter mais entradas do que a
lista de referências correspondente; erros de deslocamento por um falham com um erro claro.
Use uma string vazia para deixar um espaço sem definição. Para xAI, defina todas as funções de imagem como
`reference_image` para usar seu modo de geração `reference_images`; omita a
função ou use `first_frame` para imagem-para-vídeo com uma única imagem.
função adicionais. Os arrays `*Roles` não podem ter mais entradas do que a
lista de referências correspondente; erros de índice por uma posição falham com um erro claro.
Use uma string vazia para deixar um slot não definido. Para xAI, defina todas as funções de imagem como
`reference_image` para usar o modo de geração `reference_images`; omita a
função ou use `first_frame` para imagem para vídeo com uma única imagem.
</Note>
### Controles de estilo
@ -209,89 +209,89 @@ função ou use `first_frame` para imagem-para-vídeo com uma única imagem.
</ParamField>
<ParamField path="resolution" type="string">Dica de resolução, como `480P`, `720P`, `768P`, `1080P`, `4K` ou um valor específico do provedor. O OpenClaw normaliza ou ignora valores sem suporte por provedor.</ParamField>
<ParamField path="durationSeconds" type="number">
Duração-alvo em segundos (arredondada para o valor mais próximo compatível com o provedor).
Duração desejada em segundos (arredondada para o valor mais próximo com suporte do provedor).
</ParamField>
<ParamField path="size" type="string">Dica de tamanho quando o provedor oferece suporte.</ParamField>
<ParamField path="size" type="string">Dica de tamanho quando o provedor oferece suporte a isso.</ParamField>
<ParamField path="audio" type="boolean">
Habilita áudio gerado na saída quando houver suporte. Diferente de `audioRef*` (entradas).
Habilite áudio gerado na saída quando houver suporte. Diferente de `audioRef*` (entradas).
</ParamField>
<ParamField path="watermark" type="boolean">Alterna a marca-d'água do provedor quando houver suporte.</ParamField>
<ParamField path="watermark" type="boolean">Ative ou desative a marca d'água do provedor quando houver suporte.</ParamField>
`adaptive` é um sentinela específico do provedor: ele é encaminhado como está para
provedores que declaram `adaptive` em seus recursos (por exemplo, o BytePlus
Seedance o usa para detectar automaticamente a proporção a partir das dimensões
da imagem de entrada). Provedores que não o declaram exibem o valor por meio de
`details.ignoredOverrides` no resultado da ferramenta para que o descarte fique visível.
`adaptive` é um sentinela específico do provedor: ele é encaminhado sem alterações para
provedores que declaram `adaptive` em suas capacidades (por exemplo, o BytePlus
Seedance o usa para detectar automaticamente a proporção a partir das
dimensões da imagem de entrada). Provedores que não o declaram exibem o valor em
`details.ignoredOverrides` no resultado da ferramenta, para que o descarte fique visível.
### Avançado
<ParamField path="action" type='"generate" | "status" | "list"' default="generate">
`"status"` retorna a tarefa atual da sessão; `"list"` inspeciona provedores.
`"status"` retorna a tarefa atual da sessão; `"list"` inspeciona os provedores.
</ParamField>
<ParamField path="model" type="string">Substituição de provedor/modelo (por exemplo, `runway/gen4.5`).</ParamField>
<ParamField path="filename" type="string">Dica de nome do arquivo de saída.</ParamField>
<ParamField path="timeoutMs" type="number">Tempo limite opcional da solicitação ao provedor em milissegundos.</ParamField>
<ParamField path="timeoutMs" type="number">Tempo limite opcional da operação do provedor em milissegundos.</ParamField>
<ParamField path="providerOptions" type="object">
Opções específicas do provedor como um objeto JSON (por exemplo, `{"seed": 42, "draft": true}`).
Provedores que declaram um esquema tipado validam as chaves e os tipos; chaves
desconhecidas ou incompatibilidades ignoram o candidato durante a alternativa. Provedores sem um
esquema declarado recebem as opções como estão. Execute `video_generate action=list`
desconhecidas ou incompatibilidades ignoram o candidato durante a alternância. Provedores sem um
esquema declarado recebem as opções sem alterações. Execute `video_generate action=list`
para ver o que cada provedor aceita.
</ParamField>
<Note>
Nem todos os provedores oferecem suporte a todos os parâmetros. O OpenClaw normaliza a duração para
o valor mais próximo compatível com o provedor e remapeia dicas de geometria traduzidas,
como tamanho para proporção, quando um provedor alternativo expõe uma superfície de
controle diferente. Substituições realmente sem suporte são ignoradas em regime de melhor esforço
e relatadas como avisos no resultado da ferramenta. Limites rígidos de recurso
(como entradas de referência em excesso) falham antes do envio. Os resultados da ferramenta
o valor mais próximo com suporte do provedor e remapeia dicas de geometria traduzidas,
como tamanho para proporção, quando um provedor alternativo expõe uma
superfície de controle diferente. Substituições realmente sem suporte são ignoradas com base no melhor esforço
e relatadas como avisos no resultado da ferramenta. Limites rígidos de capacidade
(como referências de entrada em excesso) falham antes do envio. Os resultados da ferramenta
relatam as configurações aplicadas; `details.normalization` captura qualquer
tradução de solicitado para aplicado.
tradução do solicitado para o aplicado.
</Note>
Entradas de referência selecionam o modo de execução:
As entradas de referência selecionam o modo de execução:
- Nenhuma mídia de referência → `generate`
- Qualquer referência de imagem → `imageToVideo`
- Qualquer referência de vídeo → `videoToVideo`
- Entradas de áudio de referência **não** alteram o modo resolvido; elas se aplicam
sobre qualquer modo selecionado pelas referências de imagem/vídeo e funcionam
sobre qualquer modo selecionado pelas referências de imagem/vídeo e funcionam apenas
com provedores que declaram `maxInputAudios`.
Referências mistas de imagem e vídeo não são uma superfície de recurso compartilhada estável.
Misturar referências de imagem e vídeo não é uma superfície de capacidade compartilhada estável.
Prefira um tipo de referência por solicitação.
#### Alternativa e opções tipadas
#### Alternância e opções tipadas
Algumas verificações de recurso são aplicadas na camada alternativa, em vez do
limite da ferramenta; portanto, uma solicitação que excede os limites do provedor principal ainda pode
ser executada em uma alternativa capaz:
Algumas verificações de capacidade são aplicadas na camada de alternância, e não no
limite da ferramenta, de modo que uma solicitação que exceda os limites do provedor primário ainda pode
ser executada em um provedor alternativo capaz:
- Candidato ativo que não declara `maxInputAudios` (ou declara `0`) é ignorado quando
- Um candidato ativo que não declara `maxInputAudios` (ou declara `0`) é ignorado quando
a solicitação contém referências de áudio; o próximo candidato é tentado.
- `maxDurationSeconds` do candidato ativo abaixo do `durationSeconds` solicitado
sem uma lista `supportedDurationSeconds` declarada → ignorado.
- O `maxDurationSeconds` do candidato ativo abaixo do `durationSeconds` solicitado,
sem lista `supportedDurationSeconds` declarada → ignorado.
- A solicitação contém `providerOptions` e o candidato ativo declara explicitamente
um esquema `providerOptions` tipado → ignorado se as chaves fornecidas
não estiverem no esquema ou os tipos de valor não corresponderem. Provedores sem um
esquema declarado recebem as opções como estão (passagem direta
compatível com versões anteriores). Um provedor pode recusar todas as opções de provedor ao
declarar um esquema vazio (`capabilities.providerOptions: {}`), o que
causa o mesmo ignorar de uma incompatibilidade de tipo.
um esquema tipado de `providerOptions` → ignorado se as chaves fornecidas
não estiverem no esquema ou se os tipos de valor não corresponderem. Provedores sem um
esquema declarado recebem as opções sem alterações (repasse
compatível com versões anteriores). Um provedor pode recusar todas as opções de provedor
declarando um esquema vazio (`capabilities.providerOptions: {}`), o que
causa o mesmo descarte que uma incompatibilidade de tipo.
O primeiro motivo de ignorar em uma solicitação é registrado em `warn` para que os operadores vejam quando
o provedor principal deles foi preterido; ignoramentos subsequentes são registrados em `debug` para
manter cadeias alternativas longas silenciosas. Se todos os candidatos forem ignorados, o
erro agregado inclui o motivo de ignorar de cada um.
O primeiro motivo de descarte em uma solicitação é registrado em `warn`, para que os operadores vejam quando
o provedor primário foi preterido; descartes subsequentes são registrados em `debug` para
manter cadeias longas de alternância silenciosas. Se todos os candidatos forem descartados, o
erro agregado incluirá o motivo de descarte de cada um.
## Ações
| Ação | O que faz |
| Ação | O que faz |
| ---------- | ---------------------------------------------------------------------------------------------------------- |
| `generate` | Padrão. Cria um vídeo a partir do prompt fornecido e das entradas de referência opcionais. |
| `status` | Verifica o estado da tarefa de vídeo em andamento para a sessão atual sem iniciar outra geração. |
| `list` | Mostra provedores, modelos e seus recursos disponíveis. |
| `generate` | Padrão. Cria um vídeo a partir do prompt fornecido e de entradas de referência opcionais. |
| `status` | Verifica o estado da tarefa de vídeo em andamento para a sessão atual sem iniciar outra geração. |
| `list` | Mostra os provedores, modelos e suas capacidades disponíveis. |
## Seleção de modelo
@ -301,10 +301,11 @@ O OpenClaw resolve o modelo nesta ordem:
2. **`videoGenerationModel.primary`** da configuração.
3. **`videoGenerationModel.fallbacks`** em ordem.
4. **Detecção automática** — provedores que têm autenticação válida, começando pelo
provedor padrão atual e depois os provedores restantes em ordem alfabética.
provedor padrão atual e depois os provedores restantes em ordem
alfabética.
Se um provedor falhar, o próximo candidato é tentado automaticamente. Se todos
os candidatos falharem, o erro inclui detalhes de cada tentativa.
Se um provedor falhar, o próximo candidato será tentado automaticamente. Se todos
os candidatos falharem, o erro inclui detalhes de cada tentativa.
Defina `agents.defaults.mediaGenerationAutoProviderFallback: false` para usar
apenas as entradas explícitas de `model`, `primary` e `fallbacks`.
@ -322,11 +323,11 @@ apenas as entradas explícitas de `model`, `primary` e `fallbacks`.
}
```
## Notas dos provedores
## Observações dos provedores
<AccordionGroup>
<Accordion title="Alibaba">
Usa o endpoint assíncrono DashScope / Model Studio. Imagens e
Usa o endpoint assíncrono do DashScope / Model Studio. Imagens e
vídeos de referência devem ser URLs `http(s)` remotas.
</Accordion>
<Accordion title="BytePlus (1.0)">
@ -338,11 +339,11 @@ apenas as entradas explícitas de `model`, `primary` e `fallbacks`.
Modelos T2V (`*-t2v-*`) não aceitam entradas de imagem; modelos I2V e
modelos gerais `*-pro-*` oferecem suporte a uma única imagem de referência (primeiro
quadro). Passe a imagem por posição ou defina `role: "first_frame"`.
IDs de modelo T2V são alternados automaticamente para a variante I2V
quadro). Passe a imagem posicionalmente ou defina `role: "first_frame"`.
IDs de modelo T2V são automaticamente trocados para a variante I2V
correspondente quando uma imagem é fornecida.
Chaves `providerOptions` compatíveis: `seed` (número), `draft` (booleano —
Chaves `providerOptions` com suporte: `seed` (número), `draft` (booleano —
força 480p), `camera_fixed` (booleano).
</Accordion>
@ -354,10 +355,10 @@ apenas as entradas explícitas de `model`, `primary` e `fallbacks`.
Usa a API unificada `content[]`. Oferece suporte a no máximo 2 imagens de entrada
(`first_frame` + `last_frame`). Todas as entradas devem ser URLs `https://`
remotas. Defina `role: "first_frame"` / `"last_frame"` em cada imagem, ou
passe imagens por posição.
passe as imagens posicionalmente.
`aspectRatio: "adaptive"` detecta automaticamente a proporção a partir da imagem de entrada.
`audio: true` mapeia para `generate_audio`. `providerOptions.seed`
`audio: true` é mapeado para `generate_audio`. `providerOptions.seed`
(número) é encaminhado.
</Accordion>
@ -369,72 +370,77 @@ apenas as entradas explícitas de `model`, `primary` e `fallbacks`.
Usa a API unificada `content[]`. Oferece suporte a até 9 imagens de referência,
3 vídeos de referência e 3 áudios de referência. Todas as entradas devem ser URLs
`https://` remotas. Defina `role` em cada ativo — valores compatíveis:
`https://` remotas. Defina `role` em cada ativo — valores com suporte:
`"first_frame"`, `"last_frame"`, `"reference_image"`,
`"reference_video"`, `"reference_audio"`.
`aspectRatio: "adaptive"` detecta automaticamente a proporção a partir da imagem de entrada.
`audio: true` mapeia para `generate_audio`. `providerOptions.seed`
`audio: true` é mapeado para `generate_audio`. `providerOptions.seed`
(número) é encaminhado.
</Accordion>
<Accordion title="ComfyUI">
Execução local ou na nuvem orientada por workflow. Compatível com text-to-video e
image-to-video por meio do grafo configurado.
Execução local ou em nuvem orientada por workflows. Suporta texto para vídeo e
imagem para vídeo por meio do grafo configurado.
</Accordion>
<Accordion title="fal">
Usa um fluxo com suporte de fila para jobs de longa duração. A maioria dos modelos de vídeo fal
aceita uma única referência de imagem. Modelos Seedance 2.0 reference-to-video
aceitam até 9 imagens, 3 vídeos e 3 referências de áudio, com
no máximo 12 arquivos de referência no total.
Usa um fluxo baseado em fila para jobs de longa duração. O OpenClaw aguarda até 20
minutos por padrão antes de tratar um job de fila fal em andamento como expirado.
A maioria dos modelos de vídeo fal aceita uma única referência de imagem. Os
modelos de referência para vídeo Seedance 2.0 aceitam até 9 imagens, 3 vídeos e
3 referências de áudio, com no máximo 12 arquivos de referência no total.
</Accordion>
<Accordion title="Google (Gemini / Veo)">
Compatível com uma referência de imagem ou uma referência de vídeo.
Suporta uma referência de imagem ou uma referência de vídeo. Solicitações de
áudio gerado são ignoradas com um aviso no caminho da API Gemini porque essa API
rejeita o parâmetro `generateAudio` para a geração de vídeo Veo atual.
</Accordion>
<Accordion title="MiniMax">
Apenas uma única referência de imagem.
Apenas uma referência de imagem. O MiniMax aceita resoluções `768P` e `1080P`;
solicitações como `720P` são normalizadas para o valor compatível mais próximo
antes do envio.
</Accordion>
<Accordion title="OpenAI">
Apenas a substituição de `size` é encaminhada. Outras substituições de estilo
Somente a substituição de `size` é encaminhada. Outras substituições de estilo
(`aspectRatio`, `resolution`, `audio`, `watermark`) são ignoradas com
um aviso.
</Accordion>
<Accordion title="OpenRouter">
Usa a API assíncrona `/videos` do OpenRouter. O OpenClaw envia o
Usa a API assíncrona `/videos` da OpenRouter. O OpenClaw envia o
job, consulta `polling_url` e baixa `unsigned_urls` ou o
endpoint de conteúdo do job documentado. O padrão `google/veo-3.1-fast` incluído
anuncia durações de 4/6/8 segundos, resoluções `720P`/`1080P` e
proporções de tela `16:9`/`9:16`.
proporções `16:9`/`9:16`.
</Accordion>
<Accordion title="Qwen">
Mesmo backend DashScope da Alibaba. As entradas de referência devem ser URLs remotas
`http(s)`; arquivos locais são rejeitados de antemão.
O mesmo backend DashScope da Alibaba. As entradas de referência devem ser URLs
`http(s)` remotas; arquivos locais são rejeitados antecipadamente.
</Accordion>
<Accordion title="Runway">
Compatível com arquivos locais via data URIs. Video-to-video exige
`runway/gen4_aleph`. Execuções somente texto expõem proporções de tela
Suporta arquivos locais via URIs de dados. Vídeo para vídeo requer
`runway/gen4_aleph`. Execuções apenas com texto expõem proporções
`16:9` e `9:16`.
</Accordion>
<Accordion title="Together">
Apenas uma única referência de imagem.
Apenas uma referência de imagem.
</Accordion>
<Accordion title="Vydra">
Usa `https://www.vydra.ai/api/v1` diretamente para evitar redirecionamentos
que removem autenticação. `veo3` é incluído apenas como text-to-video; `kling` exige
uma URL remota de imagem.
que removem autenticação. `veo3` é incluído apenas como texto para vídeo; `kling`
requer uma URL de imagem remota.
</Accordion>
<Accordion title="xAI">
Compatível com text-to-video, image-to-video com uma única imagem de primeiro quadro, até 7
entradas `reference_image` por meio de `reference_images` da xAI, e fluxos remotos
de edição/expansão de vídeo.
Suporta texto para vídeo, imagem única de primeiro quadro para vídeo, até 7
entradas `reference_image` por meio de `reference_images` da xAI e fluxos remotos
de edição/extensão de vídeo.
</Accordion>
</AccordionGroup>
## Modos de capacidade de provedores
O contrato compartilhado de geração de vídeo oferece suporte a capacidades específicas por modo
em vez de apenas limites agregados planos. Novas implementações de provedores
devem preferir blocos de modo explícitos:
O contrato compartilhado de geração de vídeo oferece suporte a capacidades
específicas por modo, em vez de apenas limites agregados planos. Novas implementações
de provedores devem preferir blocos de modo explícitos:
```typescript
capabilities: {
@ -460,18 +466,18 @@ capabilities: {
```
Campos agregados planos como `maxInputImages` e `maxInputVideos` **não** são
suficientes para anunciar suporte ao modo de transformação. Provedores devem
suficientes para anunciar suporte a modos de transformação. Provedores devem
declarar `generate`, `imageToVideo` e `videoToVideo` explicitamente para que testes
ao vivo, testes de contrato e a ferramenta compartilhada `video_generate` possam validar
o suporte a modos de forma determinística.
live, testes de contrato e a ferramenta compartilhada `video_generate` possam
validar o suporte a modos de forma determinística.
Quando um modelo em um provedor tiver suporte mais amplo a entradas de referência do que o
restante, use `maxInputImagesByModel`, `maxInputVideosByModel` ou
`maxInputAudiosByModel` em vez de elevar o limite de todo o modo.
Quando um modelo de um provedor tem suporte mais amplo a entradas de referência do
que o restante, use `maxInputImagesByModel`, `maxInputVideosByModel` ou
`maxInputAudiosByModel` em vez de aumentar o limite de todo o modo.
## Testes ao vivo
## Testes live
Cobertura ao vivo opcional para os provedores incluídos compartilhados:
Cobertura live opcional para os provedores compartilhados incluídos:
```bash
OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts
@ -483,31 +489,32 @@ Wrapper do repositório:
pnpm test:live:media video
```
Este arquivo ao vivo carrega variáveis de ambiente de provedores ausentes a partir de `~/.profile`, prefere
chaves de API ao vivo/de ambiente antes de perfis de autenticação armazenados por padrão, e executa um
smoke seguro para release por padrão:
Esse arquivo live carrega variáveis de ambiente ausentes do provedor a partir de
`~/.profile`, prefere chaves de API live/de ambiente antes de perfis de autenticação
armazenados por padrão e executa um smoke seguro para releases por padrão:
- `generate` para todos os provedores não FAL na varredura.
- Prompt de lagosta de um segundo.
- Limite de operação por provedor a partir de
`OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` por padrão).
FAL é opcional porque a latência de fila do lado do provedor pode dominar o tempo
FAL é opcional porque a latência da fila do lado do provedor pode dominar o tempo
de release:
```bash
pnpm test:live:media video --video-providers fal
```
Defina `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` para também executar os
modos de transformação declarados que a varredura compartilhada consegue exercitar com segurança com mídia local:
Defina `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` para também executar modos de
transformação declarados que a varredura compartilhada consegue exercitar com
segurança usando mídia local:
- `imageToVideo` quando `capabilities.imageToVideo.enabled`.
- `videoToVideo` quando `capabilities.videoToVideo.enabled` e o
provedor/modelo aceitar entrada de vídeo local baseada em buffer na varredura
provedor/modelo aceita entrada de vídeo local baseada em buffer na varredura
compartilhada.
Hoje, a lane ao vivo compartilhada de `videoToVideo` cobre apenas `runway` quando você
Hoje a lane live compartilhada de `videoToVideo` cobre `runway` somente quando você
seleciona `runway/gen4_aleph`.
## Configuração
@ -527,7 +534,7 @@ Defina o modelo padrão de geração de vídeo na sua configuração do OpenClaw
}
```
Ou pela CLI:
Ou via CLI:
```bash
openclaw config set agents.defaults.videoGenerationModel.primary "qwen/wan2.6-t2v"
@ -536,7 +543,7 @@ openclaw config set agents.defaults.videoGenerationModel.primary "qwen/wan2.6-t2
## Relacionado
- [Alibaba Model Studio](/pt-BR/providers/alibaba)
- [Tarefas em segundo plano](/pt-BR/automation/tasks) — rastreamento de tarefas para geração assíncrona de vídeo
- [Tarefas em segundo plano](/pt-BR/automation/tasks) — acompanhamento de tarefas para geração assíncrona de vídeo
- [BytePlus](/pt-BR/concepts/model-providers#byteplus-international)
- [ComfyUI](/pt-BR/providers/comfy)
- [Referência de configuração](/pt-BR/gateway/config-agents#agent-defaults)