openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh pt-BR translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-30 16:31:42 +00:00
parent a1e42ff315
commit 9d712ecc03
19 changed files with 2239 additions and 2192 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

211
docs/pt-BR/automation/tasks.md
View File

@ -1,27 +1,27 @@
---
read_when:
- Inspecionando trabalhos em segundo plano em andamento ou concluídos recentemente
- Depuração de falhas de entrega em execuções desacopladas de agentes
- Entendendo como as execuções em segundo plano se relacionam a sessões, Cron e Heartbeat
- Inspecionando trabalho em segundo plano em andamento ou concluído recentemente
- Depuração de falhas de entrega em execuções destacadas de agentes
- Entendendo como execuções em segundo plano se relacionam com sessões, Cron e Heartbeat
sidebarTitle: Background tasks
summary: Rastreamento de tarefas em segundo plano para execuções do ACP, subagentes, trabalhos Cron isolados e operações da CLI
title: Tarefas em segundo plano
x-i18n:
generated_at: "2026-04-30T09:35:15Z"
generated_at: "2026-04-30T16:27:52Z"
model: gpt-5.5
provider: openai
source_hash: 4bbf74f3aeea532738b56b83cd2e1a0a3734bfd453da6636b8be985a28ccc027
source_hash: 999653c9360323d5135e33193c76458cba8c288227de46a6217f1ccbed2a6d34
source_path: automation/tasks.md
workflow: 16
---
<Note>
Procurando agendamento? Consulte [Automação e tarefas](/pt-BR/automation) para escolher o mecanismo certo. Esta página é o registro de atividades do trabalho em segundo plano, não o agendador.
Procurando agendamento? Consulte [Automação e tarefas](/pt-BR/automation) para escolher o mecanismo certo. Esta página é o registro de atividades para trabalho em segundo plano, não o agendador.
</Note>
Tarefas em segundo plano acompanham trabalhos que rodam **fora da sua sessão principal de conversa**: execuções ACP, criações de subagentes, execuções isoladas de trabalhos Cron e operações iniciadas pela CLI.
Tarefas em segundo plano rastreiam trabalho que é executado **fora da sua sessão de conversa principal**: execuções ACP, criação de subagentes, execuções isoladas de trabalhos Cron e operações iniciadas pela CLI.
Tarefas **não** substituem sessões, trabalhos Cron nem Heartbeats — elas são o **registro de atividades** que registra qual trabalho desacoplado aconteceu, quando e se foi bem-sucedido.
Tarefas **não** substituem sessões, trabalhos Cron nem Heartbeats — elas são o **registro de atividades** que registra qual trabalho desconectado aconteceu, quando e se foi bem-sucedido.
<Note>
Nem toda execução de agente cria uma tarefa. Turnos de Heartbeat e chat interativo normal não criam. Todas as execuções Cron, criações ACP, criações de subagentes e comandos de agente da CLI criam.
@ -29,19 +29,19 @@ Nem toda execução de agente cria uma tarefa. Turnos de Heartbeat e chat intera
## TL;DR
- Tarefas são **registros**, não agendadores — Cron e Heartbeat decidem _quando_ o trabalho roda; tarefas acompanham _o que aconteceu_.
- Tarefas são **registros**, não agendadores — Cron e Heartbeat decidem _quando_ o trabalho é executado; tarefas rastreiam _o que aconteceu_.
- ACP, subagentes, todos os trabalhos Cron e operações da CLI criam tarefas. Turnos de Heartbeat não criam.
- Cada tarefa passa por `queued → running → terminal` (succeeded, failed, timed_out, cancelled ou lost).
- Tarefas Cron permanecem ativas enquanto o runtime do Cron ainda é dono do trabalho; se o
estado em memória do runtime desaparecer, a manutenção de tarefas primeiro verifica o histórico durável de execuções Cron
antes de marcar uma tarefa como perdida.
- A conclusão é orientada por push: trabalhos desacoplados podem notificar diretamente ou acordar a
sessão solicitante/Heartbeat quando terminam, portanto loops de polling de status
- Tarefas Cron permanecem ativas enquanto o runtime Cron ainda é dono do trabalho; se o
estado do runtime em memória desapareceu, a manutenção de tarefas primeiro verifica o histórico durável de
execuções Cron antes de marcar uma tarefa como perdida.
- A conclusão é orientada por push: trabalho desconectado pode notificar diretamente ou acordar a
sessão/Heartbeat solicitante quando termina, então loops de polling de status
geralmente têm o formato errado.
- Execuções Cron isoladas e conclusões de subagentes tentam limpar, em melhor esforço, abas/processos de navegador rastreados da sessão filha antes da escrituração final de limpeza.
- A entrega de Cron isolado suprime respostas intermediárias obsoletas do pai enquanto trabalho descendente de subagentes ainda está drenando, e prefere a saída final do descendente quando ela chega antes da entrega.
- Execuções Cron isoladas e conclusões de subagentes fazem a melhor tentativa de limpar abas/processos do navegador rastreados para sua sessão filha antes da contabilidade final de limpeza.
- A entrega Cron isolada suprime respostas intermediárias obsoletas do pai enquanto o trabalho de subagente descendente ainda está esvaziando, e prefere a saída final do descendente quando ela chega antes da entrega.
- Notificações de conclusão são entregues diretamente a um canal ou enfileiradas para o próximo Heartbeat.
- `openclaw tasks list` mostra todas as tarefas; `openclaw tasks audit` expõe problemas.
- `openclaw tasks list` mostra todas as tarefas; `openclaw tasks audit` revela problemas.
- Registros terminais são mantidos por 7 dias e depois removidos automaticamente.
## Início rápido
@ -97,27 +97,27 @@ Nem toda execução de agente cria uma tarefa. Turnos de Heartbeat e chat intera
## O que cria uma tarefa
| Origem | Tipo de runtime | Quando um registro de tarefa é criado | Política de notificação padrão |
| Origem | Tipo de runtime | Quando um registro de tarefa é criado | Política de notificação padrão |
| ---------------------- | ------------ | ------------------------------------------------------ | --------------------- |
| Execuções em segundo plano ACP | `acp` | Ao criar uma sessão ACP filha | `done_only` |
| Orquestração de subagentes | `subagent` | Ao criar um subagente via `sessions_spawn` | `done_only` |
| Trabalhos Cron (todos os tipos) | `cron` | A cada execução Cron (sessão principal e isolada) | `silent` |
| Operações da CLI | `cli` | Comandos `openclaw agent` que rodam pelo Gateway | `silent` |
| Trabalhos de mídia do agente | `cli` | Execuções `video_generate` apoiadas por sessão | `silent` |
| Execuções em segundo plano ACP | `acp` | Ao criar uma sessão ACP filha | `done_only` |
| Orquestração de subagentes | `subagent` | Ao criar um subagente via `sessions_spawn` | `done_only` |
| Trabalhos Cron (todos os tipos) | `cron` | Toda execução Cron (sessão principal e isolada) | `silent` |
| Operações da CLI | `cli` | Comandos `openclaw agent` que são executados pelo Gateway | `silent` |
| Trabalhos de mídia do agente | `cli` | Execuções `video_generate` respaldadas por sessão | `silent` |
<AccordionGroup>
<Accordion title="Notify defaults for cron and media">
Tarefas Cron da sessão principal usam a política de notificação `silent` por padrão — elas criam registros para acompanhamento, mas não geram notificações. Tarefas Cron isoladas também usam `silent` por padrão, mas são mais visíveis porque rodam em sua própria sessão.
Tarefas Cron de sessão principal usam a política de notificação `silent` por padrão — elas criam registros para rastreamento, mas não geram notificações. Tarefas Cron isoladas também usam `silent` por padrão, mas são mais visíveis porque são executadas em sua própria sessão.
Execuções `video_generate` apoiadas por sessão também usam a política de notificação `silent`. Elas ainda criam registros de tarefa, mas a conclusão é devolvida à sessão original do agente como uma ativação interna, para que o agente possa escrever a mensagem de acompanhamento e anexar o vídeo finalizado por conta própria. Se você optar por `tools.media.asyncCompletion.directSend`, conclusões assíncronas de `music_generate` e `video_generate` tentam primeiro a entrega direta ao canal antes de recorrer ao caminho de ativação da sessão solicitante.
Execuções `video_generate` respaldadas por sessão também usam a política de notificação `silent`. Elas ainda criam registros de tarefa, mas a conclusão é devolvida à sessão original do agente como um despertar interno para que o agente possa escrever a mensagem de acompanhamento e anexar o vídeo finalizado por conta própria. Se você optar por `tools.media.asyncCompletion.directSend`, conclusões assíncronas de `music_generate` e `video_generate` tentam primeiro a entrega direta no canal antes de recorrer ao caminho de despertar da sessão solicitante.
</Accordion>
<Accordion title="Concurrent video_generate guardrail">
Enquanto uma tarefa `video_generate` apoiada por sessão ainda estiver ativa, a ferramenta também atua como uma proteção: chamadas repetidas de `video_generate` nessa mesma sessão retornam o status da tarefa ativa em vez de iniciar uma segunda geração concorrente. Use `action: "status"` quando quiser uma consulta explícita de progresso/status pelo lado do agente.
Enquanto uma tarefa `video_generate` respaldada por sessão ainda está ativa, a ferramenta também atua como uma proteção: chamadas repetidas a `video_generate` nessa mesma sessão retornam o status da tarefa ativa em vez de iniciar uma segunda geração concorrente. Use `action: "status"` quando quiser uma consulta explícita de progresso/status pelo lado do agente.
</Accordion>
<Accordion title="What does not create tasks">
- Turnos de Heartbeat — sessão principal; consulte [Heartbeat](/pt-BR/gateway/heartbeat)
- Turnos normais de chat interativo
- Turnos de chat interativo normal
- Respostas diretas de `/command`
</Accordion>
@ -137,56 +137,56 @@ stateDiagram-v2
running --> lost : session gone > 5 min
```
| Status | O que significa |
| Status | O que significa |
| ----------- | -------------------------------------------------------------------------- |
| `queued` | Criada, aguardando o agente iniciar |
| `running` | O turno do agente está em execução ativa |
| `queued` | Criada, aguardando o agente iniciar |
| `running` | O turno do agente está em execução ativa |
| `succeeded` | Concluída com sucesso |
| `failed` | Concluída com erro |
| `timed_out` | Excedeu o tempo limite configurado |
| `cancelled` | Interrompida pelo operador via `openclaw tasks cancel` |
| `lost` | O runtime perdeu o estado de apoio autoritativo após um período de tolerância de 5 minutos |
| `failed` | Concluída com erro |
| `timed_out` | Excedeu o tempo limite configurado |
| `cancelled` | Interrompida pelo operador via `openclaw tasks cancel` |
| `lost` | O runtime perdeu o estado de apoio autoritativo após um período de carência de 5 minutos |
Transições acontecem automaticamente — quando a execução do agente associada termina, o status da tarefa é atualizado para corresponder.
Transições acontecem automaticamente — quando a execução de agente associada termina, o status da tarefa é atualizado para corresponder.
A conclusão da execução do agente é autoritativa para registros de tarefas ativos. Uma execução desacoplada bem-sucedida finaliza como `succeeded`, erros comuns de execução finalizam como `failed`, e resultados de timeout ou abortamento finalizam como `timed_out`. Se um operador já cancelou a tarefa, ou o runtime já registrou um estado terminal mais forte, como `failed`, `timed_out` ou `lost`, um sinal de sucesso posterior não rebaixa esse status terminal.
A conclusão da execução do agente é autoritativa para registros de tarefa ativos. Uma execução desconectada bem-sucedida é finalizada como `succeeded`, erros comuns de execução são finalizados como `failed`, e resultados de timeout ou abort são finalizados como `timed_out`. Se um operador já cancelou a tarefa, ou o runtime já registrou um estado terminal mais forte como `failed`, `timed_out` ou `lost`, um sinal de sucesso posterior não rebaixa esse status terminal.
`lost` leva em conta o runtime:
`lost` considera o runtime:
- Tarefas ACP: metadados da sessão ACP filha de apoio desapareceram.
- Tarefas de subagentes: a sessão filha de apoio desapareceu do armazenamento do agente de destino.
- Tarefas Cron: o runtime do Cron não rastreia mais o trabalho como ativo e o histórico durável de execuções
Cron não mostra um resultado terminal para essa execução. A auditoria offline da CLI
não trata seu próprio estado vazio do runtime Cron em processo como autoridade.
- Tarefas da CLI: tarefas de sessão filha isolada usam a sessão filha; tarefas da CLI apoiadas por chat
usam o contexto de execução ao vivo, portanto linhas persistentes de sessão de
canal/grupo/direta não as mantêm ativas. Execuções `openclaw agent` apoiadas pelo Gateway
também finalizam a partir do resultado da execução, portanto execuções concluídas
- Tarefas ACP: os metadados da sessão ACP filha de apoio desapareceram.
- Tarefas de subagente: a sessão filha de apoio desapareceu do armazenamento do agente de destino.
- Tarefas Cron: o runtime Cron não rastreia mais o trabalho como ativo e o histórico durável de
execuções Cron não mostra um resultado terminal para essa execução. Auditoria da CLI offline
não trata seu próprio estado vazio de runtime Cron em processo como autoridade.
- Tarefas da CLI: tarefas isoladas de sessão filha usam a sessão filha; tarefas da CLI respaldadas por chat
usam o contexto de execução ao vivo em vez disso, então linhas persistentes de
sessão de canal/grupo/direta não as mantêm vivas. Execuções `openclaw agent`
respaldadas pelo Gateway também são finalizadas a partir do resultado da execução, então execuções concluídas
não ficam ativas até que o varredor as marque como `lost`.
## Entrega e notificações
Quando uma tarefa atinge um estado terminal, o OpenClaw notifica você. Há dois caminhos de entrega:
Quando uma tarefa chega a um estado terminal, o OpenClaw notifica você. Há dois caminhos de entrega:
**Entrega direta** — se a tarefa tiver um destino de canal (o `requesterOrigin`), a mensagem de conclusão vai diretamente para esse canal (Telegram, Discord, Slack etc.). Para conclusões de subagentes, o OpenClaw também preserva o roteamento de thread/tópico vinculado quando disponível e pode preencher um `to` / conta ausente a partir da rota armazenada da sessão solicitante (`lastChannel` / `lastTo` / `lastAccountId`) antes de desistir da entrega direta.
**Entrega direta** — se a tarefa tiver um destino de canal (o `requesterOrigin`), a mensagem de conclusão vai direto para esse canal (Telegram, Discord, Slack etc.). Para conclusões de subagentes, o OpenClaw também preserva o roteamento de thread/tópico vinculado quando disponível e pode preencher um `to` / conta ausente a partir da rota armazenada da sessão solicitante (`lastChannel` / `lastTo` / `lastAccountId`) antes de desistir da entrega direta.
**Entrega enfileirada na sessão** — se a entrega direta falhar ou nenhuma origem estiver definida, a atualização é enfileirada como um evento de sistema na sessão solicitante e aparece no próximo Heartbeat.
**Entrega enfileirada na sessão** — se a entrega direta falhar ou nenhuma origem estiver definida, a atualização é enfileirada como um evento de sistema na sessão do solicitante e aparece no próximo Heartbeat.
<Tip>
A conclusão da tarefa aciona uma ativação imediata do Heartbeat para que você veja o resultado rapidamente — você não precisa esperar pelo próximo tick agendado do Heartbeat.
A conclusão da tarefa aciona um despertar imediato do Heartbeat para que você veja o resultado rapidamente — você não precisa esperar pelo próximo tick de Heartbeat agendado.
</Tip>
Isso significa que o fluxo de trabalho usual é baseado em push: inicie o trabalho desacoplado uma vez e deixe o runtime acordar ou notificar você na conclusão. Consulte o estado da tarefa apenas quando precisar de depuração, intervenção ou uma auditoria explícita.
Isso significa que o fluxo de trabalho usual é baseado em push: inicie o trabalho desconectado uma vez e então deixe o runtime acordar ou notificar você na conclusão. Consulte o estado da tarefa por polling apenas quando precisar de depuração, intervenção ou uma auditoria explícita.
### Políticas de notificação
Controle quanto você recebe sobre cada tarefa:
Controle quanto você ouve sobre cada tarefa:
| Política | O que é entregue |
| Política | O que é entregue |
| --------------------- | ----------------------------------------------------------------------- |
| `done_only` (padrão) | Apenas estado terminal (succeeded, failed etc.) — **este é o padrão** |
| `state_changes` | Cada transição de estado e atualização de progresso |
| `silent` | Nada |
| `state_changes` | Toda transição de estado e atualização de progresso |
| `silent` | Nada |
Altere a política enquanto uma tarefa está em execução:
@ -218,7 +218,7 @@ openclaw tasks notify <lookup> state_changes
openclaw tasks cancel <lookup>
```
Para tarefas ACP e de subagentes, isso encerra a sessão filha. Para tarefas rastreadas pela CLI, o cancelamento é registrado no registro de tarefas (não há um handle separado de runtime filho). O status transiciona para `cancelled` e uma notificação de entrega é enviada quando aplicável.
Para tarefas ACP e de subagente, isso encerra a sessão filha. Para tarefas rastreadas pela CLI, o cancelamento é registrado no registro de tarefas (não há identificador separado de runtime filho). O status muda para `cancelled` e uma notificação de entrega é enviada quando aplicável.
</Accordion>
<Accordion title="tasks notify">
@ -231,16 +231,16 @@ openclaw tasks notify <lookup> state_changes
openclaw tasks audit [--json]
```
Expõe problemas operacionais. As descobertas também aparecem em `openclaw status` quando problemas são detectados.
Revela problemas operacionais. Achados também aparecem em `openclaw status` quando problemas são detectados.
| Constatação | Severidade | Gatilho |
| ------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------ |
| `stale_queued` | aviso | Na fila há mais de 10 minutos |
| `stale_running` | erro | Em execução há mais de 30 minutos |
| `lost` | aviso/erro | A propriedade da tarefa apoiada por runtime desapareceu; tarefas perdidas retidas avisam até `cleanupAfter`, então viram erros |
| `delivery_failed` | aviso | A entrega falhou e a política de notificação não é `silent` |
| `missing_cleanup` | aviso | Tarefa terminal sem timestamp de limpeza |
| `inconsistent_timestamps` | aviso | Violação da linha do tempo (por exemplo, terminou antes de iniciar) |
| Constatação | Gravidade | Acionador |
| ------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------- |
| `stale_queued` | warn | Na fila por mais de 10 minutos |
| `stale_running` | error | Em execução por mais de 30 minutos |
| `lost` | warn/error | A propriedade da tarefa apoiada pelo runtime desapareceu; tarefas perdidas retidas avisam até `cleanupAfter` e depois viram erros |
| `delivery_failed` | warn | A entrega falhou e a política de notificação não é `silent` |
| `missing_cleanup` | warn | Tarefa terminal sem timestamp de limpeza |
| `inconsistent_timestamps` | warn | Violação da linha do tempo (por exemplo, terminou antes de começar) |
</Accordion>
<Accordion title="manutenção de tarefas">
@ -249,20 +249,21 @@ openclaw tasks notify <lookup> state_changes
openclaw tasks maintenance --apply [--json]
```
Use isto para pré-visualizar ou aplicar reconciliação, marcação de limpeza e poda para tarefas e o estado do Fluxo de Tarefas.
Use isto para pré-visualizar ou aplicar reconciliação, marcação de limpeza e poda para tarefas e estado do Task Flow.
A reconciliação reconhece o runtime:
- Tarefas de ACP/subagente verificam sua sessão filha de suporte.
- Tarefas de Cron verificam se o runtime de cron ainda possui o trabalho, então recuperam o status terminal dos logs de execução de cron persistidos/estado do trabalho antes de recorrer a `lost`. Somente o processo do Gateway é autoritativo para o conjunto em memória de trabalhos ativos de cron; a auditoria offline da CLI usa histórico durável, mas não marca uma tarefa de cron como perdida apenas porque esse Set local está vazio.
- Tarefas da CLI apoiadas por chat verificam o contexto da execução ativa proprietária, não apenas a linha da sessão de chat.
- Tarefas ACP/subagent verificam a sessão filha que as sustenta.
- Tarefas subagent cuja sessão filha tem uma lápide de recuperação de reinício são marcadas como perdidas, em vez de serem tratadas como sessões de sustentação recuperáveis.
- Tarefas Cron verificam se o runtime cron ainda é proprietário do trabalho e então recuperam o status terminal de logs de execução cron persistidos/estado do trabalho antes de recorrer a `lost`. Somente o processo Gateway é autoritativo para o conjunto em memória de trabalhos cron ativos; a auditoria offline da CLI usa histórico durável, mas não marca uma tarefa cron como perdida apenas porque esse Set local está vazio.
- Tarefas da CLI apoiadas por chat verificam o contexto de execução ao vivo proprietário, não apenas a linha da sessão de chat.
A limpeza de conclusão também reconhece o runtime:
- A conclusão de subagente tenta fechar, em melhor esforço, abas do navegador/processos rastreados para a sessão filha antes de a limpeza de anúncio continuar.
- A conclusão de cron isolado tenta fechar, em melhor esforço, abas do navegador/processos rastreados para a sessão de cron antes de a execução ser totalmente encerrada.
- A entrega de cron isolado aguarda o acompanhamento de subagentes descendentes quando necessário e suprime o texto obsoleto de confirmação do pai em vez de anunciá-lo.
- A entrega de conclusão de subagente prefere o texto mais recente visível do assistente; se ele estiver vazio, recorre ao texto sanitizado mais recente de ferramenta/toolResult, e execuções de chamada de ferramenta apenas com timeout podem ser reduzidas a um resumo curto de progresso parcial. Execuções terminais com falha anunciam o status de falha sem reproduzir o texto de resposta capturado.
- A conclusão de subagent tenta, em melhor esforço, fechar abas/processos de navegador rastreados para a sessão filha antes que a limpeza de anúncio continue.
- A conclusão de cron isolado tenta, em melhor esforço, fechar abas/processos de navegador rastreados para a sessão cron antes que a execução seja totalmente encerrada.
- A entrega de cron isolado aguarda o acompanhamento de subagent descendente quando necessário e suprime texto obsoleto de confirmação do pai em vez de anunciá-lo.
- A entrega de conclusão de subagent prefere o texto de assistente visível mais recente; se estiver vazio, recorre ao texto sanitizado mais recente de ferramenta/toolResult, e execuções de chamada de ferramenta apenas com timeout podem ser reduzidas a um breve resumo de progresso parcial. Execuções terminais com falha anunciam o status de falha sem reproduzir o texto de resposta capturado.
- Falhas de limpeza não mascaram o resultado real da tarefa.
</Accordion>
@ -273,7 +274,7 @@ openclaw tasks notify <lookup> state_changes
openclaw tasks flow cancel <lookup>
```
Use estes quando o Fluxo de Tarefas orquestrador for o que importa, em vez de um registro individual de tarefa em segundo plano.
Use estes comandos quando o Task Flow orquestrador for o que importa para você, em vez de um registro individual de tarefa em segundo plano.
</Accordion>
</AccordionGroup>
@ -282,9 +283,9 @@ openclaw tasks notify <lookup> state_changes
Use `/tasks` em qualquer sessão de chat para ver tarefas em segundo plano vinculadas a essa sessão. O quadro mostra tarefas ativas e concluídas recentemente com runtime, status, tempo e detalhes de progresso ou erro.
Quando a sessão atual não tem tarefas vinculadas visíveis, `/tasks` recorre a contagens de tarefas locais do agente para que você ainda tenha uma visão geral sem vazar detalhes de outras sessões.
Quando a sessão atual não tem tarefas vinculadas visíveis, `/tasks` recorre às contagens de tarefas locais do agente para que você ainda tenha uma visão geral sem vazar detalhes de outras sessões.
Para o registro completo do operador, use a CLI: `openclaw tasks list`.
Para o livro-razão completo do operador, use a CLI: `openclaw tasks list`.
## Integração de status (pressão de tarefas)
@ -296,81 +297,81 @@ Tasks: 3 queued · 2 running · 1 issues
O resumo informa:
- **ativas** — contagem de `queued` + `running`
- **falhas** — contagem de `failed` + `timed_out` + `lost`
- **porRuntime** — detalhamento por `acp`, `subagent`, `cron`, `cli`
- **active** — contagem de `queued` + `running`
- **failures** — contagem de `failed` + `timed_out` + `lost`
- **byRuntime** — detalhamento por `acp`, `subagent`, `cron`, `cli`
Tanto `/status` quanto a ferramenta `session_status` usam um snapshot de tarefas com reconhecimento de limpeza: tarefas ativas têm preferência, linhas concluídas obsoletas ficam ocultas, e falhas recentes só aparecem quando não resta nenhum trabalho ativo. Isso mantém o cartão de status focado no que importa agora.
Tanto `/status` quanto a ferramenta `session_status` usam um snapshot de tarefas com reconhecimento de limpeza: tarefas ativas são preferidas, linhas concluídas obsoletas são ocultadas, e falhas recentes só aparecem quando não há mais trabalho ativo. Isso mantém o cartão de status focado no que importa agora.
## Armazenamento e manutenção
### Onde as tarefas ficam
Os registros de tarefas persistem no SQLite em:
Registros de tarefas persistem no SQLite em:
```
$OPENCLAW_STATE_DIR/tasks/runs.sqlite
```
O registro é carregado na memória na inicialização do gateway e sincroniza gravações no SQLite para durabilidade entre reinicializações.
O Gateway mantém o log de gravação antecipada do SQLite delimitado usando o limite padrão de autocheckpoint do SQLite, além de checkpoints `TRUNCATE` periódicos e no desligamento.
O registro é carregado na memória na inicialização do Gateway e sincroniza gravações com o SQLite para durabilidade entre reinicializações.
O Gateway mantém o log write-ahead do SQLite limitado usando o limite padrão de autocheckpoint do SQLite, além de checkpoints periódicos e de desligamento `TRUNCATE`.
### Manutenção automática
Um varredor executa a cada **60 segundos** e cuida de quatro coisas:
Um varredor é executado a cada **60 segundos** e cuida de quatro coisas:
<Steps>
<Step title="Reconciliação">
Verifica se tarefas ativas ainda têm suporte autoritativo do runtime. Tarefas de ACP/subagente usam o estado da sessão filha, tarefas de cron usam a propriedade de trabalho ativo, e tarefas da CLI apoiadas por chat usam o contexto da execução proprietária. Se esse estado de suporte desaparecer por mais de 5 minutos, a tarefa é marcada como `lost`.
Verifica se tarefas ativas ainda têm sustentação autoritativa do runtime. Tarefas ACP/subagent usam o estado da sessão filha, tarefas cron usam propriedade de trabalho ativo, e tarefas da CLI apoiadas por chat usam o contexto de execução proprietário. Se esse estado de sustentação desaparecer por mais de 5 minutos, a tarefa é marcada como `lost`.
</Step>
<Step title="Reparo de sessão ACP">
Fecha sessões ACP one-shot terminais ou órfãs de propriedade do pai, e fecha sessões ACP persistentes terminais obsoletas ou órfãs somente quando não resta nenhuma vinculação ativa de conversa.
Fecha sessões ACP one-shot terminais ou órfãs pertencentes ao pai, e fecha sessões ACP persistentes terminais obsoletas ou órfãs somente quando não resta nenhuma vinculação de conversa ativa.
</Step>
<Step title="Marcação de limpeza">
Define um timestamp `cleanupAfter` em tarefas terminais (endedAt + 7 dias). Durante a retenção, tarefas perdidas ainda aparecem na auditoria como avisos; depois que `cleanupAfter` expira ou quando metadados de limpeza estão ausentes, elas são erros.
Define um timestamp `cleanupAfter` em tarefas terminais (endedAt + 7 dias). Durante a retenção, tarefas perdidas ainda aparecem na auditoria como avisos; depois que `cleanupAfter` expira ou quando os metadados de limpeza estão ausentes, elas são erros.
</Step>
<Step title="Poda">
Exclui registros após a data `cleanupAfter`.
Exclui registros após sua data `cleanupAfter`.
</Step>
</Steps>
<Note>
**Retenção:** registros de tarefas terminais são mantidos por **7 dias** e então podados automaticamente. Nenhuma configuração necessária.
**Retenção:** registros de tarefas terminais são mantidos por **7 dias** e depois automaticamente podados. Nenhuma configuração necessária.
</Note>
## Como as tarefas se relacionam com outros sistemas
## Como tarefas se relacionam com outros sistemas
<AccordionGroup>
<Accordion title="Tarefas e Fluxo de Tarefas">
[Fluxo de Tarefas](/pt-BR/automation/taskflow) é a camada de orquestração de fluxos acima das tarefas em segundo plano. Um único fluxo pode coordenar várias tarefas ao longo de sua vida útil usando modos de sincronização gerenciados ou espelhados. Use `openclaw tasks` para inspecionar registros individuais de tarefas e `openclaw tasks flow` para inspecionar o fluxo orquestrador.
<Accordion title="Tarefas e Task Flow">
[Task Flow](/pt-BR/automation/taskflow) é a camada de orquestração de fluxos acima das tarefas em segundo plano. Um único fluxo pode coordenar várias tarefas ao longo de sua vida útil usando modos de sincronização gerenciados ou espelhados. Use `openclaw tasks` para inspecionar registros individuais de tarefas e `openclaw tasks flow` para inspecionar o fluxo orquestrador.
Veja [Fluxo de Tarefas](/pt-BR/automation/taskflow) para detalhes.
Consulte [Task Flow](/pt-BR/automation/taskflow) para obter detalhes.
</Accordion>
<Accordion title="Tarefas e cron">
Uma **definição** de trabalho de cron fica em `~/.openclaw/cron/jobs.json`; o estado de execução em runtime fica ao lado dela em `~/.openclaw/cron/jobs-state.json`. **Toda** execução de cron cria um registro de tarefa — tanto em sessão principal quanto isolada. Tarefas de cron em sessão principal usam a política de notificação `silent` por padrão, para que rastreiem sem gerar notificações.
Uma **definição** de trabalho cron fica em `~/.openclaw/cron/jobs.json`; o estado de execução do runtime fica ao lado, em `~/.openclaw/cron/jobs-state.json`. **Toda** execução cron cria um registro de tarefa, tanto de sessão principal quanto isolada. Tarefas cron de sessão principal usam por padrão a política de notificação `silent`, para que sejam rastreadas sem gerar notificações.
Veja [Trabalhos Cron](/pt-BR/automation/cron-jobs).
Consulte [Cron Jobs](/pt-BR/automation/cron-jobs).
</Accordion>
<Accordion title="Tarefas e heartbeat">
Execuções de Heartbeat são turnos de sessão principal — elas não criam registros de tarefa. Quando uma tarefa é concluída, ela pode acionar um despertar de heartbeat para que você veja o resultado rapidamente.
<Accordion title="Tarefas e Heartbeat">
Execuções de Heartbeat são turnos da sessão principal; elas não criam registros de tarefa. Quando uma tarefa é concluída, ela pode acionar um despertar de Heartbeat para que você veja o resultado prontamente.
Veja [Heartbeat](/pt-BR/gateway/heartbeat).
Consulte [Heartbeat](/pt-BR/gateway/heartbeat).
</Accordion>
<Accordion title="Tarefas e sessões">
Uma tarefa pode referenciar uma `childSessionKey` (onde o trabalho é executado) e uma `requesterSessionKey` (quem a iniciou). Sessões são contexto de conversa; tarefas são rastreamento de atividade por cima disso.
Uma tarefa pode referenciar uma `childSessionKey` (onde o trabalho é executado) e uma `requesterSessionKey` (quem a iniciou). Sessões são contexto de conversa; tarefas são rastreamento de atividade sobre isso.
</Accordion>
<Accordion title="Tarefas e execuções de agente">
O `runId` de uma tarefa vincula à execução do agente que realiza o trabalho. Eventos do ciclo de vida do agente (início, fim, erro) atualizam automaticamente o status da tarefa — você não precisa gerenciar o ciclo de vida manualmente.
O `runId` de uma tarefa vincula à execução do agente que faz o trabalho. Eventos de ciclo de vida do agente (início, fim, erro) atualizam automaticamente o status da tarefa; você não precisa gerenciar o ciclo de vida manualmente.
</Accordion>
</AccordionGroup>
## Relacionado
## Relacionados
- [Automação e Tarefas](/pt-BR/automation) — todos os mecanismos de automação em resumo
- [Automação e tarefas](/pt-BR/automation) — todos os mecanismos de automação em uma visão rápida
- [CLI: Tarefas](/pt-BR/cli/tasks) — referência de comandos da CLI
- [Heartbeat](/pt-BR/gateway/heartbeat) — turnos periódicos de sessão principal
- [Tarefas Agendadas](/pt-BR/automation/cron-jobs) — agendamento de trabalho em segundo plano
- [Fluxo de Tarefas](/pt-BR/automation/taskflow) — orquestração de fluxos acima de tarefas
- [Heartbeat](/pt-BR/gateway/heartbeat) — turnos periódicos da sessão principal
- [Tarefas agendadas](/pt-BR/automation/cron-jobs) — agendamento de trabalho em segundo plano
- [Task Flow](/pt-BR/automation/taskflow) — orquestração de fluxos acima de tarefas

173
docs/pt-BR/channels/groups.md
View File

@ -2,37 +2,37 @@
read_when:
- Alterar o comportamento de chats em grupo ou o controle por menções
sidebarTitle: Groups
summary: Comportamento de conversas em grupo entre superfícies (Discord/iMessage/Matrix/Microsoft Teams/Signal/Slack/Telegram/WhatsApp/Zalo)
summary: Comportamento de chats em grupo em diferentes superfícies (Discord/iMessage/Matrix/Microsoft Teams/Signal/Slack/Telegram/WhatsApp/Zalo)
title: Grupos
x-i18n:
generated_at: "2026-04-30T09:36:10Z"
generated_at: "2026-04-30T16:27:38Z"
model: gpt-5.5
provider: openai
source_hash: 743dc1ce1a0e5dc5c6d66091854cdcbb8d2b8f7e06b5c1d13c272142265fc998
source_hash: ed9cba03cf4546a20d473e8095a54858530869b27f8934f2680e8dbe987dbf5e
source_path: channels/groups.md
workflow: 16
---
O OpenClaw trata chats em grupo de forma consistente entre superfícies: Discord, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp, Zalo.
OpenClaw trata conversas em grupo de forma consistente entre as superfícies: Discord, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp, Zalo.
## Introdução para iniciantes (2 minutos)
O OpenClaw "vive" nas suas próprias contas de mensagens. Não há um usuário de bot separado no WhatsApp. Se **você** está em um grupo, o OpenClaw pode ver esse grupo e responder ali.
OpenClaw "vive" nas suas próprias contas de mensagens. Não há um usuário de bot separado no WhatsApp. Se **você** está em um grupo, o OpenClaw consegue ver esse grupo e responder ali.
Comportamento padrão:
- Grupos são restritos (`groupPolicy: "allowlist"`).
- Respostas exigem uma menção, a menos que você desative explicitamente o controle por menção.
- Respostas exigem uma menção, a menos que você desative explicitamente o bloqueio por menção.
- Respostas finais normais em grupos/canais são privadas por padrão. A saída visível na sala usa a ferramenta `message`.
Tradução: remetentes na lista de permissões podem acionar o OpenClaw ao mencioná-lo.
Tradução: remetentes na allowlist podem acionar o OpenClaw mencionando-o.
<Note>
**Resumo**
**TL;DR**
- **Acesso por DM** é controlado por `*.allowFrom`.
- **Acesso a grupos** é controlado por `*.groupPolicy` + listas de permissões (`*.groups`, `*.groupAllowFrom`).
- **Acionamento de respostas** é controlado pelo controle por menção (`requireMention`, `/activation`).
- **Acesso a grupos** é controlado por `*.groupPolicy` + allowlists (`*.groups`, `*.groupAllowFrom`).
- **Acionamento de resposta** é controlado pelo bloqueio por menção (`requireMention`, `/activation`).
</Note>
@ -47,16 +47,16 @@ otherwise -> reply
## Respostas visíveis
Para salas de grupo/canal, o padrão do OpenClaw é `messages.groupChat.visibleReplies: "message_tool"`.
Isso significa que o agente ainda processa o turno e pode atualizar a memória/o estado da sessão, mas sua resposta final normal não é publicada automaticamente de volta na sala. Para falar de forma visível, o agente usa `message(action=send)`.
Para salas de grupo/canal, o OpenClaw usa por padrão `messages.groupChat.visibleReplies: "message_tool"`.
Isso significa que o agente ainda processa o turno e pode atualizar o estado de memória/sessão, mas sua resposta final normal não é publicada automaticamente de volta na sala. Para falar de forma visível, o agente usa `message(action=send)`.
Para chats diretos e qualquer outro turno de origem, use `messages.visibleReplies: "message_tool"` para aplicar o mesmo comportamento global de resposta visível somente via ferramenta. `messages.groupChat.visibleReplies` continua sendo a substituição mais específica para salas de grupo/canal.
Para chats diretos e qualquer outro turno de origem, use `messages.visibleReplies: "message_tool"` para aplicar globalmente o mesmo comportamento de resposta visível apenas por ferramenta. `messages.groupChat.visibleReplies` continua sendo a substituição mais específica para salas de grupo/canal.
Isso substitui o padrão antigo de forçar o modelo a responder `NO_REPLY` para a maioria dos turnos em modo de observação. No modo somente via ferramenta, não fazer nada visível significa simplesmente não chamar a ferramenta de mensagem.
Isso substitui o padrão antigo de forçar o modelo a responder `NO_REPLY` na maioria dos turnos em modo de observação. No modo apenas por ferramenta, não fazer nada visível simplesmente significa não chamar a ferramenta de mensagem.
Indicadores de digitação ainda são enviados enquanto o agente trabalha no modo somente via ferramenta. O modo padrão de digitação em grupo é atualizado de "message" para "instant" nesses turnos porque talvez nunca haja texto normal de mensagem do assistente antes de o agente decidir se deve chamar a ferramenta de mensagem. A configuração explícita do modo de digitação ainda prevalece.
Indicadores de digitação ainda são enviados enquanto o agente trabalha no modo apenas por ferramenta. O modo padrão de digitação em grupo é atualizado de "message" para "instant" nesses turnos, porque talvez nunca haja texto normal de mensagem do assistente antes de o agente decidir se deve chamar a ferramenta de mensagem. A configuração explícita do modo de digitação ainda prevalece.
Para restaurar respostas finais automáticas legadas para salas de grupo/canal:
Para restaurar as respostas finais automáticas legadas para salas de grupo/canal:
```json5
{
@ -68,6 +68,9 @@ Para restaurar respostas finais automáticas legadas para salas de grupo/canal:
}
```
O gateway recarrega a configuração de `messages` automaticamente após o arquivo ser salvo. Reinicie apenas
quando o monitoramento de arquivos ou o recarregamento de configuração estiver desativado na implantação.
Para exigir que a saída visível passe pela ferramenta de mensagem em todos os chats de origem:
```json5
@ -78,43 +81,43 @@ Para exigir que a saída visível passe pela ferramenta de mensagem em todos os
}
```
Comandos de barra nativos (Discord, Telegram e outras superfícies com suporte a comandos nativos) ignoram `visibleReplies: "message_tool"` e sempre respondem de forma visível para que a IU de comando nativa do canal receba a resposta esperada. Isso se aplica apenas a turnos de comando nativo validados; comandos `/...` digitados como texto e turnos comuns de chat ainda seguem o padrão de grupo configurado.
Comandos de barra nativos (Discord, Telegram e outras superfícies com suporte nativo a comandos) ignoram `visibleReplies: "message_tool"` e sempre respondem de forma visível para que a interface de comando nativa do canal receba a resposta esperada. Isso se aplica apenas a turnos de comando nativo validados; comandos `/...` digitados como texto e turnos comuns de chat ainda seguem o padrão de grupo configurado.
## Visibilidade de contexto e listas de permissões
## Visibilidade de contexto e allowlists
Dois controles diferentes estão envolvidos na segurança de grupos:
- **Autorização de acionamento**: quem pode acionar o agente (`groupPolicy`, `groups`, `groupAllowFrom`, listas de permissões específicas do canal).
- **Visibilidade de contexto**: qual contexto suplementar é injetado no modelo (texto de resposta, citações, histórico da thread, metadados encaminhados).
- **Autorização de acionamento**: quem pode acionar o agente (`groupPolicy`, `groups`, `groupAllowFrom`, allowlists específicas do canal).
- **Visibilidade de contexto**: qual contexto suplementar é injetado no modelo (texto de resposta, citações, histórico de thread, metadados encaminhados).
Por padrão, o OpenClaw prioriza o comportamento normal de chat e mantém o contexto majoritariamente como recebido. Isso significa que listas de permissões decidem principalmente quem pode acionar ações, não uma fronteira universal de redação para todo trecho citado ou histórico.
Por padrão, o OpenClaw prioriza o comportamento normal de chat e mantém o contexto quase como foi recebido. Isso significa que allowlists decidem principalmente quem pode acionar ações, não um limite universal de redação para cada trecho citado ou histórico.
<AccordionGroup>
<Accordion title="Current behavior is channel-specific">
<Accordion title="O comportamento atual é específico por canal">
- Alguns canais já aplicam filtragem baseada em remetente para contexto suplementar em caminhos específicos (por exemplo, semeadura de threads do Slack, buscas de resposta/thread do Matrix).
- Outros canais ainda passam contexto de citação/resposta/encaminhamento como recebido.
- Outros canais ainda repassam contexto de citação/resposta/encaminhamento como recebido.
</Accordion>
<Accordion title="Hardening direction (planned)">
<Accordion title="Direção de reforço (planejada)">
- `contextVisibility: "all"` (padrão) mantém o comportamento atual como recebido.
- `contextVisibility: "allowlist"` filtra contexto suplementar para remetentes na lista de permissões.
- `contextVisibility: "allowlist"` filtra contexto suplementar para remetentes na allowlist.
- `contextVisibility: "allowlist_quote"` é `allowlist` mais uma exceção explícita de citação/resposta.
Até que este modelo de reforço seja implementado de forma consistente entre canais, espere diferenças por superfície.
Até que esse modelo de reforço seja implementado de forma consistente entre os canais, espere diferenças por superfície.
</Accordion>
</AccordionGroup>
![Fluxo de mensagem em grupo](/images/groups-flow.svg)
![Fluxo de mensagem de grupo](/images/groups-flow.svg)
Se você quiser...
Se você quer...
| Objetivo | O que configurar |
| -------------------------------------------- | ---------------------------------------------------------- |
| Permitir todos os grupos, mas responder apenas a @menções | `groups: { "*": { requireMention: true } }` |
| Permitir todos os grupos, mas responder apenas em @menções | `groups: { "*": { requireMention: true } }` |
| Desativar todas as respostas em grupo | `groupPolicy: "disabled"` |
| Apenas grupos específicos | `groups: { "<group-id>": { ... } }` (sem chave `"*"` ) |
| Só você pode acionar em grupos | `groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]` |
| Apenas você pode acionar em grupos | `groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]` |
## Chaves de sessão
@ -127,21 +130,21 @@ Se você quiser...
## Padrão: DMs pessoais + grupos públicos (agente único)
Sim — isso funciona bem se o seu tráfego "pessoal" for **DMs** e o seu tráfego "público" for **grupos**.
Sim — isso funciona bem se o seu tráfego "pessoal" são **DMs** e o seu tráfego "público" são **grupos**.
Por quê: no modo de agente único, DMs normalmente chegam na chave de sessão **principal** (`agent:main:main`), enquanto grupos sempre usam chaves de sessão **não principais** (`agent:main:<channel>:group:<id>`). Se você ativar sandboxing com `mode: "non-main"`, essas sessões de grupo serão executadas no backend de sandbox configurado, enquanto sua sessão principal de DM permanece no host. Docker é o backend padrão se você não escolher um.
Por quê: no modo de agente único, DMs normalmente chegam à chave de sessão **principal** (`agent:main:main`), enquanto grupos sempre usam chaves de sessão **não principais** (`agent:main:<channel>:group:<id>`). Se você ativar sandboxing com `mode: "non-main"`, essas sessões de grupo rodam no backend de sandbox configurado enquanto sua sessão principal de DM permanece no host. Docker é o backend padrão se você não escolher um.
Isso dá a você um único "cérebro" de agente (workspace + memória compartilhados), mas duas posturas de execução:
Isso dá a você um "cérebro" de agente (workspace + memória compartilhados), mas duas posturas de execução:
- **DMs**: ferramentas completas (host)
- **Grupos**: sandbox + ferramentas restritas
<Note>
Se você precisa de workspaces/personas realmente separados ("pessoal" e "público" nunca devem se misturar), use um segundo agente + vínculos. Veja [Roteamento Multiagente](/pt-BR/concepts/multi-agent).
Se você precisa de workspaces/personas realmente separados ("pessoal" e "público" nunca devem se misturar), use um segundo agente + bindings. Consulte [Roteamento multiagente](/pt-BR/concepts/multi-agent).
</Note>
<Tabs>
<Tab title="DMs on host, groups sandboxed">
<Tab title="DMs no host, grupos em sandbox">
```json5
{
agents: {
@ -165,8 +168,8 @@ Se você precisa de workspaces/personas realmente separados ("pessoal" e "públi
}
```
</Tab>
<Tab title="Groups see only an allowlisted folder">
Quer que "grupos só possam ver a pasta X" em vez de "sem acesso ao host"? Mantenha `workspaceAccess: "none"` e monte apenas caminhos na lista de permissões no sandbox:
<Tab title="Grupos veem apenas uma pasta na allowlist">
Quer que "grupos só possam ver a pasta X" em vez de "sem acesso ao host"? Mantenha `workspaceAccess: "none"` e monte apenas caminhos na allowlist dentro do sandbox:
```json5
{
@ -199,8 +202,8 @@ Relacionado:
## Rótulos de exibição
- Rótulos da IU usam `displayName` quando disponível, formatado como `<channel>:<token>`.
- `#room` é reservado para salas/canais; chats em grupo usam `g-<slug>` (minúsculas, espaços -> `-`, manter `#@+._-`).
- Rótulos da UI usam `displayName` quando disponível, formatado como `<channel>:<token>`.
- `#room` é reservado para salas/canais; chats em grupo usam `g-<slug>` (minúsculas, espaços -> `-`, mantém `#@+._-`).
## Política de grupo
@ -251,24 +254,25 @@ Controle como mensagens de grupo/sala são tratadas por canal:
}
```
| Política | Comportamento |
| Política | Comportamento |
| ------------- | ------------------------------------------------------------ |
| `"open"` | Grupos ignoram listas de permissões; o controle por menção ainda se aplica. |
| `"disabled"` | Bloqueia completamente todas as mensagens de grupo. |
| `"allowlist"` | Permite apenas grupos/salas que correspondam à lista de permissões configurada. |
| `"open"` | Grupos ignoram allowlists; o bloqueio por menção ainda se aplica. |
| `"disabled"` | Bloqueia totalmente todas as mensagens de grupo. |
| `"allowlist"` | Permite apenas grupos/salas que correspondem à allowlist configurada. |
<AccordionGroup>
<Accordion title="Per-channel notes">
- `groupPolicy` é separado do controle por menção (que exige @menções).
<Accordion title="Observações por canal">
- `groupPolicy` é separado do bloqueio por menção (que exige @menções).
- WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo: use `groupAllowFrom` (fallback: `allowFrom` explícito).
- Aprovações de pareamento de DM (entradas de armazenamento `*-allowFrom`) aplicam-se apenas ao acesso por DM; a autorização de remetente em grupo continua explícita nas listas de permissões de grupo.
- Discord: a lista de permissões usa `channels.discord.guilds.<id>.channels`.
- Slack: a lista de permissões usa `channels.slack.channels`.
- Matrix: a lista de permissões usa `channels.matrix.groups`. Prefira IDs de sala ou aliases; a busca por nome de sala ingressada é de melhor esforço, e nomes não resolvidos são ignorados em runtime. Use `channels.matrix.groupAllowFrom` para restringir remetentes; listas de permissões `users` por sala também são compatíveis.
- DMs em grupo são controladas separadamente (`channels.discord.dm.*`, `channels.slack.dm.*`).
- A lista de permissões do Telegram pode corresponder a IDs de usuário (`"123456789"`, `"telegram:123456789"`, `"tg:123456789"`) ou nomes de usuário (`"@alice"` ou `"alice"`); prefixos não diferenciam maiúsculas de minúsculas.
- O padrão é `groupPolicy: "allowlist"`; se a sua lista de permissões de grupo estiver vazia, mensagens de grupo serão bloqueadas.
- Segurança em runtime: quando um bloco de provedor está completamente ausente (`channels.<provider>` ausente), a política de grupo recorre a um modo fechado por segurança (normalmente `allowlist`) em vez de herdar `channels.defaults.groupPolicy`.
- Signal: `groupAllowFrom` pode corresponder ao id de grupo Signal de entrada ou ao telefone/UUID do remetente.
- Aprovações de pareamento por DM (entradas de armazenamento `*-allowFrom`) aplicam-se apenas ao acesso por DM; a autorização de remetente em grupo permanece explícita para allowlists de grupo.
- Discord: a allowlist usa `channels.discord.guilds.<id>.channels`.
- Slack: a allowlist usa `channels.slack.channels`.
- Matrix: a allowlist usa `channels.matrix.groups`. Prefira IDs de sala ou aliases; a busca de nome de salas ingressadas é de melhor esforço, e nomes não resolvidos são ignorados em tempo de execução. Use `channels.matrix.groupAllowFrom` para restringir remetentes; allowlists `users` por sala também são compatíveis.
- DMs de grupo são controladas separadamente (`channels.discord.dm.*`, `channels.slack.dm.*`).
- A allowlist do Telegram pode corresponder a IDs de usuário (`"123456789"`, `"telegram:123456789"`, `"tg:123456789"`) ou nomes de usuário (`"@alice"` ou `"alice"`); prefixos não diferenciam maiúsculas de minúsculas.
- O padrão é `groupPolicy: "allowlist"`; se a allowlist de grupo estiver vazia, mensagens de grupo serão bloqueadas.
- Segurança em tempo de execução: quando um bloco de provedor está completamente ausente (`channels.<provider>` ausente), a política de grupo recua para um modo fail-closed (normalmente `allowlist`) em vez de herdar `channels.defaults.groupPolicy`.
</Accordion>
</AccordionGroup>
@ -279,17 +283,17 @@ Modelo mental rápido (ordem de avaliação para mensagens de grupo):
<Step title="groupPolicy">
`groupPolicy` (open/disabled/allowlist).
</Step>
<Step title="Group allowlists">
Listas de permissões de grupo (`*.groups`, `*.groupAllowFrom`, lista de permissões específica do canal).
<Step title="Allowlists de grupo">
Allowlists de grupo (`*.groups`, `*.groupAllowFrom`, allowlist específica do canal).
</Step>
<Step title="Mention gating">
Controle por menção (`requireMention`, `/activation`).
<Step title="Bloqueio por menção">
Bloqueio por menção (`requireMention`, `/activation`).
</Step>
</Steps>
## Controle por menção (padrão)
## Bloqueio por menção (padrão)
Mensagens de grupo exigem uma menção, a menos que substituído por grupo. Padrões ficam por subsistema em `*.groups."*"`.
Mensagens de grupo exigem uma menção, a menos que sejam substituídas por grupo. Os padrões ficam por subsistema em `*.groups."*"`.
Responder a uma mensagem do bot conta como uma menção implícita quando o canal oferece suporte a metadados de resposta. Citar uma mensagem do bot também pode contar como uma menção implícita em canais que expõem metadados de citação. Os casos integrados atuais incluem Telegram, WhatsApp, Slack, Discord, Microsoft Teams e ZaloUser.
@ -330,14 +334,15 @@ Responder a uma mensagem do bot conta como uma menção implícita quando o cana
```
<AccordionGroup>
<Accordion title="Observações sobre controle por menção">
- `mentionPatterns` são padrões regex seguros e sem distinção entre maiúsculas e minúsculas; padrões inválidos e formas inseguras com repetição aninhada são ignorados.
- Superfícies que fornecem menções explícitas ainda passam; padrões são um fallback.
<Accordion title="Notas sobre controle por menção">
- `mentionPatterns` são padrões regex seguros e sem diferenciação entre maiúsculas e minúsculas; padrões inválidos e formas inseguras de repetição aninhada são ignorados.
- Superfícies que fornecem menções explícitas ainda passam; os padrões são um fallback.
- Substituição por agente: `agents.list[].groupChat.mentionPatterns` (útil quando vários agentes compartilham um grupo).
- O controle por menção só é aplicado quando a detecção de menção é possível (menções nativas ou `mentionPatterns` configurados).
- O contexto de prompt de chat em grupo carrega a instrução de resposta silenciosa resolvida a cada turno; arquivos do workspace não devem duplicar mecanismos de `NO_REPLY`.
- Grupos em que respostas silenciosas são permitidas tratam turnos limpos vazios ou apenas com raciocínio do modelo como silenciosos, equivalentes a `NO_REPLY`. Chats diretos fazem o mesmo somente quando respostas silenciosas diretas são explicitamente permitidas; caso contrário, respostas vazias continuam sendo turnos de agente com falha.
- Os padrões do Discord ficam em `channels.discord.guilds."*"` (substituíveis por guild/canal).
- O controle por menção só é aplicado quando a detecção de menção é possível (menções nativas ou `mentionPatterns` estão configurados).
- Colocar um grupo ou remetente na lista de permissões não desativa o controle por menção; defina `requireMention` desse grupo como `false` quando todas as mensagens devem acionar.
- O contexto do prompt de chat em grupo carrega a instrução resolvida de resposta silenciosa a cada turno; arquivos do workspace não devem duplicar a mecânica de `NO_REPLY`.
- Grupos em que respostas silenciosas são permitidas tratam turnos do modelo limpos, vazios ou apenas de raciocínio como silenciosos, equivalentes a `NO_REPLY`. Chats diretos fazem o mesmo somente quando respostas silenciosas diretas são explicitamente permitidas; caso contrário, respostas vazias continuam sendo turnos de agente com falha.
- Os padrões do Discord ficam em `channels.discord.guilds."*"` (substituíveis por servidor/canal).
- O contexto de histórico de grupo é encapsulado uniformemente entre canais e é **somente pendente** (mensagens ignoradas devido ao controle por menção); use `messages.groupChat.historyLimit` para o padrão global e `channels.<channel>.historyLimit` (ou `channels.<channel>.accounts.*.historyLimit`) para substituições. Defina `0` para desativar.
</Accordion>
@ -345,19 +350,19 @@ Responder a uma mensagem do bot conta como uma menção implícita quando o cana
## Restrições de ferramentas por grupo/canal (opcional)
Algumas configurações de canal oferecem suporte à restrição de quais ferramentas ficam disponíveis **dentro de um grupo/sala/canal específico**.
Algumas configurações de canal permitem restringir quais ferramentas estão disponíveis **dentro de um grupo/sala/canal específico**.
- `tools`: permite/nega ferramentas para o grupo inteiro.
- `toolsBySender`: substituições por remetente dentro do grupo. Use prefixos de chave explícitos: `id:<senderId>`, `e164:<phone>`, `username:<handle>`, `name:<displayName>` e curinga `"*"`. Chaves legadas sem prefixo ainda são aceitas e correspondidas somente como `id:`.
- `toolsBySender`: substituições por remetente dentro do grupo. Use prefixos de chave explícitos: `id:<senderId>`, `e164:<phone>`, `username:<handle>`, `name:<displayName>` e o curinga `"*"`. Chaves legadas sem prefixo ainda são aceitas e correspondem apenas como `id:`.
Ordem de resolução (a mais específica vence):
<Steps>
<Step title="toolsBySender do grupo">
Correspondência de `toolsBySender` de grupo/canal.
Correspondência de `toolsBySender` do grupo/canal.
</Step>
<Step title="tools do grupo">
`tools` de grupo/canal.
`tools` do grupo/canal.
</Step>
<Step title="toolsBySender padrão">
Correspondência de `toolsBySender` padrão (`"*"`).
@ -388,15 +393,15 @@ Exemplo (Telegram):
```
<Note>
Restrições de ferramentas por grupo/canal são aplicadas além da política global/de agente para ferramentas (negação ainda vence). Alguns canais usam aninhamento diferente para salas/canais (por exemplo, Discord `guilds.*.channels.*`, Slack `channels.*`, Microsoft Teams `teams.*.channels.*`).
Restrições de ferramentas por grupo/canal são aplicadas além da política global/de ferramentas do agente (negação ainda vence). Alguns canais usam aninhamento diferente para salas/canais (por exemplo, Discord `guilds.*.channels.*`, Slack `channels.*`, Microsoft Teams `teams.*.channels.*`).
</Note>
## Listas de permissão de grupos
## Listas de permissões de grupos
Quando `channels.whatsapp.groups`, `channels.telegram.groups` ou `channels.imessage.groups` está configurado, as chaves atuam como uma lista de permissão de grupos. Use `"*"` para permitir todos os grupos enquanto ainda define o comportamento padrão de menção.
Quando `channels.whatsapp.groups`, `channels.telegram.groups` ou `channels.imessage.groups` está configurado, as chaves atuam como uma lista de permissões de grupos. Use `"*"` para permitir todos os grupos enquanto ainda define o comportamento padrão de menção.
<Warning>
Confusão comum: aprovação de pareamento por DM não é o mesmo que autorização de grupo. Para canais que oferecem suporte a pareamento por DM, o armazenamento de pareamento desbloqueia apenas DMs. Comandos de grupo ainda exigem autorização explícita de remetente de grupo a partir de listas de permissão de configuração, como `groupAllowFrom`, ou do fallback de configuração documentado para esse canal.
Confusão comum: a aprovação de pareamento por DM não é o mesmo que autorização de grupo. Para canais que oferecem suporte a pareamento por DM, o armazenamento de pareamento desbloqueia apenas DMs. Comandos de grupo ainda exigem autorização explícita do remetente do grupo por listas de permissões de configuração, como `groupAllowFrom`, ou pelo fallback de configuração documentado para esse canal.
</Warning>
Intenções comuns (copiar/colar):
@ -434,7 +439,7 @@ Intenções comuns (copiar/colar):
}
```
</Tab>
<Tab title="Acionamentos apenas pelo proprietário (WhatsApp)">
<Tab title="Acionamentos somente pelo proprietário (WhatsApp)">
```json5
{
channels: {
@ -451,7 +456,7 @@ Intenções comuns (copiar/colar):
## Ativação (somente proprietário)
Proprietários de grupo podem alternar a ativação por grupo:
Proprietários de grupos podem alternar a ativação por grupo:
- `/activation mention`
- `/activation always`
@ -468,27 +473,27 @@ Payloads de entrada de grupo definem:
- `WasMentioned` (resultado do controle por menção)
- Tópicos de fórum do Telegram também incluem `MessageThreadId` e `IsForum`.
Observações específicas por canal:
Notas específicas por canal:
- BlueBubbles pode, opcionalmente, enriquecer participantes de grupos do macOS sem nome usando o banco de dados local de Contatos antes de preencher `GroupMembers`. Isso fica desativado por padrão e só é executado depois que o controle normal de grupo passa.
- O BlueBubbles pode opcionalmente enriquecer participantes de grupos macOS sem nome a partir do banco de dados local de Contatos antes de preencher `GroupMembers`. Isso fica desativado por padrão e só é executado depois que o controle normal de grupo passa.
O prompt de sistema do agente inclui uma introdução de grupo no primeiro turno de uma nova sessão de grupo. Ele lembra o modelo de responder como um humano, evitar tabelas Markdown, minimizar linhas vazias e seguir o espaçamento normal de chat, além de evitar digitar sequências literais `\n`. Nomes de grupo e rótulos de participantes vindos do canal são renderizados como metadados não confiáveis em bloco cercado, não como instruções de sistema inline.
O prompt de sistema do agente inclui uma introdução de grupo no primeiro turno de uma nova sessão de grupo. Ele lembra o modelo de responder como uma pessoa, evitar tabelas em Markdown, minimizar linhas vazias e seguir o espaçamento normal de chat, além de evitar digitar sequências literais `\n`. Nomes de grupos e rótulos de participantes provenientes do canal são renderizados como metadados não confiáveis em bloco de código, não como instruções de sistema inline.
## Especificidades do iMessage
- Prefira `chat_id:<id>` ao rotear ou adicionar a listas de permissão.
- Liste chats: `imsg chats --limit 20`.
- Respostas de grupo sempre retornam para o mesmo `chat_id`.
- Prefira `chat_id:<id>` ao rotear ou colocar na lista de permissões.
- Listar chats: `imsg chats --limit 20`.
- Respostas em grupo sempre voltam para o mesmo `chat_id`.
## Prompts de sistema do WhatsApp
Consulte [WhatsApp](/pt-BR/channels/whatsapp#system-prompts) para as regras canônicas de prompt de sistema do WhatsApp, incluindo resolução de prompts de grupo e diretos, comportamento de curinga e semântica de substituição por conta.
Consulte [WhatsApp](/pt-BR/channels/whatsapp#system-prompts) para as regras canônicas de prompt de sistema do WhatsApp, incluindo resolução de prompts de grupo e diretos, comportamento de curinga e semântica de substituição de conta.
## Especificidades do WhatsApp
Consulte [Mensagens de grupo](/pt-BR/channels/group-messages) para comportamento exclusivo do WhatsApp (injeção de histórico, detalhes de tratamento de menções).
## Relacionado
## Relacionados
- [Grupos de transmissão](/pt-BR/channels/broadcast-groups)
- [Roteamento de canais](/pt-BR/channels/channel-routing)

153
docs/pt-BR/channels/signal.md
View File

@ -2,35 +2,35 @@
read_when:
- Configurando o suporte ao Signal
- Depuração de envio/recebimento no Signal
summary: Suporte ao Signal via signal-cli (JSON-RPC + SSE), caminhos de configuração e modelo de número
summary: Suporte ao Signal via signal-cli (JSON-RPC + SSE), caminhos de configuração e modelo de números
title: Signal
x-i18n:
generated_at: "2026-04-30T09:37:59Z"
generated_at: "2026-04-30T16:27:36Z"
model: gpt-5.5
provider: openai
source_hash: d450454550a86cbf0e2b7231bb149f78275a756517db1f20d7a07e3d298febee
source_hash: 111b6ebe3bde4e03c7ed432f52d663f0b471f0fc4a4bf835c1ac1972467e0b96
source_path: channels/signal.md
workflow: 16
---
Status: integração externa com CLI. O Gateway se comunica com `signal-cli` por HTTP JSON-RPC + SSE.
Status: integração externa com CLI. Gateway conversa com `signal-cli` por HTTP JSON-RPC + SSE.
## Pré-requisitos
- OpenClaw instalado no seu servidor (fluxo Linux abaixo testado no Ubuntu 24).
- `signal-cli` disponível no host em que o Gateway é executado.
- `signal-cli` disponível no host onde o gateway é executado.
- Um número de telefone que possa receber um SMS de verificação (para o caminho de registro por SMS).
- Acesso ao navegador para o captcha do Signal (`signalcaptchas.org`) durante o registro.
## Configuração rápida (iniciante)
1. Use um **número separado do Signal** para o bot (recomendado).
1. Use um **número Signal separado** para o bot (recomendado).
2. Instale `signal-cli` (Java é necessário se você usar a build JVM).
3. Escolha um caminho de configuração:
- **Caminho A (vinculação por QR):** `signal-cli link -n "OpenClaw"` e escaneie com o Signal.
- **Caminho B (registro por SMS):** registre um número dedicado com captcha + verificação por SMS.
4. Configure o OpenClaw e reinicie o Gateway.
5. Envie uma primeira mensagem direta e aprove o pareamento (`openclaw pairing approve signal <CODE>`).
- **Caminho A (vincular por QR):** `signal-cli link -n "OpenClaw"` e escaneie com o Signal.
- **Caminho B (registrar por SMS):** registre um número dedicado com captcha + verificação por SMS.
4. Configure o OpenClaw e reinicie o gateway.
5. Envie uma primeira DM e aprove o pareamento (`openclaw pairing approve signal <CODE>`).
Configuração mínima:
@ -48,24 +48,24 @@ Configuração mínima:
}
```
Referência de campos:
Referência dos campos:
| Campo | Descrição |
| ----------- | ------------------------------------------------------------- |
| `account` | Número de telefone do bot no formato E.164 (`+15551234567`) |
| Campo | Descrição |
| ----------- | ----------------------------------------------------- |
| `account` | Número de telefone do bot no formato E.164 (`+15551234567`) |
| `cliPath` | Caminho para `signal-cli` (`signal-cli` se estiver no `PATH`) |
| `dmPolicy` | Política de acesso a mensagens diretas (`pairing` recomendado) |
| `allowFrom` | Números de telefone ou valores `uuid:<id>` autorizados a enviar mensagens diretas |
| `dmPolicy` | Política de acesso por DM (`pairing` recomendado) |
| `allowFrom` | Números de telefone ou valores `uuid:<id>` autorizados a enviar DM |
## O que é
- Canal Signal via `signal-cli` (não libsignal embutido).
- Roteamento determinístico: as respostas sempre voltam para o Signal.
- Mensagens diretas compartilham a sessão principal do agente; grupos são isolados (`agent:<agentId>:signal:group:<groupId>`).
- DMs compartilham a sessão principal do agente; grupos são isolados (`agent:<agentId>:signal:group:<groupId>`).
## Escritas de configuração
Por padrão, o Signal tem permissão para gravar atualizações de configuração acionadas por `/config set|unset` (requer `commands.config: true`).
Por padrão, o Signal tem permissão para escrever atualizações de configuração acionadas por `/config set|unset` (requer `commands.config: true`).
Desative com:
@ -77,16 +77,16 @@ Desative com:
## O modelo de número (importante)
- O Gateway se conecta a um **dispositivo Signal** (a conta `signal-cli`).
- O gateway se conecta a um **dispositivo Signal** (a conta `signal-cli`).
- Se você executar o bot na **sua conta pessoal do Signal**, ele ignorará suas próprias mensagens (proteção contra loop).
- Para "eu envio mensagem para o bot e ele responde", use um **número de bot separado**.
- Para "eu mando mensagem para o bot e ele responde", use um **número de bot separado**.
## Caminho de configuração A: vincular conta Signal existente (QR)
1. Instale `signal-cli` (build JVM ou nativa).
2. Vincule uma conta de bot:
- `signal-cli link -n "OpenClaw"` e então escaneie o QR no Signal.
3. Configure o Signal e inicie o Gateway.
- `signal-cli link -n "OpenClaw"` e depois escaneie o QR no Signal.
3. Configure o Signal e inicie o gateway.
Exemplo:
@ -104,7 +104,7 @@ Exemplo:
}
```
Suporte a várias contas: use `channels.signal.accounts` com configuração por conta e `name` opcional. Consulte [`gateway/configuration`](/pt-BR/gateway/config-channels#multi-account-all-channels) para o padrão compartilhado.
Suporte a múltiplas contas: use `channels.signal.accounts` com configuração por conta e `name` opcional. Consulte [`gateway/configuration`](/pt-BR/gateway/config-channels#multi-account-all-channels) para o padrão compartilhado.
## Caminho de configuração B: registrar número de bot dedicado (SMS, Linux)
@ -112,7 +112,7 @@ Use isto quando quiser um número de bot dedicado em vez de vincular uma conta e
1. Obtenha um número que possa receber SMS (ou verificação por voz para linhas fixas).
- Use um número de bot dedicado para evitar conflitos de conta/sessão.
2. Instale `signal-cli` no host do Gateway:
2. Instale `signal-cli` no host do gateway:
```bash
VERSION=$(curl -Ls -o /dev/null -w %{url_effective} https://github.com/AsamK/signal-cli/releases/latest | sed -e 's/^.*\/v//')
@ -123,7 +123,7 @@ signal-cli --version
```
Se você usar a build JVM (`signal-cli-${VERSION}.tar.gz`), instale o JRE 25+ primeiro.
Mantenha `signal-cli` atualizado; o upstream observa que versões antigas podem parar de funcionar à medida que as APIs do servidor Signal mudam.
Mantenha `signal-cli` atualizado; o upstream observa que versões antigas podem parar de funcionar conforme as APIs do servidor Signal mudam.
3. Registre e verifique o número:
@ -143,24 +143,24 @@ signal-cli -a +<BOT_PHONE_NUMBER> register --captcha '<SIGNALCAPTCHA_URL>'
signal-cli -a +<BOT_PHONE_NUMBER> verify <VERIFICATION_CODE>
```
4. Configure o OpenClaw, reinicie o Gateway, verifique o canal:
4. Configure o OpenClaw, reinicie o gateway e verifique o canal:
```bash
# Se você executa o Gateway como um serviço systemd de usuário:
# If you run the gateway as a user systemd service:
systemctl --user restart openclaw-gateway.service
# Depois verifique:
# Then verify:
openclaw doctor
openclaw channels status --probe
```
5. Pareie seu remetente de mensagem direta:
5. Pareie seu remetente de DM:
- Envie qualquer mensagem para o número do bot.
- Aprove o código no servidor: `openclaw pairing approve signal <PAIRING_CODE>`.
- Salve o número do bot como contato no seu telefone para evitar "Contato desconhecido".
<Warning>
Registrar uma conta de número de telefone com `signal-cli` pode desautenticar a sessão principal do app Signal para esse número. Prefira um número de bot dedicado, ou use o modo de vinculação por QR se você precisar manter sua configuração existente do app no telefone.
Registrar uma conta de número de telefone com `signal-cli` pode desautenticar a sessão principal do app Signal para esse número. Prefira um número de bot dedicado ou use o modo de vínculo por QR se precisar manter a configuração existente do app no telefone.
</Warning>
Referências upstream:
@ -171,7 +171,7 @@ Referências upstream:
## Modo daemon externo (httpUrl)
Se você quiser gerenciar `signal-cli` por conta própria (inicializações frias lentas da JVM, inicialização de contêiner ou CPUs compartilhadas), execute o daemon separadamente e aponte o OpenClaw para ele:
Se quiser gerenciar `signal-cli` por conta própria (inicializações frias lentas da JVM, inicialização em contêiner ou CPUs compartilhadas), execute o daemon separadamente e aponte o OpenClaw para ele:
```json5
{
@ -184,55 +184,56 @@ Se você quiser gerenciar `signal-cli` por conta própria (inicializações fria
}
```
Isso pula a geração automática de processo e a espera de inicialização dentro do OpenClaw. Para inicializações lentas ao gerar automaticamente, defina `channels.signal.startupTimeoutMs`.
Isso ignora o auto-spawn e a espera de inicialização dentro do OpenClaw. Para inicializações lentas ao usar auto-spawn, defina `channels.signal.startupTimeoutMs`.
## Controle de acesso (mensagens diretas + grupos)
## Controle de acesso (DMs + grupos)
Mensagens diretas:
DMs:
- Padrão: `channels.signal.dmPolicy = "pairing"`.
- Remetentes desconhecidos recebem um código de pareamento; mensagens são ignoradas até serem aprovadas (códigos expiram após 1 hora).
- Aprove via:
- `openclaw pairing list signal`
- `openclaw pairing approve signal <CODE>`
- Pareamento é a troca de token padrão para mensagens diretas do Signal. Detalhes: [Pareamento](/pt-BR/channels/pairing)
- Pareamento é a troca de token padrão para DMs do Signal. Detalhes: [Pareamento](/pt-BR/channels/pairing)
- Remetentes somente UUID (de `sourceUuid`) são armazenados como `uuid:<id>` em `channels.signal.allowFrom`.
Grupos:
- `channels.signal.groupPolicy = open | allowlist | disabled`.
- `channels.signal.groupAllowFrom` controla quem pode acionar em grupos quando `allowlist` está definido.
- `channels.signal.groups["<group-id>" | "*"]` pode substituir o comportamento do grupo com `requireMention`, `tools` e `toolsBySender`.
- Use `channels.signal.accounts.<id>.groups` para substituições por conta em configurações de várias contas.
- Observação de runtime: se `channels.signal` estiver completamente ausente, o runtime recorre a `groupPolicy="allowlist"` para verificações de grupo (mesmo que `channels.defaults.groupPolicy` esteja definido).
- `channels.signal.groupAllowFrom` controla quais grupos ou remetentes podem acionar respostas de grupo quando `allowlist` está definido; entradas podem ser IDs de grupo do Signal (bruto, `group:<id>` ou `signal:group:<id>`), números de telefone de remetentes, valores `uuid:<id>` ou `*`.
- `channels.signal.groups["<group-id>" | "*"]` pode substituir o comportamento de grupo com `requireMention`, `tools` e `toolsBySender`.
- Use `channels.signal.accounts.<id>.groups` para substituições por conta em configurações de múltiplas contas.
- Colocar um grupo Signal na lista de permissão por meio de `groupAllowFrom` não desativa, por si só, o bloqueio por menção. Uma entrada `channels.signal.groups["<group-id>"]` configurada especificamente processa todas as mensagens de grupo, a menos que `requireMention=true` esteja definido.
- Observação de runtime: se `channels.signal` estiver completamente ausente, o runtime usa `groupPolicy="allowlist"` como fallback para verificações de grupo (mesmo que `channels.defaults.groupPolicy` esteja definido).
## Como funciona (comportamento)
- `signal-cli` é executado como daemon; o Gateway lê eventos via SSE.
- `signal-cli` é executado como daemon; o gateway lê eventos via SSE.
- Mensagens de entrada são normalizadas no envelope de canal compartilhado.
- Respostas sempre roteiam de volta para o mesmo número ou grupo.
- As respostas sempre são roteadas de volta para o mesmo número ou grupo.
## Mídia + limites
- Texto de saída é dividido em partes conforme `channels.signal.textChunkLimit` (padrão 4000).
- Divisão opcional por nova linha: defina `channels.signal.chunkMode="newline"` para dividir em linhas em branco (limites de parágrafo) antes da divisão por comprimento.
- Texto de saída é dividido em partes até `channels.signal.textChunkLimit` (padrão 4000).
- Divisão opcional por nova linha: defina `channels.signal.chunkMode="newline"` para dividir em linhas em branco (limites de parágrafo) antes da divisão por tamanho.
- Anexos compatíveis (base64 obtido de `signal-cli`).
- Anexos de nota de voz usam o nome de arquivo do `signal-cli` como fallback de MIME quando `contentType` está ausente, para que a transcrição de áudio ainda consiga classificar memorandos de voz AAC.
- Limite de mídia padrão: `channels.signal.mediaMaxMb` (padrão 8).
- Use `channels.signal.ignoreAttachments` para pular o download de mídia.
- O contexto de histórico de grupo usa `channels.signal.historyLimit` (ou `channels.signal.accounts.*.historyLimit`), recorrendo a `messages.groupChat.historyLimit`. Defina `0` para desativar (padrão 50).
- Anexos de notas de voz usam o nome de arquivo do `signal-cli` como fallback de MIME quando `contentType` está ausente, para que a transcrição de áudio ainda possa classificar memorandos de voz AAC.
- Limite padrão de mídia: `channels.signal.mediaMaxMb` (padrão 8).
- Use `channels.signal.ignoreAttachments` para ignorar o download de mídia.
- O contexto de histórico de grupo usa `channels.signal.historyLimit` (ou `channels.signal.accounts.*.historyLimit`), com fallback para `messages.groupChat.historyLimit`. Defina `0` para desativar (padrão 50).
## Indicadores de digitação + recibos de leitura
- **Indicadores de digitação**: o OpenClaw envia sinais de digitação via `signal-cli sendTyping` e os atualiza enquanto uma resposta está em execução.
- **Recibos de leitura**: quando `channels.signal.sendReadReceipts` é true, o OpenClaw encaminha recibos de leitura para mensagens diretas permitidas.
- **Indicadores de digitação**: o OpenClaw envia sinais de digitação via `signal-cli sendTyping` e os atualiza enquanto uma resposta está em andamento.
- **Recibos de leitura**: quando `channels.signal.sendReadReceipts` é true, o OpenClaw encaminha recibos de leitura para DMs permitidas.
- Signal-cli não expõe recibos de leitura para grupos.
## Reações (ferramenta de mensagem)
- Use `message action=react` com `channel=signal`.
- Destinos: remetente E.164 ou UUID (use `uuid:<id>` da saída de pareamento; UUID simples também funciona).
- `messageId` é o carimbo de data/hora do Signal para a mensagem à qual você está reagindo.
- Destinos: E.164 do remetente ou UUID (use `uuid:<id>` da saída de pareamento; UUID sem prefixo também funciona).
- `messageId` é o timestamp do Signal para a mensagem à qual você está reagindo.
- Reações em grupo exigem `targetAuthor` ou `targetAuthorUuid`.
Exemplos:
@ -245,16 +246,16 @@ message action=react channel=signal target=signal:group:<groupId> targetAuthor=u
Configuração:
- `channels.signal.actions.reactions`: habilita/desabilita ações de reação (padrão true).
- `channels.signal.actions.reactions`: ativa/desativa ações de reação (padrão true).
- `channels.signal.reactionLevel`: `off | ack | minimal | extensive`.
- `off`/`ack` desabilita reações do agente (a ferramenta de mensagem `react` retornará erro).
- `minimal`/`extensive` habilita reações do agente e define o nível de orientação.
- `off`/`ack` desativa reações do agente (a ferramenta de mensagem `react` retornará erro).
- `minimal`/`extensive` ativa reações do agente e define o nível de orientação.
- Substituições por conta: `channels.signal.accounts.<id>.actions.reactions`, `channels.signal.accounts.<id>.reactionLevel`.
## Destinos de entrega (CLI/Cron)
## Destinos de entrega (CLI/cron)
- Mensagens diretas: `signal:+15551234567` (ou E.164 simples).
- Mensagens diretas por UUID: `uuid:<id>` (ou UUID simples).
- DMs: `signal:+15551234567` (ou E.164 simples).
- DMs por UUID: `uuid:<id>` (ou UUID sem prefixo).
- Grupos: `signal:group:<groupId>`.
- Nomes de usuário: `username:<name>` (se compatível com sua conta Signal).
@ -270,7 +271,7 @@ openclaw doctor
openclaw channels status --probe
```
Depois confirme o estado de pareamento de mensagens diretas se necessário:
Depois confirme o estado de pareamento de DM se necessário:
```bash
openclaw pairing list signal
@ -279,10 +280,10 @@ openclaw pairing list signal
Falhas comuns:
- Daemon acessível, mas sem respostas: verifique as configurações de conta/daemon (`httpUrl`, `account`) e o modo de recebimento.
- Mensagens diretas ignoradas: o remetente está pendente de aprovação de pareamento.
- DMs ignoradas: remetente está com aprovação de pareamento pendente.
- Mensagens de grupo ignoradas: bloqueio por remetente/menção do grupo impede a entrega.
- Erros de validação de configuração após edições: execute `openclaw doctor --fix`.
- Signal ausente dos diagnósticos: confirme `channels.signal.enabled: true`.
- Signal ausente nos diagnósticos: confirme `channels.signal.enabled: true`.
Verificações extras:
@ -296,9 +297,9 @@ Para o fluxo de triagem: [/channels/troubleshooting](/pt-BR/channels/troubleshoo
## Notas de segurança
- `signal-cli` armazena chaves de conta localmente (normalmente `~/.local/share/signal-cli/data/`).
- `signal-cli` armazena chaves da conta localmente (normalmente em `~/.local/share/signal-cli/data/`).
- Faça backup do estado da conta Signal antes de migrar ou reconstruir o servidor.
- Mantenha `channels.signal.dmPolicy: "pairing"` a menos que você queira explicitamente acesso mais amplo a mensagens diretas.
- Mantenha `channels.signal.dmPolicy: "pairing"` a menos que você queira explicitamente acesso mais amplo por DM.
- A verificação por SMS só é necessária para fluxos de registro ou recuperação, mas perder o controle do número/conta pode complicar o novo registro.
## Referência de configuração (Signal)
@ -312,34 +313,34 @@ Opções do provedor:
- `channels.signal.cliPath`: caminho para `signal-cli`.
- `channels.signal.httpUrl`: URL completa do daemon (substitui host/porta).
- `channels.signal.httpHost`, `channels.signal.httpPort`: bind do daemon (padrão 127.0.0.1:8080).
- `channels.signal.autoStart`: inicia automaticamente o daemon (padrão true se `httpUrl` não estiver definido).
- `channels.signal.startupTimeoutMs`: tempo limite de espera de inicialização em ms (limite 120000).
- `channels.signal.autoStart`: inicia o daemon automaticamente (padrão true se `httpUrl` não estiver definido).
- `channels.signal.startupTimeoutMs`: tempo limite de espera pela inicialização em ms (limite 120000).
- `channels.signal.receiveMode`: `on-start | manual`.
- `channels.signal.ignoreAttachments`: ignora downloads de anexos.
- `channels.signal.ignoreStories`: ignora stories do daemon.
- `channels.signal.sendReadReceipts`: encaminha confirmações de leitura.
- `channels.signal.dmPolicy`: `pairing | allowlist | open | disabled` (padrão: pairing).
- `channels.signal.allowFrom`: lista de permissões de DM (E.164 ou `uuid:<id>`). `open` exige `"*"`. O Signal não tem nomes de usuário; use IDs de telefone/UUID.
- `channels.signal.allowFrom`: lista de permissão de DM (E.164 ou `uuid:<id>`). `open` exige `"*"`. O Signal não tem nomes de usuário; use IDs de telefone/UUID.
- `channels.signal.groupPolicy`: `open | allowlist | disabled` (padrão: allowlist).
- `channels.signal.groupAllowFrom`: lista de permissões de remetentes de grupo.
- `channels.signal.groups`: substituições por grupo indexadas pelo ID do grupo do Signal (ou `"*"`). Campos compatíveis: `requireMention`, `tools`, `toolsBySender`.
- `channels.signal.accounts.<id>.groups`: versão por conta de `channels.signal.groups` para configurações com múltiplas contas.
- `channels.signal.historyLimit`: máximo de mensagens de grupo a incluir como contexto (0 desativa).
- `channels.signal.dmHistoryLimit`: limite do histórico de DM em turnos do usuário. Substituições por usuário: `channels.signal.dms["<phone_or_uuid>"].historyLimit`.
- `channels.signal.textChunkLimit`: tamanho do trecho de saída (caracteres).
- `channels.signal.chunkMode`: `length` (padrão) ou `newline` para dividir em linhas em branco (limites de parágrafo) antes da divisão por tamanho.
- `channels.signal.groupAllowFrom`: lista de permissão de grupos; aceita IDs de grupo do Signal (brutos, `group:<id>` ou `signal:group:<id>`), números E.164 do remetente ou valores `uuid:<id>`.
- `channels.signal.groups`: substituições por grupo indexadas por ID de grupo do Signal (ou `"*"`). Campos compatíveis: `requireMention`, `tools`, `toolsBySender`.
- `channels.signal.accounts.<id>.groups`: versão por conta de `channels.signal.groups` para configurações com várias contas.
- `channels.signal.historyLimit`: máximo de mensagens de grupo a incluir como contexto (0 desabilita).
- `channels.signal.dmHistoryLimit`: limite de histórico de DM em turnos do usuário. Substituições por usuário: `channels.signal.dms["<phone_or_uuid>"].historyLimit`.
- `channels.signal.textChunkLimit`: tamanho de fragmento de saída (caracteres).
- `channels.signal.chunkMode`: `length` (padrão) ou `newline` para dividir em linhas em branco (limites de parágrafo) antes da divisão por comprimento.
- `channels.signal.mediaMaxMb`: limite de mídia de entrada/saída (MB).
Opções globais relacionadas:
- `agents.list[].groupChat.mentionPatterns` (o Signal não oferece suporte a menções nativas).
- `agents.list[].groupChat.mentionPatterns` (Signal não é compatível com menções nativas).
- `messages.groupChat.mentionPatterns` (fallback global).
- `messages.responsePrefix`.
## Relacionado
- [Visão geral dos canais](/pt-BR/channels) — todos os canais compatíveis
- [Emparelhamento](/pt-BR/channels/pairing) — autenticação por DM e fluxo de emparelhamento
- [Pareamento](/pt-BR/channels/pairing) — autenticação de DM e fluxo de pareamento
- [Grupos](/pt-BR/channels/groups) — comportamento de chat em grupo e controle por menção
- [Roteamento de canais](/pt-BR/channels/channel-routing) — roteamento de sessões para mensagens
- [Segurança](/pt-BR/gateway/security) — modelo de acesso e hardening
- [Roteamento de canais](/pt-BR/channels/channel-routing) — roteamento de sessão para mensagens
- [Segurança](/pt-BR/gateway/security) — modelo de acesso e endurecimento

395
docs/pt-BR/channels/slack.md
View File

@ -1,27 +1,27 @@
---
read_when:
- Configuração do Slack ou depuração do modo socket/HTTP do Slack
summary: Configuração do Slack e comportamento em tempo de execução (Modo Socket + URLs de solicitação HTTP)
- Configurando o Slack ou depurando o modo socket/HTTP do Slack
summary: Configuração do Slack e comportamento em tempo de execução (Socket Mode + URLs de solicitação HTTP)
title: Slack
x-i18n:
generated_at: "2026-04-30T09:38:07Z"
generated_at: "2026-04-30T16:27:36Z"
model: gpt-5.5
provider: openai
source_hash: 08024bd947ddeb00a1ab3aaa3864cf31817303bbc0523902acdc539fc662e127
source_hash: 55beddb43a6b91c6853dcf053eab713322de4da5beced7c107d73e1c066fded6
source_path: channels/slack.md
workflow: 16
---
Pronto para produção para DMs e canais via integrações de app Slack. O modo padrão é Socket Mode; URLs de solicitação HTTP também são compatíveis.
Pronto para produção para DMs e canais por meio de integrações de app do Slack. O modo padrão é o Socket Mode; HTTP Request URLs também são compatíveis.
<CardGroup cols={3}>
<Card title="Pareamento" icon="link" href="/pt-BR/channels/pairing">
DMs do Slack usam modo de pareamento por padrão.
<Card title="Pairing" icon="link" href="/pt-BR/channels/pairing">
DMs do Slack usam o modo de pareamento por padrão.
</Card>
<Card title="Comandos slash" icon="terminal" href="/pt-BR/tools/slash-commands">
Comportamento de comando nativo e catálogo de comandos.
<Card title="Slash commands" icon="terminal" href="/pt-BR/tools/slash-commands">
Comportamento nativo de comandos e catálogo de comandos.
</Card>
<Card title="Solução de problemas de canais" icon="wrench" href="/pt-BR/channels/troubleshooting">
<Card title="Channel troubleshooting" icon="wrench" href="/pt-BR/channels/troubleshooting">
Diagnósticos entre canais e playbooks de reparo.
</Card>
</CardGroup>
@ -29,19 +29,19 @@ Pronto para produção para DMs e canais via integrações de app Slack. O modo
## Configuração rápida
<Tabs>
<Tab title="Socket Mode (padrão)">
<Tab title="Socket Mode (default)">
<Steps>
<Step title="Crie um novo app Slack">
Nas configurações do app Slack, pressione o botão **[Create New App](https://api.slack.com/apps/new)**:
<Step title="Create a new Slack app">
Nas configurações do app do Slack, pressione o botão **[Create New App](https://api.slack.com/apps/new)**:
- escolha **from a manifest** e selecione um workspace para o seu app
- escolha **from a manifest** e selecione um workspace para seu app
- cole o [manifesto de exemplo](#manifest-and-scope-checklist) abaixo e continue para criar
- gere um **App-Level Token** (`xapp-...`) com `connections:write`
- instale o app e copie o **Bot Token** (`xoxb-...`) exibido
</Step>
<Step title="Configure o OpenClaw">
<Step title="Configure OpenClaw">
Configuração SecretRef recomendada:
@ -64,7 +64,7 @@ openclaw config patch --file ./slack.socket.patch.json5 --dry-run
openclaw config patch --file ./slack.socket.patch.json5
```
Fallback de env (somente conta padrão):
Fallback por env (somente conta padrão):
```bash
SLACK_APP_TOKEN=xapp-...
@ -73,7 +73,7 @@ SLACK_BOT_TOKEN=xoxb-...
</Step>
<Step title="Inicie o gateway">
<Step title="Start gateway">
```bash
openclaw gateway
@ -84,19 +84,19 @@ openclaw gateway
</Tab>
<Tab title="URLs de solicitação HTTP">
<Tab title="HTTP Request URLs">
<Steps>
<Step title="Crie um novo app Slack">
Nas configurações do app Slack, pressione o botão **[Create New App](https://api.slack.com/apps/new)**:
<Step title="Create a new Slack app">
Nas configurações do app do Slack, pressione o botão **[Create New App](https://api.slack.com/apps/new)**:
- escolha **from a manifest** e selecione um workspace para o seu app
- escolha **from a manifest** e selecione um workspace para seu app
- cole o [manifesto de exemplo](#manifest-and-scope-checklist) e atualize as URLs antes de criar
- salve o **Signing Secret** para verificação de solicitações
- salve o **Signing Secret** para verificação de requisições
- instale o app e copie o **Bot Token** (`xoxb-...`) exibido
</Step>
<Step title="Configure o OpenClaw">
<Step title="Configure OpenClaw">
Configuração SecretRef recomendada:
@ -121,14 +121,14 @@ openclaw config patch --file ./slack.http.patch.json5
```
<Note>
Use caminhos de webhook exclusivos para HTTP multiconta
Use caminhos de webhook exclusivos para HTTP com várias contas
Dê a cada conta um `webhookPath` distinto (padrão `/slack/events`) para que os registros não entrem em conflito.
</Note>
</Step>
<Step title="Inicie o gateway">
<Step title="Start gateway">
```bash
openclaw gateway
@ -140,9 +140,9 @@ openclaw gateway
</Tab>
</Tabs>
## Ajuste do transporte de Socket Mode
## Ajuste do transporte do Socket Mode
O OpenClaw define o tempo limite de pong do cliente do Slack SDK como 15 segundos por padrão para Socket Mode. Substitua as configurações de transporte somente quando precisar de ajustes específicos para workspace ou host:
O OpenClaw define o tempo limite de pong do cliente SDK do Slack como 15 segundos por padrão para Socket Mode. Substitua as configurações de transporte somente quando precisar de ajustes específicos de workspace ou host:
```json5
{
@ -159,13 +159,13 @@ O OpenClaw define o tempo limite de pong do cliente do Slack SDK como 15 segundo
}
```
Use isso somente para workspaces em Socket Mode que registram tempos limite de pong/websocket server-ping do Slack ou que rodam em hosts com starvation conhecido do event loop. `clientPingTimeout` é a espera pelo pong depois que o SDK envia um ping de cliente; `serverPingTimeout` é a espera por pings do servidor Slack. Mensagens e eventos do app permanecem estado da aplicação, não sinais de atividade do transporte.
Use isto somente para workspaces em Socket Mode que registrem tempos limite de pong/server-ping de websocket do Slack ou executem em hosts com inanição conhecida do event loop. `clientPingTimeout` é a espera pelo pong depois que o SDK envia um ping do cliente; `serverPingTimeout` é a espera pelos pings do servidor Slack. Mensagens e eventos do app continuam sendo estado da aplicação, não sinais de vivacidade do transporte.
## Checklist de manifesto e escopos
O manifesto base do app Slack é o mesmo para Socket Mode e URLs de solicitação HTTP. Somente o bloco `settings` (e a `url` do comando slash) difere.
O manifesto base do app do Slack é o mesmo para Socket Mode e HTTP Request URLs. Somente o bloco `settings` (e a `url` do comando de barra) difere.
Manifesto base (padrão Socket Mode):
Manifesto base (padrão de Socket Mode):
```json
{
@ -237,7 +237,7 @@ Manifesto base (padrão Socket Mode):
}
```
Para o **modo URLs de solicitação HTTP**, substitua `settings` pela variante HTTP e adicione `url` a cada comando slash. URL pública obrigatória:
Para o modo **HTTP Request URLs**, substitua `settings` pela variante HTTP e adicione `url` a cada comando de barra. URL pública obrigatória:
```json
{
@ -269,20 +269,20 @@ Para o **modo URLs de solicitação HTTP**, substitua `settings` pela variante H
### Configurações adicionais do manifesto
Disponibilize recursos diferentes que estendem os padrões acima.
Exponha recursos diferentes que estendem os padrões acima.
<AccordionGroup>
<Accordion title="Comandos slash nativos opcionais">
<Accordion title="Optional native slash commands">
Vários [comandos slash nativos](#commands-and-slash-behavior) podem ser usados em vez de um único comando configurado, com nuances:
Vários [comandos de barra nativos](#commands-and-slash-behavior) podem ser usados em vez de um único comando configurado, com nuances:
- Use `/agentstatus` em vez de `/status`, pois o comando `/status` é reservado.
- No máximo 25 comandos slash podem ser disponibilizados de uma só vez.
- Use `/agentstatus` em vez de `/status`, porque o comando `/status` é reservado.
- No máximo 25 comandos de barra podem ficar disponíveis de uma vez.
Substitua sua seção `features.slash_commands` existente por um subconjunto dos [comandos disponíveis](/pt-BR/tools/slash-commands#command-list):
<Tabs>
<Tab title="Socket Mode (padrão)">
<Tab title="Socket Mode (default)">
```json
"slash_commands": [
@ -398,8 +398,8 @@ Disponibilize recursos diferentes que estendem os padrões acima.
```
</Tab>
<Tab title="URLs de solicitação HTTP">
Use a mesma lista `slash_commands` do Socket Mode acima e adicione `"url": "https://gateway-host.example.com/slack/events"` a cada entrada. Exemplo:
<Tab title="HTTP Request URLs">
Use a mesma lista de `slash_commands` do Socket Mode acima e adicione `"url": "https://gateway-host.example.com/slack/events"` a cada entrada. Exemplo:
```json
"slash_commands": [
@ -422,13 +422,13 @@ Disponibilize recursos diferentes que estendem os padrões acima.
</Tabs>
</Accordion>
<Accordion title="Escopos de autoria opcionais (operações de escrita)">
Adicione o escopo de bot `chat:write.customize` se quiser que as mensagens de saída usem a identidade do agente ativo (nome de usuário e ícone personalizados) em vez da identidade padrão do app Slack.
<Accordion title="Optional authorship scopes (write operations)">
Adicione o escopo de bot `chat:write.customize` se quiser que as mensagens de saída usem a identidade do agente ativo (nome de usuário e ícone personalizados) em vez da identidade padrão do app do Slack.
Se você usar um ícone de emoji, o Slack espera a sintaxe `:emoji_name:`.
</Accordion>
<Accordion title="Escopos opcionais de token de usuário (operações de leitura)">
<Accordion title="Optional user-token scopes (read operations)">
Se você configurar `channels.slack.userToken`, os escopos típicos de leitura são:
- `channels:history`, `groups:history`, `im:history`, `mpim:history`
@ -437,51 +437,51 @@ Disponibilize recursos diferentes que estendem os padrões acima.
- `reactions:read`
- `pins:read`
- `emoji:read`
- `search:read` (se você depender de leituras de pesquisa do Slack)
- `search:read` (se você depende de leituras de pesquisa do Slack)
</Accordion>
</AccordionGroup>
## Modelo de tokens
- `botToken` + `appToken` são obrigatórios para Socket Mode.
- `botToken` + `appToken` são obrigatórios para o Modo Socket.
- O modo HTTP exige `botToken` + `signingSecret`.
- `botToken`, `appToken`, `signingSecret` e `userToken` aceitam strings de texto simples
- `botToken`, `appToken`, `signingSecret` e `userToken` aceitam strings em texto puro
ou objetos SecretRef.
- Tokens de configuração substituem o fallback de env.
- O fallback de env `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` se aplica somente à conta padrão.
- `userToken` (`xoxp-...`) existe somente na configuração (sem fallback de env) e usa por padrão o comportamento somente leitura (`userTokenReadOnly: true`).
- O fallback de env `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` se aplica apenas à conta padrão.
- `userToken` (`xoxp-...`) é somente por configuração (sem fallback de env) e usa comportamento somente leitura por padrão (`userTokenReadOnly: true`).
Comportamento do snapshot de status:
- A inspeção de conta do Slack rastreia campos `*Source` e `*Status`
por credencial (`botToken`, `appToken`, `signingSecret`, `userToken`).
- A inspeção de conta do Slack rastreia campos `*Source` e `*Status` por credencial
(`botToken`, `appToken`, `signingSecret`, `userToken`).
- O status é `available`, `configured_unavailable` ou `missing`.
- `configured_unavailable` significa que a conta está configurada por SecretRef
ou outra origem de segredo não inline, mas o caminho atual de comando/runtime
ou outra fonte de segredo não inline, mas o caminho atual de comando/runtime
não conseguiu resolver o valor real.
- No modo HTTP, `signingSecretStatus` é incluído; no Socket Mode, o par
obrigatório é `botTokenStatus` + `appTokenStatus`.
- No modo HTTP, `signingSecretStatus` é incluído; no Modo Socket, o
par obrigatório é `botTokenStatus` + `appTokenStatus`.
<Tip>
Para ações/leituras de diretório, o token de usuário pode ser preferido quando configurado. Para escritas, o token de bot continua preferido; escritas com token de usuário só são permitidas quando `userTokenReadOnly: false` e o token de bot está indisponível.
Para ações/leituras de diretório, o token de usuário pode ser preferido quando configurado. Para gravações, o token do bot continua sendo preferido; gravações com token de usuário só são permitidas quando `userTokenReadOnly: false` e o token do bot está indisponível.
</Tip>
## Ações e controles
## Ações e gates
As ações do Slack são controladas por `channels.slack.actions.*`.
Grupos de ações disponíveis nas ferramentas atuais do Slack:
| Grupo | Padrão |
| ---------- | ------- |
| ---------- | ------ |
| messages | habilitado |
| reactions | habilitado |
| pins | habilitado |
| memberInfo | habilitado |
| emojiList | habilitado |
As ações atuais de mensagens do Slack incluem `send`, `upload-file`, `download-file`, `read`, `edit`, `delete`, `pin`, `unpin`, `list-pins`, `member-info` e `emoji-list`. `download-file` aceita IDs de arquivo do Slack mostrados em placeholders de arquivo recebidos e retorna prévias de imagem para imagens ou metadados de arquivo local para outros tipos de arquivo.
As ações atuais de mensagem do Slack incluem `send`, `upload-file`, `download-file`, `read`, `edit`, `delete`, `pin`, `unpin`, `list-pins`, `member-info` e `emoji-list`. `download-file` aceita IDs de arquivo do Slack exibidos em placeholders de arquivo de entrada e retorna prévias de imagem para imagens ou metadados de arquivo local para outros tipos de arquivo.
## Controle de acesso e roteamento
@ -500,41 +500,41 @@ As ações atuais de mensagens do Slack incluem `send`, `upload-file`, `download
- `channels.slack.allowFrom`
- `dm.allowFrom` (legado)
- `dm.groupEnabled` (DMs em grupo padrão false)
- `dm.groupChannels` (allowlist MPIM opcional)
- `dm.groupChannels` (allowlist opcional de MPIM)
Precedência em múltiplas contas:
Precedência de várias contas:
- `channels.slack.accounts.default.allowFrom` se aplica somente à conta `default`.
- `channels.slack.accounts.default.allowFrom` se aplica apenas à conta `default`.
- Contas nomeadas herdam `channels.slack.allowFrom` quando seu próprio `allowFrom` não está definido.
- Contas nomeadas não herdam `channels.slack.accounts.default.allowFrom`.
`channels.slack.dm.policy` e `channels.slack.dm.allowFrom` legados ainda são lidos para compatibilidade. `openclaw doctor --fix` os migra para `dmPolicy` e `allowFrom` quando pode fazer isso sem alterar o acesso.
`channels.slack.dm.policy` e `channels.slack.dm.allowFrom` legados ainda são lidos para compatibilidade. `openclaw doctor --fix` os migra para `dmPolicy` e `allowFrom` quando consegue fazer isso sem alterar o acesso.
O pareamento em DMs usa `openclaw pairing approve slack <code>`.
</Tab>
<Tab title="Política de canal">
<Tab title="Política de canais">
`channels.slack.groupPolicy` controla o tratamento de canais:
- `open`
- `allowlist`
- `disabled`
A allowlist de canais fica em `channels.slack.channels` e **deve usar IDs estáveis de canal do Slack** (por exemplo, `C12345678`) como chaves de configuração.
A allowlist de canais fica em `channels.slack.channels` e **deve usar IDs estáveis de canal do Slack** (por exemplo `C12345678`) como chaves de configuração.
Nota de runtime: se `channels.slack` estiver completamente ausente (configuração somente por env), o runtime faz fallback para `groupPolicy="allowlist"` e registra um aviso (mesmo que `channels.defaults.groupPolicy` esteja definido).
Nota de runtime: se `channels.slack` estiver completamente ausente (configuração somente por env), o runtime usa fallback para `groupPolicy="allowlist"` e registra um aviso (mesmo se `channels.defaults.groupPolicy` estiver definido).
Resolução de nome/ID:
- entradas da allowlist de canais e entradas da allowlist de DM são resolvidas na inicialização quando o acesso por token permite
- entradas de nome de canal não resolvidas são mantidas como configuradas, mas ignoradas por padrão para roteamento
- autorização recebida e roteamento de canais usam ID primeiro por padrão; correspondência direta por nome de usuário/slug exige `channels.slack.dangerouslyAllowNameMatching: true`
- entradas da allowlist de canais e entradas da allowlist de DM são resolvidas na inicialização quando o acesso do token permite
- entradas de nome de canal não resolvidas são mantidas conforme configuradas, mas ignoradas para roteamento por padrão
- autorização de entrada e roteamento de canais usam ID primeiro por padrão; correspondência direta por nome de usuário/slug exige `channels.slack.dangerouslyAllowNameMatching: true`
<Warning>
Chaves baseadas em nome (`#channel-name` ou `channel-name`) **não** correspondem em `groupPolicy: "allowlist"`. A busca de canal usa ID primeiro por padrão, então uma chave baseada em nome nunca será roteada com sucesso e todas as mensagens nesse canal serão bloqueadas silenciosamente. Isso difere de `groupPolicy: "open"`, em que a chave do canal não é exigida para roteamento e uma chave baseada em nome parece funcionar.
Chaves baseadas em nome (`#channel-name` ou `channel-name`) **não** correspondem em `groupPolicy: "allowlist"`. A busca de canal usa ID primeiro por padrão, então uma chave baseada em nome nunca será roteada com sucesso e todas as mensagens nesse canal serão bloqueadas silenciosamente. Isso difere de `groupPolicy: "open"`, em que a chave do canal não é necessária para roteamento e uma chave baseada em nome parece funcionar.
Sempre use o ID do canal do Slack como chave. Para encontrá-lo: clique com o botão direito no canal no Slack → **Copiar link** — o ID (`C...`) aparece no final da URL.
Sempre use o ID do canal do Slack como chave. Para encontrá-lo: clique com o botão direito no canal no Slack → **Copiar link** — o ID (`C...`) aparece no fim da URL.
Correto:
@ -569,16 +569,16 @@ As ações atuais de mensagens do Slack incluem `send`, `upload-file`, `download
</Tab>
<Tab title="Menções e usuários do canal">
<Tab title="Menções e usuários de canal">
Mensagens de canal exigem menção por padrão.
Origens de menção:
Fontes de menção:
- menção explícita ao app (`<@botId>`)
- padrões regex de menção (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`)
- comportamento implícito de thread de resposta ao bot (desabilitado quando `thread.requireExplicitMention` é `true`)
- comportamento implícito de resposta em thread ao bot (desativado quando `thread.requireExplicitMention` é `true`)
Controles por canal (`channels.slack.channels.<id>`; nomes somente via resolução na inicialização ou `dangerouslyAllowNameMatching`):
Controles por canal (`channels.slack.channels.<id>`; nomes somente por resolução na inicialização ou `dangerouslyAllowNameMatching`):
- `requireMention`
- `users` (allowlist)
@ -586,8 +586,10 @@ As ações atuais de mensagens do Slack incluem `send`, `upload-file`, `download
- `skills`
- `systemPrompt`
- `tools`, `toolsBySender`
- formato de chave de `toolsBySender`: `id:`, `e164:`, `username:`, `name:` ou curinga `"*"`
(chaves legadas sem prefixo ainda mapeiam somente para `id:`)
- formato da chave `toolsBySender`: `id:`, `e164:`, `username:`, `name:` ou curinga `"*"`
(chaves legadas sem prefixo ainda mapeiam apenas para `id:`)
`allowBots` é conservador para canais e canais privados: mensagens de sala criadas por bot são aceitas somente quando o bot remetente está explicitamente listado na allowlist `users` dessa sala, ou quando pelo menos um ID explícito de proprietário do Slack vindo de `channels.slack.allowFrom` é atualmente membro da sala. Curingas e entradas de proprietário por nome de exibição não satisfazem a presença do proprietário. A presença do proprietário usa `conversations.members` do Slack; garanta que o app tenha o escopo de leitura correspondente ao tipo de sala (`channels:read` para canais públicos, `groups:read` para canais privados). Se a busca de membros falhar, o OpenClaw descarta a mensagem de sala criada por bot.
</Tab>
</Tabs>
@ -595,14 +597,14 @@ As ações atuais de mensagens do Slack incluem `send`, `upload-file`, `download
## Threads, sessões e tags de resposta
- DMs são roteadas como `direct`; canais como `channel`; MPIMs como `group`.
- Com `session.dmScope=main` padrão, DMs do Slack são consolidadas na sessão principal do agente.
- Com o padrão `session.dmScope=main`, DMs do Slack convergem para a sessão principal do agente.
- Sessões de canal: `agent:<agentId>:slack:channel:<channelId>`.
- Respostas em thread podem criar sufixos de sessão de thread (`:thread:<threadTs>`) quando aplicável.
- O padrão de `channels.slack.thread.historyScope` é `thread`; o padrão de `thread.inheritParent` é `false`.
- `channels.slack.thread.initialHistoryLimit` controla quantas mensagens existentes da thread são buscadas quando uma nova sessão de thread começa (padrão `20`; defina `0` para desabilitar).
- `channels.slack.thread.requireExplicitMention` (padrão `false`): quando `true`, suprime menções implícitas em thread para que o bot responda apenas a menções explícitas `@bot` dentro de threads, mesmo quando o bot já participou da thread. Sem isso, respostas em uma thread com participação do bot ignoram o controle de `requireMention`.
- `channels.slack.thread.initialHistoryLimit` controla quantas mensagens de thread existentes são buscadas quando uma nova sessão de thread começa (padrão `20`; defina `0` para desativar).
- `channels.slack.thread.requireExplicitMention` (padrão `false`): quando `true`, suprime menções implícitas em thread para que o bot responda somente a menções explícitas `@bot` dentro de threads, mesmo quando o bot já participou da thread. Sem isso, respostas em uma thread com participação do bot ignoram o gate de `requireMention`.
Controles de threading de resposta:
Controles de encadeamento de respostas:
- `channels.slack.replyToMode`: `off|first|all|batched` (padrão `off`)
- `channels.slack.replyToModeByChatType`: por `direct|group|channel`
@ -614,32 +616,32 @@ Tags manuais de resposta são compatíveis:
- `[[reply_to:<id>]]`
<Note>
`replyToMode="off"` desabilita **todo** threading de resposta no Slack, incluindo tags explícitas `[[reply_to_*]]`. Isso difere do Telegram, em que tags explícitas ainda são respeitadas no modo `"off"`. Threads do Slack ocultam mensagens do canal, enquanto respostas do Telegram permanecem visíveis inline.
`replyToMode="off"` desativa **todo** encadeamento de respostas no Slack, incluindo tags explícitas `[[reply_to_*]]`. Isso difere do Telegram, em que tags explícitas ainda são respeitadas no modo `"off"`. Threads do Slack ocultam mensagens do canal, enquanto respostas do Telegram permanecem visíveis inline.
</Note>
## Reações de confirmação
`ackReaction` envia um emoji de confirmação enquanto o OpenClaw processa uma mensagem recebida.
`ackReaction` envia um emoji de confirmação enquanto o OpenClaw está processando uma mensagem de entrada.
Ordem de resolução:
- `channels.slack.accounts.<accountId>.ackReaction`
- `channels.slack.ackReaction`
- `messages.ackReaction`
- fallback de emoji de identidade do agente (`agents.list[].identity.emoji`, caso contrário "👀")
- fallback de emoji da identidade do agente (`agents.list[].identity.emoji`, senão "👀")
Notas:
- O Slack espera shortcodes (por exemplo, `"eyes"`).
- Use `""` para desabilitar a reação para a conta do Slack ou globalmente.
- O Slack espera shortcodes (por exemplo `"eyes"`).
- Use `""` para desativar a reação para a conta do Slack ou globalmente.
## Streaming de texto
`channels.slack.streaming` controla o comportamento de prévia ao vivo:
- `off`: desabilita o streaming de prévia ao vivo.
- `partial` (padrão): substitui o texto da prévia pela saída parcial mais recente.
- `block`: acrescenta atualizações de prévia em blocos.
- `off`: desativa streaming de prévia ao vivo.
- `partial` (padrão): substitui o texto de prévia pela saída parcial mais recente.
- `block`: anexa atualizações de prévia em chunks.
- `progress`: mostra texto de status de progresso durante a geração e depois envia o texto final.
- `streaming.preview.toolProgress`: quando a prévia de rascunho está ativa, roteia atualizações de ferramenta/progresso para a mesma mensagem de prévia editada (padrão: `true`). Defina `false` para manter mensagens separadas de ferramenta/progresso.
@ -647,10 +649,10 @@ Notas:
- Uma thread de resposta deve estar disponível para que o streaming de texto nativo e o status de thread do assistente do Slack apareçam. A seleção de thread ainda segue `replyToMode`.
- Raízes de canal e chat em grupo ainda podem usar a prévia de rascunho normal quando o streaming nativo está indisponível.
- DMs de nível superior do Slack permanecem fora de thread por padrão, portanto não mostram a prévia no estilo de thread; use respostas em thread ou `typingReaction` se quiser progresso visível nelas.
- Mídia e payloads não textuais fazem fallback para entrega normal.
- Finais de mídia/erro cancelam edições de prévia pendentes; finais de texto/bloco elegíveis são liberados somente quando podem editar a prévia no lugar.
- Se o streaming falhar no meio da resposta, o OpenClaw faz fallback para entrega normal para os payloads restantes.
- DMs de nível superior do Slack permanecem fora de thread por padrão, então não mostram a prévia em estilo de thread; use respostas em thread ou `typingReaction` se quiser progresso visível ali.
- Payloads de mídia e não texto usam fallback para entrega normal.
- Finais de mídia/erro cancelam edições de prévia pendentes; finais elegíveis de texto/bloco só são descarregados quando conseguem editar a prévia no local.
- Se o streaming falhar no meio da resposta, o OpenClaw usa fallback para entrega normal dos payloads restantes.
Use prévia de rascunho em vez de streaming de texto nativo do Slack:
@ -675,7 +677,7 @@ Chaves legadas:
## Fallback de reação de digitação
`typingReaction` adiciona uma reação temporária à mensagem recebida do Slack enquanto o OpenClaw processa uma resposta, depois a remove quando a execução termina. Isso é mais útil fora de respostas em thread, que usam um indicador de status padrão "está digitando...".
`typingReaction` adiciona uma reação temporária à mensagem de entrada do Slack enquanto o OpenClaw está processando uma resposta, e a remove quando a execução termina. Isso é mais útil fora de respostas em thread, que usam um indicador de status padrão "is typing...".
Ordem de resolução:
@ -684,43 +686,43 @@ Ordem de resolução:
Notas:
- O Slack espera shortcodes (por exemplo, `"hourglass_flowing_sand"`).
- A reação é best-effort e a limpeza é tentada automaticamente depois que o caminho de resposta ou falha é concluído.
- O Slack espera shortcodes (por exemplo `"hourglass_flowing_sand"`).
- A reação é best-effort, e a limpeza é tentada automaticamente depois que o caminho de resposta ou falha é concluído.
## Mídia, fragmentação e entrega
## Mídia, chunking e entrega
<AccordionGroup>
<Accordion title="Anexos recebidos">
Anexos de arquivo do Slack são baixados de URLs privadas hospedadas pelo Slack (fluxo de solicitação autenticada por token) e gravados no armazenamento de mídia quando a busca é bem-sucedida e os limites de tamanho permitem. Placeholders de arquivo incluem o `fileId` do Slack para que agentes possam buscar o arquivo original com `download-file`.
<Accordion title="Anexos de entrada">
Anexos de arquivo do Slack são baixados de URLs privadas hospedadas pelo Slack (fluxo de solicitação autenticada por token) e gravados no armazenamento de mídia quando a busca tem sucesso e os limites de tamanho permitem. Placeholders de arquivo incluem o `fileId` do Slack para que agentes possam buscar o arquivo original com `download-file`.
Downloads usam timeouts limitados de ociosidade e total. Se a recuperação de arquivo do Slack travar ou falhar, o OpenClaw continua processando a mensagem e faz fallback para o placeholder de arquivo.
Downloads usam timeouts limitados de inatividade e total. Se a recuperação do arquivo do Slack travar ou falhar, o OpenClaw continua processando a mensagem e usa fallback para o placeholder de arquivo.
O limite de tamanho de entrada em runtime tem padrão `20MB`, a menos que seja substituído por `channels.slack.mediaMaxMb`.
O limite de tamanho de entrada em runtime é `20MB` por padrão, salvo se substituído por `channels.slack.mediaMaxMb`.
</Accordion>
<Accordion title="Texto e arquivos enviados">
- fragmentos de texto usam `channels.slack.textChunkLimit` (padrão 4000)
- `channels.slack.chunkMode="newline"` habilita divisão priorizando parágrafos
- envios de arquivo usam APIs de upload do Slack e podem incluir respostas em thread (`thread_ts`)
- o limite de mídia enviada segue `channels.slack.mediaMaxMb` quando configurado; caso contrário, envios de canal usam padrões por tipo MIME do pipeline de mídia
<Accordion title="Texto e arquivos de saída">
- blocos de texto usam `channels.slack.textChunkLimit` (padrão 4000)
- `channels.slack.chunkMode="newline"` habilita a divisão priorizando parágrafos
- envios de arquivos usam as APIs de upload do Slack e podem incluir respostas em thread (`thread_ts`)
- o limite de mídia de saída segue `channels.slack.mediaMaxMb` quando configurado; caso contrário, envios de canal usam os padrões por tipo MIME do pipeline de mídia
</Accordion>
<Accordion title="Destinos de entrega">
Destinos explícitos preferidos:
<Accordion title="Alvos de entrega">
Alvos explícitos preferidos:
- `user:<id>` para DMs
- `channel:<id>` para canais
DMs do Slack são abertas via APIs de conversa do Slack ao enviar para destinos de usuário.
DMs do Slack são abertas por meio das APIs de conversa do Slack ao enviar para alvos de usuário.
</Accordion>
</AccordionGroup>
## Comandos e comportamento de slash
Comandos slash aparecem no Slack como um único comando configurado ou múltiplos comandos nativos. Configure `channels.slack.slashCommand` para alterar os padrões de comando:
Comandos slash aparecem no Slack como um único comando configurado ou como vários comandos nativos. Configure `channels.slack.slashCommand` para alterar os padrões de comando:
- `enabled: false`
- `name: "openclaw"`
@ -731,30 +733,30 @@ Comandos slash aparecem no Slack como um único comando configurado ou múltiplo
/openclaw /help
```
Comandos nativos exigem [configurações adicionais de manifesto](#additional-manifest-settings) no seu app Slack e são habilitados com `channels.slack.commands.native: true` ou `commands.native: true` nas configurações globais.
Comandos nativos exigem [configurações adicionais de manifesto](#additional-manifest-settings) no seu app Slack e, em vez disso, são habilitados com `channels.slack.commands.native: true` ou `commands.native: true` em configurações globais.
- O modo automático de comandos nativos fica **desativado** para Slack, portanto `commands.native: "auto"` não habilita comandos nativos do Slack.
- O modo automático de comando nativo está **desativado** para Slack, portanto `commands.native: "auto"` não habilita comandos nativos do Slack.
```txt
/help
```
Menus de argumentos nativos usam uma estratégia de renderização adaptativa que mostra um modal de confirmação antes de despachar um valor de opção selecionado:
Menus de argumentos nativos usam uma estratégia de renderização adaptativa que mostra um modal de confirmação antes de despachar o valor de uma opção selecionada:
- até 5 opções: blocos de botões
- até 5 opções: blocos de botão
- 6-100 opções: menu de seleção estático
- mais de 100 opções: seleção externa com filtragem assíncrona de opções quando handlers de opções de interatividade estiverem disponíveis
- limites do Slack excedidos: valores de opção codificados usam botões como fallback
- mais de 100 opções: seleção externa com filtragem assíncrona de opções quando handlers de opções de interatividade estão disponíveis
- limites do Slack excedidos: valores de opção codificados voltam a usar botões
```txt
/think
```
Sessões slash usam chaves isoladas como `agent:<agentId>:slack:slash:<userId>` e ainda encaminham execuções de comandos para a sessão de conversa de destino usando `CommandTargetSessionKey`.
Sessões slash usam chaves isoladas como `agent:<agentId>:slack:slash:<userId>` e ainda roteiam execuções de comandos para a sessão da conversa de destino usando `CommandTargetSessionKey`.
## Respostas interativas
Slack pode renderizar controles de resposta interativa criados por agentes, mas esse recurso fica desativado por padrão.
O Slack pode renderizar controles de resposta interativa criados pelo agente, mas esse recurso é desabilitado por padrão.
Habilite globalmente:
@ -770,7 +772,7 @@ Habilite globalmente:
}
```
Ou habilite apenas para uma conta Slack:
Ou habilite somente para uma conta Slack:
```json5
{
@ -793,39 +795,39 @@ Quando habilitado, agentes podem emitir diretivas de resposta exclusivas do Slac
- `[[slack_buttons: Approve:approve, Reject:reject]]`
- `[[slack_select: Choose a target | Canary:canary, Production:production]]`
Essas diretivas são compiladas para Slack Block Kit e encaminham cliques ou seleções de volta pelo caminho existente de eventos de interação do Slack.
Essas diretivas são compiladas para Slack Block Kit e roteiam cliques ou seleções de volta pelo caminho de evento de interação do Slack existente.
Observações:
- Esta é uma UI específica do Slack. Outros canais não traduzem diretivas do Slack Block Kit para seus próprios sistemas de botões.
- Os valores de callback interativo são tokens opacos gerados pelo OpenClaw, não valores brutos criados por agentes.
- Se os blocos interativos gerados excederem os limites do Slack Block Kit, o OpenClaw volta para a resposta de texto original em vez de enviar uma carga de blocos inválida.
- Esta é uma interface de usuário específica do Slack. Outros canais não traduzem diretivas do Slack Block Kit para seus próprios sistemas de botões.
- Os valores de callback interativo são tokens opacos gerados pelo OpenClaw, não valores brutos criados pelo agente.
- Se blocos interativos gerados excederem os limites do Slack Block Kit, o OpenClaw volta para a resposta de texto original em vez de enviar uma carga de blocos inválida.
## Aprovações de execução no Slack
## Aprovações de exec no Slack
Slack pode atuar como um cliente de aprovação nativo com botões e interações interativas, em vez de usar a UI da Web ou o terminal como fallback.
O Slack pode atuar como um cliente de aprovação nativo com botões interativos e interações, em vez de voltar para a interface Web ou o terminal.
- Aprovações de execução usam `channels.slack.execApprovals.*` para roteamento nativo por DM/canal.
- Aprovações de Plugin ainda podem ser resolvidas pela mesma superfície de botões nativa do Slack quando a solicitação já chega ao Slack e o tipo de id da aprovação é `plugin:`.
- A autorização de aprovadores ainda é aplicada: somente usuários identificados como aprovadores podem aprovar ou negar solicitações pelo Slack.
- Aprovações de exec usam `channels.slack.execApprovals.*` para roteamento nativo de DM/canal.
- Aprovações de Plugin ainda podem ser resolvidas pela mesma superfície de botões nativa do Slack quando a solicitação já chega ao Slack e o tipo do id de aprovação é `plugin:`.
- A autorização do aprovador ainda é aplicada: somente usuários identificados como aprovadores podem aprovar ou negar solicitações pelo Slack.
Isso usa a mesma superfície compartilhada de botões de aprovação de outros canais. Quando `interactivity` está habilitada nas configurações do seu app Slack, prompts de aprovação são renderizados como botões do Block Kit diretamente na conversa.
Quando esses botões estão presentes, eles são a UX principal de aprovação; o OpenClaw
Isso usa a mesma superfície compartilhada de botões de aprovação que outros canais. Quando `interactivity` está habilitado nas configurações do seu app Slack, prompts de aprovação são renderizados como botões do Block Kit diretamente na conversa.
Quando esses botões estão presentes, eles são a UX de aprovação principal; o OpenClaw
só deve incluir um comando manual `/approve` quando o resultado da ferramenta disser que aprovações
por chat estão indisponíveis ou que a aprovação manual é o único caminho.
por chat estão indisponíveis ou a aprovação manual é o único caminho.
Caminho de configuração:
- `channels.slack.execApprovals.enabled`
- `channels.slack.execApprovals.approvers` (opcional; usa `commands.ownerAllowFrom` como fallback quando possível)
- `channels.slack.execApprovals.approvers` (opcional; recai para `commands.ownerAllowFrom` quando possível)
- `channels.slack.execApprovals.target` (`dm` | `channel` | `both`, padrão: `dm`)
- `agentFilter`, `sessionFilter`
Slack habilita automaticamente aprovações de execução nativas quando `enabled` não está definido ou é `"auto"` e pelo menos um
O Slack habilita automaticamente aprovações de exec nativas quando `enabled` não está definido ou é `"auto"` e pelo menos um
aprovador é resolvido. Defina `enabled: false` para desabilitar explicitamente o Slack como cliente de aprovação nativo.
Defina `enabled: true` para forçar aprovações nativas quando aprovadores forem resolvidos.
Comportamento padrão sem configuração explícita de aprovação de execução do Slack:
Comportamento padrão sem configuração explícita de aprovação de exec do Slack:
```json5
{
@ -835,7 +837,7 @@ Comportamento padrão sem configuração explícita de aprovação de execução
}
```
A configuração explícita nativa do Slack só é necessária quando você quer substituir aprovadores, adicionar filtros ou
Configuração explícita nativa do Slack só é necessária quando você quer substituir aprovadores, adicionar filtros ou
aderir à entrega no chat de origem:
```json5
@ -852,25 +854,25 @@ aderir à entrega no chat de origem:
}
```
O encaminhamento compartilhado de `approvals.exec` é separado. Use-o somente quando prompts de aprovação de execução também precisarem
ser roteados para outros chats ou destinos explícitos fora de banda. O encaminhamento compartilhado de `approvals.plugin` também é
O encaminhamento compartilhado de `approvals.exec` é separado. Use-o somente quando prompts de aprovação de exec também precisarem
rotear para outros chats ou alvos explícitos fora de banda. O encaminhamento compartilhado de `approvals.plugin` também é
separado; botões nativos do Slack ainda podem resolver aprovações de Plugin quando essas solicitações já chegam
ao Slack.
`/approve` no mesmo chat também funciona em canais Slack e DMs que já oferecem suporte a comandos. Consulte [Aprovações de execução](/pt-BR/tools/exec-approvals) para ver o modelo completo de encaminhamento de aprovações.
`/approve` no mesmo chat também funciona em canais e DMs do Slack que já oferecem suporte a comandos. Consulte [Aprovações de exec](/pt-BR/tools/exec-approvals) para ver o modelo completo de encaminhamento de aprovação.
## Eventos e comportamento operacional
- Edições/exclusões de mensagens são mapeadas para eventos do sistema.
- Transmissões de threads (respostas de thread com "Also send to channel") são processadas como mensagens normais de usuários.
- Transmissões de thread ("Também enviar para o canal" em respostas de thread) são processadas como mensagens de usuário normais.
- Eventos de adicionar/remover reação são mapeados para eventos do sistema.
- Eventos de entrada/saída de membros, canal criado/renomeado e adição/remoção de pin são mapeados para eventos do sistema.
- Eventos de entrada/saída de membro, canal criado/renomeado e adicionar/remover fixação são mapeados para eventos do sistema.
- `channel_id_changed` pode migrar chaves de configuração de canal quando `configWrites` está habilitado.
- Metadados de tópico/propósito do canal são tratados como contexto não confiável e podem ser injetados no contexto de roteamento.
- O iniciador da thread e a semeadura inicial do contexto de histórico da thread são filtrados por allowlists de remetentes configuradas quando aplicável.
- Ações de bloco e interações modais emitem eventos de sistema estruturados `Slack interaction: ...` com campos de carga avançados:
- ações de bloco: valores selecionados, rótulos, valores de seletores e metadados `workflow_*`
- eventos modais `view_submission` e `view_closed` com metadados de canal roteado e entradas de formulário
- O contexto inicial de início de thread e histórico inicial da thread é filtrado por allowlists de remetentes configuradas quando aplicável.
- Ações de bloco e interações modais emitem eventos de sistema estruturados `Slack interaction: ...` com campos de payload ricos:
- ações de bloco: valores selecionados, rótulos, valores de seletor e metadados `workflow_*`
- eventos modais `view_submission` e `view_closed` com metadados de canal roteados e entradas de formulário
## Referência de configuração
@ -879,12 +881,12 @@ Referência principal: [Referência de configuração - Slack](/pt-BR/gateway/co
<Accordion title="Campos Slack de alto sinal">
- modo/autenticação: `mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*`
- acesso por DM: `dm.enabled`, `dmPolicy`, `allowFrom` (legado: `dm.policy`, `dm.allowFrom`), `dm.groupEnabled`, `dm.groupChannels`
- alternância de compatibilidade: `dangerouslyAllowNameMatching` (quebra-vidro; mantenha desativado salvo necessidade)
- acesso a canais: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention`
- threads/histórico: `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit`
- acesso a DM: `dm.enabled`, `dmPolicy`, `allowFrom` (legado: `dm.policy`, `dm.allowFrom`), `dm.groupEnabled`, `dm.groupChannels`
- alternância de compatibilidade: `dangerouslyAllowNameMatching` (quebra-vidro; mantenha desativado, a menos que seja necessário)
- acesso a canal: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention`
- encadeamento/histórico: `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit`
- entrega: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `streaming.nativeTransport`, `streaming.preview.toolProgress`
- ops/recursos: `configWrites`, `commands.native`, `slashCommand.*`, `actions.*`, `userToken`, `userTokenReadOnly`
- operações/recursos: `configWrites`, `commands.native`, `slashCommand.*`, `actions.*`, `userToken`, `userTokenReadOnly`
</Accordion>
@ -892,10 +894,10 @@ Referência principal: [Referência de configuração - Slack](/pt-BR/gateway/co
<AccordionGroup>
<Accordion title="Sem respostas em canais">
Verifique, nesta ordem:
Verifique, na ordem:
- `groupPolicy`
- allowlist de canais (`channels.slack.channels`) — **as chaves devem ser IDs de canal** (`C12345678`), não nomes (`#channel-name`). Chaves baseadas em nome falham silenciosamente com `groupPolicy: "allowlist"` porque o roteamento de canais é ID-first por padrão. Para encontrar um ID: clique com o botão direito no canal no Slack → **Copy link** — o valor `C...` no fim da URL é o ID do canal.
- allowlist de canais (`channels.slack.channels`) — **as chaves devem ser IDs de canal** (`C12345678`), não nomes (`#channel-name`). Chaves baseadas em nome falham silenciosamente sob `groupPolicy: "allowlist"` porque o roteamento de canal prioriza IDs por padrão. Para encontrar um ID: clique com o botão direito no canal no Slack → **Copiar link** — o valor `C...` no fim da URL é o ID do canal.
- `requireMention`
- allowlist `users` por canal
@ -913,10 +915,10 @@ openclaw doctor
Verifique:
- `channels.slack.dm.enabled`
- `channels.slack.dmPolicy` (ou legado `channels.slack.dm.policy`)
- `channels.slack.dmPolicy` (ou o legado `channels.slack.dm.policy`)
- aprovações de pareamento / entradas de allowlist
- eventos de DM do Slack Assistant: logs detalhados mencionando `drop message_changed`
geralmente significam que o Slack enviou um evento editado de thread do Assistant sem um
geralmente significam que o Slack enviou um evento de thread do Assistant editado sem um
remetente humano recuperável nos metadados da mensagem
```bash
@ -926,30 +928,31 @@ openclaw pairing list slack
</Accordion>
<Accordion title="Socket mode não conecta">
Valide tokens de bot + app e a habilitação de Socket Mode nas configurações do app Slack.
Valide os tokens de bot + app e a habilitação do Socket Mode nas configurações do app Slack.
Se `openclaw channels status --probe --json` mostrar `botTokenStatus` ou
`appTokenStatus: "configured_unavailable"`, a conta Slack está
configurada, mas o runtime atual não conseguiu resolver o valor apoiado por SecretRef.
configurada, mas o runtime atual não conseguiu resolver o valor
baseado em SecretRef.
</Accordion>
<Accordion title="Modo HTTP não recebe eventos">
Valide:
- segredo de assinatura
- caminho do Webhook
- URLs de solicitação do Slack (Events + Interactivity + Slash Commands)
- signing secret
- caminho de Webhook
- URLs de solicitação do Slack (eventos + interatividade + comandos slash)
- `webhookPath` único por conta HTTP
Se `signingSecretStatus: "configured_unavailable"` aparecer em snapshots de conta,
a conta HTTP está configurada, mas o runtime atual não conseguiu
resolver o segredo de assinatura apoiado por SecretRef.
resolver o signing secret baseado em SecretRef.
</Accordion>
<Accordion title="Comandos nativos/slash não disparam">
Verifique o que você pretendia:
Verifique se você pretendia usar:
- modo de comando nativo (`channels.slack.commands.native: true`) com comandos slash correspondentes registrados no Slack
- ou modo de comando slash único (`channels.slack.slashCommand.enabled: true`)
@ -959,90 +962,90 @@ openclaw pairing list slack
</Accordion>
</AccordionGroup>
## Referência de visão para anexos
## Referência de visão de anexos
Slack pode anexar mídia baixada ao turno do agente quando downloads de arquivos do Slack são bem-sucedidos e limites de tamanho permitem. Arquivos de imagem podem passar pelo caminho de compreensão de mídia ou diretamente para um modelo de resposta com capacidade de visão; outros arquivos são mantidos como contexto de arquivo baixável em vez de serem tratados como entrada de imagem.
O Slack pode anexar mídia baixada ao turno do agente quando downloads de arquivos do Slack são bem-sucedidos e os limites de tamanho permitem. Arquivos de imagem podem passar pelo caminho de entendimento de mídia ou diretamente para um modelo de resposta com capacidade de visão; outros arquivos são mantidos como contexto de arquivo baixável em vez de serem tratados como entrada de imagem.
### Tipos de mídia compatíveis
| Tipo de mídia | Origem | Comportamento atual | Observações |
| ------------------------------ | -------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| Imagens JPEG / PNG / GIF / WebP | URL de arquivo Slack | Baixadas e anexadas ao turno para processamento com capacidade de visão | Limite por arquivo: `channels.slack.mediaMaxMb` (padrão 20 MB) |
| Imagens JPEG / PNG / GIF / WebP | URL de arquivo Slack | Baixadas e anexadas ao turno para tratamento com capacidade de visão | Limite por arquivo: `channels.slack.mediaMaxMb` (padrão 20 MB) |
| Arquivos PDF | URL de arquivo Slack | Baixados e expostos como contexto de arquivo para ferramentas como `download-file` ou `pdf` | A entrada do Slack não converte PDFs automaticamente em entrada de visão de imagem |
| Outros arquivos | URL de arquivo Slack | Baixados quando possível e expostos como contexto de arquivo | Arquivos binários não são tratados como entrada de imagem |
| Respostas em thread | Arquivos do iniciador da thread | Arquivos da mensagem raiz podem ser hidratados como contexto quando a resposta não tem mídia direta | Iniciadores somente com arquivo usam um placeholder de anexo |
| Mensagens multi-imagem | Vários arquivos Slack | Cada arquivo é avaliado independentemente | O processamento do Slack é limitado a oito arquivos por mensagem |
| Outros arquivos | URL de arquivo Slack | Baixados quando possível e expostos como contexto de arquivo | Arquivos binários não são tratados como entrada de imagem |
| Respostas em thread | Arquivos do início da thread | Arquivos da mensagem raiz podem ser hidratados como contexto quando a resposta não tem mídia direta | Inícios somente com arquivo usam um placeholder de anexo |
| Mensagens com várias imagens | Vários arquivos Slack | Cada arquivo é avaliado independentemente | O processamento do Slack é limitado a oito arquivos por mensagem |
### Pipeline de entrada
Quando uma mensagem Slack com anexos de arquivo chega:
Quando uma mensagem do Slack com anexos de arquivo chega:
1. O OpenClaw baixa o arquivo a partir da URL privada do Slack usando o token de bot (`xoxb-...`).
1. O OpenClaw baixa o arquivo da URL privada do Slack usando o token do bot (`xoxb-...`).
2. O arquivo é gravado no armazenamento de mídia em caso de sucesso.
3. Caminhos de mídia baixada e tipos de conteúdo são adicionados ao contexto de entrada.
4. Caminhos de modelo/ferramenta com capacidade de imagem podem usar anexos de imagem desse contexto.
5. Arquivos que não são imagem permanecem disponíveis como metadados de arquivo ou referências de mídia para ferramentas que podem lidar com eles.
3. Os caminhos de mídia baixada e os tipos de conteúdo são adicionados ao contexto de entrada.
4. Caminhos de modelo/ferramenta com suporte a imagens podem usar anexos de imagem desse contexto.
5. Arquivos que não são imagens permanecem disponíveis como metadados de arquivo ou referências de mídia para ferramentas capazes de lidar com eles.
### Herança de anexos da raiz da thread
Quando uma mensagem chega em uma thread (tem um pai `thread_ts`):
- Se a própria resposta não tiver mídia direta e a mensagem raiz incluída tiver arquivos, Slack pode hidratar os arquivos raiz como contexto de iniciador de thread.
- Se a própria resposta não tiver mídia direta e a mensagem raiz incluída tiver arquivos, o Slack pode hidratar os arquivos da raiz como contexto inicial da thread.
- Anexos diretos da resposta têm precedência sobre anexos da mensagem raiz.
- Uma mensagem raiz que tem apenas arquivos e nenhum texto é representada com um placeholder de anexo para que o fallback ainda possa incluir seus arquivos.
### Processamento de vários anexos
### Tratamento de múltiplos anexos
Quando uma única mensagem Slack contém vários anexos de arquivo:
Quando uma única mensagem do Slack contém vários anexos de arquivo:
- Cada anexo é processado de forma independente pelo pipeline de mídia.
- As referências de mídia baixadas são agregadas ao contexto da mensagem.
- A ordem de processamento segue a ordem dos arquivos do Slack na carga útil do evento.
- Cada anexo é processado independentemente pelo pipeline de mídia.
- As referências de mídia baixada são agregadas ao contexto da mensagem.
- A ordem de processamento segue a ordem dos arquivos do Slack no payload do evento.
- Uma falha no download de um anexo não bloqueia os outros.
### Limites de tamanho, download e modelo
- **Limite de tamanho**: padrão de 20 MB por arquivo. Configurável via `channels.slack.mediaMaxMb`.
- **Falhas de download**: arquivos que o Slack não consegue servir, URLs expiradas, arquivos inacessíveis, arquivos acima do tamanho permitido e respostas HTML de autenticação/login do Slack são ignorados em vez de serem relatados como formatos incompatíveis.
- **Modelo de visão**: a análise de imagens usa o modelo de resposta ativo quando ele é compatível com visão, ou o modelo de imagem configurado em `agents.defaults.imageModel`.
- **Falhas de download**: arquivos que o Slack não consegue servir, URLs expiradas, arquivos inacessíveis, arquivos grandes demais e respostas HTML de autenticação/login do Slack são ignorados em vez de serem reportados como formatos sem suporte.
- **Modelo de visão**: a análise de imagens usa o modelo de resposta ativo quando ele oferece suporte a visão, ou o modelo de imagem configurado em `agents.defaults.imageModel`.
### Limites conhecidos
| Cenário | Comportamento atual | Solução alternativa |
| -------------------------------------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- |
| URL de arquivo do Slack expirada | Arquivo ignorado; nenhum erro exibido | Reenvie o arquivo no Slack |
| Modelo de visão não configurado | Anexos de imagem são armazenados como referências de mídia, mas não analisados como imagens | Configure `agents.defaults.imageModel` ou use um modelo de resposta compatível com visão |
| Imagens muito grandes (> 20 MB por padrão) | Ignoradas pelo limite de tamanho | Aumente `channels.slack.mediaMaxMb` se o Slack permitir |
| Anexos encaminhados/compartilhados | Texto e mídia de imagem/arquivo hospedados no Slack são tratados com melhor esforço | Compartilhe novamente diretamente na conversa do OpenClaw |
| Anexos PDF | Armazenados como contexto de arquivo/mídia, não roteados automaticamente pela visão de imagem | Use `download-file` para metadados do arquivo ou a ferramenta `pdf` para análise de PDF |
| Cenário | Comportamento atual | Solução alternativa |
| ---------------------------------------- | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| URL de arquivo do Slack expirada | Arquivo ignorado; nenhum erro exibido | Reenvie o arquivo no Slack |
| Modelo de visão não configurado | Anexos de imagem são armazenados como referências de mídia, mas não analisados como imagens | Configure `agents.defaults.imageModel` ou use um modelo de resposta com suporte a visão |
| Imagens muito grandes (> 20 MB por padrão) | Ignoradas conforme o limite de tamanho | Aumente `channels.slack.mediaMaxMb` se o Slack permitir |
| Anexos encaminhados/compartilhados | Texto e mídia de imagem/arquivo hospedada no Slack são tratados em melhor esforço | Compartilhe novamente diretamente na thread do OpenClaw |
| Anexos PDF | Armazenados como contexto de arquivo/mídia, não roteados automaticamente pela visão de imagem | Use `download-file` para metadados de arquivo ou a ferramenta `pdf` para análise de PDF |
### Documentação relacionada
- [Pipeline de compreensão de mídia](/pt-BR/nodes/media-understanding)
- [Ferramenta PDF](/pt-BR/tools/pdf)
- Épico: [#51349](https://github.com/openclaw/openclaw/issues/51349) — habilitação de visão para anexos do Slack
- [Ferramenta de PDF](/pt-BR/tools/pdf)
- Épico: [#51349](https://github.com/openclaw/openclaw/issues/51349) — ativação de visão para anexos do Slack
- Testes de regressão: [#51353](https://github.com/openclaw/openclaw/issues/51353)
- Verificação ao vivo: [#51354](https://github.com/openclaw/openclaw/issues/51354)
## Relacionado
## Relacionados
<CardGroup cols={2}>
<Card title="Emparelhamento" icon="link" href="/pt-BR/channels/pairing">
Emparelhe um usuário do Slack ao Gateway.
<Card title="Pairing" icon="link" href="/pt-BR/channels/pairing">
Emparelhe um usuário do Slack ao gateway.
</Card>
<Card title="Grupos" icon="users" href="/pt-BR/channels/groups">
Comportamento de canais e DMs de grupo.
<Card title="Groups" icon="users" href="/pt-BR/channels/groups">
Comportamento de canais e DMs em grupo.
</Card>
<Card title="Roteamento de canais" icon="route" href="/pt-BR/channels/channel-routing">
Encaminhe mensagens recebidas para agentes.
<Card title="Channel routing" icon="route" href="/pt-BR/channels/channel-routing">
Roteie mensagens de entrada para agentes.
</Card>
<Card title="Segurança" icon="shield" href="/pt-BR/gateway/security">
Modelo de ameaças e endurecimento.
<Card title="Security" icon="shield" href="/pt-BR/gateway/security">
Modelo de ameaças e hardening.
</Card>
<Card title="Configuração" icon="sliders" href="/pt-BR/gateway/configuration">
<Card title="Configuration" icon="sliders" href="/pt-BR/gateway/configuration">
Layout e precedência da configuração.
</Card>
<Card title="Comandos de barra" icon="terminal" href="/pt-BR/tools/slash-commands">
<Card title="Slash commands" icon="terminal" href="/pt-BR/tools/slash-commands">
Catálogo e comportamento de comandos.
</Card>
</CardGroup>

365
docs/pt-BR/channels/telegram.md
View File

@ -1,28 +1,28 @@
---
read_when:
- Trabalhando em recursos do Telegram ou webhooks
summary: Status de suporte, recursos e configuração do bot do Telegram
- Trabalhando em funcionalidades do Telegram ou Webhooks
summary: Status de suporte, capacidades e configuração do bot do Telegram
title: Telegram
x-i18n:
generated_at: "2026-04-30T09:38:20Z"
generated_at: "2026-04-30T16:27:30Z"
model: gpt-5.5
provider: openai
source_hash: 1ffc0c1a6bb94fbab81ede0f08b0e3a165f06c599d4d06d4b9e70c8ba41121f7
source_hash: d18ca6c7ab39d7d34848c562857661501d8364329f6e5a266213aa23846047dd
source_path: channels/telegram.md
workflow: 16
---
Pronto para produção para DMs e grupos de bot via grammY. Polling longo é o modo padrão; o modo Webhook é opcional.
Pronto para produção para DMs e grupos de bots via grammY. Long polling é o modo padrão; o modo webhook é opcional.
<CardGroup cols={3}>
<Card title="Pareamento" icon="link" href="/pt-BR/channels/pairing">
A política padrão de DM para Telegram é pareamento.
A política padrão de DM para Telegram é o pareamento.
</Card>
<Card title="Solução de problemas de canais" icon="wrench" href="/pt-BR/channels/troubleshooting">
Diagnósticos entre canais e manuais de reparo.
<Card title="Solução de problemas de canal" icon="wrench" href="/pt-BR/channels/troubleshooting">
Diagnósticos entre canais e playbooks de reparo.
</Card>
<Card title="Configuração do Gateway" icon="settings" href="/pt-BR/gateway/configuration">
Padrões e exemplos completos de configuração de canais.
Padrões e exemplos completos de configuração de canal.
</Card>
</CardGroup>
@ -51,12 +51,12 @@ Pronto para produção para DMs e grupos de bot via grammY. Polling longo é o m
}
```
Alternativa por env: `TELEGRAM_BOT_TOKEN=...` (somente conta padrão).
Telegram **não** usa `openclaw channels login telegram`; configure o token em config/env e então inicie o gateway.
Fallback de env: `TELEGRAM_BOT_TOKEN=...` (somente conta padrão).
Telegram **não** usa `openclaw channels login telegram`; configure o token na configuração/env e então inicie o Gateway.
</Step>
<Step title="Inicie o gateway e aprove a primeira DM">
<Step title="Inicie o Gateway e aprove a primeira DM">
```bash
openclaw gateway
@ -69,19 +69,19 @@ openclaw pairing approve telegram <CODE>
</Step>
<Step title="Adicione o bot a um grupo">
Adicione o bot ao seu grupo, então defina `channels.telegram.groups` e `groupPolicy` para corresponder ao seu modelo de acesso.
Adicione o bot ao seu grupo e então defina `channels.telegram.groups` e `groupPolicy` para corresponder ao seu modelo de acesso.
</Step>
</Steps>
<Note>
A ordem de resolução de tokens considera a conta. Na prática, valores de configuração prevalecem sobre a alternativa por env, e `TELEGRAM_BOT_TOKEN` se aplica somente à conta padrão.
A ordem de resolução do token considera a conta. Na prática, valores de configuração têm precedência sobre o fallback de env, e `TELEGRAM_BOT_TOKEN` se aplica somente à conta padrão.
</Note>
## Configurações no lado do Telegram
## Configurações do lado do Telegram
<AccordionGroup>
<Accordion title="Modo de privacidade e visibilidade em grupos">
Bots do Telegram usam **Modo de Privacidade** por padrão, o que limita quais mensagens de grupo eles recebem.
Bots do Telegram usam **Privacy Mode** por padrão, o que limita quais mensagens de grupo eles recebem.
Se o bot precisar ver todas as mensagens do grupo, você pode:
@ -93,7 +93,7 @@ A ordem de resolução de tokens considera a conta. Na prática, valores de conf
</Accordion>
<Accordion title="Permissões de grupo">
O status de administrador é controlado nas configurações do grupo no Telegram.
O status de administrador é controlado nas configurações do grupo do Telegram.
Bots administradores recebem todas as mensagens do grupo, o que é útil para comportamento de grupo sempre ativo.
@ -114,35 +114,35 @@ A ordem de resolução de tokens considera a conta. Na prática, valores de conf
`channels.telegram.dmPolicy` controla o acesso por mensagem direta:
- `pairing` (padrão)
- `allowlist` (requer pelo menos um ID de remetente em `allowFrom`)
- `open` (requer que `allowFrom` inclua `"*"`)
- `allowlist` (exige pelo menos um ID de remetente em `allowFrom`)
- `open` (exige que `allowFrom` inclua `"*"`)
- `disabled`
`dmPolicy: "open"` com `allowFrom: ["*"]` permite que qualquer conta do Telegram que encontre ou adivinhe o nome de usuário do bot comande o bot. Use isso somente para bots intencionalmente públicos com ferramentas rigidamente restritas; bots de dono único devem usar `allowlist` com IDs de usuário numéricos.
`dmPolicy: "open"` com `allowFrom: ["*"]` permite que qualquer conta do Telegram que encontre ou adivinhe o nome de usuário do bot comande o bot. Use apenas para bots intencionalmente públicos com ferramentas fortemente restritas; bots de um único proprietário devem usar `allowlist` com IDs numéricos de usuário.
`channels.telegram.allowFrom` aceita IDs de usuário numéricos do Telegram. Prefixos `telegram:` / `tg:` são aceitos e normalizados.
Em configurações com várias contas, um `channels.telegram.allowFrom` restritivo de nível superior é tratado como uma fronteira de segurança: entradas `allowFrom: ["*"]` no nível da conta não tornam essa conta pública, a menos que a allowlist efetiva da conta ainda contenha um curinga explícito após a mesclagem.
`channels.telegram.allowFrom` aceita IDs numéricos de usuário do Telegram. Prefixos `telegram:` / `tg:` são aceitos e normalizados.
Em configurações com múltiplas contas, um `channels.telegram.allowFrom` restritivo no nível superior é tratado como uma fronteira de segurança: entradas `allowFrom: ["*"]` no nível da conta não tornam essa conta pública, a menos que a allowlist efetiva da conta ainda contenha um curinga explícito após a mesclagem.
`dmPolicy: "allowlist"` com `allowFrom` vazio bloqueia todas as DMs e é rejeitado pela validação de configuração.
A configuração pede somente IDs de usuário numéricos.
Se você atualizou e sua configuração contém entradas de allowlist `@username`, execute `openclaw doctor --fix` para resolvê-las (melhor esforço; requer um token de bot do Telegram).
Se você dependia anteriormente de arquivos de allowlist do armazenamento de pareamento, `openclaw doctor --fix` pode recuperar entradas para `channels.telegram.allowFrom` em fluxos de allowlist (por exemplo, quando `dmPolicy: "allowlist"` ainda não tem IDs explícitos).
A configuração pede apenas IDs numéricos de usuário.
Se você atualizou e sua configuração contém entradas de allowlist `@username`, execute `openclaw doctor --fix` para resolvê-las (melhor esforço; exige um token de bot do Telegram).
Se antes você dependia de arquivos de allowlist do armazenamento de pareamento, `openclaw doctor --fix` pode recuperar entradas para `channels.telegram.allowFrom` em fluxos de allowlist (por exemplo, quando `dmPolicy: "allowlist"` ainda não tem IDs explícitos).
Para bots de dono único, prefira `dmPolicy: "allowlist"` com IDs numéricos explícitos em `allowFrom` para manter a política de acesso durável na configuração (em vez de depender de aprovações de pareamento anteriores).
Para bots de um único proprietário, prefira `dmPolicy: "allowlist"` com IDs numéricos explícitos em `allowFrom` para manter a política de acesso durável na configuração (em vez de depender de aprovações de pareamento anteriores).
Confusão comum: a aprovação de pareamento por DM não significa "este remetente está autorizado em todos os lugares".
O pareamento concede acesso por DM. Se ainda não existir dono de comandos, o primeiro pareamento aprovado também define `commands.ownerAllowFrom` para que comandos exclusivos do dono e aprovações de exec tenham uma conta de operador explícita.
A autorização de remetentes em grupos ainda vem de allowlists explícitas na configuração.
Se você quer "estou autorizado uma vez e tanto DMs quanto comandos de grupo funcionam", coloque seu ID de usuário numérico do Telegram em `channels.telegram.allowFrom`; para comandos exclusivos do dono, confirme que `commands.ownerAllowFrom` contém `telegram:<your user id>`.
Confusão comum: aprovação de pareamento por DM não significa "este remetente está autorizado em todos os lugares".
O pareamento concede acesso por DM. Se ainda não existir proprietário de comando, o primeiro pareamento aprovado também define `commands.ownerAllowFrom` para que comandos exclusivos do proprietário e aprovações de exec tenham uma conta de operador explícita.
A autorização de remetente em grupos ainda vem de allowlists explícitas na configuração.
Se você quer "estou autorizado uma vez e tanto DMs quanto comandos de grupo funcionam", coloque seu ID numérico de usuário do Telegram em `channels.telegram.allowFrom`; para comandos exclusivos do proprietário, garanta que `commands.ownerAllowFrom` contenha `telegram:<your user id>`.
### Encontrando seu ID de usuário do Telegram
Mais seguro (sem bot de terceiros):
1. Envie uma DM para o seu bot.
1. Envie uma DM ao seu bot.
2. Execute `openclaw logs --follow`.
3. Leia `from.id`.
Método oficial da API de Bot:
Método oficial da Bot API:
```bash
curl "https://api.telegram.org/bot<bot_token>/getUpdates"
@ -153,12 +153,12 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
</Tab>
<Tab title="Política de grupo e allowlists">
Dois controles se aplicam em conjunto:
Dois controles se aplicam juntos:
1. **Quais grupos são permitidos** (`channels.telegram.groups`)
- sem configuração `groups`:
- sem configuração de `groups`:
- com `groupPolicy: "open"`: qualquer grupo pode passar nas verificações de ID de grupo
- com `groupPolicy: "allowlist"` (padrão): grupos são bloqueados até que você adicione entradas em `groups` (ou `"*"`)
- com `groupPolicy: "allowlist"` (padrão): grupos ficam bloqueados até você adicionar entradas em `groups` (ou `"*"`)
- `groups` configurado: atua como allowlist (IDs explícitos ou `"*"`)
2. **Quais remetentes são permitidos em grupos** (`channels.telegram.groupPolicy`)
@ -166,15 +166,15 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
- `allowlist` (padrão)
- `disabled`
`groupAllowFrom` é usado para filtragem de remetentes em grupos. Se não definido, Telegram recorre a `allowFrom`.
Entradas de `groupAllowFrom` devem ser IDs de usuário numéricos do Telegram (prefixos `telegram:` / `tg:` são normalizados).
Não coloque IDs de chat de grupos ou supergrupos do Telegram em `groupAllowFrom`. IDs de chat negativos pertencem a `channels.telegram.groups`.
`groupAllowFrom` é usado para filtragem de remetente em grupos. Se não estiver definido, Telegram usa `allowFrom` como fallback.
Entradas `groupAllowFrom` devem ser IDs numéricos de usuário do Telegram (prefixos `telegram:` / `tg:` são normalizados).
Não coloque IDs de chat de grupo ou supergrupo do Telegram em `groupAllowFrom`. IDs de chat negativos pertencem a `channels.telegram.groups`.
Entradas não numéricas são ignoradas para autorização de remetente.
Fronteira de segurança (`2026.2.25+`): autenticação de remetente de grupo **não** herda aprovações do armazenamento de pareamento de DMs.
O pareamento permanece exclusivo para DMs. Para grupos, defina `groupAllowFrom` ou `allowFrom` por grupo/tópico.
Se `groupAllowFrom` não for definido, Telegram recorre ao `allowFrom` da configuração, não ao armazenamento de pareamento.
Padrão prático para bots de dono único: defina seu ID de usuário em `channels.telegram.allowFrom`, deixe `groupAllowFrom` não definido e permita os grupos de destino em `channels.telegram.groups`.
Observação de runtime: se `channels.telegram` estiver completamente ausente, o runtime usa como padrão fechamento seguro `groupPolicy="allowlist"`, a menos que `channels.defaults.groupPolicy` seja definido explicitamente.
Fronteira de segurança (`2026.2.25+`): autenticação de remetente em grupo **não** herda aprovações do armazenamento de pareamento de DM.
O pareamento permanece somente para DM. Para grupos, defina `groupAllowFrom` ou `allowFrom` por grupo/por tópico.
Se `groupAllowFrom` não estiver definido, Telegram usa como fallback o `allowFrom` da configuração, não o armazenamento de pareamento.
Padrão prático para bots de um único proprietário: defina seu ID de usuário em `channels.telegram.allowFrom`, deixe `groupAllowFrom` indefinido e permita os grupos de destino em `channels.telegram.groups`.
Observação de runtime: se `channels.telegram` estiver completamente ausente, o runtime usa como padrão o fail-closed `groupPolicy="allowlist"`, a menos que `channels.defaults.groupPolicy` seja definido explicitamente.
Exemplo: permitir qualquer membro em um grupo específico:
@ -193,7 +193,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
}
```
Exemplo: permitir somente usuários específicos dentro de um grupo específico:
Exemplo: permitir apenas usuários específicos dentro de um grupo específico:
```json5
{
@ -213,9 +213,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
<Warning>
Erro comum: `groupAllowFrom` não é uma allowlist de grupos do Telegram.
- Coloque IDs de chat negativos de grupos ou supergrupos do Telegram, como `-1001234567890`, em `channels.telegram.groups`.
- Coloque IDs negativos de chat de grupo ou supergrupo do Telegram, como `-1001234567890`, em `channels.telegram.groups`.
- Coloque IDs de usuário do Telegram, como `8734062810`, em `groupAllowFrom` quando quiser limitar quais pessoas dentro de um grupo permitido podem acionar o bot.
- Use `groupAllowFrom: ["*"]` somente quando quiser que qualquer membro de um grupo permitido possa falar com o bot.
- Use `groupAllowFrom: ["*"]` apenas quando quiser que qualquer membro de um grupo permitido possa falar com o bot.
</Warning>
@ -231,12 +231,12 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
- `agents.list[].groupChat.mentionPatterns`
- `messages.groupChat.mentionPatterns`
Alternâncias de comando em nível de sessão:
Alternâncias de comando no nível da sessão:
- `/activation always`
- `/activation mention`
Elas atualizam somente o estado da sessão. Use a configuração para persistência.
Elas atualizam apenas o estado da sessão. Use configuração para persistência.
Exemplo de configuração persistente:
@ -256,27 +256,27 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
- encaminhe uma mensagem do grupo para `@userinfobot` / `@getidsbot`
- ou leia `chat.id` em `openclaw logs --follow`
- ou inspecione `getUpdates` da API de Bot
- ou inspecione `getUpdates` da Bot API
</Tab>
</Tabs>
## Comportamento em runtime
- Telegram é de propriedade do processo do gateway.
- Telegram pertence ao processo do Gateway.
- O roteamento é determinístico: entradas do Telegram respondem de volta no Telegram (o modelo não escolhe canais).
- Mensagens recebidas são normalizadas no envelope de canal compartilhado com metadados de resposta e placeholders de mídia.
- Sessões de grupo são isoladas por ID de grupo. Tópicos de fórum acrescentam `:topic:<threadId>` para manter tópicos isolados.
- Mensagens recebidas são normalizadas para o envelope de canal compartilhado com metadados de resposta e placeholders de mídia.
- Sessões de grupo são isoladas por ID de grupo. Tópicos de fórum acrescentam `:topic:<threadId>` para manter os tópicos isolados.
- Mensagens de DM podem carregar `message_thread_id`; OpenClaw as roteia com chaves de sessão cientes de thread e preserva o ID da thread para respostas.
- Polling longo usa o runner do grammY com sequenciamento por chat/por thread. A concorrência geral do coletor do runner usa `agents.defaults.maxConcurrent`.
- Polling longo é protegido dentro de cada processo de gateway para que apenas um poller ativo possa usar um token de bot por vez. Se você ainda vir conflitos `getUpdates` 409, outro gateway do OpenClaw, script ou poller externo provavelmente está usando o mesmo token.
- Reinicializações do watchdog de polling longo disparam após 120 segundos sem liveness concluído de `getUpdates` por padrão. Aumente `channels.telegram.pollingStallThresholdMs` somente se seu deployment ainda vir reinicializações falsas por travamento de polling durante trabalhos de longa duração. O valor é em milissegundos e é permitido de `30000` a `600000`; substituições por conta são compatíveis.
- A API de Bot do Telegram não tem suporte a confirmação de leitura (`sendReadReceipts` não se aplica).
- Long polling usa grammY runner com sequenciamento por chat/por thread. A concorrência geral do runner sink usa `agents.defaults.maxConcurrent`.
- Long polling é protegido dentro de cada processo do Gateway para que apenas um poller ativo possa usar um token de bot por vez. Se você ainda vê conflitos `getUpdates` 409, outro Gateway OpenClaw, script ou poller externo provavelmente está usando o mesmo token.
- Reinicializações do watchdog de long polling são acionadas após 120 segundos sem liveness concluída de `getUpdates` por padrão. Aumente `channels.telegram.pollingStallThresholdMs` apenas se sua implantação ainda tiver reinicializações falsas por polling-stall durante trabalho de longa duração. O valor é em milissegundos e é permitido de `30000` a `600000`; substituições por conta são compatíveis.
- Telegram Bot API não tem suporte a confirmação de leitura (`sendReadReceipts` não se aplica).
## Referência de recursos
<AccordionGroup>
<Accordion title="Prévia de transmissão ao vivo (edições de mensagem)">
<Accordion title="Prévia de stream ao vivo (edições de mensagem)">
OpenClaw pode transmitir respostas parciais em tempo real:
- chats diretos: mensagem de prévia + `editMessageText`
@ -286,10 +286,10 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
- `channels.telegram.streaming` é `off | partial | block | progress` (padrão: `partial`)
- `progress` mapeia para `partial` no Telegram (compatibilidade com nomenclatura entre canais)
- `streaming.preview.toolProgress` controla se atualizações de ferramenta/progresso reutilizam a mesma mensagem de prévia editada (padrão: `true` quando streaming de prévia está ativo)
- `streaming.preview.toolProgress` controla se atualizações de ferramenta/progresso reutilizam a mesma mensagem de prévia editada (padrão: `true` quando o streaming de prévia está ativo)
- `channels.telegram.streamMode` legado e valores booleanos de `streaming` são detectados; execute `openclaw doctor --fix` para migrá-los para `channels.telegram.streaming.mode`
Atualizações de prévia de progresso de ferramenta são as linhas curtas "Trabalhando..." exibidas enquanto ferramentas são executadas, por exemplo execução de comandos, leituras de arquivos, atualizações de planejamento ou resumos de patches. Telegram as mantém ativadas por padrão para corresponder ao comportamento lançado do OpenClaw de `v2026.4.22` e posteriores. Para manter a prévia editada para o texto da resposta, mas ocultar linhas de progresso de ferramenta, defina:
Atualizações de prévia de progresso de ferramenta são as linhas curtas "Trabalhando..." mostradas enquanto ferramentas são executadas, por exemplo execução de comandos, leituras de arquivos, atualizações de planejamento ou resumos de patches. Telegram as mantém ativadas por padrão para corresponder ao comportamento lançado do OpenClaw a partir de `v2026.4.22`. Para manter a prévia editada para o texto da resposta, mas ocultar linhas de progresso de ferramenta, defina:
```json
{
@ -306,30 +306,28 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
}
```
Use `streaming.mode: "off"` somente quando quiser entrega apenas final: edições de prévia do Telegram são desativadas, e conversas genéricas de ferramenta/progresso são suprimidas em vez de serem enviadas como mensagens autônomas "Trabalhando...". Solicitações de aprovação, payloads de mídia e erros ainda são roteados pela entrega final normal. Use `streaming.preview.toolProgress: false` quando você quiser apenas manter edições de prévia da resposta enquanto oculta as linhas de status de progresso de ferramenta.
Use `streaming.mode: "off"` apenas quando quiser entrega somente final: edições de prévia do Telegram são desativadas e conversas genéricas de ferramenta/progresso são suprimidas em vez de serem enviadas como mensagens "Trabalhando..." independentes. Prompts de aprovação, payloads de mídia e erros ainda são roteados pela entrega final normal. Use `streaming.preview.toolProgress: false` quando quiser manter apenas edições de prévia de resposta enquanto oculta as linhas de status de progresso de ferramenta.
Para respostas somente texto:
- prévias curtas em MD/grupo/tópico: o OpenClaw mantém a mesma mensagem de prévia e realiza uma edição final no local
- prévias curtas de DM/grupo/tópico: o OpenClaw mantém a mesma mensagem de prévia e faz uma edição final no local
- prévias com mais de cerca de um minuto: o OpenClaw envia a resposta concluída como uma nova mensagem final e depois limpa a prévia, para que o carimbo de data/hora visível do Telegram reflita o horário de conclusão em vez do horário de criação da prévia
Para respostas complexas (por exemplo, cargas úteis de mídia), o OpenClaw recorre à entrega final normal e depois limpa a mensagem de prévia.
Para respostas complexas (por exemplo, cargas de mídia), o OpenClaw volta para a entrega final normal e depois limpa a mensagem de prévia.
O streaming de prévia é separado do streaming de blocos. Quando o streaming de blocos é habilitado explicitamente para o Telegram, o OpenClaw ignora o stream de prévia para evitar streaming duplo.
O streaming de prévia é separado do streaming de bloco. Quando o streaming de bloco está explicitamente habilitado para Telegram, o OpenClaw ignora o stream de prévia para evitar streaming duplicado.
Se o transporte nativo de rascunho estiver indisponível/for rejeitado, o OpenClaw recorre automaticamente a `sendMessage` + `editMessageText`.
Stream de raciocínio somente no Telegram:
Stream de raciocínio exclusivo do Telegram:
- `/reasoning stream` envia o raciocínio para a prévia ao vivo durante a geração
- a resposta final é enviada sem texto de raciocínio
- a resposta final é enviada sem o texto de raciocínio
</Accordion>
<Accordion title="Formatação e fallback de HTML">
O texto de saída usa `parse_mode: "HTML"` do Telegram.
<Accordion title="Formatação e fallback HTML">
O texto de saída usa Telegram `parse_mode: "HTML"`.
- Texto no estilo Markdown é renderizado como HTML seguro para o Telegram.
- Texto com estilo Markdown é renderizado em HTML seguro para Telegram.
- HTML bruto do modelo é escapado para reduzir falhas de análise do Telegram.
- Se o Telegram rejeitar o HTML analisado, o OpenClaw tenta novamente como texto simples.
@ -342,7 +340,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
Padrões de comandos nativos:
- `commands.native: "auto"` habilita comandos nativos para o Telegram
- `commands.native: "auto"` habilita comandos nativos para Telegram
Adicione entradas personalizadas ao menu de comandos:
@ -361,7 +359,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
Regras:
- nomes são normalizados (remove `/` inicial, converte para minúsculas)
- nomes são normalizados (remove `/` inicial, minúsculas)
- padrão válido: `a-z`, `0-9`, `_`, comprimento `1..32`
- comandos personalizados não podem sobrescrever comandos nativos
- conflitos/duplicatas são ignorados e registrados em log
@ -369,30 +367,30 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
Observações:
- comandos personalizados são apenas entradas de menu; eles não implementam comportamento automaticamente
- comandos de Plugin/Skills ainda podem funcionar quando digitados, mesmo que não sejam exibidos no menu do Telegram
- comandos de plugin/skill ainda podem funcionar quando digitados, mesmo se não forem exibidos no menu do Telegram
Se comandos nativos forem desabilitados, os integrados serão removidos. Comandos personalizados/de Plugin ainda poderão ser registrados se configurados.
Se comandos nativos estiverem desabilitados, os integrados são removidos. Comandos personalizados/de plugin ainda podem ser registrados se configurados.
Falhas comuns de configuração:
- `setMyCommands failed` com `BOT_COMMANDS_TOO_MUCH` significa que o menu do Telegram ainda excedeu o limite após o corte; reduza comandos de Plugin/Skills/personalizados ou desabilite `channels.telegram.commands.native`.
- Falha em `deleteWebhook`, `deleteMyCommands` ou `setMyCommands` com `404: Not Found` enquanto comandos diretos de curl para a Bot API funcionam pode significar que `channels.telegram.apiRoot` foi definido como o endpoint completo `/bot<TOKEN>`. `apiRoot` deve ser apenas a raiz da Bot API, e `openclaw doctor --fix` remove um `/bot<TOKEN>` final acidental.
- `setMyCommands failed` com `BOT_COMMANDS_TOO_MUCH` significa que o menu do Telegram ainda excedeu o limite após a redução; reduza comandos de plugin/skill/personalizados ou desabilite `channels.telegram.commands.native`.
- `deleteWebhook`, `deleteMyCommands` ou `setMyCommands` falhando com `404: Not Found` enquanto comandos curl diretos da Bot API funcionam pode significar que `channels.telegram.apiRoot` foi definido como o endpoint completo `/bot<TOKEN>`. `apiRoot` deve ser apenas a raiz da Bot API, e `openclaw doctor --fix` remove um `/bot<TOKEN>` final acidental.
- `getMe returned 401` significa que o Telegram rejeitou o token do bot configurado. Atualize `botToken`, `tokenFile` ou `TELEGRAM_BOT_TOKEN` com o token atual do BotFather; o OpenClaw para antes do polling, então isso não é relatado como uma falha de limpeza de Webhook.
- `setMyCommands failed` com erros de rede/fetch geralmente significa que DNS/HTTPS de saída para `api.telegram.org` está bloqueado.
### Comandos de pareamento de dispositivo (Plugin `device-pair`)
### Comandos de pareamento de dispositivo (plugin `device-pair`)
Quando o Plugin `device-pair` está instalado:
Quando o plugin `device-pair` está instalado:
1. `/pair` gera o código de configuração
2. cole o código no app iOS
2. cole o código no aplicativo iOS
3. `/pair pending` lista solicitações pendentes (incluindo função/escopos)
4. aprove a solicitação:
- `/pair approve <requestId>` para aprovação explícita
- `/pair approve` quando houver apenas uma solicitação pendente
- `/pair approve latest` para a mais recente
O código de configuração carrega um token de bootstrap de curta duração. A transferência de bootstrap integrada mantém o token do nó primário em `scopes: []`; qualquer token de operador transferido permanece limitado a `operator.approvals`, `operator.read`, `operator.talk.secrets` e `operator.write`. Verificações de escopo de bootstrap têm prefixo de função, portanto essa allowlist de operador satisfaz apenas solicitações de operador; funções não operadoras ainda precisam de escopos sob seu próprio prefixo de função.
O código de configuração carrega um token de bootstrap de curta duração. A transferência de bootstrap integrada mantém o token do nó primário em `scopes: []`; qualquer token de operador transferido permanece limitado a `operator.approvals`, `operator.read`, `operator.talk.secrets` e `operator.write`. As verificações de escopo de bootstrap são prefixadas por função, então essa lista de permissões de operador só satisfaz solicitações de operador; funções que não são de operador ainda precisam de escopos sob seu próprio prefixo de função.
Se um dispositivo tentar novamente com detalhes de autenticação alterados (por exemplo, função/escopos/chave pública), a solicitação pendente anterior será substituída e a nova solicitação usará um `requestId` diferente. Execute `/pair pending` novamente antes de aprovar.
@ -441,7 +439,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
- `all`
- `allowlist` (padrão)
`capabilities: ["inlineButtons"]` legado mapeia para `inlineButtons: "all"`.
O legado `capabilities: ["inlineButtons"]` mapeia para `inlineButtons: "all"`.
Exemplo de ação de mensagem:
@ -467,34 +465,34 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
</Accordion>
<Accordion title="Ações de mensagem do Telegram para agentes e automação">
Ações de ferramenta do Telegram incluem:
As ações de ferramenta do Telegram incluem:
- `sendMessage` (`to`, `content`, `mediaUrl` opcional, `replyToMessageId`, `messageThreadId`)
- `sendMessage` (`to`, `content`, opcional `mediaUrl`, `replyToMessageId`, `messageThreadId`)
- `react` (`chatId`, `messageId`, `emoji`)
- `deleteMessage` (`chatId`, `messageId`)
- `editMessage` (`chatId`, `messageId`, `content`)
- `createForumTopic` (`chatId`, `name`, `iconColor` opcional, `iconCustomEmojiId`)
- `createForumTopic` (`chatId`, `name`, opcional `iconColor`, `iconCustomEmojiId`)
Ações de mensagem de canal expõem aliases ergonômicos (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`).
Controles de gating:
Controles de bloqueio:
- `channels.telegram.actions.sendMessage`
- `channels.telegram.actions.deleteMessage`
- `channels.telegram.actions.reactions`
- `channels.telegram.actions.sticker` (padrão: desabilitado)
Observação: `edit` e `topic-create` atualmente são habilitados por padrão e não têm toggles `channels.telegram.actions.*` separados.
Envios em runtime usam o snapshot ativo de configuração/segredos (inicialização/recarregamento), portanto os caminhos de ação não fazem nova resolução ad hoc de SecretRef por envio.
Observação: `edit` e `topic-create` estão atualmente habilitados por padrão e não têm alternâncias separadas em `channels.telegram.actions.*`.
Envios em tempo de execução usam o snapshot ativo de configuração/segredos (inicialização/recarregamento), portanto os caminhos de ação não fazem nova resolução ad hoc de SecretRef por envio.
Semântica de remoção de reações: [/tools/reactions](/pt-BR/tools/reactions)
</Accordion>
<Accordion title="Tags de encadeamento de resposta">
O Telegram oferece suporte a tags explícitas de encadeamento de resposta na saída gerada:
O Telegram dá suporte a tags explícitas de encadeamento de resposta na saída gerada:
- `[[reply_to_current]]` responde à mensagem acionadora
- `[[reply_to_current]]` responde à mensagem que disparou a ação
- `[[reply_to:<id>]]` responde a uma ID específica de mensagem do Telegram
`channels.telegram.replyToMode` controla o tratamento:
@ -503,9 +501,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
- `first`
- `all`
Quando o encadeamento de resposta está habilitado e o texto ou a legenda original do Telegram está disponível, o OpenClaw inclui automaticamente um trecho de citação nativa do Telegram. O Telegram limita o texto de citação nativa a 1024 unidades de código UTF-16, então mensagens mais longas são citadas desde o início e recorrem a uma resposta simples se o Telegram rejeitar a citação.
Quando o encadeamento de resposta está habilitado e o texto ou a legenda original do Telegram está disponível, o OpenClaw inclui automaticamente um trecho de citação nativa do Telegram. O Telegram limita o texto de citação nativa a 1024 unidades de código UTF-16, então mensagens mais longas são citadas a partir do início e recorrem a uma resposta simples se o Telegram rejeitar a citação.
Observação: `off` desabilita o encadeamento de resposta implícito. Tags explícitas `[[reply_to_*]]` ainda são honradas.
Observação: `off` desabilita o encadeamento implícito de resposta. Tags explícitas `[[reply_to_*]]` ainda são respeitadas.
</Accordion>
@ -513,7 +511,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
Supergrupos de fórum:
- chaves de sessão de tópico acrescentam `:topic:<threadId>`
- respostas e digitação miram a thread do tópico
- respostas e digitação têm como destino a thread do tópico
- caminho de configuração de tópico:
`channels.telegram.groups.<chatId>.topics.<threadId>`
@ -522,10 +520,10 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
- envios de mensagem omitem `message_thread_id` (o Telegram rejeita `sendMessage(...thread_id=1)`)
- ações de digitação ainda incluem `message_thread_id`
Herança de tópicos: entradas de tópico herdam configurações de grupo, a menos que sejam sobrescritas (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`).
Herança de tópico: entradas de tópico herdam configurações do grupo, a menos que sejam sobrescritas (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`).
`agentId` é exclusivo do tópico e não herda dos padrões do grupo.
**Roteamento de agente por tópico**: cada tópico pode rotear para um agente diferente definindo `agentId` na configuração do tópico. Isso dá a cada tópico seu próprio workspace, memória e sessão isolados. Exemplo:
**Roteamento de agente por tópico**: Cada tópico pode rotear para um agente diferente definindo `agentId` na configuração do tópico. Isso dá a cada tópico seu próprio workspace, memória e sessão isolados. Exemplo:
```json5
{
@ -547,11 +545,11 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
Cada tópico então tem sua própria chave de sessão: `agent:zu:telegram:group:-1001234567890:topic:3`
**Vinculação persistente de tópico ACP**: tópicos de fórum podem fixar sessões de harness ACP por meio de vinculações ACP tipadas de nível superior (`bindings[]` com `type: "acp"` e `match.channel: "telegram"`, `peer.kind: "group"` e uma id qualificada por tópico, como `-1001234567890:topic:42`). Atualmente limitado a tópicos de fórum em grupos/supergrupos. Consulte [Agentes ACP](/pt-BR/tools/acp-agents).
**Vínculo persistente de tópico ACP**: Tópicos de fórum podem fixar sessões de harness ACP por meio de vínculos ACP tipados de nível superior (`bindings[]` com `type: "acp"` e `match.channel: "telegram"`, `peer.kind: "group"` e uma ID qualificada por tópico como `-1001234567890:topic:42`). Atualmente limitado a tópicos de fórum em grupos/supergrupos. Veja [Agentes ACP](/pt-BR/tools/acp-agents).
**Spawn de ACP vinculado à thread a partir do chat**: `/acp spawn <agent> --thread here|auto` vincula o tópico atual a uma nova sessão ACP; acompanhamentos são roteados diretamente para lá. O OpenClaw fixa a confirmação de spawn no tópico. Requer `channels.telegram.threadBindings.spawnAcpSessions=true`.
**Spawn ACP vinculado à thread a partir do chat**: `/acp spawn <agent> --thread here|auto` vincula o tópico atual a uma nova sessão ACP; acompanhamentos são roteados diretamente para lá. O OpenClaw fixa a confirmação de spawn no tópico. Requer `channels.telegram.threadBindings.spawnAcpSessions=true`.
O contexto de template expõe `MessageThreadId` e `IsForum`. Chats de MD com `message_thread_id` mantêm o roteamento de MD, mas usam chaves de sessão cientes de thread.
O contexto de template expõe `MessageThreadId` e `IsForum`. Chats de DM com `message_thread_id` mantêm o roteamento de DM, mas usam chaves de sessão cientes de thread.
</Accordion>
@ -564,7 +562,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
- tag `[[audio_as_voice]]` na resposta do agente para forçar envio como nota de voz
- transcrições de notas de voz recebidas são enquadradas como texto gerado por máquina,
não confiável no contexto do agente; a detecção de menção ainda usa a transcrição
bruta, então mensagens de voz bloqueadas por menção continuam funcionando.
bruta, então mensagens de voz condicionadas a menção continuam funcionando.
Exemplo de ação de mensagem:
@ -594,7 +592,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
}
```
Notas de vídeo não oferecem suporte a legendas; o texto de mensagem fornecido é enviado separadamente.
Notas de vídeo não dão suporte a legendas; o texto da mensagem fornecido é enviado separadamente.
### Stickers
@ -657,9 +655,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
</Accordion>
<Accordion title="Notificações de reação">
Reações do Telegram chegam como atualizações `message_reaction` (separadas das cargas úteis de mensagem).
Reações do Telegram chegam como atualizações `message_reaction` (separadas das cargas de mensagem).
Quando habilitado, o OpenClaw enfileira eventos de sistema como:
Quando habilitado, o OpenClaw enfileira eventos do sistema como:
- `Telegram reaction added: 👍 by Alice (@alice) on msg 42`
@ -672,7 +670,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
- `own` significa apenas reações de usuários a mensagens enviadas pelo bot (melhor esforço via cache de mensagens enviadas).
- Eventos de reação ainda respeitam os controles de acesso do Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); remetentes não autorizados são descartados.
- O Telegram não fornece IDs de thread nas atualizações de reação.
- O Telegram não fornece IDs de tópico em atualizações de reação.
- grupos que não são fóruns são roteados para a sessão de chat do grupo
- grupos de fórum são roteados para a sessão do tópico geral do grupo (`:topic:1`), não para o tópico exato de origem
@ -688,22 +686,22 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
- `channels.telegram.accounts.<accountId>.ackReaction`
- `channels.telegram.ackReaction`
- `messages.ackReaction`
- fallback de emoji da identidade do agente (`agents.list[].identity.emoji`, caso contrário "👀")
- fallback para emoji de identidade do agente (`agents.list[].identity.emoji`, senão "👀")
Observações:
- O Telegram espera emoji unicode (por exemplo "👀").
- O Telegram espera emoji unicode (por exemplo, "👀").
- Use `""` para desabilitar a reação para um canal ou conta.
</Accordion>
<Accordion title="Gravações de configuração a partir de eventos e comandos do Telegram">
Gravações de configuração do canal são habilitadas por padrão (`configWrites !== false`).
<Accordion title="Escritas de configuração a partir de eventos e comandos do Telegram">
Escritas na configuração do canal são habilitadas por padrão (`configWrites !== false`).
Gravações acionadas pelo Telegram incluem:
Escritas acionadas pelo Telegram incluem:
- eventos de migração de grupo (`migrate_to_chat_id`) para atualizar `channels.telegram.groups`
- `/config set` e `/config unset` (requer habilitação de comandos)
- `/config set` e `/config unset` (requer habilitação de comando)
Desabilitar:
@ -720,37 +718,37 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
</Accordion>
<Accordion title="Long polling vs webhook">
O padrão é long polling. Para o modo webhook, defina `channels.telegram.webhookUrl` e `channels.telegram.webhookSecret`; opcionais `webhookPath`, `webhookHost`, `webhookPort` (padrões `/telegram-webhook`, `127.0.0.1`, `8787`).
O padrão é long polling. Para o modo webhook, defina `channels.telegram.webhookUrl` e `channels.telegram.webhookSecret`; `webhookPath`, `webhookHost`, `webhookPort` opcionais (padrões `/telegram-webhook`, `127.0.0.1`, `8787`).
O listener local faz bind em `127.0.0.1:8787`. Para ingresso público, coloque um proxy reverso na frente da porta local ou defina `webhookHost: "0.0.0.0"` intencionalmente.
O modo Webhook valida as proteções da requisição, o token secreto do Telegram e o corpo JSON antes de retornar `200` ao Telegram.
Em seguida, o OpenClaw processa a atualização de forma assíncrona pelas mesmas lanes de bot por chat/por tópico usadas pelo long polling, então turnos lentos do agente não seguram o ACK de entrega do Telegram.
O modo webhook valida as proteções da solicitação, o token secreto do Telegram e o corpo JSON antes de retornar `200` ao Telegram.
Em seguida, o OpenClaw processa a atualização de forma assíncrona pelas mesmas lanes de bot por chat/por tópico usadas pelo long polling, então turnos lentos do agente não retêm o ACK de entrega do Telegram.
</Accordion>
<Accordion title="Limites, repetição e destinos da CLI">
- `channels.telegram.textChunkLimit` tem padrão 4000.
- `channels.telegram.chunkMode="newline"` prefere limites de parágrafo (linhas em branco) antes da divisão por tamanho.
<Accordion title="Limites, retry e alvos da CLI">
- O padrão de `channels.telegram.textChunkLimit` é 4000.
- `channels.telegram.chunkMode="newline"` prefere limites de parágrafo (linhas em branco) antes de dividir por comprimento.
- `channels.telegram.mediaMaxMb` (padrão 100) limita o tamanho de mídia recebida e enviada do Telegram.
- `channels.telegram.timeoutSeconds` substitui o timeout do cliente da API do Telegram (se não definido, aplica-se o padrão do grammY).
- `channels.telegram.pollingStallThresholdMs` tem padrão `120000`; ajuste entre `30000` e `600000` apenas para reinícios por polling travado falso-positivos.
- `channels.telegram.timeoutSeconds` sobrescreve o timeout do cliente da API do Telegram (se não definido, aplica-se o padrão do grammY). Clientes de bot em long polling limitam valores configurados abaixo da proteção de solicitação de 45 segundos de `getUpdates`, para que polls ociosos não sejam abortados antes da conclusão da janela de poll de 30 segundos.
- `channels.telegram.pollingStallThresholdMs` tem padrão `120000`; ajuste entre `30000` e `600000` apenas para reinicializações por polling travado falso-positivas.
- o histórico de contexto de grupo usa `channels.telegram.historyLimit` ou `messages.groupChat.historyLimit` (padrão 50); `0` desabilita.
- contexto suplementar de resposta/citação/encaminhamento atualmente é passado como recebido.
- allowlists do Telegram controlam principalmente quem pode acionar o agente, não uma fronteira completa de redação de contexto suplementar.
- contexto suplementar de resposta/citação/encaminhamento é atualmente passado como recebido.
- allowlists do Telegram controlam principalmente quem pode acionar o agente, não um limite completo de redação de contexto suplementar.
- Controles de histórico de DM:
- `channels.telegram.dmHistoryLimit`
- `channels.telegram.dms["<user_id>"].historyLimit`
- A configuração `channels.telegram.retry` se aplica aos helpers de envio do Telegram (CLI/ferramentas/ações) para erros recuperáveis da API de saída. A entrega de resposta final recebida também usa uma repetição safe-send limitada para falhas pré-conexão do Telegram, mas não repete envelopes de rede ambíguos pós-envio que poderiam duplicar mensagens visíveis.
- A configuração `channels.telegram.retry` se aplica aos helpers de envio do Telegram (CLI/ferramentas/ações) para erros recuperáveis da API de saída. A entrega de resposta final recebida também usa uma nova tentativa de envio seguro limitada para falhas de pré-conexão do Telegram, mas não repete envelopes de rede ambíguos após o envio que poderiam duplicar mensagens visíveis.
O destino de envio da CLI pode ser um ID numérico de chat ou nome de usuário:
O alvo de envio da CLI pode ser um ID numérico de chat ou nome de usuário:
```bash
openclaw message send --channel telegram --target 123456789 --message "hi"
openclaw message send --channel telegram --target @name --message "hi"
```
Enquetes do Telegram usam `openclaw message poll` e oferecem suporte a tópicos de fórum:
Polls do Telegram usam `openclaw message poll` e oferecem suporte a tópicos de fórum:
```bash
openclaw message poll --channel telegram --target 123456789 \
@ -760,41 +758,41 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
--poll-duration-seconds 300 --poll-public
```
Flags de enquete exclusivas do Telegram:
Flags de poll exclusivas do Telegram:
- `--poll-duration-seconds` (5-600)
- `--poll-anonymous`
- `--poll-public`
- `--thread-id` para tópicos de fórum (ou use um destino `:topic:`)
- `--thread-id` para tópicos de fórum (ou use um alvo `:topic:`)
O envio do Telegram também oferece suporte a:
O envio pelo Telegram também aceita:
- `--presentation` com blocos `buttons` para teclados inline quando `channels.telegram.capabilities.inlineButtons` permite
- `--pin` ou `--delivery '{"pin":true}'` para solicitar entrega fixada quando o bot pode fixar nesse chat
- `--force-document` para enviar imagens e GIFs de saída como documentos em vez de uploads compactados de foto ou mídia animada
- `--presentation` com blocos `buttons` para teclados inline quando `channels.telegram.capabilities.inlineButtons` permitir
- `--pin` ou `--delivery '{"pin":true}'` para solicitar entrega fixada quando o bot puder fixar mensagens nesse chat
- `--force-document` para enviar imagens e GIFs de saída como documentos em vez de uploads de foto compactada ou mídia animada
Controle de ações:
- `channels.telegram.actions.sendMessage=false` desabilita mensagens de saída do Telegram, incluindo enquetes
- `channels.telegram.actions.poll=false` desabilita a criação de enquetes do Telegram, mantendo envios regulares habilitados
- `channels.telegram.actions.sendMessage=false` desabilita mensagens de saída do Telegram, incluindo polls
- `channels.telegram.actions.poll=false` desabilita a criação de polls do Telegram, mantendo envios regulares habilitados
</Accordion>
<Accordion title="Aprovações de exec no Telegram">
O Telegram oferece suporte a aprovações de exec em DMs de aprovadores e pode opcionalmente publicar prompts no chat ou tópico de origem. Aprovadores devem ser IDs numéricos de usuários do Telegram.
O Telegram oferece suporte a aprovações de exec em DMs de aprovadores e pode opcionalmente publicar prompts no chat ou tópico de origem. Aprovadores devem ser IDs numéricos de usuário do Telegram.
Caminho de configuração:
- `channels.telegram.execApprovals.enabled` (habilita automaticamente quando pelo menos um aprovador pode ser resolvido)
- `channels.telegram.execApprovals.enabled` (habilita automaticamente quando pelo menos um aprovador é resolvível)
- `channels.telegram.execApprovals.approvers` (faz fallback para IDs numéricos de proprietários de `commands.ownerAllowFrom`)
- `channels.telegram.execApprovals.target`: `dm` (padrão) | `channel` | `both`
- `agentFilter`, `sessionFilter`
`channels.telegram.allowFrom`, `groupAllowFrom` e `defaultTo` controlam quem pode falar com o bot e para onde ele envia respostas normais. Eles não tornam alguém um aprovador de exec. O primeiro pareamento de DM aprovado inicializa `commands.ownerAllowFrom` quando ainda não existe um proprietário de comandos, então a configuração com um único proprietário ainda funciona sem duplicar IDs em `execApprovals.approvers`.
`channels.telegram.allowFrom`, `groupAllowFrom` e `defaultTo` controlam quem pode falar com o bot e para onde ele envia respostas normais. Eles não tornam alguém um aprovador de exec. O primeiro pareamento de DM aprovado inicializa `commands.ownerAllowFrom` quando ainda não existe nenhum proprietário de comando, então a configuração com um proprietário ainda funciona sem duplicar IDs em `execApprovals.approvers`.
A entrega no canal mostra o texto do comando no chat; habilite `channel` ou `both` apenas em grupos/tópicos confiáveis. Quando o prompt chega a um tópico de fórum, o OpenClaw preserva o tópico para o prompt de aprovação e o acompanhamento. Aprovações de exec expiram após 30 minutos por padrão.
Botões inline de aprovação também exigem que `channels.telegram.capabilities.inlineButtons` permita a superfície de destino (`dm`, `group` ou `all`). IDs de aprovação prefixados com `plugin:` são resolvidos por aprovações de Plugin; outros são resolvidos primeiro por aprovações de exec.
Botões de aprovação inline também exigem que `channels.telegram.capabilities.inlineButtons` permita a superfície de destino (`dm`, `group` ou `all`). IDs de aprovação prefixados com `plugin:` são resolvidos por aprovações de plugin; os demais são resolvidos primeiro por aprovações de exec.
Consulte [Aprovações de exec](/pt-BR/tools/exec-approvals).
@ -803,14 +801,14 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
## Controles de resposta de erro
Quando o agente encontra um erro de entrega ou provedor, o Telegram pode responder com o texto do erro ou suprimi-lo. Duas chaves de configuração controlam esse comportamento:
Quando o agente encontra um erro de entrega ou de provedor, o Telegram pode responder com o texto do erro ou suprimi-lo. Duas chaves de configuração controlam esse comportamento:
| Chave | Valores | Padrão | Descrição |
| ----------------------------------- | ----------------- | ------- | ---------------------------------------------------------------------------------------------------------- |
| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` envia uma mensagem de erro amigável ao chat. `silent` suprime respostas de erro completamente. |
| `channels.telegram.errorCooldownMs` | número (ms) | `60000` | Tempo mínimo entre respostas de erro para o mesmo chat. Evita spam de erros durante interrupções. |
| Chave | Valores | Padrão | Descrição |
| ----------------------------------- | ----------------- | ------- | ------------------------------------------------------------------------------------------------ |
| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` envia uma mensagem de erro amigável para o chat. `silent` suprime totalmente respostas de erro. |
| `channels.telegram.errorCooldownMs` | número (ms) | `60000` | Tempo mínimo entre respostas de erro para o mesmo chat. Evita spam de erros durante indisponibilidades. |
Substituições por conta, por grupo e por tópico são suportadas (mesma herança de outras chaves de configuração do Telegram).
Substituições por conta, por grupo e por tópico são aceitas (mesma herança de outras chaves de configuração do Telegram).
```json5
{
@ -834,51 +832,52 @@ Substituições por conta, por grupo e por tópico são suportadas (mesma heran
<Accordion title="Bot não responde a mensagens de grupo sem menção">
- Se `requireMention=false`, o modo de privacidade do Telegram deve permitir visibilidade total.
- BotFather: `/setprivacy` -> Desabilitar
- depois remova e adicione novamente o bot ao grupo
- BotFather: `/setprivacy` -> Disable
- depois remova e readicione o bot ao grupo
- `openclaw channels status` avisa quando a configuração espera mensagens de grupo sem menção.
- `openclaw channels status --probe` pode verificar IDs numéricos explícitos de grupo; o curinga `"*"` não pode ter associação verificada.
- `openclaw channels status --probe` pode verificar IDs numéricos explícitos de grupo; o curinga `"*"` não pode ter associação sondada.
- teste rápido de sessão: `/activation always`.
</Accordion>
<Accordion title="Bot não vê nenhuma mensagem de grupo">
<Accordion title="Bot não está vendo mensagens de grupo">
- quando `channels.telegram.groups` existe, o grupo deve estar listado (ou incluir `"*"`)
- verifique a associação do bot ao grupo
- revise os logs: `openclaw logs --follow` para motivos de salto
- revise os logs: `openclaw logs --follow` para motivos de ignorar
</Accordion>
<Accordion title="Comandos funcionam parcialmente ou não funcionam">
- autorize sua identidade de remetente (pareamento e/ou `allowFrom` numérico)
- a autorização de comandos ainda se aplica mesmo quando a política de grupo é `open`
- `setMyCommands failed` com `BOT_COMMANDS_TOO_MUCH` significa que o menu nativo tem entradas demais; reduza comandos de Plugin/skill/personalizados ou desabilite menus nativos
- chamadas de inicialização `deleteMyCommands` / `setMyCommands` são limitadas e tentam novamente uma vez pelo fallback de transporte do Telegram em timeout de requisição. Erros persistentes de rede/fetch geralmente indicam problemas de acessibilidade DNS/HTTPS para `api.telegram.org`
- a autorização de comando ainda se aplica mesmo quando a política de grupo é `open`
- `setMyCommands failed` com `BOT_COMMANDS_TOO_MUCH` significa que o menu nativo tem entradas demais; reduza comandos de plugin/skill/customizados ou desabilite menus nativos
- chamadas de inicialização `deleteMyCommands` / `setMyCommands` são limitadas e tentam novamente uma vez pelo fallback de transporte do Telegram em timeout de solicitação. Erros persistentes de rede/fetch normalmente indicam problemas de DNS/alcance HTTPS para `api.telegram.org`
</Accordion>
<Accordion title="Inicialização relata token não autorizado">
- `getMe returned 401` é uma falha de autenticação do Telegram para o token de bot configurado.
- Copie novamente ou regenere o token do bot no BotFather, depois atualize `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts.<id>.botToken` ou `TELEGRAM_BOT_TOKEN` para a conta padrão.
- `deleteWebhook 401 Unauthorized` durante a inicialização também é uma falha de autenticação; tratá-lo como "nenhum webhook existe" apenas adiaria a mesma falha de token inválido para chamadas posteriores da API.
- Se `deleteWebhook` falhar com um erro transitório de rede durante a inicialização do polling, o OpenClaw verifica `getWebhookInfo`; quando o Telegram relata uma URL de webhook vazia, o polling continua porque a limpeza já foi satisfeita.
- Copie novamente ou regenere o token do bot no BotFather e atualize `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts.<id>.botToken` ou `TELEGRAM_BOT_TOKEN` para a conta padrão.
- `deleteWebhook 401 Unauthorized` durante a inicialização também é uma falha de autenticação; tratá-lo como "nenhum webhook existe" apenas adiaria a mesma falha de token inválido para chamadas de API posteriores.
- Se `deleteWebhook` falhar com um erro transitório de rede durante a inicialização de polling, o OpenClaw verifica `getWebhookInfo`; quando o Telegram relata uma URL de webhook vazia, o polling continua porque a limpeza já foi satisfeita.
</Accordion>
<Accordion title="Instabilidade de polling ou rede">
- Node 22+ + fetch/proxy personalizado pode acionar comportamento de aborto imediato se os tipos de AbortSignal não corresponderem.
- Alguns hosts resolvem `api.telegram.org` para IPv6 primeiro; egress IPv6 quebrado pode causar falhas intermitentes da API do Telegram.
- Node 22+ + fetch/proxy personalizados podem acionar comportamento de cancelamento imediato se os tipos de AbortSignal não corresponderem.
- Alguns hosts resolvem `api.telegram.org` para IPv6 primeiro; saída IPv6 quebrada pode causar falhas intermitentes na API do Telegram.
- Se os logs incluírem `TypeError: fetch failed` ou `Network request for 'getUpdates' failed!`, o OpenClaw agora tenta novamente esses casos como erros de rede recuperáveis.
- Se os logs incluírem `Polling stall detected`, o OpenClaw reinicia o polling e reconstrói o transporte do Telegram após 120 segundos sem liveness de long-poll concluído por padrão.
- `openclaw channels status --probe` e `openclaw doctor` avisam quando uma conta de polling em execução não concluiu `getUpdates` após a tolerância de inicialização, quando uma conta de Webhook em execução não concluiu `setWebhook` após a tolerância de inicialização, ou quando a última atividade bem-sucedida do transporte de polling está obsoleta.
- Aumente `channels.telegram.pollingStallThresholdMs` somente quando chamadas `getUpdates` de longa duração estiverem saudáveis, mas seu host ainda relatar falsos reinícios por polling travado. Travamentos persistentes geralmente apontam para problemas de proxy, DNS, IPv6 ou egress TLS entre o host e `api.telegram.org`.
- O Telegram também respeita env de proxy do processo para o transporte da Bot API, incluindo `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` e suas variantes em minúsculas. `NO_PROXY` / `no_proxy` ainda podem ignorar `api.telegram.org`.
- Se o proxy gerenciado pelo OpenClaw estiver configurado por meio de `OPENCLAW_PROXY_URL` para um ambiente de serviço e nenhum env de proxy padrão estiver presente, o Telegram também usa essa URL para o transporte da Bot API.
- Em hosts VPS com egress/TLS direto instável, roteie as chamadas da API do Telegram por meio de `channels.telegram.proxy`:
- Se os sockets do Telegram forem reciclados em uma cadência fixa curta, verifique se há um `channels.telegram.timeoutSeconds` baixo; clientes de bot com long polling limitam valores configurados abaixo da proteção da solicitação `getUpdates`, mas versões mais antigas podiam abortar cada polling quando isso era definido abaixo do tempo limite de long polling.
- Se os logs incluírem `Polling stall detected`, o OpenClaw reinicia o polling e reconstrói o transporte do Telegram após 120 segundos sem liveness de long poll concluída por padrão.
- `openclaw channels status --probe` e `openclaw doctor` avisam quando uma conta de polling em execução não concluiu `getUpdates` após o período de tolerância da inicialização, quando uma conta de webhook em execução não concluiu `setWebhook` após o período de tolerância da inicialização, ou quando a última atividade bem-sucedida do transporte de polling está obsoleta.
- Aumente `channels.telegram.pollingStallThresholdMs` somente quando chamadas `getUpdates` de longa duração estiverem saudáveis, mas seu host ainda relatar reinícios falsos por polling travado. Travamentos persistentes geralmente indicam problemas de proxy, DNS, IPv6 ou saída TLS entre o host e `api.telegram.org`.
- O Telegram também respeita env de proxy do processo para transporte da Bot API, incluindo `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` e suas variantes em minúsculas. `NO_PROXY` / `no_proxy` ainda pode ignorar `api.telegram.org`.
- Se o proxy gerenciado pelo OpenClaw estiver configurado por meio de `OPENCLAW_PROXY_URL` para um ambiente de serviço e nenhum env de proxy padrão estiver presente, o Telegram também usará essa URL para o transporte da Bot API.
- Em hosts VPS com saída direta/TLS instável, roteie chamadas da API do Telegram por `channels.telegram.proxy`:
```yaml
channels:
@ -896,10 +895,10 @@ channels:
autoSelectFamily: false
```
- Respostas de intervalo de benchmark RFC 2544 (`198.18.0.0/15`) já são permitidas
para downloads de mídia do Telegram por padrão. Se um fake-IP confiável ou
proxy transparente reescrever `api.telegram.org` para algum outro
endereço privado/interno/de uso especial durante downloads de mídia, você pode optar
- Respostas na faixa de benchmark RFC 2544 (`198.18.0.0/15`) já são permitidas
por padrão para downloads de mídia do Telegram. Se um fake-IP confiável ou
proxy transparente reescrever `api.telegram.org` para algum outro endereço
privado/interno/de uso especial durante downloads de mídia, você pode optar
pelo bypass exclusivo do Telegram:
```yaml
@ -909,26 +908,26 @@ channels:
dangerouslyAllowPrivateNetwork: true
```
- A mesma opção está disponível por conta em
- A mesma adesão está disponível por conta em
`channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork`.
- Se seu proxy resolver hosts de mídia do Telegram para `198.18.x.x`, deixe a
flag perigosa desativada primeiro. A mídia do Telegram já permite o intervalo
de benchmark RFC 2544 por padrão.
flag perigosa desativada primeiro. A mídia do Telegram já permite a faixa de
benchmark RFC 2544 por padrão.
<Warning>
`channels.telegram.network.dangerouslyAllowPrivateNetwork` enfraquece as
proteções SSRF de mídia do Telegram. Use somente em ambientes de proxy
proteções de SSRF de mídia do Telegram. Use-a apenas em ambientes de proxy
confiáveis controlados pelo operador, como roteamento fake-IP do Clash,
Mihomo ou Surge, quando eles sintetizam respostas privadas ou de uso especial
fora do intervalo de benchmark RFC 2544. Deixe desativado para acesso normal
do Telegram pela internet pública.
Mihomo ou Surge quando eles sintetizam respostas privadas ou de uso especial
fora da faixa de benchmark RFC 2544. Deixe-a desativada para acesso normal
do Telegram à internet pública.
</Warning>
- Sobrescritas de ambiente (temporárias):
- Substituições de ambiente (temporárias):
- `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1`
- `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1`
- `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first`
- Valide as respostas DNS:
- Valide respostas DNS:
```bash
dig +short api.telegram.org A
@ -944,43 +943,43 @@ Mais ajuda: [Solução de problemas de canais](/pt-BR/channels/troubleshooting).
Referência principal: [Referência de configuração - Telegram](/pt-BR/gateway/config-channels#telegram).
<Accordion title="Campos do Telegram de alta relevância">
<Accordion title="Campos de alta relevância do Telegram">
- inicialização/autenticação: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` deve apontar para um arquivo regular; symlinks são rejeitados)
- inicialização/auth: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` deve apontar para um arquivo regular; symlinks são rejeitados)
- controle de acesso: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, `bindings[]` de nível superior (`type: "acp"`)
- aprovações de execução: `execApprovals`, `accounts.*.execApprovals`
- comando/menu: `commands.native`, `commands.nativeSkills`, `customCommands`
- encadeamento/respostas: `replyToMode`
- threading/respostas: `replyToMode`
- streaming: `streaming` (prévia), `streaming.preview.toolProgress`, `blockStreaming`
- formatação/entrega: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix`
- mídia/rede: `mediaMaxMb`, `timeoutSeconds`, `pollingStallThresholdMs`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy`
- raiz de API personalizada: `apiRoot` (somente raiz da Bot API; não inclua `/bot<TOKEN>`)
- Webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost`
- raiz da API personalizada: `apiRoot` (somente raiz da Bot API; não inclua `/bot<TOKEN>`)
- webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost`
- ações/capacidades: `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker`
- reações: `reactionNotifications`, `reactionLevel`
- erros: `errorPolicy`, `errorCooldownMs`
- gravações/histórico: `configWrites`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit`
- escritas/histórico: `configWrites`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit`
</Accordion>
<Note>
Precedência de várias contas: quando dois ou mais IDs de conta estiverem configurados, defina `channels.telegram.defaultAccount` (ou inclua `channels.telegram.accounts.default`) para tornar o roteamento padrão explícito. Caso contrário, o OpenClaw volta para o primeiro ID de conta normalizado e `openclaw doctor` avisa. Contas nomeadas herdam `channels.telegram.allowFrom` / `groupAllowFrom`, mas não os valores de `accounts.default.*`.
Precedência de várias contas: quando dois ou mais IDs de conta estiverem configurados, defina `channels.telegram.defaultAccount` (ou inclua `channels.telegram.accounts.default`) para tornar o roteamento padrão explícito. Caso contrário, o OpenClaw recorre ao primeiro ID de conta normalizado e `openclaw doctor` avisa. Contas nomeadas herdam `channels.telegram.allowFrom` / `groupAllowFrom`, mas não valores de `accounts.default.*`.
</Note>
## Relacionado
## Relacionados
<CardGroup cols={2}>
<Card title="Emparelhamento" icon="link" href="/pt-BR/channels/pairing">
Emparelhe um usuário do Telegram ao Gateway.
<Card title="Pareamento" icon="link" href="/pt-BR/channels/pairing">
Pareie um usuário do Telegram com o Gateway.
</Card>
<Card title="Grupos" icon="users" href="/pt-BR/channels/groups">
Comportamento de lista de permissões de grupos e tópicos.
</Card>
<Card title="Roteamento de canais" icon="route" href="/pt-BR/channels/channel-routing">
Roteie mensagens de entrada para agentes.
Roteie mensagens recebidas para agentes.
</Card>
<Card title="Segurança" icon="shield" href="/pt-BR/gateway/security">
Modelo de ameaças e endurecimento.
Modelo de ameaça e hardening.
</Card>
<Card title="Roteamento multiagente" icon="sitemap" href="/pt-BR/concepts/multi-agent">
Mapeie grupos e tópicos para agentes.

114
docs/pt-BR/concepts/memory-search.md
View File

@ -3,25 +3,25 @@ read_when:
- Você quer entender como o memory_search funciona
- Você quer escolher um provedor de embeddings
- Você quer ajustar a qualidade da busca
summary: Como a busca de memória encontra notas relevantes usando embeddings e recuperação híbrida
title: Busca na memória
summary: Como a busca na memória encontra notas relevantes usando embeddings e recuperação híbrida
title: Busca de memória
x-i18n:
generated_at: "2026-04-30T09:44:34Z"
generated_at: "2026-04-30T16:27:47Z"
model: gpt-5.5
provider: openai
source_hash: 3e6c44d90f49a797bda01b9a575928c128a334f89ae14fc3620e65562a866aa9
source_hash: 7f40bbe32453a28070ffc67f19a4c06e2fe59a24237a2aef353f4b9b8260bcf2
source_path: concepts/memory-search.md
workflow: 16
---
`memory_search` encontra notas relevantes nos seus arquivos de memória, mesmo quando a
formulação difere do texto original. Ele funciona indexando a memória em pequenos
redação difere do texto original. Ele funciona indexando a memória em pequenos
trechos e pesquisando neles usando embeddings, palavras-chave ou ambos.
## Início rápido
Se você tiver uma assinatura do GitHub Copilot, uma chave de API da OpenAI,
Gemini, Voyage ou Mistral configurada, a pesquisa na memória funciona
Se você tiver uma assinatura do GitHub Copilot, ou uma chave de API da OpenAI,
Gemini, Voyage ou Mistral configurada, a pesquisa de memória funciona
automaticamente. Para definir um provedor explicitamente:
```json5
@ -36,13 +36,14 @@ automaticamente. Para definir um provedor explicitamente:
}
```
Para configurações com múltiplos endpoints, `provider` também pode ser uma
entrada personalizada de `models.providers.<id>`, como `ollama-5080`, quando
esse provedor define `api: "ollama"` ou outro proprietário de adaptador de
embedding.
Para configurações com vários endpoints, `provider` também pode ser uma entrada
personalizada de `models.providers.<id>`, como `ollama-5080`, quando esse
provedor define `api: "ollama"` ou outro proprietário de adaptador de embedding.
Para embeddings locais sem chave de API, instale o pacote de runtime opcional
`node-llama-cpp` ao lado do OpenClaw e use `provider: "local"`.
Para embeddings locais sem chave de API, defina `provider: "local"`. Instalações
empacotadas mantêm o runtime nativo `node-llama-cpp` na árvore de runtime-deps
de Plugin gerenciado do OpenClaw; execute `openclaw doctor --fix` se essa árvore
precisar de reparo.
Alguns endpoints de embedding compatíveis com OpenAI exigem rótulos assimétricos,
como `input_type: "query"` para pesquisas e `input_type: "document"` ou
@ -52,16 +53,16 @@ como `input_type: "query"` para pesquisas e `input_type: "document"` ou
## Provedores compatíveis
| Provedor | ID | Precisa de chave de API | Notas |
| -------------- | ---------------- | ----------------------- | ----------------------------------------------------------- |
| Bedrock | `bedrock` | Não | Detectado automaticamente quando a cadeia de credenciais da AWS é resolvida |
| Gemini | `gemini` | Sim | Compatível com indexação de imagem/áudio |
| GitHub Copilot | `github-copilot` | Não | Detectado automaticamente, usa a assinatura do Copilot |
| Local | `local` | Não | Modelo GGUF, download de ~0,6 GB |
| Mistral | `mistral` | Sim | Detectado automaticamente |
| Ollama | `ollama` | Não | Local, deve ser definido explicitamente |
| OpenAI | `openai` | Sim | Detectado automaticamente, rápido |
| Voyage | `voyage` | Sim | Detectado automaticamente |
| Provedor | ID | Precisa de chave de API | Observações |
| -------------- | ---------------- | ----------------------- | -------------------------------------------------------------- |
| Bedrock | `bedrock` | Não | Detectado automaticamente quando a cadeia de credenciais da AWS resolve |
| Gemini | `gemini` | Sim | Oferece suporte à indexação de imagem/áudio |
| GitHub Copilot | `github-copilot` | Não | Detectado automaticamente, usa a assinatura do Copilot |
| Local | `local` | Não | Modelo GGUF, download de ~0,6 GB |
| Mistral | `mistral` | Sim | Detectado automaticamente |
| Ollama | `ollama` | Não | Local, deve ser definido explicitamente |
| OpenAI | `openai` | Sim | Detectado automaticamente, rápido |
| Voyage | `voyage` | Sim | Detectado automaticamente |
## Como a pesquisa funciona
@ -78,45 +79,35 @@ flowchart LR
M --> R["Top Results"]
```
- **Pesquisa vetorial** encontra notas com significado semelhante ("gateway host"
corresponde a "the machine running OpenClaw").
- **Pesquisa por palavra-chave BM25** encontra correspondências exatas (IDs,
strings de erro, chaves de configuração).
- **Pesquisa vetorial** encontra notas com significado semelhante ("gateway host" corresponde a
"the machine running OpenClaw").
- **Pesquisa por palavra-chave BM25** encontra correspondências exatas (IDs, strings de erro, chaves de configuração).
Se apenas um caminho estiver disponível (sem embeddings ou sem FTS), o outro será
executado sozinho.
Se apenas um caminho estiver disponível (sem embeddings ou sem FTS), o outro é executado sozinho.
Quando embeddings não estão disponíveis, o OpenClaw ainda usa ranqueamento lexical
sobre resultados de FTS em vez de recorrer apenas à ordenação bruta por
correspondência exata. Esse modo degradado impulsiona trechos com cobertura mais
forte dos termos da consulta e caminhos de arquivo relevantes, o que mantém a
revocação útil mesmo sem `sqlite-vec` ou um provedor de embedding.
Quando embeddings estão indisponíveis, o OpenClaw ainda usa ranqueamento lexical sobre resultados FTS em vez de recorrer apenas à ordenação bruta por correspondência exata. Esse modo degradado impulsiona trechos com cobertura mais forte dos termos da consulta e caminhos de arquivo relevantes, o que mantém a revocação útil mesmo sem `sqlite-vec` ou um provedor de embedding.
## Melhorando a qualidade da pesquisa
Dois recursos opcionais ajudam quando você tem um grande histórico de notas:
Dois recursos opcionais ajudam quando você tem um histórico grande de notas:
### Decaimento temporal
Notas antigas perdem peso de ranqueamento gradualmente para que informações
recentes apareçam primeiro. Com a meia-vida padrão de 30 dias, uma nota do mês
passado pontua com 50% do seu peso original. Arquivos permanentes como
`MEMORY.md` nunca sofrem decaimento.
Notas antigas perdem gradualmente peso de ranqueamento para que informações recentes apareçam primeiro.
Com a meia-vida padrão de 30 dias, uma nota do mês passado pontua 50% do
seu peso original. Arquivos perenes como `MEMORY.md` nunca sofrem decaimento.
<Tip>
Ative o decaimento temporal se o seu agente tiver meses de notas diárias e
informações obsoletas continuarem superando o contexto recente no ranqueamento.
Ative o decaimento temporal se o seu agente tiver meses de notas diárias e informações obsoletas continuarem ficando acima do contexto recente.
</Tip>
### MMR (diversidade)
Reduz resultados redundantes. Se cinco notas mencionarem a mesma configuração de
roteador, o MMR garante que os principais resultados cubram tópicos diferentes
em vez de repetir.
Reduz resultados redundantes. Se cinco notas mencionarem a mesma configuração de roteador, MMR
garante que os principais resultados cubram tópicos diferentes em vez de repetir.
<Tip>
Ative o MMR se `memory_search` continuar retornando snippets quase duplicados de
notas diárias diferentes.
Ative MMR se `memory_search` continuar retornando trechos quase duplicados de diferentes notas diárias.
</Tip>
### Ativar ambos
@ -141,29 +132,28 @@ notas diárias diferentes.
## Memória multimodal
Com o Gemini Embedding 2, você pode indexar imagens e arquivos de áudio junto com
Markdown. As consultas de pesquisa continuam sendo texto, mas correspondem a
conteúdo visual e de áudio. Consulte a [referência de configuração de memória](/pt-BR/reference/memory-config)
para a configuração.
Markdown. As consultas de pesquisa continuam sendo texto, mas correspondem a conteúdo visual e de áudio.
Consulte a [referência de configuração de memória](/pt-BR/reference/memory-config) para
configuração.
## Pesquisa na memória da sessão
## Pesquisa de memória de sessão
Opcionalmente, você pode indexar transcrições de sessão para que `memory_search`
consiga recordar conversas anteriores. Isso é opcional via
Você pode opcionalmente indexar transcrições de sessão para que `memory_search` possa lembrar
conversas anteriores. Isso é opcional via
`memorySearch.experimental.sessionMemory`. Consulte a
[referência de configuração](/pt-BR/reference/memory-config) para detalhes.
[referência de configuração](/pt-BR/reference/memory-config) para obter detalhes.
## Solução de problemas
**Sem resultados?** Execute `openclaw memory status` para verificar o índice. Se
estiver vazio, execute `openclaw memory index --force`.
**Sem resultados?** Execute `openclaw memory status` para verificar o índice. Se estiver vazio, execute
`openclaw memory index --force`.
**Apenas correspondências por palavra-chave?** Seu provedor de embedding pode não
estar configurado. Verifique `openclaw memory status --deep`.
**Apenas correspondências por palavra-chave?** Seu provedor de embedding pode não estar configurado. Verifique
`openclaw memory status --deep`.
**Embeddings locais expiram?** `ollama`, `lmstudio` e `local` usam um timeout
inline de lote mais longo por padrão. Se o host for simplesmente lento, defina
`agents.defaults.memorySearch.sync.embeddingBatchTimeoutSeconds` e execute
`openclaw memory index --force` novamente.
**Embeddings locais expiram?** `ollama`, `lmstudio` e `local` usam um tempo limite de lote inline mais longo por padrão. Se o host for simplesmente lento, defina
`agents.defaults.memorySearch.sync.embeddingBatchTimeoutSeconds` e execute novamente
`openclaw memory index --force`.
**Texto CJK não encontrado?** Reconstrua o índice FTS com
`openclaw memory index --force`.
@ -172,7 +162,7 @@ inline de lote mais longo por padrão. Se o host for simplesmente lento, defina
- [Active Memory](/pt-BR/concepts/active-memory) -- memória de subagente para sessões de chat interativas
- [Memória](/pt-BR/concepts/memory) -- layout de arquivos, backends, ferramentas
- [Referência de configuração de memória](/pt-BR/reference/memory-config) -- todas as opções de configuração
- [Referência de configuração de memória](/pt-BR/reference/memory-config) -- todos os controles de configuração
## Relacionado

121
docs/pt-BR/concepts/messages.md
View File

@ -1,20 +1,20 @@
---
read_when:
- Explicando como as mensagens recebidas se tornam respostas
- Explicando como mensagens recebidas se tornam respostas
- Esclarecendo sessões, modos de enfileiramento ou comportamento de transmissão contínua
- Documentando a visibilidade do raciocínio e as implicações de uso
summary: Fluxo de mensagens, sessões, enfileiramento e visibilidade do raciocínio
title: Mensagens
x-i18n:
generated_at: "2026-04-30T09:44:52Z"
generated_at: "2026-04-30T16:27:50Z"
model: gpt-5.5
provider: openai
source_hash: dcfcc995995516b627993755b255a779c681b4976d2d724c0c11e87875e37b1e
source_hash: fdeee014d92767a725501691fbe0c4ee6b631acc9a2ab5cbbcf321bfee9679b9
source_path: concepts/messages.md
workflow: 16
---
OpenClaw processa mensagens recebidas por meio de um pipeline de resolução de sessão, enfileiramento, streaming, execução de ferramentas e visibilidade de raciocínio. Esta página mapeia o caminho da mensagem recebida até a resposta.
OpenClaw lida com mensagens recebidas por meio de um pipeline de resolução de sessão, enfileiramento, streaming, execução de ferramentas e visibilidade de raciocínio. Esta página mapeia o caminho da mensagem recebida até a resposta.
## Fluxo de mensagens (alto nível)
@ -30,23 +30,23 @@ Os principais controles ficam na configuração:
- `messages.*` para prefixos, enfileiramento e comportamento de grupos.
- `agents.defaults.*` para padrões de streaming em blocos e fragmentação.
- Substituições por canal (`channels.whatsapp.*`, `channels.telegram.*` etc.) para limites e alternâncias de streaming.
- Sobrescritas de canal (`channels.whatsapp.*`, `channels.telegram.*` etc.) para limites e alternâncias de streaming.
Consulte [Configuração](/pt-BR/gateway/configuration) para ver o esquema completo.
## Deduplicação de recebimento
Canais podem reenviar a mesma mensagem após reconexões. OpenClaw mantém um
cache de curta duração indexado por canal/conta/par/sessão/ID da mensagem para que entregas
Canais podem reenviar a mesma mensagem após reconexões. O OpenClaw mantém um
cache de curta duração indexado por canal/conta/par/sessão/id da mensagem para que entregas
duplicadas não acionem outra execução do agente.
## Debouncing de recebimento
## Debounce de recebimento
Mensagens consecutivas rápidas do **mesmo remetente** podem ser agrupadas em uma única
rodada do agente via `messages.inbound`. O debouncing é escopado por canal + conversa
Mensagens consecutivas rápidas do **mesmo remetente** podem ser agrupadas em um único
turno do agente por meio de `messages.inbound`. O debounce tem escopo por canal + conversa
e usa a mensagem mais recente para encadeamento/IDs de resposta.
Configuração (padrão global + substituições por canal):
Configuração (padrão global + sobrescritas por canal):
```json5
{
@ -66,42 +66,45 @@ Configuração (padrão global + substituições por canal):
Observações:
- O debounce se aplica a mensagens **somente de texto**; mídia/anexos são liberados imediatamente.
- Comandos de controle ignoram o debouncing para permanecerem independentes — **exceto** quando um canal aceita explicitamente a agregação de DMs do mesmo remetente (por exemplo, [BlueBubbles `coalesceSameSenderDms`](/pt-BR/channels/bluebubbles#coalescing-split-send-dms-command--url-in-one-composition)), em que comandos de DM aguardam dentro da janela de debounce para que uma carga útil enviada em partes possa entrar na mesma rodada do agente.
- Comandos de controle ignoram o debounce para permanecerem autônomos — **exceto** quando um canal opta explicitamente por coalescência de DM do mesmo remetente (por exemplo, [BlueBubbles `coalesceSameSenderDms`](/pt-BR/channels/bluebubbles#coalescing-split-send-dms-command--url-in-one-composition)), em que comandos de DM aguardam dentro da janela de debounce para que uma carga útil enviada em partes possa entrar no mesmo turno do agente.
## Sessões e dispositivos
As sessões pertencem ao Gateway, não aos clientes.
As sessões pertencem ao gateway, não aos clientes.
- Conversas diretas são reduzidas à chave da sessão principal do agente.
- Conversas diretas são consolidadas na chave de sessão principal do agente.
- Grupos/canais recebem suas próprias chaves de sessão.
- O armazenamento de sessão e as transcrições ficam no host do Gateway.
- O armazenamento de sessões e as transcrições ficam no host do Gateway.
Vários dispositivos/canais podem mapear para a mesma sessão, mas o histórico não é totalmente
sincronizado de volta para todos os clientes. Recomendação: use um dispositivo principal para conversas
longas para evitar contexto divergente. A Control UI e a TUI sempre mostram a
transcrição da sessão respaldada pelo Gateway, portanto elas são a fonte da verdade.
longas a fim de evitar contexto divergente. A Control UI e a TUI sempre mostram a
transcrição da sessão respaldada pelo Gateway, portanto são a fonte da verdade.
Detalhes: [Gerenciamento de sessão](/pt-BR/concepts/session).
Detalhes: [Gerenciamento de sessões](/pt-BR/concepts/session).
## Metadados de resultado de ferramenta
O `content` do resultado de ferramenta é o resultado visível para o modelo. O `details` do resultado de ferramenta é
metadado de runtime para renderização na UI, diagnósticos, entrega de mídia e plugins.
`content` do resultado da ferramenta é o resultado visível para o modelo. `details` do resultado da ferramenta é
metadado de runtime para renderização de UI, diagnósticos, entrega de mídia e plugins.
OpenClaw mantém esse limite explícito:
O OpenClaw mantém esse limite explícito:
- `toolResult.details` é removido antes do replay do provedor e da entrada de Compaction.
- `toolResult.details` é removido antes de repetição pelo provedor e entrada de Compaction.
- Transcrições de sessão persistidas mantêm apenas `details` limitados; metadados grandes demais
são substituídos por um resumo compacto marcado com `persistedDetailsTruncated: true`.
são substituídos por um resumo compacto marcado como `persistedDetailsTruncated: true`.
- Plugins e ferramentas devem colocar o texto que o modelo precisa ler em `content`, não apenas
em `details`.
## Corpos de entrada e contexto do histórico
## Corpos recebidos e contexto de histórico
OpenClaw separa o **corpo do prompt** do **corpo do comando**:
O OpenClaw separa o **corpo do prompt** do **corpo do comando**:
- `Body`: texto do prompt enviado ao agente. Isso pode incluir envelopes do canal e
wrappers opcionais de histórico.
- `BodyForAgent`: texto primário voltado ao modelo para a mensagem atual. Plugins de canal
devem mantê-lo focado no texto atual do remetente que contém o prompt.
- `Body`: fallback legado de prompt. Ele pode incluir envelopes do canal e
wrappers opcionais de histórico, mas canais atuais não devem depender dele como
entrada primária do modelo quando `BodyForAgent` estiver disponível.
- `CommandBody`: texto bruto do usuário para análise de diretivas/comandos.
- `RawBody`: alias legado de `CommandBody` (mantido por compatibilidade).
@ -110,71 +113,73 @@ Quando um canal fornece histórico, ele usa um wrapper compartilhado:
- `[Chat messages since your last reply - for context]`
- `[Current message - respond to this]`
Para **conversas não diretas** (grupos/canais/salas), o **corpo da mensagem atual** é prefixado com o
rótulo do remetente (o mesmo estilo usado para entradas de histórico). Isso mantém mensagens em tempo real e mensagens
enfileiradas/de histórico consistentes no prompt do agente.
Para **conversas não diretas** (grupos/canais/salas), o **corpo da mensagem atual** recebe como prefixo o
rótulo do remetente (o mesmo estilo usado para entradas de histórico). Isso mantém mensagens em tempo real e mensagens enfileiradas/de histórico
consistentes no prompt do agente.
Buffers de histórico são **somente pendentes**: eles incluem mensagens de grupo que _não_
acionaram uma execução (por exemplo, mensagens bloqueadas por menção) e **excluem** mensagens
Buffers de histórico são **somente pendentes**: incluem mensagens de grupo que _não_
acionaram uma execução (por exemplo, mensagens controladas por menção) e **excluem** mensagens
já presentes na transcrição da sessão.
A remoção de diretivas se aplica apenas à seção da **mensagem atual**, para que o histórico
permaneça intacto. Canais que envolvem histórico devem definir `CommandBody` (ou
permaneça intacto. Canais que encapsulam histórico devem definir `CommandBody` (ou
`RawBody`) como o texto original da mensagem e manter `Body` como o prompt combinado.
Histórico estruturado, resposta, encaminhamento e metadados de canal são renderizados como
blocos de contexto não confiável no papel de usuário durante a montagem do prompt.
Buffers de histórico são configuráveis via `messages.groupChat.historyLimit` (padrão
global) e substituições por canal, como `channels.slack.historyLimit` ou
`channels.telegram.accounts.<id>.historyLimit` (defina `0` para desabilitar).
global) e sobrescritas por canal como `channels.slack.historyLimit` ou
`channels.telegram.accounts.<id>.historyLimit` (defina `0` para desativar).
## Enfileiramento e acompanhamentos
Se uma execução já estiver ativa, mensagens recebidas podem ser enfileiradas, direcionadas para a
execução atual ou coletadas para uma rodada de acompanhamento.
execução atual ou coletadas para um turno de acompanhamento.
- Configure via `messages.queue` (e `messages.queue.byChannel`).
- O modo padrão é `steer`, com um debounce de acompanhamento de 500 ms quando o direcionamento recai
para entrega de acompanhamento enfileirada.
- Modos: `steer`, `followup`, `collect`, `steer-backlog`, `interrupt` e o
modo legado `queue`, um por vez.
modo legado um-por-vez `queue`.
Detalhes: [Fila de comandos](/pt-BR/concepts/queue) e [Fila de direcionamento](/pt-BR/concepts/queue-steering).
## Propriedade da execução por canal
## Propriedade da execução do canal
Plugins de canal podem preservar a ordenação, aplicar debounce à entrada e aplicar contrapressão
de transporte antes que uma mensagem entre na fila da sessão. Eles não devem impor um
timeout separado ao redor da rodada do agente em si. Depois que uma mensagem é roteada para uma
timeout separado em torno do próprio turno do agente. Depois que uma mensagem é roteada para uma
sessão, trabalhos de longa duração são regidos pelo ciclo de vida da sessão, da ferramenta e do runtime,
para que todos os canais relatem e se recuperem de rodadas lentas de forma consistente.
para que todos os canais relatem e se recuperem de turnos lentos de forma consistente.
## Streaming, fragmentação e agrupamento
O streaming em blocos envia respostas parciais conforme o modelo produz blocos de texto.
A fragmentação respeita os limites de texto do canal e evita dividir código cercado.
Streaming em blocos envia respostas parciais conforme o modelo produz blocos de texto.
A fragmentação respeita os limites de texto do canal e evita dividir blocos de código cercados.
Principais configurações:
Configurações principais:
- `agents.defaults.blockStreamingDefault` (`on|off`, padrão off)
- `agents.defaults.blockStreamingDefault` (`on|off`, padrão desativado)
- `agents.defaults.blockStreamingBreak` (`text_end|message_end`)
- `agents.defaults.blockStreamingChunk` (`minChars|maxChars|breakPreference`)
- `agents.defaults.blockStreamingCoalesce` (agrupamento baseado em ociosidade)
- `agents.defaults.humanDelay` (pausa semelhante à humana entre respostas em blocos)
- Substituições por canal: `*.blockStreaming` e `*.blockStreamingCoalesce` (canais que não são Telegram exigem `*.blockStreaming: true` explícito)
- Sobrescritas de canal: `*.blockStreaming` e `*.blockStreamingCoalesce` (canais que não sejam Telegram exigem `*.blockStreaming: true` explícito)
Detalhes: [Streaming + fragmentação](/pt-BR/concepts/streaming).
## Visibilidade de raciocínio e tokens
OpenClaw pode expor ou ocultar o raciocínio do modelo:
O OpenClaw pode expor ou ocultar o raciocínio do modelo:
- `/reasoning on|off|stream` controla a visibilidade.
- O conteúdo de raciocínio ainda conta para o uso de tokens quando produzido pelo modelo.
- Telegram oferece suporte a fluxo de raciocínio no balão de rascunho.
- O Telegram oferece suporte a streaming de raciocínio no balão de rascunho.
Detalhes: [Diretivas de pensamento + raciocínio](/pt-BR/tools/thinking) e [Uso de tokens](/pt-BR/reference/token-use).
## Prefixos, encadeamento e respostas
A formatação de mensagens enviadas é centralizada em `messages`:
A formatação de mensagens de saída é centralizada em `messages`:
- `messages.responsePrefix`, `channels.<channel>.responsePrefix` e `channels.<channel>.accounts.<id>.responsePrefix` (cascata de prefixo de saída), além de `channels.whatsapp.messagePrefix` (prefixo de entrada do WhatsApp)
- Encadeamento de respostas via `replyToMode` e padrões por canal
@ -184,31 +189,31 @@ Detalhes: [Configuração](/pt-BR/gateway/config-agents#messages) e documentaç
## Respostas silenciosas
O token silencioso exato `NO_REPLY` / `no_reply` significa “não entregar uma resposta visível ao usuário”.
Quando uma rodada também tem mídia de ferramenta pendente, como áudio TTS gerado, OpenClaw
Quando um turno também tem mídia de ferramenta pendente, como áudio TTS gerado, o OpenClaw
remove o texto silencioso, mas ainda entrega o anexo de mídia.
OpenClaw resolve esse comportamento por tipo de conversa:
O OpenClaw resolve esse comportamento por tipo de conversa:
- Conversas diretas não permitem silêncio por padrão e reescrevem uma resposta
silenciosa isolada para uma alternativa curta visível.
silenciosa pura para um fallback curto e visível.
- Grupos/canais permitem silêncio por padrão.
- Orquestração interna permite silêncio por padrão.
OpenClaw também usa respostas silenciosas para falhas internas do executor que acontecem
O OpenClaw também usa respostas silenciosas para falhas internas do executor que acontecem
antes de qualquer resposta do assistente em conversas não diretas, para que grupos/canais não vejam
texto genérico de erro do Gateway. Conversas diretas mostram texto compacto de falha por padrão;
texto boilerplate de erro do gateway. Conversas diretas mostram texto compacto de falha por padrão;
detalhes brutos do executor são mostrados somente quando `/verbose` está `on` ou `full`.
Os padrões ficam em `agents.defaults.silentReply` e
`agents.defaults.silentReplyRewrite`; `surfaces.<id>.silentReply` e
`surfaces.<id>.silentReplyRewrite` podem substituí-los por superfície.
`surfaces.<id>.silentReplyRewrite` podem sobrescrevê-los por superfície.
Quando a sessão pai tem uma ou mais execuções pendentes de subagentes gerados, respostas
silenciosas isoladas são descartadas em todas as superfícies em vez de serem reescritas, para que o
pai permaneça silencioso até que o evento de conclusão do filho entregue a resposta real.
Quando a sessão pai tem uma ou mais execuções de subagente geradas pendentes, respostas
silenciosas puras são descartadas em todas as superfícies em vez de serem reescritas, para que o
pai permaneça quieto até que o evento de conclusão do filho entregue a resposta real.
## Relacionados
- [Streaming](/pt-BR/concepts/streaming) — entrega de mensagens em tempo real
- [Nova tentativa](/pt-BR/concepts/retry) — comportamento de nova tentativa de entrega de mensagens
- [Tentativa novamente](/pt-BR/concepts/retry) — comportamento de nova tentativa de entrega de mensagens
- [Fila](/pt-BR/concepts/queue) — fila de processamento de mensagens
- [Canais](/pt-BR/channels) — integrações com plataformas de mensagens

426
docs/pt-BR/gateway/config-agents.md
View File

@ -1,22 +1,22 @@
---
read_when:
- Ajuste dos padrões do agente (modelos, raciocínio, espaço de trabalho, Heartbeat, mídia, Skills)
- Configuração do roteamento e das vinculações multiagente
- Ajustando o comportamento de sessão, entrega de mensagens e modo de conversa
summary: Padrões do agente, roteamento multiagente, sessão, mensagens e configuração de conversa
- Configurando o roteamento e as vinculações de múltiplos agentes
- Ajustando o comportamento da sessão, da entrega de mensagens e do modo de conversa
summary: Padrões de agente, roteamento multiagente, sessão, mensagens e configuração de conversa
title: Configuração — agentes
x-i18n:
generated_at: "2026-04-30T09:47:20Z"
generated_at: "2026-04-30T16:27:55Z"
model: gpt-5.5
provider: openai
source_hash: 61f2d33ae1d3f4ce07636ae4584b9e344fd14e8e08a2612bb1f39ed71c99c25a
source_hash: e6a38f42c35c6c6e46d6d00ad710c6c80d78703e0b7e3388f5631cf91eb17084
source_path: gateway/config-agents.md
workflow: 16
---
Chaves de configuração com escopo de agente em `agents.*`, `multiAgent.*`, `session.*`,
Chaves de configuração no escopo de agente em `agents.*`, `multiAgent.*`, `session.*`,
`messages.*` e `talk.*`. Para canais, ferramentas, runtime do Gateway e outras
chaves de nível superior, consulte [Referência de configuração](/pt-BR/gateway/configuration-reference).
chaves de nível superior, consulte a [referência de configuração](/pt-BR/gateway/configuration-reference).
## Padrões do agente
@ -32,7 +32,7 @@ Padrão: `~/.openclaw/workspace`.
### `agents.defaults.repoRoot`
Raiz opcional do repositório exibida na linha Runtime do prompt do sistema. Se não for definida, o OpenClaw detecta automaticamente subindo a partir do workspace.
Raiz opcional do repositório mostrada na linha Runtime do prompt do sistema. Se não definido, o OpenClaw detecta automaticamente subindo a partir do workspace.
```json5
{
@ -42,7 +42,7 @@ Raiz opcional do repositório exibida na linha Runtime do prompt do sistema. Se
### `agents.defaults.skills`
Lista de permissão padrão opcional de Skills para agentes que não definem
Lista de permissões padrão opcional de Skills para agentes que não definem
`agents.list[].skills`.
```json5
@ -61,7 +61,7 @@ Lista de permissão padrão opcional de Skills para agentes que não definem
- Omita `agents.defaults.skills` para Skills irrestritas por padrão.
- Omita `agents.list[].skills` para herdar os padrões.
- Defina `agents.list[].skills: []` para não ter Skills.
- Uma lista `agents.list[].skills` não vazia é o conjunto final para esse agente; ela
- Uma lista não vazia em `agents.list[].skills` é o conjunto final para esse agente; ela
não é mesclada com os padrões.
### `agents.defaults.skipBootstrap`
@ -76,10 +76,10 @@ Desativa a criação automática de arquivos de bootstrap do workspace (`AGENTS.
### `agents.defaults.contextInjection`
Controla quando os arquivos de bootstrap do workspace são injetados no prompt do sistema. Padrão: `"always"`.
Controla quando arquivos de bootstrap do workspace são injetados no prompt do sistema. Padrão: `"always"`.
- `"continuation-skip"`: turnos de continuação seguros (após uma resposta concluída do assistente) pulam a reinjeção do bootstrap do workspace, reduzindo o tamanho do prompt. Execuções de Heartbeat e novas tentativas pós-Compaction ainda reconstroem o contexto.
- `"never"`: desativa o bootstrap do workspace e a injeção de arquivos de contexto em todos os turnos. Use isto apenas para agentes que controlam totalmente o ciclo de vida do próprio prompt (mecanismos de contexto personalizados, runtimes nativos que constroem seu próprio contexto ou fluxos de trabalho especializados sem bootstrap). Turnos de Heartbeat e de recuperação de Compaction também pulam a injeção.
- `"continuation-skip"`: turnos de continuação seguros (após uma resposta concluída do assistente) pulam a reinjeção do bootstrap do workspace, reduzindo o tamanho do prompt. Execuções de Heartbeat e tentativas pós-Compaction ainda reconstroem o contexto.
- `"never"`: desativa a injeção de bootstrap do workspace e de arquivos de contexto em todos os turnos. Use isso apenas para agentes que controlam totalmente o ciclo de vida do próprio prompt (mecanismos de contexto personalizados, runtimes nativos que constroem o próprio contexto ou fluxos de trabalho especializados sem bootstrap). Turnos de Heartbeat e de recuperação de Compaction também pulam a injeção.
```json5
{
@ -99,7 +99,7 @@ Máximo de caracteres por arquivo de bootstrap do workspace antes do truncamento
### `agents.defaults.bootstrapTotalMaxChars`
Máximo total de caracteres injetados em todos os arquivos de bootstrap do workspace. Padrão: `60000`.
Máximo total de caracteres injetados entre todos os arquivos de bootstrap do workspace. Padrão: `60000`.
```json5
{
@ -114,7 +114,7 @@ Padrão: `"once"`.
- `"off"`: nunca injeta texto de aviso no prompt do sistema.
- `"once"`: injeta o aviso uma vez por assinatura única de truncamento (recomendado).
- `"always"`: injeta o aviso em toda execução quando houver truncamento.
- `"always"`: injeta o aviso em toda execução quando há truncamento.
```json5
{
@ -122,25 +122,25 @@ Padrão: `"once"`.
}
```
### Mapa de propriedade do orçamento de contexto
### Mapa de propriedade dos orçamentos de contexto
O OpenClaw tem vários orçamentos de prompt/contexto de alto volume, e eles são
intencionalmente divididos por subsistema em vez de todos passarem por um único
intencionalmente divididos por subsistema, em vez de todos passarem por um único
controle genérico.
- `agents.defaults.bootstrapMaxChars` /
`agents.defaults.bootstrapTotalMaxChars`:
injeção normal de bootstrap do workspace.
- `agents.defaults.startupContext.*`:
preâmbulo de execução do modelo de reset/inicialização de uso único, incluindo arquivos diários recentes
`memory/*.md`. Comandos de chat simples `/new` e `/reset` são
preâmbulo único de execução do modelo em reset/inicialização, incluindo arquivos
`memory/*.md` diários recentes. Comandos simples de chat `/new` e `/reset` são
confirmados sem invocar o modelo.
- `skills.limits.*`:
a lista compacta de Skills injetada no prompt do sistema.
- `agents.defaults.contextLimits.*`:
trechos limitados de runtime e blocos injetados pertencentes ao runtime.
- `memory.qmd.limits.*`:
dimensionamento de snippet e injeção de busca de memória indexada.
dimensionamento do trecho de busca de memória indexada e da injeção.
Use a substituição correspondente por agente apenas quando um agente precisar de um
orçamento diferente:
@ -151,7 +151,7 @@ orçamento diferente:
#### `agents.defaults.startupContext`
Controla o preâmbulo de inicialização do primeiro turno injetado em execuções do modelo de reset/inicialização.
Comandos de chat simples `/new` e `/reset` confirmam o reset sem invocar
Comandos simples de chat `/new` e `/reset` confirmam o reset sem invocar
o modelo, portanto não carregam este preâmbulo.
```json5
@ -190,12 +190,12 @@ Padrões compartilhados para superfícies limitadas de contexto de runtime.
}
```
- `memoryGetMaxChars`: limite padrão de trecho de `memory_get` antes que os
metadados de truncamento e o aviso de continuação sejam adicionados.
- `memoryGetDefaultLines`: janela de linhas padrão de `memory_get` quando `lines` é
- `memoryGetMaxChars`: limite padrão do trecho de `memory_get` antes que metadados
de truncamento e aviso de continuação sejam adicionados.
- `memoryGetDefaultLines`: janela padrão de linhas de `memory_get` quando `lines` é
omitido.
- `toolResultMaxChars`: limite de resultado de ferramenta ao vivo usado para resultados persistidos e
recuperação de excedente.
recuperação de estouro.
- `postCompactionMaxChars`: limite de trecho de AGENTS.md usado durante a injeção de
atualização pós-Compaction.
@ -262,10 +262,10 @@ Substituição por agente para o orçamento do prompt de Skills.
### `agents.defaults.imageMaxDimensionPx`
Tamanho máximo em pixels para o maior lado da imagem em blocos de imagem de transcrição/ferramenta antes das chamadas ao provedor.
Tamanho máximo em pixels do maior lado da imagem em blocos de imagem de transcrição/ferramenta antes das chamadas ao provedor.
Padrão: `1200`.
Valores menores geralmente reduzem o uso de tokens de visão e o tamanho da carga útil da requisição para execuções com muitas capturas de tela.
Valores menores geralmente reduzem o uso de tokens de visão e o tamanho do payload da solicitação em execuções com muitas capturas de tela.
Valores maiores preservam mais detalhes visuais.
```json5
@ -276,7 +276,7 @@ Valores maiores preservam mais detalhes visuais.
### `agents.defaults.userTimezone`
Fuso horário para o contexto do prompt do sistema (não para carimbos de data/hora de mensagens). Recorre ao fuso horário do host.
Fuso horário para o contexto do prompt do sistema (não para timestamps de mensagens). Recorre ao fuso horário do host.
```json5
{
@ -345,58 +345,58 @@ Formato de hora no prompt do sistema. Padrão: `auto` (preferência do SO).
```
- `model`: aceita uma string (`"provider/model"`) ou um objeto (`{ primary, fallbacks }`).
- A forma em string define apenas o modelo primário.
- A forma em objeto define o primário mais modelos de failover ordenados.
- A forma de string define apenas o modelo primário.
- A forma de objeto define o primário mais modelos de failover ordenados.
- `imageModel`: aceita uma string (`"provider/model"`) ou um objeto (`{ primary, fallbacks }`).
- Usado pelo caminho da ferramenta `image` como sua configuração de modelo de visão.
- Também usado como roteamento de fallback quando o modelo selecionado/padrão não pode aceitar entrada de imagem.
- Prefira referências `provider/model` explícitas. IDs simples são aceitos por compatibilidade; se um ID simples corresponder exclusivamente a uma entrada configurada compatível com imagens em `models.providers.*.models`, o OpenClaw a qualifica para esse provedor. Correspondências configuradas ambíguas exigem um prefixo de provedor explícito.
- Também usado como roteamento de fallback quando o modelo selecionado/padrão não aceita entrada de imagem.
- Prefira refs explícitas `provider/model`. IDs simples são aceitos por compatibilidade; se um ID simples corresponder de forma única a uma entrada configurada com suporte a imagens em `models.providers.*.models`, o OpenClaw o qualifica para esse provedor. Correspondências configuradas ambíguas exigem um prefixo de provedor explícito.
- `imageGenerationModel`: aceita uma string (`"provider/model"`) ou um objeto (`{ primary, fallbacks }`).
- Usado pelo recurso compartilhado de geração de imagens e por qualquer superfície futura de ferramenta/Plugin que gere imagens.
- Valores típicos: `google/gemini-3.1-flash-image-preview` para geração de imagens nativa do Gemini, `fal/fal-ai/flux/dev` para fal, `openai/gpt-image-2` para OpenAI Images, ou `openai/gpt-image-1.5` para saída PNG/WebP da OpenAI com fundo transparente.
- Se você selecionar um provedor/modelo diretamente, configure também a autenticação correspondente do provedor (por exemplo, `GEMINI_API_KEY` ou `GOOGLE_API_KEY` para `google/*`, `OPENAI_API_KEY` ou OpenAI Codex OAuth para `openai/gpt-image-2` / `openai/gpt-image-1.5`, `FAL_KEY` para `fal/*`).
- Se omitido, `image_generate` ainda pode inferir um padrão de provedor com autenticação. Ele tenta primeiro o provedor padrão atual e depois os demais provedores registrados de geração de imagens na ordem de ID do provedor.
- Usado pela capacidade compartilhada de geração de imagens e por qualquer superfície futura de ferramenta/plugin que gere imagens.
- Valores típicos: `google/gemini-3.1-flash-image-preview` para geração nativa de imagens do Gemini, `fal/fal-ai/flux/dev` para fal, `openai/gpt-image-2` para OpenAI Images, ou `openai/gpt-image-1.5` para saída PNG/WebP da OpenAI com fundo transparente.
- Se você selecionar diretamente um provedor/modelo, configure também a autenticação correspondente do provedor (por exemplo, `GEMINI_API_KEY` ou `GOOGLE_API_KEY` para `google/*`, `OPENAI_API_KEY` ou OpenAI Codex OAuth para `openai/gpt-image-2` / `openai/gpt-image-1.5`, `FAL_KEY` para `fal/*`).
- Se omitido, `image_generate` ainda pode inferir um padrão de provedor respaldado por autenticação. Ele tenta primeiro o provedor padrão atual e depois os demais provedores registrados de geração de imagens em ordem de ID de provedor.
- `musicGenerationModel`: aceita uma string (`"provider/model"`) ou um objeto (`{ primary, fallbacks }`).
- Usado pelo recurso compartilhado de geração de música e pela ferramenta integrada `music_generate`.
- Usado pela capacidade compartilhada de geração de música e pela ferramenta integrada `music_generate`.
- Valores típicos: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview` ou `minimax/music-2.6`.
- Se omitido, `music_generate` ainda pode inferir um padrão de provedor com autenticação. Ele tenta primeiro o provedor padrão atual e depois os demais provedores registrados de geração de música na ordem de ID do provedor.
- Se você selecionar um provedor/modelo diretamente, configure também a autenticação/chave de API correspondente do provedor.
- Se omitido, `music_generate` ainda pode inferir um padrão de provedor respaldado por autenticação. Ele tenta primeiro o provedor padrão atual e depois os demais provedores registrados de geração de música em ordem de ID de provedor.
- Se você selecionar diretamente um provedor/modelo, configure também a autenticação/chave de API correspondente do provedor.
- `videoGenerationModel`: aceita uma string (`"provider/model"`) ou um objeto (`{ primary, fallbacks }`).
- Usado pelo recurso compartilhado de geração de vídeo e pela ferramenta integrada `video_generate`.
- Usado pela capacidade compartilhada de geração de vídeo e pela ferramenta integrada `video_generate`.
- Valores típicos: `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash` ou `qwen/wan2.7-r2v`.
- Se omitido, `video_generate` ainda pode inferir um padrão de provedor com autenticação. Ele tenta primeiro o provedor padrão atual e depois os demais provedores registrados de geração de vídeo na ordem de ID do provedor.
- Se você selecionar um provedor/modelo diretamente, configure também a autenticação/chave de API correspondente do provedor.
- O provedor de geração de vídeo Qwen incluído oferece suporte a até 1 vídeo de saída, 1 imagem de entrada, 4 vídeos de entrada, 10 segundos de duração e opções de nível de provedor `size`, `aspectRatio`, `resolution`, `audio` e `watermark`.
- Se omitido, `video_generate` ainda pode inferir um padrão de provedor respaldado por autenticação. Ele tenta primeiro o provedor padrão atual e depois os demais provedores registrados de geração de vídeo em ordem de ID de provedor.
- Se você selecionar diretamente um provedor/modelo, configure também a autenticação/chave de API correspondente do provedor.
- O provedor integrado de geração de vídeo Qwen oferece suporte a até 1 vídeo de saída, 1 imagem de entrada, 4 vídeos de entrada, duração de 10 segundos e opções de nível de provedor `size`, `aspectRatio`, `resolution`, `audio` e `watermark`.
- `pdfModel`: aceita uma string (`"provider/model"`) ou um objeto (`{ primary, fallbacks }`).
- Usado pela ferramenta `pdf` para roteamento de modelo.
- Se omitido, a ferramenta PDF faz fallback para `imageModel` e depois para o modelo resolvido da sessão/padrão.
- Se omitido, a ferramenta PDF usa como fallback `imageModel` e depois o modelo resolvido da sessão/padrão.
- `pdfMaxBytesMb`: limite padrão de tamanho de PDF para a ferramenta `pdf` quando `maxBytesMb` não é passado no momento da chamada.
- `pdfMaxPages`: número máximo padrão de páginas consideradas pelo modo de fallback de extração na ferramenta `pdf`.
- `verboseDefault`: nível verbose padrão para agentes. Valores: `"off"`, `"on"`, `"full"`. Padrão: `"off"`.
- `reasoningDefault`: visibilidade padrão de raciocínio para agentes. Valores: `"off"`, `"on"`, `"stream"`. `agents.list[].reasoningDefault` por agente substitui esse padrão. Padrões de raciocínio configurados só são aplicados para proprietários, remetentes autorizados ou contextos de Gateway de administrador-operador quando nenhuma substituição de raciocínio por mensagem ou sessão está definida.
- `verboseDefault`: nível verboso padrão para agentes. Valores: `"off"`, `"on"`, `"full"`. Padrão: `"off"`.
- `reasoningDefault`: visibilidade de raciocínio padrão para agentes. Valores: `"off"`, `"on"`, `"stream"`. `agents.list[].reasoningDefault` por agente substitui esse padrão. Padrões de raciocínio configurados só são aplicados para proprietários, remetentes autorizados ou contextos de Gateway de administrador-operador quando nenhuma substituição de raciocínio por mensagem ou por sessão está definida.
- `elevatedDefault`: nível padrão de saída elevada para agentes. Valores: `"off"`, `"on"`, `"ask"`, `"full"`. Padrão: `"on"`.
- `model.primary`: formato `provider/model` (por exemplo, `openai/gpt-5.5` para acesso com chave de API ou `openai-codex/gpt-5.5` para Codex OAuth). Se você omitir o provedor, o OpenClaw tenta primeiro um alias, depois uma correspondência única de provedor configurado para esse ID de modelo exato e só então faz fallback para o provedor padrão configurado (comportamento de compatibilidade obsoleto, portanto prefira `provider/model` explícito). Se esse provedor não expuser mais o modelo padrão configurado, o OpenClaw faz fallback para o primeiro provedor/modelo configurado em vez de expor um padrão obsoleto de provedor removido.
- `models`: o catálogo de modelos configurado e a allowlist para `/model`. Cada entrada pode incluir `alias` (atalho) e `params` (específicos do provedor, por exemplo `temperature`, `maxTokens`, `cacheRetention`, `context1m`, `responsesServerCompaction`, `responsesCompactThreshold`, `chat_template_kwargs`, `extra_body`/`extraBody`).
- Edições seguras: use `openclaw config set agents.defaults.models '<json>' --strict-json --merge` para adicionar entradas. `config set` recusa substituições que removeriam entradas existentes da allowlist, a menos que você passe `--replace`.
- Fluxos de configuração/onboarding com escopo de provedor mesclam modelos do provedor selecionado neste mapa e preservam provedores não relacionados já configurados.
- Para modelos diretos da OpenAI Responses, a compactação do lado do servidor é ativada automaticamente. Use `params.responsesServerCompaction: false` para parar de injetar `context_management`, ou `params.responsesCompactThreshold` para substituir o limite. Veja [compactação do lado do servidor da OpenAI](/pt-BR/providers/openai#server-side-compaction-responses-api).
- `params`: parâmetros globais padrão do provedor aplicados a todos os modelos. Definido em `agents.defaults.params` (por exemplo, `{ cacheRetention: "long" }`).
- Precedência de mesclagem de `params` (configuração): `agents.defaults.params` (base global) é substituído por `agents.defaults.models["provider/model"].params` (por modelo), depois `agents.list[].params` (ID de agente correspondente) substitui por chave. Veja [Prompt Caching](/pt-BR/reference/prompt-caching) para detalhes.
- `params.extra_body`/`params.extraBody`: JSON avançado de repasse mesclado nos corpos de solicitação `api: "openai-completions"` para proxies compatíveis com OpenAI. Se ele colidir com chaves de solicitação geradas, o corpo extra vence; rotas de completions não nativas ainda removem `store` exclusivo da OpenAI depois disso.
- `params.chat_template_kwargs`: argumentos de template de chat compatíveis com vLLM/OpenAI mesclados em corpos de solicitação `api: "openai-completions"` de nível superior. Para `vllm/nemotron-3-*` com pensamento desativado, o Plugin vLLM incluído envia automaticamente `enable_thinking: false` e `force_nonempty_content: true`; `chat_template_kwargs` explícito substitui padrões gerados, e `extra_body.chat_template_kwargs` ainda tem precedência final. Para controles de pensamento do vLLM Qwen, defina `params.qwenThinkingFormat` como `"chat-template"` ou `"top-level"` nessa entrada de modelo.
- `compat.supportedReasoningEfforts`: lista de esforço de raciocínio compatível com OpenAI por modelo. Inclua `"xhigh"` para endpoints personalizados que realmente o aceitam; o OpenClaw então expõe `/think xhigh` nos menus de comando, linhas de sessão do Gateway, validação de patch de sessão, validação de CLI de agente e validação de `llm-task` para esse provedor/modelo configurado. Use `compat.reasoningEffortMap` quando o backend quiser um valor específico do provedor para um nível canônico.
- `params.preserveThinking`: opt-in exclusivo da Z.AI para pensamento preservado. Quando ativado e o pensamento está ligado, o OpenClaw envia `thinking.clear_thinking: false` e reproduz o `reasoning_content` anterior; veja [pensamento e pensamento preservado da Z.AI](/pt-BR/providers/zai#thinking-and-preserved-thinking).
- `agentRuntime`: política padrão de runtime de agente de baixo nível. ID omitido usa o padrão OpenClaw Pi. Use `id: "pi"` para forçar o harness PI integrado, `id: "auto"` para permitir que harnesses de Plugin registrados assumam modelos compatíveis, um ID de harness registrado como `id: "codex"`, ou um alias de backend CLI compatível como `id: "claude-cli"`. Defina `fallback: "none"` para desativar o fallback automático para PI. Runtimes explícitos de Plugin, como `codex`, falham fechados por padrão, a menos que você defina `fallback: "pi"` no mesmo escopo de substituição. Mantenha referências de modelo canônicas como `provider/model`; selecione Codex, Claude CLI, Gemini CLI e outros backends de execução por meio da configuração de runtime em vez de prefixos legados de provedor de runtime. Veja [Runtimes de agente](/pt-BR/concepts/agent-runtimes) para entender como isso difere da seleção de provedor/modelo.
- Gravadores de configuração que alteram estes campos (por exemplo `/models set`, `/models set-image` e comandos de adicionar/remover fallback) salvam a forma canônica de objeto e preservam listas de fallback existentes quando possível.
- `model.primary`: formato `provider/model` (por exemplo, `openai/gpt-5.5` para acesso por chave de API ou `openai-codex/gpt-5.5` para Codex OAuth). Se você omitir o provedor, o OpenClaw tenta primeiro um alias, depois uma correspondência única de provedor configurado para esse ID de modelo exato e só então usa como fallback o provedor padrão configurado (comportamento de compatibilidade obsoleto, portanto prefira `provider/model` explícito). Se esse provedor não expuser mais o modelo padrão configurado, o OpenClaw usa como fallback o primeiro provedor/modelo configurado em vez de expor um padrão obsoleto de provedor removido.
- `models`: o catálogo de modelos configurado e a lista de permissões para `/model`. Cada entrada pode incluir `alias` (atalho) e `params` (específicos do provedor, por exemplo `temperature`, `maxTokens`, `cacheRetention`, `context1m`, `responsesServerCompaction`, `responsesCompactThreshold`, `chat_template_kwargs`, `extra_body`/`extraBody`).
- Edições seguras: use `openclaw config set agents.defaults.models '<json>' --strict-json --merge` para adicionar entradas. `config set` recusa substituições que removeriam entradas existentes da lista de permissões, a menos que você passe `--replace`.
- Fluxos de configuração/onboarding com escopo de provedor mesclam modelos do provedor selecionado nesse mapa e preservam provedores não relacionados já configurados.
- Para modelos diretos da OpenAI Responses, a compactação no lado do servidor é ativada automaticamente. Use `params.responsesServerCompaction: false` para parar de injetar `context_management`, ou `params.responsesCompactThreshold` para substituir o limite. Consulte [compactação no lado do servidor da OpenAI](/pt-BR/providers/openai#server-side-compaction-responses-api).
- `params`: parâmetros globais padrão de provedor aplicados a todos os modelos. Definido em `agents.defaults.params` (por exemplo, `{ cacheRetention: "long" }`).
- Precedência de mesclagem de `params` (configuração): `agents.defaults.params` (base global) é substituído por `agents.defaults.models["provider/model"].params` (por modelo), e então `agents.list[].params` (ID de agente correspondente) substitui por chave. Consulte [Cache de prompt](/pt-BR/reference/prompt-caching) para obter detalhes.
- `params.extra_body`/`params.extraBody`: JSON avançado de repasse mesclado em corpos de requisição `api: "openai-completions"` para proxies compatíveis com OpenAI. Se houver conflito com chaves de requisição geradas, o corpo extra prevalece; rotas de completions não nativas ainda removem `store` exclusivo da OpenAI depois.
- `params.chat_template_kwargs`: argumentos de template de chat compatíveis com vLLM/OpenAI mesclados em corpos de requisição de nível superior `api: "openai-completions"`. Para `vllm/nemotron-3-*` com pensamento desativado, o plugin vLLM integrado envia automaticamente `enable_thinking: false` e `force_nonempty_content: true`; `chat_template_kwargs` explícitos substituem padrões gerados, e `extra_body.chat_template_kwargs` ainda tem precedência final. Para controles de pensamento do vLLM Qwen, defina `params.qwenThinkingFormat` como `"chat-template"` ou `"top-level"` nessa entrada de modelo.
- `compat.supportedReasoningEfforts`: lista de esforço de raciocínio compatível com OpenAI por modelo. Inclua `"xhigh"` para endpoints personalizados que realmente aceitam esse valor; o OpenClaw então expõe `/think xhigh` em menus de comando, linhas de sessão do Gateway, validação de patch de sessão, validação da CLI de agente e validação de `llm-task` para esse provedor/modelo configurado. Use `compat.reasoningEffortMap` quando o backend exigir um valor específico de provedor para um nível canônico.
- `params.preserveThinking`: opção exclusiva da Z.AI para preservar pensamento. Quando ativada e o pensamento está ligado, o OpenClaw envia `thinking.clear_thinking: false` e reproduz `reasoning_content` anterior; consulte [pensamento e pensamento preservado da Z.AI](/pt-BR/providers/zai#thinking-and-preserved-thinking).
- `agentRuntime`: política padrão de runtime de agente de baixo nível. ID omitido usa como padrão o OpenClaw Pi. Use `id: "pi"` para forçar o harness PI integrado, `id: "auto"` para permitir que harnesses de plugins registrados reivindiquem modelos compatíveis, um ID de harness registrado como `id: "codex"`, ou um alias de backend de CLI compatível como `id: "claude-cli"`. Defina `fallback: "none"` para desativar o fallback automático para PI. Runtimes explícitos de plugin, como `codex`, falham de forma fechada por padrão, a menos que você defina `fallback: "pi"` no mesmo escopo de substituição. Mantenha refs de modelo canônicas como `provider/model`; selecione Codex, Claude CLI, Gemini CLI e outros backends de execução por meio da configuração de runtime em vez de prefixos legados de provedor de runtime. Consulte [runtimes de agente](/pt-BR/concepts/agent-runtimes) para saber como isso difere da seleção de provedor/modelo.
- Gravadores de configuração que alteram esses campos (por exemplo, `/models set`, `/models set-image` e comandos de adicionar/remover fallback) salvam a forma de objeto canônica e preservam listas de fallback existentes quando possível.
- `maxConcurrent`: máximo de execuções paralelas de agentes entre sessões (cada sessão ainda é serializada). Padrão: 4.
### `agents.defaults.agentRuntime`
`agentRuntime` controla qual executor de baixo nível executa turnos de agente. A maioria das
implantações deve manter o runtime padrão OpenClaw Pi. Use-o quando um
Plugin confiável fornecer um harness nativo, como o harness de app-server Codex incluído,
ou quando você quiser um backend CLI compatível, como Claude CLI. Para o modelo mental,
veja [Runtimes de agente](/pt-BR/concepts/agent-runtimes).
implantações deve manter o runtime padrão OpenClaw Pi. Use-o quando um plugin confiável
fornecer um harness nativo, como o harness integrado de servidor de app do Codex,
ou quando você quiser um backend de CLI compatível, como Claude CLI. Para o modelo
mental, consulte [runtimes de agente](/pt-BR/concepts/agent-runtimes).
```json5
{
@ -412,13 +412,13 @@ veja [Runtimes de agente](/pt-BR/concepts/agent-runtimes).
}
```
- `id`: `"auto"`, `"pi"`, um ID de harness de Plugin registrado ou um alias de backend CLI compatível. O Plugin Codex incluído registra `codex`; o Plugin Anthropic incluído fornece o backend CLI `claude-cli`.
- `fallback`: `"pi"` ou `"none"`. Em `id: "auto"`, fallback omitido usa `"pi"` como padrão para que configurações antigas possam continuar usando PI quando nenhum harness de Plugin assumir uma execução. No modo de runtime explícito de Plugin, como `id: "codex"`, fallback omitido usa `"none"` como padrão para que um harness ausente falhe em vez de usar PI silenciosamente. Substituições de runtime não herdam fallback de um escopo mais amplo; defina `fallback: "pi"` junto ao runtime explícito quando você quiser intencionalmente esse fallback de compatibilidade. Falhas do harness de Plugin selecionado sempre aparecem diretamente.
- Substituições de ambiente: `OPENCLAW_AGENT_RUNTIME=<id|auto|pi>` substitui `id`; `OPENCLAW_AGENT_HARNESS_FALLBACK=pi|none` substitui o fallback para esse processo.
- Para implantações somente com Codex, defina `model: "openai/gpt-5.5"` e `agentRuntime.id: "codex"`. Você também pode definir `agentRuntime.fallback: "none"` explicitamente para legibilidade; ele é o padrão para runtimes explícitos de Plugin.
- Para implantações com Claude CLI, prefira `model: "anthropic/claude-opus-4-7"` mais `agentRuntime.id: "claude-cli"`. Referências de modelo legadas `claude-cli/claude-opus-4-7` ainda funcionam por compatibilidade, mas novas configurações devem manter a seleção de provedor/modelo canônica e colocar o backend de execução em `agentRuntime.id`.
- Chaves de política de runtime mais antigas são reescritas para `agentRuntime` por `openclaw doctor --fix`.
- A escolha do harness fica fixada por ID de sessão após a primeira execução incorporada. Alterações de configuração/env afetam sessões novas ou redefinidas, não uma transcrição existente. Sessões legadas com histórico de transcrição, mas sem fixação registrada, são tratadas como fixadas em PI. `/status` relata o runtime efetivo, por exemplo `Runtime: OpenClaw Pi Default` ou `Runtime: OpenAI Codex`.
- `id`: `"auto"`, `"pi"`, um ID de harness de plugin registrado ou um alias de backend de CLI compatível. O plugin Codex integrado registra `codex`; o plugin Anthropic integrado fornece o backend de CLI `claude-cli`.
- `fallback`: `"pi"` ou `"none"`. Em `id: "auto"`, fallback omitido usa como padrão `"pi"` para que configurações antigas possam continuar usando PI quando nenhum harness de plugin reivindicar uma execução. No modo de runtime de plugin explícito, como `id: "codex"`, fallback omitido usa como padrão `"none"` para que um harness ausente falhe em vez de usar PI silenciosamente. Substituições de runtime não herdam fallback de um escopo mais amplo; defina `fallback: "pi"` junto do runtime explícito quando você quiser intencionalmente esse fallback de compatibilidade. Falhas do harness de plugin selecionado sempre são exibidas diretamente.
- Substituições de ambiente: `OPENCLAW_AGENT_RUNTIME=<id|auto|pi>` substitui `id`; `OPENCLAW_AGENT_HARNESS_FALLBACK=pi|none` substitui fallback para esse processo.
- Para implantações somente com Codex, defina `model: "openai/gpt-5.5"` e `agentRuntime.id: "codex"`. Você também pode definir `agentRuntime.fallback: "none"` explicitamente para legibilidade; esse é o padrão para runtimes de plugin explícitos.
- Para implantações com Claude CLI, prefira `model: "anthropic/claude-opus-4-7"` mais `agentRuntime.id: "claude-cli"`. Refs de modelo legadas `claude-cli/claude-opus-4-7` ainda funcionam por compatibilidade, mas novas configurações devem manter a seleção de provedor/modelo canônica e colocar o backend de execução em `agentRuntime.id`.
- Chaves mais antigas de política de runtime são reescritas para `agentRuntime` por `openclaw doctor --fix`.
- A escolha de harness é fixada por ID de sessão depois da primeira execução incorporada. Alterações de configuração/ambiente afetam sessões novas ou redefinidas, não uma transcrição existente. Sessões legadas com histórico de transcrição, mas sem pin registrado, são tratadas como fixadas em PI. `/status` informa o runtime efetivo, por exemplo `Runtime: OpenClaw Pi Default` ou `Runtime: OpenAI Codex`.
- Isso controla apenas a execução de turnos de agente de texto. Geração de mídia, visão, PDF, música, vídeo e TTS ainda usam suas configurações de provedor/modelo.
**Atalhos de alias integrados** (aplicam-se somente quando o modelo está em `agents.defaults.models`):
@ -427,22 +427,22 @@ veja [Runtimes de agente](/pt-BR/concepts/agent-runtimes).
| ------------------- | ------------------------------------------ |
| `opus` | `anthropic/claude-opus-4-6` |
| `sonnet` | `anthropic/claude-sonnet-4-6` |
| `gpt` | `openai/gpt-5.5` or `openai-codex/gpt-5.5` |
| `gpt` | `openai/gpt-5.5` ou `openai-codex/gpt-5.5` |
| `gpt-mini` | `openai/gpt-5.4-mini` |
| `gpt-nano` | `openai/gpt-5.4-nano` |
| `gemini` | `google/gemini-3.1-pro-preview` |
| `gemini-flash` | `google/gemini-3-flash-preview` |
| `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` |
Seus aliases configurados sempre têm precedência sobre os padrões.
Seus apelidos configurados sempre prevalecem sobre os padrões.
Modelos Z.AI GLM-4.x ativam automaticamente o modo de raciocínio, a menos que você defina `--thinking off` ou defina `agents.defaults.models["zai/<model>"].params.thinking` por conta própria.
Modelos Z.AI ativam `tool_stream` por padrão para streaming de chamadas de ferramenta. Defina `agents.defaults.models["zai/<model>"].params.tool_stream` como `false` para desativá-lo.
Modelos Anthropic Claude 4.6 usam `adaptive` como padrão para raciocínio quando nenhum nível de raciocínio explícito é definido.
Modelos Anthropic Claude 4.6 usam `adaptive` como raciocínio padrão quando nenhum nível explícito de raciocínio está definido.
### `agents.defaults.cliBackends`
Backends de CLI opcionais para execuções de fallback somente texto (sem chamadas de ferramenta). Úteis como backup quando provedores de API falham.
Backends CLI opcionais para execuções de fallback somente em texto (sem chamadas de ferramentas). Útil como backup quando provedores de API falham.
```json5
{
@ -471,13 +471,13 @@ Backends de CLI opcionais para execuções de fallback somente texto (sem chamad
}
```
- Backends de CLI priorizam texto; ferramentas sempre ficam desativadas.
- Backends CLI são centrados em texto; ferramentas estão sempre desativadas.
- Sessões são compatíveis quando `sessionArg` está definido.
- Repasse de imagens é compatível quando `imageArg` aceita caminhos de arquivos.
- Repasse de imagens é compatível quando `imageArg` aceita caminhos de arquivo.
### `agents.defaults.systemPromptOverride`
Substitui todo o prompt de sistema montado pelo OpenClaw por uma string fixa. Defina no nível padrão (`agents.defaults.systemPromptOverride`) ou por agente (`agents.list[].systemPromptOverride`). Valores por agente têm precedência; um valor vazio ou contendo apenas espaços em branco é ignorado. Útil para experimentos de prompt controlados.
Substitui todo o prompt do sistema montado pelo OpenClaw por uma string fixa. Defina no nível padrão (`agents.defaults.systemPromptOverride`) ou por agente (`agents.list[].systemPromptOverride`). Valores por agente têm precedência; um valor vazio ou contendo apenas espaços em branco é ignorado. Útil para experimentos controlados de prompt.
```json5
{
@ -542,14 +542,14 @@ Execuções periódicas de Heartbeat.
```
- `every`: string de duração (ms/s/m/h). Padrão: `30m` (autenticação por chave de API) ou `1h` (autenticação OAuth). Defina como `0m` para desativar.
- `includeSystemPromptSection`: quando falso, omite a seção Heartbeat do prompt de sistema e ignora a injeção de `HEARTBEAT.md` no contexto de bootstrap. Padrão: `true`.
- `suppressToolErrorWarnings`: quando verdadeiro, suprime payloads de aviso de erro de ferramenta durante execuções de Heartbeat.
- `timeoutSeconds`: tempo máximo em segundos permitido para um turno de agente de Heartbeat antes de ele ser abortado. Deixe indefinido para usar `agents.defaults.timeoutSeconds`.
- `directPolicy`: política de entrega direta/DM. `allow` (padrão) permite entrega para destino direto. `block` suprime entrega para destino direto e emite `reason=dm-blocked`.
- `lightContext`: quando verdadeiro, execuções de Heartbeat usam contexto de bootstrap leve e mantêm apenas `HEARTBEAT.md` dos arquivos de bootstrap do workspace.
- `isolatedSession`: quando verdadeiro, cada Heartbeat roda em uma sessão nova, sem histórico de conversa anterior. Mesmo padrão de isolamento que cron `sessionTarget: "isolated"`. Reduz o custo de tokens por Heartbeat de ~100K para ~2-5K tokens.
- `skipWhenBusy`: quando verdadeiro, execuções de Heartbeat são adiadas em lanes ocupadas extras: trabalho de subagente ou comando aninhado. Lanes de Cron sempre adiam Heartbeats, mesmo sem esta flag.
- Por agente: defina `agents.list[].heartbeat`. Quando qualquer agente define `heartbeat`, **somente esses agentes** executam Heartbeats.
- `includeSystemPromptSection`: quando falso, omite a seção Heartbeat do prompt do sistema e pula a injeção de `HEARTBEAT.md` no contexto de bootstrap. Padrão: `true`.
- `suppressToolErrorWarnings`: quando verdadeiro, suprime payloads de aviso de erro de ferramenta durante execuções de heartbeat.
- `timeoutSeconds`: tempo máximo em segundos permitido para um turno de agente de heartbeat antes que ele seja abortado. Deixe indefinido para usar `agents.defaults.timeoutSeconds`.
- `directPolicy`: política de entrega direta/DM. `allow` (padrão) permite entrega para destino direto. `block` suprime a entrega para destino direto e emite `reason=dm-blocked`.
- `lightContext`: quando verdadeiro, execuções de heartbeat usam contexto de bootstrap leve e mantêm apenas `HEARTBEAT.md` dos arquivos de bootstrap do workspace.
- `isolatedSession`: quando verdadeiro, cada heartbeat é executado em uma sessão nova sem histórico de conversa anterior. Mesmo padrão de isolamento que cron `sessionTarget: "isolated"`. Reduz o custo de tokens por heartbeat de ~100K para ~2-5K tokens.
- `skipWhenBusy`: quando verdadeiro, execuções de heartbeat são adiadas em lanes ocupadas extras: trabalho de subagente ou comando aninhado. Lanes de Cron sempre adiam heartbeats, mesmo sem esta flag.
- Por agente: defina `agents.list[].heartbeat`. Quando qualquer agente define `heartbeat`, **somente esses agentes** executam heartbeats.
- Heartbeats executam turnos completos de agente — intervalos mais curtos consomem mais tokens.
### `agents.defaults.compaction`
@ -567,6 +567,7 @@ Execuções periódicas de Heartbeat.
identifierPolicy: "strict", // strict | off | custom
identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // used when identifierPolicy=custom
qualityGuard: { enabled: true, maxRetries: 1 },
midTurnPrecheck: { enabled: false }, // optional Pi tool-loop pressure check
postCompactionSections: ["Session Startup", "Red Lines"], // [] disables reinjection
model: "openrouter/anthropic/claude-sonnet-4-6", // optional compaction-only model override
truncateAfterCompaction: true, // rotate to a smaller successor JSONL after compaction
@ -585,22 +586,23 @@ Execuções periódicas de Heartbeat.
}
```
- `mode`: `default` ou `safeguard` (resumo em chunks para históricos longos). Veja [Compaction](/pt-BR/concepts/compaction).
- `provider`: id de um Plugin de provedor de Compaction registrado. Quando definido, o `summarize()` do provedor é chamado em vez do resumo LLM integrado. Recorre ao integrado em caso de falha. Definir um provedor força `mode: "safeguard"`. Veja [Compaction](/pt-BR/concepts/compaction).
- `timeoutSeconds`: máximo de segundos permitido para uma única operação de Compaction antes que o OpenClaw a aborte. Padrão: `900`.
- `keepRecentTokens`: orçamento de ponto de corte do Pi para manter literalmente a cauda mais recente da transcrição. `/compact` manual respeita isso quando definido explicitamente; caso contrário, a Compaction manual é um checkpoint rígido.
- `identifierPolicy`: `strict` (padrão), `off` ou `custom`. `strict` antepõe orientações integradas de retenção de identificadores opacos durante o resumo de Compaction.
- `mode`: `default` ou `safeguard` (sumarização em chunks para históricos longos). Consulte [Compaction](/pt-BR/concepts/compaction).
- `provider`: id de um Plugin provedor de compaction registrado. Quando definido, o `summarize()` do provedor é chamado em vez da sumarização LLM integrada. Recorre ao integrado em caso de falha. Definir um provedor força `mode: "safeguard"`. Consulte [Compaction](/pt-BR/concepts/compaction).
- `timeoutSeconds`: máximo de segundos permitido para uma única operação de compaction antes que o OpenClaw a aborte. Padrão: `900`.
- `keepRecentTokens`: orçamento de ponto de corte do Pi para manter literalmente a cauda mais recente do transcript. `/compact` manual respeita isto quando definido explicitamente; caso contrário, a compaction manual é um checkpoint rígido.
- `identifierPolicy`: `strict` (padrão), `off` ou `custom`. `strict` antepõe orientações integradas de retenção de identificadores opacos durante a sumarização de compaction.
- `identifierInstructions`: texto personalizado opcional de preservação de identificadores usado quando `identifierPolicy=custom`.
- `qualityGuard`: verificações de nova tentativa em saída malformada para resumos safeguard. Ativado por padrão no modo safeguard; defina `enabled: false` para ignorar a auditoria.
- `postCompactionSections`: nomes opcionais de seções H2/H3 de AGENTS.md a reinjetar após a Compaction. O padrão é `["Session Startup", "Red Lines"]`; defina `[]` para desativar a reinjeção. Quando não definido ou definido explicitamente para esse par padrão, os títulos antigos `Every Session`/`Safety` também são aceitos como fallback legado.
- `model`: substituição opcional `provider/model-id` apenas para resumo de Compaction. Use isto quando a sessão principal deve manter um modelo, mas os resumos de Compaction devem rodar em outro; quando não definido, a Compaction usa o modelo primário da sessão.
- `maxActiveTranscriptBytes`: limite opcional em bytes (`number` ou strings como `"20mb"`) que aciona a Compaction local normal antes de uma execução quando o JSONL ativo ultrapassa o limite. Requer `truncateAfterCompaction` para que uma Compaction bem-sucedida possa alternar para uma transcrição sucessora menor. Desativado quando não definido ou `0`.
- `notifyUser`: quando `true`, envia avisos breves ao usuário quando a Compaction começa e quando ela termina (por exemplo, "Compactando contexto..." e "Compaction concluída"). Desativado por padrão para manter a Compaction silenciosa.
- `memoryFlush`: turno agêntico silencioso antes da Compaction automática para armazenar memórias duráveis. Defina `model` como um provedor/modelo exato, como `ollama/qwen3:8b`, quando este turno de manutenção deve permanecer em um modelo local; a substituição não herda a cadeia de fallback da sessão ativa. Ignorado quando o workspace é somente leitura.
- `qualityGuard`: verificações de tentar novamente em caso de saída malformada para resumos safeguard. Ativado por padrão no modo safeguard; defina `enabled: false` para pular a auditoria.
- `midTurnPrecheck`: verificação opcional de pressão do loop de ferramentas do Pi. Quando `enabled: true`, o OpenClaw verifica a pressão de contexto depois que resultados de ferramentas são anexados e antes da próxima chamada de modelo. Se o contexto não couber mais, ele aborta a tentativa atual antes de enviar o prompt e reutiliza o caminho de recuperação de pré-verificação existente para truncar resultados de ferramentas ou compactar e tentar novamente. Funciona com os modos de compaction `default` e `safeguard`. Padrão: desativado.
- `postCompactionSections`: nomes opcionais de seções H2/H3 de AGENTS.md para reinjetar depois da compaction. O padrão é `["Session Startup", "Red Lines"]`; defina `[]` para desativar a reinjeção. Quando indefinido ou definido explicitamente como esse par padrão, os cabeçalhos antigos `Every Session`/`Safety` também são aceitos como fallback legado.
- `model`: substituição opcional `provider/model-id` somente para sumarização de compaction. Use isto quando a sessão principal deve manter um modelo, mas os resumos de compaction devem ser executados em outro; quando indefinido, a compaction usa o modelo primário da sessão.
- `maxActiveTranscriptBytes`: limite opcional de bytes (`number` ou strings como `"20mb"`) que aciona compaction local normal antes de uma execução quando o JSONL ativo ultrapassa o limite. Requer `truncateAfterCompaction` para que uma compaction bem-sucedida possa rotacionar para um transcript sucessor menor. Desativado quando indefinido ou `0`.
- `notifyUser`: quando `true`, envia avisos breves ao usuário quando a compaction começa e quando termina (por exemplo, "Compacting context..." e "Compaction complete"). Desativado por padrão para manter a compaction silenciosa.
- `memoryFlush`: turno agentivo silencioso antes da compaction automática para armazenar memórias duráveis. Defina `model` como um provedor/modelo exato, como `ollama/qwen3:8b`, quando este turno de manutenção deve permanecer em um modelo local; a substituição não herda a cadeia de fallback da sessão ativa. Ignorado quando o workspace é somente leitura.
### `agents.defaults.contextPruning`
Remove **resultados antigos de ferramentas** do contexto em memória antes de enviar ao LLM. **Não** modifica o histórico da sessão no disco.
Remove **resultados antigos de ferramentas** do contexto em memória antes de enviar ao LLM. **Não** modifica o histórico da sessão em disco.
```json5
{
@ -622,27 +624,27 @@ Remove **resultados antigos de ferramentas** do contexto em memória antes de en
}
```
<Accordion title="comportamento do modo cache-ttl">
<Accordion title="cache-ttl mode behavior">
- `mode: "cache-ttl"` ativa passes de poda.
- `ttl` controla com que frequência a poda pode rodar novamente (após o último toque no cache).
- A poda primeiro aplica soft-trim a resultados de ferramenta grandes demais e depois faz hard-clear de resultados de ferramenta mais antigos se necessário.
- `mode: "cache-ttl"` ativa passagens de poda.
- `ttl` controla com que frequência a poda pode ser executada novamente (depois do último toque no cache).
- A poda primeiro faz soft-trim em resultados de ferramentas grandes demais, depois faz hard-clear em resultados de ferramentas mais antigos se necessário.
**Soft-trim** mantém o começo + fim e insere `...` no meio.
**Hard-clear** substitui todo o resultado da ferramenta pelo placeholder.
Observações:
Notas:
- Blocos de imagem nunca são aparados/removidos.
- Blocos de imagem nunca são truncados/removidos.
- Proporções são baseadas em caracteres (aproximadas), não em contagens exatas de tokens.
- Se houver menos de `keepLastAssistants` mensagens de assistente, a poda é ignorada.
- Se houver menos de `keepLastAssistants` mensagens do assistente, a poda é ignorada.
</Accordion>
Veja [Poda de sessão](/pt-BR/concepts/session-pruning) para detalhes de comportamento.
Consulte [Poda de sessão](/pt-BR/concepts/session-pruning) para detalhes de comportamento.
### Streaming em blocos
### Streaming de blocos
```json5
{
@ -658,11 +660,11 @@ Veja [Poda de sessão](/pt-BR/concepts/session-pruning) para detalhes de comport
}
```
- Canais que não sejam Telegram exigem `*.blockStreaming: true` explícito para ativar respostas em bloco.
- Substituições de canal: `channels.<channel>.blockStreamingCoalesce` (e variantes por conta). Signal/Slack/Discord/Google Chat usam `minChars: 1500` por padrão.
- `humanDelay`: pausa aleatória entre respostas em bloco. `natural` = 800–2500ms. Substituição por agente: `agents.list[].humanDelay`.
- Canais que não sejam Telegram exigem `*.blockStreaming: true` explícito para habilitar respostas em bloco.
- Substituições por canal: `channels.<channel>.blockStreamingCoalesce` (e variantes por conta). Signal/Slack/Discord/Google Chat usam `minChars: 1500` por padrão.
- `humanDelay`: pausa aleatória entre respostas em bloco. `natural` = 800–2500 ms. Substituição por agente: `agents.list[].humanDelay`.
Veja [Streaming](/pt-BR/concepts/streaming) para comportamento + detalhes de divisão em chunks.
Consulte [Streaming](/pt-BR/concepts/streaming) para detalhes de comportamento e divisão em partes.
### Indicadores de digitação
@ -686,7 +688,7 @@ Consulte [Indicadores de Digitação](/pt-BR/concepts/typing-indicators).
### `agents.defaults.sandbox`
Isolamento em sandbox opcional para o agente incorporado. Consulte [Isolamento em Sandbox](/pt-BR/gateway/sandboxing) para o guia completo.
Isolamento em sandbox opcional para o agente embutido. Consulte [Isolamento em sandbox](/pt-BR/gateway/sandboxing) para o guia completo.
```json5
{
@ -787,9 +789,9 @@ Isolamento em sandbox opcional para o agente incorporado. Consulte [Isolamento e
- `docker`: runtime local do Docker (padrão)
- `ssh`: runtime remoto genérico baseado em SSH
- `openshell`: runtime OpenShell
- `openshell`: runtime do OpenShell
Quando `backend: "openshell"` é selecionado, as configurações específicas de runtime passam para
Quando `backend: "openshell"` é selecionado, as configurações específicas do runtime passam para
`plugins.entries.openshell.config`.
**Configuração do backend SSH:**
@ -797,20 +799,20 @@ Quando `backend: "openshell"` é selecionado, as configurações específicas de
- `target`: destino SSH no formato `user@host[:port]`
- `command`: comando do cliente SSH (padrão: `ssh`)
- `workspaceRoot`: raiz remota absoluta usada para workspaces por escopo
- `identityFile` / `certificateFile` / `knownHostsFile`: arquivos locais existentes passados para o OpenSSH
- `identityData` / `certificateData` / `knownHostsData`: conteúdo inline ou SecretRefs que o OpenClaw materializa em arquivos temporários em runtime
- `identityFile` / `certificateFile` / `knownHostsFile`: arquivos locais existentes passados ao OpenSSH
- `identityData` / `certificateData` / `knownHostsData`: conteúdos inline ou SecretRefs que o OpenClaw materializa em arquivos temporários em tempo de execução
- `strictHostKeyChecking` / `updateHostKeys`: controles de política de chave de host do OpenSSH
**Precedência de autenticação SSH:**
- `identityData` prevalece sobre `identityFile`
- `certificateData` prevalece sobre `certificateFile`
- `knownHostsData` prevalece sobre `knownHostsFile`
- `identityData` tem precedência sobre `identityFile`
- `certificateData` tem precedência sobre `certificateFile`
- `knownHostsData` tem precedência sobre `knownHostsFile`
- Valores `*Data` baseados em SecretRef são resolvidos a partir do snapshot ativo do runtime de segredos antes do início da sessão de sandbox
**Comportamento do backend SSH:**
- propaga o workspace remoto uma vez após a criação ou recriação
- inicializa o workspace remoto uma vez após criação ou recriação
- depois mantém o workspace SSH remoto como canônico
- roteia `exec`, ferramentas de arquivo e caminhos de mídia por SSH
- não sincroniza alterações remotas de volta para o host automaticamente
@ -854,31 +856,31 @@ Quando `backend: "openshell"` é selecionado, as configurações específicas de
}
```
**Modo OpenShell:**
**Modo do OpenShell:**
- `mirror`: propaga o remoto a partir do local antes de exec, sincroniza de volta após exec; o workspace local permanece canônico
- `remote`: propaga o remoto uma vez quando a sandbox é criada e depois mantém o workspace remoto como canônico
- `mirror`: inicializa o remoto a partir do local antes de executar, sincroniza de volta após executar; o workspace local permanece canônico
- `remote`: inicializa o remoto uma vez quando a sandbox é criada e depois mantém o workspace remoto como canônico
No modo `remote`, edições locais no host feitas fora do OpenClaw não são sincronizadas automaticamente para a sandbox após a etapa de propagação.
O transporte é SSH para dentro da sandbox OpenShell, mas o Plugin é responsável pelo ciclo de vida da sandbox e pela sincronização espelhada opcional.
No modo `remote`, edições locais no host feitas fora do OpenClaw não são sincronizadas automaticamente para a sandbox após a etapa de inicialização.
O transporte é SSH para a sandbox OpenShell, mas o Plugin controla o ciclo de vida da sandbox e a sincronização espelhada opcional.
**`setupCommand`** é executado uma vez após a criação do contêiner (via `sh -lc`). Precisa de saída de rede, raiz gravável e usuário root.
**`setupCommand`** é executado uma vez após a criação do contêiner (via `sh -lc`). Requer saída de rede, raiz gravável e usuário root.
**Os contêineres usam `network: "none"` por padrão** — defina como `"bridge"` (ou uma rede bridge personalizada) se o agente precisar de acesso de saída.
**Contêineres usam `network: "none"` por padrão** — defina como `"bridge"` (ou uma rede bridge personalizada) se o agente precisar de acesso externo.
`"host"` é bloqueado. `"container:<id>"` é bloqueado por padrão, a menos que você defina explicitamente
`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (emergência).
`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (último recurso).
**Anexos de entrada** são preparados em `media/inbound/*` no workspace ativo.
**`docker.binds`** monta diretórios adicionais do host; binds globais e por agente são mesclados.
**`docker.binds`** monta diretórios adicionais do host; vínculos globais e por agente são mesclados.
**Navegador em sandbox** (`sandbox.browser.enabled`): Chromium + CDP em um contêiner. URL noVNC injetada no prompt do sistema. Não requer `browser.enabled` em `openclaw.json`.
O acesso de observador noVNC usa autenticação VNC por padrão, e o OpenClaw emite uma URL de token de curta duração (em vez de expor a senha na URL compartilhada).
**Navegador em sandbox** (`sandbox.browser.enabled`): Chromium + CDP em um contêiner. URL do noVNC injetada no prompt do sistema. Não requer `browser.enabled` em `openclaw.json`.
O acesso de observador noVNC usa autenticação VNC por padrão, e o OpenClaw emite uma URL com token de curta duração (em vez de expor a senha na URL compartilhada).
- `allowHostControl: false` (padrão) impede que sessões em sandbox tenham como alvo o navegador do host.
- `network` usa `openclaw-sandbox-browser` por padrão (rede bridge dedicada). Defina como `bridge` apenas quando você quiser explicitamente conectividade bridge global.
- `cdpSourceRange` restringe opcionalmente a entrada CDP na borda do contêiner a um intervalo CIDR (por exemplo, `172.21.0.1/32`).
- `sandbox.browser.binds` monta diretórios adicionais do host apenas no contêiner do navegador em sandbox. Quando definido (incluindo `[]`), substitui `docker.binds` para o contêiner do navegador.
- `allowHostControl: false` (padrão) impede sessões em sandbox de direcionar o navegador do host.
- `network` usa `openclaw-sandbox-browser` por padrão (rede bridge dedicada). Defina como `bridge` somente quando quiser explicitamente conectividade bridge global.
- `cdpSourceRange` restringe opcionalmente a entrada CDP na borda do contêiner a uma faixa CIDR (por exemplo, `172.21.0.1/32`).
- `sandbox.browser.binds` monta diretórios adicionais do host somente no contêiner do navegador em sandbox. Quando definido (incluindo `[]`), substitui `docker.binds` para o contêiner do navegador.
- Os padrões de inicialização são definidos em `scripts/sandbox-browser-entrypoint.sh` e ajustados para hosts de contêiner:
- `--remote-debugging-address=127.0.0.1`
- `--remote-debugging-port=<derived from OPENCLAW_BROWSER_CDP_PORT>`
@ -899,14 +901,14 @@ O acesso de observador noVNC usa autenticação VNC por padrão, e o OpenClaw em
- `--disable-extensions` (habilitado por padrão)
- `--disable-3d-apis`, `--disable-software-rasterizer` e `--disable-gpu` são
habilitados por padrão e podem ser desabilitados com
`OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` se o uso de WebGL/3D exigir.
- `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` reabilita extensões se o seu fluxo de trabalho
`OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` se o uso de WebGL/3D exigir isso.
- `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` reabilita extensões se seu fluxo de trabalho
depender delas.
- `--renderer-process-limit=2` pode ser alterado com
`OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N>`; defina `0` para usar o limite de processos
padrão do Chromium.
`OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N>`; defina `0` para usar o limite
de processos padrão do Chromium.
- mais `--no-sandbox` quando `noSandbox` está habilitado.
- Os padrões são a linha de base da imagem de contêiner; use uma imagem de navegador personalizada com um
- Os padrões são a baseline da imagem do contêiner; use uma imagem de navegador personalizada com um
entrypoint personalizado para alterar os padrões do contêiner.
</Accordion>
@ -923,9 +925,9 @@ scripts/sandbox-browser-setup.sh # optional browser image
### `agents.list` (substituições por agente)
Use `agents.list[].tts` para dar a um agente seu próprio provedor de TTS, voz, modelo,
estilo ou modo de TTS automático. O bloco do agente faz deep merge sobre
`messages.tts`, de modo que credenciais compartilhadas possam permanecer em um só lugar enquanto agentes individuais
substituem apenas os campos de voz ou provedor de que precisam. A substituição do agente ativo
estilo ou modo de TTS automático. O bloco do agente faz um deep merge sobre o
`messages.tts` global, portanto credenciais compartilhadas podem permanecer em um só lugar enquanto agentes individuais
substituem somente os campos de voz ou provedor de que precisam. A substituição do agente ativo
se aplica a respostas faladas automáticas, `/tts audio`, `/tts status` e
à ferramenta de agente `tts`. Consulte [Texto para fala](/pt-BR/tools/tts#per-agent-voice-overrides)
para exemplos de provedores e precedência.
@ -983,27 +985,27 @@ para exemplos de provedores e precedência.
```
- `id`: id estável do agente (obrigatório).
- `default`: quando vários são definidos, o primeiro vence (aviso registrado). Se nenhum for definido, a primeira entrada da lista é o padrão.
- `model`: a forma de string define um primário estrito por agente sem fallback de modelo; a forma de objeto `{ primary }` também é estrita, a menos que você adicione `fallbacks`. Use `{ primary, fallbacks: [...] }` para habilitar fallback para esse agente, ou `{ primary, fallbacks: [] }` para explicitar o comportamento estrito. Jobs Cron que substituem apenas `primary` ainda herdam fallbacks padrão, a menos que você defina `fallbacks: []`.
- `params`: parâmetros de stream por agente mesclados sobre a entrada de modelo selecionada em `agents.defaults.models`. Use isto para substituições específicas do agente, como `cacheRetention`, `temperature` ou `maxTokens`, sem duplicar todo o catálogo de modelos.
- `tts`: substituições opcionais de texto para fala por agente. O bloco faz uma mesclagem profunda sobre `messages.tts`, então mantenha credenciais compartilhadas de provedor e política de fallback em `messages.tts` e defina aqui apenas valores específicos da persona, como provedor, voz, modelo, estilo ou modo automático.
- `skills`: allowlist opcional de Skills por agente. Se omitida, o agente herda `agents.defaults.skills` quando definido; uma lista explícita substitui os padrões em vez de mesclar, e `[]` significa nenhuma Skills.
- `thinkingDefault`: nível de pensamento padrão opcional por agente (`off | minimal | low | medium | high | xhigh | adaptive | max`). Substitui `agents.defaults.thinkingDefault` para este agente quando nenhuma substituição por mensagem ou sessão estiver definida. O perfil de provedor/modelo selecionado controla quais valores são válidos; para Google Gemini, `adaptive` mantém o pensamento dinâmico pertencente ao provedor (`thinkingLevel` omitido no Gemini 3/3.1, `thinkingBudget: -1` no Gemini 2.5).
- `reasoningDefault`: visibilidade de raciocínio padrão opcional por agente (`on | off | stream`). Substitui `agents.defaults.reasoningDefault` para este agente quando nenhuma substituição de raciocínio por mensagem ou sessão estiver definida.
- `default`: quando vários são definidos, o primeiro vence (aviso registrado). Se nenhum for definido, a primeira entrada da lista será a padrão.
- `model`: a forma de string define um primário estrito por agente sem fallback de modelo; a forma de objeto `{ primary }` também é estrita, a menos que você adicione `fallbacks`. Use `{ primary, fallbacks: [...] }` para habilitar fallback para esse agente, ou `{ primary, fallbacks: [] }` para tornar o comportamento estrito explícito. Jobs Cron que substituem apenas `primary` ainda herdam fallbacks padrão, a menos que você defina `fallbacks: []`.
- `params`: parâmetros de stream por agente mesclados sobre a entrada de modelo selecionada em `agents.defaults.models`. Use isto para substituições específicas do agente como `cacheRetention`, `temperature` ou `maxTokens` sem duplicar todo o catálogo de modelos.
- `tts`: substituições opcionais de texto para fala por agente. O bloco faz uma mesclagem profunda sobre `messages.tts`, então mantenha credenciais de provedor compartilhadas e política de fallback em `messages.tts` e defina aqui apenas valores específicos da persona, como provedor, voz, modelo, estilo ou modo automático.
- `skills`: allowlist opcional de Skills por agente. Se omitida, o agente herda `agents.defaults.skills` quando definido; uma lista explícita substitui os padrões em vez de mesclar, e `[]` significa sem Skills.
- `thinkingDefault`: nível de raciocínio padrão opcional por agente (`off | minimal | low | medium | high | xhigh | adaptive | max`). Substitui `agents.defaults.thinkingDefault` para este agente quando nenhuma substituição por mensagem ou sessão estiver definida. O perfil de provedor/modelo selecionado controla quais valores são válidos; para Google Gemini, `adaptive` mantém o raciocínio dinâmico controlado pelo provedor (`thinkingLevel` omitido no Gemini 3/3.1, `thinkingBudget: -1` no Gemini 2.5).
- `reasoningDefault`: visibilidade de reasoning padrão opcional por agente (`on | off | stream`). Substitui `agents.defaults.reasoningDefault` para este agente quando nenhuma substituição de reasoning por mensagem ou sessão estiver definida.
- `fastModeDefault`: padrão opcional por agente para modo rápido (`true | false`). Aplica-se quando nenhuma substituição de modo rápido por mensagem ou sessão estiver definida.
- `agentRuntime`: substituição opcional de política de runtime de baixo nível por agente. Use `{ id: "codex" }` para tornar um agente exclusivo do Codex enquanto outros agentes mantêm o fallback padrão do PI no modo `auto`.
- `runtime`: descritor opcional de runtime por agente. Use `type: "acp"` com padrões de `runtime.acp` (`agent`, `backend`, `mode`, `cwd`) quando o agente deve usar sessões de harness ACP por padrão.
- `agentRuntime`: substituição opcional de política de runtime de baixo nível por agente. Use `{ id: "codex" }` para tornar um agente exclusivo do Codex enquanto outros agentes mantêm o fallback padrão para PI no modo `auto`.
- `runtime`: descritor opcional de runtime por agente. Use `type: "acp"` com padrões de `runtime.acp` (`agent`, `backend`, `mode`, `cwd`) quando o agente deve usar sessões do harness ACP por padrão.
- `identity.avatar`: caminho relativo ao workspace, URL `http(s)` ou URI `data:`.
- `identity` deriva padrões: `ackReaction` de `emoji`, `mentionPatterns` de `name`/`emoji`.
- `subagents.allowAgents`: allowlist de ids de agente para destinos explícitos de `sessions_spawn.agentId` (`["*"]` = qualquer um; padrão: apenas o mesmo agente). Inclua o id do solicitante quando chamadas de `agentId` direcionadas a si mesmo devem ser permitidas.
- `subagents.allowAgents`: allowlist de ids de agentes para destinos explícitos `sessions_spawn.agentId` (`["*"]` = qualquer um; padrão: apenas o mesmo agente). Inclua o id do solicitante quando chamadas `agentId` direcionadas a si mesmas devem ser permitidas.
- Proteção de herança de sandbox: se a sessão solicitante estiver em sandbox, `sessions_spawn` rejeita destinos que seriam executados sem sandbox.
- `subagents.requireAgentId`: quando verdadeiro, bloqueia chamadas de `sessions_spawn` que omitem `agentId` (força seleção explícita de perfil; padrão: falso).
- `subagents.requireAgentId`: quando verdadeiro, bloqueia chamadas `sessions_spawn` que omitem `agentId` (força seleção explícita de perfil; padrão: false).
---
## Roteamento multiagente
Execute vários agentes isolados dentro de um Gateway. Consulte [Multiagente](/pt-BR/concepts/multi-agent).
Execute vários agentes isolados dentro de um Gateway. Veja [Multiagente](/pt-BR/concepts/multi-agent).
```json5
{
@ -1020,14 +1022,14 @@ Execute vários agentes isolados dentro de um Gateway. Consulte [Multiagente](/p
}
```
### Campos de correspondência de vínculo
### Campos de correspondência de binding
- `type` (opcional): `route` para roteamento normal (tipo ausente usa route por padrão), `acp` para vínculos persistentes de conversa ACP.
- `type` (opcional): `route` para roteamento normal (tipo ausente usa route por padrão), `acp` para bindings persistentes de conversa ACP.
- `match.channel` (obrigatório)
- `match.accountId` (opcional; `*` = qualquer conta; omitido = conta padrão)
- `match.peer` (opcional; `{ kind: direct|group|channel, id }`)
- `match.guildId` / `match.teamId` (opcional; específico do canal)
- `acp` (opcional; somente para `type: "acp"`): `{ mode, label, cwd, backend }`
- `acp` (opcional; apenas para `type: "acp"`): `{ mode, label, cwd, backend }`
**Ordem determinística de correspondência:**
@ -1040,11 +1042,11 @@ Execute vários agentes isolados dentro de um Gateway. Consulte [Multiagente](/p
Dentro de cada nível, a primeira entrada correspondente em `bindings` vence.
Para entradas `type: "acp"`, o OpenClaw resolve pela identidade exata da conversa (`match.channel` + conta + `match.peer.id`) e não usa a ordem de níveis de vínculo de rota acima.
Para entradas `type: "acp"`, o OpenClaw resolve pela identidade exata da conversa (`match.channel` + conta + `match.peer.id`) e não usa a ordem de níveis de binding de rota acima.
### Perfis de acesso por agente
<Accordion title="Acesso total (sem sandbox)">
<Accordion title="Full access (no sandbox)">
```json5
{
@ -1062,7 +1064,7 @@ Para entradas `type: "acp"`, o OpenClaw resolve pela identidade exata da convers
</Accordion>
<Accordion title="Ferramentas somente leitura + workspace">
<Accordion title="Read-only tools + workspace">
```json5
{
@ -1091,7 +1093,7 @@ Para entradas `type: "acp"`, o OpenClaw resolve pela identidade exata da convers
</Accordion>
<Accordion title="Sem acesso ao sistema de arquivos (somente mensagens)">
<Accordion title="No filesystem access (messaging only)">
```json5
{
@ -1137,7 +1139,7 @@ Para entradas `type: "acp"`, o OpenClaw resolve pela identidade exata da convers
</Accordion>
Consulte [Sandbox e ferramentas multiagente](/pt-BR/tools/multi-agent-sandbox-tools) para detalhes de precedência.
Veja [Sandbox e ferramentas multiagente](/pt-BR/tools/multi-agent-sandbox-tools) para detalhes de precedência.
---
@ -1187,37 +1189,37 @@ Consulte [Sandbox e ferramentas multiagente](/pt-BR/tools/multi-agent-sandbox-to
}
```
<Accordion title="Detalhes dos campos de sessão">
<Accordion title="Session field details">
- **`scope`**: estratégia base de agrupamento de sessões para contextos de chat em grupo.
- `per-sender` (padrão): cada remetente recebe uma sessão isolada dentro de um contexto de canal.
- `global`: todos os participantes em um contexto de canal compartilham uma única sessão (use apenas quando o contexto compartilhado for intencional).
- **`dmScope`**: como DMs são agrupadas.
- `global`: todos os participantes em um contexto de canal compartilham uma única sessão (use somente quando o contexto compartilhado for intencional).
- **`dmScope`**: como as DMs são agrupadas.
- `main`: todas as DMs compartilham a sessão principal.
- `per-peer`: isola por id do remetente entre canais.
- `per-peer`: isola por id de remetente entre canais.
- `per-channel-peer`: isola por canal + remetente (recomendado para caixas de entrada multiusuário).
- `per-account-channel-peer`: isola por conta + canal + remetente (recomendado para várias contas).
- **`identityLinks`**: mapeia ids canônicos para peers prefixados por provedor para compartilhamento de sessão entre canais. Comandos de dock como `/dock_discord` usam o mesmo mapa para alternar a rota de resposta da sessão ativa para outro peer de canal vinculado; consulte [Docking de canais](/pt-BR/concepts/channel-docking).
- **`reset`**: política principal de redefinição. `daily` redefine em `atHour` no horário local; `idle` redefine após `idleMinutes`. Quando ambos estão configurados, vence o que expirar primeiro. A atualização da redefinição diária usa `sessionStartedAt` da linha da sessão; a atualização da redefinição por inatividade usa `lastInteractionAt`. Gravações de eventos em segundo plano/sistema, como Heartbeat, despertares Cron, notificações de exec e registros internos do Gateway, podem atualizar `updatedAt`, mas não mantêm sessões diárias/por inatividade atualizadas.
- **`resetByType`**: substituições por tipo (`direct`, `group`, `thread`). `dm` legado aceito como alias de `direct`.
- `per-account-channel-peer`: isola por conta + canal + remetente (recomendado para múltiplas contas).
- **`identityLinks`**: mapeia ids canônicos para pares com prefixo de provedor para compartilhamento de sessão entre canais. Comandos de acoplamento como `/dock_discord` usam o mesmo mapa para alternar a rota de resposta da sessão ativa para outro par de canal vinculado; consulte [Acoplamento de canais](/pt-BR/concepts/channel-docking).
- **`reset`**: política principal de redefinição. `daily` redefine no horário local `atHour`; `idle` redefine após `idleMinutes`. Quando ambos estão configurados, vence o que expirar primeiro. O frescor da redefinição diária usa o `sessionStartedAt` da linha da sessão; o frescor da redefinição por inatividade usa `lastInteractionAt`. Gravações de evento de fundo/sistema, como heartbeat, despertares de cron, notificações de execução e contabilidade do gateway, podem atualizar `updatedAt`, mas não mantêm sessões diárias/por inatividade recentes.
- **`resetByType`**: substituições por tipo (`direct`, `group`, `thread`). O `dm` legado é aceito como alias para `direct`.
- **`parentForkMaxTokens`**: máximo de `totalTokens` da sessão pai permitido ao criar uma sessão de thread bifurcada (padrão `100000`).
- Se `totalTokens` do pai estiver acima desse valor, o OpenClaw inicia uma nova sessão de thread em vez de herdar o histórico de transcrição do pai.
- Defina `0` para desabilitar esta proteção e sempre permitir bifurcação a partir do pai.
- Se o `totalTokens` pai estiver acima desse valor, o OpenClaw inicia uma nova sessão de thread em vez de herdar o histórico de transcrição pai.
- Defina `0` para desativar essa proteção e sempre permitir bifurcação a partir do pai.
- **`mainKey`**: campo legado. O runtime sempre usa `"main"` para o bucket principal de chat direto.
- **`agentToAgent.maxPingPongTurns`**: número máximo de turnos de resposta entre agentes durante trocas agente-para-agente (inteiro, intervalo: `0`–`5`). `0` desabilita encadeamento de ping-pong.
- **`agentToAgent.maxPingPongTurns`**: máximo de turnos de resposta de volta entre agentes durante trocas agente-a-agente (inteiro, intervalo: `0`–`5`). `0` desativa o encadeamento ping-pong.
- **`sendPolicy`**: corresponde por `channel`, `chatType` (`direct|group|channel`, com alias legado `dm`), `keyPrefix` ou `rawKeyPrefix`. A primeira negação vence.
- **`maintenance`**: controles de limpeza + retenção do armazenamento de sessões.
- **`maintenance`**: limpeza do armazenamento de sessões + controles de retenção.
- `mode`: `warn` emite apenas avisos; `enforce` aplica a limpeza.
- `pruneAfter`: corte de idade para entradas obsoletas (padrão `30d`).
- `maxEntries`: número máximo de entradas em `sessions.json` (padrão `500`). O runtime grava limpeza em lote com uma pequena margem de nível máximo para limites de tamanho de produção; `openclaw sessions cleanup --enforce` aplica o limite imediatamente.
- `maxEntries`: número máximo de entradas em `sessions.json` (padrão `500`). O runtime grava limpeza em lote com um pequeno buffer de marca d'água alta para limites de tamanho de produção; `openclaw sessions cleanup --enforce` aplica o limite imediatamente.
- `rotateBytes`: obsoleto e ignorado; `openclaw doctor --fix` o remove de configurações antigas.
- `resetArchiveRetention`: retenção para arquivos de transcrição `*.reset.<timestamp>`. O padrão é `pruneAfter`; defina `false` para desabilitar.
- `maxDiskBytes`: orçamento opcional de disco do diretório de sessões. No modo `warn`, registra avisos; no modo `enforce`, remove primeiro artefatos/sessões mais antigos.
- `highWaterBytes`: alvo opcional após limpeza de orçamento. O padrão é `80%` de `maxDiskBytes`.
- `resetArchiveRetention`: retenção para arquivos de transcrição `*.reset.<timestamp>`. O padrão é `pruneAfter`; defina `false` para desativar.
- `maxDiskBytes`: orçamento opcional de disco do diretório de sessões. No modo `warn`, registra avisos; no modo `enforce`, remove primeiro os artefatos/sessões mais antigos.
- `highWaterBytes`: alvo opcional após a limpeza por orçamento. O padrão é `80%` de `maxDiskBytes`.
- **`threadBindings`**: padrões globais para recursos de sessão vinculada a thread.
- `enabled`: chave padrão mestre (provedores podem substituir; Discord usa `channels.discord.threadBindings.enabled`)
- `idleHours`: desenfoque automático padrão por inatividade em horas (`0` desabilita; provedores podem substituir)
- `maxAgeHours`: idade máxima rígida padrão em horas (`0` desabilita; provedores podem substituir)
- `idleHours`: desfoco automático padrão por inatividade em horas (`0` desativa; provedores podem substituir)
- `maxAgeHours`: idade máxima rígida padrão em horas (`0` desativa; provedores podem substituir)
</Accordion>
@ -1228,12 +1230,12 @@ Consulte [Sandbox e ferramentas multiagente](/pt-BR/tools/multi-agent-sandbox-to
```json5
{
messages: {
responsePrefix: "🦞", // or "auto"
responsePrefix: "🦞", // ou "auto"
ackReaction: "👀",
ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all
removeAckAfterReply: false,
queue: {
mode: "steer", // steer | queue (legacy one-at-a-time) | followup | collect | steer-backlog | steer+backlog | interrupt
mode: "steer", // steer | queue (legado, um por vez) | followup | collect | steer-backlog | steer+backlog | interrupt
debounceMs: 500,
cap: 20,
drop: "summarize", // old | new | summarize
@ -1243,7 +1245,7 @@ Consulte [Sandbox e ferramentas multiagente](/pt-BR/tools/multi-agent-sandbox-to
},
},
inbound: {
debounceMs: 2000, // 0 disables
debounceMs: 2000, // 0 desativa
byChannel: {
whatsapp: 5000,
slack: 1500,
@ -1261,30 +1263,30 @@ Resolução (a mais específica vence): conta → canal → global. `""` desativ
**Variáveis de modelo:**
| Variável | Descrição | Exemplo |
| ----------------- | ------------------------- | --------------------------- |
| `{model}` | Nome curto do modelo | `claude-opus-4-6` |
| Variável | Descrição | Exemplo |
| ----------------- | -------------------------- | --------------------------- |
| `{model}` | Nome curto do modelo | `claude-opus-4-6` |
| `{modelFull}` | Identificador completo do modelo | `anthropic/claude-opus-4-6` |
| `{provider}` | Nome do provedor | `anthropic` |
| `{thinkingLevel}` | Nível de raciocínio atual | `high`, `low`, `off` |
| `{identity.name}` | Nome da identidade do agente | (igual a `"auto"`) |
| `{provider}` | Nome do provedor | `anthropic` |
| `{thinkingLevel}` | Nível de pensamento atual | `high`, `low`, `off` |
| `{identity.name}` | Nome da identidade do agente | (igual a `"auto"`) |
As variáveis não diferenciam maiúsculas de minúsculas. `{think}` é um alias para `{thinkingLevel}`.
Variáveis não diferenciam maiúsculas de minúsculas. `{think}` é um alias para `{thinkingLevel}`.
### Reação de confirmação
- O padrão é `identity.emoji` do agente ativo; caso contrário, `"👀"`. Defina `""` para desativar.
- O padrão é o `identity.emoji` do agente ativo; caso contrário, `"👀"`. Defina `""` para desativar.
- Substituições por canal: `channels.<channel>.ackReaction`, `channels.<channel>.accounts.<id>.ackReaction`.
- Ordem de resolução: conta → canal → `messages.ackReaction` → fallback da identidade.
- Ordem de resolução: conta → canal → `messages.ackReaction` → fallback de identidade.
- Escopo: `group-mentions` (padrão), `group-all`, `direct`, `all`.
- `removeAckAfterReply`: remove a confirmação após a resposta em canais com suporte a reações, como Slack, Discord, Telegram, WhatsApp e BlueBubbles.
- `messages.statusReactions.enabled`: ativa reações de status do ciclo de vida no Slack, Discord e Telegram.
No Slack e no Discord, quando não definido, mantém as reações de status ativadas quando as reações de confirmação estão ativas.
No Slack e no Discord, não definir mantém as reações de status ativadas quando as reações de confirmação estão ativas.
No Telegram, defina explicitamente como `true` para ativar reações de status do ciclo de vida.
### Debounce de entrada
Agrupa mensagens rápidas somente de texto do mesmo remetente em um único turno do agente. Mídia/anexos são enviados imediatamente. Comandos de controle ignoram o debounce.
Agrupa mensagens rápidas apenas de texto do mesmo remetente em um único turno do agente. Mídia/anexos liberam imediatamente. Comandos de controle ignoram o debounce.
### TTS (texto para fala)
@ -1334,19 +1336,19 @@ Agrupa mensagens rápidas somente de texto do mesmo remetente em um único turno
}
```
- `auto` controla o modo TTS automático padrão: `off`, `always`, `inbound` ou `tagged`. `/tts on|off` pode substituir as preferências locais, e `/tts status` mostra o estado efetivo.
- `auto` controla o modo auto-TTS padrão: `off`, `always`, `inbound` ou `tagged`. `/tts on|off` pode substituir preferências locais, e `/tts status` mostra o estado efetivo.
- `summaryModel` substitui `agents.defaults.model.primary` para resumo automático.
- `modelOverrides` é ativado por padrão; `modelOverrides.allowProvider` tem `false` como padrão (ativação opcional).
- As chaves de API recorrem a `ELEVENLABS_API_KEY`/`XI_API_KEY` e `OPENAI_API_KEY`.
- Provedores de fala incluídos são de propriedade dos plugins. Se `plugins.allow` estiver definido, inclua cada Plugin provedor de TTS que você quiser usar, por exemplo `microsoft` para TTS do Edge. O id legado de provedor `edge` é aceito como alias para `microsoft`.
- `providers.openai.baseUrl` substitui o endpoint de TTS da OpenAI. A ordem de resolução é configuração, depois `OPENAI_TTS_BASE_URL`, depois `https://api.openai.com/v1`.
- Quando `providers.openai.baseUrl` aponta para um endpoint que não é da OpenAI, o OpenClaw o trata como um servidor de TTS compatível com a OpenAI e flexibiliza a validação de modelo/voz.
- `modelOverrides` vem ativado por padrão; `modelOverrides.allowProvider` usa `false` como padrão (adesão opcional).
- Chaves de API usam fallback para `ELEVENLABS_API_KEY`/`XI_API_KEY` e `OPENAI_API_KEY`.
- Provedores de fala incluídos são de propriedade de Plugins. Se `plugins.allow` estiver definido, inclua cada Plugin de provedor de TTS que você queira usar, por exemplo `microsoft` para Edge TTS. O id de provedor legado `edge` é aceito como alias para `microsoft`.
- `providers.openai.baseUrl` substitui o endpoint de TTS da OpenAI. A ordem de resolução é config, depois `OPENAI_TTS_BASE_URL`, depois `https://api.openai.com/v1`.
- Quando `providers.openai.baseUrl` aponta para um endpoint que não é da OpenAI, o OpenClaw o trata como um servidor de TTS compatível com OpenAI e relaxa a validação de modelo/voz.
---
## Fala
## Talk
Padrões para o modo Fala (macOS/iOS/Android).
Padrões para o modo Talk (macOS/iOS/Android).
```json5
{
@ -1375,20 +1377,20 @@ Padrões para o modo Fala (macOS/iOS/Android).
}
```
- `talk.provider` deve corresponder a uma chave em `talk.providers` quando vários provedores de Fala estiverem configurados.
- Chaves planas legadas de Fala (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) existem apenas para compatibilidade e são migradas automaticamente para `talk.providers.<provider>`.
- IDs de voz recorrem a `ELEVENLABS_VOICE_ID` ou `SAG_VOICE_ID`.
- `providers.*.apiKey` aceita strings de texto simples ou objetos SecretRef.
- O fallback `ELEVENLABS_API_KEY` se aplica apenas quando nenhuma chave de API de Fala está configurada.
- `providers.*.voiceAliases` permite que diretivas de Fala usem nomes amigáveis.
- `talk.provider` deve corresponder a uma chave em `talk.providers` quando vários provedores de Talk estiverem configurados.
- Chaves planas legadas de Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) existem apenas para compatibilidade e são migradas automaticamente para `talk.providers.<provider>`.
- IDs de voz usam fallback para `ELEVENLABS_VOICE_ID` ou `SAG_VOICE_ID`.
- `providers.*.apiKey` aceita strings em texto simples ou objetos SecretRef.
- O fallback `ELEVENLABS_API_KEY` se aplica somente quando nenhuma chave de API de Talk está configurada.
- `providers.*.voiceAliases` permite que diretivas de Talk usem nomes amigáveis.
- `providers.mlx.modelId` seleciona o repositório do Hugging Face usado pelo auxiliar local MLX do macOS. Se omitido, o macOS usa `mlx-community/Soprano-80M-bf16`.
- A reprodução MLX no macOS é executada pelo auxiliar incluído `openclaw-mlx-tts` quando presente, ou por um executável em `PATH`; `OPENCLAW_MLX_TTS_BIN` substitui o caminho do auxiliar para desenvolvimento.
- `speechLocale` define o id de localidade BCP 47 usado pelo reconhecimento de fala do Fala no iOS/macOS. Deixe indefinido para usar o padrão do dispositivo.
- `silenceTimeoutMs` controla por quanto tempo o modo Fala aguarda após o silêncio do usuário antes de enviar a transcrição. Quando não definido, mantém a janela de pausa padrão da plataforma (`700 ms on macOS and Android, 900 ms on iOS`).
- A reprodução MLX no macOS passa pelo auxiliar incluído `openclaw-mlx-tts` quando presente, ou por um executável em `PATH`; `OPENCLAW_MLX_TTS_BIN` substitui o caminho do auxiliar para desenvolvimento.
- `speechLocale` define o id de localidade BCP 47 usado pelo reconhecimento de fala do Talk no iOS/macOS. Deixe indefinido para usar o padrão do dispositivo.
- `silenceTimeoutMs` controla por quanto tempo o modo Talk espera após o silêncio do usuário antes de enviar a transcrição. Indefinido mantém a janela de pausa padrão da plataforma (`700 ms no macOS e Android, 900 ms no iOS`).
---
## Relacionado
## Relacionados
- [Referência de configuração](/pt-BR/gateway/configuration-reference) — todas as outras chaves de configuração
- [Configuração](/pt-BR/gateway/configuration) — tarefas comuns e configuração rápida

294
docs/pt-BR/gateway/config-channels.md
View File

@ -2,21 +2,21 @@
read_when:
- Configurando um Plugin de canal (autenticação, controle de acesso, múltiplas contas)
- Solução de problemas de chaves de configuração por canal
- Auditoria da política de mensagens diretas, da política de grupos ou do controle de acesso por menção
summary: 'Configuração de canais: controle de acesso, emparelhamento, chaves por canal no Slack, Discord, Telegram, WhatsApp, Matrix, iMessage e mais'
- Auditando política de DM, política de grupo ou controle de menções
summary: 'Configuração de canais: controle de acesso, pareamento, chaves por canal no Slack, Discord, Telegram, WhatsApp, Matrix, iMessage e muito mais'
title: Configuração — canais
x-i18n:
generated_at: "2026-04-30T09:47:42Z"
generated_at: "2026-04-30T16:28:37Z"
model: gpt-5.5
provider: openai
source_hash: e16ab50020711aac8e06cd234739ac7b566420cf7ce8621c0aca12c22484f07f
source_hash: aba14cb43e1fe914cc7c03f41bed1b5915cc6b2ad8e0f1d47f58b7e98c1b3915
source_path: gateway/config-channels.md
workflow: 16
---
Configuração por canal sob `channels.*`. Abrange acesso a DMs e grupos,
configurações de várias contas, controle por menção e chaves por canal para Slack, Discord,
Telegram, WhatsApp, Matrix, iMessage e os outros plugins de canal incluídos.
Chaves de configuração por canal em `channels.*`. Abrange acesso a DM e grupos,
configurações multi-conta, controle por menção e chaves por canal para Slack, Discord,
Telegram, WhatsApp, Matrix, iMessage e os outros Plugins de canal incluídos.
Para agentes, ferramentas, runtime do gateway e outras chaves de nível superior, consulte
[Referência de configuração](/pt-BR/gateway/configuration-reference).
@ -25,25 +25,25 @@ Para agentes, ferramentas, runtime do gateway e outras chaves de nível superior
Cada canal inicia automaticamente quando sua seção de configuração existe (a menos que `enabled: false`).
### Acesso a DMs e grupos
### Acesso a DM e grupos
Todos os canais aceitam políticas de DM e políticas de grupo:
Todos os canais oferecem suporte a políticas de DM e políticas de grupo:
| Política de DM | Comportamento |
| ------------------- | --------------------------------------------------------------- |
| `pairing` (padrão) | Remetentes desconhecidos recebem um código de pareamento único; o proprietário deve aprovar |
| `allowlist` | Somente remetentes em `allowFrom` (ou armazenamento de permissões pareado) |
| `open` | Permite todas as DMs de entrada (requer `allowFrom: ["*"]`) |
| `disabled` | Ignora todas as DMs de entrada |
| ------------------- | -------------------------------------------------------------- |
| `pairing` (default) | Remetentes desconhecidos recebem um código de pareamento único; o proprietário deve aprovar |
| `allowlist` | Somente remetentes em `allowFrom` (ou armazenamento de permissão pareado) |
| `open` | Permite todas as DMs recebidas (requer `allowFrom: ["*"]`) |
| `disabled` | Ignora todas as DMs recebidas |
| Política de grupo | Comportamento |
| --------------------- | ------------------------------------------------------- |
| `allowlist` (padrão) | Somente grupos que correspondem à allowlist configurada |
| `open` | Ignora allowlists de grupo (controle por menção ainda se aplica) |
| `disabled` | Bloqueia todas as mensagens de grupos/salas |
| Política de grupo | Comportamento |
| -------------------- | -------------------------------------------------------------- |
| `allowlist` (default) | Somente grupos que correspondem à lista de permissões configurada |
| `open` | Ignora listas de permissões de grupo (o controle por menção ainda se aplica) |
| `disabled` | Bloqueia todas as mensagens de grupo/sala |
<Note>
`channels.defaults.groupPolicy` define o padrão quando o `groupPolicy` de um provedor não está definido.
`channels.defaults.groupPolicy` define o padrão quando `groupPolicy` de um provedor não está definido.
Códigos de pareamento expiram após 1 hora. Solicitações pendentes de pareamento por DM são limitadas a **3 por canal**.
Se um bloco de provedor estiver totalmente ausente (`channels.<provider>` ausente), a política de grupo em runtime volta para `allowlist` (falha fechada) com um aviso na inicialização.
</Note>
@ -73,7 +73,7 @@ Use `channels.modelByChannel` para fixar IDs de canal específicos a um modelo.
### Padrões de canal e Heartbeat
Use `channels.defaults` para política de grupo e comportamento de Heartbeat compartilhados entre provedores:
Use `channels.defaults` para comportamento compartilhado de política de grupo e Heartbeat entre provedores:
```json5
{
@ -91,15 +91,15 @@ Use `channels.defaults` para política de grupo e comportamento de Heartbeat com
}
```
- `channels.defaults.groupPolicy`: política de grupo de fallback quando um `groupPolicy` no nível do provedor não está definido.
- `channels.defaults.contextVisibility`: modo padrão de visibilidade de contexto suplementar para todos os canais. Valores: `all` (padrão, inclui todo o contexto de citações/threads/histórico), `allowlist` (inclui somente contexto de remetentes na allowlist), `allowlist_quote` (igual a allowlist, mas mantém contexto explícito de citação/resposta). Substituição por canal: `channels.<channel>.contextVisibility`.
- `channels.defaults.groupPolicy`: política de grupo de fallback quando `groupPolicy` em nível de provedor não está definida.
- `channels.defaults.contextVisibility`: modo padrão de visibilidade de contexto suplementar para todos os canais. Valores: `all` (padrão, inclui todo contexto de citação/thread/histórico), `allowlist` (inclui apenas contexto de remetentes na lista de permissões), `allowlist_quote` (igual a allowlist, mas mantém contexto explícito de citação/resposta). Substituição por canal: `channels.<channel>.contextVisibility`.
- `channels.defaults.heartbeat.showOk`: inclui status de canais saudáveis na saída de Heartbeat.
- `channels.defaults.heartbeat.showAlerts`: inclui status degradados/com erro na saída de Heartbeat.
- `channels.defaults.heartbeat.useIndicator`: renderiza saída de Heartbeat compacta em estilo de indicador.
- `channels.defaults.heartbeat.useIndicator`: renderiza saída de Heartbeat compacta no estilo de indicador.
### WhatsApp
WhatsApp roda pelo canal web do Gateway (Baileys Web). Ele inicia automaticamente quando existe uma sessão vinculada.
O WhatsApp roda pelo canal web do Gateway (Baileys Web). Ele inicia automaticamente quando uma sessão vinculada existe.
```json5
{
@ -139,7 +139,7 @@ WhatsApp roda pelo canal web do Gateway (Baileys Web). Ele inicia automaticament
}
```
<Accordion title="WhatsApp com várias contas">
<Accordion title="WhatsApp multi-conta">
```json5
{
@ -157,9 +157,9 @@ WhatsApp roda pelo canal web do Gateway (Baileys Web). Ele inicia automaticament
}
```
- Comandos de saída usam a conta `default` por padrão, se presente; caso contrário, usam o primeiro id de conta configurado (ordenado).
- O `channels.whatsapp.defaultAccount` opcional substitui essa seleção de conta padrão de fallback quando corresponde a um id de conta configurado.
- O diretório de autenticação legado de conta única do Baileys é migrado por `openclaw doctor` para `whatsapp/default`.
- Comandos de saída usam a conta `default` por padrão, se presente; caso contrário, o primeiro id de conta configurado (ordenado).
- `channels.whatsapp.defaultAccount` opcional substitui essa seleção de conta padrão de fallback quando corresponde a um id de conta configurado.
- O diretório de autenticação Baileys legado de conta única é migrado por `openclaw doctor` para `whatsapp/default`.
- Substituições por conta: `channels.whatsapp.accounts.<id>.sendReadReceipts`, `channels.whatsapp.accounts.<id>.dmPolicy`, `channels.whatsapp.accounts.<id>.allowFrom`.
</Accordion>
@ -220,13 +220,13 @@ WhatsApp roda pelo canal web do Gateway (Baileys Web). Ele inicia automaticament
```
- Token do bot: `channels.telegram.botToken` ou `channels.telegram.tokenFile` (somente arquivo regular; symlinks rejeitados), com `TELEGRAM_BOT_TOKEN` como fallback para a conta padrão.
- `apiRoot` é apenas a raiz da Telegram Bot API. Use `https://api.telegram.org` ou sua raiz auto-hospedada/proxy, não `https://api.telegram.org/bot<TOKEN>`; `openclaw doctor --fix` remove um sufixo final `/bot<TOKEN>` acidental.
- O `channels.telegram.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um id de conta configurado.
- Em configurações com várias contas (2+ ids de conta), defina um padrão explícito (`channels.telegram.defaultAccount` ou `channels.telegram.accounts.default`) para evitar roteamento de fallback; `openclaw doctor` avisa quando isso está ausente ou é inválido.
- `apiRoot` é somente a raiz da API Bot do Telegram. Use `https://api.telegram.org` ou sua raiz auto-hospedada/proxy, não `https://api.telegram.org/bot<TOKEN>`; `openclaw doctor --fix` remove um sufixo `/bot<TOKEN>` final acidental.
- `channels.telegram.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um id de conta configurado.
- Em configurações multi-conta (2+ ids de conta), defina um padrão explícito (`channels.telegram.defaultAccount` ou `channels.telegram.accounts.default`) para evitar roteamento de fallback; `openclaw doctor` avisa quando isso está ausente ou inválido.
- `configWrites: false` bloqueia gravações de configuração iniciadas pelo Telegram (migrações de ID de supergrupo, `/config set|unset`).
- Entradas `bindings[]` de nível superior com `type: "acp"` configuram vínculos ACP persistentes para tópicos de fórum (use `chatId:topic:topicId` canônico em `match.peer.id`). A semântica dos campos é compartilhada em [Agentes ACP](/pt-BR/tools/acp-agents#channel-specific-settings).
- Pré-visualizações de stream do Telegram usam `sendMessage` + `editMessageText` (funciona em conversas diretas e grupos).
- Política de nova tentativa: consulte [Política de nova tentativa](/pt-BR/concepts/retry).
- Entradas `bindings[]` de nível superior com `type: "acp"` configuram associações ACP persistentes para tópicos de fórum (use o `chatId:topic:topicId` canônico em `match.peer.id`). A semântica dos campos é compartilhada em [Agentes ACP](/pt-BR/tools/acp-agents#channel-specific-settings).
- Pré-visualizações de stream do Telegram usam `sendMessage` + `editMessageText` (funciona em chats diretos e de grupo).
- Política de repetição: consulte [Política de repetição](/pt-BR/concepts/retry).
### Discord
@ -329,36 +329,36 @@ WhatsApp roda pelo canal web do Gateway (Baileys Web). Ele inicia automaticament
```
- Token: `channels.discord.token`, com `DISCORD_BOT_TOKEN` como fallback para a conta padrão.
- Chamadas de saída diretas que fornecem um `token` explícito do Discord usam esse token para a chamada; as configurações de nova tentativa/política da conta ainda vêm da conta selecionada no snapshot de runtime ativo.
- `channels.discord.defaultAccount` opcional substitui a seleção da conta padrão quando corresponde a um ID de conta configurado.
- Use `user:<id>` (DM) ou `channel:<id>` (canal do servidor) para destinos de entrega; IDs numéricos simples são rejeitados.
- Slugs de servidores ficam em minúsculas com espaços substituídos por `-`; chaves de canal usam o nome com slug (sem `#`). Prefira IDs de servidor.
- Mensagens criadas por bots são ignoradas por padrão. `allowBots: true` as habilita; use `allowBots: "mentions"` para aceitar apenas mensagens de bots que mencionem o bot (mensagens próprias ainda são filtradas).
- `channels.discord.guilds.<id>.ignoreOtherMentions` (e substituições por canal) descarta mensagens que mencionam outro usuário ou cargo, mas não o bot (excluindo @everyone/@here).
- `maxLinesPerMessage` (padrão 17) divide mensagens altas mesmo quando estão abaixo de 2000 caracteres.
- Chamadas diretas de saída que fornecem um `token` do Discord explícito usam esse token para a chamada; as configurações de nova tentativa/política da conta ainda vêm da conta selecionada no snapshot de runtime ativo.
- `channels.discord.defaultAccount` opcional substitui a seleção da conta padrão quando corresponde a um id de conta configurado.
- Use `user:<id>` (DM) ou `channel:<id>` (canal de guild) para destinos de entrega; IDs numéricos sem prefixo são rejeitados.
- Slugs de guild ficam em minúsculas com espaços substituídos por `-`; chaves de canal usam o nome em slug (sem `#`). Prefira IDs de guild.
- Mensagens criadas por bots são ignoradas por padrão. `allowBots: true` as habilita; use `allowBots: "mentions"` para aceitar apenas mensagens de bot que mencionem o bot (mensagens próprias ainda são filtradas).
- `channels.discord.guilds.<id>.ignoreOtherMentions` (e substituições por canal) descarta mensagens que mencionam outro usuário ou cargo, mas não o bot (exceto @everyone/@here).
- `maxLinesPerMessage` (padrão 17) divide mensagens altas mesmo quando têm menos de 2000 caracteres.
- `channels.discord.threadBindings` controla o roteamento vinculado a threads do Discord:
- `enabled`: substituição do Discord para recursos de sessão vinculados a thread (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`, e entrega/roteamento vinculados)
- `idleHours`: substituição do Discord para desfoco automático por inatividade em horas (`0` desabilita)
- `maxAgeHours`: substituição do Discord para idade máxima rígida em horas (`0` desabilita)
- `spawnSubagentSessions`: alternância opt-in para criação/vinculação automática de thread por `sessions_spawn({ thread: true })`
- Entradas `bindings[]` de nível superior com `type: "acp"` configuram vinculações ACP persistentes para canais e threads (use o ID de canal/thread em `match.peer.id`). A semântica dos campos é compartilhada em [Agentes ACP](/pt-BR/tools/acp-agents#channel-specific-settings).
- `enabled`: substituição do Discord para recursos de sessão vinculados a thread (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` e entrega/roteamento vinculados)
- `idleHours`: substituição do Discord para auto-unfocus por inatividade em horas (`0` desabilita)
- `maxAgeHours`: substituição do Discord para idade máxima absoluta em horas (`0` desabilita)
- `spawnSubagentSessions`: opção de adesão para criação/vinculação automática de thread em `sessions_spawn({ thread: true })`
- Entradas `bindings[]` de nível superior com `type: "acp"` configuram vinculações ACP persistentes para canais e threads (use o id de canal/thread em `match.peer.id`). A semântica dos campos é compartilhada em [Agentes ACP](/pt-BR/tools/acp-agents#channel-specific-settings).
- `channels.discord.ui.components.accentColor` define a cor de destaque para contêineres v2 de componentes do Discord.
- `channels.discord.voice` habilita conversas em canais de voz do Discord e substituições opcionais de entrada automática + LLM + TTS.
- `channels.discord.voice.model` substitui opcionalmente o modelo LLM usado para respostas em canais de voz do Discord.
- `channels.discord.voice` habilita conversas em canais de voz do Discord e substituições opcionais de autoentrada + LLM + TTS.
- `channels.discord.voice.model` substitui opcionalmente o modelo de LLM usado para respostas em canais de voz do Discord.
- `channels.discord.voice.daveEncryption` e `channels.discord.voice.decryptionFailureTolerance` são repassados para as opções DAVE de `@discordjs/voice` (`true` e `24` por padrão).
- O OpenClaw também tenta recuperar o recebimento de voz saindo/entrando novamente em uma sessão de voz após falhas repetidas de descriptografia.
- `channels.discord.streaming` é a chave canônica do modo de stream. Valores legados `streamMode` e booleanos `streaming` são migrados automaticamente.
- O OpenClaw também tenta recuperar o recebimento de voz saindo/reentrando em uma sessão de voz após falhas repetidas de descriptografia.
- `channels.discord.streaming` é a chave canônica do modo de stream. Valores legados de `streamMode` e `streaming` booleano são migrados automaticamente.
- `channels.discord.autoPresence` mapeia a disponibilidade de runtime para a presença do bot (healthy => online, degraded => idle, exhausted => dnd) e permite substituições opcionais de texto de status.
- `channels.discord.dangerouslyAllowNameMatching` reabilita a correspondência mutável de nome/tag (modo de compatibilidade emergencial).
- `channels.discord.dangerouslyAllowNameMatching` reabilita correspondência mutável por nome/tag (modo de compatibilidade break-glass).
- `channels.discord.execApprovals`: entrega de aprovação de exec nativa do Discord e autorização de aprovadores.
- `enabled`: `true`, `false` ou `"auto"` (padrão). No modo automático, aprovações de exec são ativadas quando aprovadores podem ser resolvidos a partir de `approvers` ou `commands.ownerAllowFrom`.
- `approvers`: IDs de usuário do Discord autorizados a aprovar solicitações de exec. Recorre a `commands.ownerAllowFrom` quando omitido.
- `agentFilter`: lista de permissões opcional de IDs de agente. Omita para encaminhar aprovações para todos os agentes.
- `enabled`: `true`, `false` ou `"auto"` (padrão). No modo auto, aprovações de exec são ativadas quando aprovadores podem ser resolvidos a partir de `approvers` ou `commands.ownerAllowFrom`.
- `approvers`: IDs de usuário do Discord autorizados a aprovar solicitações de exec. Usa `commands.ownerAllowFrom` como fallback quando omitido.
- `agentFilter`: lista de permissão opcional de IDs de agente. Omita para encaminhar aprovações para todos os agentes.
- `sessionFilter`: padrões opcionais de chave de sessão (substring ou regex).
- `target`: onde enviar prompts de aprovação. `"dm"` (padrão) envia para DMs dos aprovadores, `"channel"` envia para o canal de origem, `"both"` envia para ambos. Quando o destino inclui `"channel"`, os botões só podem ser usados por aprovadores resolvidos.
- `cleanupAfterResolve`: quando `true`, exclui DMs de aprovação após aprovação, negação ou timeout.
**Modos de notificação por reação:** `off` (nenhum), `own` (mensagens do bot, padrão), `all` (todas as mensagens), `allowlist` (de `guilds.<id>.users` em todas as mensagens).
**Modos de notificação por reação:** `off` (nenhuma), `own` (mensagens do bot, padrão), `all` (todas as mensagens), `allowlist` (de `guilds.<id>.users` em todas as mensagens).
### Google Chat
@ -389,11 +389,11 @@ WhatsApp roda pelo canal web do Gateway (Baileys Web). Ele inicia automaticament
}
```
- JSON de conta de serviço: inline (`serviceAccount`) ou baseado em arquivo (`serviceAccountFile`).
- JSON da conta de serviço: inline (`serviceAccount`) ou baseado em arquivo (`serviceAccountFile`).
- SecretRef de conta de serviço também é compatível (`serviceAccountRef`).
- Fallbacks de env: `GOOGLE_CHAT_SERVICE_ACCOUNT` ou `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`.
- Use `spaces/<spaceId>` ou `users/<userId>` para destinos de entrega.
- `channels.googlechat.dangerouslyAllowNameMatching` reabilita a correspondência mutável de principal de e-mail (modo de compatibilidade emergencial).
- `channels.googlechat.dangerouslyAllowNameMatching` reabilita correspondência mutável por principal de e-mail (modo de compatibilidade break-glass).
### Slack
@ -467,42 +467,33 @@ WhatsApp roda pelo canal web do Gateway (Baileys Web). Ele inicia automaticament
- **Modo Socket** requer `botToken` e `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` para fallback de env da conta padrão).
- **Modo HTTP** requer `botToken` mais `signingSecret` (na raiz ou por conta).
- `socketMode` repassa o ajuste fino de transporte do Socket Mode do SDK do Slack para a API pública do receptor Bolt. Use-o apenas ao investigar timeout de ping/pong ou comportamento de websocket obsoleto.
- `botToken`, `appToken`, `signingSecret` e `userToken` aceitam strings de texto simples
ou objetos SecretRef.
- Snapshots de conta do Slack expõem campos de origem/status por credencial, como
`botTokenSource`, `botTokenStatus`, `appTokenStatus` e, no modo HTTP,
`signingSecretStatus`. `configured_unavailable` significa que a conta está
configurada por SecretRef, mas o caminho atual de comando/runtime não conseguiu
resolver o valor do segredo.
- `socketMode` repassa o ajuste de transporte Socket Mode do SDK do Slack para a API pública do receptor Bolt. Use apenas ao investigar timeout de ping/pong ou comportamento de websocket obsoleto.
- `botToken`, `appToken`, `signingSecret` e `userToken` aceitam strings em texto simples ou objetos SecretRef.
- Snapshots de conta do Slack expõem campos de origem/status por credencial, como `botTokenSource`, `botTokenStatus`, `appTokenStatus` e, no modo HTTP, `signingSecretStatus`. `configured_unavailable` significa que a conta está configurada por SecretRef, mas o caminho atual de comando/runtime não conseguiu resolver o valor do segredo.
- `configWrites: false` bloqueia gravações de configuração iniciadas pelo Slack.
- `channels.slack.defaultAccount` opcional substitui a seleção da conta padrão quando corresponde a um ID de conta configurado.
- `channels.slack.streaming.mode` é a chave canônica do modo de stream do Slack. `channels.slack.streaming.nativeTransport` controla o transporte de streaming nativo do Slack. Valores legados `streamMode`, booleanos `streaming` e `nativeStreaming` são migrados automaticamente.
- `channels.slack.defaultAccount` opcional substitui a seleção da conta padrão quando corresponde a um id de conta configurado.
- `channels.slack.streaming.mode` é a chave canônica do modo de stream do Slack. `channels.slack.streaming.nativeTransport` controla o transporte de streaming nativo do Slack. Valores legados de `streamMode`, `streaming` booleano e `nativeStreaming` são migrados automaticamente.
- Use `user:<id>` (DM) ou `channel:<id>` para destinos de entrega.
**Modos de notificação por reação:** `off`, `own` (padrão), `all`, `allowlist` (de `reactionAllowlist`).
**Isolamento de sessão de thread:** `thread.historyScope` é por thread (padrão) ou compartilhado em todo o canal. `thread.inheritParent` copia a transcrição do canal pai para novas threads.
**Isolamento de sessão por thread:** `thread.historyScope` é por thread (padrão) ou compartilhado pelo canal. `thread.inheritParent` copia a transcrição do canal pai para novas threads.
- O streaming nativo do Slack mais o status de thread no estilo assistente do Slack "está digitando..." exigem um destino de thread de resposta. DMs de nível superior permanecem fora de threads por padrão, então usam `typingReaction` ou entrega normal em vez da prévia no estilo thread.
- `typingReaction` adiciona uma reação temporária à mensagem de entrada do Slack enquanto uma resposta está em andamento, depois a remove na conclusão. Use um shortcode de emoji do Slack, como `"hourglass_flowing_sand"`.
- `channels.slack.execApprovals`: entrega de aprovação de exec nativa do Slack e autorização de aprovadores. Mesmo esquema que o Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (IDs de usuário do Slack), `agentFilter`, `sessionFilter` e `target` (`"dm"`, `"channel"` ou `"both"`).
- Streaming nativo do Slack mais o status de thread "is typing..." no estilo de assistente do Slack exigem um destino de thread de resposta. DMs de nível superior ficam fora de thread por padrão, então usam `typingReaction` ou entrega normal em vez da prévia no estilo de thread.
- `typingReaction` adiciona uma reação temporária à mensagem recebida no Slack enquanto uma resposta está em execução, depois a remove na conclusão. Use um shortcode de emoji do Slack, como `"hourglass_flowing_sand"`.
- `channels.slack.execApprovals`: entrega de aprovação de exec nativa do Slack e autorização de aprovadores. Mesmo esquema do Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (IDs de usuário do Slack), `agentFilter`, `sessionFilter` e `target` (`"dm"`, `"channel"` ou `"both"`).
| Grupo de ação | Padrão | Observações |
| ------------- | --------- | ------------------------ |
| reactions | habilitado | Reagir + listar reações |
| messages | habilitado | Ler/enviar/editar/excluir |
| pins | habilitado | Fixar/desafixar/listar |
| memberInfo | habilitado | Informações de membro |
| emojiList | habilitado | Lista de emojis personalizados |
| Grupo de ações | Padrão | Observações |
| -------------- | --------- | ----------------------- |
| reactions | habilitado | Reagir + listar reações |
| messages | habilitado | Ler/enviar/editar/excluir |
| pins | habilitado | Fixar/desafixar/listar |
| memberInfo | habilitado | Informações do membro |
| emojiList | habilitado | Lista de emojis personalizados |
### Mattermost
O Mattermost é distribuído como um Plugin incluído nas versões atuais do OpenClaw. Builds mais antigos ou
personalizados podem instalar um pacote npm atual com
`openclaw plugins install @openclaw/mattermost`; se o npm informar que o
pacote de propriedade do OpenClaw está obsoleto, use o Plugin incluído ou um checkout local
até que um pacote npm mais novo seja publicado.
O Mattermost é distribuído como um Plugin incluído nas versões atuais do OpenClaw. Builds antigas ou personalizadas podem instalar um pacote npm atual com `openclaw plugins install @openclaw/mattermost`; se o npm informar que o pacote de propriedade do OpenClaw está obsoleto, use o Plugin incluído ou um checkout local até que um pacote npm mais novo seja publicado.
```json5
{
@ -532,23 +523,18 @@ até que um pacote npm mais novo seja publicado.
}
```
Modos de chat: `oncall` (responde em @menção, padrão), `onmessage` (todas as mensagens), `onchar` (mensagens que começam com prefixo de gatilho).
Modos de chat: `oncall` (responde em @-mention, padrão), `onmessage` (todas as mensagens), `onchar` (mensagens que começam com prefixo de acionamento).
Quando comandos nativos do Mattermost estão habilitados:
- `commands.callbackPath` deve ser um caminho (por exemplo `/api/channels/mattermost/command`), não uma URL completa.
- `commands.callbackUrl` deve resolver para o endpoint do Gateway do OpenClaw e ser acessível pelo servidor Mattermost.
- Callbacks de barras nativas são autenticados com os tokens por comando retornados
pelo Mattermost durante o registro de comando de barra. Se o registro falhar ou nenhum
comando for ativado, o OpenClaw rejeita callbacks com
`Unauthorized: invalid command token.`
- Para hosts de callback privados/tailnet/internos, o Mattermost pode exigir que
`ServiceSettings.AllowedUntrustedInternalConnections` inclua o host/domínio de callback.
Use valores de host/domínio, não URLs completas.
- `commands.callbackUrl` deve resolver para o endpoint do Gateway do OpenClaw e ser alcançável pelo servidor Mattermost.
- Callbacks slash nativos são autenticados com os tokens por comando retornados pelo Mattermost durante o registro do comando slash. Se o registro falhar ou nenhum comando for ativado, o OpenClaw rejeita callbacks com `Unauthorized: invalid command token.`
- Para hosts de callback privados/tailnet/internos, o Mattermost pode exigir que `ServiceSettings.AllowedUntrustedInternalConnections` inclua o host/domínio de callback. Use valores de host/domínio, não URLs completas.
- `channels.mattermost.configWrites`: permite ou nega gravações de configuração iniciadas pelo Mattermost.
- `channels.mattermost.requireMention`: exige `@mention` antes de responder em canais.
- `channels.mattermost.groups.<channelId>.requireMention`: substituição de controle de menção por canal (`"*"` para padrão).
- `channels.mattermost.defaultAccount` opcional substitui a seleção da conta padrão quando corresponde a um ID de conta configurado.
- `channels.mattermost.groups.<channelId>.requireMention`: substituição por canal da exigência de menção (`"*"` para padrão).
- `channels.mattermost.defaultAccount` opcional substitui a seleção da conta padrão quando corresponde a um id de conta configurado.
### Signal
@ -571,13 +557,13 @@ Quando comandos nativos do Mattermost estão habilitados:
**Modos de notificação de reação:** `off`, `own` (padrão), `all`, `allowlist` (de `reactionAllowlist`).
- `channels.signal.account`: fixa a inicialização do canal a uma identidade específica de conta do Signal.
- `channels.signal.account`: fixa a inicialização do canal a uma identidade de conta Signal específica.
- `channels.signal.configWrites`: permite ou nega gravações de configuração iniciadas pelo Signal.
- `channels.signal.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um ID de conta configurado.
- O `channels.signal.defaultAccount` opcional substitui a seleção padrão de conta quando corresponde a um id de conta configurado.
### BlueBubbles
BlueBubbles é o caminho recomendado para iMessage (com respaldo por Plugin, configurado em `channels.bluebubbles`).
BlueBubbles é o caminho recomendado para iMessage (com suporte de Plugin, configurado em `channels.bluebubbles`).
```json5
{
@ -593,8 +579,8 @@ BlueBubbles é o caminho recomendado para iMessage (com respaldo por Plugin, con
```
- Caminhos de chave principais cobertos aqui: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`.
- `channels.bluebubbles.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um ID de conta configurado.
- Entradas `bindings[]` de nível superior com `type: "acp"` podem vincular conversas do BlueBubbles a sessões persistentes de ACP. Use um identificador do BlueBubbles ou uma string de destino (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) em `match.peer.id`. Semântica de campos compartilhados: [Agentes ACP](/pt-BR/tools/acp-agents#channel-specific-settings).
- O `channels.bluebubbles.defaultAccount` opcional substitui a seleção padrão de conta quando corresponde a um id de conta configurado.
- Entradas `bindings[]` de nível superior com `type: "acp"` podem vincular conversas do BlueBubbles a sessões ACP persistentes. Use um identificador do BlueBubbles ou uma string de destino (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) em `match.peer.id`. Semântica de campos compartilhados: [Agentes ACP](/pt-BR/tools/acp-agents#channel-specific-settings).
- A configuração completa do canal BlueBubbles está documentada em [BlueBubbles](/pt-BR/channels/bluebubbles).
### iMessage
@ -623,17 +609,17 @@ OpenClaw inicia `imsg rpc` (JSON-RPC sobre stdio). Nenhum daemon ou porta é nec
}
```
- `channels.imessage.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um ID de conta configurado.
- O `channels.imessage.defaultAccount` opcional substitui a seleção padrão de conta quando corresponde a um id de conta configurado.
- Requer Acesso Total ao Disco para o banco de dados do Messages.
- Requer Acesso Total ao Disco para o banco de dados do Mensagens.
- Prefira destinos `chat_id:<id>`. Use `imsg chats --limit 20` para listar chats.
- `cliPath` pode apontar para um wrapper SSH; defina `remoteHost` (`host` ou `user@host`) para buscar anexos via SCP.
- `attachmentRoots` e `remoteAttachmentRoots` restringem caminhos de anexos recebidos (padrão: `/Users/*/Library/Messages/Attachments`).
- SCP usa verificação estrita de chave de host, portanto garanta que a chave do host de retransmissão já exista em `~/.ssh/known_hosts`.
- `cliPath` pode apontar para um wrapper SSH; defina `remoteHost` (`host` ou `user@host`) para buscar anexos por SCP.
- `attachmentRoots` e `remoteAttachmentRoots` restringem caminhos de anexos de entrada (padrão: `/Users/*/Library/Messages/Attachments`).
- O SCP usa verificação estrita de chave de host, portanto garanta que a chave do host de retransmissão já exista em `~/.ssh/known_hosts`.
- `channels.imessage.configWrites`: permite ou nega gravações de configuração iniciadas pelo iMessage.
- Entradas `bindings[]` de nível superior com `type: "acp"` podem vincular conversas do iMessage a sessões persistentes de ACP. Use um identificador normalizado ou destino de chat explícito (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) em `match.peer.id`. Semântica de campos compartilhados: [Agentes ACP](/pt-BR/tools/acp-agents#channel-specific-settings).
- Entradas `bindings[]` de nível superior com `type: "acp"` podem vincular conversas do iMessage a sessões ACP persistentes. Use um identificador normalizado ou destino de chat explícito (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) em `match.peer.id`. Semântica de campos compartilhados: [Agentes ACP](/pt-BR/tools/acp-agents#channel-specific-settings).
<Accordion title="Exemplo de wrapper SSH para iMessage">
<Accordion title="Exemplo de wrapper SSH do iMessage">
```bash
#!/usr/bin/env bash
@ -644,7 +630,7 @@ exec ssh -T gateway-host imsg "$@"
### Matrix
Matrix é respaldado por Plugin e configurado em `channels.matrix`.
Matrix tem suporte de Plugin e é configurado em `channels.matrix`.
```json5
{
@ -674,25 +660,25 @@ Matrix é respaldado por Plugin e configurado em `channels.matrix`.
}
```
- Autenticação por token usa `accessToken`; autenticação por senha usa `userId` + `password`.
- `channels.matrix.proxy` roteia o tráfego HTTP do Matrix por um proxy HTTP(S) explícito. Contas nomeadas podem substituí-lo com `channels.matrix.accounts.<id>.proxy`.
- A autenticação por token usa `accessToken`; a autenticação por senha usa `userId` + `password`.
- `channels.matrix.proxy` roteia o tráfego HTTP do Matrix por meio de um proxy HTTP(S) explícito. Contas nomeadas podem substituí-lo com `channels.matrix.accounts.<id>.proxy`.
- `channels.matrix.network.dangerouslyAllowPrivateNetwork` permite homeservers privados/internos. `proxy` e essa adesão de rede são controles independentes.
- `channels.matrix.defaultAccount` seleciona a conta preferida em configurações com várias contas.
- `channels.matrix.autoJoin` usa `off` por padrão, então salas convidadas e novos convites no estilo DM são ignorados até você definir `autoJoin: "allowlist"` com `autoJoinAllowlist` ou `autoJoin: "always"`.
- `channels.matrix.autoJoin` tem `off` como padrão, então salas com convite e novos convites no estilo DM são ignorados até que você defina `autoJoin: "allowlist"` com `autoJoinAllowlist` ou `autoJoin: "always"`.
- `channels.matrix.execApprovals`: entrega de aprovação de exec nativa do Matrix e autorização de aprovador.
- `enabled`: `true`, `false` ou `"auto"` (padrão). No modo automático, aprovações de exec são ativadas quando aprovadores podem ser resolvidos de `approvers` ou `commands.ownerAllowFrom`.
- `approvers`: IDs de usuário do Matrix (por exemplo, `@owner:example.org`) autorizados a aprovar solicitações de exec.
- `agentFilter`: allowlist opcional de IDs de agente. Omita para encaminhar aprovações para todos os agentes.
- `approvers`: IDs de usuário Matrix (por exemplo, `@owner:example.org`) autorizados a aprovar solicitações de exec.
- `agentFilter`: lista de permissões opcional de IDs de agente. Omita para encaminhar aprovações para todos os agentes.
- `sessionFilter`: padrões opcionais de chave de sessão (substring ou regex).
- `target`: para onde enviar prompts de aprovação. `"dm"` (padrão), `"channel"` (sala de origem) ou `"both"`.
- Substituições por conta: `channels.matrix.accounts.<id>.execApprovals`.
- `channels.matrix.dm.sessionScope` controla como DMs do Matrix são agrupadas em sessões: `per-user` (padrão) compartilha por par roteado, enquanto `per-room` isola cada sala de DM.
- Sondas de status do Matrix e consultas de diretório ao vivo usam a mesma política de proxy do tráfego em tempo de execução.
- A configuração completa do Matrix, regras de direcionamento e exemplos de configuração estão documentados em [Matrix](/pt-BR/channels/matrix).
- `channels.matrix.dm.sessionScope` controla como DMs do Matrix são agrupadas em sessões: `per-user` (padrão) compartilha pelo par roteado, enquanto `per-room` isola cada sala de DM.
- Sondagens de status do Matrix e consultas de diretório ao vivo usam a mesma política de proxy do tráfego em runtime.
- A configuração completa do Matrix, regras de destino e exemplos de configuração estão documentados em [Matrix](/pt-BR/channels/matrix).
### Microsoft Teams
Microsoft Teams é respaldado por Plugin e configurado em `channels.msteams`.
Microsoft Teams tem suporte de Plugin e é configurado em `channels.msteams`.
```json5
{
@ -712,7 +698,7 @@ Microsoft Teams é respaldado por Plugin e configurado em `channels.msteams`.
### IRC
IRC é respaldado por Plugin e configurado em `channels.irc`.
IRC tem suporte de Plugin e é configurado em `channels.irc`.
```json5
{
@ -734,8 +720,8 @@ IRC é respaldado por Plugin e configurado em `channels.irc`.
```
- Caminhos de chave principais cobertos aqui: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`.
- `channels.irc.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um ID de conta configurado.
- A configuração completa do canal IRC (host/porta/TLS/canais/allowlists/bloqueio por menção) está documentada em [IRC](/pt-BR/channels/irc).
- O `channels.irc.defaultAccount` opcional substitui a seleção padrão de conta quando corresponde a um id de conta configurado.
- A configuração completa do canal IRC (host/porta/TLS/canais/listas de permissão/bloqueio por menção) está documentada em [IRC](/pt-BR/channels/irc).
### Várias contas (todos os canais)
@ -761,29 +747,31 @@ Execute várias contas por canal (cada uma com seu próprio `accountId`):
```
- `default` é usado quando `accountId` é omitido (CLI + roteamento).
- Tokens de env se aplicam apenas à conta **padrão**.
- As configurações base do canal se aplicam a todas as contas, salvo substituição por conta.
- Use `bindings[].match.accountId` para rotear cada conta a um agente diferente.
- Se você adicionar uma conta não padrão via `openclaw channels add` (ou integração de canal) enquanto ainda estiver em uma configuração de canal de nível superior com uma única conta, OpenClaw promove primeiro valores de conta única de nível superior com escopo de conta para o mapa de contas do canal, para que a conta original continue funcionando. A maioria dos canais os move para `channels.<channel>.accounts.default`; Matrix pode preservar um destino nomeado/padrão correspondente existente em vez disso.
- Tokens de ambiente se aplicam somente à conta **padrão**.
- Configurações básicas do canal se aplicam a todas as contas, a menos que sejam substituídas por conta.
- Use `bindings[].match.accountId` para rotear cada conta para um agente diferente.
- Se você adicionar uma conta não padrão por meio de `openclaw channels add` (ou onboarding de canal) enquanto ainda estiver em uma configuração de canal de nível superior com conta única, OpenClaw primeiro promove valores de conta única de nível superior com escopo de conta para o mapa de contas do canal, para que a conta original continue funcionando. A maioria dos canais os move para `channels.<channel>.accounts.default`; Matrix pode preservar um destino nomeado/padrão correspondente existente.
- Vinculações existentes somente de canal (sem `accountId`) continuam correspondendo à conta padrão; vinculações com escopo de conta permanecem opcionais.
- `openclaw doctor --fix` também repara formatos mistos movendo valores de conta única de nível superior com escopo de conta para a conta promovida escolhida para esse canal. A maioria dos canais usa `accounts.default`; Matrix pode preservar um destino nomeado/padrão correspondente existente em vez disso.
- `openclaw doctor --fix` também repara formatos mistos movendo valores de conta única de nível superior com escopo de conta para a conta promovida escolhida para esse canal. A maioria dos canais usa `accounts.default`; Matrix pode preservar um destino nomeado/padrão correspondente existente.
### Outros canais de Plugin
Muitos canais de Plugin são configurados como `channels.<id>` e documentados em suas páginas de canal dedicadas (por exemplo, Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat e Twitch).
Veja o índice completo de canais: [Canais](/pt-BR/channels).
### Bloqueio por menção em chats de grupo
### Controle de menção em chats em grupo
Mensagens de grupo usam por padrão **exigir menção** (menção de metadados ou padrões regex seguros). Aplica-se a chats de grupo do WhatsApp, Telegram, Discord, Google Chat e iMessage.
Mensagens de grupo exigem **menção obrigatória** por padrão (menção de metadados ou padrões regex seguros). Aplica-se a chats em grupo do WhatsApp, Telegram, Discord, Google Chat e iMessage.
Respostas visíveis são controladas separadamente. Salas de grupo/canal usam por padrão `messages.groupChat.visibleReplies: "message_tool"`: OpenClaw ainda processa o turno, mas respostas finais normais permanecem privadas e a saída visível na sala exige `message(action=send)`. Defina `"automatic"` somente quando quiser o comportamento legado em que respostas normais são publicadas de volta na sala. Para aplicar o mesmo comportamento de resposta visível somente por ferramenta também a chats diretos, defina `messages.visibleReplies: "message_tool"`.
Respostas visíveis são controladas separadamente. Salas de grupo/canal usam `messages.groupChat.visibleReplies: "message_tool"` como padrão: OpenClaw ainda processa o turno, mas respostas finais normais permanecem privadas, e saída visível na sala requer `message(action=send)`. Defina `"automatic"` somente quando quiser o comportamento legado em que respostas normais são publicadas de volta na sala. Para aplicar o mesmo comportamento de resposta visível somente por ferramenta também a chats diretos, defina `messages.visibleReplies: "message_tool"`.
O Gateway recarrega a configuração de `messages` a quente após o arquivo ser salvo. Reinicie somente quando a observação de arquivos ou o recarregamento de configuração estiver desativado na implantação.
**Tipos de menção:**
- **Menções de metadados**: @menções nativas da plataforma. Ignoradas no modo de chat consigo mesmo do WhatsApp.
- **Padrões de texto**: Padrões regex seguros em `agents.list[].groupChat.mentionPatterns`. Padrões inválidos e repetição aninhada insegura são ignorados.
- O bloqueio por menção é imposto somente quando a detecção é possível (menções nativas ou pelo menos um padrão).
- **Menções de metadados**: @menções nativas da plataforma. Ignoradas no modo de autochat do WhatsApp.
- **Padrões de texto**: padrões regex seguros em `agents.list[].groupChat.mentionPatterns`. Padrões inválidos e repetição aninhada insegura são ignorados.
- O controle de menção é aplicado somente quando a detecção é possível (menções nativas ou pelo menos um padrão).
```json5
{
@ -802,7 +790,7 @@ Respostas visíveis são controladas separadamente. Salas de grupo/canal usam po
`messages.groupChat.historyLimit` define o padrão global. Canais podem substituir com `channels.<channel>.historyLimit` (ou por conta). Defina `0` para desativar.
`messages.visibleReplies` é o padrão global de turno de origem; `messages.groupChat.visibleReplies` o substitui para turnos de origem de grupo/canal. Allowlists de canal e bloqueio por menção ainda decidem se um turno é processado.
`messages.visibleReplies` é o padrão global para turnos de origem; `messages.groupChat.visibleReplies` o substitui para turnos de origem em grupo/canal. Listas de permissão de canal e controle de menção ainda decidem se um turno é processado.
#### Limites de histórico de DM
@ -823,9 +811,9 @@ Resolução: substituição por DM → padrão do provedor → sem limite (tudo
Compatível com: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`.
#### Modo de chat consigo mesmo
#### Modo de autochat
Inclua seu próprio número em `allowFrom` para ativar o modo de chat consigo mesmo (ignora @menções nativas, responde apenas a padrões de texto):
Inclua seu próprio número em `allowFrom` para ativar o modo de autochat (ignora @menções nativas, responde somente a padrões de texto):
```json5
{
@ -873,41 +861,41 @@ Inclua seu próprio número em `allowFrom` para ativar o modo de chat consigo me
}
```
<Accordion title="Command details">
<Accordion title="Detalhes dos comandos">
- Este bloco configura as superfícies de comando. Para o catálogo atual de comandos integrados + empacotados, consulte [Comandos Slash](/pt-BR/tools/slash-commands).
- Esta página é uma **referência de chaves de configuração**, não o catálogo completo de comandos. Comandos pertencentes a canais/Plugins, como QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, pareamento de dispositivo `/pair`, memória `/dreaming`, controle de telefone `/phone` e Talk `/voice`, estão documentados em suas páginas de canal/Plugin, além de [Comandos Slash](/pt-BR/tools/slash-commands).
- Comandos de texto devem ser mensagens **independentes** com `/` inicial.
- `native: "auto"` ativa comandos nativos para Discord/Telegram, deixa Slack desativado.
- `nativeSkills: "auto"` ativa comandos nativos de Skills para Discord/Telegram, deixa Slack desativado.
- Sobrescreva por canal: `channels.discord.commands.native` (bool ou `"auto"`). `false` limpa comandos registrados anteriormente.
- Sobrescreva o registro de Skills nativas por canal com `channels.<provider>.commands.nativeSkills`.
- Este bloco configura superfícies de comandos. Para o catálogo atual de comandos integrados + incluídos no pacote, consulte [Comandos de barra](/pt-BR/tools/slash-commands).
- Esta página é uma **referência de chaves de configuração**, não o catálogo completo de comandos. Comandos pertencentes a canais/plugins, como QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, pareamento de dispositivos `/pair`, memória `/dreaming`, controle de telefone `/phone` e Talk `/voice`, são documentados nas páginas dos respectivos canais/plugins, além de [Comandos de barra](/pt-BR/tools/slash-commands).
- Comandos de texto devem ser mensagens **independentes** com `/` no início.
- `native: "auto"` ativa comandos nativos para Discord/Telegram e mantém Slack desativado.
- `nativeSkills: "auto"` ativa comandos nativos de Skills para Discord/Telegram e mantém Slack desativado.
- Substitua por canal: `channels.discord.commands.native` (bool ou `"auto"`). `false` limpa comandos registrados anteriormente.
- Substitua o registro nativo de Skills por canal com `channels.<provider>.commands.nativeSkills`.
- `channels.telegram.customCommands` adiciona entradas extras ao menu do bot do Telegram.
- `bash: true` habilita `! <cmd>` para o shell do host. Requer `tools.elevated.enabled` e remetente em `tools.elevated.allowFrom.<channel>`.
- `config: true` habilita `/config` (lê/grava `openclaw.json`). Para clientes `chat.send` do Gateway, gravações persistentes de `/config set|unset` também exigem `operator.admin`; `/config show` somente leitura continua disponível para clientes operadores normais com escopo de gravação.
- `config: true` habilita `/config` (lê/grava `openclaw.json`). Para clientes `chat.send` do Gateway, gravações persistentes de `/config set|unset` também exigem `operator.admin`; `/config show` somente leitura permanece disponível para clientes operadores normais com escopo de gravação.
- `mcp: true` habilita `/mcp` para configuração de servidor MCP gerenciado pelo OpenClaw em `mcp.servers`.
- `plugins: true` habilita `/plugins` para descoberta, instalação e controles de habilitar/desabilitar Plugins.
- `plugins: true` habilita `/plugins` para descoberta, instalação e controles de ativação/desativação de plugins.
- `channels.<provider>.configWrites` controla mutações de configuração por canal (padrão: true).
- Para canais com várias contas, `channels.<provider>.accounts.<id>.configWrites` também controla gravações que miram essa conta (por exemplo, `/allowlist --config --account <id>` ou `/config set channels.<provider>.accounts.<id>...`).
- `restart: false` desabilita `/restart` e ações da ferramenta de reinício do Gateway. Padrão: `true`.
- `ownerAllowFrom` é a allowlist explícita do proprietário para comandos/ferramentas somente de proprietário. Ela é separada de `allowFrom`.
- `ownerDisplay: "hash"` aplica hash aos IDs de proprietário no prompt do sistema. Defina `ownerDisplaySecret` para controlar o hashing.
- `allowFrom` é por provedor. Quando definido, é a **única** fonte de autorização (allowlists/pareamento de canal e `useAccessGroups` são ignorados).
- Para canais com várias contas, `channels.<provider>.accounts.<id>.configWrites` também controla gravações direcionadas a essa conta (por exemplo, `/allowlist --config --account <id>` ou `/config set channels.<provider>.accounts.<id>...`).
- `restart: false` desativa `/restart` e ações da ferramenta de reinício do Gateway. Padrão: `true`.
- `ownerAllowFrom` é a lista de permissão explícita do proprietário para comandos/ferramentas exclusivos do proprietário. Ela é separada de `allowFrom`.
- `ownerDisplay: "hash"` aplica hash aos ids do proprietário no prompt do sistema. Defina `ownerDisplaySecret` para controlar o hashing.
- `allowFrom` é por provedor. Quando definido, é a **única** fonte de autorização (listas de permissão/pareamento de canais e `useAccessGroups` são ignorados).
- `useAccessGroups: false` permite que comandos contornem políticas de grupos de acesso quando `allowFrom` não está definido.
- Mapa da documentação de comandos:
- catálogo integrado + empacotado: [Comandos Slash](/pt-BR/tools/slash-commands)
- catálogo integrado + incluído no pacote: [Comandos de barra](/pt-BR/tools/slash-commands)
- superfícies de comandos específicas de canal: [Canais](/pt-BR/channels)
- comandos do QQ Bot: [QQ Bot](/pt-BR/channels/qqbot)
- comandos de pareamento: [Pareamento](/pt-BR/channels/pairing)
- comando de cartão do LINE: [LINE](/pt-BR/channels/line)
- memória Dreaming: [Dreaming](/pt-BR/concepts/dreaming)
- dreaming de memória: [Dreaming](/pt-BR/concepts/dreaming)
</Accordion>
---
## Relacionados
## Relacionado
- [Referência de configuração](/pt-BR/gateway/configuration-reference) — chaves de nível superior
- [Configuração — agentes](/pt-BR/gateway/config-agents)
- [Visão geral de canais](/pt-BR/channels)
- [Visão geral dos canais](/pt-BR/channels)

339
docs/pt-BR/gateway/doctor.md
View File

@ -3,18 +3,18 @@ read_when:
- Adicionar ou modificar migrações do doctor
- Introduzindo alterações incompatíveis na configuração
sidebarTitle: Doctor
summary: 'Comando doctor: verificações de integridade, migrações de configuração e etapas de reparo'
summary: 'Comando Doctor: verificações de integridade, migrações de configuração e etapas de reparo'
title: Diagnóstico
x-i18n:
generated_at: "2026-04-30T09:48:43Z"
generated_at: "2026-04-30T16:28:43Z"
model: gpt-5.5
provider: openai
source_hash: c27b8e85eb0a577e676f0e6e205262775ff37303453e64fc1bc2adaf8b51147c
source_hash: 89150fe2b2848f1f168b42ca6b240bc0e6a0edee4f1bcad7f79d297face9c95e
source_path: gateway/doctor.md
workflow: 16
---
`openclaw doctor` é a ferramenta de reparo + migração do OpenClaw. Ela corrige configurações/estados obsoletos, verifica a saúde e fornece etapas de reparo acionáveis.
`openclaw doctor` é a ferramenta de reparo + migração do OpenClaw. Ela corrige configurações/estado obsoletos, verifica a integridade e fornece etapas de reparo acionáveis.
## Início rápido
@ -30,7 +30,7 @@ openclaw doctor
openclaw doctor --yes
```
Aceita os padrões sem solicitar confirmação (incluindo etapas de reinicialização/serviço/reparo de sandbox quando aplicável).
Aceita os padrões sem perguntar (incluindo etapas de reparo de reinício/serviço/sandbox quando aplicável).
</Tab>
<Tab title="--repair">
@ -38,7 +38,7 @@ openclaw doctor
openclaw doctor --repair
```
Aplica os reparos recomendados sem solicitar confirmação (reparos + reinicializações quando seguro).
Aplica os reparos recomendados sem perguntar (reparos + reinícios quando seguro).
</Tab>
<Tab title="--repair --force">
@ -46,7 +46,7 @@ openclaw doctor
openclaw doctor --repair --force
```
Aplica também reparos agressivos (sobrescreve configurações personalizadas do supervisor).
Aplica também reparos agressivos (sobrescreve configurações personalizadas de supervisor).
</Tab>
<Tab title="--non-interactive">
@ -54,7 +54,7 @@ openclaw doctor
openclaw doctor --non-interactive
```
Executa sem prompts e aplica apenas migrações seguras (normalização de configuração + movimentações de estado em disco). Ignora ações de reinicialização/serviço/sandbox que exigem confirmação humana. Migrações de estado legado são executadas automaticamente quando detectadas.
Executa sem prompts e aplica apenas migrações seguras (normalização de configuração + movimentações de estado em disco). Ignora ações de reinício/serviço/sandbox que exigem confirmação humana. Migrações de estado legado são executadas automaticamente quando detectadas.
</Tab>
<Tab title="--deep">
@ -67,7 +67,7 @@ openclaw doctor
</Tab>
</Tabs>
Se quiser revisar as alterações antes de gravar, abra primeiro o arquivo de configuração:
Se quiser revisar as alterações antes de gravar, abra o arquivo de configuração primeiro:
```bash
cat ~/.openclaw/openclaw.json
@ -76,58 +76,59 @@ cat ~/.openclaw/openclaw.json
## O que ele faz (resumo)
<AccordionGroup>
<Accordion title="Saúde, UI e atualizações">
- Atualização opcional de pré-verificação para instalações via git (somente interativo).
- Verificação de atualização do protocolo da UI (recompila a Control UI quando o esquema do protocolo é mais recente).
- Verificação de saúde + prompt de reinicialização.
<Accordion title="Integridade, UI e atualizações">
- Atualização opcional de pré-execução para instalações via git (somente interativo).
- Verificação de atualização do protocolo da UI (recompila a Control UI quando o esquema de protocolo é mais recente).
- Verificação de integridade + prompt de reinício.
- Resumo de status de Skills (elegíveis/ausentes/bloqueadas) e status de Plugin.
</Accordion>
<Accordion title="Configuração e migrações">
- Normalização de configuração para valores legados.
- Migração da configuração de Talk de campos planos legados `talk.*` para `talk.provider` + `talk.providers.<provider>`.
- Verificações de migração do navegador para configurações legadas da extensão do Chrome e prontidão do Chrome MCP.
- Avisos de substituição de provedor do OpenCode (`models.providers.opencode` / `models.providers.opencode-go`).
- Avisos de sombreamento de OAuth do Codex (`models.providers.openai-codex`).
- Verificação de pré-requisitos TLS de OAuth para perfis de OAuth do OpenAI Codex.
- Migração da configuração do Talk de campos planos legados `talk.*` para `talk.provider` + `talk.providers.<provider>`.
- Verificações de migração de navegador para configurações legadas da extensão do Chrome e prontidão do Chrome MCP.
- Avisos de substituição do provedor OpenCode (`models.providers.opencode` / `models.providers.opencode-go`).
- Avisos de sombreamento do OAuth do Codex (`models.providers.openai-codex`).
- Verificação de pré-requisitos de TLS do OAuth para perfis OAuth do OpenAI Codex.
- Migração de estado legado em disco (sessões/diretório do agente/autenticação do WhatsApp).
- Migração de chaves legadas do contrato de manifesto de Plugin (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`).
- Migração da store legada de Cron (`jobId`, `schedule.cron`, campos de entrega/payload no nível superior, payload `provider`, jobs simples de fallback de Webhook `notify: true`).
- Migração de política de runtime de agente legada para `agents.defaults.agentRuntime` e `agents.list[].agentRuntime`.
- Limpeza de configuração obsoleta de Plugin quando plugins estão habilitados; quando `plugins.enabled=false`, referências obsoletas de Plugin são tratadas como configuração de contenção inerte e são preservadas.
- Migração da store de Cron legada (`jobId`, `schedule.cron`, campos de entrega/payload de nível superior, payload `provider`, jobs simples de fallback de Webhook `notify: true`).
- Migração da política de runtime legada do agente para `agents.defaults.agentRuntime` e `agents.list[].agentRuntime`.
- Limpeza de configuração obsoleta de Plugin quando plugins estão habilitados; quando `plugins.enabled=false`, referências obsoletas de Plugin são tratadas como configuração inerte de contenção e são preservadas.
</Accordion>
<Accordion title="Estado e integridade">
- Inspeção de arquivos de lock de sessão e limpeza de locks obsoletos.
- Reparo de transcrições de sessão para branches duplicadas de reescrita de prompt criadas por builds afetadas de 2026.4.24.
- Verificações de integridade e permissões de estado (sessões, transcrições, diretório de estado).
- Verificações de permissões do arquivo de configuração (chmod 600) ao executar localmente.
- Saúde de autenticação de modelos: verifica expiração de OAuth, pode atualizar tokens próximos da expiração e relata estados de cooldown/desativado de perfis de autenticação.
- Reparo de transcritos de sessão para ramificações duplicadas de reescrita de prompt criadas por builds 2026.4.24 afetadas.
- Detecção de tombstones de recuperação por reinício de subagentes travados, com suporte a `--fix` para limpar flags obsoletas de recuperação abortada, para que a inicialização não continue tratando o filho como abortado por reinício.
- Verificações de integridade de estado e permissões (sessões, transcritos, diretório de estado).
- Verificações de permissão do arquivo de configuração (chmod 600) ao executar localmente.
- Integridade da autenticação de modelo: verifica expiração de OAuth, pode atualizar tokens prestes a expirar e relata estados de cooldown/desabilitação de perfis de autenticação.
- Detecção de diretório extra de workspace (`~/openclaw`).
</Accordion>
<Accordion title="Gateway, serviços e supervisores">
- Reparo de imagem de sandbox quando sandboxing está habilitado.
- Migração de serviços legados e detecção de Gateway extra.
- Reparo da imagem de sandbox quando sandboxing está habilitado.
- Migração de serviço legado e detecção de Gateway extra.
- Migração de estado legado do canal Matrix (no modo `--fix` / `--repair`).
- Verificações de runtime do Gateway (serviço instalado mas não em execução; rótulo launchd em cache).
- Avisos de status de canais (sondados a partir do Gateway em execução).
- Verificações de runtime do Gateway (serviço instalado, mas não em execução; rótulo launchd em cache).
- Avisos de status de canal (sondados a partir do Gateway em execução).
- Auditoria de configuração de supervisor (launchd/systemd/schtasks) com reparo opcional.
- Limpeza do ambiente de proxy embutido para serviços do Gateway que capturaram valores de shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` durante instalação ou atualização.
- Verificações de boas práticas de runtime do Gateway (Node vs Bun, caminhos de gerenciadores de versão).
- Limpeza de ambiente de proxy embutido para serviços do Gateway que capturaram valores shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` durante a instalação ou atualização.
- Verificações de melhores práticas de runtime do Gateway (Node vs Bun, caminhos de gerenciador de versões).
- Diagnósticos de colisão de porta do Gateway (padrão `18789`).
</Accordion>
<Accordion title="Autenticação, segurança e pareamento">
- Avisos de segurança para políticas abertas de DM.
- Verificações de autenticação do Gateway para modo de token local (oferece geração de token quando nenhuma origem de token existe; não sobrescreve configurações SecretRef de token).
- Detecção de problemas de pareamento de dispositivos (solicitações pendentes de primeiro pareamento, upgrades pendentes de função/escopo, divergência obsoleta de cache local de token de dispositivo e divergência de autenticação de registro pareado).
- Verificações de autenticação do Gateway para modo de token local (oferece geração de token quando não existe fonte de token; não sobrescreve configurações SecretRef de token).
- Detecção de problemas de pareamento de dispositivo (solicitações pendentes de pareamento inicial, upgrades pendentes de função/escopo, divergência de cache local obsoleto de token de dispositivo e divergência de autenticação de registro pareado).
</Accordion>
<Accordion title="Workspace e shell">
- Verificação de linger do systemd no Linux.
- Verificação de tamanho de arquivo de bootstrap do workspace (avisos de truncamento/quase limite para arquivos de contexto).
- Verificação de status de completions do shell e instalação/upgrade automático.
- Verificação de tamanho do arquivo de bootstrap do workspace (avisos de truncamento/quase limite para arquivos de contexto).
- Verificação de status de conclusão do shell e instalação/upgrade automático.
- Verificação de prontidão do provedor de embeddings de busca de memória (modelo local, chave de API remota ou binário QMD).
- Verificações de instalação a partir do código-fonte (incompatibilidade de workspace pnpm, assets de UI ausentes, binário tsx ausente).
- Grava configuração atualizada + metadados do assistente.
@ -135,52 +136,52 @@ cat ~/.openclaw/openclaw.json
</Accordion>
</AccordionGroup>
## Backfill e reset da UI de Dreams
## Preenchimento retroativo e redefinição da UI Dreams
A cena Dreams da Control UI inclui as ações **Backfill**, **Reset** e **Clear Grounded** para o fluxo de trabalho de dreaming fundamentado. Essas ações usam métodos RPC no estilo do Gateway doctor, mas **não** fazem parte do reparo/migração da CLI `openclaw doctor`.
A cena Dreams da Control UI inclui ações **Backfill**, **Reset** e **Clear Grounded** para o fluxo de trabalho de Dreaming fundamentado. Essas ações usam métodos RPC no estilo do Gateway doctor, mas **não** fazem parte do reparo/migração da CLI `openclaw doctor`.
O que elas fazem:
- **Backfill** examina arquivos históricos `memory/YYYY-MM-DD.md` no workspace ativo, executa a passagem de diário REM fundamentado e grava entradas reversíveis de backfill em `DREAMS.md`.
- **Reset** remove apenas essas entradas marcadas de diário de backfill de `DREAMS.md`.
- **Clear Grounded** remove apenas entradas de curto prazo staged, somente fundamentadas, que vieram de replay histórico e ainda não acumularam recall ao vivo nem suporte diário.
- **Backfill** examina arquivos históricos `memory/YYYY-MM-DD.md` no workspace ativo, executa a passagem de diário REM fundamentada e grava entradas reversíveis de preenchimento retroativo em `DREAMS.md`.
- **Reset** remove apenas essas entradas marcadas de diário de preenchimento retroativo de `DREAMS.md`.
- **Clear Grounded** remove apenas entradas encenadas de curto prazo somente fundamentadas que vieram de replay histórico e ainda não acumularam recall ao vivo ou suporte diário.
O que elas **não** fazem por conta própria:
O que elas **não** fazem por si mesmas:
- elas não editam `MEMORY.md`
- elas não executam migrações completas do doctor
- elas não fazem stage automático de candidatos fundamentados na store ativa de promoção de curto prazo, a menos que você execute explicitamente primeiro o caminho staged da CLI
- elas não encenam automaticamente candidatos fundamentados na store de promoção de curto prazo ao vivo, a menos que você execute explicitamente o caminho da CLI encenado primeiro
Se quiser que o replay histórico fundamentado influencie a faixa normal de promoção profunda, use o fluxo da CLI em vez disso:
Se quiser que o replay histórico fundamentado influencie a lane normal de promoção profunda, use o fluxo da CLI em vez disso:
```bash
openclaw memory rem-backfill --path ./memory --stage-short-term
```
Isso faz stage de candidatos duráveis fundamentados na store de dreaming de curto prazo, mantendo `DREAMS.md` como superfície de revisão.
Isso encena candidatos duráveis fundamentados na store de Dreaming de curto prazo, mantendo `DREAMS.md` como superfície de revisão.
## Comportamento detalhado e justificativa
<AccordionGroup>
<Accordion title="0. Atualização opcional (instalações via git)">
Se esta for uma checkout git e o doctor estiver em execução interativa, ele oferece atualizar (fetch/rebase/build) antes de executar o doctor.
Se este for um checkout git e o doctor estiver sendo executado interativamente, ele oferecerá uma atualização (fetch/rebase/build) antes de executar o doctor.
</Accordion>
<Accordion title="1. Normalização de configuração">
Se a configuração contiver formatos de valores legados (por exemplo, `messages.ackReaction` sem uma substituição específica de canal), o doctor os normaliza para o esquema atual.
Isso inclui campos planos legados de Talk. A configuração pública atual de Talk é `talk.provider` + `talk.providers.<provider>`. O doctor reescreve formatos antigos `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` no mapa de provedores.
Isso inclui campos planos legados do Talk. A configuração pública atual do Talk é `talk.provider` + `talk.providers.<provider>`. O doctor reescreve formatos antigos `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` no mapa de provedores.
</Accordion>
<Accordion title="2. Migrações de chaves de configuração legadas">
Quando a configuração contém chaves obsoletas, outros comandos se recusam a executar e pedem que você execute `openclaw doctor`.
O doctor vai:
O doctor irá:
- Explicar quais chaves legadas foram encontradas.
- Mostrar a migração que aplicou.
- Mostrar a migração aplicada.
- Reescrever `~/.openclaw/openclaw.json` com o esquema atualizado.
O Gateway também executa automaticamente migrações do doctor na inicialização quando detecta um formato legado de configuração, então configurações obsoletas são reparadas sem intervenção manual. Migrações da store de jobs Cron são tratadas por `openclaw doctor --fix`.
O Gateway também executa migrações do doctor automaticamente na inicialização quando detecta um formato de configuração legado, para que configurações obsoletas sejam reparadas sem intervenção manual. Migrações da store de jobs Cron são tratadas por `openclaw doctor --fix`.
Migrações atuais:
@ -205,70 +206,70 @@ Isso faz stage de candidatos duráveis fundamentados na store de dreaming de cur
- `plugins.entries.voice-call.config.streaming.sttProvider` → `plugins.entries.voice-call.config.streaming.provider`
- `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold` → `plugins.entries.voice-call.config.streaming.providers.openai.*`
- `bindings[].match.accountID` → `bindings[].match.accountId`
- Para canais com `accounts` nomeadas, mas valores persistentes de canal de nível superior de conta única, move esses valores com escopo de conta para a conta promovida escolhida para esse canal (`accounts.default` para a maioria dos canais; Matrix pode preservar um destino nomeado/padrão correspondente existente)
- Para canais com `accounts` nomeadas, mas valores de canal de nível superior de conta única remanescentes, move esses valores com escopo de conta para a conta promovida escolhida para esse canal (`accounts.default` para a maioria dos canais; Matrix pode preservar um destino nomeado/padrão correspondente existente)
- `identity` → `agents.list[].identity`
- `agent.*` → `agents.defaults` + `tools.*` (tools/elevated/exec/sandbox/subagents)
- `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks` → `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks`
- remove `agents.defaults.llm`; use `models.providers.<id>.timeoutSeconds` para timeouts lentos de provedor/modelo
- remove `agents.defaults.llm`; use `models.providers.<id>.timeoutSeconds` para timeouts de provedor/modelo lentos
- `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`
- `browser.profiles.*.driver: "extension"` → `"existing-session"`
- remove `browser.relayBindHost` (configuração legada de relay da extensão)
- `models.providers.*.api: "openai"` legado → `"openai-completions"` (a inicialização do Gateway também ignora provedores cujo `api` está definido como um valor enum futuro ou desconhecido, em vez de falhar de forma fechada)
- `models.providers.*.api: "openai"` legado → `"openai-completions"` (a inicialização do gateway também ignora provedores cujo `api` está definido como valor de enum futuro ou desconhecido, em vez de falhar fechado)
Os avisos do doctor também incluem orientação de conta padrão para canais multi-conta:
Os avisos do doctor também incluem orientação de padrão de conta para canais com várias contas:
- Se duas ou mais entradas `channels.<channel>.accounts` estiverem configuradas sem `channels.<channel>.defaultAccount` ou `accounts.default`, o doctor avisa que o roteamento de fallback pode escolher uma conta inesperada.
- Se `channels.<channel>.defaultAccount` estiver definido para um ID de conta desconhecido, o doctor avisa e lista os IDs de conta configurados.
- Se `channels.<channel>.defaultAccount` estiver definido como um ID de conta desconhecido, o doctor avisa e lista os IDs de conta configurados.
</Accordion>
<Accordion title="2b. Substituições do provedor OpenCode">
Se você adicionou `models.providers.opencode`, `opencode-zen` ou `opencode-go` manualmente, isso substitui o catálogo OpenCode integrado de `@mariozechner/pi-ai`. Isso pode forçar modelos para a API errada ou zerar custos. O doctor avisa para que você possa remover a substituição e restaurar o roteamento de API por modelo + custos.
Se você adicionou `models.providers.opencode`, `opencode-zen` ou `opencode-go` manualmente, isso substitui o catálogo OpenCode integrado de `@mariozechner/pi-ai`. Isso pode forçar modelos para a API errada ou zerar custos. O doctor avisa para que você possa remover a substituição e restaurar o roteamento de API + custos por modelo.
</Accordion>
<Accordion title="2c. Migração do navegador e prontidão do Chrome MCP">
Se a configuração do seu navegador ainda aponta para o caminho removido da extensão do Chrome, o doctor a normaliza para o modelo atual de anexação Chrome MCP local ao host:
Se sua configuração de navegador ainda aponta para o caminho removido da extensão do Chrome, o doctor a normaliza para o modelo atual de anexação do Chrome MCP local ao host:
- `browser.profiles.*.driver: "extension"` se torna `"existing-session"`
- `browser.profiles.*.driver: "extension"` vira `"existing-session"`
- `browser.relayBindHost` é removido
O doctor também audita o caminho Chrome MCP local ao host quando você usa `defaultProfile: "user"` ou um perfil `existing-session` configurado:
O doctor também audita o caminho do Chrome MCP local ao host quando você usa `defaultProfile: "user"` ou um perfil `existing-session` configurado:
- verifica se o Google Chrome está instalado no mesmo host para perfis padrão de conexão automática
- verifica a versão detectada do Chrome e avisa quando ela é inferior ao Chrome 144
- lembra você de habilitar a depuração remota na página de inspeção do navegador (por exemplo `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging` ou `edge://inspect/#remote-debugging`)
- verifica a versão detectada do Chrome e avisa quando ela está abaixo do Chrome 144
- lembra você de habilitar a depuração remota na página de inspeção do navegador (por exemplo, `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging` ou `edge://inspect/#remote-debugging`)
O doctor não consegue habilitar a configuração do lado do Chrome para você. O Chrome MCP local ao host ainda exige:
O doctor não pode habilitar a configuração do lado do Chrome para você. O Chrome MCP local ao host ainda exige:
- um navegador baseado em Chromium 144+ no host do Gateway/Node
- um navegador baseado em Chromium 144+ no host do gateway/node
- o navegador em execução localmente
- depuração remota habilitada nesse navegador
- aprovação do primeiro prompt de consentimento de anexação no navegador
- aprovar o primeiro prompt de consentimento de anexação no navegador
A prontidão aqui trata apenas dos pré-requisitos de anexação local. Existing-session mantém os limites atuais de rota do Chrome MCP; rotas avançadas como `responsebody`, exportação de PDF, interceptação de downloads e ações em lote ainda exigem um navegador gerenciado ou perfil CDP bruto.
Esta verificação **não** se aplica a Docker, sandbox, navegador remoto ou outros fluxos headless. Eles continuam usando CDP bruto.
Esta verificação **não** se aplica a Docker, sandbox, remote-browser ou outros fluxos headless. Esses continuam usando CDP bruto.
</Accordion>
<Accordion title="2d. Pré-requisitos de TLS do OAuth">
Quando um perfil OAuth do OpenAI Codex é configurado, o doctor sonda o endpoint de autorização da OpenAI para verificar se a pilha TLS local de Node/OpenSSL consegue validar a cadeia de certificados. Se a sondagem falhar com um erro de certificado (por exemplo `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, certificado expirado ou certificado autoassinado), o doctor imprime orientações de correção específicas da plataforma. No macOS com um Node do Homebrew, a correção normalmente é `brew postinstall ca-certificates`. Com `--deep`, a sondagem é executada mesmo se o gateway estiver saudável.
Quando um perfil OAuth do OpenAI Codex está configurado, o doctor sonda o endpoint de autorização da OpenAI para verificar se a pilha TLS local do Node/OpenSSL consegue validar a cadeia de certificados. Se a sondagem falhar com um erro de certificado (por exemplo, `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, certificado expirado ou certificado autoassinado), o doctor imprime orientações de correção específicas da plataforma. No macOS com um Node do Homebrew, a correção geralmente é `brew postinstall ca-certificates`. Com `--deep`, a sondagem é executada mesmo se o gateway estiver íntegro.
</Accordion>
<Accordion title="2e. Substituições do provedor Codex OAuth">
Se você adicionou anteriormente configurações legadas de transporte OpenAI em `models.providers.openai-codex`, elas podem obscurecer o caminho do provedor Codex OAuth integrado que versões mais novas usam automaticamente. O doctor avisa quando vê essas configurações antigas de transporte junto com Codex OAuth para que você possa remover ou reescrever a substituição de transporte obsoleta e recuperar o comportamento integrado de roteamento/fallback. Proxies personalizados e substituições apenas de cabeçalho ainda são compatíveis e não acionam este aviso.
<Accordion title="2e. Substituições do provedor OAuth do Codex">
Se você adicionou anteriormente configurações legadas de transporte da OpenAI em `models.providers.openai-codex`, elas podem mascarar o caminho do provedor OAuth do Codex integrado que versões mais novas usam automaticamente. O doctor avisa quando encontra essas configurações antigas de transporte junto com OAuth do Codex, para que você possa remover ou reescrever a substituição de transporte obsoleta e recuperar o comportamento integrado de roteamento/fallback. Proxies personalizados e substituições apenas de cabeçalho ainda são compatíveis e não acionam este aviso.
</Accordion>
<Accordion title="2f. Avisos de rota do Plugin Codex">
Quando o Plugin Codex incluído está habilitado, o doctor também verifica se refs de modelo primário `openai-codex/*` ainda resolvem pelo runner PI padrão. Essa combinação é válida quando você quer autenticação Codex OAuth/por assinatura via PI, mas é fácil confundi-la com o harness nativo de app-server do Codex. O doctor avisa e aponta para a forma explícita de app-server: `openai/*` mais `agentRuntime.id: "codex"` ou `OPENCLAW_AGENT_RUNTIME=codex`.
Quando o Plugin Codex incluído está habilitado, o doctor também verifica se referências de modelo primário `openai-codex/*` ainda são resolvidas pelo executor PI padrão. Essa combinação é válida quando você quer autenticação OAuth/assinatura do Codex via PI, mas é fácil confundi-la com o harness app-server nativo do Codex. O doctor avisa e aponta para a forma explícita de app-server: `openai/*` mais `agentRuntime.id: "codex"` ou `OPENCLAW_AGENT_RUNTIME=codex`.
O doctor não corrige isso automaticamente porque ambas as rotas são válidas:
O doctor não repara isso automaticamente porque ambas as rotas são válidas:
- `openai-codex/*` + PI significa "usar autenticação Codex OAuth/por assinatura pelo runner normal do OpenClaw."
- `openai/*` + `runtime: "codex"` significa "executar o turno incorporado pelo app-server nativo do Codex."
- `openai-codex/*` + PI significa "usar autenticação OAuth/assinatura do Codex pelo executor normal do OpenClaw."
- `openai/*` + `runtime: "codex"` significa "executar o turno embutido pelo app-server nativo do Codex."
- `/codex ...` significa "controlar ou vincular uma conversa nativa do Codex pelo chat."
- `/acp ...` ou `runtime: "acp"` significa "usar o adaptador externo ACP/acpx."
Se o aviso aparecer, escolha a rota que você pretendia e edite a configuração manualmente. Mantenha o aviso como está quando PI Codex OAuth for intencional.
Se o aviso aparecer, escolha a rota que você pretendia e edite a configuração manualmente. Mantenha o aviso como está quando o OAuth do Codex via PI for intencional.
</Accordion>
<Accordion title="3. Migrações de estado legado (layout em disco)">
O doctor consegue migrar layouts mais antigos em disco para a estrutura atual:
O doctor pode migrar layouts antigos em disco para a estrutura atual:
- Armazenamento de sessões + transcrições:
- de `~/.openclaw/sessions/` para `~/.openclaw/agents/<agentId>/sessions/`
@ -276,86 +277,86 @@ Isso faz stage de candidatos duráveis fundamentados na store de dreaming de cur
- de `~/.openclaw/agent/` para `~/.openclaw/agents/<agentId>/agent/`
- Estado de autenticação do WhatsApp (Baileys):
- de `~/.openclaw/credentials/*.json` legado (exceto `oauth.json`)
- para `~/.openclaw/credentials/whatsapp/<accountId>/...` (id de conta padrão: `default`)
- para `~/.openclaw/credentials/whatsapp/<accountId>/...` (ID da conta padrão: `default`)
Essas migrações são de melhor esforço e idempotentes; o doctor emitirá avisos quando deixar quaisquer pastas legadas para trás como backups. O Gateway/CLI também migra automaticamente as sessões legadas + diretório do agente na inicialização para que histórico/autenticação/modelos fiquem no caminho por agente sem uma execução manual do doctor. A autenticação do WhatsApp é intencionalmente migrada apenas via `openclaw doctor`. A normalização de provedor/mapa de provedores de conversa agora compara por igualdade estrutural, então diffs apenas de ordem de chaves não acionam mais alterações repetidas sem efeito de `doctor --fix`.
Essas migrações são de melhor esforço e idempotentes; o doctor emitirá avisos quando deixar pastas legadas para trás como backups. O Gateway/CLI também migra automaticamente as sessões legadas + o diretório do agente na inicialização, para que histórico/autenticação/modelos cheguem ao caminho por agente sem uma execução manual do doctor. A autenticação do WhatsApp é migrada intencionalmente apenas via `openclaw doctor`. A normalização de provedor/mapa de provedores de conversa agora compara por igualdade estrutural, então diffs apenas de ordem de chaves não acionam mais alterações repetidas sem efeito de `doctor --fix`.
</Accordion>
<Accordion title="3a. Migrações de manifesto de Plugin legado">
O doctor verifica todos os manifestos de Plugins instalados em busca de chaves de capacidade de nível superior obsoletas (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). Quando as encontra, ele oferece movê-las para o objeto `contracts` e reescrever o arquivo de manifesto in-place. Esta migração é idempotente; se a chave `contracts` já tiver os mesmos valores, a chave legada é removida sem duplicar os dados.
<Accordion title="3a. Migrações de manifestos legados de Plugin">
O doctor verifica todos os manifestos de Plugin instalados em busca de chaves de capacidade de nível superior obsoletas (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). Quando encontradas, ele oferece movê-las para o objeto `contracts` e reescrever o arquivo de manifesto no local. Esta migração é idempotente; se a chave `contracts` já tiver os mesmos valores, a chave legada será removida sem duplicar os dados.
</Accordion>
<Accordion title="3b. Migrações de armazenamento de cron legado">
O doctor também verifica o armazenamento de jobs cron (`~/.openclaw/cron/jobs.json` por padrão, ou `cron.store` quando substituído) em busca de formatos antigos de job que o agendador ainda aceita por compatibilidade.
<Accordion title="3b. Migrações do armazenamento de Cron legado">
O doctor também verifica o armazenamento de tarefas cron (`~/.openclaw/cron/jobs.json` por padrão, ou `cron.store` quando substituído) em busca de formatos antigos de tarefa que o agendador ainda aceita por compatibilidade.
As limpezas atuais de cron incluem:
As limpezas de cron atuais incluem:
- `jobId` → `id`
- `schedule.cron` → `schedule.expr`
- campos de payload de nível superior (`message`, `model`, `thinking`, ...) → `payload`
- campos de entrega de nível superior (`deliver`, `channel`, `to`, `provider`, ...) → `delivery`
- aliases de entrega `provider` no payload → `delivery.channel` explícito
- jobs simples legados de fallback de Webhook com `notify: true` → `delivery.mode="webhook"` explícito com `delivery.to=cron.webhook`
- aliases de entrega `provider` do payload → `delivery.channel` explícito
- tarefas webhook simples legadas de fallback `notify: true` → `delivery.mode="webhook"` explícito com `delivery.to=cron.webhook`
O doctor só migra automaticamente jobs `notify: true` quando pode fazer isso sem alterar o comportamento. Se um job combinar fallback legado de notificação com um modo de entrega não Webhook existente, o doctor avisa e deixa esse job para revisão manual.
O doctor só migra automaticamente tarefas `notify: true` quando consegue fazer isso sem alterar o comportamento. Se uma tarefa combina fallback legado de notify com um modo de entrega não webhook existente, o doctor avisa e deixa essa tarefa para revisão manual.
</Accordion>
<Accordion title="3c. Limpeza de locks de sessão">
O doctor verifica cada diretório de sessão de agente em busca de arquivos de lock de escrita obsoletos — arquivos deixados para trás quando uma sessão saiu de forma anormal. Para cada arquivo de lock encontrado, ele relata: o caminho, PID, se o PID ainda está vivo, a idade do lock e se ele é considerado obsoleto (PID morto ou mais antigo que 30 minutos). No modo `--fix` / `--repair`, ele remove automaticamente arquivos de lock obsoletos; caso contrário, imprime uma observação e instrui você a executar novamente com `--fix`.
<Accordion title="3c. Limpeza de bloqueios de sessão">
O doctor verifica cada diretório de sessão de agente em busca de arquivos de bloqueio de escrita obsoletos — arquivos deixados para trás quando uma sessão encerrou de forma anormal. Para cada arquivo de bloqueio encontrado, ele relata: o caminho, PID, se o PID ainda está ativo, idade do bloqueio e se ele é considerado obsoleto (PID morto ou mais antigo que 30 minutos). No modo `--fix` / `--repair`, ele remove arquivos de bloqueio obsoletos automaticamente; caso contrário, imprime uma observação e instrui você a executar novamente com `--fix`.
</Accordion>
<Accordion title="3d. Reparo de ramificação de transcrição de sessão">
O doctor verifica arquivos JSONL de sessão de agente em busca do formato de ramificação duplicada criado pelo bug de reescrita de transcrição de prompt de 2026.4.24: um turno de usuário abandonado com contexto de runtime interno do OpenClaw mais um irmão ativo contendo o mesmo prompt de usuário visível. No modo `--fix` / `--repair`, o doctor faz backup de cada arquivo afetado ao lado do original e reescreve a transcrição para a ramificação ativa, para que o histórico do Gateway e os leitores de memória não vejam mais turnos duplicados.
O doctor verifica arquivos JSONL de sessão de agente em busca do formato de ramificação duplicada criado pelo bug de reescrita de transcrição de prompt de 2026.4.24: um turno de usuário abandonado com contexto interno de runtime do OpenClaw mais um irmão ativo contendo o mesmo prompt de usuário visível. No modo `--fix` / `--repair`, o doctor faz backup de cada arquivo afetado ao lado do original e reescreve a transcrição para a ramificação ativa, para que o histórico do gateway e os leitores de memória não vejam mais turnos duplicados.
</Accordion>
<Accordion title="4. Verificações de integridade de estado (persistência de sessão, roteamento e segurança)">
O diretório de estado é o tronco encefálico operacional. Se ele desaparecer, você perde sessões, credenciais, logs e configuração (a menos que tenha backups em outro lugar).
<Accordion title="4. Verificações de integridade do estado (persistência de sessão, roteamento e segurança)">
O diretório de estado é o tronco cerebral operacional. Se ele desaparecer, você perde sessões, credenciais, logs e configuração (a menos que tenha backups em outro lugar).
O doctor verifica:
- **Diretório de estado ausente**: avisa sobre perda catastrófica de estado, solicita recriar o diretório e lembra que não pode recuperar dados ausentes.
- **Permissões do diretório de estado**: verifica a capacidade de escrita; oferece reparar permissões (e emite uma dica de `chown` quando uma incompatibilidade de proprietário/grupo é detectada).
- **Diretório de estado sincronizado com nuvem no macOS**: avisa quando o estado resolve sob o iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) ou `~/Library/CloudStorage/...`, porque caminhos baseados em sincronização podem causar E/S mais lenta e corridas de lock/sincronização.
- **Diretório de estado em SD ou eMMC no Linux**: avisa quando o estado resolve para uma origem de montagem `mmcblk*`, porque E/S aleatória em SD ou eMMC pode ser mais lenta e desgastar mais rápido sob escritas de sessão e credenciais.
- **Diretório de estado ausente**: avisa sobre perda catastrófica de estado, pede para recriar o diretório e lembra que não consegue recuperar dados ausentes.
- **Permissões do diretório de estado**: verifica capacidade de escrita; oferece reparar permissões (e emite uma dica de `chown` quando uma divergência de proprietário/grupo é detectada).
- **Diretório de estado sincronizado em nuvem no macOS**: avisa quando o estado é resolvido em iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) ou `~/Library/CloudStorage/...`, porque caminhos com sincronização podem causar E/S mais lenta e corridas de bloqueio/sincronização.
- **Diretório de estado em SD ou eMMC no Linux**: avisa quando o estado é resolvido para uma fonte de montagem `mmcblk*`, porque E/S aleatória apoiada por SD ou eMMC pode ser mais lenta e desgastar mais rapidamente sob escritas de sessões e credenciais.
- **Diretórios de sessão ausentes**: `sessions/` e o diretório de armazenamento de sessões são necessários para persistir histórico e evitar falhas `ENOENT`.
- **Incompatibilidade de transcrição**: avisa quando entradas de sessão recentes têm arquivos de transcrição ausentes.
- **Sessão principal "JSONL de 1 linha"**: sinaliza quando a transcrição principal tem apenas uma linha (o histórico não está se acumulando).
- **Incompatibilidade de transcrição**: avisa quando entradas recentes de sessão têm arquivos de transcrição ausentes.
- **Sessão principal "JSONL de 1 linha"**: sinaliza quando a transcrição principal tem apenas uma linha (o histórico não está acumulando).
- **Múltiplos diretórios de estado**: avisa quando múltiplas pastas `~/.openclaw` existem em diretórios home ou quando `OPENCLAW_STATE_DIR` aponta para outro lugar (o histórico pode se dividir entre instalações).
- **Lembrete de modo remoto**: se `gateway.mode=remote`, o doctor lembra você de executá-lo no host remoto (o estado vive lá).
- **Permissões do arquivo de configuração**: avisa se `~/.openclaw/openclaw.json` é legível por grupo/mundo e oferece restringir para `600`.
- **Lembrete de modo remoto**: se `gateway.mode=remote`, o doctor lembra você de executá-lo no host remoto (o estado fica lá).
- **Permissões do arquivo de configuração**: avisa se `~/.openclaw/openclaw.json` está legível por grupo/mundo e oferece restringir para `600`.
</Accordion>
<Accordion title="5. Saúde da autenticação de modelos (expiração de OAuth)">
O doctor inspeciona perfis OAuth no armazenamento de autenticação, avisa quando tokens estão expirando/expirados e pode atualizá-los quando seguro. Se o perfil OAuth/token da Anthropic estiver obsoleto, ele sugere uma chave de API da Anthropic ou o caminho de setup-token da Anthropic. Prompts de atualização aparecem apenas ao executar interativamente (TTY); `--non-interactive` pula tentativas de atualização.
<Accordion title="5. Saúde de autenticação de modelo (expiração de OAuth)">
O doctor inspeciona perfis OAuth no armazenamento de autenticação, avisa quando tokens estão expirando/expirados e pode atualizá-los quando for seguro. Se o perfil OAuth/token da Anthropic estiver obsoleto, ele sugere uma chave de API da Anthropic ou o caminho de setup-token da Anthropic. Prompts de atualização aparecem apenas quando executado interativamente (TTY); `--non-interactive` ignora tentativas de atualização.
Quando uma atualização OAuth falha permanentemente (por exemplo `refresh_token_reused`, `invalid_grant` ou um provedor dizendo para você entrar novamente), o doctor relata que reautenticação é necessária e imprime o comando exato `openclaw models auth login --provider ...` a executar.
Quando uma atualização de OAuth falha permanentemente (por exemplo, `refresh_token_reused`, `invalid_grant` ou um provedor dizendo para você entrar novamente), o doctor informa que uma nova autenticação é necessária e imprime o comando exato `openclaw models auth login --provider ...` a ser executado.
O doctor também relata perfis de autenticação temporariamente inutilizáveis devido a:
O doctor também relata perfis de autenticação que estão temporariamente inutilizáveis devido a:
- cooldowns curtos (limites de taxa/timeouts/falhas de autenticação)
- desativações mais longas (falhas de faturamento/crédito)
- desativações mais longas (falhas de cobrança/crédito)
</Accordion>
<Accordion title="6. Validação de modelo de hooks">
Se `hooks.gmail.model` estiver definido, o doctor valida a referência do modelo em relação ao catálogo e à allowlist e avisa quando ela não resolve ou é proibida.
<Accordion title="6. Validação do modelo de hooks">
Se `hooks.gmail.model` estiver definido, o doctor valida a referência do modelo em relação ao catálogo e à allowlist e avisa quando ela não puder ser resolvida ou não for permitida.
</Accordion>
<Accordion title="7. Reparo de imagem de sandbox">
Quando sandboxing está habilitado, o doctor verifica imagens Docker e oferece criar ou alternar para nomes legados se a imagem atual estiver ausente.
Quando o sandboxing está habilitado, o doctor verifica as imagens Docker e oferece criar ou alternar para nomes legados se a imagem atual estiver ausente.
</Accordion>
<Accordion title="7b. Dependências de runtime de Plugins incluídos">
O doctor verifica dependências de runtime apenas para Plugins incluídos que estejam ativos na configuração atual ou habilitados pelo padrão do manifesto incluído, por exemplo `plugins.entries.discord.enabled: true`, `channels.discord.enabled: true` legado, `models.providers.*` / refs de modelo de agente configuradas, ou um Plugin incluído habilitado por padrão sem propriedade de provedor. Se alguma estiver ausente, o doctor relata os pacotes e os instala no modo `openclaw doctor --fix` / `openclaw doctor --repair`. Plugins externos ainda usam `openclaw plugins install` / `openclaw plugins update`; o doctor não instala dependências para caminhos arbitrários de Plugin.
<Accordion title="7b. Dependências de runtime de plugins incluídos">
O Doctor verifica dependências de runtime apenas para plugins incluídos que estão ativos na configuração atual ou habilitados pelo padrão do manifesto incluído, por exemplo `plugins.entries.discord.enabled: true`, o legado `channels.discord.enabled: true`, `models.providers.*` configurados / referências de modelo de agente, ou um plugin incluído habilitado por padrão sem propriedade de provedor. Se alguma estiver ausente, o doctor informa os pacotes e os instala no modo `openclaw doctor --fix` / `openclaw doctor --repair`. Plugins externos ainda usam `openclaw plugins install` / `openclaw plugins update`; o doctor não instala dependências para caminhos arbitrários de plugins.
Durante o reparo do doctor, instalações npm de dependências de runtime incluídas relatam progresso com spinner em sessões TTY e progresso periódico por linha em saída canalizada/headless. O Gateway e a CLI local também podem reparar dependências de runtime de Plugins incluídos ativos sob demanda antes de importar um Plugin incluído. Essas instalações são limitadas à raiz de instalação do runtime do Plugin, executadas com scripts desabilitados, não gravam um package lock e são protegidas por um bloqueio da raiz de instalação para que inicializações simultâneas da CLI ou do Gateway não modifiquem a mesma árvore `node_modules` ao mesmo tempo.
Durante o reparo do doctor, instalações npm de dependências de runtime incluídas relatam progresso por spinner em sessões TTY e progresso periódico em linhas em saída canalizada/headless. O Gateway e a CLI local também podem reparar dependências de runtime de plugins incluídos ativos sob demanda antes de importar um plugin incluído. Essas instalações ficam restritas à raiz de instalação do runtime do plugin, executam com scripts desabilitados, não gravam um package lock e são protegidas por um bloqueio da raiz de instalação para que inicializações simultâneas da CLI ou do Gateway não alterem a mesma árvore `node_modules` ao mesmo tempo.
</Accordion>
<Accordion title="8. Migrações de serviço do Gateway e dicas de limpeza">
O doctor detecta serviços de gateway legados (launchd/systemd/schtasks) e oferece removê-los e instalar o serviço OpenClaw usando a porta atual do gateway. Ele também pode procurar serviços extras semelhantes a gateway e imprimir dicas de limpeza. Serviços de gateway OpenClaw nomeados por perfil são considerados de primeira classe e não são sinalizados como "extras."
O Doctor detecta serviços de gateway legados (launchd/systemd/schtasks) e oferece removê-los e instalar o serviço do OpenClaw usando a porta atual do gateway. Ele também pode verificar serviços extras semelhantes ao gateway e imprimir dicas de limpeza. Serviços de gateway do OpenClaw nomeados por perfil são considerados de primeira classe e não são marcados como "extras".
No Linux, se o serviço de gateway em nível de usuário estiver ausente, mas existir um serviço de gateway OpenClaw em nível de sistema, o doctor não instala automaticamente um segundo serviço em nível de usuário. Inspecione com `openclaw gateway status --deep` ou `openclaw doctor --deep`; em seguida, remova a duplicata ou defina `OPENCLAW_SERVICE_REPAIR_POLICY=external` quando um supervisor de sistema controlar o ciclo de vida do gateway.
No Linux, se o serviço de gateway em nível de usuário estiver ausente, mas existir um serviço de gateway do OpenClaw em nível de sistema, o doctor não instala automaticamente um segundo serviço em nível de usuário. Inspecione com `openclaw gateway status --deep` ou `openclaw doctor --deep`, depois remova a duplicata ou defina `OPENCLAW_SERVICE_REPAIR_POLICY=external` quando um supervisor de sistema for responsável pelo ciclo de vida do gateway.
</Accordion>
<Accordion title="8b. Migração de inicialização do Matrix">
Quando uma conta de canal Matrix tem uma migração de estado legado pendente ou acionável, o doctor (no modo `--fix` / `--repair`) cria um snapshot pré-migração e depois executa as etapas de migração de melhor esforço: migração de estado legado do Matrix e preparação de estado criptografado legado. Ambas as etapas são não fatais; erros são registrados e a inicialização continua. No modo somente leitura (`openclaw doctor` sem `--fix`), essa verificação é totalmente ignorada.
Quando uma conta de canal Matrix tem uma migração de estado legado pendente ou acionável, o doctor (no modo `--fix` / `--repair`) cria um snapshot pré-migração e depois executa as etapas de migração de melhor esforço: migração de estado legado do Matrix e preparação de estado criptografado legado. Ambas as etapas não são fatais; erros são registrados e a inicialização continua. No modo somente leitura (`openclaw doctor` sem `--fix`), essa verificação é totalmente ignorada.
</Accordion>
<Accordion title="8c. Pareamento de dispositivos e desvio de autenticação">
O doctor agora inspeciona o estado de pareamento de dispositivos como parte da passagem normal de integridade.
O Doctor agora inspeciona o estado de pareamento de dispositivos como parte da passagem normal de saúde.
O que ele relata:
@ -364,123 +365,123 @@ Isso faz stage de candidatos duráveis fundamentados na store de dreaming de cur
- upgrades de escopo pendentes para dispositivos já pareados
- reparos de incompatibilidade de chave pública em que o id do dispositivo ainda corresponde, mas a identidade do dispositivo não corresponde mais ao registro aprovado
- registros pareados sem um token ativo para uma função aprovada
- tokens pareados cujos escopos se desviam da linha de base de pareamento aprovada
- entradas locais em cache de token de dispositivo para a máquina atual que são anteriores a uma rotação de token no lado do gateway ou carregam metadados de escopo obsoletos
- tokens pareados cujos escopos desviaram da linha de base de pareamento aprovada
- entradas locais em cache de token de dispositivo para a máquina atual anteriores a uma rotação de token no lado do gateway ou com metadados de escopo obsoletos
O doctor não aprova automaticamente solicitações de pareamento nem rotaciona automaticamente tokens de dispositivo. Em vez disso, ele imprime as próximas etapas exatas:
O Doctor não aprova automaticamente solicitações de pareamento nem rotaciona automaticamente tokens de dispositivo. Em vez disso, ele imprime os próximos passos exatos:
- inspecione solicitações pendentes com `openclaw devices list`
- aprove a solicitação exata com `openclaw devices approve <requestId>`
- rotacione um token novo com `openclaw devices rotate --device <deviceId> --role <role>`
- remova e aprove novamente um registro obsoleto com `openclaw devices remove <deviceId>`
Isso fecha a lacuna comum de "já pareado, mas ainda recebendo exigência de pareamento": o doctor agora distingue primeiro pareamento de upgrades pendentes de função/escopo e de desvios de token/identidade do dispositivo obsoletos.
Isso fecha a lacuna comum de "já pareado, mas ainda recebendo pareamento obrigatório": o doctor agora distingue primeiro pareamento de upgrades pendentes de função/escopo e de desvio de token/identidade de dispositivo obsoleto.
</Accordion>
<Accordion title="9. Avisos de segurança">
O doctor emite avisos quando um provedor está aberto a DMs sem uma allowlist, ou quando uma política está configurada de forma perigosa.
O Doctor emite avisos quando um provedor está aberto a DMs sem uma allowlist, ou quando uma política está configurada de forma perigosa.
</Accordion>
<Accordion title="10. Linger do systemd (Linux)">
Se estiver em execução como um serviço de usuário do systemd, o doctor garante que o lingering esteja habilitado para que o gateway continue ativo após o logout.
Se estiver executando como um serviço de usuário do systemd, o doctor garante que o lingering esteja habilitado para que o gateway permaneça ativo após o logout.
</Accordion>
<Accordion title="11. Status do workspace (Skills, Plugins e diretórios legados)">
O doctor imprime um resumo do estado do workspace para o agente padrão:
<Accordion title="11. Status do workspace (skills, plugins e diretórios legados)">
O Doctor imprime um resumo do estado do workspace para o agente padrão:
- **Status de Skills**: conta Skills elegíveis, com requisitos ausentes e bloqueadas por allowlist.
- **Diretórios de workspace legados**: avisa quando `~/openclaw` ou outros diretórios de workspace legados existem ao lado do workspace atual.
- **Status de Plugins**: conta Plugins habilitados/desabilitados/com erro; lista IDs de Plugins para quaisquer erros; relata capacidades de Plugins incluídos.
- **Avisos de compatibilidade de Plugins**: sinaliza Plugins que têm problemas de compatibilidade com o runtime atual.
- **Diagnósticos de Plugins**: expõe quaisquer avisos ou erros de tempo de carregamento emitidos pelo registro de Plugins.
- **Status de Skills**: conta skills elegíveis, com requisitos ausentes e bloqueadas por allowlist.
- **Diretórios legados de workspace**: avisa quando `~/openclaw` ou outros diretórios legados de workspace existem ao lado do workspace atual.
- **Status de Plugin**: conta plugins habilitados/desabilitados/com erro; lista IDs de plugins para quaisquer erros; relata capacidades de plugins do bundle.
- **Avisos de compatibilidade de Plugin**: sinaliza plugins que têm problemas de compatibilidade com o runtime atual.
- **Diagnósticos de Plugin**: expõe quaisquer avisos ou erros de tempo de carregamento emitidos pelo registro de plugins.
</Accordion>
<Accordion title="11b. Tamanho do arquivo de bootstrap">
O doctor verifica se arquivos de bootstrap do workspace (por exemplo, `AGENTS.md`, `CLAUDE.md` ou outros arquivos de contexto injetados) estão próximos ou acima do orçamento de caracteres configurado. Ele relata contagens de caracteres brutas vs. injetadas por arquivo, porcentagem de truncamento, causa do truncamento (`max/file` ou `max/total`) e total de caracteres injetados como uma fração do orçamento total. Quando arquivos são truncados ou estão próximos do limite, o doctor imprime dicas para ajustar `agents.defaults.bootstrapMaxChars` e `agents.defaults.bootstrapTotalMaxChars`.
O Doctor verifica se os arquivos de bootstrap do workspace (por exemplo `AGENTS.md`, `CLAUDE.md` ou outros arquivos de contexto injetados) estão próximos ou acima do orçamento de caracteres configurado. Ele relata contagens por arquivo de caracteres brutos vs. injetados, percentual de truncamento, causa do truncamento (`max/file` ou `max/total`) e total de caracteres injetados como fração do orçamento total. Quando os arquivos são truncados ou se aproximam do limite, o doctor imprime dicas para ajustar `agents.defaults.bootstrapMaxChars` e `agents.defaults.bootstrapTotalMaxChars`.
</Accordion>
<Accordion title="11d. Limpeza de Plugin de canal obsoleto">
Quando `openclaw doctor --fix` remove um Plugin de canal ausente, ele também remove a configuração pendente com escopo de canal que referenciava esse Plugin: entradas `channels.<id>`, destinos de Heartbeat que nomeavam o canal e substituições `agents.*.models["<channel>/*"]`. Isso impede loops de inicialização do Gateway em que o runtime do canal não existe mais, mas a configuração ainda pede ao gateway para se vincular a ele.
<Accordion title="11d. Limpeza de plugin de canal obsoleto">
Quando `openclaw doctor --fix` remove um plugin de canal ausente, ele também remove a configuração pendente com escopo de canal que referenciava esse plugin: entradas `channels.<id>`, alvos de Heartbeat que nomeavam o canal e substituições `agents.*.models["<channel>/*"]`. Isso evita loops de inicialização do Gateway em que o runtime do canal desapareceu, mas a configuração ainda pede que o gateway se vincule a ele.
</Accordion>
<Accordion title="11c. Completação de shell">
O doctor verifica se a completação por tab está instalada para o shell atual (zsh, bash, fish ou PowerShell):
<Accordion title="11c. Autocompletar do shell">
O Doctor verifica se a conclusão por tab está instalada para o shell atual (zsh, bash, fish ou PowerShell):
- Se o perfil do shell usa um padrão de completação dinâmica lento (`source <(openclaw completion ...)`), o doctor o atualiza para a variante mais rápida de arquivo em cache.
- Se a completação está configurada no perfil, mas o arquivo de cache está ausente, o doctor regenera o cache automaticamente.
- Se nenhuma completação está configurada, o doctor solicita a instalação (somente modo interativo; ignorado com `--non-interactive`).
- Se o perfil do shell usa um padrão lento de conclusão dinâmica (`source <(openclaw completion ...)`), o doctor o atualiza para a variante mais rápida de arquivo em cache.
- Se a conclusão está configurada no perfil, mas o arquivo de cache está ausente, o doctor regenera o cache automaticamente.
- Se nenhuma conclusão está configurada, o doctor solicita a instalação (somente no modo interativo; ignorado com `--non-interactive`).
Execute `openclaw completion --write-state` para regenerar o cache manualmente.
</Accordion>
<Accordion title="12. Verificações de autenticação do Gateway (token local)">
O doctor verifica a prontidão da autenticação por token do gateway local.
O Doctor verifica a prontidão da autenticação por token do gateway local.
- Se o modo de token precisa de um token e nenhuma fonte de token existe, o doctor oferece gerar um.
- Se o modo de token precisa de um token e não existe fonte de token, o doctor oferece gerar um.
- Se `gateway.auth.token` é gerenciado por SecretRef, mas está indisponível, o doctor avisa e não o sobrescreve com texto simples.
- `openclaw doctor --generate-gateway-token` força a geração somente quando nenhum SecretRef de token está configurado.
- `openclaw doctor --generate-gateway-token` força a geração apenas quando nenhum SecretRef de token está configurado.
</Accordion>
<Accordion title="12b. Reparos somente leitura cientes de SecretRef">
Alguns fluxos de reparo precisam inspecionar credenciais configuradas sem enfraquecer o comportamento fail-fast do runtime.
Alguns fluxos de reparo precisam inspecionar credenciais configuradas sem enfraquecer o comportamento de falha rápida do runtime.
- `openclaw doctor --fix` agora usa o mesmo modelo de resumo SecretRef somente leitura dos comandos da família de status para reparos de configuração direcionados.
- Exemplo: o reparo de `allowFrom` / `groupAllowFrom` `@username` do Telegram tenta usar credenciais de bot configuradas quando disponíveis.
- Se o token de bot do Telegram estiver configurado via SecretRef, mas indisponível no caminho do comando atual, o doctor relata que a credencial está configurada, porém indisponível, e ignora a resolução automática em vez de travar ou informar incorretamente que o token está ausente.
- `openclaw doctor --fix` agora usa o mesmo modelo de resumo somente leitura de SecretRef que os comandos da família de status para reparos de configuração direcionados.
- Exemplo: o reparo de `allowFrom` / `groupAllowFrom` `@username` do Telegram tenta usar as credenciais de bot configuradas quando disponíveis.
- Se o token do bot do Telegram estiver configurado via SecretRef, mas indisponível no caminho do comando atual, o doctor relata que a credencial está configurada-mas-indisponível e ignora a resolução automática em vez de travar ou relatar incorretamente que o token está ausente.
</Accordion>
<Accordion title="13. Verificação de integridade do Gateway + reinício">
O doctor executa uma verificação de integridade e oferece reiniciar o gateway quando ele parece não íntegro.
<Accordion title="13. Verificação de saúde do Gateway + reinicialização">
O Doctor executa uma verificação de saúde e oferece reiniciar o gateway quando ele parece não saudável.
</Accordion>
<Accordion title="13b. Prontidão da busca de memória">
O doctor verifica se o provedor configurado de embeddings da busca de memória está pronto para o agente padrão. O comportamento depende do backend e do provedor configurados:
O Doctor verifica se o provedor de embeddings de busca de memória configurado está pronto para o agente padrão. O comportamento depende do backend e do provedor configurados:
- **Backend QMD**: verifica se o binário `qmd` está disponível e pode ser iniciado. Se não estiver, imprime orientações de correção incluindo o pacote npm e uma opção de caminho manual do binário.
- **Provedor local explícito**: verifica se há um arquivo de modelo local ou uma URL de modelo remoto/baixável reconhecida. Se ausente, sugere mudar para um provedor remoto.
- **Backend QMD**: verifica se o binário `qmd` está disponível e pode ser iniciado. Se não, imprime orientação de correção incluindo o pacote npm e uma opção de caminho manual para o binário.
- **Provedor local explícito**: verifica se há um arquivo de modelo local ou uma URL de modelo remoto/baixável reconhecida. Se estiver ausente, sugere alternar para um provedor remoto.
- **Provedor remoto explícito** (`openai`, `voyage` etc.): verifica se uma chave de API está presente no ambiente ou no armazenamento de autenticação. Imprime dicas de correção acionáveis se estiver ausente.
- **Provedor automático**: verifica a disponibilidade do modelo local primeiro, depois tenta cada provedor remoto na ordem de seleção automática.
- **Provedor automático**: verifica primeiro a disponibilidade do modelo local e depois tenta cada provedor remoto na ordem de seleção automática.
Quando um resultado de sondagem do gateway em cache está disponível (o gateway estava íntegro no momento da verificação), o doctor cruza seu resultado com a configuração visível pela CLI e observa qualquer discrepância. O doctor não inicia uma nova sondagem de embedding no caminho padrão; use o comando de status profundo de memória quando quiser uma verificação ao vivo do provedor.
Quando um resultado de sondagem do gateway em cache está disponível (o gateway estava saudável no momento da verificação), o doctor cruza seu resultado com a configuração visível pela CLI e observa qualquer discrepância. O Doctor não inicia um novo ping de embedding no caminho padrão; use o comando de status profundo de memória quando quiser uma verificação ao vivo do provedor.
Use `openclaw memory status --deep` para verificar a prontidão de embedding em runtime.
Use `openclaw memory status --deep` para verificar a prontidão de embeddings em runtime.
</Accordion>
<Accordion title="14. Avisos de status de canal">
Se o gateway estiver íntegro, o doctor executa uma sondagem de status de canal e relata avisos com correções sugeridas.
Se o gateway estiver saudável, o doctor executa uma sondagem de status de canal e relata avisos com correções sugeridas.
</Accordion>
<Accordion title="15. Auditoria + reparo da configuração do supervisor">
O doctor verifica a configuração instalada do supervisor (launchd/systemd/schtasks) em busca de padrões ausentes ou desatualizados (por exemplo, dependências `network-online` do systemd e atraso de reinício). Quando encontra uma divergência, ele recomenda uma atualização e pode regravar o arquivo de serviço/tarefa com os padrões atuais.
O Doctor verifica a configuração do supervisor instalado (launchd/systemd/schtasks) em busca de padrões ausentes ou desatualizados (por exemplo, dependências de systemd network-online e atraso de reinício). Quando encontra uma incompatibilidade, ele recomenda uma atualização e pode reescrever o arquivo de serviço/tarefa para os padrões atuais.
Observações:
- `openclaw doctor` solicita confirmação antes de regravar a configuração do supervisor.
- `openclaw doctor` solicita confirmação antes de reescrever a configuração do supervisor.
- `openclaw doctor --yes` aceita os prompts de reparo padrão.
- `openclaw doctor --repair` aplica correções recomendadas sem prompts.
- `openclaw doctor --repair` aplica as correções recomendadas sem prompts.
- `openclaw doctor --repair --force` sobrescreve configurações personalizadas do supervisor.
- `OPENCLAW_SERVICE_REPAIR_POLICY=external` mantém o doctor somente leitura para o ciclo de vida do serviço do gateway. Ele ainda relata a integridade do serviço e executa reparos que não são de serviço, mas ignora instalação/início/reinício/bootstrap de serviço, regravações de configuração do supervisor e limpeza de serviços legados porque um supervisor externo controla esse ciclo de vida.
- No Linux, o doctor não regrava metadados de comando/entrypoint enquanto a unidade de gateway systemd correspondente está ativa. Ele também ignora unidades extras inativas semelhantes a gateway e não legadas durante a varredura de serviços duplicados, para que arquivos de serviço complementares não gerem ruído de limpeza.
- Se a autenticação por token exige um token e `gateway.auth.token` é gerenciado por SecretRef, a instalação/reparo de serviço do doctor valida o SecretRef, mas não persiste valores de token em texto simples resolvidos nos metadados de ambiente do serviço do supervisor.
- O doctor detecta valores de ambiente de serviço gerenciados por `.env`/SecretRef que instalações antigas de LaunchAgent, systemd ou Windows Scheduled Task incorporaram inline e regrava os metadados do serviço para que esses valores sejam carregados da fonte de runtime em vez da definição do supervisor.
- O doctor detecta quando o comando do serviço ainda fixa um `--port` antigo depois que `gateway.port` muda e regrava os metadados do serviço para a porta atual.
- Se a autenticação por token exige um token e o SecretRef de token configurado não está resolvido, o doctor bloqueia o caminho de instalação/reparo com orientação acionável.
- Se `gateway.auth.token` e `gateway.auth.password` estão ambos configurados e `gateway.auth.mode` não está definido, o doctor bloqueia instalação/reparo até que o modo seja definido explicitamente.
- Para unidades user-systemd do Linux, as verificações de desvio de token do doctor agora incluem fontes `Environment=` e `EnvironmentFile=` ao comparar metadados de autenticação do serviço.
- Reparos de serviço do doctor se recusam a regravar, parar ou reiniciar um serviço de gateway de um binário OpenClaw mais antigo quando a configuração foi gravada pela última vez por uma versão mais nova. Consulte [Solução de problemas do Gateway](/pt-BR/gateway/troubleshooting#split-brain-installs-and-newer-config-guard).
- Você sempre pode forçar uma regravação completa via `openclaw gateway install --force`.
- `OPENCLAW_SERVICE_REPAIR_POLICY=external` mantém o doctor somente leitura para o ciclo de vida do serviço do Gateway. Ele ainda relata a integridade do serviço e executa reparos que não são de serviço, mas ignora instalação/início/reinício/bootstrap do serviço, reescritas de configuração do supervisor e limpeza de serviços legados porque um supervisor externo é dono desse ciclo de vida.
- No Linux, o doctor não reescreve metadados de comando/entrypoint enquanto a unidade systemd do Gateway correspondente está ativa. Ele também ignora unidades extras inativas não legadas semelhantes ao Gateway durante a varredura de serviços duplicados, para que arquivos de serviço complementares não gerem ruído de limpeza.
- Se a autenticação por token exigir um token e `gateway.auth.token` for gerenciado por SecretRef, a instalação/reparo do serviço pelo doctor valida o SecretRef, mas não persiste valores de token em texto claro resolvidos nos metadados de ambiente do serviço do supervisor.
- O Doctor detecta valores de ambiente de serviço gerenciados por `.env`/SecretRef que instalações mais antigas de LaunchAgent, systemd ou Tarefa Agendada do Windows incorporaram inline e reescreve os metadados do serviço para que esses valores sejam carregados da fonte de runtime em vez da definição do supervisor.
- O Doctor detecta quando o comando do serviço ainda fixa um `--port` antigo depois que `gateway.port` muda e reescreve os metadados do serviço para a porta atual.
- Se a autenticação por token exigir um token e o SecretRef de token configurado não for resolvido, o doctor bloqueia o caminho de instalação/reparo com orientação acionável.
- Se `gateway.auth.token` e `gateway.auth.password` estiverem configurados e `gateway.auth.mode` não estiver definido, o doctor bloqueia a instalação/reparo até que o modo seja definido explicitamente.
- Para unidades user-systemd no Linux, as verificações de divergência de token do doctor agora incluem fontes `Environment=` e `EnvironmentFile=` ao comparar metadados de autenticação do serviço.
- Reparos de serviço do Doctor se recusam a reescrever, parar ou reiniciar um serviço do Gateway de um binário OpenClaw mais antigo quando a configuração foi gravada pela última vez por uma versão mais nova. Consulte [solução de problemas do Gateway](/pt-BR/gateway/troubleshooting#split-brain-installs-and-newer-config-guard).
- Você sempre pode forçar uma reescrita completa via `openclaw gateway install --force`.
</Accordion>
<Accordion title="16. Runtime do Gateway + diagnóstico de porta">
O diagnóstico inspeciona o runtime do serviço (PID, último status de saída) e avisa quando o serviço está instalado, mas não está de fato em execução. Ele também verifica colisões de porta na porta do Gateway (padrão `18789`) e relata causas prováveis (Gateway já em execução, túnel SSH).
<Accordion title="16. Diagnóstico de runtime + porta do Gateway">
O Doctor inspeciona o runtime do serviço (PID, último status de saída) e avisa quando o serviço está instalado, mas não está realmente em execução. Ele também verifica colisões de porta na porta do Gateway (padrão `18789`) e relata causas prováveis (Gateway já em execução, túnel SSH).
</Accordion>
<Accordion title="17. Práticas recomendadas de runtime do Gateway">
O diagnóstico avisa quando o serviço de Gateway é executado no Bun ou em um caminho de Node gerenciado por versão (`nvm`, `fnm`, `volta`, `asdf` etc.). Os canais WhatsApp + Telegram exigem Node, e caminhos de gerenciadores de versão podem quebrar após atualizações porque o serviço não carrega a inicialização do seu shell. O diagnóstico oferece migrar para uma instalação de Node do sistema quando disponível (Homebrew/apt/choco).
O Doctor avisa quando o serviço do Gateway é executado no Bun ou em um caminho de Node gerenciado por versão (`nvm`, `fnm`, `volta`, `asdf`, etc.). Os canais WhatsApp + Telegram exigem Node, e caminhos de gerenciadores de versão podem quebrar após upgrades porque o serviço não carrega sua inicialização de shell. O Doctor oferece migração para uma instalação de Node do sistema quando disponível (Homebrew/apt/choco).
Serviços recém-instalados ou reparados mantêm raízes de ambiente explícitas (`NVM_DIR`, `FNM_DIR`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `BUN_INSTALL`, `PNPM_HOME`) e diretórios user-bin estáveis, mas diretórios fallback inferidos de gerenciadores de versão só são gravados no PATH do serviço quando esses diretórios existem no disco. Isso mantém o PATH do supervisor gerado alinhado com a mesma auditoria de PATH mínimo que o diagnóstico executa depois.
Serviços recém-instalados ou reparados mantêm raízes de ambiente explícitas (`NVM_DIR`, `FNM_DIR`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `BUN_INSTALL`, `PNPM_HOME`) e diretórios user-bin estáveis, mas diretórios fallback inferidos de gerenciadores de versão só são gravados no PATH do serviço quando esses diretórios existem no disco. Isso mantém o PATH gerado do supervisor alinhado à mesma auditoria de PATH mínimo que o doctor executa depois.
</Accordion>
<Accordion title="18. Gravação da configuração + metadados do assistente">
O diagnóstico persiste quaisquer alterações de configuração e marca os metadados do assistente para registrar a execução do diagnóstico.
<Accordion title="18. Gravação de configuração + metadados do assistente">
O Doctor persiste quaisquer alterações de configuração e marca metadados do assistente para registrar a execução do doctor.
</Accordion>
<Accordion title="19. Dicas de workspace (backup + sistema de memória)">
O diagnóstico sugere um sistema de memória de workspace quando ausente e imprime uma dica de backup se o workspace ainda não estiver sob git.
O Doctor sugere um sistema de memória de workspace quando ausente e imprime uma dica de backup se o workspace ainda não estiver sob git.
Consulte [/concepts/agent-workspace](/pt-BR/concepts/agent-workspace) para ver um guia completo sobre estrutura de workspace e backup com git (recomendado GitHub ou GitLab privado).
Consulte [/concepts/agent-workspace](/pt-BR/concepts/agent-workspace) para um guia completo sobre a estrutura do workspace e backup com git (recomendado GitHub ou GitLab privado).
</Accordion>
</AccordionGroup>

38
docs/pt-BR/gateway/gateway-lock.md
View File

@ -1,44 +1,44 @@
---
read_when:
- Executar ou depurar o processo do Gateway
- Executando ou depurando o processo do Gateway
- Investigando a imposição de instância única
summary: Proteção singleton do Gateway usando o bind do listener WebSocket
summary: Proteção de instância única do Gateway usando a vinculação do listener WebSocket
title: Bloqueio do Gateway
x-i18n:
generated_at: "2026-04-30T09:48:49Z"
generated_at: "2026-04-30T16:28:46Z"
model: gpt-5.5
provider: openai
source_hash: fe61ff81106554e98de1ca04c213b76d230265cdf3e81b70897d2de00f6a0179
source_hash: 85a1cb55f08d47d36fde25900e4247ef01c9a6800bf017fbff44a337f299ce13
source_path: gateway/gateway-lock.md
workflow: 16
---
## Por quê
- Garantir que apenas uma instância do Gateway seja executada por porta base no mesmo host; Gateways adicionais devem usar perfis isolados e portas exclusivas.
- Sobreviver a falhas/SIGKILL sem deixar arquivos de lock obsoletos.
- Falhar rapidamente com um erro claro quando a porta de controle já estiver ocupada.
- Garanta que apenas uma instância do Gateway seja executada por porta base no mesmo host; Gateways adicionais devem usar perfis isolados e portas exclusivas.
- Sobreviva a falhas/SIGKILL sem deixar arquivos de bloqueio obsoletos.
- Falhe rapidamente com um erro claro quando a porta de controle já estiver ocupada.
## Mecanismo
- O Gateway primeiro adquire um arquivo de lock por configuração sob o diretório de locks de estado e verifica a porta configurada em busca de um processo em escuta existente.
- Se o proprietário registrado do lock não existir mais, a porta estiver livre ou o lock estiver obsoleto, a inicialização recupera o lock e continua.
- O Gateway então associa o ouvinte HTTP/WebSocket (padrão `ws://127.0.0.1:18789`) usando uma escuta TCP exclusiva.
- Se a associação falhar com `EADDRINUSE`, a inicialização lança `GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")`.
- No encerramento, o Gateway fecha o servidor HTTP/WebSocket e remove o arquivo de lock.
- O Gateway primeiro adquire um arquivo de bloqueio por configuração no diretório de bloqueios de estado e verifica a porta configurada em busca de um ouvinte existente.
- Se o proprietário do bloqueio registrado não existir mais, a porta estiver livre ou o bloqueio estiver obsoleto, a inicialização recupera o bloqueio e continua.
- Em seguida, o Gateway vincula o ouvinte HTTP/WebSocket (padrão `ws://127.0.0.1:18789`) usando um ouvinte TCP exclusivo.
- Se a vinculação falhar com `EADDRINUSE`, a inicialização lança `GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")`.
- No desligamento, o Gateway fecha o servidor HTTP/WebSocket e remove o arquivo de bloqueio.
## Superfície de erro
- Se outro processo estiver segurando a porta, a inicialização lança `GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")`.
- Outras falhas de associação aparecem como `GatewayLockError("failed to bind gateway socket on ws://127.0.0.1:<port>: …")`.
- Se outro processo mantiver a porta, a inicialização lança `GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")`.
- Outras falhas de vinculação aparecem como `GatewayLockError("failed to bind gateway socket on ws://127.0.0.1:<port>: …")`.
## Notas operacionais
## Observações operacionais
- Se a porta estiver ocupada por _outro_ processo, o erro é o mesmo; libere a porta ou escolha outra com `openclaw gateway --port <port>`.
- Sob um supervisor de serviço, um novo processo do Gateway que encontra um respondedor `/healthz` saudável existente sai com sucesso e deixa esse processo no controle. Se o processo existente nunca ficar saudável, as novas tentativas são limitadas e a inicialização falha com um erro de lock claro, em vez de entrar em loop para sempre.
- O app macOS ainda mantém sua própria proteção leve por PID antes de iniciar o Gateway; o lock em tempo de execução é imposto pelo arquivo de lock mais a associação HTTP/WebSocket.
- Se a porta estiver ocupada por _outro_ processo, o erro será o mesmo; libere a porta ou escolha outra com `openclaw gateway --port <port>`.
- Sob um supervisor de serviço, um novo processo do Gateway que encontra um respondedor `/healthz` existente e íntegro deixa esse processo no controle. No systemd, o inicializador duplicado sai com código 78 para que o `RestartPreventExitStatus=78` padrão impeça que `Restart=always` entre em loop em um conflito de bloqueio ou `EADDRINUSE`. Se o processo existente nunca se tornar íntegro, as tentativas são limitadas e a inicialização falha com um erro de bloqueio claro em vez de entrar em loop para sempre.
- O app para macOS ainda mantém sua própria proteção leve por PID antes de iniciar o Gateway; o bloqueio em tempo de execução é imposto pelo arquivo de bloqueio mais a vinculação HTTP/WebSocket.
## Relacionado
- [Múltiplos Gateways](/pt-BR/gateway/multiple-gateways) — executando várias instâncias com portas exclusivas
- [Vários Gateways](/pt-BR/gateway/multiple-gateways) — executando várias instâncias com portas exclusivas
- [Solução de problemas](/pt-BR/gateway/troubleshooting) — diagnosticando `EADDRINUSE` e conflitos de porta

104
docs/pt-BR/platforms/mac/remote.md
View File

@ -1,107 +1,109 @@
---
read_when:
- Configurando ou depurando controle remoto no macOS
summary: Fluxo do app de macOS para controlar um gateway OpenClaw remoto por SSH
- Configurando ou depurando o controle remoto do Mac
summary: Fluxo do app macOS para controlar um Gateway OpenClaw remoto via SSH
title: Controle remoto
x-i18n:
generated_at: "2026-04-26T11:33:28Z"
model: gpt-5.4
generated_at: "2026-04-30T16:28:50Z"
model: gpt-5.5
provider: openai
source_hash: 4de4980fe378fc9b685cf7732d21a80c640088191308b8ef1d3df9f468cb5be2
source_hash: 2c63f752c3636a253220310c7c8e57a28549704b74b2f0370bac432bae28a7d3
source_path: platforms/mac/remote.md
workflow: 15
workflow: 16
---
# OpenClaw remoto (macOS ⇄ host remoto)
Esse fluxo permite que o app de macOS atue como um controle remoto completo para um gateway OpenClaw em execução em outro host (desktop/servidor). Esse é o recurso **Remoto por SSH** (execução remota) do app. Todos os recursos — verificações de integridade, encaminhamento do Voice Wake e Web Chat — reutilizam a mesma configuração SSH remota em _Settings → General_.
Este fluxo permite que o app para macOS atue como um controle remoto completo para um OpenClaw Gateway em execução em outro host (desktop/servidor). É o recurso **Remoto por SSH** (execução remota) do app. Todos os recursos — verificações de integridade, encaminhamento do Voice Wake e Web Chat — reutilizam a mesma configuração remota de SSH em _Ajustes → Geral_.
## Modos
- **Local (este Mac)**: tudo é executado no laptop. Não há SSH envolvido.
- **Remoto por SSH (padrão)**: comandos do OpenClaw são executados no host remoto. O app do mac abre uma conexão SSH com `-o BatchMode`, além da identidade/chave escolhida e um encaminhamento de porta local.
- **Remoto direto (ws/wss)**: sem túnel SSH. O app do mac se conecta diretamente à URL do gateway (por exemplo, via Tailscale Serve ou um proxy reverso HTTPS público).
- **Local (este Mac)**: Tudo é executado no laptop. Sem SSH envolvido.
- **Remoto por SSH (padrão)**: comandos do OpenClaw são executados no host remoto. O app para Mac abre uma conexão SSH com `-o BatchMode`, além da identidade/chave escolhida e um encaminhamento de porta local.
- **Remoto direto (ws/wss)**: Sem túnel SSH. O app para Mac se conecta diretamente à URL do Gateway (por exemplo, via Tailscale Serve ou um proxy reverso HTTPS público).
## Transportes remotos
O modo remoto oferece suporte a dois transportes:
O modo remoto aceita dois transportes:
- **Túnel SSH** (padrão): usa `ssh -N -L ...` para encaminhar a porta do gateway para localhost. O gateway verá o IP do node como `127.0.0.1` porque o túnel é loopback.
- **Direto (ws/wss)**: conecta diretamente à URL do gateway. O gateway vê o IP real do cliente.
- **Túnel SSH** (padrão): usa `ssh -N -L ...` para encaminhar a porta do Gateway para localhost. O Gateway verá o IP do Node como `127.0.0.1` porque o túnel é loopback.
- **Direto (ws/wss)**: conecta diretamente à URL do Gateway. O Gateway vê o IP real do cliente.
No modo de túnel SSH, hostnames LAN/tailnet descobertos são salvos como
No modo de túnel SSH, nomes de host de LAN/tailnet descobertos são salvos como
`gateway.remote.sshTarget`. O app mantém `gateway.remote.url` no endpoint local
do túnel, por exemplo `ws://127.0.0.1:18789`, para que CLI, Web Chat e
o serviço local de hospedagem de node usem o mesmo transporte loopback seguro.
o serviço node-host local usem todos o mesmo transporte seguro de loopback.
A automação de navegador no modo remoto é controlada pelo node host da CLI, não pelo
node nativo do app de macOS. O app inicia o serviço de node host instalado quando
A automação de navegador no modo remoto pertence ao host Node da CLI, não ao
Node nativo do app para macOS. O app inicia o serviço de host Node instalado quando
possível; se você precisar de controle de navegador a partir desse Mac, instale/inicie-o com
`openclaw node install ...` e `openclaw node start` (ou execute
`openclaw node run ...` em foreground), e então mire nesse node com suporte a navegador.
`openclaw node run ...` em primeiro plano), então direcione para esse Node
com suporte a navegador.
## Pré-requisitos no host remoto
1. Instale Node + pnpm e compile/instale a CLI do OpenClaw (`pnpm install && pnpm build && pnpm link --global`).
2. Garanta que `openclaw` esteja no PATH para shells não interativos (symlink em `/usr/local/bin` ou `/opt/homebrew/bin`, se necessário).
3. Abra SSH com auth por chave. Recomendamos IPs do **Tailscale** para acessibilidade estável fora da LAN.
2. Garanta que `openclaw` esteja no PATH para shells não interativos (crie um symlink em `/usr/local/bin` ou `/opt/homebrew/bin`, se necessário).
3. Abra SSH com autenticação por chave. Recomendamos IPs do **Tailscale** para alcance estável fora da LAN.
## Configuração do app de macOS
## Configuração do app para macOS
1. Abra _Settings → General_.
2. Em **OpenClaw runs**, escolha **Remote over SSH** e defina:
- **Transport**: **SSH tunnel** ou **Direct (ws/wss)**.
- **SSH target**: `user@host` (opcional `:port`).
- Se o gateway estiver na mesma LAN e publicar Bonjour, escolha-o na lista descoberta para preencher esse campo automaticamente.
- **Gateway URL** (somente Direct): `wss://gateway.example.ts.net` (ou `ws://...` para local/LAN).
- **Identity file** (avançado): caminho para sua chave.
- **Project root** (avançado): caminho do checkout remoto usado para comandos.
- **CLI path** (avançado): caminho opcional para um entrypoint/binário `openclaw` executável (preenchido automaticamente quando publicado).
3. Clique em **Test remote**. Sucesso indica que `openclaw status --json` no remoto é executado corretamente. Falhas normalmente significam problemas de PATH/CLI; saída 127 significa que a CLI não foi encontrada no remoto.
4. Verificações de integridade e Web Chat agora serão executados por esse túnel SSH automaticamente.
1. Abra _Ajustes → Geral_.
2. Em **OpenClaw executa em**, escolha **Remoto por SSH** e defina:
- **Transporte**: **Túnel SSH** ou **Direto (ws/wss)**.
- **Destino SSH**: `user@host` (`:port` opcional).
- Se o Gateway estiver na mesma LAN e anunciar Bonjour, escolha-o na lista descoberta para preencher este campo automaticamente.
- **URL do Gateway** (somente Direto): `wss://gateway.example.ts.net` (ou `ws://...` para local/LAN).
- **Arquivo de identidade** (avançado): caminho para sua chave.
- **Raiz do projeto** (avançado): caminho do checkout remoto usado para comandos.
- **Caminho da CLI** (avançado): caminho opcional para um ponto de entrada/binário `openclaw` executável (preenchido automaticamente quando anunciado).
3. Clique em **Testar remoto**. Sucesso indica que o `openclaw status --json` remoto é executado corretamente. Falhas geralmente indicam problemas de PATH/CLI; o código de saída 127 significa que a CLI não foi encontrada remotamente.
4. Verificações de integridade e Web Chat agora serão executados automaticamente por este túnel SSH.
## Web Chat
- **Túnel SSH**: o Web Chat se conecta ao gateway pela porta de controle WebSocket encaminhada (padrão 18789).
- **Direto (ws/wss)**: o Web Chat se conecta diretamente à URL configurada do gateway.
- Não existe mais um servidor HTTP separado de WebChat.
- **Túnel SSH**: o Web Chat se conecta ao Gateway pela porta de controle WebSocket encaminhada (padrão 18789).
- **Direto (ws/wss)**: o Web Chat se conecta diretamente à URL configurada do Gateway.
- Não há mais um servidor HTTP separado para WebChat.
## Permissões
- O host remoto precisa das mesmas aprovações TCC que o local (Automação, Acessibilidade, Gravação de Tela, Microfone, Reconhecimento de Fala, Notificações). Execute o onboarding nessa máquina para concedê-las uma vez.
- Nodes publicam seu estado de permissões via `node.list` / `node.describe`, para que agentes saibam o que está disponível.
- Nodes anunciam seu estado de permissões via `node.list` / `node.describe` para que agentes saibam o que está disponível.
## Observações de segurança
## Notas de segurança
- Prefira binds em loopback no host remoto e conecte-se via SSH ou Tailscale.
- O tunelamento SSH usa verificação estrita de chave do host; confie primeiro na chave do host para que ela exista em `~/.ssh/known_hosts`.
- Se você fizer bind do Gateway em uma interface não loopback, exija auth válida do Gateway: token, senha ou um proxy reverso com reconhecimento de identidade usando `gateway.auth.mode: "trusted-proxy"`.
- Veja [Segurança](/pt-BR/gateway/security) e [Tailscale](/pt-BR/gateway/tailscale).
- Prefira binds de loopback no host remoto e conecte via SSH ou Tailscale.
- O tunelamento SSH usa verificação rigorosa de chave de host; confie primeiro na chave do host para que ela exista em `~/.ssh/known_hosts`.
- Se você vincular o Gateway a uma interface que não seja loopback, exija autenticação válida do Gateway: token, senha ou um proxy reverso ciente de identidade com `gateway.auth.mode: "trusted-proxy"`.
- Consulte [Segurança](/pt-BR/gateway/security) e [Tailscale](/pt-BR/gateway/tailscale).
## Fluxo de login do WhatsApp (remoto)
- Execute `openclaw channels login --verbose` **no host remoto**. Escaneie o QR com o WhatsApp no seu telefone.
- Execute novamente o login nesse host se a auth expirar. A verificação de integridade mostrará problemas de vínculo.
- Execute o login novamente nesse host se a autenticação expirar. A verificação de integridade mostrará problemas de vínculo.
## Solução de problemas
- **exit 127 / not found**: `openclaw` não está no PATH para shells sem login. Adicione-o a `/etc/paths`, ao rc do seu shell ou crie um symlink em `/usr/local/bin`/`/opt/homebrew/bin`.
- **Health probe failed**: verifique acessibilidade SSH, PATH e se o Baileys está logado (`openclaw status --json`).
- **Web Chat travado**: confirme se o gateway está em execução no host remoto e se a porta encaminhada corresponde à porta WS do gateway; a UI exige uma conexão WS íntegra.
- **Node IP mostra 127.0.0.1**: esperado com o túnel SSH. Troque **Transport** para **Direct (ws/wss)** se quiser que o gateway veja o IP real do cliente.
- **Voice Wake**: frases de ativação são encaminhadas automaticamente no modo remoto; não é necessário um encaminhador separado.
- **exit 127 / não encontrado**: `openclaw` não está no PATH para shells sem login. Adicione-o a `/etc/paths`, ao rc do seu shell ou crie um symlink em `/usr/local/bin`/`/opt/homebrew/bin`.
- **Sondagem de integridade falhou**: verifique o alcance SSH, o PATH e se o Baileys está logado (`openclaw status --json`).
- **Web Chat travado**: confirme que o Gateway está em execução no host remoto e que a porta encaminhada corresponde à porta WS do Gateway; a UI exige uma conexão WS íntegra.
- **IP do Node mostra 127.0.0.1**: esperado com o túnel SSH. Altere **Transporte** para **Direto (ws/wss)** se quiser que o Gateway veja o IP real do cliente.
- **Dashboard funciona, mas os recursos do Mac estão offline**: isso significa que a conexão de operador/controle do app está íntegra, mas a conexão do Node complementar não está conectada ou não tem sua superfície de comandos. Abra a seção de dispositivo na barra de menus e verifique se o Mac está `paired · disconnected`. Para endpoints Tailscale Serve `wss://*.ts.net`, o app detecta pins TLS legados de folha obsoletos após a rotação do certificado, limpa o pin obsoleto quando o macOS confia no novo certificado e tenta novamente automaticamente. Se o certificado não for confiável pelo sistema ou o host não for um nome Tailscale Serve, revise o certificado ou mude para **Remoto por SSH**.
- **Voice Wake**: frases de acionamento são encaminhadas automaticamente no modo remoto; nenhum encaminhador separado é necessário.
## Sons de notificação
Escolha sons por notificação a partir de scripts com `openclaw` e `node.invoke`, por exemplo:
```bash
openclaw nodes notify --node <id> --title "Ping" --body "Gateway remoto pronto" --sound Glass
openclaw nodes notify --node <id> --title "Ping" --body "Remote gateway ready" --sound Glass
```
Não existe mais uma opção global de “som padrão” no app; chamadores escolhem um som (ou nenhum) por solicitação.
Não há mais uma alternância global de “som padrão” no app; os chamadores escolhem um som (ou nenhum) por solicitação.
## Relacionados
## Relacionado
- [App de macOS](/pt-BR/platforms/macos)
- [app para macOS](/pt-BR/platforms/macos)
- [Acesso remoto](/pt-BR/gateway/remote)

66
docs/pt-BR/providers/deepseek.md
View File

@ -5,10 +5,10 @@ read_when:
summary: Configuração do DeepSeek (autenticação + seleção de modelo)
title: DeepSeek
x-i18n:
generated_at: "2026-04-30T10:04:25Z"
generated_at: "2026-04-30T16:29:16Z"
model: gpt-5.5
provider: openai
source_hash: e84d989a7cba8d259779ac02293718050ce51efe6ce2bdbfacb9e22bbfd294ef
source_hash: 6fbc7bd4de14000eaa5c42b17eb8c9312321ed02ac1667e60774ead3f1749eb4
source_path: providers/deepseek.md
workflow: 16
---
@ -18,11 +18,11 @@ x-i18n:
| Propriedade | Valor |
| -------- | -------------------------- |
| Provedor | `deepseek` |
| Autenticação | `DEEPSEEK_API_KEY` |
| API | Compatível com OpenAI |
| Autenticação | `DEEPSEEK_API_KEY` |
| API | compatível com OpenAI |
| URL base | `https://api.deepseek.com` |
## Introdução
## Primeiros passos
<Steps>
<Step title="Obtenha sua chave de API">
@ -68,45 +68,47 @@ x-i18n:
</AccordionGroup>
<Warning>
Se o Gateway for executado como daemon (launchd/systemd), garanta que `DEEPSEEK_API_KEY`
Se o Gateway for executado como um daemon (launchd/systemd), certifique-se de que `DEEPSEEK_API_KEY`
esteja disponível para esse processo (por exemplo, em `~/.openclaw/.env` ou via
`env.shellEnv`).
</Warning>
## Catálogo integrado
| Ref do modelo | Nome | Entrada | Contexto | Saída máxima | Observações |
| Ref. do modelo | Nome | Entrada | Contexto | Saída máxima | Observações |
| ---------------------------- | ----------------- | ----- | --------- | ---------- | ------------------------------------------ |
| `deepseek/deepseek-v4-flash` | DeepSeek V4 Flash | text | 1,000,000 | 384,000 | Modelo padrão; superfície V4 com suporte a pensamento |
| `deepseek/deepseek-v4-pro` | DeepSeek V4 Pro | text | 1,000,000 | 384,000 | Superfície V4 com suporte a pensamento |
| `deepseek/deepseek-chat` | DeepSeek Chat | text | 131,072 | 8,192 | Superfície DeepSeek V3.2 sem pensamento |
| `deepseek/deepseek-reasoner` | DeepSeek Reasoner | text | 131,072 | 65,536 | Superfície V3.2 com raciocínio habilitado |
| `deepseek/deepseek-v4-flash` | DeepSeek V4 Flash | texto | 1.000.000 | 384.000 | Modelo padrão; superfície V4 compatível com thinking |
| `deepseek/deepseek-v4-pro` | DeepSeek V4 Pro | texto | 1.000.000 | 384.000 | Superfície V4 compatível com thinking |
| `deepseek/deepseek-chat` | DeepSeek Chat | texto | 131.072 | 8.192 | Superfície DeepSeek V3.2 sem thinking |
| `deepseek/deepseek-reasoner` | DeepSeek Reasoner | texto | 131.072 | 65.536 | Superfície V3.2 com reasoning habilitado |
<Tip>
Os modelos V4 são compatíveis com o controle `thinking` do DeepSeek. O OpenClaw também reproduz
`reasoning_content` do DeepSeek em turnos seguintes para que sessões de pensamento com chamadas de ferramenta
Modelos V4 oferecem suporte ao controle `thinking` do DeepSeek. O OpenClaw também reproduz
o `reasoning_content` do DeepSeek em turnos de acompanhamento para que sessões de thinking com chamadas de ferramentas
possam continuar.
Use `/think xhigh` ou `/think max` com modelos DeepSeek V4 para solicitar o
`reasoning_effort` máximo do DeepSeek.
</Tip>
## Pensamento e ferramentas
## Thinking e ferramentas
Sessões de pensamento do DeepSeek V4 têm um contrato de reprodução mais rigoroso do que a maioria dos
provedores compatíveis com OpenAI: depois que um turno com pensamento habilitado usa ferramentas, o DeepSeek
Sessões de thinking do DeepSeek V4 têm um contrato de reprodução mais rigoroso do que a maioria dos
provedores compatíveis com OpenAI: depois que um turno com thinking habilitado usa ferramentas, o DeepSeek
espera que as mensagens de assistente reproduzidas desse turno incluam
`reasoning_content` em solicitações seguintes. O OpenClaw lida com isso dentro do
Plugin do DeepSeek, então o uso normal de ferramentas em múltiplos turnos funciona com
`reasoning_content` nas solicitações de acompanhamento. O OpenClaw lida com isso dentro do
plugin DeepSeek, então o uso normal de ferramentas em múltiplos turnos funciona com
`deepseek/deepseek-v4-flash` e `deepseek/deepseek-v4-pro`.
Se você alternar uma sessão existente de outro provedor compatível com OpenAI para um
modelo DeepSeek V4, turnos antigos de chamadas de ferramenta do assistente podem não ter
`reasoning_content` nativo do DeepSeek. O OpenClaw preenche esse campo ausente em mensagens de
assistente reproduzidas para solicitações de pensamento do DeepSeek V4, para que o provedor possa aceitar
modelo DeepSeek V4, turnos antigos de chamadas de ferramentas do assistente podem não ter
`reasoning_content` nativo do DeepSeek. O OpenClaw preenche esse campo ausente em mensagens de assistente
reproduzidas para solicitações de thinking do DeepSeek V4, para que o provedor possa aceitar
o histórico sem exigir `/new`.
Quando o pensamento está desabilitado no OpenClaw (incluindo a seleção **Nenhum** da UI),
o OpenClaw envia `thinking: { type: "disabled" }` ao DeepSeek e remove
`reasoning_content` reproduzido do histórico de saída. Isso mantém as sessões com pensamento desabilitado
no caminho sem pensamento do DeepSeek.
Quando o thinking está desativado no OpenClaw (incluindo a seleção **None** na UI),
o OpenClaw envia ao DeepSeek `thinking: { type: "disabled" }` e remove o
`reasoning_content` reproduzido do histórico de saída. Isso mantém as sessões com thinking desativado
no caminho sem thinking do DeepSeek.
Use `deepseek/deepseek-v4-flash` para o caminho rápido padrão. Use
`deepseek/deepseek-v4-pro` quando quiser o modelo V4 mais forte e puder aceitar
@ -114,8 +116,8 @@ custo ou latência maiores.
## Testes ao vivo
A suíte direta de modelos ao vivo inclui DeepSeek V4 no conjunto de modelos moderno. Para
executar apenas as verificações diretas de modelo do DeepSeek V4:
A suíte direta de modelos ao vivo inclui o DeepSeek V4 no conjunto moderno de modelos. Para
executar apenas as verificações diretas de modelos DeepSeek V4:
```bash
OPENCLAW_LIVE_PROVIDERS=deepseek \
@ -123,8 +125,8 @@ OPENCLAW_LIVE_MODELS="deepseek/deepseek-v4-flash,deepseek/deepseek-v4-pro" \
pnpm test:live src/agents/models.profiles.live.test.ts
```
Essa verificação ao vivo confirma que ambos os modelos V4 conseguem concluir e que os turnos seguintes de pensamento/ferramenta
preservam o payload de reprodução exigido pelo DeepSeek.
Essa verificação ao vivo confirma que ambos os modelos V4 conseguem concluir e que os turnos de acompanhamento
com thinking/ferramentas preservam a carga de reprodução exigida pelo DeepSeek.
## Exemplo de configuração
@ -139,11 +141,11 @@ preservam o payload de reprodução exigido pelo DeepSeek.
}
```
## Relacionado
## Relacionados
<CardGroup cols={2}>
<Card title="Seleção de modelo" href="/pt-BR/concepts/model-providers" icon="layers">
Escolha de provedores, refs de modelo e comportamento de failover.
<Card title="Seleção de modelos" href="/pt-BR/concepts/model-providers" icon="layers">
Escolha de provedores, refs. de modelo e comportamento de failover.
</Card>
<Card title="Referência de configuração" href="/pt-BR/gateway/configuration-reference" icon="gear">
Referência completa de configuração para agentes, modelos e provedores.

429
docs/pt-BR/providers/openai.md
View File

@ -3,29 +3,29 @@ read_when:
- Você quer usar modelos da OpenAI no OpenClaw
- Você quer autenticação por assinatura do Codex em vez de chaves de API
- Você precisa de um comportamento de execução de agente GPT-5 mais rigoroso
summary: Use a OpenAI por meio de chaves de API ou da assinatura do Codex no OpenClaw
summary: Use a OpenAI por meio de chaves de API ou assinatura do Codex no OpenClaw
title: OpenAI
x-i18n:
generated_at: "2026-04-30T10:05:43Z"
generated_at: "2026-04-30T16:29:25Z"
model: gpt-5.5
provider: openai
source_hash: be0e2cd14990a53533c800cd8d305c9c50b0fa7131f6638e7b9d8dd9f2942fe8
source_hash: 7e113f2418f82a8859f208f85efb55114bda7bc17beeb28f012b19e861609dad
source_path: providers/openai.md
workflow: 16
---
A OpenAI fornece APIs para desenvolvedores para modelos GPT, e o Codex também está disponível como um agente de codificação de plano ChatGPT por meio dos clientes Codex da OpenAI. O OpenClaw mantém essas superfícies separadas para que a configuração permaneça previsível.
A OpenAI fornece APIs de desenvolvedor para modelos GPT, e o Codex também está disponível como um agente de codificação de plano ChatGPT por meio dos clientes Codex da OpenAI. O OpenClaw mantém essas superfícies separadas para que a configuração permaneça previsível.
O OpenClaw oferece suporte a três rotas da família OpenAI. O prefixo do modelo seleciona a rota de provedor/autenticação; uma configuração de runtime separada seleciona quem executa o loop de agente incorporado:
O OpenClaw oferece suporte a três rotas da família OpenAI. O prefixo do modelo seleciona a rota de provedor/autenticação; uma configuração de runtime separada seleciona quem executa o loop do agente incorporado:
- **Chave de API** — acesso direto à OpenAI Platform com cobrança baseada em uso (modelos `openai/*`)
- **Assinatura Codex via PI** — login ChatGPT/Codex com acesso por assinatura (modelos `openai-codex/*`)
- **Harness do app-server Codex** — execução nativa do app-server Codex (modelos `openai/*` mais `agents.defaults.agentRuntime.id: "codex"`)
- **Assinatura do Codex pelo PI** — login do ChatGPT/Codex com acesso por assinatura (modelos `openai-codex/*`)
- **Harness do servidor de aplicativo do Codex** — execução nativa do servidor de aplicativo do Codex (modelos `openai/*` mais `agents.defaults.agentRuntime.id: "codex"`)
A OpenAI oferece suporte explícito ao uso de OAuth de assinatura em ferramentas externas e fluxos de trabalho como o OpenClaw.
Provedor, modelo, runtime e canal são camadas separadas. Se esses rótulos estiverem
sendo confundidos, leia [Runtimes de agente](/pt-BR/concepts/agent-runtimes) antes de
sendo misturados, leia [Runtimes de agente](/pt-BR/concepts/agent-runtimes) antes de
alterar a configuração.
## Escolha rápida
@ -33,8 +33,8 @@ alterar a configuração.
| Objetivo | Use | Observações |
| --------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------- |
| Cobrança direta por chave de API | `openai/gpt-5.5` | Defina `OPENAI_API_KEY` ou execute o onboarding de chave de API da OpenAI. |
| GPT-5.5 com autenticação de assinatura ChatGPT/Codex | `openai-codex/gpt-5.5` | Rota PI padrão para OAuth do Codex. Melhor primeira escolha para configurações de assinatura. |
| GPT-5.5 com comportamento nativo do app-server Codex | `openai/gpt-5.5` mais `agentRuntime.id: "codex"` | Força o harness do app-server Codex para essa referência de modelo. |
| GPT-5.5 com autenticação de assinatura ChatGPT/Codex | `openai-codex/gpt-5.5` | Rota PI padrão para OAuth do Codex. Melhor primeira escolha para configurações com assinatura. |
| GPT-5.5 com comportamento nativo do servidor de aplicativo do Codex | `openai/gpt-5.5` mais `agentRuntime.id: "codex"` | Força o harness do servidor de aplicativo do Codex para essa referência de modelo. |
| Geração ou edição de imagens | `openai/gpt-image-2` | Funciona com `OPENAI_API_KEY` ou OAuth do OpenAI Codex. |
| Imagens com fundo transparente | `openai/gpt-image-1.5` | Use `outputFormat=png` ou `webp` e `openai.background=transparent`. |
@ -42,45 +42,57 @@ alterar a configuração.
Os nomes são parecidos, mas não são intercambiáveis:
| Nome que você vê | Camada | Significado |
| Nome que você vê | Camada | Significado |
| ---------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------- |
| `openai` | Prefixo de provedor | Rota direta da API da OpenAI Platform. |
| `openai-codex` | Prefixo de provedor | Rota de OAuth/assinatura do OpenAI Codex pelo executor PI normal do OpenClaw. |
| Plugin `codex` | Plugin | Plugin incluído do OpenClaw que fornece runtime nativo do app-server Codex e controles de chat `/codex`. |
| `agentRuntime.id: codex` | Runtime de agente | Força o harness nativo do app-server Codex para turnos incorporados. |
| `/codex ...` | Conjunto de comandos de chat | Vincula/controla threads do app-server Codex a partir de uma conversa. |
| `runtime: "acp", agentId: "codex"` | Rota de sessão ACP | Caminho de fallback explícito que executa o Codex por ACP/acpx. |
| `openai-codex` | Prefixo de provedor | Rota de OAuth/assinatura do OpenAI Codex pelo executor PI normal do OpenClaw. |
| `codex` plugin | Plugin | Plugin integrado do OpenClaw que fornece runtime nativo do servidor de aplicativo do Codex e controles de chat `/codex`. |
| `agentRuntime.id: codex` | Runtime de agente | Força o harness nativo do servidor de aplicativo do Codex para turnos incorporados. |
| `/codex ...` | Conjunto de comandos de chat | Vincule/controle threads do servidor de aplicativo do Codex a partir de uma conversa. |
| `runtime: "acp", agentId: "codex"` | Rota de sessão ACP | Caminho de fallback explícito que executa o Codex por meio de ACP/acpx. |
Isso significa que uma configuração pode conter intencionalmente tanto `openai-codex/*` quanto o Plugin `codex`. Isso é válido quando você quer OAuth do Codex via PI e também quer controles de chat nativos `/codex` disponíveis. `openclaw doctor` avisa sobre essa combinação para que você possa confirmar que ela é intencional; ele não a reescreve.
Isso significa que uma configuração pode conter intencionalmente tanto `openai-codex/*` quanto o
Plugin `codex`. Isso é válido quando você quer OAuth do Codex pelo PI e também quer
controles de chat nativos `/codex` disponíveis. `openclaw doctor` avisa sobre essa
combinação para que você possa confirmar que ela é intencional; ele não a reescreve.
<Note>
O GPT-5.5 está disponível tanto por acesso direto com chave de API da OpenAI Platform quanto por rotas de assinatura/OAuth. Use `openai/gpt-5.5` para tráfego direto com `OPENAI_API_KEY`, `openai-codex/gpt-5.5` para OAuth do Codex via PI, ou `openai/gpt-5.5` com `agentRuntime.id: "codex"` para o harness nativo do app-server Codex.
O GPT-5.5 está disponível tanto por acesso direto com chave de API da OpenAI Platform quanto por
rotas de assinatura/OAuth. Use `openai/gpt-5.5` para tráfego direto com `OPENAI_API_KEY`,
`openai-codex/gpt-5.5` para OAuth do Codex pelo PI ou
`openai/gpt-5.5` com `agentRuntime.id: "codex"` para o harness nativo do servidor de aplicativo
do Codex.
</Note>
<Note>
Habilitar o Plugin da OpenAI, ou selecionar um modelo `openai-codex/*`, não habilita o Plugin incluído do app-server Codex. O OpenClaw habilita esse Plugin somente quando você seleciona explicitamente o harness nativo do Codex com `agentRuntime.id: "codex"` ou usa uma referência de modelo legada `codex/*`.
Se o Plugin incluído `codex` estiver habilitado, mas `openai-codex/*` ainda resolver pelo PI, `openclaw doctor` avisa e deixa a rota inalterada.
Habilitar o Plugin da OpenAI, ou selecionar um modelo `openai-codex/*`, não
habilita o Plugin integrado de servidor de aplicativo do Codex. O OpenClaw habilita esse Plugin apenas
quando você seleciona explicitamente o harness nativo do Codex com
`agentRuntime.id: "codex"` ou usa uma referência de modelo legada `codex/*`.
Se o Plugin integrado `codex` estiver habilitado, mas `openai-codex/*` ainda resolver
pelo PI, `openclaw doctor` avisa e deixa a rota inalterada.
</Note>
## Cobertura de recursos do OpenClaw
| Capacidade da OpenAI | Superfície do OpenClaw | Status |
| Capacidade da OpenAI | Superfície do OpenClaw | Status |
| ------------------------- | ---------------------------------------------------------- | ------------------------------------------------------ |
| Chat / Responses | provedor de modelo `openai/<model>` | Sim |
| Modelos de assinatura Codex | `openai-codex/<model>` com OAuth `openai-codex` | Sim |
| Harness do app-server Codex | `openai/<model>` com `agentRuntime.id: codex` | Sim |
| Busca web no lado do servidor | Ferramenta nativa OpenAI Responses | Sim, quando a busca web está habilitada e nenhum provedor está fixado |
| Chat / Responses | provedor de modelo `openai/<model>` | Sim |
| Modelos de assinatura do Codex | `openai-codex/<model>` com OAuth `openai-codex` | Sim |
| Harness do servidor de aplicativo do Codex | `openai/<model>` com `agentRuntime.id: codex` | Sim |
| Pesquisa na web no lado do servidor | Ferramenta nativa OpenAI Responses | Sim, quando a pesquisa na web está habilitada e nenhum provedor está fixado |
| Imagens | `image_generate` | Sim |
| Vídeos | `video_generate` | Sim |
| Texto para fala | `messages.tts.provider: "openai"` / `tts` | Sim |
| Fala para texto em lote | `tools.media.audio` / compreensão de mídia | Sim |
| Fala para texto em streaming | Voice Call `streaming.provider: "openai"` | Sim |
| Fala para texto em streaming | Voice Call `streaming.provider: "openai"` | Sim |
| Voz em tempo real | Voice Call `realtime.provider: "openai"` / Control UI Talk | Sim |
| Embeddings | provedor de embeddings de memória | Sim |
## Embeddings de memória
O OpenClaw pode usar a OpenAI, ou um endpoint de embeddings compatível com a OpenAI, para indexação `memory_search` e embeddings de consulta:
O OpenClaw pode usar a OpenAI, ou um endpoint de embeddings compatível com a OpenAI, para
indexação de `memory_search` e embeddings de consulta:
```json5
{
@ -95,7 +107,11 @@ O OpenClaw pode usar a OpenAI, ou um endpoint de embeddings compatível com a Op
}
```
Para endpoints compatíveis com a OpenAI que exigem rótulos de embedding assimétricos, defina `queryInputType` e `documentInputType` em `memorySearch`. O OpenClaw encaminha esses valores como campos de solicitação `input_type` específicos do provedor: embeddings de consulta usam `queryInputType`; fragmentos de memória indexados e indexação em lote usam `documentInputType`. Veja a [referência de configuração de memória](/pt-BR/reference/memory-config#provider-specific-config) para o exemplo completo.
Para endpoints compatíveis com a OpenAI que exigem rótulos assimétricos de embeddings, defina
`queryInputType` e `documentInputType` em `memorySearch`. O OpenClaw encaminha
esses valores como campos de solicitação `input_type` específicos do provedor: embeddings de consulta usam
`queryInputType`; fragmentos de memória indexados e indexação em lote usam
`documentInputType`. Consulte a [referência de configuração de memória](/pt-BR/reference/memory-config#provider-specific-config) para o exemplo completo.
## Primeiros passos
@ -129,14 +145,17 @@ Escolha seu método de autenticação preferido e siga as etapas de configuraç
### Resumo da rota
| Referência de modelo | Configuração de runtime | Rota | Autenticação |
| Referência de modelo | Configuração de runtime | Rota | Autenticação |
| ---------------------- | -------------------------- | --------------------------- | ---------------- |
| `openai/gpt-5.5` | omitido / `agentRuntime.id: "pi"` | API direta da OpenAI Platform | `OPENAI_API_KEY` |
| `openai/gpt-5.4-mini` | omitido / `agentRuntime.id: "pi"` | API direta da OpenAI Platform | `OPENAI_API_KEY` |
| `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Harness do app-server Codex | App-server Codex |
| `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Harness do servidor de aplicativo do Codex | Servidor de aplicativo do Codex |
<Note>
`openai/*` é a rota direta com chave de API da OpenAI, a menos que você force explicitamente o harness do app-server Codex. Use `openai-codex/*` para OAuth do Codex pelo executor PI padrão, ou use `openai/gpt-5.5` com `agentRuntime.id: "codex"` para execução nativa do app-server Codex.
`openai/*` é a rota direta com chave de API da OpenAI, a menos que você force explicitamente
o harness do servidor de aplicativo do Codex. Use `openai-codex/*` para OAuth do Codex pelo
executor PI padrão, ou use `openai/gpt-5.5` com
`agentRuntime.id: "codex"` para execução nativa no servidor de aplicativo do Codex.
</Note>
### Exemplo de configuração
@ -149,13 +168,13 @@ Escolha seu método de autenticação preferido e siga as etapas de configuraç
```
<Warning>
O OpenClaw **não** expõe `openai/gpt-5.3-codex-spark`. Solicitações live à API da OpenAI rejeitam esse modelo, e o catálogo Codex atual também não o expõe.
O OpenClaw **não** expõe `openai/gpt-5.3-codex-spark`. Solicitações reais à API da OpenAI rejeitam esse modelo, e o catálogo atual do Codex também não o expõe.
</Warning>
</Tab>
<Tab title="Assinatura Codex">
**Melhor para:** usar sua assinatura ChatGPT/Codex em vez de uma chave de API separada. A nuvem do Codex exige login ChatGPT.
<Tab title="Assinatura do Codex">
**Melhor para:** usar sua assinatura ChatGPT/Codex em vez de uma chave de API separada. A nuvem do Codex exige login no ChatGPT.
<Steps>
<Step title="Execute o OAuth do Codex">
@ -169,7 +188,7 @@ Escolha seu método de autenticação preferido e siga as etapas de configuraç
openclaw models auth login --provider openai-codex
```
Para configurações sem interface ou hostis a callback, adicione `--device-code` para entrar com um fluxo de código de dispositivo do ChatGPT em vez do callback do navegador localhost:
Para configurações sem interface ou hostis a callbacks, adicione `--device-code` para entrar com um fluxo de código de dispositivo do ChatGPT em vez do callback de navegador localhost:
```bash
openclaw models auth login --provider openai-codex --device-code
@ -191,18 +210,17 @@ Escolha seu método de autenticação preferido e siga as etapas de configuraç
| Referência de modelo | Configuração de runtime | Rota | Autenticação |
|-----------|----------------|-------|------|
| `openai-codex/gpt-5.5` | omitido / `runtime: "pi"` | OAuth ChatGPT/Codex via PI | Login Codex |
| `openai-codex/gpt-5.5` | `runtime: "auto"` | Ainda PI, a menos que um Plugin reivindique explicitamente `openai-codex` | Login Codex |
| `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Harness do app-server Codex | Autenticação do app-server Codex |
| `openai-codex/gpt-5.5` | omitido / `runtime: "pi"` | OAuth ChatGPT/Codex pelo PI | Login do Codex |
| `openai-codex/gpt-5.4-mini` | omitido / `runtime: "pi"` | OAuth ChatGPT/Codex pelo PI | Login do Codex |
| `openai-codex/gpt-5.5` | `runtime: "auto"` | Ainda PI, a menos que um Plugin reivindique explicitamente `openai-codex` | Login do Codex |
| `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Harness do servidor de aplicativo do Codex | Autenticação do servidor de aplicativo do Codex |
<Note>
Continue usando o id de provedor `openai-codex` para comandos de autenticação/perfil. O prefixo de modelo `openai-codex/*` também é a rota PI explícita para OAuth do Codex. Ele não seleciona nem habilita automaticamente o harness incluído do app-server Codex.
Continue usando o id de provedor `openai-codex` para comandos de autenticação/perfil. O
prefixo de modelo `openai-codex/*` também é a rota PI explícita para OAuth do Codex.
Ele não seleciona nem habilita automaticamente o harness integrado do servidor de aplicativo do Codex.
</Note>
<Warning>
`openai-codex/gpt-5.4-mini` não é uma rota de OAuth do Codex compatível. Use `openai/gpt-5.4-mini` com uma chave de API da OpenAI, ou use `openai-codex/gpt-5.5` com OAuth do Codex.
</Warning>
### Exemplo de configuração
```json5
@ -212,32 +230,31 @@ Escolha seu método de autenticação preferido e siga as etapas de configuraç
```
<Note>
O onboarding não importa mais material de OAuth de `~/.codex`. Entre com OAuth pelo navegador (padrão) ou pelo fluxo de código de dispositivo acima — o OpenClaw gerencia as credenciais resultantes em seu próprio armazenamento de autenticação de agente.
O onboarding não importa mais material OAuth de `~/.codex`. Entre com OAuth no navegador (padrão) ou com o fluxo de código de dispositivo acima — o OpenClaw gerencia as credenciais resultantes em seu próprio armazenamento de autenticação de agente.
</Note>
### Indicador de status
O `/status` do chat mostra qual runtime de modelo está ativo para a sessão atual.
O harness Pi padrão aparece como `Runtime: OpenClaw Pi Default`. Quando o
harness app-server Codex incluído é selecionado, `/status` mostra
Chat `/status` mostra qual runtime de modelo está ativo para a sessão atual.
O harness PI padrão aparece como `Runtime: OpenClaw Pi Default`. Quando o
harness app-server do Codex incluído é selecionado, `/status` mostra
`Runtime: OpenAI Codex`. Sessões existentes mantêm o id de harness registrado, então use
`/new` ou `/reset` após alterar `agentRuntime` se quiser que `/status`
reflita uma nova escolha PI/Codex.
`/new` ou `/reset` depois de alterar `agentRuntime` se quiser que `/status`
reflita uma nova escolha de PI/Codex.
### Aviso do doctor
Se o Plugin `codex` incluído estiver habilitado enquanto a rota
`openai-codex/*` desta aba estiver selecionada, `openclaw doctor` avisa que o modelo
ainda é resolvido por meio do PI. Mantenha a configuração inalterada quando essa for a
rota pretendida de autenticação por assinatura. Troque para `openai/<model>` mais
`agentRuntime.id: "codex"` somente quando quiser execução nativa do app-server
Codex.
rota pretendida de autenticação por assinatura. Mude para `openai/<model>` mais
`agentRuntime.id: "codex"` somente quando quiser execução nativa pelo app-server do Codex.
### Limite da janela de contexto
O OpenClaw trata metadados de modelo e o limite de contexto do runtime como valores separados.
O OpenClaw trata os metadados do modelo e o limite de contexto do runtime como valores separados.
Para `openai-codex/gpt-5.5` por OAuth do Codex:
Para `openai-codex/gpt-5.5` por meio do Codex OAuth:
- `contextWindow` nativa: `1000000`
- Limite padrão de `contextTokens` do runtime: `272000`
@ -263,7 +280,7 @@ Escolha seu método de autenticação preferido e siga as etapas de configuraç
### Recuperação do catálogo
O OpenClaw usa metadados do catálogo upstream do Codex para `gpt-5.5` quando eles estão
presentes. Se a descoberta ao vivo do Codex omitir a linha `openai-codex/gpt-5.5` enquanto
presentes. Se a descoberta Codex ao vivo omitir a linha `openai-codex/gpt-5.5` enquanto
a conta estiver autenticada, o OpenClaw sintetiza essa linha de modelo OAuth para que
execuções de cron, subagente e modelo padrão configurado não falhem com
`Unknown model`.
@ -271,41 +288,41 @@ Escolha seu método de autenticação preferido e siga as etapas de configuraç
</Tab>
</Tabs>
## Autenticação nativa do app-server Codex
## Autenticação nativa do app-server do Codex
O harness nativo app-server Codex usa referências de modelo `openai/*` mais
O harness app-server nativo do Codex usa referências de modelo `openai/*` mais
`agentRuntime.id: "codex"`, mas sua autenticação ainda é baseada em conta. O OpenClaw
seleciona a autenticação nesta ordem:
1. Um perfil de autenticação OpenClaw `openai-codex` explícito vinculado ao agente.
2. A conta existente do app-server, como um login local ChatGPT da CLI Codex.
3. Somente para inicializações locais do app-server por stdio, `CODEX_API_KEY`, depois
`OPENAI_API_KEY`, quando o app-server não relata nenhuma conta e ainda exige
autenticação OpenAI.
1. Um perfil de autenticação `openai-codex` explícito do OpenClaw vinculado ao agente.
2. A conta existente do app-server, como um login local do Codex CLI ChatGPT.
3. Somente para inicializações locais do app-server via stdio, `CODEX_API_KEY`, depois
`OPENAI_API_KEY`, quando o app-server informa que não há conta e ainda requer
autenticação da OpenAI.
Isso significa que um login local de assinatura ChatGPT/Codex não é substituído apenas
porque o processo Gateway também tem `OPENAI_API_KEY` para modelos OpenAI diretos
ou embeddings. O fallback de chave de API por env é apenas o caminho local de stdio sem conta; ele
não é enviado para conexões WebSocket do app-server. Quando um perfil Codex
em estilo assinatura é selecionado, o OpenClaw também mantém `CODEX_API_KEY` e `OPENAI_API_KEY`
fora do processo filho app-server stdio gerado e envia as credenciais selecionadas
Isso significa que um login de assinatura local do ChatGPT/Codex não é substituído apenas
porque o processo do Gateway também tem `OPENAI_API_KEY` para modelos diretos da OpenAI
ou embeddings. O fallback de chave de API por env é apenas o caminho local stdio sem conta; ele
não é enviado a conexões app-server WebSocket. Quando um perfil Codex em estilo de assinatura
é selecionado, o OpenClaw também mantém `CODEX_API_KEY` e `OPENAI_API_KEY`
fora do processo filho app-server stdio iniciado e envia as credenciais selecionadas
por meio do RPC de login do app-server.
## Geração de imagens
O Plugin `openai` incluído registra geração de imagens por meio da ferramenta `image_generate`.
Ele oferece suporte tanto à geração de imagens por chave de API OpenAI quanto à geração de imagens por OAuth do Codex
por meio da mesma referência de modelo `openai/gpt-image-2`.
Ele oferece suporte tanto à geração de imagens com chave de API da OpenAI quanto à geração
de imagens com Codex OAuth por meio da mesma referência de modelo `openai/gpt-image-2`.
| Capacidade | Chave de API OpenAI | OAuth do Codex |
| ------------------------ | ---------------------------------- | ----------------------------------- |
| Referência de modelo | `openai/gpt-image-2` | `openai/gpt-image-2` |
| Autenticação | `OPENAI_API_KEY` | Login OAuth OpenAI Codex |
| Transporte | API OpenAI Images | Backend Responses do Codex |
| Máx. de imagens por solicitação | 4 | 4 |
| Capacidade | Chave de API da OpenAI | Codex OAuth |
| ------------------------ | ---------------------------------- | ------------------------------------ |
| Referência de modelo | `openai/gpt-image-2` | `openai/gpt-image-2` |
| Autenticação | `OPENAI_API_KEY` | Login OpenAI Codex OAuth |
| Transporte | API Images da OpenAI | Backend Responses do Codex |
| Máx. de imagens por solicitação | 4 | 4 |
| Modo de edição | Habilitado (até 5 imagens de referência) | Habilitado (até 5 imagens de referência) |
| Substituições de tamanho | Compatíveis, incluindo tamanhos 2K/4K | Compatíveis, incluindo tamanhos 2K/4K |
| Proporção / resolução | Não encaminhada para a API OpenAI Images | Mapeada para um tamanho compatível quando seguro |
| Substituições de tamanho | Suportadas, incluindo tamanhos 2K/4K | Suportadas, incluindo tamanhos 2K/4K |
| Proporção / resolução | Não encaminhada para a API Images da OpenAI | Mapeada para um tamanho compatível quando seguro |
```json5
{
@ -318,24 +335,24 @@ por meio da mesma referência de modelo `openai/gpt-image-2`.
```
<Note>
Veja [Geração de imagens](/pt-BR/tools/image-generation) para parâmetros compartilhados da ferramenta, seleção de provedor e comportamento de failover.
Consulte [Geração de imagens](/pt-BR/tools/image-generation) para parâmetros compartilhados da ferramenta, seleção de provedor e comportamento de failover.
</Note>
`gpt-image-2` é o padrão tanto para geração OpenAI de texto para imagem quanto para edição de imagens.
`gpt-image-1.5`, `gpt-image-1` e `gpt-image-1-mini` continuam utilizáveis como
`gpt-image-2` é o padrão tanto para geração de texto para imagem da OpenAI quanto para edição
de imagens. `gpt-image-1.5`, `gpt-image-1` e `gpt-image-1-mini` continuam utilizáveis como
substituições explícitas de modelo. Use `openai/gpt-image-1.5` para saída PNG/WebP
com fundo transparente; a API atual de `gpt-image-2` rejeita
`background: "transparent"`.
Para uma solicitação com fundo transparente, os agentes devem chamar `image_generate` com
Para uma solicitação de fundo transparente, agentes devem chamar `image_generate` com
`model: "openai/gpt-image-1.5"`, `outputFormat: "png"` ou `"webp"`, e
`background: "transparent"`; a opção de provedor mais antiga `openai.background` ainda é
aceita. O OpenClaw também protege as rotas públicas OpenAI e
OAuth OpenAI Codex reescrevendo solicitações transparentes padrão de `openai/gpt-image-2`
`background: "transparent"`; a opção de provedor `openai.background` mais antiga
ainda é aceita. O OpenClaw também protege as rotas públicas da OpenAI e
OpenAI Codex OAuth reescrevendo solicitações transparentes padrão de `openai/gpt-image-2`
para `gpt-image-1.5`; endpoints Azure e personalizados compatíveis com OpenAI mantêm
seus nomes de implantação/modelo configurados.
A mesma configuração é exposta para execuções CLI headless:
A mesma configuração é exposta para execuções headless da CLI:
```bash
openclaw infer image generate \
@ -348,17 +365,17 @@ openclaw infer image generate \
Use as mesmas flags `--output-format` e `--background` com
`openclaw infer image edit` ao começar a partir de um arquivo de entrada.
`--openai-background` continua disponível como um alias específico da OpenAI.
`--openai-background` continua disponível como alias específico da OpenAI.
Para instalações com OAuth do Codex, mantenha a mesma referência `openai/gpt-image-2`. Quando um
perfil OAuth `openai-codex` é configurado, o OpenClaw resolve esse token de acesso OAuth
Para instalações com Codex OAuth, mantenha a mesma referência `openai/gpt-image-2`. Quando um
perfil OAuth `openai-codex` está configurado, o OpenClaw resolve esse token de acesso OAuth
armazenado e envia solicitações de imagem por meio do backend Responses do Codex. Ele
não tenta primeiro `OPENAI_API_KEY` nem faz fallback silencioso para uma chave de API nessa
solicitação. Configure `models.providers.openai` explicitamente com uma chave de API,
URL base personalizada ou endpoint Azure quando quiser a rota direta da API OpenAI Images.
Se esse endpoint personalizado de imagens estiver em uma LAN/endereço privado confiável, defina também
URL base personalizada ou endpoint Azure quando quiser a rota direta da API Images da OpenAI.
Se esse endpoint de imagem personalizado estiver em uma LAN/endereço privado confiável, também defina
`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`; o OpenClaw mantém
endpoints de imagem privados/internos compatíveis com OpenAI bloqueados, a menos que essa opção esteja
endpoints de imagem privados/internos compatíveis com OpenAI bloqueados a menos que essa adesão esteja
presente.
Gerar:
@ -383,13 +400,13 @@ Editar:
O Plugin `openai` incluído registra geração de vídeo por meio da ferramenta `video_generate`.
| Capacidade | Valor |
| ---------------------- | --------------------------------------------------------------------------------- |
| Modelo padrão | `openai/sora-2` |
| Modos | Texto para vídeo, imagem para vídeo, edição de vídeo único |
| Entradas de referência | 1 imagem ou 1 vídeo |
| Substituições de tamanho | Compatíveis |
| Outras substituições | `aspectRatio`, `resolution`, `audio`, `watermark` são ignorados com um aviso da ferramenta |
| Capacidade | Valor |
| ---------------- | --------------------------------------------------------------------------------- |
| Modelo padrão | `openai/sora-2` |
| Modos | Texto para vídeo, imagem para vídeo, edição de um único vídeo |
| Entradas de referência | 1 imagem ou 1 vídeo |
| Substituições de tamanho | Suportadas |
| Outras substituições | `aspectRatio`, `resolution`, `audio`, `watermark` são ignorados com um aviso da ferramenta |
```json5
{
@ -402,25 +419,25 @@ O Plugin `openai` incluído registra geração de vídeo por meio da ferramenta
```
<Note>
Veja [Geração de vídeo](/pt-BR/tools/video-generation) para parâmetros compartilhados da ferramenta, seleção de provedor e comportamento de failover.
Consulte [Geração de vídeo](/pt-BR/tools/video-generation) para parâmetros compartilhados da ferramenta, seleção de provedor e comportamento de failover.
</Note>
## Contribuição de prompt do GPT-5
O OpenClaw adiciona uma contribuição compartilhada de prompt do GPT-5 para execuções da família GPT-5 entre provedores. Ela se aplica por id de modelo, então `openai-codex/gpt-5.5`, `openai/gpt-5.5`, `openrouter/openai/gpt-5.5`, `opencode/gpt-5.5` e outras referências GPT-5 compatíveis recebem a mesma sobreposição. Modelos GPT-4.x mais antigos não recebem.
O OpenClaw adiciona uma contribuição de prompt GPT-5 compartilhada para execuções da família GPT-5 entre provedores. Ela se aplica por id de modelo, então `openai-codex/gpt-5.5`, `openai/gpt-5.5`, `openrouter/openai/gpt-5.5`, `opencode/gpt-5.5` e outras referências GPT-5 compatíveis recebem a mesma sobreposição. Modelos GPT-4.x mais antigos não recebem.
O harness nativo Codex incluído usa o mesmo comportamento GPT-5 e a mesma sobreposição de Heartbeat por meio de instruções de desenvolvedor do app-server Codex, então sessões `openai/gpt-5.x` forçadas por `agentRuntime.id: "codex"` mantêm a mesma orientação de acompanhamento e Heartbeat proativo, embora o Codex controle o restante do prompt do harness.
O harness nativo do Codex incluído usa o mesmo comportamento GPT-5 e a mesma sobreposição de Heartbeat por meio das instruções de desenvolvedor do app-server Codex, então sessões `openai/gpt-5.x` forçadas por `agentRuntime.id: "codex"` mantêm a mesma orientação de acompanhamento e Heartbeat proativo, mesmo que o Codex seja dono do restante do prompt do harness.
A contribuição GPT-5 adiciona um contrato de comportamento com tags para persistência de persona, segurança de execução, disciplina de ferramentas, formato de saída, verificações de conclusão e verificação. O comportamento de resposta específico do canal e de mensagem silenciosa permanece no prompt de sistema compartilhado do OpenClaw e na política de entrega de saída. A orientação GPT-5 está sempre habilitada para modelos correspondentes. A camada de estilo de interação amigável é separada e configurável.
A contribuição GPT-5 adiciona um contrato de comportamento marcado para persistência de persona, segurança de execução, disciplina de ferramentas, formato de saída, verificações de conclusão e verificação. O comportamento de resposta específico do canal e de mensagens silenciosas permanece no prompt de sistema compartilhado do OpenClaw e na política de entrega de saída. A orientação GPT-5 está sempre habilitada para modelos correspondentes. A camada de estilo de interação amigável é separada e configurável.
| Valor | Efeito |
| ---------------------- | ------------------------------------------- |
| `"friendly"` (padrão) | Habilita a camada de estilo de interação amigável |
| `"on"` | Alias para `"friendly"` |
| `"off"` | Desabilita apenas a camada de estilo amigável |
| `"off"` | Desabilita somente a camada de estilo amigável |
<Tabs>
<Tab title="Config">
<Tab title="Configuração">
```json5
{
agents: {
@ -451,15 +468,15 @@ Os valores não diferenciam maiúsculas de minúsculas em runtime, então `"Off"
## Voz e fala
<AccordionGroup>
<Accordion title="Speech synthesis (TTS)">
<Accordion title="Síntese de fala (TTS)">
O Plugin `openai` incluído registra síntese de fala para a superfície `messages.tts`.
| Configuração | Caminho de configuração | Padrão |
|---------|------------|---------|
|--------------|-------------------------|--------|
| Modelo | `messages.tts.providers.openai.model` | `gpt-4o-mini-tts` |
| Voz | `messages.tts.providers.openai.voice` | `coral` |
| Velocidade | `messages.tts.providers.openai.speed` | (não definido) |
| Instruções | `messages.tts.providers.openai.instructions` | (não definido, apenas `gpt-4o-mini-tts`) |
| Instruções | `messages.tts.providers.openai.instructions` | (não definido, somente `gpt-4o-mini-tts`) |
| Formato | `messages.tts.providers.openai.responseFormat` | `opus` para notas de voz, `mp3` para arquivos |
| Chave de API | `messages.tts.providers.openai.apiKey` | Faz fallback para `OPENAI_API_KEY` |
| URL base | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` |
@ -484,16 +501,16 @@ Os valores não diferenciam maiúsculas de minúsculas em runtime, então `"Off"
</Accordion>
<Accordion title="Speech-to-text">
<Accordion title="Fala para texto">
O Plugin `openai` incluído registra fala para texto em lote por meio da
superfície de transcrição de entendimento de mídia do OpenClaw.
superfície de transcrição de compreensão de mídia do OpenClaw.
- Modelo padrão: `gpt-4o-transcribe`
- Endpoint: REST OpenAI `/v1/audio/transcriptions`
- Endpoint: REST da OpenAI `/v1/audio/transcriptions`
- Caminho de entrada: upload de arquivo de áudio multipart
- Compatível com o OpenClaw onde quer que a transcrição de áudio de entrada use
- Compatível com o OpenClaw sempre que a transcrição de áudio de entrada usa
`tools.media.audio`, incluindo segmentos de canal de voz do Discord e anexos
de áudio de canais
de áudio de canal
Para forçar a OpenAI para transcrição de áudio de entrada:
@ -515,51 +532,51 @@ Os valores não diferenciam maiúsculas de minúsculas em runtime, então `"Off"
}
```
As dicas de idioma e prompt são encaminhadas para a OpenAI quando fornecidas pela
As dicas de idioma e prompt são encaminhadas à OpenAI quando fornecidas pela
configuração compartilhada de mídia de áudio ou pela solicitação de transcrição por chamada.
</Accordion>
<Accordion title="Transcrição em tempo real">
O Plugin `openai` incluído registra transcrição em tempo real para o Plugin Voice Call.
O plugin `openai` incluído registra transcrição em tempo real para o plugin Voice Call.
| Configuração | Caminho de configuração | Padrão |
| Configuração | Caminho da configuração | Padrão |
|---------|------------|---------|
| Modelo | `plugins.entries.voice-call.config.streaming.providers.openai.model` | `gpt-4o-transcribe` |
| Idioma | `...openai.language` | (não definido) |
| Prompt | `...openai.prompt` | (não definido) |
| Duração do silêncio | `...openai.silenceDurationMs` | `800` |
| Limite de VAD | `...openai.vadThreshold` | `0.5` |
| Chave de API | `...openai.apiKey` | Usa `OPENAI_API_KEY` como fallback |
| Limiar de VAD | `...openai.vadThreshold` | `0.5` |
| Chave de API | `...openai.apiKey` | Recorre a `OPENAI_API_KEY` |
<Note>
Usa uma conexão WebSocket com `wss://api.openai.com/v1/realtime` com áudio G.711 u-law (`g711_ulaw` / `audio/pcmu`). Este provedor de streaming é para o caminho de transcrição em tempo real do Voice Call; a voz do Discord atualmente grava segmentos curtos e usa o caminho de transcrição em lote `tools.media.audio`.
Usa uma conexão WebSocket com `wss://api.openai.com/v1/realtime` com áudio G.711 u-law (`g711_ulaw` / `audio/pcmu`). Esse provedor de streaming é para o caminho de transcrição em tempo real do Voice Call; a voz do Discord atualmente grava segmentos curtos e usa o caminho de transcrição em lote `tools.media.audio`.
</Note>
</Accordion>
<Accordion title="Voz em tempo real">
O Plugin `openai` incluído registra voz em tempo real para o Plugin Voice Call.
O plugin `openai` incluído registra voz em tempo real para o plugin Voice Call.
| Configuração | Caminho de configuração | Padrão |
| Configuração | Caminho da configuração | Padrão |
|---------|------------|---------|
| Modelo | `plugins.entries.voice-call.config.realtime.providers.openai.model` | `gpt-realtime-1.5` |
| Voz | `...openai.voice` | `alloy` |
| Temperatura | `...openai.temperature` | `0.8` |
| Limite de VAD | `...openai.vadThreshold` | `0.5` |
| Limiar de VAD | `...openai.vadThreshold` | `0.5` |
| Duração do silêncio | `...openai.silenceDurationMs` | `500` |
| Chave de API | `...openai.apiKey` | Usa `OPENAI_API_KEY` como fallback |
| Chave de API | `...openai.apiKey` | Recorre a `OPENAI_API_KEY` |
<Note>
Oferece suporte ao Azure OpenAI por meio das chaves de configuração `azureEndpoint` e `azureDeployment` para pontes em tempo real de backend. Oferece suporte a chamadas de ferramentas bidirecionais. Usa formato de áudio G.711 u-law.
Compatível com Azure OpenAI por meio das chaves de configuração `azureEndpoint` e `azureDeployment` para pontes de tempo real no backend. Compatível com chamadas de ferramentas bidirecionais. Usa o formato de áudio G.711 u-law.
</Note>
<Note>
O Talk da Control UI usa sessões em tempo real da OpenAI no navegador com um segredo de cliente efêmero
emitido pelo Gateway e uma troca SDP WebRTC direta do navegador com a
OpenAI Realtime API. A verificação ao vivo por mantenedores está disponível com
O Talk da UI de Controle usa sessões em tempo real da OpenAI no navegador com um segredo de cliente efêmero
cunhado pelo Gateway e uma troca SDP WebRTC direta no navegador contra a
API Realtime da OpenAI. A verificação ao vivo por mantenedor está disponível com
`OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts`;
a etapa da OpenAI emite um segredo de cliente no Node, gera uma oferta SDP do navegador
a etapa da OpenAI cunha um segredo de cliente no Node, gera uma oferta SDP do navegador
com mídia de microfone falsa, publica-a na OpenAI e aplica a resposta SDP
sem registrar segredos.
</Note>
@ -567,31 +584,30 @@ Os valores não diferenciam maiúsculas de minúsculas em runtime, então `"Off"
</Accordion>
</AccordionGroup>
## Endpoints do Azure OpenAI
## Endpoints da Azure OpenAI
O provedor `openai` incluído pode direcionar uma recurso Azure OpenAI para geração de imagem
ao substituir a URL base. No caminho de geração de imagem, o OpenClaw
detecta nomes de host do Azure em `models.providers.openai.baseUrl` e alterna para
o formato de solicitação do Azure automaticamente.
O provedor `openai` incluído pode apontar para um recurso da Azure OpenAI para geração
de imagens substituindo a URL base. No caminho de geração de imagens, o OpenClaw
detecta nomes de host da Azure em `models.providers.openai.baseUrl` e alterna para
o formato de solicitação da Azure automaticamente.
<Note>
A voz em tempo real usa um caminho de configuração separado
(`plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint`)
e não é afetada por `models.providers.openai.baseUrl`. Consulte o acordeão **Voz em tempo real**
em [Voz e fala](#voice-and-speech) para suas configurações do Azure.
e não é afetada por `models.providers.openai.baseUrl`. Consulte o acordeão **Voz em tempo real** em [Voz e fala](#voice-and-speech) para suas configurações da Azure.
</Note>
Use o Azure OpenAI quando:
Use Azure OpenAI quando:
- Você já tiver uma assinatura, cota ou acordo empresarial do Azure OpenAI
- Você precisar de residência regional de dados ou controles de conformidade fornecidos pelo Azure
- Você quiser manter o tráfego dentro de uma tenancy existente do Azure
- Você já tem uma assinatura, cota ou contrato empresarial da Azure OpenAI
- Você precisa de residência regional de dados ou controles de conformidade que a Azure fornece
- Você quer manter o tráfego dentro de uma locação existente da Azure
### Configuração
Para geração de imagem do Azure pelo provedor `openai` incluído, aponte
`models.providers.openai.baseUrl` para seu recurso do Azure e defina `apiKey` como
a chave do Azure OpenAI (não uma chave da OpenAI Platform):
Para geração de imagens da Azure por meio do provedor `openai` incluído, aponte
`models.providers.openai.baseUrl` para seu recurso da Azure e defina `apiKey` como
a chave da Azure OpenAI (não uma chave da Plataforma OpenAI):
```json5
{
@ -606,47 +622,48 @@ a chave do Azure OpenAI (não uma chave da OpenAI Platform):
}
```
O OpenClaw reconhece estes sufixos de host do Azure para a rota de geração de imagem do Azure:
O OpenClaw reconhece estes sufixos de host da Azure para a rota de geração
de imagens da Azure:
- `*.openai.azure.com`
- `*.services.ai.azure.com`
- `*.cognitiveservices.azure.com`
Para solicitações de geração de imagem em um host do Azure reconhecido, o OpenClaw:
Para solicitações de geração de imagens em um host da Azure reconhecido, o OpenClaw:
- Envia o cabeçalho `api-key` em vez de `Authorization: Bearer`
- Usa caminhos com escopo de implantação (`/openai/deployments/{deployment}/...`)
- Acrescenta `?api-version=...` a cada solicitação
- Usa um tempo limite padrão de solicitação de 600 s para chamadas de geração de imagem do Azure.
- Usa um tempo limite padrão de solicitação de 600 s para chamadas de geração de imagens da Azure.
Valores `timeoutMs` por chamada ainda substituem esse padrão.
Outras URLs base (OpenAI pública, proxies compatíveis com OpenAI) mantêm o formato padrão
de solicitação de imagem da OpenAI.
Outras URLs base (OpenAI pública, proxies compatíveis com OpenAI) mantêm o formato
padrão de solicitação de imagem da OpenAI.
<Note>
O roteamento do Azure para o caminho de geração de imagem do provedor `openai` requer
O roteamento da Azure para o caminho de geração de imagens do provedor `openai` requer
OpenClaw 2026.4.22 ou posterior. Versões anteriores tratam qualquer
`openai.baseUrl` personalizado como o endpoint público da OpenAI e falharão com implantações
de imagem do Azure.
`openai.baseUrl` personalizado como o endpoint público da OpenAI e falharão contra implantações
de imagem da Azure.
</Note>
### Versão da API
Defina `AZURE_OPENAI_API_VERSION` para fixar uma versão específica preview ou GA do Azure
para o caminho de geração de imagem do Azure:
Defina `AZURE_OPENAI_API_VERSION` para fixar uma versão de prévia ou GA específica da Azure
para o caminho de geração de imagens da Azure:
```bash
export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
```
O padrão é `2024-12-01-preview` quando a variável não estiver definida.
O padrão é `2024-12-01-preview` quando a variável não está definida.
### Nomes de modelos são nomes de implantação
### Nomes de modelo são nomes de implantação
O Azure OpenAI vincula modelos a implantações. Para solicitações de geração de imagem do Azure
A Azure OpenAI vincula modelos a implantações. Para solicitações de geração de imagens da Azure
roteadas pelo provedor `openai` incluído, o campo `model` no OpenClaw
deve ser o **nome da implantação do Azure** configurado no portal do Azure, não
o id público do modelo da OpenAI.
deve ser o **nome da implantação da Azure** que você configurou no portal da Azure, não
o ID público do modelo da OpenAI.
Se você criar uma implantação chamada `gpt-image-2-prod` que serve `gpt-image-2`:
@ -654,55 +671,53 @@ Se você criar uma implantação chamada `gpt-image-2-prod` que serve `gpt-image
/tool image_generate model=openai/gpt-image-2-prod prompt="A clean poster" size=1024x1024 count=1
```
A mesma regra de nome de implantação se aplica a chamadas de geração de imagem roteadas pelo
A mesma regra de nome de implantação se aplica a chamadas de geração de imagens roteadas pelo
provedor `openai` incluído.
### Disponibilidade regional
A geração de imagem do Azure está disponível atualmente apenas em um subconjunto de regiões
(por exemplo `eastus2`, `swedencentral`, `polandcentral`, `westus3`,
`uaenorth`). Verifique a lista atual de regiões da Microsoft antes de criar uma
A geração de imagens da Azure está atualmente disponível apenas em um subconjunto de regiões
(por exemplo, `eastus2`, `swedencentral`, `polandcentral`, `westus3`,
`uaenorth`). Confira a lista atual de regiões da Microsoft antes de criar uma
implantação e confirme se o modelo específico é oferecido na sua região.
### Diferenças de parâmetros
O Azure OpenAI e a OpenAI pública nem sempre aceitam os mesmos parâmetros de imagem.
O Azure pode rejeitar opções que a OpenAI pública permite (por exemplo, certos
A Azure OpenAI e a OpenAI pública nem sempre aceitam os mesmos parâmetros de imagem.
A Azure pode rejeitar opções que a OpenAI pública permite (por exemplo, certos
valores de `background` em `gpt-image-2`) ou expô-las apenas em versões específicas
do modelo. Essas diferenças vêm do Azure e do modelo subjacente, não do
OpenClaw. Se uma solicitação do Azure falhar com um erro de validação, verifique o
conjunto de parâmetros compatível com sua implantação e versão da API específicas no
portal do Azure.
do modelo. Essas diferenças vêm da Azure e do modelo subjacente, não do
OpenClaw. Se uma solicitação da Azure falhar com um erro de validação, confira o
conjunto de parâmetros compatível com sua implantação e versão de API específicas no
portal da Azure.
<Note>
O Azure OpenAI usa transporte nativo e comportamento compatível, mas não recebe
os cabeçalhos de atribuição ocultos do OpenClaw — consulte o acordeão **Rotas nativas vs compatíveis com OpenAI**
em [Configuração avançada](#advanced-configuration).
A Azure OpenAI usa transporte nativo e comportamento de compatibilidade, mas não recebe
os cabeçalhos ocultos de atribuição do OpenClaw — consulte o acordeão **Rotas nativas vs compatíveis com OpenAI** em [Configuração avançada](#advanced-configuration).
Para tráfego de chat ou Responses no Azure (além da geração de imagem), use o
fluxo de integração inicial ou uma configuração de provedor Azure dedicada — `openai.baseUrl` sozinho
não adota o formato de API/autenticação do Azure. Existe um provedor
`azure-openai-responses/*` separado; consulte
o acordeão Compaction do lado do servidor abaixo.
Para tráfego de chat ou Responses na Azure (além da geração de imagens), use o
fluxo de integração ou uma configuração dedicada de provedor da Azure — apenas `openai.baseUrl`
não adota o formato de API/autenticação da Azure. Existe um provedor separado
`azure-openai-responses/*`; consulte o acordeão de compaction no lado do servidor abaixo.
</Note>
## Configuração avançada
<AccordionGroup>
<Accordion title="Transporte (WebSocket vs SSE)">
O OpenClaw usa WebSocket primeiro, com fallback para SSE (`"auto"`), tanto para `openai/*` quanto para `openai-codex/*`.
O OpenClaw usa WebSocket primeiro com fallback para SSE (`"auto"`) tanto para `openai/*` quanto para `openai-codex/*`.
No modo `"auto"`, o OpenClaw:
- Tenta novamente uma falha inicial de WebSocket antes de voltar para SSE
- Após uma falha, marca o WebSocket como degradado por cerca de 60 segundos e usa SSE durante o resfriamento
- Tenta novamente uma falha inicial de WebSocket antes de recorrer ao SSE
- Após uma falha, marca o WebSocket como degradado por ~60 segundos e usa SSE durante o resfriamento
- Anexa cabeçalhos estáveis de identidade de sessão e turno para novas tentativas e reconexões
- Normaliza contadores de uso (`input_tokens` / `prompt_tokens`) entre variantes de transporte
| Valor | Comportamento |
|-------|----------|
| `"auto"` (padrão) | WebSocket primeiro, fallback para SSE |
| `"sse"` | Forçar apenas SSE |
| `"websocket"` | Forçar apenas WebSocket |
| `"sse"` | Força apenas SSE |
| `"websocket"` | Força apenas WebSocket |
```json5
{
@ -722,8 +737,8 @@ o acordeão Compaction do lado do servidor abaixo.
```
Documentação relacionada da OpenAI:
- [Realtime API com WebSocket](https://platform.openai.com/docs/guides/realtime-websocket)
- [Respostas da API por streaming (SSE)](https://platform.openai.com/docs/guides/streaming-responses)
- [API Realtime com WebSocket](https://platform.openai.com/docs/guides/realtime-websocket)
- [Respostas de API em streaming (SSE)](https://platform.openai.com/docs/guides/streaming-responses)
</Accordion>
@ -753,7 +768,7 @@ o acordeão Compaction do lado do servidor abaixo.
- **Chat/UI:** `/fast status|on|off`
- **Configuração:** `agents.defaults.models["<provider>/<model>"].params.fastMode`
Quando habilitado, o OpenClaw mapeia o modo rápido para processamento prioritário da OpenAI (`service_tier = "priority"`). Valores existentes de `service_tier` são preservados, e o modo rápido não reescreve `reasoning` nem `text.verbosity`.
Quando habilitado, o OpenClaw mapeia o modo rápido para o processamento prioritário da OpenAI (`service_tier = "priority"`). Valores existentes de `service_tier` são preservados, e o modo rápido não reescreve `reasoning` nem `text.verbosity`.
```json5
{
@ -768,13 +783,13 @@ o acordeão Compaction do lado do servidor abaixo.
```
<Note>
Substituições da sessão prevalecem sobre a configuração. Limpar a substituição da sessão na UI de Sessions retorna a sessão ao padrão configurado.
Substituições de sessão prevalecem sobre a configuração. Limpar a substituição de sessão na UI de Sessões retorna a sessão ao padrão configurado.
</Note>
</Accordion>
<Accordion title="Processamento prioritário (service_tier)">
A API da OpenAI expõe processamento prioritário por meio de `service_tier`. Defina por modelo no OpenClaw:
A API da OpenAI expõe processamento prioritário por meio de `service_tier`. Defina-o por modelo no OpenClaw:
```json5
{
@ -791,19 +806,19 @@ o acordeão Compaction do lado do servidor abaixo.
Valores compatíveis: `auto`, `default`, `flex`, `priority`.
<Warning>
`serviceTier` é encaminhado apenas para endpoints nativos da OpenAI (`api.openai.com`) e endpoints nativos do Codex (`chatgpt.com/backend-api`). Se você rotear qualquer um dos provedores por um proxy, o OpenClaw deixa `service_tier` intocado.
`serviceTier` só é encaminhado a endpoints nativos da OpenAI (`api.openai.com`) e endpoints nativos do Codex (`chatgpt.com/backend-api`). Se você rotear qualquer provedor por meio de um proxy, o OpenClaw deixa `service_tier` intocado.
</Warning>
</Accordion>
<Accordion title="Compaction do lado do servidor (Responses API)">
Para modelos OpenAI Responses diretos (`openai/*` em `api.openai.com`), o wrapper de stream Pi-harness do Plugin OpenAI habilita automaticamente a Compaction do lado do servidor:
<Accordion title="Compaction no lado do servidor (API Responses)">
Para modelos OpenAI Responses diretos (`openai/*` em `api.openai.com`), o wrapper de stream Pi-harness do plugin OpenAI habilita automaticamente compaction no lado do servidor:
- Força `store: true` (a menos que a compatibilidade do modelo defina `supportsStore: false`)
- Injeta `context_management: [{ type: "compaction", compact_threshold: ... }]`
- `compact_threshold` padrão: 70% de `contextWindow` (ou `80000` quando indisponível)
Isso se aplica ao caminho integrado do harness Pi e aos hooks do provedor OpenAI usados por execuções incorporadas. O harness nativo do servidor de aplicativo Codex gerencia seu próprio contexto por meio do Codex e é configurado separadamente com `agents.defaults.agentRuntime.id`.
Isso se aplica ao caminho interno do harness Pi e aos hooks do provedor OpenAI usados por execuções incorporadas. O harness nativo do servidor de app Codex gerencia seu próprio contexto por meio do Codex e é configurado separadamente com `agents.defaults.agentRuntime.id`.
<Tabs>
<Tab title="Habilitar explicitamente">
@ -823,7 +838,7 @@ o acordeão Compaction do lado do servidor abaixo.
}
```
</Tab>
<Tab title="Limite personalizado">
<Tab title="Custom threshold">
```json5
{
agents: {
@ -841,7 +856,7 @@ o acordeão Compaction do lado do servidor abaixo.
}
```
</Tab>
<Tab title="Desativar">
<Tab title="Disable">
```json5
{
agents: {
@ -864,8 +879,8 @@ o acordeão Compaction do lado do servidor abaixo.
</Accordion>
<Accordion title="Modo GPT strict-agentic">
Para execuções da família GPT-5 em `openai/*`, o OpenClaw pode usar um contrato de execução embutido mais rigoroso:
<Accordion title="Strict-agentic GPT mode">
Para execuções da família GPT-5 em `openai/*`, o OpenClaw pode usar um contrato de execução incorporado mais rígido:
```json5
{
@ -878,33 +893,33 @@ o acordeão Compaction do lado do servidor abaixo.
```
Com `strict-agentic`, o OpenClaw:
- Não trata mais uma interação apenas com plano como progresso bem-sucedido quando uma ação de ferramenta está disponível
- Repete a interação com um direcionamento para agir agora
- Não trata mais um turno somente de plano como progresso bem-sucedido quando uma ação de ferramenta está disponível
- Tenta novamente o turno com um direcionamento para agir agora
- Habilita automaticamente `update_plan` para trabalhos substanciais
- Expõe um estado bloqueado explícito se o modelo continuar planejando sem agir
<Note>
Limitado apenas a execuções OpenAI e Codex da família GPT-5. Outros provedores e famílias de modelos mais antigas mantêm o comportamento padrão.
Escopo limitado apenas a execuções da família GPT-5 da OpenAI e do Codex. Outros provedores e famílias de modelos mais antigas mantêm o comportamento padrão.
</Note>
</Accordion>
<Accordion title="Rotas nativas vs. compatíveis com OpenAI">
<Accordion title="Rotas nativas vs compatíveis com OpenAI">
O OpenClaw trata endpoints diretos da OpenAI, Codex e Azure OpenAI de forma diferente de proxies `/v1` genéricos compatíveis com OpenAI:
**Rotas nativas** (`openai/*`, Azure OpenAI):
- Mantêm `reasoning: { effort: "none" }` apenas para modelos que dão suporte ao esforço `none` da OpenAI
- Omitem reasoning desabilitado para modelos ou proxies que rejeitam `reasoning.effort: "none"`
- Definem esquemas de ferramentas para o modo estrito por padrão
- Mantêm `reasoning: { effort: "none" }` apenas para modelos que oferecem suporte ao esforço `none` da OpenAI
- Omitem reasoning desativado para modelos ou proxies que rejeitam `reasoning.effort: "none"`
- Definem schemas de ferramentas como modo estrito por padrão
- Anexam cabeçalhos de atribuição ocultos apenas em hosts nativos verificados
- Mantêm a modelagem de solicitação exclusiva da OpenAI (`service_tier`, `store`, compatibilidade de reasoning, dicas de cache de prompt)
- Mantêm a formatação de requisição exclusiva da OpenAI (`service_tier`, `store`, compatibilidade de reasoning, dicas de cache de prompt)
**Rotas proxy/compatíveis:**
- Usam comportamento de compatibilidade mais flexível
- Removem `store` de Completions de payloads `openai-completions` não nativos
- Aceitam JSON avançado de passagem direta em `params.extra_body`/`params.extraBody` para proxies de Completions compatíveis com OpenAI
- Removem `store` de Completions em payloads `openai-completions` não nativos
- Aceitam JSON avançado de passagem direta `params.extra_body`/`params.extraBody` para proxies de Completions compatíveis com OpenAI
- Aceitam `params.chat_template_kwargs` para proxies de Completions compatíveis com OpenAI, como vLLM
- Não forçam esquemas de ferramentas estritos nem cabeçalhos exclusivos de rotas nativas
- Não forçam schemas de ferramentas estritos nem cabeçalhos exclusivos de rotas nativas
O Azure OpenAI usa transporte nativo e comportamento de compatibilidade, mas não recebe os cabeçalhos de atribuição ocultos.
@ -914,10 +929,10 @@ o acordeão Compaction do lado do servidor abaixo.
## Relacionado
<CardGroup cols={2}>
<Card title="Seleção de modelos" href="/pt-BR/concepts/model-providers" icon="layers">
Escolha de provedores, referências de modelos e comportamento de failover.
<Card title="Seleção de modelo" href="/pt-BR/concepts/model-providers" icon="layers">
Escolha de provedores, refs de modelo e comportamento de failover.
</Card>
<Card title="Geração de imagens" href="/pt-BR/tools/image-generation" icon="image">
<Card title="Geração de imagem" href="/pt-BR/tools/image-generation" icon="image">
Parâmetros compartilhados da ferramenta de imagem e seleção de provedor.
</Card>
<Card title="Geração de vídeo" href="/pt-BR/tools/video-generation" icon="video">

300
docs/pt-BR/reference/memory-config.md
View File

@ -1,22 +1,22 @@
---
read_when:
- Você quer configurar provedores de busca na memória ou modelos de embedding
- Você quer configurar o backend QMD
- Você quer configurar provedores de busca de memória ou modelos de embedding
- Você quer configurar o back-end QMD
- Você quer ajustar a busca híbrida, MMR ou o decaimento temporal
- Você quer ativar a indexação de memória multimodal
- Você quer ativar a indexação multimodal de memória
sidebarTitle: Memory config
summary: Todas as opções de configuração para busca na memória, provedores de embeddings, QMD, busca híbrida e indexação multimodal
summary: Todos os controles de configuração para busca de memória, provedores de incorporação, QMD, busca híbrida e indexação multimodal
title: Referência de configuração de memória
x-i18n:
generated_at: "2026-04-30T10:07:16Z"
generated_at: "2026-04-30T16:29:51Z"
model: gpt-5.5
provider: openai
source_hash: fbb21d407f7ec9ef76e68c268138892b12568137735b723579703e535d34b195
source_hash: 58b75751a19afb883fd7646cf5f71859f95bac468b2bfd8cc79db12ae892f70f
source_path: reference/memory-config.md
workflow: 16
---
Esta página lista todos os ajustes de configuração para a pesquisa de memória do OpenClaw. Para visões gerais conceituais, consulte:
Esta página lista todos os controles de configuração para a busca de memória do OpenClaw. Para visões gerais conceituais, consulte:
<CardGroup cols={2}>
<Card title="Visão geral da memória" href="/pt-BR/concepts/memory">
@ -28,37 +28,37 @@ Esta página lista todos os ajustes de configuração para a pesquisa de memóri
<Card title="Mecanismo QMD" href="/pt-BR/concepts/memory-qmd">
Sidecar local-first.
</Card>
<Card title="Pesquisa de memória" href="/pt-BR/concepts/memory-search">
Pipeline de pesquisa e ajustes.
<Card title="Busca de memória" href="/pt-BR/concepts/memory-search">
Pipeline de busca e ajuste.
</Card>
<Card title="Active Memory" href="/pt-BR/concepts/active-memory">
Subagente de memória para sessões interativas.
</Card>
</CardGroup>
Todas as configurações de pesquisa de memória ficam em `agents.defaults.memorySearch` no `openclaw.json`, salvo indicação em contrário.
Todas as configurações de busca de memória ficam em `agents.defaults.memorySearch` no `openclaw.json`, salvo indicação em contrário.
<Note>
Se você está procurando o alternador do recurso **Active Memory** e a configuração do subagente, isso fica em `plugins.entries.active-memory`, em vez de `memorySearch`.
Se você está procurando a alternância do recurso **Active Memory** e a configuração do subagente, isso fica em `plugins.entries.active-memory` em vez de `memorySearch`.
Active Memory usa um modelo de dois portões:
1. o plugin deve estar habilitado e mirar no ID do agente atual
1. o plugin deve estar habilitado e ter como alvo o id do agente atual
2. a solicitação deve ser uma sessão de chat persistente interativa qualificada
Consulte [Active Memory](/pt-BR/concepts/active-memory) para o modelo de ativação, a configuração pertencente ao plugin, a persistência de transcrição e o padrão de implantação segura.
Consulte [Active Memory](/pt-BR/concepts/active-memory) para ver o modelo de ativação, a configuração pertencente ao plugin, a persistência de transcrições e o padrão de implantação segura.
</Note>
---
## Seleção de provedor
| Chave | Tipo | Padrão | Descrição |
| ---------- | --------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Chave | Tipo | Padrão | Descrição |
| ---------- | --------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `provider` | `string` | detectado automaticamente | ID do adaptador de embeddings, como `bedrock`, `deepinfra`, `gemini`, `github-copilot`, `local`, `mistral`, `ollama`, `openai` ou `voyage`; também pode ser um `models.providers.<id>` configurado cujo `api` aponta para um desses adaptadores |
| `model` | `string` | padrão do provedor | Nome do modelo de embeddings |
| `fallback` | `string` | `"none"` | ID do adaptador de fallback quando o primário falha |
| `enabled` | `boolean` | `true` | Habilita ou desabilita a pesquisa de memória |
| `model` | `string` | padrão do provedor | Nome do modelo de embeddings |
| `fallback` | `string` | `"none"` | ID do adaptador de fallback quando o principal falha |
| `enabled` | `boolean` | `true` | Habilita ou desabilita a busca de memória |
### Ordem de detecção automática
@ -87,15 +87,15 @@ Quando `provider` não está definido, o OpenClaw seleciona o primeiro disponív
Selecionado se uma chave da DeepInfra puder ser resolvida.
</Step>
<Step title="bedrock">
Selecionado se a cadeia de credenciais do AWS SDK resolver (função de instância, chaves de acesso, perfil, SSO, identidade web ou configuração compartilhada).
Selecionado se a cadeia de credenciais do AWS SDK for resolvida (função de instância, chaves de acesso, perfil, SSO, identidade web ou configuração compartilhada).
</Step>
</Steps>
`ollama` é compatível, mas não é detectado automaticamente (defina-o explicitamente).
### IDs de provedor personalizados
### IDs de provedores personalizados
`memorySearch.provider` pode apontar para uma entrada personalizada de `models.providers.<id>`. O OpenClaw resolve o proprietário de `api` desse provedor para o adaptador de embeddings, preservando o ID de provedor personalizado para endpoint, autenticação e tratamento de prefixo de modelo. Isso permite que configurações com várias GPUs ou vários hosts dediquem embeddings de memória a um endpoint local específico:
`memorySearch.provider` pode apontar para uma entrada personalizada `models.providers.<id>`. O OpenClaw resolve o proprietário de `api` desse provedor para o adaptador de embeddings, preservando o id do provedor personalizado para tratamento de endpoint, autenticação e prefixo de modelo. Isso permite que configurações multi-GPU ou multi-host dediquem embeddings de memória a um endpoint local específico:
```json5
{
@ -122,21 +122,21 @@ Quando `provider` não está definido, o OpenClaw seleciona o primeiro disponív
### Resolução de chave de API
Embeddings remotos exigem uma chave de API. Bedrock usa a cadeia de credenciais padrão do AWS SDK em vez disso (funções de instância, SSO, chaves de acesso).
Embeddings remotos exigem uma chave de API. Em vez disso, o Bedrock usa a cadeia de credenciais padrão do AWS SDK (funções de instância, SSO, chaves de acesso).
| Provedor | Variável de ambiente | Chave de configuração |
| -------------- | -------------------------------------------------- | ----------------------------------- |
| Bedrock | Cadeia de credenciais da AWS | Nenhuma chave de API necessária |
| DeepInfra | `DEEPINFRA_API_KEY` | `models.providers.deepinfra.apiKey` |
| Gemini | `GEMINI_API_KEY` | `models.providers.google.apiKey` |
| GitHub Copilot | `COPILOT_GITHUB_TOKEN`, `GH_TOKEN`, `GITHUB_TOKEN` | Perfil de autenticação via login do dispositivo |
| GitHub Copilot | `COPILOT_GITHUB_TOKEN`, `GH_TOKEN`, `GITHUB_TOKEN` | Perfil de autenticação via login por dispositivo |
| Mistral | `MISTRAL_API_KEY` | `models.providers.mistral.apiKey` |
| Ollama | `OLLAMA_API_KEY` (placeholder) | -- |
| OpenAI | `OPENAI_API_KEY` | `models.providers.openai.apiKey` |
| Voyage | `VOYAGE_API_KEY` | `models.providers.voyage.apiKey` |
<Note>
O OAuth do Codex cobre apenas chat/conclusões e não atende a solicitações de embeddings.
O OAuth do Codex cobre apenas chat/completions e não atende solicitações de embeddings.
</Note>
---
@ -146,13 +146,13 @@ O OAuth do Codex cobre apenas chat/conclusões e não atende a solicitações de
Para endpoints personalizados compatíveis com OpenAI ou para substituir padrões do provedor:
<ParamField path="remote.baseUrl" type="string">
URL base personalizada da API.
URL base da API personalizada.
</ParamField>
<ParamField path="remote.apiKey" type="string">
Substitui a chave de API.
</ParamField>
<ParamField path="remote.headers" type="object">
Cabeçalhos HTTP extras (mesclados com os padrões do provedor).
Cabeçalhos HTTP adicionais (mesclados com os padrões do provedor).
</ParamField>
```json5
@ -180,7 +180,7 @@ Para endpoints personalizados compatíveis com OpenAI ou para substituir padrõe
<Accordion title="Gemini">
| Chave | Tipo | Padrão | Descrição |
| ---------------------- | -------- | ---------------------- | ------------------------------------------ |
| `model` | `string` | `gemini-embedding-001` | Também aceita `gemini-embedding-2-preview` |
| `model` | `string` | `gemini-embedding-001` | Também oferece suporte a `gemini-embedding-2-preview` |
| `outputDimensionality` | `number` | `3072` | Para Embedding 2: 768, 1536 ou 3072 |
<Warning>
@ -191,8 +191,8 @@ Para endpoints personalizados compatíveis com OpenAI ou para substituir padrõe
<Accordion title="Tipos de entrada compatíveis com OpenAI">
Endpoints de embeddings compatíveis com OpenAI podem optar por campos de solicitação `input_type` específicos do provedor. Isso é útil para modelos de embeddings assimétricos que exigem rótulos diferentes para embeddings de consulta e de documento.
| Chave | Tipo | Padrão | Descrição |
| ------------------- | -------- | ------------ | ----------------------------------------------------- |
| Chave | Tipo | Padrão | Descrição |
| ------------------- | -------- | ---------- | ----------------------------------------------------- |
| `inputType` | `string` | não definido | `input_type` compartilhado para embeddings de consulta e documento |
| `queryInputType` | `string` | não definido | `input_type` no momento da consulta; substitui `inputType` |
| `documentInputType` | `string` | não definido | `input_type` de índice/documento; substitui `inputType` |
@ -216,11 +216,11 @@ Para endpoints personalizados compatíveis com OpenAI ou para substituir padrõe
}
```
Alterar esses valores afeta a identidade do cache de embeddings para indexação em lote do provedor e deve ser seguido por uma reindexação da memória quando o modelo upstream trata os rótulos de forma diferente.
Alterar esses valores afeta a identidade do cache de embeddings para indexação em lote do provedor e deve ser seguido por uma reindexação de memória quando o modelo upstream tratar os rótulos de forma diferente.
</Accordion>
<Accordion title="Bedrock">
Bedrock usa a cadeia de credenciais padrão do AWS SDK — nenhuma chave de API é necessária. Se o OpenClaw roda no EC2 com uma função de instância habilitada para Bedrock, basta definir o provedor e o modelo:
O Bedrock usa a cadeia de credenciais padrão do AWS SDK — nenhuma chave de API é necessária. Se o OpenClaw roda no EC2 com uma função de instância habilitada para Bedrock, basta definir o provedor e o modelo:
```json5
{
@ -235,14 +235,14 @@ Para endpoints personalizados compatíveis com OpenAI ou para substituir padrõe
}
```
| Chave | Tipo | Padrão | Descrição |
| ---------------------- | -------- | ----------------------------- | --------------------------------- |
| Chave | Tipo | Padrão | Descrição |
| ---------------------- | -------- | ----------------------------- | -------------------------------- |
| `model` | `string` | `amazon.titan-embed-text-v2:0` | Qualquer ID de modelo de embeddings do Bedrock |
| `outputDimensionality` | `number` | padrão do modelo | Para Titan V2: 256, 512 ou 1024 |
| `outputDimensionality` | `number` | padrão do modelo | Para Titan V2: 256, 512 ou 1024 |
**Modelos compatíveis** (com detecção de família e padrões de dimensão):
**Modelos compatíveis** (com detecção de família e dimensões padrão):
| ID do modelo | Provedor | Dimensões padrão | Dimensões configuráveis |
| ID do modelo | Provedor | Dimensões padrão | Dimensões configuráveis |
| ------------------------------------------ | ---------- | ---------------- | ----------------------- |
| `amazon.titan-embed-text-v2:0` | Amazon | 1024 | 256, 512, 1024 |
| `amazon.titan-embed-text-v1` | Amazon | 1536 | -- |
@ -262,12 +262,12 @@ Para endpoints personalizados compatíveis com OpenAI ou para substituir padrõe
1. Variáveis de ambiente (`AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`)
2. Cache de token SSO
3. Credenciais de token de identidade web
4. Arquivos de credenciais e configuração compartilhados
4. Arquivos compartilhados de credenciais e configuração
5. Credenciais de metadados do ECS ou EC2
A região é resolvida a partir de `AWS_REGION`, `AWS_DEFAULT_REGION`, do `baseUrl` do provedor `amazon-bedrock`, ou usa `us-east-1` como padrão.
A região é resolvida a partir de `AWS_REGION`, `AWS_DEFAULT_REGION`, o `baseUrl` do provedor `amazon-bedrock`, ou assume `us-east-1` por padrão.
**Permissões IAM:** a função ou o usuário IAM precisa de:
**Permissões IAM:** a função ou usuário IAM precisa de:
```json
{
@ -277,7 +277,7 @@ Para endpoints personalizados compatíveis com OpenAI ou para substituir padrõe
}
```
Para privilégio mínimo, restrinja `InvokeModel` ao modelo específico:
Para privilégio mínimo, limite `InvokeModel` ao modelo específico:
```
arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
@ -285,22 +285,22 @@ Para endpoints personalizados compatíveis com OpenAI ou para substituir padrõe
</Accordion>
<Accordion title="Local (GGUF + node-llama-cpp)">
| Chave | Tipo | Padrão | Descrição |
| --------------------- | ------------------ | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `local.modelPath` | `string` | baixado automaticamente | Caminho para o arquivo de modelo GGUF |
| `local.modelCacheDir` | `string` | padrão do node-llama-cpp | Diretório de cache para modelos baixados |
| `local.contextSize` | `number \| "auto"` | `4096` | Tamanho da janela de contexto para o contexto de embedding. 4096 cobre chunks típicos (128–512 tokens) enquanto limita a VRAM que não é de pesos. Reduza para 1024–2048 em hosts restritos. `"auto"` usa o máximo treinado do modelo — não recomendado para modelos 8B+ (Qwen3-Embedding-8B: 40 960 tokens → ~32 GB de VRAM contra ~8.8 GB em 4096). |
| Chave | Tipo | Padrão | Descrição |
| --------------------- | ------------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `local.modelPath` | `string` | baixado automaticamente | Caminho para o arquivo de modelo GGUF |
| `local.modelCacheDir` | `string` | padrão do node-llama-cpp | Diretório de cache para modelos baixados |
| `local.contextSize` | `number \| "auto"` | `4096` | Tamanho da janela de contexto para o contexto de embeddings. 4096 cobre chunks típicos (128–512 tokens) enquanto limita a VRAM que não é de pesos. Reduza para 1024–2048 em hosts restritos. `"auto"` usa o máximo treinado do modelo — não recomendado para modelos 8B+ (Qwen3-Embedding-8B: 40.960 tokens → ~32 GB de VRAM contra ~8,8 GB em 4096). |
Modelo padrão: `embeddinggemma-300m-qat-Q8_0.gguf` (~0.6 GB, baixado automaticamente). Requer build nativo: `pnpm approve-builds` e depois `pnpm rebuild node-llama-cpp`.
Modelo padrão: `embeddinggemma-300m-qat-Q8_0.gguf` (~0,6 GB, baixado automaticamente). Instalações empacotadas reparam o runtime nativo `node-llama-cpp` por meio de dependências gerenciadas de runtime de Plugin quando `provider: "local"` está configurado. Checkouts do código-fonte ainda exigem aprovação de build nativo: `pnpm approve-builds` e depois `pnpm rebuild node-llama-cpp`.
Use a CLI independente para verificar o mesmo caminho de provider usado pelo Gateway:
Use a CLI autônoma para verificar o mesmo caminho de provedor que o Gateway usa:
```bash
openclaw memory status --deep --agent main
openclaw memory index --force --agent main
```
Se `provider` for `auto`, `local` será selecionado apenas quando `local.modelPath` apontar para um arquivo local existente. Referências de modelo `hf:` e HTTP(S) ainda podem ser usadas explicitamente com `provider: "local"`, mas elas não fazem `auto` selecionar local antes que o modelo esteja disponível no disco.
Se `provider` for `auto`, `local` será selecionado somente quando `local.modelPath` apontar para um arquivo local existente. Referências de modelo `hf:` e HTTP(S) ainda podem ser usadas explicitamente com `provider: "local"`, mas elas não fazem `auto` selecionar local antes que o modelo esteja disponível no disco.
</Accordion>
</AccordionGroup>
@ -308,38 +308,38 @@ Para endpoints personalizados compatíveis com OpenAI ou para substituir padrõe
### Timeout de embedding inline
<ParamField path="sync.embeddingBatchTimeoutSeconds" type="number">
Substitua o timeout para lotes de embedding inline durante a indexação de memória.
Sobrescreve o timeout para lotes de embedding inline durante a indexação de memória.
Quando não definido, usa o padrão do provider: 600 segundos para providers locais/auto-hospedados, como `local`, `ollama` e `lmstudio`, e 120 segundos para providers hospedados. Aumente isso quando lotes de embedding locais limitados por CPU estiverem saudáveis, mas lentos.
Quando não definido, usa o padrão do provedor: 600 segundos para provedores locais/auto-hospedados como `local`, `ollama` e `lmstudio`, e 120 segundos para provedores hospedados. Aumente isso quando lotes de embedding locais limitados por CPU estiverem saudáveis, mas lentos.
</ParamField>
---
## Configuração de pesquisa híbrida
## Configuração de busca híbrida
Tudo em `memorySearch.query.hybrid`:
| Chave | Tipo | Padrão | Descrição |
| --------------------- | --------- | ------ | ---------------------------------------------- |
| `enabled` | `boolean` | `true` | Habilitar pesquisa híbrida BM25 + vetorial |
| `vectorWeight` | `number` | `0.7` | Peso para pontuações vetoriais (0-1) |
| `textWeight` | `number` | `0.3` | Peso para pontuações BM25 (0-1) |
| `candidateMultiplier` | `number` | `4` | Multiplicador do tamanho do pool de candidatos |
| Chave | Tipo | Padrão | Descrição |
| --------------------- | --------- | ------ | --------------------------------- |
| `enabled` | `boolean` | `true` | Habilita busca híbrida BM25 + vetorial |
| `vectorWeight` | `number` | `0.7` | Peso para pontuações vetoriais (0-1) |
| `textWeight` | `number` | `0.3` | Peso para pontuações BM25 (0-1) |
| `candidateMultiplier` | `number` | `4` | Multiplicador do tamanho do conjunto de candidatos |
<Tabs>
<Tab title="MMR (diversidade)">
<Tab title="MMR (diversity)">
| Chave | Tipo | Padrão | Descrição |
| ------------- | --------- | ------- | -------------------------------------- |
| `mmr.enabled` | `boolean` | `false` | Habilitar reclassificação MMR |
| `mmr.lambda` | `number` | `0.7` | 0 = diversidade máx., 1 = relevância máx. |
| `mmr.enabled` | `boolean` | `false` | Habilita reclassificação MMR |
| `mmr.lambda` | `number` | `0.7` | 0 = diversidade máxima, 1 = relevância máxima |
</Tab>
<Tab title="Decaimento temporal (recência)">
<Tab title="Temporal decay (recency)">
| Chave | Tipo | Padrão | Descrição |
| ---------------------------- | --------- | ------ | --------------------------------- |
| `temporalDecay.enabled` | `boolean` | `false` | Habilitar aumento por recência |
| `temporalDecay.enabled` | `boolean` | `false` | Habilita aumento por recência |
| `temporalDecay.halfLifeDays` | `number` | `30` | A pontuação cai pela metade a cada N dias |
Arquivos evergreen (`MEMORY.md`, arquivos sem data em `memory/`) nunca sofrem decaimento.
Arquivos sempre atuais (`MEMORY.md`, arquivos sem data em `memory/`) nunca sofrem decaimento.
</Tab>
</Tabs>
@ -369,9 +369,9 @@ Tudo em `memorySearch.query.hybrid`:
## Caminhos de memória adicionais
| Chave | Tipo | Descrição |
| ------------ | ---------- | --------------------------------------------- |
| `extraPaths` | `string[]` | Diretórios ou arquivos adicionais a indexar |
| Chave | Tipo | Descrição |
| ------------ | ---------- | ------------------------------------------ |
| `extraPaths` | `string[]` | Diretórios ou arquivos adicionais para indexar |
```json5
{
@ -385,9 +385,9 @@ Tudo em `memorySearch.query.hybrid`:
}
```
Os caminhos podem ser absolutos ou relativos ao workspace. Diretórios são verificados recursivamente em busca de arquivos `.md`. O tratamento de symlinks depende do backend ativo: o mecanismo embutido ignora symlinks, enquanto o QMD segue o comportamento do scanner QMD subjacente.
Os caminhos podem ser absolutos ou relativos ao workspace. Diretórios são varridos recursivamente em busca de arquivos `.md`. O tratamento de symlinks depende do backend ativo: o mecanismo integrado ignora symlinks, enquanto o QMD segue o comportamento do scanner QMD subjacente.
Para pesquisa de transcrições entre agentes com escopo de agente, use `agents.list[].memorySearch.qmd.extraCollections` em vez de `memory.qmd.paths`. Essas coleções extras seguem o mesmo formato `{ path, name, pattern? }`, mas são mescladas por agente e podem preservar nomes compartilhados explícitos quando o caminho aponta para fora do workspace atual. Se o mesmo caminho resolvido aparecer tanto em `memory.qmd.paths` quanto em `memorySearch.qmd.extraCollections`, o QMD mantém a primeira entrada e ignora a duplicata.
Para busca de transcrições entre agentes com escopo por agente, use `agents.list[].memorySearch.qmd.extraCollections` em vez de `memory.qmd.paths`. Essas coleções extras seguem o mesmo formato `{ path, name, pattern? }`, mas são mescladas por agente e podem preservar nomes compartilhados explícitos quando o caminho aponta para fora do workspace atual. Se o mesmo caminho resolvido aparecer tanto em `memory.qmd.paths` quanto em `memorySearch.qmd.extraCollections`, o QMD mantém a primeira entrada e ignora a duplicada.
---
@ -395,14 +395,14 @@ Para pesquisa de transcrições entre agentes com escopo de agente, use `agents.
Indexe imagens e áudio junto com Markdown usando Gemini Embedding 2:
| Chave | Tipo | Padrão | Descrição |
| Chave | Tipo | Padrão | Descrição |
| ------------------------- | ---------- | ---------- | -------------------------------------- |
| `multimodal.enabled` | `boolean` | `false` | Habilitar indexação multimodal |
| `multimodal.modalities` | `string[]` | -- | `["image"]`, `["audio"]` ou `["all"]` |
| `multimodal.enabled` | `boolean` | `false` | Habilita indexação multimodal |
| `multimodal.modalities` | `string[]` | -- | `["image"]`, `["audio"]`, ou `["all"]` |
| `multimodal.maxFileBytes` | `number` | `10000000` | Tamanho máximo de arquivo para indexação |
<Note>
Aplica-se apenas a arquivos em `extraPaths`. As raízes de memória padrão continuam somente Markdown. Requer `gemini-embedding-2-preview`. `fallback` deve ser `"none"`.
Aplica-se somente a arquivos em `extraPaths`. As raízes de memória padrão permanecem somente Markdown. Requer `gemini-embedding-2-preview`. `fallback` deve ser `"none"`.
</Note>
Formatos compatíveis: `.jpg`, `.jpeg`, `.png`, `.webp`, `.gif`, `.heic`, `.heif` (imagens); `.mp3`, `.wav`, `.ogg`, `.opus`, `.m4a`, `.aac`, `.flac` (áudio).
@ -411,10 +411,10 @@ Formatos compatíveis: `.jpg`, `.jpeg`, `.png`, `.webp`, `.gif`, `.heic`, `.heif
## Cache de embeddings
| Chave | Tipo | Padrão | Descrição |
| ------------------ | --------- | ------- | ---------------------------------- |
| Chave | Tipo | Padrão | Descrição |
| ------------------ | --------- | ------ | -------------------------------------- |
| `cache.enabled` | `boolean` | `false` | Armazena embeddings de chunks em cache no SQLite |
| `cache.maxEntries` | `number` | `50000` | Máximo de embeddings em cache |
| `cache.maxEntries` | `number` | `50000` | Máximo de embeddings em cache |
Evita gerar embeddings novamente para texto inalterado durante reindexação ou atualizações de transcrições.
@ -422,20 +422,20 @@ Evita gerar embeddings novamente para texto inalterado durante reindexação ou
## Indexação em lote
| Chave | Tipo | Padrão | Descrição |
| ----------------------------- | --------- | ------ | ---------------------------- |
| `remote.nonBatchConcurrency` | `number` | `4` | Embeddings inline paralelos |
| `remote.batch.enabled` | `boolean` | `false` | Ativa API de embeddings em lote |
| `remote.batch.concurrency` | `number` | `2` | Trabalhos em lote paralelos |
| `remote.batch.wait` | `boolean` | `true` | Aguarda a conclusão do lote |
| `remote.batch.pollIntervalMs` | `number` | -- | Intervalo de consulta |
| `remote.batch.timeoutMinutes` | `number` | -- | Tempo limite do lote |
| Chave | Tipo | Padrão | Descrição |
| ----------------------------- | --------- | ------ | ----------------------------- |
| `remote.nonBatchConcurrency` | `number` | `4` | Embeddings inline paralelos |
| `remote.batch.enabled` | `boolean` | `false` | Habilita API de embedding em lote |
| `remote.batch.concurrency` | `number` | `2` | Jobs em lote paralelos |
| `remote.batch.wait` | `boolean` | `true` | Aguarda a conclusão do lote |
| `remote.batch.pollIntervalMs` | `number` | -- | Intervalo de polling |
| `remote.batch.timeoutMinutes` | `number` | -- | Timeout do lote |
Disponível para `openai`, `gemini` e `voyage`. O lote da OpenAI normalmente é o mais rápido e barato para grandes preenchimentos retroativos.
Disponível para `openai`, `gemini` e `voyage`. O lote da OpenAI costuma ser mais rápido e mais barato para grandes backfills.
`remote.nonBatchConcurrency` controla chamadas inline de embedding usadas por provedores locais/auto-hospedados e provedores hospedados quando APIs de lote do provedor não estão ativas. O padrão do Ollama é `1` para indexação sem lote a fim de evitar sobrecarregar hosts locais menores; defina um valor mais alto em máquinas maiores.
`remote.nonBatchConcurrency` controla chamadas de embedding inline usadas por provedores locais/auto-hospedados e provedores hospedados quando as APIs de lote do provedor não estão ativas. Ollama usa como padrão `1` para indexação sem lote para evitar sobrecarregar hosts locais menores; defina um valor mais alto em máquinas maiores.
Isso é separado de `sync.embeddingBatchTimeoutSeconds`, que controla o tempo limite para chamadas inline de embedding.
Isso é separado de `sync.embeddingBatchTimeoutSeconds`, que controla o timeout para chamadas de embedding inline.
---
@ -443,25 +443,25 @@ Isso é separado de `sync.embeddingBatchTimeoutSeconds`, que controla o tempo li
Indexa transcrições de sessão e as expõe via `memory_search`:
| Chave | Tipo | Padrão | Descrição |
| ----------------------------- | ---------- | ----------- | ---------------------------------------------- |
| `experimental.sessionMemory` | `boolean` | `false` | Ativa a indexação de sessões |
| Chave | Tipo | Padrão | Descrição |
| ----------------------------- | ---------- | ------------ | ---------------------------------------- |
| `experimental.sessionMemory` | `boolean` | `false` | Habilita indexação de sessões |
| `sources` | `string[]` | `["memory"]` | Adicione `"sessions"` para incluir transcrições |
| `sync.sessions.deltaBytes` | `number` | `100000` | Limite de bytes para reindexação |
| `sync.sessions.deltaMessages` | `number` | `50` | Limite de mensagens para reindexação |
| `sync.sessions.deltaBytes` | `number` | `100000` | Limite de bytes para reindexação |
| `sync.sessions.deltaMessages` | `number` | `50` | Limite de mensagens para reindexação |
<Warning>
A indexação de sessões é opcional e roda de forma assíncrona. Os resultados podem ficar ligeiramente desatualizados. Os logs de sessão ficam no disco, então trate o acesso ao sistema de arquivos como o limite de confiança.
A indexação de sessões é opcional e executa de forma assíncrona. Os resultados podem ficar ligeiramente desatualizados. Logs de sessão ficam no disco, então trate o acesso ao sistema de arquivos como o limite de confiança.
</Warning>
---
## Aceleração vetorial do SQLite (sqlite-vec)
## Aceleração vetorial SQLite (sqlite-vec)
| Chave | Tipo | Padrão | Descrição |
| ---------------------------- | --------- | ------ | --------------------------------- |
| `store.vector.enabled` | `boolean` | `true` | Usa sqlite-vec para consultas vetoriais |
| `store.vector.extensionPath` | `string` | bundled | Substitui o caminho do sqlite-vec |
| Chave | Tipo | Padrão | Descrição |
| ---------------------------- | --------- | --------- | -------------------------------------- |
| `store.vector.enabled` | `boolean` | `true` | Usa sqlite-vec para consultas vetoriais |
| `store.vector.extensionPath` | `string` | incluído | Sobrescreve o caminho do sqlite-vec |
Quando sqlite-vec não está disponível, o OpenClaw recorre automaticamente à similaridade de cosseno em processo.
@ -469,60 +469,60 @@ Quando sqlite-vec não está disponível, o OpenClaw recorre automaticamente à
## Armazenamento do índice
| Chave | Tipo | Padrão | Descrição |
| --------------------- | -------- | ------------------------------------- | --------------------------------------------- |
| `store.path` | `string` | `~/.openclaw/memory/{agentId}.sqlite` | Local do índice (compatível com o token `{agentId}`) |
| `store.fts.tokenizer` | `string` | `unicode61` | Tokenizador FTS5 (`unicode61` ou `trigram`) |
| Chave | Tipo | Padrão | Descrição |
| --------------------- | -------- | ------------------------------------- | ---------------------------------------------- |
| `store.path` | `string` | `~/.openclaw/memory/{agentId}.sqlite` | Local do índice (compatível com token `{agentId}`) |
| `store.fts.tokenizer` | `string` | `unicode61` | Tokenizador FTS5 (`unicode61` ou `trigram`) |
---
## Configuração do backend QMD
Defina `memory.backend = "qmd"` para ativar. Todas as configurações de QMD ficam em `memory.qmd`:
Defina `memory.backend = "qmd"` para habilitar. Todas as configurações do QMD ficam em `memory.qmd`:
| Chave | Tipo | Padrão | Descrição |
| ------------------------ | --------- | ------- | ----------------------------------------------------------------------------------- |
| `command` | `string` | `qmd` | Caminho do executável QMD; defina um caminho absoluto quando o `PATH` do serviço diferir do seu shell |
| `searchMode` | `string` | `search` | Comando de busca: `search`, `vsearch`, `query` |
| `includeDefaultMemory` | `boolean` | `true` | Indexa automaticamente `MEMORY.md` + `memory/**/*.md` |
| `paths[]` | `array` | -- | Caminhos extras: `{ name, path, pattern? }` |
| `sessions.enabled` | `boolean` | `false` | Indexa transcrições de sessão |
| `sessions.retentionDays` | `number` | -- | Retenção de transcrições |
| `sessions.exportDir` | `string` | -- | Diretório de exportação |
| Chave | Tipo | Padrão | Descrição |
| ------------------------ | --------- | -------- | ---------------------------------------------------------------------------------------------------------- |
| `command` | `string` | `qmd` | Caminho do executável QMD; defina um caminho absoluto quando o `PATH` do serviço diferir do seu interpretador de comandos |
| `searchMode` | `string` | `search` | Comando de busca: `search`, `vsearch`, `query` |
| `includeDefaultMemory` | `boolean` | `true` | Indexar automaticamente `MEMORY.md` + `memory/**/*.md` |
| `paths[]` | `array` | -- | Caminhos extras: `{ name, path, pattern? }` |
| `sessions.enabled` | `boolean` | `false` | Indexar transcrições de sessões |
| `sessions.retentionDays` | `number` | -- | Retenção de transcrições |
| `sessions.exportDir` | `string` | -- | Diretório de exportação |
`searchMode: "search"` é somente lexical/BM25. O OpenClaw não executa sondagens de prontidão de vetores semânticos nem manutenção de embeddings do QMD para esse modo, inclusive durante `memory status --deep`; `vsearch` e `query` continuam exigindo prontidão de vetores e embeddings do QMD.
`searchMode: "search"` é apenas lexical/BM25. O OpenClaw não executa verificações de prontidão de vetores semânticos nem manutenção de embeddings do QMD para esse modo, inclusive durante `memory status --deep`; `vsearch` e `query` continuam exigindo prontidão de vetores e embeddings do QMD.
O OpenClaw prefere as formas atuais de coleção do QMD e de consulta MCP, mas mantém versões mais antigas do QMD funcionando ao tentar flags de padrão de coleção compatíveis e nomes de ferramentas MCP mais antigos quando necessário. Quando o QMD anuncia suporte a vários filtros de coleção, coleções da mesma fonte são pesquisadas com um único processo do QMD; compilações mais antigas do QMD mantêm o caminho de compatibilidade por coleção. Mesma fonte significa que coleções de memória durável são agrupadas, enquanto coleções de transcrições de sessão permanecem em um grupo separado para que a diversificação de fontes ainda tenha as duas entradas.
O OpenClaw prefere a coleção atual do QMD e os formatos de consulta MCP atuais, mas mantém versões mais antigas do QMD funcionando ao tentar flags de padrão de coleção compatíveis e nomes antigos de ferramentas MCP quando necessário. Quando o QMD anuncia suporte a múltiplos filtros de coleção, coleções da mesma fonte são pesquisadas com um único processo QMD; compilações mais antigas do QMD mantêm o caminho de compatibilidade por coleção. Mesma fonte significa que coleções de memória durável são agrupadas, enquanto coleções de transcrições de sessão permanecem em um grupo separado para que a diversificação de fontes ainda tenha ambas as entradas.
<Note>
As substituições de modelo do QMD ficam do lado do QMD, não na configuração do OpenClaw. Se você precisar substituir os modelos do QMD globalmente, defina variáveis de ambiente como `QMD_EMBED_MODEL`, `QMD_RERANK_MODEL` e `QMD_GENERATE_MODEL` no ambiente de runtime do Gateway.
As substituições de modelo do QMD ficam no lado do QMD, não na configuração do OpenClaw. Se você precisar substituir os modelos do QMD globalmente, defina variáveis de ambiente como `QMD_EMBED_MODEL`, `QMD_RERANK_MODEL` e `QMD_GENERATE_MODEL` no ambiente de runtime do Gateway.
</Note>
<AccordionGroup>
<Accordion title="Cronograma de atualização">
| Chave | Tipo | Padrão | Descrição |
| Chave | Tipo | Padrão | Descrição |
| ------------------------- | --------- | ------- | ------------------------------------- |
| `update.interval` | `string` | `5m` | Intervalo de atualização |
| `update.debounceMs` | `number` | `15000` | Debounce de alterações de arquivo |
| `update.onBoot` | `boolean` | `true` | Atualiza quando o gerenciador QMD de longa duração abre; também controla a atualização de inicialização opcional |
| `update.startup` | `string` | `off` | Atualização opcional ao iniciar o Gateway: `off`, `idle` ou `immediate` |
| `update.startupDelayMs` | `number` | `120000` | Atraso antes de a atualização `startup: "idle"` ser executada |
| `update.waitForBootSync` | `boolean` | `false` | Bloqueia a abertura do gerenciador até que a atualização inicial seja concluída |
| `update.embedInterval` | `string` | -- | Cadência separada de embeddings |
| `update.commandTimeoutMs` | `number` | -- | Tempo limite para comandos do QMD |
| `update.updateTimeoutMs` | `number` | -- | Tempo limite para operações de atualização do QMD |
| `update.embedTimeoutMs` | `number` | -- | Tempo limite para operações de embedding do QMD |
| `update.interval` | `string` | `5m` | Intervalo de atualização |
| `update.debounceMs` | `number` | `15000` | Aplicar debounce a alterações de arquivos |
| `update.onBoot` | `boolean` | `true` | Atualizar quando o gerenciador QMD de longa duração abrir; também controla a atualização de inicialização opcional |
| `update.startup` | `string` | `off` | Atualização opcional ao iniciar o gateway: `off`, `idle` ou `immediate` |
| `update.startupDelayMs` | `number` | `120000` | Atraso antes da atualização `startup: "idle"` ser executada |
| `update.waitForBootSync` | `boolean` | `false` | Bloquear a abertura do gerenciador até que sua atualização inicial seja concluída |
| `update.embedInterval` | `string` | -- | Cadência separada de embeddings |
| `update.commandTimeoutMs` | `number` | -- | Tempo limite para comandos QMD |
| `update.updateTimeoutMs` | `number` | -- | Tempo limite para operações de atualização do QMD |
| `update.embedTimeoutMs` | `number` | -- | Tempo limite para operações de embedding do QMD |
</Accordion>
<Accordion title="Limites">
| Chave | Tipo | Padrão | Descrição |
| ------------------------- | -------- | ------- | --------------------------------- |
| `limits.maxResults` | `number` | `6` | Máximo de resultados de pesquisa |
| `limits.maxSnippetChars` | `number` | -- | Limita o tamanho do trecho |
| `limits.maxInjectedChars` | `number` | -- | Limita o total de caracteres injetados |
| `limits.timeoutMs` | `number` | `4000` | Tempo limite da pesquisa |
| Chave | Tipo | Padrão | Descrição |
| ------------------------- | -------- | ------- | -------------------------- |
| `limits.maxResults` | `number` | `6` | Máximo de resultados de busca |
| `limits.maxSnippetChars` | `number` | -- | Limitar comprimento do trecho |
| `limits.maxInjectedChars` | `number` | -- | Limitar total de caracteres injetados |
| `limits.timeoutMs` | `number` | `4000` | Tempo limite da busca |
</Accordion>
<Accordion title="Escopo">
Controla quais sessões podem receber resultados de pesquisa do QMD. Mesmo esquema de [`session.sendPolicy`](/pt-BR/gateway/config-agents#session):
Controla quais sessões podem receber resultados de busca do QMD. Mesmo esquema que [`session.sendPolicy`](/pt-BR/gateway/config-agents#session):
```json5
{
@ -537,24 +537,24 @@ As substituições de modelo do QMD ficam do lado do QMD, não na configuração
}
```
O padrão distribuído permite sessões diretas e de canal, mas ainda nega grupos.
O padrão distribuído permite sessões diretas e de canal, enquanto ainda nega grupos.
O padrão é somente DM. `match.keyPrefix` corresponde à chave de sessão normalizada; `match.rawKeyPrefix` corresponde à chave bruta incluindo `agent:<id>:`.
O padrão é apenas DM. `match.keyPrefix` corresponde à chave de sessão normalizada; `match.rawKeyPrefix` corresponde à chave bruta, incluindo `agent:<id>:`.
</Accordion>
<Accordion title="Citações">
`memory.citations` se aplica a todos os backends:
| Valor | Comportamento |
| ---------------- | ------------------------------------------------- |
| `auto` (padrão) | Inclui o rodapé `Source: <path#line>` em trechos |
| `on` | Sempre inclui o rodapé |
| `off` | Omite o rodapé (o caminho ainda é passado internamente ao agente) |
| Valor | Comportamento |
| ---------------- | --------------------------------------------------- |
| `auto` (padrão) | Incluir rodapé `Source: <path#line>` nos trechos |
| `on` | Sempre incluir rodapé |
| `off` | Omitir rodapé (o caminho ainda é passado internamente ao agente) |
</Accordion>
</AccordionGroup>
As atualizações de inicialização do QMD usam um caminho de subprocesso único durante a inicialização do Gateway. O gerenciador QMD de longa duração ainda controla o observador de arquivos regular e os temporizadores de intervalo quando a pesquisa de memória é aberta para uso interativo.
As atualizações de boot do QMD usam um caminho de subprocesso de execução única durante a inicialização do gateway. O gerenciador QMD de longa duração ainda é responsável pelo observador de arquivos regular e pelos temporizadores de intervalo quando a busca de memória é aberta para uso interativo.
### Exemplo completo de QMD
@ -583,17 +583,17 @@ As atualizações de inicialização do QMD usam um caminho de subprocesso únic
Dreaming é configurado em `plugins.entries.memory-core.config.dreaming`, não em `agents.defaults.memorySearch`.
Dreaming é executado como uma varredura agendada única e usa fases internas light/deep/REM como detalhe de implementação.
Dreaming é executado como uma única varredura agendada e usa fases internas light/deep/REM como detalhe de implementação.
Para comportamento conceitual e comandos de barra, consulte [Dreaming](/pt-BR/concepts/dreaming).
### Configurações do usuário
| Chave | Tipo | Padrão | Descrição |
| ----------- | --------- | ------------- | ---------------------------------------------- |
| `enabled` | `boolean` | `false` | Ativa ou desativa completamente o dreaming |
| Chave | Tipo | Padrão | Descrição |
| ----------- | --------- | ------------- | ------------------------------------------------- |
| `enabled` | `boolean` | `false` | Ativar ou desativar completamente o dreaming |
| `frequency` | `string` | `0 3 * * *` | Cadência cron opcional para a varredura completa de dreaming |
| `model` | `string` | modelo padrão | Substituição opcional do modelo do subagente Dream Diary |
| `model` | `string` | modelo padrão | Substituição opcional do modelo do subagente Dream Diary |
### Exemplo
@ -621,9 +621,9 @@ Para comportamento conceitual e comandos de barra, consulte [Dreaming](/pt-BR/co
<Note>
- Dreaming grava o estado de máquina em `memory/.dreams/`.
- Dreaming grava a saída narrativa legível por humanos em `DREAMS.md` (ou no `dreams.md` existente).
- `dreaming.model` usa o gate de confiança de subagente do Plugin existente; defina `plugins.entries.memory-core.subagent.allowModelOverride: true` antes de ativá-lo.
- O Dream Diary tenta novamente uma vez com o modelo padrão da sessão quando o modelo configurado está indisponível. Falhas de confiança ou allowlist são registradas e não são repetidas silenciosamente.
- Dreaming grava a saída narrativa legível por humanos em `DREAMS.md` (ou em `dreams.md` existente).
- `dreaming.model` usa a porta de confiança de subagente do Plugin existente; defina `plugins.entries.memory-core.subagent.allowModelOverride: true` antes de ativá-lo.
- Dream Diary tenta novamente uma vez com o modelo padrão da sessão quando o modelo configurado está indisponível. Falhas de confiança ou allowlist são registradas em log e não são tentadas novamente silenciosamente.
- A política e os limites das fases light/deep/REM são comportamento interno, não configuração voltada ao usuário.
</Note>
@ -631,5 +631,5 @@ Para comportamento conceitual e comandos de barra, consulte [Dreaming](/pt-BR/co
## Relacionados
- [Referência de configuração](/pt-BR/gateway/configuration-reference)
- [Visão geral de memória](/pt-BR/concepts/memory)
- [Pesquisa de memória](/pt-BR/concepts/memory-search)
- [Visão geral da memória](/pt-BR/concepts/memory)
- [Busca de memória](/pt-BR/concepts/memory-search)

295
docs/pt-BR/reference/session-management-compaction.md
View File

@ -1,43 +1,43 @@
---
read_when:
- Você precisa depurar IDs de sessão, JSONL de transcrições ou campos de sessions.json
- Você está alterando o comportamento de Compaction automática ou adicionando tarefas de manutenção “pré-Compaction”
- Você precisa depurar IDs de sessão, JSONL de transcrição ou campos de sessions.json
- Você está alterando o comportamento de compactação automática ou adicionando manutenção “pré-compactação”
- Você quer implementar limpezas de memória ou turnos silenciosos do sistema
summary: 'Análise aprofundada: armazenamento de sessões + transcrições, ciclo de vida e detalhes internos de (auto)Compaction'
title: Análise aprofundada do gerenciamento de sessões
summary: 'Aprofundamento: armazenamento de sessões + transcrições, ciclo de vida e funcionamento interno de (auto)Compaction'
title: Aprofundamento no gerenciamento de sessões
x-i18n:
generated_at: "2026-04-30T10:07:46Z"
generated_at: "2026-04-30T16:30:03Z"
model: gpt-5.5
provider: openai
source_hash: 1e9785723ebf9b5411440a8f3b2885a50d659f669811ba749c431a2b3aeed700
source_hash: 5a6a7031cebd90d27784a32a0d0378ea9959249389d209f0745395f90b8a0df9
source_path: reference/session-management-compaction.md
workflow: 16
---
OpenClaw gerencia sessões de ponta a ponta nestas áreas:
- **Roteamento de sessão** (como mensagens recebidas são mapeadas para um `sessionKey`)
- **Roteamento de sessão** (como mensagens recebidas são mapeadas para uma `sessionKey`)
- **Armazenamento de sessão** (`sessions.json`) e o que ele rastreia
- **Persistência de transcrição** (`*.jsonl`) e sua estrutura
- **Higiene de transcrição** (ajustes específicos de provedor antes das execuções)
- **Limites de contexto** (janela de contexto versus tokens rastreados)
- **Compaction** (manual e autocompactação) e onde conectar trabalho pré-Compaction
- **Persistência de transcritos** (`*.jsonl`) e sua estrutura
- **Higiene de transcritos** (correções específicas de provedor antes das execuções)
- **Limites de contexto** (janela de contexto vs tokens rastreados)
- **Compaction** (manual e auto-compaction) e onde conectar trabalho pré-compaction
- **Manutenção silenciosa** (gravações de memória que não devem produzir saída visível ao usuário)
Se você quiser uma visão geral de nível mais alto primeiro, comece por:
Se quiser primeiro uma visão geral de nível mais alto, comece com:
- [Gerenciamento de sessão](/pt-BR/concepts/session)
- [Compaction](/pt-BR/concepts/compaction)
- [Visão geral de memória](/pt-BR/concepts/memory)
- [Busca de memória](/pt-BR/concepts/memory-search)
- [Poda de sessão](/pt-BR/concepts/session-pruning)
- [Higiene de transcrição](/pt-BR/reference/transcript-hygiene)
- [Higiene de transcritos](/pt-BR/reference/transcript-hygiene)
---
## Fonte da verdade: o Gateway
OpenClaw é projetado em torno de um único **processo Gateway** que possui o estado da sessão.
O OpenClaw foi projetado em torno de um único **processo Gateway** que é dono do estado de sessão.
- UIs (app macOS, Control UI web, TUI) devem consultar o Gateway para listas de sessões e contagens de tokens.
- No modo remoto, os arquivos de sessão ficam no host remoto; “verificar seus arquivos locais do Mac” não refletirá o que o Gateway está usando.
@ -46,59 +46,59 @@ OpenClaw é projetado em torno de um único **processo Gateway** que possui o es
## Duas camadas de persistência
OpenClaw persiste sessões em duas camadas:
O OpenClaw persiste sessões em duas camadas:
1. **Armazenamento de sessão (`sessions.json`)**
- Mapa chave/valor: `sessionKey -> SessionEntry`
- Pequeno, mutável, seguro de editar (ou excluir entradas)
- Pequeno, mutável, seguro para editar (ou excluir entradas)
- Rastreia metadados de sessão (id da sessão atual, última atividade, alternâncias, contadores de tokens etc.)
2. **Transcrição (`<sessionId>.jsonl`)**
- Transcrição somente anexável com estrutura em árvore (entradas têm `id` + `parentId`)
- Armazena a conversa real + chamadas de ferramentas + resumos de Compaction
- Usada para reconstruir o contexto do modelo para turnos futuros
- Grandes checkpoints de depuração pré-Compaction são ignorados quando a transcrição
ativa excede o limite de tamanho de checkpoint, evitando uma segunda cópia gigante
2. **Transcrito (`<sessionId>.jsonl`)**
- Transcrito somente anexável com estrutura em árvore (entradas têm `id` + `parentId`)
- Armazena a conversa real + chamadas de ferramenta + resumos de Compaction
- Usado para reconstruir o contexto do modelo em turnos futuros
- Grandes checkpoints de depuração pré-Compaction são ignorados quando o transcrito
ativo excede o limite de tamanho de checkpoint, evitando uma segunda cópia gigante
`.checkpoint.*.jsonl`.
---
## Locais em disco
Por agente, no host do Gateway:
Por agente, no host Gateway:
- Armazenamento: `~/.openclaw/agents/<agentId>/sessions/sessions.json`
- Transcrições: `~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl`
- Transcritos: `~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl`
- Sessões de tópico do Telegram: `.../<sessionId>-topic-<threadId>.jsonl`
OpenClaw resolve isso via `src/config/sessions.ts`.
O OpenClaw resolve isso via `src/config/sessions.ts`.
---
## Manutenção do armazenamento e controles de disco
A persistência de sessão tem controles automáticos de manutenção (`session.maintenance`) para `sessions.json`, artefatos de transcrição e arquivos auxiliares de trajetória:
A persistência de sessão tem controles automáticos de manutenção (`session.maintenance`) para `sessions.json`, artefatos de transcrito e sidecars de trajetória:
- `mode`: `warn` (padrão) ou `enforce`
- `pruneAfter`: limite de idade para entradas obsoletas (padrão `30d`)
- `pruneAfter`: corte de idade de entrada obsoleta (padrão `30d`)
- `maxEntries`: limita entradas em `sessions.json` (padrão `500`)
- `resetArchiveRetention`: retenção para arquivos de transcrição `*.reset.<timestamp>` (padrão: igual a `pruneAfter`; `false` desabilita a limpeza)
- `resetArchiveRetention`: retenção para arquivos de transcrito `*.reset.<timestamp>` (padrão: igual a `pruneAfter`; `false` desativa a limpeza)
- `maxDiskBytes`: orçamento opcional do diretório de sessões
- `highWaterBytes`: alvo opcional após a limpeza (padrão `80%` de `maxDiskBytes`)
Gravações normais do Gateway agrupam a limpeza de `maxEntries` para limites de tamanho de produção, então um armazenamento pode exceder brevemente o limite configurado antes que a próxima limpeza de marca d’água alta o regrave de volta para baixo. `openclaw sessions cleanup --enforce` ainda aplica o limite configurado imediatamente.
Gravações normais do Gateway agrupam a limpeza de `maxEntries` para limites de tamanho de produção, então um armazenamento pode exceder brevemente o limite configurado antes que a próxima limpeza de marca alta o regrave para baixo. `openclaw sessions cleanup --enforce` ainda aplica o limite configurado imediatamente.
OpenClaw não cria mais backups automáticos de rotação `sessions.json.bak.*` durante gravações do Gateway. A chave legada `session.maintenance.rotateBytes` é ignorada, e `openclaw doctor --fix` a remove de configurações antigas.
O OpenClaw não cria mais backups automáticos de rotação `sessions.json.bak.*` durante gravações do Gateway. A chave legada `session.maintenance.rotateBytes` é ignorada e `openclaw doctor --fix` a remove de configurações antigas.
Ordem de aplicação para limpeza de orçamento de disco (`mode: "enforce"`):
1. Remova primeiro os artefatos arquivados mais antigos, transcrições órfãs ou trajetórias órfãs.
2. Se ainda estiver acima do alvo, remova as entradas de sessão mais antigas e seus arquivos de transcrição/trajetória.
1. Remova primeiro os artefatos arquivados mais antigos, transcritos órfãos ou trajetórias órfãs.
2. Se ainda estiver acima do alvo, expulse as entradas de sessão mais antigas e seus arquivos de transcrito/trajetória.
3. Continue até que o uso esteja em ou abaixo de `highWaterBytes`.
Em `mode: "warn"`, OpenClaw relata possíveis remoções, mas não modifica o armazenamento/arquivos.
Em `mode: "warn"`, o OpenClaw relata possíveis expulsões, mas não altera o armazenamento/arquivos.
Execute manutenção sob demanda:
Execute a manutenção sob demanda:
```bash
openclaw sessions cleanup --dry-run
@ -109,24 +109,24 @@ openclaw sessions cleanup --enforce
## Sessões Cron e logs de execução
Execuções Cron isoladas também criam entradas de sessão/transcrições, e elas têm controles de retenção dedicados:
Execuções cron isoladas também criam entradas/transcritos de sessão, e elas têm controles dedicados de retenção:
- `cron.sessionRetention` (padrão `24h`) remove sessões antigas de execução Cron isolada do armazenamento de sessões (`false` desabilita).
- `cron.runLog.maxBytes` + `cron.runLog.keepLines` podam arquivos `~/.openclaw/cron/runs/<jobId>.jsonl` (padrões: `2_000_000` bytes e `2000` linhas).
- `cron.sessionRetention` (padrão `24h`) remove sessões antigas de execução cron isolada do armazenamento de sessão (`false` desativa).
- `cron.runLog.maxBytes` + `cron.runLog.keepLines` removem arquivos `~/.openclaw/cron/runs/<jobId>.jsonl` (padrões: `2_000_000` bytes e `2000` linhas).
Quando o Cron força a criação de uma nova sessão de execução isolada, ele sanitiza a entrada de sessão
`cron:<jobId>` anterior antes de gravar a nova linha. Ele carrega preferências seguras
como configurações de pensamento/rápido/detalhado, rótulos e substituições explícitas
de modelo/autenticação selecionadas pelo usuário. Ele descarta contexto ambiente de conversa, como
roteamento de canal/grupo, política de envio ou fila, elevação, origem e vínculo de runtime
ACP, para que uma nova execução isolada não possa herdar entrega obsoleta ou
autoridade de runtime de uma execução mais antiga.
Quando o cron força a criação de uma nova sessão de execução isolada, ele sanitiza a entrada de sessão
`cron:<jobId>` anterior antes de gravar a nova linha. Ele carrega preferências
seguras, como configurações de thinking/fast/verbose, rótulos e substituições explícitas
de modelo/autenticação selecionadas pelo usuário. Ele descarta contexto de conversa ambiente,
como roteamento de canal/grupo, política de envio ou fila, elevação, origem e vínculo de runtime
ACP, para que uma nova execução isolada não possa herdar autoridade obsoleta de entrega ou
runtime de uma execução antiga.
---
## Chaves de sessão (`sessionKey`)
Um `sessionKey` identifica _em qual compartimento de conversa_ você está (roteamento + isolamento).
Uma `sessionKey` identifica _em qual balde de conversa_ você está (roteamento + isolamento).
Padrões comuns:
@ -134,7 +134,7 @@ Padrões comuns:
- Grupo: `agent:<agentId>:<channel>:group:<id>`
- Sala/canal (Discord/Slack): `agent:<agentId>:<channel>:channel:<id>` ou `...:room:<id>`
- Cron: `cron:<job.id>`
- Webhook: `hook:<uuid>` (a menos que substituído)
- Webhook: `hook:<uuid>` (a menos que seja substituído)
As regras canônicas estão documentadas em [/concepts/session](/pt-BR/concepts/session).
@ -142,15 +142,15 @@ As regras canônicas estão documentadas em [/concepts/session](/pt-BR/concepts/
## IDs de sessão (`sessionId`)
Cada `sessionKey` aponta para um `sessionId` atual (o arquivo de transcrição que continua a conversa).
Cada `sessionKey` aponta para uma `sessionId` atual (o arquivo de transcrito que continua a conversa).
Regras práticas:
Regras gerais:
- **Reset** (`/new`, `/reset`) cria um novo `sessionId` para esse `sessionKey`.
- **Reset diário** (padrão 4:00 AM no horário local do host do gateway) cria um novo `sessionId` na próxima mensagem após o limite de reset.
- **Expiração por inatividade** (`session.reset.idleMinutes` ou legado `session.idleMinutes`) cria um novo `sessionId` quando uma mensagem chega após a janela de inatividade. Quando diário + inatividade estão configurados, vence o que expirar primeiro.
- **Eventos do sistema** (Heartbeat, despertares Cron, notificações de exec, escrituração do gateway) podem modificar a linha da sessão, mas não estendem a validade do reset diário/por inatividade. A rolagem de reset descarta avisos de evento do sistema enfileirados para a sessão anterior antes que o prompt novo seja criado.
- **Proteção contra fork do pai da thread** (`session.parentForkMaxTokens`, padrão `100000`) ignora o fork da transcrição pai quando a sessão pai já está grande demais; a nova thread começa limpa. Defina `0` para desabilitar.
- **Redefinição** (`/new`, `/reset`) cria uma nova `sessionId` para essa `sessionKey`.
- **Redefinição diária** (padrão 4:00 AM no horário local do host gateway) cria uma nova `sessionId` na próxima mensagem após o limite de redefinição.
- **Expiração por inatividade** (`session.reset.idleMinutes` ou legado `session.idleMinutes`) cria uma nova `sessionId` quando uma mensagem chega após a janela de inatividade. Quando diária + inatividade estão configuradas, vence o que expirar primeiro.
- **Eventos do sistema** (Heartbeat, despertares cron, notificações exec, contabilidade do gateway) podem alterar a linha da sessão, mas não estendem a atualização de redefinição diária/por inatividade. A troca de redefinição descarta avisos de eventos do sistema enfileirados para a sessão anterior antes que o novo prompt seja construído.
- **Guarda de bifurcação de pai de thread** (`session.parentForkMaxTokens`, padrão `100000`) ignora a bifurcação do transcrito pai quando a sessão pai já está grande demais; a nova thread começa do zero. Defina `0` para desativar.
Detalhe de implementação: a decisão acontece em `initSessionState()` em `src/auto-reply/reply/session.ts`.
@ -162,16 +162,16 @@ O tipo de valor do armazenamento é `SessionEntry` em `src/config/sessions.ts`.
Campos principais (não exaustivo):
- `sessionId`: id da transcrição atual (o nome do arquivo é derivado dele, a menos que `sessionFile` esteja definido)
- `sessionStartedAt`: timestamp de início para o `sessionId` atual; a validade do reset diário
- `sessionId`: id do transcrito atual (o nome do arquivo é derivado disso, a menos que `sessionFile` esteja definido)
- `sessionStartedAt`: timestamp de início da `sessionId` atual; a atualização de redefinição diária
usa isso. Linhas legadas podem derivá-lo do cabeçalho de sessão JSONL.
- `lastInteractionAt`: timestamp da última interação real de usuário/canal; a validade do reset por inatividade
usa isso para que eventos de Heartbeat, Cron e exec não mantenham sessões
vivas. Linhas legadas sem este campo recorrem ao horário de início da sessão recuperado
para validade por inatividade.
- `lastInteractionAt`: timestamp da última interação real de usuário/canal; a atualização de redefinição
por inatividade usa isso para que Heartbeat, cron e eventos exec não mantenham sessões
vivas. Linhas legadas sem este campo recaem para o horário de início de sessão recuperado
para atualização por inatividade.
- `updatedAt`: timestamp da última mutação da linha do armazenamento, usado para listagem, poda e
escrituração. Ele não é a autoridade para validade de reset diário/por inatividade.
- `sessionFile`: substituição opcional explícita do caminho da transcrição
contabilidade. Ele não é a autoridade para a atualização de redefinição diária/por inatividade.
- `sessionFile`: substituição opcional explícita do caminho do transcrito
- `chatType`: `direct | group | room` (ajuda UIs e política de envio)
- `provider`, `subject`, `room`, `space`, `displayName`: metadados para rotulagem de grupo/canal
- Alternâncias:
@ -179,19 +179,19 @@ Campos principais (não exaustivo):
- `sendPolicy` (substituição por sessão)
- Seleção de modelo:
- `providerOverride`, `modelOverride`, `authProfileOverride`
- Contadores de tokens (melhor esforço / dependentes do provedor):
- Contadores de tokens (melhor esforço / dependente do provedor):
- `inputTokens`, `outputTokens`, `totalTokens`, `contextTokens`
- `compactionCount`: quantas vezes a autocompactação foi concluída para esta chave de sessão
- `compactionCount`: com que frequência a auto-compaction foi concluída para esta chave de sessão
- `memoryFlushAt`: timestamp da última descarga de memória pré-Compaction
- `memoryFlushCompactionCount`: contagem de Compaction quando a última descarga foi executada
O armazenamento é seguro de editar, mas o Gateway é a autoridade: ele pode regravar ou reidratar entradas à medida que as sessões são executadas.
É seguro editar o armazenamento, mas o Gateway é a autoridade: ele pode regravar ou reidratar entradas conforme as sessões são executadas.
---
## Estrutura da transcrição (`*.jsonl`)
## Estrutura do transcrito (`*.jsonl`)
As transcrições são gerenciadas pelo `SessionManager` de `@mariozechner/pi-coding-agent`.
Transcritos são gerenciados pelo `SessionManager` de `@mariozechner/pi-coding-agent`.
O arquivo é JSONL:
@ -201,65 +201,66 @@ O arquivo é JSONL:
Tipos de entrada notáveis:
- `message`: mensagens de usuário/assistente/toolResult
- `custom_message`: mensagens injetadas por Plugin que _entram_ no contexto do modelo (podem ficar ocultas da UI)
- `custom`: estado de Plugin que _não_ entra no contexto do modelo
- `compaction`: resumo de Compaction persistido com `firstKeptEntryId` e `tokensBefore`
- `branch_summary`: resumo persistido ao navegar por uma ramificação da árvore
- `custom_message`: mensagens injetadas por extensão que _entram_ no contexto do modelo (podem ficar ocultas da UI)
- `custom`: estado de extensão que _não_ entra no contexto do modelo
- `compaction`: resumo persistido de Compaction com `firstKeptEntryId` e `tokensBefore`
- `branch_summary`: resumo persistido ao navegar por um ramo da árvore
OpenClaw intencionalmente **não** “corrige” transcrições; o Gateway usa `SessionManager` para lê-las/gravá-las.
O OpenClaw intencionalmente **não** “corrige” transcritos; o Gateway usa `SessionManager` para lê-los/gravá-los.
---
## Janelas de contexto versus tokens rastreados
## Janelas de contexto vs tokens rastreados
Dois conceitos diferentes importam:
1. **Janela de contexto do modelo**: limite rígido por modelo (tokens visíveis para o modelo)
1. **Janela de contexto do modelo**: limite rígido por modelo (tokens visíveis ao modelo)
2. **Contadores do armazenamento de sessão**: estatísticas móveis gravadas em `sessions.json` (usadas para /status e dashboards)
Se você está ajustando limites:
Se você estiver ajustando limites:
- A janela de contexto vem do catálogo de modelos (e pode ser substituída via configuração).
- `contextTokens` no armazenamento é um valor de estimativa/relatório em runtime; não o trate como uma garantia estrita.
Para mais, consulte [/token-use](/pt-BR/reference/token-use).
Para saber mais, consulte [/token-use](/pt-BR/reference/token-use).
---
## Compaction: o que é
Compaction resume a conversa mais antiga em uma entrada `compaction` persistida na transcrição e mantém mensagens recentes intactas.
Compaction resume conversas antigas em uma entrada `compaction` persistida no transcrito e mantém mensagens recentes intactas.
Após a Compaction, turnos futuros veem:
- O resumo de Compaction
- O resumo da Compaction
- Mensagens após `firstKeptEntryId`
Compaction é **persistente** (diferente da poda de sessão). Consulte [/concepts/session-pruning](/pt-BR/concepts/session-pruning).
Compaction é **persistente** (ao contrário da poda de sessão). Consulte [/concepts/session-pruning](/pt-BR/concepts/session-pruning).
## Limites de blocos de Compaction e pareamento de ferramentas
## Limites de chunks de Compaction e pareamento de ferramentas
Quando o OpenClaw divide uma transcrição longa em blocos de Compaction, ele mantém
Quando o OpenClaw divide um transcrito longo em chunks de Compaction, ele mantém
chamadas de ferramenta do assistente pareadas com suas entradas `toolResult` correspondentes.
- Se a divisão por proporção de tokens cair entre uma chamada de ferramenta e seu resultado, o OpenClaw
- Se a divisão por participação de tokens cair entre uma chamada de ferramenta e seu resultado, o OpenClaw
desloca o limite para a mensagem de chamada de ferramenta do assistente em vez de separar
o par.
- Se um bloco final de resultados de ferramenta de outra forma empurraria o bloco para além do alvo,
o OpenClaw preserva esse bloco de ferramenta pendente e mantém intacta a cauda não resumida.
- Blocos de chamada de ferramenta abortados/com erro não mantêm uma divisão pendente aberta.
- Se um bloco final de resultado de ferramenta fosse empurrar o chunk acima do alvo,
o OpenClaw preserva esse bloco de ferramenta pendente e mantém a cauda não resumida
intacta.
- Blocos de chamadas de ferramenta abortadas/com erro não mantêm uma divisão pendente aberta.
---
## Quando a autocompactação acontece (runtime Pi)
## Quando a auto-compaction acontece (runtime Pi)
No agente Pi incorporado, a autocompactação é acionada em dois casos:
No agente Pi incorporado, a auto-compaction é acionada em dois casos:
1. **Recuperação de estouro**: o modelo retorna um erro de estouro de contexto
(`request_too_large`, `context length exceeded`, `input exceeds the maximum
number of tokens`, `input token count exceeds the maximum number of input
tokens`, `input is too long for the model`, `ollama error: context length
exceeded` e variantes semelhantes no formato de provedor) → compactar → tentar novamente.
exceeded` e variantes similares no formato do provedor) → compacta → tenta novamente.
2. **Manutenção por limite**: após um turno bem-sucedido, quando:
`contextTokens > contextWindow - reserveTokens`
@ -269,14 +270,28 @@ Onde:
- `contextWindow` é a janela de contexto do modelo
- `reserveTokens` é a folga reservada para prompts + a próxima saída do modelo
Estas são semânticas do runtime Pi (OpenClaw consome os eventos, mas Pi decide quando compactar).
Estas são semânticas de runtime Pi (o OpenClaw consome os eventos, mas o Pi decide quando compactar).
OpenClaw também pode acionar uma Compaction local de pré-verificação antes de abrir a próxima
O OpenClaw também pode acionar uma Compaction local prévia antes de abrir a próxima
execução quando `agents.defaults.compaction.maxActiveTranscriptBytes` está definido e o
arquivo de transcrição ativo atinge esse tamanho. Esta é uma proteção por tamanho de arquivo para custo
de reabertura local, não arquivamento bruto: OpenClaw ainda executa a Compaction semântica normal,
e ela exige `truncateAfterCompaction` para que o resumo compactado possa se tornar uma
nova transcrição sucessora.
arquivo de transcrito ativo atinge esse tamanho. Este é um guarda de tamanho de arquivo para
custo de reabertura local, não arquivamento bruto: o OpenClaw ainda executa a Compaction semântica normal,
e ela requer `truncateAfterCompaction` para que o resumo compactado possa se tornar um
novo transcrito sucessor.
Para execuções embarcadas no Pi, `agents.defaults.compaction.midTurnPrecheck.enabled: true`
adiciona uma proteção opt-in para o ciclo de ferramentas. Depois que um resultado de ferramenta é anexado e antes da
próxima chamada ao modelo, o OpenClaw estima a pressão do prompt usando a mesma lógica de orçamento de
pré-verificação usada no início do turno. Se o contexto não couber mais, a proteção
não faz Compaction dentro do hook `transformContext` do Pi. Ela emite um sinal estruturado de
pré-verificação no meio do turno, interrompe o envio do prompt atual e permite que o
loop de execução externo use o caminho de recuperação existente: truncar resultados de ferramentas grandes demais
quando isso for suficiente, ou acionar o modo de Compaction configurado e tentar novamente. A
opção vem desativada por padrão e funciona com os modos de Compaction `default` e `safeguard`,
incluindo Compaction de safeguard apoiada por provedor.
Isso é independente de `maxActiveTranscriptBytes`: a proteção por tamanho em bytes roda
antes de um turno começar, enquanto a pré-verificação no meio do turno roda depois, no loop de ferramentas embarcado do Pi,
após novos resultados de ferramentas terem sido anexados.
---
@ -294,47 +309,51 @@ As configurações de Compaction do Pi ficam nas configurações do Pi:
}
```
OpenClaw também aplica um limite mínimo de segurança para execuções embutidas:
O OpenClaw também aplica um piso de segurança para execuções embarcadas:
- Se `compaction.reserveTokens < reserveTokensFloor`, o OpenClaw o aumenta.
- O limite mínimo padrão é de `20000` tokens.
- Defina `agents.defaults.compaction.reserveTokensFloor: 0` para desativar o limite mínimo.
- Se ele já estiver mais alto, o OpenClaw não o altera.
- Se `compaction.reserveTokens < reserveTokensFloor`, o OpenClaw aumenta esse valor.
- O piso padrão é de `20000` tokens.
- Defina `agents.defaults.compaction.reserveTokensFloor: 0` para desativar o piso.
- Se ele já estiver mais alto, o OpenClaw não altera.
- O `/compact` manual respeita um `agents.defaults.compaction.keepRecentTokens`
explícito e mantém o ponto de corte da cauda recente do Pi. Sem um orçamento
de manutenção explícito, a Compaction manual continua sendo um checkpoint rígido
e o contexto reconstruído começa a partir do novo resumo.
explícito e mantém o ponto de corte da cauda recente do Pi. Sem um orçamento de retenção explícito,
a Compaction manual continua sendo um checkpoint rígido, e o contexto reconstruído começa a partir
do novo resumo.
- Defina `agents.defaults.compaction.midTurnPrecheck.enabled: true` para executar a
pré-verificação opcional do loop de ferramentas depois de novos resultados de ferramentas e antes da próxima chamada ao modelo. Isso é apenas um acionador; a geração do resumo ainda usa o caminho de
Compaction configurado. Ele é independente de `maxActiveTranscriptBytes`, que é uma
proteção por tamanho em bytes da transcrição ativa no início do turno.
- Defina `agents.defaults.compaction.maxActiveTranscriptBytes` como um valor em bytes ou
uma string como `"20mb"` para executar a Compaction local antes de um turno quando a
transcrição ativa ficar grande. Essa proteção fica ativa somente quando
`truncateAfterCompaction` também está habilitado. Deixe sem definir ou defina `0` para
uma string como `"20mb"` para executar Compaction local antes de um turno quando a transcrição
ativa ficar grande. Essa proteção só fica ativa quando
`truncateAfterCompaction` também está habilitado. Deixe indefinido ou defina `0` para
desativar.
- Quando `agents.defaults.compaction.truncateAfterCompaction` está habilitado,
o OpenClaw rotaciona a transcrição ativa para um JSONL sucessor compactado após a
Compaction. A transcrição completa antiga permanece arquivada e vinculada a partir do
checkpoint de Compaction, em vez de ser reescrita no local.
checkpoint de Compaction, em vez de ser reescrita no próprio arquivo.
Motivo: deixar margem suficiente para “tarefas de manutenção” de vários turnos (como gravações de memória) antes que a Compaction se torne inevitável.
Motivo: deixar espaço suficiente para “tarefas de manutenção” de múltiplos turnos (como gravações de memória) antes que a Compaction se torne inevitável.
Implementação: `ensurePiCompactionReserveTokens()` em `src/agents/pi-settings.ts`
(chamado a partir de `src/agents/pi-embedded-runner.ts`).
---
## Provedores plugáveis de Compaction
## Provedores de Compaction plugáveis
Plugins podem registrar um provedor de Compaction via `registerCompactionProvider()` na API do plugin. Quando `agents.defaults.compaction.provider` é definido como o id de um provedor registrado, a extensão de salvaguarda delega a sumarização a esse provedor em vez do pipeline integrado `summarizeInStages`.
Plugins podem registrar um provedor de Compaction via `registerCompactionProvider()` na API de Plugin. Quando `agents.defaults.compaction.provider` é definido como o id de um provedor registrado, a extensão safeguard delega a sumarização a esse provedor em vez de usar o pipeline embutido `summarizeInStages`.
- `provider`: id de um Plugin provedor de Compaction registrado. Deixe sem definir para a sumarização LLM padrão.
- `provider`: id de um Plugin provedor de Compaction registrado. Deixe indefinido para sumarização LLM padrão.
- Definir um `provider` força `mode: "safeguard"`.
- Os provedores recebem as mesmas instruções de Compaction e a mesma política de preservação de identificadores do caminho integrado.
- A salvaguarda ainda preserva o contexto de sufixo de turnos recentes e turnos divididos após a saída do provedor.
- A sumarização integrada da salvaguarda redestila resumos anteriores com novas mensagens
- Provedores recebem as mesmas instruções de Compaction e a mesma política de preservação de identificadores do caminho embutido.
- O safeguard ainda preserva o contexto de sufixo de turnos recentes e turnos divididos após a saída do provedor.
- A sumarização safeguard embutida redestila resumos anteriores com novas mensagens
em vez de preservar o resumo anterior completo literalmente.
- O modo de salvaguarda habilita auditorias de qualidade do resumo por padrão; defina
- O modo safeguard habilita auditorias de qualidade de resumo por padrão; defina
`qualityGuard.enabled: false` para ignorar o comportamento de tentar novamente em caso de saída malformada.
- Se o provedor falhar ou retornar um resultado vazio, o OpenClaw recorre automaticamente à sumarização LLM integrada.
- Sinais de aborto/timeout são relançados (não engolidos) para respeitar o cancelamento do chamador.
- Se o provedor falhar ou retornar um resultado vazio, o OpenClaw volta automaticamente para a sumarização LLM embutida.
- Sinais de abort/timeout são relançados (não engolidos) para respeitar o cancelamento pelo chamador.
Fonte: `src/plugins/compaction-provider.ts`, `src/agents/pi-hooks/compaction-safeguard.ts`.
@ -353,44 +372,44 @@ Você pode observar a Compaction e o estado da sessão via:
## Manutenção silenciosa (`NO_REPLY`)
O OpenClaw oferece suporte a turnos “silenciosos” para tarefas em segundo plano em que o usuário não deve ver saída intermediária.
O OpenClaw oferece suporte a turnos “silenciosos” para tarefas em segundo plano nas quais o usuário não deve ver saída intermediária.
Convenção:
- O assistente inicia sua saída com o token silencioso exato `NO_REPLY` /
`no_reply` para indicar “não entregar uma resposta ao usuário”.
`no_reply` para indicar “não entregue uma resposta ao usuário”.
- O OpenClaw remove/suprime isso na camada de entrega.
- A supressão por token silencioso exato não diferencia maiúsculas de minúsculas, então `NO_REPLY` e
`no_reply` contam quando a carga inteira é apenas o token silencioso.
- Isso é apenas para turnos reais em segundo plano/sem entrega; não é um atalho para
- Isso é apenas para turnos verdadeiramente em segundo plano/sem entrega; não é um atalho para
solicitações comuns e acionáveis do usuário.
A partir de `2026.1.10`, o OpenClaw também suprime **streaming de rascunho/digitação** quando um
fragmento parcial começa com `NO_REPLY`, para que operações silenciosas não vazem saída
parcial no meio do turno.
chunk parcial começa com `NO_REPLY`, para que operações silenciosas não vazem saída parcial
no meio do turno.
---
## "Flush" de memória pré-Compaction (implementado)
Objetivo: antes que a Compaction automática aconteça, executar um turno agentic silencioso que grave estado durável
Objetivo: antes que a Compaction automática aconteça, executar um turno agêntico silencioso que grave estado durável
em disco (por exemplo, `memory/YYYY-MM-DD.md` no workspace do agente) para que a Compaction não possa
apagar contexto crítico.
O OpenClaw usa a abordagem de **flush pré-limite**:
O OpenClaw usa a abordagem de **flush antes do limiar**:
1. Monitorar o uso de contexto da sessão.
2. Quando ele ultrapassar um “limite suave” (abaixo do limite de Compaction do Pi), executar uma diretiva silenciosa
“gravar memória agora” para o agente.
2. Quando ele cruza um “limiar suave” (abaixo do limiar de Compaction do Pi), executar uma diretiva silenciosa
“grave a memória agora” para o agente.
3. Usar o token silencioso exato `NO_REPLY` / `no_reply` para que o usuário não veja
nada.
Configuração (`agents.defaults.compaction.memoryFlush`):
- `enabled` (padrão: `true`)
- `model` (sobrescrita opcional exata de provedor/modelo para o turno de flush, por exemplo `ollama/qwen3:8b`)
- `model` (substituição opcional exata de provedor/modelo para o turno de flush, por exemplo `ollama/qwen3:8b`)
- `softThresholdTokens` (padrão: `4000`)
- `prompt` (mensagem de usuário para o turno de flush)
- `prompt` (mensagem do usuário para o turno de flush)
- `systemPrompt` (prompt de sistema extra anexado para o turno de flush)
Observações:
@ -398,30 +417,30 @@ Observações:
- O prompt/prompt de sistema padrão inclui uma dica `NO_REPLY` para suprimir
a entrega.
- Quando `model` é definido, o turno de flush usa esse modelo sem herdar a
cadeia de fallback da sessão ativa, para que a manutenção somente local não
recaia silenciosamente em um modelo de conversa pago.
- O flush é executado uma vez por ciclo de Compaction (rastreado em `sessions.json`).
- O flush é executado apenas para sessões Pi embutidas (backends de CLI o ignoram).
cadeia de fallback da sessão ativa, de modo que a manutenção apenas local não faça fallback silencioso
para um modelo de conversa pago.
- O flush roda uma vez por ciclo de Compaction (rastreado em `sessions.json`).
- O flush roda apenas para sessões embarcadas do Pi (backends de CLI o ignoram).
- O flush é ignorado quando o workspace da sessão é somente leitura (`workspaceAccess: "ro"` ou `"none"`).
- Consulte [Memória](/pt-BR/concepts/memory) para o layout de arquivos do workspace e os padrões de gravação.
- Consulte [Memória](/pt-BR/concepts/memory) para o layout de arquivos do workspace e os padrões de escrita.
O Pi também expõe um hook `session_before_compact` na API da extensão, mas hoje a lógica de
flush do OpenClaw fica no lado do Gateway.
O Pi também expõe um hook `session_before_compact` na API da extensão, mas a lógica de
flush do OpenClaw fica no lado do Gateway hoje.
---
## Checklist de solução de problemas
- Chave de sessão errada? Comece com [/concepts/session](/pt-BR/concepts/session) e confirme o `sessionKey` em `/status`.
- Incompatibilidade entre armazenamento e transcrição? Confirme o host do Gateway e o caminho do armazenamento a partir de `openclaw status`.
- Chave de sessão incorreta? Comece com [/concepts/session](/pt-BR/concepts/session) e confirme o `sessionKey` em `/status`.
- Incompatibilidade entre store e transcrição? Confirme o host do Gateway e o caminho do store a partir de `openclaw status`.
- Spam de Compaction? Verifique:
- janela de contexto do modelo (pequena demais)
- configurações de Compaction (`reserveTokens` alto demais para a janela do modelo pode causar Compaction mais cedo)
- inchaço de resultados de ferramentas: habilite/ajuste a poda de sessão
- Turnos silenciosos vazando? Confirme que a resposta começa com `NO_REPLY` (token exato sem diferenciação de maiúsculas/minúsculas) e que você está em uma build que inclui a correção de supressão de streaming.
- Turnos silenciosos vazando? Confirme que a resposta começa com `NO_REPLY` (token exato sem diferenciar maiúsculas/minúsculas) e que você está em uma build que inclui a correção de supressão de streaming.
## Relacionado
## Relacionados
- [Gerenciamento de sessão](/pt-BR/concepts/session)
- [Poda de sessão](/pt-BR/concepts/session-pruning)
- [Motor de contexto](/pt-BR/concepts/context-engine)
- [Mecanismo de contexto](/pt-BR/concepts/context-engine)

141
docs/pt-BR/tools/index.md
View File

@ -3,13 +3,13 @@ read_when:
- Você quer entender quais ferramentas o OpenClaw oferece
- Você precisa configurar, permitir ou negar ferramentas
- Você está decidindo entre ferramentas integradas, Skills e plugins
summary: 'Visão geral das ferramentas e dos plugins do OpenClaw: o que o agente pode fazer e como estendê-lo'
summary: 'Visão geral das ferramentas e plugins do OpenClaw: o que o agente pode fazer e como estendê-lo'
title: Ferramentas e plugins
x-i18n:
generated_at: "2026-04-30T10:11:53Z"
generated_at: "2026-04-30T16:30:08Z"
model: gpt-5.5
provider: openai
source_hash: 62cde740188c224af03b4425c7f6dfca9a12f95603066db5925724fc6a07dcf0
source_hash: 7acfac11669b6f9696a368c08afada8d33e30ac2f452d507f5d1bc36bae367eb
source_path: tools/index.md
workflow: 16
---
@ -20,33 +20,33 @@ mensagens e interage com dispositivos.
## Ferramentas, Skills e plugins
O OpenClaw tem três camadas que trabalham juntas:
O OpenClaw tem três camadas que funcionam em conjunto:
<Steps>
<Step title="Ferramentas são o que o agente chama">
Uma ferramenta é uma função tipada que o agente pode invocar (por exemplo, `exec`, `browser`,
`web_search`, `message`). O OpenClaw inclui um conjunto de **ferramentas integradas** e
`web_search`, `message`). O OpenClaw inclui um conjunto de **ferramentas integradas**, e
plugins podem registrar outras.
O agente vê ferramentas como definições de função estruturadas enviadas para a API do modelo.
O agente vê as ferramentas como definições de função estruturadas enviadas à API do modelo.
</Step>
<Step title="Skills ensinam ao agente quando e como">
Uma skill é um arquivo markdown (`SKILL.md`) injetado no prompt do sistema.
<Step title="Skills ensinam o agente quando e como agir">
Uma Skill é um arquivo markdown (`SKILL.md`) injetado no prompt do sistema.
Skills dão ao agente contexto, restrições e orientação passo a passo para
usar ferramentas de forma eficaz. Skills ficam no seu workspace, em pastas compartilhadas
ou são incluídas dentro de plugins.
usar ferramentas com eficácia. Skills ficam no seu workspace, em pastas compartilhadas
ou são incluídas em plugins.
[Referência de Skills](/pt-BR/tools/skills) | [Criando skills](/pt-BR/tools/creating-skills)
[Referência de Skills](/pt-BR/tools/skills) | [Criando Skills](/pt-BR/tools/creating-skills)
</Step>
<Step title="Plugins empacotam tudo junto">
Um plugin é um pacote que pode registrar qualquer combinação de capacidades:
canais, provedores de modelo, ferramentas, skills, fala, transcrição em tempo real,
voz em tempo real, compreensão de mídia, geração de imagem, geração de vídeo,
busca web, pesquisa web e mais. Alguns plugins são **centrais** (incluídos com
canais, provedores de modelo, ferramentas, Skills, fala, transcrição em tempo real,
voz em tempo real, compreensão de mídia, geração de imagens, geração de vídeos,
busca de páginas web, pesquisa na web e muito mais. Alguns plugins são **centrais** (incluídos com
o OpenClaw), outros são **externos** (publicados no npm pela comunidade).
[Instale e configure plugins](/pt-BR/tools/plugin) | [Crie o seu](/pt-BR/plugins/building-plugins)
@ -56,26 +56,26 @@ O OpenClaw tem três camadas que trabalham juntas:
## Ferramentas integradas
Estas ferramentas são incluídas com o OpenClaw e estão disponíveis sem instalar nenhum plugin:
Estas ferramentas são incluídas no OpenClaw e estão disponíveis sem instalar plugins:
| Ferramenta | O que faz | Página |
| ------------------------------------------ | --------------------------------------------------------------------- | ------------------------------------------------------------ |
| `exec` / `process` | Executa comandos shell, gerencia processos em segundo plano | [Exec](/pt-BR/tools/exec), [Aprovações de Exec](/pt-BR/tools/exec-approvals) |
| `code_execution` | Executa análise Python remota em sandbox | [Execução de Código](/pt-BR/tools/code-execution) |
| `browser` | Controla um navegador Chromium (navegar, clicar, capturar tela) | [Navegador](/pt-BR/tools/browser) |
| `web_search` / `x_search` / `web_fetch` | Pesquisa na web, pesquisa posts do X, busca conteúdo de páginas | [Web](/pt-BR/tools/web), [Busca Web](/pt-BR/tools/web-fetch) |
| `read` / `write` / `edit` | E/S de arquivos no workspace | |
| `apply_patch` | Patches de arquivo com múltiplos hunks | [Aplicar Patch](/pt-BR/tools/apply-patch) |
| `message` | Envia mensagens por todos os canais | [Envio do Agente](/pt-BR/tools/agent-send) |
| `canvas` | Controla Canvas de Node (apresentar, avaliar, snapshot) | |
| `nodes` | Descobre e direciona dispositivos pareados | |
| `cron` / `gateway` | Gerencia tarefas agendadas; inspeciona, aplica patch, reinicia ou atualiza o Gateway | |
| `image` / `image_generate` | Analisa ou gera imagens | [Geração de Imagem](/pt-BR/tools/image-generation) |
| `music_generate` | Gera faixas de música | [Geração de Música](/pt-BR/tools/music-generation) |
| `video_generate` | Gera vídeos | [Geração de Vídeo](/pt-BR/tools/video-generation) |
| `tts` | Conversão pontual de texto em fala | [TTS](/pt-BR/tools/tts) |
| `sessions_*` / `subagents` / `agents_list` | Gerenciamento de sessões, status e orquestração de subagentes | [Subagentes](/pt-BR/tools/subagents) |
| `session_status` | Retorno leve no estilo `/status` e substituição de modelo da sessão | [Ferramentas de Sessão](/pt-BR/concepts/session-tool) |
| Ferramenta | O que ela faz | Página |
| ----------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------ |
| `exec` / `process` | Executar comandos de shell, gerenciar processos em segundo plano | [Exec](/pt-BR/tools/exec), [Aprovações de Exec](/pt-BR/tools/exec-approvals) |
| `code_execution` | Executar análise Python remota em sandbox | [Execução de Código](/pt-BR/tools/code-execution) |
| `browser` | Controlar um navegador Chromium (navegar, clicar, capturar tela) | [Navegador](/pt-BR/tools/browser) |
| `web_search` / `x_search` / `web_fetch` | Pesquisar na web, pesquisar publicações no X, buscar conteúdo de páginas | [Web](/pt-BR/tools/web), [Busca de Página Web](/pt-BR/tools/web-fetch) |
| `read` / `write` / `edit` | E/S de arquivos no workspace | |
| `apply_patch` | Patches de arquivo com múltiplos hunks | [Aplicar Patch](/pt-BR/tools/apply-patch) |
| `message` | Enviar mensagens por todos os canais | [Envio pelo Agente](/pt-BR/tools/agent-send) |
| `canvas` | Controlar node Canvas (apresentar, avaliar, snapshot) | |
| `nodes` | Descobrir e direcionar dispositivos pareados | |
| `cron` / `gateway` | Gerenciar tarefas agendadas; inspecionar, aplicar patches, reiniciar ou atualizar o Gateway | |
| `image` / `image_generate` | Analisar ou gerar imagens | [Geração de Imagens](/pt-BR/tools/image-generation) |
| `music_generate` | Gerar faixas musicais | [Geração de Música](/pt-BR/tools/music-generation) |
| `video_generate` | Gerar vídeos | [Geração de Vídeo](/pt-BR/tools/video-generation) |
| `tts` | Conversão pontual de texto em fala | [TTS](/pt-BR/tools/tts) |
| `sessions_*` / `subagents` / `agents_list` | Gerenciamento de sessões, status e orquestração de subagentes | [Subagentes](/pt-BR/tools/subagents) |
| `session_status` | Retorno leve no estilo `/status` e substituição do modelo da sessão | [Ferramentas de Sessão](/pt-BR/concepts/session-tool) |
Para trabalho com imagens, use `image` para análise e `image_generate` para geração ou edição. Se você direcionar para `openai/*`, `google/*`, `fal/*` ou outro provedor de imagem não padrão, configure primeiro a autenticação/chave de API desse provedor.
@ -84,45 +84,45 @@ Para trabalho com música, use `music_generate`. Se você direcionar para `googl
Para trabalho com vídeo, use `video_generate`. Se você direcionar para `qwen/*` ou outro provedor de vídeo não padrão, configure primeiro a autenticação/chave de API desse provedor.
Para geração de áudio orientada por workflow, use `music_generate` quando um plugin como
ComfyUI o registrar. Isso é separado de `tts`, que é texto em fala.
ComfyUI o registrar. Isso é separado de `tts`, que é texto para fala.
`session_status` é a ferramenta leve de status/retorno no grupo de sessões.
Ela responde a perguntas no estilo `/status` sobre a sessão atual e pode
opcionalmente definir uma substituição de modelo por sessão; `model=default` limpa essa
substituição. Como `/status`, ela pode preencher retrospectivamente contadores esparsos de tokens/cache e o
rótulo do modelo de runtime ativo a partir da entrada mais recente de uso do transcript.
substituição. Como `/status`, ela pode preencher retroativamente contadores esparsos de tokens/cache e o
rótulo do modelo de runtime ativo a partir da entrada de uso mais recente do transcript.
`gateway` é a ferramenta de runtime exclusiva do proprietário para operações de Gateway:
`gateway` é a ferramenta de runtime exclusiva do proprietário para operações do Gateway:
- `config.schema.lookup` para uma subárvore de configuração delimitada por caminho antes de edições
- `config.get` para o snapshot + hash da configuração atual
- `config.schema.lookup` para uma subárvore de configuração com escopo de caminho antes de edições
- `config.get` para o snapshot da configuração atual + hash
- `config.patch` para atualizações parciais de configuração com reinicialização
- `config.apply` apenas para substituição completa de configuração
- `config.apply` apenas para substituição completa da configuração
- `update.run` para autoatualização explícita + reinicialização
Para alterações parciais, prefira `config.schema.lookup` e depois `config.patch`. Use
`config.apply` apenas quando você pretende substituir a configuração inteira.
Para mudanças parciais, prefira `config.schema.lookup` e depois `config.patch`. Use
`config.apply` apenas quando você tiver a intenção de substituir a configuração inteira.
Para documentação de configuração mais ampla, leia [Configuração](/pt-BR/gateway/configuration) e
[Referência de configuração](/pt-BR/gateway/configuration-reference).
A ferramenta também se recusa a alterar `tools.exec.ask` ou `tools.exec.security`;
aliases legados `tools.bash.*` são normalizados para os mesmos caminhos exec protegidos.
aliases legados `tools.bash.*` são normalizados para os mesmos caminhos de exec protegidos.
### Ferramentas fornecidas por plugins
Plugins podem registrar ferramentas adicionais. Alguns exemplos:
- [Diffs](/pt-BR/tools/diffs) — visualizador e renderizador de diffs
- [LLM Task](/pt-BR/tools/llm-task) — etapa LLM somente JSON para saída estruturada
- [Tarefa LLM](/pt-BR/tools/llm-task) — etapa LLM somente JSON para saída estruturada
- [Lobster](/pt-BR/tools/lobster) — runtime de workflow tipado com aprovações retomáveis
- [Geração de Música](/pt-BR/tools/music-generation) — ferramenta `music_generate` compartilhada com provedores baseados em workflow
- [OpenProse](/pt-BR/prose) — orquestração de workflow com markdown em primeiro lugar
- [OpenProse](/pt-BR/prose) — orquestração de workflow markdown-first
- [Tokenjuice](/pt-BR/tools/tokenjuice) — compacta resultados ruidosos das ferramentas `exec` e `bash`
## Configuração de ferramentas
### Listas de permissão e negação
Controle quais ferramentas o agente pode chamar por meio de `tools.allow` / `tools.deny` na
Controle quais ferramentas o agente pode chamar via `tools.allow` / `tools.deny` na
configuração. Negação sempre prevalece sobre permissão.
```json5
@ -134,20 +134,20 @@ configuração. Negação sempre prevalece sobre permissão.
}
```
O OpenClaw falha fechado quando uma allowlist explícita não resolve para nenhuma ferramenta chamável.
O OpenClaw falha de forma fechada quando uma lista de permissões explícita não resolve para nenhuma ferramenta chamável.
Por exemplo, `tools.allow: ["query_db"]` só funciona se um plugin carregado realmente
registrar `query_db`. Se nenhuma ferramenta integrada, plugin ou MCP empacotada corresponder à
allowlist, a execução para antes da chamada ao modelo em vez de continuar como uma
lista de permissões, a execução para antes da chamada ao modelo em vez de continuar como uma
execução somente texto que poderia alucinar resultados de ferramentas.
### Perfis de ferramentas
`tools.profile` define uma allowlist base antes de `allow`/`deny` ser aplicado.
`tools.profile` define uma lista de permissões base antes de `allow`/`deny` ser aplicado.
Substituição por agente: `agents.list[].tools.profile`.
| Perfil | O que inclui |
| Perfil | O que inclui |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `full` | Base irrestrita para acesso mais amplo de comando/controle; igual a deixar `tools.profile` sem definição |
| `full` | Base sem restrições para acesso mais amplo de comando/controle; igual a deixar `tools.profile` indefinido |
| `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `music_generate`, `video_generate` |
| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` |
| `minimal` | Apenas `session_status` |
@ -155,21 +155,25 @@ Substituição por agente: `agents.list[].tools.profile`.
<Note>
`tools.profile: "messaging"` é intencionalmente restrito para agentes focados em canais.
Ele deixa de fora ferramentas mais amplas de comando/controle, como sistema de arquivos, runtime,
navegador, canvas, nós, Cron e controle de Gateway. Use `tools.profile: "full"`
como a base irrestrita para acesso mais amplo de comando/controle e depois reduza o
navegador, canvas, nodes, cron e controle do Gateway. Use `tools.profile: "full"`
como a base sem restrições para acesso mais amplo de comando/controle e, em seguida, reduza o
acesso com `tools.allow` / `tools.deny` quando necessário.
</Note>
`coding` inclui ferramentas web leves (`web_search`, `web_fetch`, `x_search`),
mas não a ferramenta completa de controle de navegador. Automação de navegador pode controlar
sessões reais e perfis conectados, então adicione-a explicitamente com
`tools.alsoAllow: ["browser"]` ou por agente com
mas não a ferramenta completa de controle de navegador. A automação de navegador pode controlar
sessões reais e perfis autenticados, então adicione-a explicitamente com
`tools.alsoAllow: ["browser"]` ou por agente
`agents.list[].tools.alsoAllow: ["browser"]`.
Os perfis `coding` e `messaging` também permitem ferramentas MCP empacotadas configuradas
<Note>
Configurar `tools.exec` ou `tools.fs` em um perfil restritivo (`messaging`, `minimal`) não amplia implicitamente a lista de permissões do perfil. Adicione entradas explícitas em `tools.alsoAllow` (por exemplo, `["exec", "process"]` para exec, ou `["read", "write", "edit"]` para fs) quando você quiser que um perfil restritivo use essas seções configuradas. O OpenClaw registra um aviso de inicialização quando uma seção de configuração está presente sem uma concessão `alsoAllow` correspondente.
</Note>
Os perfis `coding` e `messaging` também permitem ferramentas MCP de bundle configuradas
sob a chave de plugin `bundle-mcp`. Adicione `tools.deny: ["bundle-mcp"]` quando você
quiser que um perfil mantenha suas ferramentas integradas normais, mas oculte todas as ferramentas MCP configuradas.
O perfil `minimal` não inclui ferramentas MCP empacotadas.
quiser que um perfil mantenha seus recursos integrados normais, mas oculte todas as ferramentas MCP configuradas.
O perfil `minimal` não inclui ferramentas MCP de bundle.
Exemplo (superfície de ferramentas mais ampla por padrão):
@ -187,7 +191,7 @@ Use atalhos `group:*` em listas de permissão/negação:
| Grupo | Ferramentas |
| ------------------ | --------------------------------------------------------------------------------------------------------- |
| `group:runtime` | exec, process, code_execution (`bash` é aceito como alias para `exec`) |
| `group:runtime` | exec, process, code_execution (`bash` é aceito como um alias para `exec`) |
| `group:fs` | read, write, edit, apply_patch |
| `group:sessions` | sessions_list, sessions_history, sessions_send, sessions_spawn, sessions_yield, subagents, session_status |
| `group:memory` | memory_search, memory_get |
@ -200,17 +204,18 @@ Use atalhos `group:*` em listas de permissão/negação:
| `group:media` | image, image_generate, music_generate, video_generate, tts |
| `group:openclaw` | Todas as ferramentas integradas do OpenClaw (exclui ferramentas de Plugin) |
`sessions_history` retorna uma visualização de recuperação limitada e filtrada por segurança. Ele remove
tags de raciocínio, estruturas de apoio `<relevant-memories>`, payloads XML
`sessions_history` retorna uma visualização de recuperação limitada e filtrada por segurança. Ela remove
tags de pensamento, estruturas auxiliares de `<relevant-memories>`, cargas XML
de chamadas de ferramenta em texto simples (incluindo `<tool_call>...</tool_call>`,
`<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`,
`<function_calls>...</function_calls>` e blocos de chamadas de ferramenta truncados),
estruturas de apoio de chamadas de ferramenta rebaixadas, tokens vazados de controle de modelo
ASCII/largura total e XML de chamada de ferramenta MiniMax malformado do texto do assistente; em seguida, aplica
redação/truncamento e possíveis placeholders para linhas grandes demais, em vez de atuar
como um despejo bruto da transcrição.
`<function_calls>...</function_calls>` e blocos truncados de chamadas de ferramenta),
estruturas auxiliares rebaixadas de chamadas de ferramenta, tokens de controle
de modelo ASCII/de largura total vazados e XML de chamadas de ferramenta MiniMax
malformado do texto do assistente; em seguida, aplica redação/truncamento e
possíveis marcadores de posição para linhas grandes demais, em vez de agir
como um despejo bruto de transcrição.
### Restrições específicas por provedor
### Restrições específicas de provedor
Use `tools.byProvider` para restringir ferramentas para provedores específicos sem
alterar os padrões globais:

332
docs/pt-BR/tools/subagents.md
View File

@ -1,43 +1,43 @@
---
read_when:
- Você quer trabalho em segundo plano ou paralelo por meio do agente
- Você está alterando a política de `sessions_spawn` ou da ferramenta de subagente
- Você está implementando ou solucionando problemas em sessões de subagentes vinculadas a encadeamentos
- Você quer trabalho em segundo plano ou em paralelo por meio do agente
- Você está alterando sessions_spawn ou a política da ferramenta de subagente
- Você está implementando ou solucionando problemas em sessões de subagentes vinculadas a threads
sidebarTitle: Sub-agents
summary: Gere execuções isoladas de agentes em segundo plano que anunciam os resultados de volta no chat do solicitante
summary: Gere execuções isoladas de agentes em segundo plano que anunciam os resultados de volta ao chat do solicitante
title: Subagentes
x-i18n:
generated_at: "2026-04-30T10:13:11Z"
generated_at: "2026-04-30T16:30:09Z"
model: gpt-5.5
provider: openai
source_hash: 84386ea706873cf9f2ea03261f916c8fb01304999f2d9fa86e037e734a62bf7e
source_hash: c7c46d2c6d9ddac23653dcbfaf20df0ff5be9619035a1b115a3b49fd48fd8280
source_path: tools/subagents.md
workflow: 16
---
Subagentes são execuções de agentes em segundo plano geradas a partir de uma execução de agente existente.
Eles rodam em sua própria sessão (`agent:<agentId>:subagent:<uuid>`) e,
quando terminam, **anunciam** o resultado de volta para o canal de chat
quando terminam, **anunciam** seu resultado de volta ao canal de chat
solicitante. Cada execução de subagente é rastreada como uma
[tarefa em segundo plano](/pt-BR/automation/tasks).
Objetivos principais:
- Paralelizar trabalho de "pesquisa / tarefa longa / ferramenta lenta" sem bloquear a execução principal.
- Manter subagentes isolados por padrão (separação de sessão + sandbox opcional).
- Paralelizar trabalhos de "pesquisa / tarefa longa / ferramenta lenta" sem bloquear a execução principal.
- Manter subagentes isolados por padrão (separação de sessão + sandboxing opcional).
- Manter a superfície de ferramentas difícil de usar incorretamente: subagentes **não** recebem ferramentas de sessão por padrão.
- Dar suporte a profundidade de aninhamento configurável para padrões de orquestrador.
- Oferecer suporte a profundidade de aninhamento configurável para padrões de orquestrador.
<Note>
**Nota de custo:** cada subagente tem seu próprio contexto e uso de tokens por
padrão. Para tarefas pesadas ou repetitivas, defina um modelo mais barato para subagentes
e mantenha seu agente principal em um modelo de maior qualidade. Configure via
`agents.defaults.subagents.model` ou substituições por agente. Quando um filho
realmente precisa do transcript atual do solicitante, o agente pode solicitar
`context: "fork"` nessa geração específica.
realmente precisar da transcrição atual do solicitante, o agente pode solicitar
`context: "fork"` nessa única geração.
</Note>
## Comando slash
## Comando de barra
Use `/subagents` para inspecionar ou controlar execuções de subagentes da **sessão
atual**:
@ -53,14 +53,14 @@ atual**:
```
`/subagents info` mostra metadados da execução (status, carimbos de data/hora, id da sessão,
caminho do transcript, limpeza). Use `sessions_history` para uma visão de recuperação limitada
e filtrada por segurança; inspecione o caminho do transcript no disco quando
precisar do transcript bruto completo.
caminho da transcrição, limpeza). Use `sessions_history` para uma visualização de recuperação delimitada
e filtrada por segurança; inspecione o caminho da transcrição em disco quando você
precisar da transcrição bruta completa.
### Controles de vinculação de thread
### Controles de vinculação de threads
Estes comandos funcionam em canais que dão suporte a vinculações persistentes de thread.
Veja [Canais com suporte a thread](#thread-supporting-channels) abaixo.
Estes comandos funcionam em canais que oferecem suporte a vinculações persistentes de threads.
Veja [Canais compatíveis com threads](#thread-supporting-channels) abaixo.
```text
/focus <subagent-label|session-key|session-id|session-label>
@ -73,40 +73,40 @@ Veja [Canais com suporte a thread](#thread-supporting-channels) abaixo.
### Comportamento de geração
`/subagents spawn` inicia um subagente em segundo plano como um comando de usuário (não um
repasse interno) e envia uma atualização final de conclusão de volta para o
repasse interno) e envia uma atualização final de conclusão de volta ao
chat solicitante quando a execução termina.
<AccordionGroup>
<Accordion title="Conclusão não bloqueante, baseada em envio">
<Accordion title="Non-blocking, push-based completion">
- O comando de geração não bloqueia; ele retorna um id de execução imediatamente.
- Na conclusão, o subagente anuncia uma mensagem de resumo/resultado de volta ao canal de chat solicitante.
- A conclusão é baseada em envio. Depois de gerado, **não** faça polling de `/subagents list`, `sessions_list` ou `sessions_history` em loop só para esperar que termine; inspecione o status apenas sob demanda para depuração ou intervenção.
- Na conclusão, o OpenClaw faz o melhor esforço para fechar abas/processos de navegador rastreados abertos por essa sessão de subagente antes que o fluxo de limpeza do anúncio continue.
- Ao concluir, o subagente anuncia uma mensagem de resumo/resultado de volta ao canal de chat solicitante.
- A conclusão é baseada em push. Depois de gerado, **não** consulte `/subagents list`, `sessions_list` ou `sessions_history` em loop apenas para esperar que ele termine; inspecione o status somente sob demanda para depuração ou intervenção.
- Na conclusão, o OpenClaw tenta fechar da melhor forma as abas/processos de navegador rastreados abertos por essa sessão de subagente antes que o fluxo de limpeza do anúncio continue.
</Accordion>
<Accordion title="Resiliência de entrega para geração manual">
<Accordion title="Manual-spawn delivery resilience">
- O OpenClaw tenta primeiro a entrega direta por `agent` com uma chave de idempotência estável.
- Se a entrega direta falhar, ele recorre ao roteamento por fila.
- Se o roteamento por fila ainda não estiver disponível, o anúncio é tentado novamente com um recuo exponencial curto antes da desistência final.
- A entrega de conclusão mantém a rota resolvida do solicitante: rotas de conclusão vinculadas a thread ou vinculadas a conversa prevalecem quando disponíveis; se a origem da conclusão fornece apenas um canal, o OpenClaw preenche o alvo/conta ausente a partir da rota resolvida da sessão solicitante (`lastChannel` / `lastTo` / `lastAccountId`) para que a entrega direta ainda funcione.
- Se o roteamento por fila ainda não estiver disponível, o anúncio é tentado novamente com um breve recuo exponencial antes da desistência final.
- A entrega de conclusão mantém a rota resolvida do solicitante: rotas de conclusão vinculadas a thread ou a conversa vencem quando disponíveis; se a origem da conclusão fornecer apenas um canal, o OpenClaw preenche o destino/conta ausente a partir da rota resolvida da sessão solicitante (`lastChannel` / `lastTo` / `lastAccountId`) para que a entrega direta ainda funcione.
</Accordion>
<Accordion title="Metadados de transferência de conclusão">
A transferência de conclusão para a sessão solicitante é um contexto interno
gerado em runtime (não texto criado pelo usuário) e inclui:
<Accordion title="Completion handoff metadata">
A transferência de conclusão para a sessão solicitante é contexto interno gerado em tempo de execução
(não texto criado pelo usuário) e inclui:
- `Result` — texto da resposta `assistant` visível mais recente; caso contrário, o texto sanitizado mais recente de tool/toolResult. Execuções terminais com falha não reutilizam texto de resposta capturado.
- `Result` — texto da resposta `assistant` visível mais recente; caso contrário, o texto saneado mais recente de ferramenta/toolResult. Execuções terminadas com falha não reutilizam texto de resposta capturado.
- `Status` — `completed successfully` / `failed` / `timed out` / `unknown`.
- Estatísticas compactas de runtime/tokens.
- Uma instrução de entrega dizendo ao agente solicitante para reescrever em voz normal de assistente (não encaminhar metadados internos brutos).
- Estatísticas compactas de tempo de execução/tokens.
- Uma instrução de entrega dizendo ao agente solicitante para reescrever na voz normal de assistente (não encaminhar metadados internos brutos).
</Accordion>
<Accordion title="Modos e runtime ACP">
<Accordion title="Modes and ACP runtime">
- `--model` e `--thinking` substituem os padrões para essa execução específica.
- Use `info`/`log` para inspecionar detalhes e saída após a conclusão.
- `/subagents spawn` é modo de execução única (`mode: "run"`). Para sessões persistentes vinculadas a thread, use `sessions_spawn` com `thread: true` e `mode: "session"`.
- Para sessões de harness ACP (Claude Code, Gemini CLI, OpenCode ou Codex ACP/acpx explícito), use `sessions_spawn` com `runtime: "acp"` quando a ferramenta anunciar esse runtime. Veja [Modelo de entrega ACP](/pt-BR/tools/acp-agents#delivery-model) ao depurar conclusões ou loops agente-para-agente. Quando o Plugin `codex` estiver habilitado, o controle de chat/thread do Codex deve preferir `/codex ...` em vez de ACP, a menos que o usuário peça explicitamente ACP/acpx.
- O OpenClaw oculta `runtime: "acp"` até que o ACP esteja habilitado, o solicitante não esteja em sandbox, e um Plugin de backend como `acpx` esteja carregado. `runtime: "acp"` espera um id de harness ACP externo, ou uma entrada `agents.list[]` com `runtime.type="acp"`; use o runtime padrão de subagente para agentes de configuração normais do OpenClaw vindos de `agents_list`.
- `/subagents spawn` é o modo de disparo único (`mode: "run"`). Para sessões persistentes vinculadas a thread, use `sessions_spawn` com `thread: true` e `mode: "session"`.
- Para sessões de harness ACP (Claude Code, Gemini CLI, OpenCode ou Codex ACP/acpx explícito), use `sessions_spawn` com `runtime: "acp"` quando a ferramenta anunciar esse runtime. Veja [Modelo de entrega ACP](/pt-BR/tools/acp-agents#delivery-model) ao depurar conclusões ou loops entre agentes. Quando o plugin `codex` estiver habilitado, o controle de chat/thread do Codex deve preferir `/codex ...` em vez de ACP, a menos que o usuário solicite explicitamente ACP/acpx.
- O OpenClaw oculta `runtime: "acp"` até que o ACP esteja habilitado, o solicitante não esteja em sandbox, e um plugin de backend como `acpx` esteja carregado. `runtime: "acp"` espera um id de harness ACP externo, ou uma entrada `agents.list[]` com `runtime.type="acp"`; use o runtime padrão de subagente para agentes normais de configuração do OpenClaw vindos de `agents_list`.
</Accordion>
</AccordionGroup>
@ -114,20 +114,20 @@ chat solicitante quando a execução termina.
## Modos de contexto
Subagentes nativos começam isolados, a menos que o chamador peça explicitamente para bifurcar
o transcript atual.
a transcrição atual.
| Modo | Quando usar | Comportamento |
| Modo | Quando usar | Comportamento |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `isolated` | Pesquisa nova, implementação independente, trabalho com ferramenta lenta ou qualquer coisa que possa ser instruída no texto da tarefa | Cria um transcript filho limpo. Este é o padrão e mantém o uso de tokens mais baixo. |
| `fork` | Trabalho que depende da conversa atual, de resultados anteriores de ferramentas ou de instruções nuançadas já presentes no transcript do solicitante | Ramifica o transcript do solicitante para a sessão filha antes de o filho iniciar. |
| `isolated` | Pesquisa nova, implementação independente, trabalho com ferramenta lenta ou qualquer coisa que possa ser resumida no texto da tarefa | Cria uma transcrição filha limpa. Este é o padrão e mantém o uso de tokens menor. |
| `fork` | Trabalho que depende da conversa atual, resultados anteriores de ferramentas ou instruções sutis já presentes na transcrição solicitante | Ramifica a transcrição solicitante para a sessão filha antes que o filho comece. |
Use `fork` com moderação. Ele é para delegação sensível ao contexto, não um
Use `fork` com moderação. Ele serve para delegação sensível ao contexto, não como
substituto para escrever um prompt de tarefa claro.
## Ferramenta: `sessions_spawn`
Inicia uma execução de subagente com `deliver: false` na faixa global `subagent`,
então executa uma etapa de anúncio e publica a resposta do anúncio no canal de chat
Inicia uma execução de subagente com `deliver: false` na lane global `subagent`,
depois executa uma etapa de anúncio e publica a resposta de anúncio no canal de chat
solicitante.
A disponibilidade depende da política efetiva de ferramentas do chamador. Os perfis `coding` e
@ -140,8 +140,8 @@ sessão para confirmar a lista efetiva de ferramentas.
**Padrões:**
- **Modelo:** herda o chamador, a menos que você defina `agents.defaults.subagents.model` (ou `agents.list[].subagents.model` por agente); um `sessions_spawn.model` explícito ainda prevalece.
- **Thinking:** herda o chamador, a menos que você defina `agents.defaults.subagents.thinking` (ou `agents.list[].subagents.thinking` por agente); um `sessions_spawn.thinking` explícito ainda prevalece.
- **Modelo:** herda do chamador, a menos que você defina `agents.defaults.subagents.model` (ou `agents.list[].subagents.model` por agente); um `sessions_spawn.model` explícito ainda vence.
- **Thinking:** herda do chamador, a menos que você defina `agents.defaults.subagents.thinking` (ou `agents.list[].subagents.thinking` por agente); um `sessions_spawn.thinking` explícito ainda vence.
- **Tempo limite da execução:** se `sessions_spawn.runTimeoutSeconds` for omitido, o OpenClaw usa `agents.defaults.subagents.runTimeoutSeconds` quando definido; caso contrário, recorre a `0` (sem tempo limite).
### Parâmetros da ferramenta
@ -153,10 +153,10 @@ sessão para confirmar a lista efetiva de ferramentas.
Rótulo opcional legível por humanos.
</ParamField>
<ParamField path="agentId" type="string">
Gere sob outro id de agente quando permitido por `subagents.allowAgents`.
Gerar sob outro id de agente quando permitido por `subagents.allowAgents`.
</ParamField>
<ParamField path="runtime" type='"subagent" | "acp"' default="subagent">
`acp` é apenas para harnesses ACP externos (`claude`, `droid`, `gemini`, `opencode` ou Codex ACP/acpx solicitado explicitamente) e para entradas `agents.list[]` cujo `runtime.type` é `acp`.
`acp` é apenas para harnesses ACP externos (`claude`, `droid`, `gemini`, `opencode` ou Codex ACP/acpx solicitado explicitamente) e para entradas `agents.list[]` cujo `runtime.type` seja `acp`.
</ParamField>
<ParamField path="resumeSessionId" type="string">
Somente ACP. Retoma uma sessão de harness ACP existente quando `runtime: "acp"`; ignorado para gerações de subagentes nativos.
@ -177,16 +177,16 @@ sessão para confirmar a lista efetiva de ferramentas.
Quando `true`, solicita vinculação de thread do canal para esta sessão de subagente.
</ParamField>
<ParamField path="mode" type='"run" | "session"' default="run">
Se `thread: true` e `mode` for omitido, o padrão passa a ser `session`. `mode: "session"` exige `thread: true`.
Se `thread: true` e `mode` for omitido, o padrão se torna `session`. `mode: "session"` requer `thread: true`.
</ParamField>
<ParamField path="cleanup" type='"delete" | "keep"' default="keep">
`"delete"` arquiva imediatamente após o anúncio (ainda mantém o transcript via renomeação).
`"delete"` arquiva imediatamente após o anúncio (ainda mantém a transcrição via renomeação).
</ParamField>
<ParamField path="sandbox" type='"inherit" | "require"' default="inherit">
`require` rejeita a geração, a menos que o runtime filho de destino esteja em sandbox.
</ParamField>
<ParamField path="context" type='"isolated" | "fork"' default="isolated">
`fork` ramifica o transcript atual do solicitante para a sessão filha. Apenas subagentes nativos. Use `fork` somente quando o filho precisar do transcript atual.
`fork` ramifica a transcrição atual do solicitante para a sessão filha. Somente subagentes nativos. Use `fork` apenas quando o filho precisar da transcrição atual.
</ParamField>
<Warning>
@ -195,18 +195,18 @@ sessão para confirmar a lista efetiva de ferramentas.
`message`/`sessions_send` a partir da execução gerada.
</Warning>
## Sessões vinculadas a thread
## Sessões vinculadas a threads
Quando vinculações de thread estão habilitadas para um canal, um subagente pode permanecer vinculado
a uma thread para que mensagens subsequentes do usuário nessa thread continuem sendo roteadas para a
Quando vinculações de threads estão habilitadas para um canal, um subagente pode permanecer vinculado
a uma thread para que mensagens de acompanhamento de usuários nessa thread continuem sendo roteadas para a
mesma sessão de subagente.
### Canais com suporte a thread
### Canais compatíveis com threads
**Discord** é atualmente o único canal com suporte. Ele oferece suporte a
sessões persistentes de subagentes vinculadas a thread (`sessions_spawn` com
**Discord** é atualmente o único canal compatível. Ele oferece suporte a
sessões persistentes de subagentes vinculadas a threads (`sessions_spawn` com
`thread: true`), controles manuais de thread (`/focus`, `/unfocus`, `/agents`,
`/session idle`, `/session max-age`) e chaves de adaptador
`/session idle`, `/session max-age`) e chaves do adaptador
`channels.discord.threadBindings.enabled`,
`channels.discord.threadBindings.idleHours`,
`channels.discord.threadBindings.maxAgeHours` e
@ -215,20 +215,20 @@ sessões persistentes de subagentes vinculadas a thread (`sessions_spawn` com
### Fluxo rápido
<Steps>
<Step title="Gerar">
<Step title="Spawn">
`sessions_spawn` com `thread: true` (e opcionalmente `mode: "session"`).
</Step>
<Step title="Vincular">
O OpenClaw cria ou vincula uma thread a esse alvo de sessão no canal ativo.
<Step title="Bind">
O OpenClaw cria ou vincula uma thread a esse destino de sessão no canal ativo.
</Step>
<Step title="Rotear acompanhamentos">
<Step title="Route follow-ups">
Respostas e mensagens de acompanhamento nessa thread são roteadas para a sessão vinculada.
</Step>
<Step title="Inspecionar tempos limite">
Use `/session idle` para inspecionar/atualizar o desfoco automático por inatividade e
<Step title="Inspect timeouts">
Use `/session idle` para inspecionar/atualizar o auto-unfocus por inatividade e
`/session max-age` para controlar o limite rígido.
</Step>
<Step title="Desvincular">
<Step title="Detach">
Use `/unfocus` para desvincular manualmente.
</Step>
</Steps>
@ -237,24 +237,24 @@ sessões persistentes de subagentes vinculadas a thread (`sessions_spawn` com
| Comando | Efeito |
| ------------------ | --------------------------------------------------------------------- |
| `/focus <target>` | Vincula a thread atual (ou cria uma) a um destino de subagente/sessão |
| `/unfocus` | Remove o vínculo da thread vinculada atual |
| `/agents` | Lista execuções ativas e estado de vínculo (`thread:<id>` ou `unbound`) |
| `/session idle` | Inspeciona/atualiza o desfoco automático por inatividade (somente threads vinculadas em foco) |
| `/focus <target>` | Vincula a thread atual (ou cria uma) a um destino de sub-agente/sessão |
| `/unfocus` | Remove a vinculação da thread vinculada atual |
| `/agents` | Lista execuções ativas e o estado de vinculação (`thread:<id>` ou `unbound`) |
| `/session idle` | Inspeciona/atualiza o auto-unfocus por inatividade (somente threads vinculadas em foco) |
| `/session max-age` | Inspeciona/atualiza o limite rígido (somente threads vinculadas em foco) |
### Alternâncias de configuração
### Alternadores de configuração
- **Padrão global:** `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`.
- **Substituição por canal e chaves de vinculação automática ao criar** são específicas do adaptador. Consulte [Canais com suporte a threads](#thread-supporting-channels) acima.
- **Substituição por canal e chaves de auto-vinculação ao criar** são específicas do adaptador. Veja [Canais com suporte a threads](#thread-supporting-channels) acima.
Consulte a [Referência de configuração](/pt-BR/gateway/configuration-reference) e
[Comandos de barra](/pt-BR/tools/slash-commands) para detalhes atuais do adaptador.
Veja a [Referência de configuração](/pt-BR/gateway/configuration-reference) e
[Comandos de barra](/pt-BR/tools/slash-commands) para detalhes atuais dos adaptadores.
### Lista de permissões
<ParamField path="agents.list[].subagents.allowAgents" type="string[]">
Lista de ids de agentes que podem ser direcionados via `agentId` explícito (`["*"]` permite qualquer um). Padrão: somente o agente solicitante. Se você definir uma lista e ainda quiser que o solicitante crie a si mesmo com `agentId`, inclua o id do solicitante na lista.
Lista de IDs de agente que podem ser direcionados via `agentId` explícito (`["*"]` permite qualquer um). Padrão: somente o agente solicitante. Se você definir uma lista e ainda quiser que o solicitante crie a si mesmo com `agentId`, inclua o ID do solicitante na lista.
</ParamField>
<ParamField path="agents.defaults.subagents.allowAgents" type="string[]">
Lista de permissões padrão de agentes de destino usada quando o agente solicitante não define seu próprio `subagents.allowAgents`.
@ -263,32 +263,32 @@ Consulte a [Referência de configuração](/pt-BR/gateway/configuration-referenc
Bloqueia chamadas `sessions_spawn` que omitem `agentId` (força a seleção explícita de perfil). Substituição por agente: `agents.list[].subagents.requireAgentId`.
</ParamField>
Se a sessão solicitante estiver em sandbox, `sessions_spawn` rejeita destinos
que seriam executados sem sandbox.
Se a sessão solicitante estiver em sandbox, `sessions_spawn` rejeitará destinos
que seriam executados fora do sandbox.
### Descoberta
Use `agents_list` para ver quais ids de agentes estão atualmente permitidos para
Use `agents_list` para ver quais IDs de agente estão permitidos no momento para
`sessions_spawn`. A resposta inclui o modelo efetivo de cada agente listado
e metadados de runtime incorporados, para que os chamadores possam distinguir PI, servidor de app do Codex
e metadados de runtime incorporados, para que os chamadores possam distinguir PI, servidor de aplicativo Codex
e outros runtimes nativos configurados.
### Arquivamento automático
### Autoarquivamento
- Sessões de subagente são arquivadas automaticamente após `agents.defaults.subagents.archiveAfterMinutes` (padrão `60`).
- Sessões de sub-agente são arquivadas automaticamente após `agents.defaults.subagents.archiveAfterMinutes` (padrão `60`).
- O arquivamento usa `sessions.delete` e renomeia a transcrição para `*.deleted.<timestamp>` (mesma pasta).
- `cleanup: "delete"` arquiva imediatamente após o anúncio (ainda mantém a transcrição via renomeação).
- O arquivamento automático é de melhor esforço; timers pendentes são perdidos se o Gateway reiniciar.
- `runTimeoutSeconds` **não** arquiva automaticamente; ele apenas interrompe a execução. A sessão permanece até o arquivamento automático.
- O arquivamento automático se aplica igualmente a sessões de profundidade 1 e profundidade 2.
- A limpeza do navegador é separada da limpeza de arquivamento: abas/processos de navegador rastreados são fechados em melhor esforço quando a execução termina, mesmo que o registro de transcrição/sessão seja mantido.
- O autoarquivamento é de melhor esforço; timers pendentes são perdidos se o Gateway reiniciar.
- `runTimeoutSeconds` **não** arquiva automaticamente; ele apenas interrompe a execução. A sessão permanece até o autoarquivamento.
- O autoarquivamento se aplica igualmente a sessões de profundidade 1 e profundidade 2.
- A limpeza do navegador é separada da limpeza de arquivamento: abas/processos de navegador rastreados são fechados em melhor esforço quando a execução termina, mesmo que a transcrição/registro de sessão seja mantido.
## Subagentes aninhados
## Sub-agentes aninhados
Por padrão, subagentes não podem criar seus próprios subagentes
Por padrão, sub-agentes não podem criar seus próprios sub-agentes
(`maxSpawnDepth: 1`). Defina `maxSpawnDepth: 2` para habilitar um nível de
aninhamento — o **padrão de orquestrador**: principal → subagente orquestrador →
subsubagentes trabalhadores.
aninhamento — o **padrão de orquestrador**: principal → sub-agente orquestrador →
sub-sub-agentes trabalhadores.
```json5
{
@ -307,30 +307,30 @@ subsubagentes trabalhadores.
### Níveis de profundidade
| Profundidade | Formato da chave de sessão | Função | Pode criar? |
| Profundidade | Formato da chave de sessão | Função | Pode criar? |
| ----- | -------------------------------------------- | --------------------------------------------- | ---------------------------- |
| 0 | `agent:<id>:main` | Agente principal | Sempre |
| 1 | `agent:<id>:subagent:<uuid>` | Subagente (orquestrador quando profundidade 2 é permitida) | Somente se `maxSpawnDepth >= 2` |
| 2 | `agent:<id>:subagent:<uuid>:subagent:<uuid>` | Subsubagente (trabalhador folha) | Nunca |
| 0 | `agent:<id>:main` | Agente principal | Sempre |
| 1 | `agent:<id>:subagent:<uuid>` | Sub-agente (orquestrador quando profundidade 2 é permitida) | Somente se `maxSpawnDepth >= 2` |
| 2 | `agent:<id>:subagent:<uuid>:subagent:<uuid>` | Sub-sub-agente (trabalhador folha) | Nunca |
### Cadeia de anúncio
Os resultados retornam pela cadeia:
Os resultados fluem de volta pela cadeia:
1. Trabalhador de profundidade 2 termina → anuncia ao seu pai (orquestrador de profundidade 1).
2. Orquestrador de profundidade 1 recebe o anúncio, sintetiza os resultados, termina → anuncia ao principal.
2. Orquestrador de profundidade 1 recebe o anúncio, sintetiza resultados, termina → anuncia ao principal.
3. Agente principal recebe o anúncio e entrega ao usuário.
Cada nível vê apenas anúncios de seus filhos diretos.
<Note>
**Orientação operacional:** inicie o trabalho filho uma vez e espere pelos
eventos de conclusão em vez de criar loops de polling em torno de `sessions_list`,
`sessions_history`, `/subagents list` ou comandos de espera `exec`.
`sessions_list` e `/subagents list` mantêm os relacionamentos de sessão filha
**Orientação operacional:** inicie o trabalho filho uma vez e aguarde eventos
de conclusão em vez de criar loops de sondagem em torno de `sessions_list`,
`sessions_history`, `/subagents list` ou comandos `exec` de espera.
`sessions_list` e `/subagents list` mantêm relacionamentos de sessão filha
focados em trabalho ativo — filhos ativos permanecem anexados, filhos encerrados ficam
visíveis por uma breve janela recente, e links antigos de filhos presentes apenas no armazenamento são
ignorados após sua janela de frescor. Isso impede que metadados antigos de `spawnedBy` /
visíveis por uma janela recente curta, e links de filhos antigos existentes apenas no armazenamento são
ignorados após sua janela de atualização. Isso impede que metadados antigos `spawnedBy` /
`parentSessionKey` ressuscitem filhos fantasma após
reinicialização. Se um evento de conclusão de filho chegar depois de você já ter enviado a
resposta final, o acompanhamento correto é o token silencioso exato
@ -341,8 +341,8 @@ resposta final, o acompanhamento correto é o token silencioso exato
- A função e o escopo de controle são gravados nos metadados da sessão no momento da criação. Isso impede que chaves de sessão planas ou restauradas recuperem acidentalmente privilégios de orquestrador.
- **Profundidade 1 (orquestrador, quando `maxSpawnDepth >= 2`):** recebe `sessions_spawn`, `subagents`, `sessions_list`, `sessions_history` para poder gerenciar seus filhos. Outras ferramentas de sessão/sistema permanecem negadas.
- **Profundidade 1 (folha, quando `maxSpawnDepth == 1`):** sem ferramentas de sessão (comportamento padrão atual).
- **Profundidade 2 (trabalhador folha):** sem ferramentas de sessão — `sessions_spawn` é sempre negado na profundidade 2. Não pode criar mais filhos.
- **Profundidade 1 (folha, quando `maxSpawnDepth == 1`):** nenhuma ferramenta de sessão (comportamento padrão atual).
- **Profundidade 2 (trabalhador folha):** nenhuma ferramenta de sessão — `sessions_spawn` é sempre negado na profundidade 2. Não pode criar mais filhos.
### Limite de criação por agente
@ -352,74 +352,74 @@ a partir de um único orquestrador.
### Parada em cascata
Parar um orquestrador de profundidade 1 interrompe automaticamente todos os seus filhos de profundidade 2:
Interromper um orquestrador de profundidade 1 interrompe automaticamente todos os seus filhos de profundidade 2:
- `/stop` no chat principal interrompe todos os agentes de profundidade 1 e propaga para seus filhos de profundidade 2.
- `/subagents kill <id>` interrompe um subagente específico e propaga para seus filhos.
- `/subagents kill all` interrompe todos os subagentes do solicitante e propaga em cascata.
- `/stop` no chat principal interrompe todos os agentes de profundidade 1 e faz cascata para seus filhos de profundidade 2.
- `/subagents kill <id>` interrompe um sub-agente específico e faz cascata para seus filhos.
- `/subagents kill all` interrompe todos os sub-agentes do solicitante e faz cascata.
## Autenticação
A autenticação de subagente é resolvida por **id de agente**, não por tipo de sessão:
A autenticação de sub-agente é resolvida por **ID de agente**, não por tipo de sessão:
- A chave de sessão do subagente é `agent:<agentId>:subagent:<uuid>`.
- A chave de sessão do sub-agente é `agent:<agentId>:subagent:<uuid>`.
- O armazenamento de autenticação é carregado a partir do `agentDir` desse agente.
- Os perfis de autenticação do agente principal são mesclados como **fallback**; perfis do agente substituem perfis principais em conflitos.
- Os perfis de autenticação do agente principal são mesclados como **fallback**; perfis de agente substituem perfis principais em caso de conflitos.
A mesclagem é aditiva, então perfis principais estão sempre disponíveis como
A mesclagem é aditiva, portanto os perfis principais estão sempre disponíveis como
fallbacks. Autenticação totalmente isolada por agente ainda não é compatível.
## Anúncio
Subagentes retornam resultados por meio de uma etapa de anúncio:
Sub-agentes reportam de volta por meio de uma etapa de anúncio:
- A etapa de anúncio é executada dentro da sessão do subagente (não na sessão do solicitante).
- Se o subagente responder exatamente `ANNOUNCE_SKIP`, nada será publicado.
- Se o texto mais recente do assistente for o token silencioso exato `NO_REPLY` / `no_reply`, a saída do anúncio será suprimida mesmo que progresso visível anterior tenha existido.
- A etapa de anúncio é executada dentro da sessão do sub-agente (não na sessão solicitante).
- Se o sub-agente responder exatamente `ANNOUNCE_SKIP`, nada será publicado.
- Se o texto mais recente do assistente for o token silencioso exato `NO_REPLY` / `no_reply`, a saída de anúncio será suprimida mesmo que tenha havido progresso visível anterior.
A entrega depende da profundidade do solicitante:
- Sessões solicitantes de nível superior usam uma chamada `agent` de acompanhamento com entrega externa (`deliver=true`).
- Sessões de subagente solicitantes aninhadas recebem uma injeção interna de acompanhamento (`deliver=false`) para que o orquestrador possa sintetizar resultados dos filhos dentro da sessão.
- Se uma sessão de subagente solicitante aninhada não existir mais, o OpenClaw recorre ao solicitante dessa sessão quando disponível.
- Sessões solicitantes de nível superior usam uma chamada de acompanhamento `agent` com entrega externa (`deliver=true`).
- Sessões de subagente solicitante aninhadas recebem uma injeção interna de acompanhamento (`deliver=false`) para que o orquestrador possa sintetizar resultados de filhos dentro da sessão.
- Se uma sessão de subagente solicitante aninhada tiver desaparecido, o OpenClaw recorre ao solicitante dessa sessão quando disponível.
Para sessões solicitantes de nível superior, a entrega direta em modo de conclusão primeiro
resolve qualquer rota de conversa/thread vinculada e substituição de hook, depois preenche
campos de destino de canal ausentes a partir da rota armazenada da sessão solicitante.
Isso mantém conclusões no chat/tópico correto mesmo quando a origem da conclusão
campos ausentes de destino de canal a partir da rota armazenada da sessão solicitante.
Isso mantém as conclusões no chat/tópico correto mesmo quando a origem da conclusão
identifica apenas o canal.
A agregação de conclusões de filhos fica restrita à execução atual do solicitante ao
criar descobertas de conclusão aninhadas, impedindo que saídas antigas de filhos de execuções anteriores
A agregação de conclusões de filhos é escopada à execução solicitante atual ao
criar achados de conclusão aninhados, impedindo que saídas de filhos de execuções anteriores
vazem para o anúncio atual. Respostas de anúncio preservam
roteamento de thread/tópico quando disponível nos adaptadores de canal.
### Contexto do anúncio
### Contexto de anúncio
O contexto do anúncio é normalizado para um bloco de evento interno estável:
O contexto de anúncio é normalizado para um bloco de evento interno estável:
| Campo | Fonte |
| Campo | Origem |
| -------------- | ------------------------------------------------------------------------------------------------------------- |
| Origem | `subagent` ou `cron` |
| Ids de sessão | Chave/id da sessão filha |
| Tipo | Tipo de anúncio + rótulo da tarefa |
| IDs de sessão | Chave/ID da sessão filha |
| Tipo | Tipo de anúncio + rótulo da tarefa |
| Status | Derivado do resultado do runtime (`success`, `error`, `timeout` ou `unknown`) — **não** inferido do texto do modelo |
| Conteúdo do resultado | Texto visível mais recente do assistente; caso contrário, texto de ferramenta/toolResult mais recente sanitizado |
| Acompanhamento | Instrução que descreve quando responder vs. permanecer em silêncio |
| Conteúdo do resultado | Texto visível mais recente do assistente; caso contrário, texto de ferramenta/toolResult mais recente higienizado |
| Acompanhamento | Instrução descrevendo quando responder versus permanecer silencioso |
Execuções finais com falha relatam status de falha sem reproduzir o texto de
resposta capturado. Em timeout, se o filho só chegou a chamadas de ferramenta, o anúncio
pode condensar esse histórico em um breve resumo de progresso parcial em vez
de reproduzir a saída bruta da ferramenta.
Execuções terminais com falha relatam status de falha sem reproduzir o texto
de resposta capturado. Em timeout, se o filho só tiver avançado por chamadas de ferramenta, o anúncio
pode condensar esse histórico em um resumo curto de progresso parcial em vez
de reproduzir saída bruta de ferramenta.
### Linha de estatísticas
Payloads de anúncio incluem uma linha de estatísticas ao final (mesmo quando encapsulados):
Payloads de anúncio incluem uma linha de estatísticas no final (mesmo quando encapsulados):
- Runtime (por exemplo, `runtime 5m12s`).
- Uso de tokens (entrada/saída/total).
- Custo estimado quando a precificação do modelo estiver configurada (`models.providers.*.models[].cost`).
- `sessionKey`, `sessionId` e caminho da transcrição para que o agente principal possa buscar o histórico via `sessions_history` ou inspecionar o arquivo no disco.
- Custo estimado quando o preço do modelo está configurado (`models.providers.*.models[].cost`).
- `sessionKey`, `sessionId` e caminho da transcrição para que o agente principal possa buscar o histórico via `sessions_history` ou inspecionar o arquivo em disco.
Metadados internos destinam-se apenas à orquestração; respostas voltadas ao usuário
devem ser reescritas na voz normal do assistente.
@ -428,19 +428,19 @@ devem ser reescritas na voz normal do assistente.
`sessions_history` é o caminho de orquestração mais seguro:
- A recordação do assistente é normalizada primeiro: tags de raciocínio removidas; estruturas `<relevant-memories>` / `<relevant_memories>` removidas; blocos de payload XML de chamada de ferramenta em texto simples (`<tool_call>`, `<function_call>`, `<tool_calls>`, `<function_calls>`) removidos, incluindo payloads truncados que nunca fecham corretamente; estruturas rebaixadas de chamada/resultado de ferramenta e marcadores de contexto histórico removidos; tokens de controle de modelo vazados (`<|assistant|>`, outros ASCII `<|...|>`, largura completa `<｜...｜>`) removidos; XML malformado de chamada de ferramenta do MiniMax removido.
- A lembrança do assistente é normalizada primeiro: tags de pensamento removidas; estrutura de suporte `<relevant-memories>` / `<relevant_memories>` removida; blocos de payload XML de chamadas de ferramenta em texto puro (`<tool_call>`, `<function_call>`, `<tool_calls>`, `<function_calls>`) removidos, incluindo payloads truncados que nunca fecham corretamente; estrutura de chamada/resultado de ferramenta rebaixada e marcadores de contexto histórico removidos; tokens de controle de modelo vazados (`<|assistant|>`, outros ASCII `<|...|>`, largura total `<｜...｜>`) removidos; XML de chamada de ferramenta MiniMax malformado removido.
- Texto semelhante a credenciais/tokens é redigido.
- Blocos longos podem ser truncados.
- Históricos muito grandes podem descartar linhas antigas ou substituir uma linha grande demais por `[sessions_history omitted: message too large]`.
- A inspeção da transcrição bruta no disco é o fallback quando você precisa da transcrição completa byte a byte.
- Históricos muito grandes podem descartar linhas mais antigas ou substituir uma linha grande demais por `[sessions_history omitted: message too large]`.
- A inspeção da transcrição bruta em disco é o fallback quando você precisa da transcrição completa byte a byte.
## Política de ferramentas
Subagentes usam primeiro o mesmo perfil e pipeline de política de ferramentas do agente pai ou
Sub-agentes usam primeiro o mesmo perfil e pipeline de política de ferramentas do agente pai ou
de destino. Depois disso, o OpenClaw aplica a camada de restrição
de subagente.
de sub-agente.
Sem um `tools.profile` restritivo, subagentes recebem **todas as ferramentas, exceto
Sem um `tools.profile` restritivo, sub-agentes recebem **todas as ferramentas exceto
ferramentas de sessão** e ferramentas de sistema:
- `sessions_list`
@ -448,14 +448,14 @@ ferramentas de sessão** e ferramentas de sistema:
- `sessions_send`
- `sessions_spawn`
`sessions_history` permanece também aqui uma visualização de recordação delimitada e sanitizada — ela
não é um despejo bruto da transcrição.
`sessions_history` também permanece uma visualização de lembrança limitada e higienizada aqui — ela
não é um despejo bruto de transcrição.
Quando `maxSpawnDepth >= 2`, subagentes orquestradores de profundidade 1 também
Quando `maxSpawnDepth >= 2`, sub-agentes orquestradores de profundidade 1 também
recebem `sessions_spawn`, `subagents`, `sessions_list` e
`sessions_history` para poderem gerenciar seus filhos.
`sessions_history` para poder gerenciar seus filhos.
### Substituição via configuração
### Substituir via configuração
```json5
{
@ -480,10 +480,10 @@ recebem `sessions_spawn`, `subagents`, `sessions_list` e
```
`tools.subagents.tools.allow` é um filtro final somente de permissão. Ele pode restringir
o conjunto de ferramentas já resolvido, mas não pode **readicionar** uma ferramenta removida
o conjunto de ferramentas já resolvido, mas não pode **adicionar de volta** uma ferramenta removida
por `tools.profile`. Por exemplo, `tools.profile: "coding"` inclui
`web_search`/`web_fetch`, mas não a ferramenta `browser`. Para permitir que
subagentes com perfil de codificação usem automação de browser, adicione browser na
subagentes com perfil de codificação usem automação de navegador, adicione browser na
etapa de perfil:
```json5
@ -496,48 +496,56 @@ etapa de perfil:
```
Use `agents.list[].tools.alsoAllow: ["browser"]` por agente quando apenas um
agente deve receber automação de browser.
agente deve receber automação de navegador.
## Concorrência
Subagentes usam uma faixa de fila dedicada no processo:
Subagentes usam uma faixa de fila dedicada dentro do processo:
- **Nome da faixa:** `subagent`
- **Concorrência:** `agents.defaults.subagents.maxConcurrent` (padrão `8`)
## Vivacidade e recuperação
O OpenClaw não trata a ausência de `endedAt` como prova permanente de que um
subagente ainda está ativo. Execuções sem encerramento mais antigas que a janela de execução obsoleta
OpenClaw não trata a ausência de `endedAt` como prova permanente de que um
subagente ainda está ativo. Execuções sem término mais antigas que a janela de execução obsoleta
deixam de contar como ativas/pendentes em `/subagents list`, resumos de status,
bloqueio de conclusão de descendentes e verificações de concorrência por sessão.
Após uma reinicialização do Gateway, execuções restauradas obsoletas sem encerramento são podadas, a menos que
Depois de uma reinicialização do Gateway, execuções restauradas obsoletas e sem término são podadas, a menos que
a sessão filha esteja marcada como `abortedLastRun: true`. Essas
sessões filhas abortadas por reinicialização permanecem recuperáveis pelo fluxo de recuperação de órfãos de subagentes,
que envia uma mensagem sintética de retomada antes de
sessões filhas abortadas pela reinicialização permanecem recuperáveis pelo fluxo de recuperação de órfãos
de subagente, que envia uma mensagem sintética de retomada antes de
limpar o marcador de abortado.
A recuperação automática após reinicialização é limitada por sessão filha. Se o mesmo
filho de subagente for aceito para recuperação de órfão repetidamente dentro da
janela rápida de reinterrupção, o OpenClaw persiste uma lápide de recuperação nessa
sessão e deixa de retomá-la automaticamente em reinicializações posteriores. Execute
`openclaw tasks maintenance --apply` para reconciliar o registro da tarefa, ou
`openclaw doctor --fix` para limpar flags obsoletas de recuperação abortada em
sessões com lápide.
<Note>
Se a criação de um subagente falhar com Gateway `PAIRING_REQUIRED` /
`scope-upgrade`, verifique o chamador RPC antes de editar o estado de pareamento.
A coordenação interna `sessions_spawn` deve se conectar como
`client.id: "gateway-client"` com `client.mode: "backend"` por autenticação direta
de loopback com token/senha compartilhados; esse caminho não depende da
linha de base de escopo de dispositivo pareado da CLI. Chamadores remotos,
`deviceIdentity` explícito, caminhos explícitos de token de dispositivo e clientes
browser/node ainda precisam de aprovação normal do dispositivo para upgrades de escopo.
de loopback com token compartilhado/senha; esse caminho não depende da
linha de base de escopo de dispositivo pareado da CLI. Chamadores remotos, `deviceIdentity`
explícito, caminhos explícitos de token de dispositivo e clientes browser/node
ainda precisam da aprovação normal do dispositivo para upgrades de escopo.
</Note>
## Interrupção
- Enviar `/stop` no chat solicitante aborta a sessão solicitante e interrompe todas as execuções ativas de subagentes criadas a partir dela, propagando para filhos aninhados.
- Enviar `/stop` no chat solicitante aborta a sessão solicitante e interrompe quaisquer execuções ativas de subagente criadas a partir dela, propagando para filhos aninhados.
- `/subagents kill <id>` interrompe um subagente específico e propaga para seus filhos.
## Limitações
- O anúncio de subagente é **por melhor esforço**. Se o Gateway reiniciar, o trabalho pendente de "anunciar de volta" será perdido.
- Subagentes ainda compartilham os mesmos recursos do processo do Gateway; trate `maxConcurrent` como uma válvula de segurança.
- O anúncio de subagente é **de melhor esforço**. Se o gateway reiniciar, o trabalho pendente de "anunciar de volta" será perdido.
- Subagentes ainda compartilham os mesmos recursos do processo do gateway; trate `maxConcurrent` como uma válvula de segurança.
- `sessions_spawn` é sempre não bloqueante: ele retorna `{ status: "accepted", runId, childSessionKey }` imediatamente.
- O contexto de subagente injeta apenas `AGENTS.md` + `TOOLS.md` (sem `SOUL.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md` ou `BOOTSTRAP.md`).
- A profundidade máxima de aninhamento é 5 (intervalo de `maxSpawnDepth`: 1–5). A profundidade 2 é recomendada para a maioria dos casos de uso.

135
docs/pt-BR/tools/thinking.md
View File

@ -1,61 +1,62 @@
---
read_when:
- Ajustar a análise sintática ou os padrões das diretivas thinking, fast-mode ou verbose
summary: Sintaxe de diretiva para /think, /fast, /verbose, /trace e visibilidade do raciocínio
- Ajuste da análise ou dos padrões das diretivas thinking, fast-mode ou verbose
summary: Sintaxe de diretivas para /think, /fast, /verbose, /trace e visibilidade do raciocínio
title: Níveis de raciocínio
x-i18n:
generated_at: "2026-04-30T10:12:58Z"
generated_at: "2026-04-30T16:30:45Z"
model: gpt-5.5
provider: openai
source_hash: e9fabead8d2f58fc5bce3bf8b281ad9d52da2cd02ba2777bc1597359537b7705
source_hash: f9adf065e46cb64e4c2149b95ecd69ed887a17e2eff5a5569894defa3e7217b7
source_path: tools/thinking.md
workflow: 16
---
## O que faz
## O que ele faz
- Diretiva inline em qualquer corpo recebido: `/t <level>`, `/think:<level>` ou `/thinking <level>`.
- Níveis (apelidos): `off | minimal | low | medium | high | xhigh | adaptive | max`
- minimal → “pense”
- low → “pense bastante”
- medium → “pense mais a fundo”
- Diretiva inline em qualquer corpo de entrada: `/t <level>`, `/think:<level>` ou `/thinking <level>`.
- Níveis (aliases): `off | minimal | low | medium | high | xhigh | adaptive | max`
- minimal → “think”
- low → “think hard”
- medium → “think harder”
- high → “ultrathink” (orçamento máximo)
- xhigh → “ultrathink+” (modelos GPT-5.2+ e Codex, além do esforço Anthropic Claude Opus 4.7)
- adaptive → pensamento adaptativo gerenciado pelo provedor (compatível com Claude 4.6 na Anthropic/Bedrock, Anthropic Claude Opus 4.7 e pensamento dinâmico do Google Gemini)
- max → raciocínio máximo do provedor (Anthropic Claude Opus 4.7; o Ollama mapeia isso para seu maior esforço `think` nativo)
- `x-high`, `x_high`, `extra-high`, `extra high` e `extra_high` mapeiam para `xhigh`.
- `highest` mapeia para `high`.
- xhigh → “ultrathink+” (modelos GPT-5.2+ e Codex, mais esforço do Anthropic Claude Opus 4.7)
- adaptive → raciocínio adaptativo gerenciado pelo provedor (compatível com Claude 4.6 na Anthropic/Bedrock, Anthropic Claude Opus 4.7 e raciocínio dinâmico do Google Gemini)
- max → raciocínio máximo do provedor (Anthropic Claude Opus 4.7; Ollama mapeia isso para seu maior esforço nativo de `think`)
- `x-high`, `x_high`, `extra-high`, `extra high` e `extra_high` são mapeados para `xhigh`.
- `highest` é mapeado para `high`.
- Observações sobre provedores:
- Menus e seletores de pensamento são orientados pelo perfil do provedor. Os plugins de provedor declaram o conjunto exato de níveis para o modelo selecionado, incluindo rótulos como o `on` binário.
- `adaptive`, `xhigh` e `max` só são anunciados para perfis de provedor/modelo que oferecem suporte a eles. Diretivas digitadas para níveis não compatíveis são rejeitadas com as opções válidas desse modelo.
- Níveis não compatíveis já armazenados são remapeados pela classificação do perfil do provedor. `adaptive` recua para `medium` em modelos não adaptativos, enquanto `xhigh` e `max` recuam para o maior nível não `off` compatível com o modelo selecionado.
- Modelos Anthropic Claude 4.6 usam `adaptive` por padrão quando nenhum nível explícito de pensamento é definido.
- Anthropic Claude Opus 4.7 não usa pensamento adaptativo por padrão. O padrão de esforço da API dele continua pertencendo ao provedor, a menos que você defina explicitamente um nível de pensamento.
- Anthropic Claude Opus 4.7 mapeia `/think xhigh` para pensamento adaptativo mais `output_config.effort: "xhigh"`, porque `/think` é uma diretiva de pensamento e `xhigh` é a configuração de esforço do Opus 4.7.
- Anthropic Claude Opus 4.7 também expõe `/think max`; ele mapeia para o mesmo caminho de esforço máximo pertencente ao provedor.
- Modelos Ollama com suporte a pensamento expõem `/think low|medium|high|max`; `max` mapeia para `think: "high"` nativo porque a API nativa do Ollama aceita as strings de esforço `low`, `medium` e `high`.
- Modelos OpenAI GPT mapeiam `/think` pelo suporte a esforço específico do modelo na Responses API. `/think off` envia `reasoning.effort: "none"` somente quando o modelo de destino oferece suporte a isso; caso contrário, o OpenClaw omite o payload de raciocínio desativado em vez de enviar um valor não compatível.
- Entradas de catálogo personalizadas compatíveis com OpenAI podem optar por `/think xhigh` definindo `models.providers.<provider>.models[].compat.supportedReasoningEfforts` para incluir `"xhigh"`. Isso usa os mesmos metadados de compatibilidade que mapeiam payloads de esforço de raciocínio OpenAI de saída, para que menus, validação de sessão, CLI do agente e `llm-task` estejam alinhados com o comportamento de transporte.
- Referências configuradas obsoletas do OpenRouter Hunter Alpha pulam a injeção de raciocínio do proxy porque essa rota descontinuada podia retornar texto de resposta final por campos de raciocínio.
- Google Gemini mapeia `/think adaptive` para o pensamento dinâmico pertencente ao provedor do Gemini. Solicitações Gemini 3 omitem um `thinkingLevel` fixo, enquanto solicitações Gemini 2.5 enviam `thinkingBudget: -1`; níveis fixos ainda mapeiam para o `thinkingLevel` ou orçamento Gemini mais próximo para essa família de modelos.
- MiniMax (`minimax/*`) no caminho de streaming compatível com Anthropic usa por padrão `thinking: { type: "disabled" }`, a menos que você defina explicitamente pensamento nos parâmetros do modelo ou da solicitação. Isso evita deltas vazados de `reasoning_content` do formato de stream Anthropic não nativo da MiniMax.
- Z.AI (`zai/*`) só oferece suporte a pensamento binário (`on`/`off`). Qualquer nível não `off` é tratado como `on` (mapeado para `low`).
- Moonshot (`moonshot/*`) mapeia `/think off` para `thinking: { type: "disabled" }` e qualquer nível não `off` para `thinking: { type: "enabled" }`. Quando o pensamento está ativado, a Moonshot aceita apenas `tool_choice` `auto|none`; o OpenClaw normaliza valores incompatíveis para `auto`.
- Menus e seletores de raciocínio são orientados por perfil de provedor. Plugins de provedor declaram o conjunto exato de níveis para o modelo selecionado, incluindo rótulos como `on` binário.
- `adaptive`, `xhigh` e `max` são anunciados apenas para perfis de provedor/modelo compatíveis. Diretivas digitadas para níveis sem suporte são rejeitadas com as opções válidas desse modelo.
- Níveis sem suporte armazenados existentes são remapeados pela classificação do perfil do provedor. `adaptive` recua para `medium` em modelos não adaptativos, enquanto `xhigh` e `max` recuam para o maior nível não `off` compatível com o modelo selecionado.
- Modelos Anthropic Claude 4.6 usam `adaptive` por padrão quando nenhum nível de raciocínio explícito é definido.
- Anthropic Claude Opus 4.7 não usa raciocínio adaptativo por padrão. O padrão de esforço da API continua sob responsabilidade do provedor, a menos que você defina explicitamente um nível de raciocínio.
- Anthropic Claude Opus 4.7 mapeia `/think xhigh` para raciocínio adaptativo mais `output_config.effort: "xhigh"`, porque `/think` é uma diretiva de raciocínio e `xhigh` é a configuração de esforço do Opus 4.7.
- Anthropic Claude Opus 4.7 também expõe `/think max`; ele é mapeado para o mesmo caminho de esforço máximo pertencente ao provedor.
- Modelos DeepSeek V4 expõem `/think xhigh|max`; ambos são mapeados para DeepSeek `reasoning_effort: "max"`, enquanto níveis não `off` inferiores são mapeados para `high`.
- Modelos Ollama com capacidade de raciocínio expõem `/think low|medium|high|max`; `max` é mapeado para `think: "high"` nativo, porque a API nativa do Ollama aceita strings de esforço `low`, `medium` e `high`.
- Modelos OpenAI GPT mapeiam `/think` por meio do suporte de esforço específico do modelo na Responses API. `/think off` envia `reasoning.effort: "none"` somente quando o modelo de destino é compatível; caso contrário, o OpenClaw omite o payload de raciocínio desativado em vez de enviar um valor sem suporte.
- Entradas de catálogo personalizadas compatíveis com OpenAI podem optar por `/think xhigh` definindo `models.providers.<provider>.models[].compat.supportedReasoningEfforts` para incluir `"xhigh"`. Isso usa os mesmos metadados de compatibilidade que mapeiam payloads de esforço de raciocínio OpenAI de saída, então menus, validação de sessão, CLI do agente e `llm-task` concordam com o comportamento de transporte.
- Referências configuradas obsoletas do OpenRouter Hunter Alpha ignoram a injeção de raciocínio por proxy porque essa rota aposentada podia retornar texto de resposta final por campos de raciocínio.
- Google Gemini mapeia `/think adaptive` para o raciocínio dinâmico pertencente ao provedor do Gemini. Solicitações do Gemini 3 omitem um `thinkingLevel` fixo, enquanto solicitações do Gemini 2.5 enviam `thinkingBudget: -1`; níveis fixos ainda são mapeados para o `thinkingLevel` ou orçamento Gemini mais próximo para essa família de modelos.
- MiniMax (`minimax/*`) no caminho de streaming compatível com Anthropic usa `thinking: { type: "disabled" }` por padrão, a menos que você defina explicitamente raciocínio em parâmetros de modelo ou de solicitação. Isso evita deltas de `reasoning_content` vazados do formato de stream Anthropic não nativo do MiniMax.
- Z.AI (`zai/*`) só oferece suporte a raciocínio binário (`on`/`off`). Qualquer nível que não seja `off` é tratado como `on` (mapeado para `low`).
- Moonshot (`moonshot/*`) mapeia `/think off` para `thinking: { type: "disabled" }` e qualquer nível que não seja `off` para `thinking: { type: "enabled" }`. Quando o raciocínio está ativado, Moonshot aceita apenas `tool_choice` `auto|none`; OpenClaw normaliza valores incompatíveis para `auto`.
## Ordem de resolução
1. Diretiva inline na mensagem (aplica-se somente a essa mensagem).
2. Substituição da sessão (definida ao enviar uma mensagem contendo apenas a diretiva).
2. Substituição da sessão (definida ao enviar uma mensagem contendo apenas diretiva).
3. Padrão por agente (`agents.list[].thinkingDefault` na configuração).
4. Padrão global (`agents.defaults.thinkingDefault` na configuração).
5. Fallback: padrão declarado pelo provedor quando disponível; caso contrário, modelos com capacidade de raciocínio resolvem para `medium` ou para o nível não `off` compatível mais próximo desse modelo, e modelos sem raciocínio permanecem `off`.
5. Fallback: padrão declarado pelo provedor quando disponível; caso contrário, modelos capazes de raciocínio resolvem para `medium` ou para o nível não `off` compatível mais próximo desse modelo, e modelos sem raciocínio permanecem `off`.
## Definindo um padrão de sessão
## Definir um padrão de sessão
- Envie uma mensagem que seja **somente** a diretiva (espaços em branco são permitidos), por exemplo, `/think:medium` ou `/t high`.
- Isso permanece para a sessão atual (por remetente, por padrão); é limpo por `/think:off` ou por redefinição de ociosidade da sessão.
- Uma resposta de confirmação é enviada (`Thinking level set to high.` / `Thinking disabled.`). Se o nível for inválido (por exemplo, `/thinking big`), o comando é rejeitado com uma dica e o estado da sessão permanece inalterado.
- Envie `/think` (ou `/think:`) sem argumento para ver o nível de pensamento atual.
- Envie uma mensagem que seja **apenas** a diretiva (espaços em branco permitidos), por exemplo, `/think:medium` ou `/t high`.
- Isso permanece para a sessão atual (por remetente, por padrão); limpo por `/think:off` ou redefinição por inatividade da sessão.
- Uma resposta de confirmação é enviada (`Thinking level set to high.` / `Thinking disabled.`). Se o nível for inválido (por exemplo, `/thinking big`), o comando será rejeitado com uma dica e o estado da sessão permanecerá inalterado.
- Envie `/think` (ou `/think:`) sem argumento para ver o nível de raciocínio atual.
## Aplicação por agente
@ -64,76 +65,76 @@ x-i18n:
## Modo rápido (/fast)
- Níveis: `on|off`.
- Mensagem contendo apenas a diretiva alterna uma substituição de modo rápido da sessão e responde `Fast mode enabled.` / `Fast mode disabled.`.
- Mensagem contendo apenas diretiva alterna uma substituição de modo rápido da sessão e responde `Fast mode enabled.` / `Fast mode disabled.`.
- Envie `/fast` (ou `/fast status`) sem modo para ver o estado efetivo atual do modo rápido.
- O OpenClaw resolve o modo rápido nesta ordem:
1. `/fast on|off` inline/contendo apenas a diretiva
- OpenClaw resolve o modo rápido nesta ordem:
1. `/fast on|off` inline/somente diretiva
2. Substituição da sessão
3. Padrão por agente (`agents.list[].fastModeDefault`)
4. Configuração por modelo: `agents.defaults.models["<provider>/<model>"].params.fastMode`
5. Fallback: `off`
- Para `openai/*`, o modo rápido mapeia para o processamento prioritário da OpenAI enviando `service_tier=priority` em solicitações Responses compatíveis.
- Para `openai-codex/*`, o modo rápido envia a mesma flag `service_tier=priority` nas Responses do Codex. O OpenClaw mantém uma alternância `/fast` compartilhada entre os dois caminhos de autenticação.
- Para solicitações públicas diretas `anthropic/*`, incluindo tráfego autenticado por OAuth enviado para `api.anthropic.com`, o modo rápido mapeia para níveis de serviço da Anthropic: `/fast on` define `service_tier=auto`, `/fast off` define `service_tier=standard_only`.
- Para `openai/*`, o modo rápido é mapeado para processamento prioritário OpenAI enviando `service_tier=priority` em solicitações Responses compatíveis.
- Para `openai-codex/*`, o modo rápido envia a mesma flag `service_tier=priority` em Responses do Codex. OpenClaw mantém uma alternância `/fast` compartilhada entre os dois caminhos de autenticação.
- Para solicitações públicas diretas `anthropic/*`, incluindo tráfego autenticado por OAuth enviado para `api.anthropic.com`, o modo rápido é mapeado para níveis de serviço da Anthropic: `/fast on` define `service_tier=auto`, `/fast off` define `service_tier=standard_only`.
- Para `minimax/*` no caminho compatível com Anthropic, `/fast on` (ou `params.fastMode: true`) reescreve `MiniMax-M2.7` para `MiniMax-M2.7-highspeed`.
- Parâmetros explícitos de modelo Anthropic `serviceTier` / `service_tier` substituem o padrão do modo rápido quando ambos estão definidos. O OpenClaw ainda pula a injeção de nível de serviço Anthropic para URLs base de proxy não Anthropic.
- Parâmetros de modelo Anthropic explícitos `serviceTier` / `service_tier` substituem o padrão do modo rápido quando ambos são definidos. OpenClaw ainda ignora a injeção de nível de serviço Anthropic para URLs base de proxy que não são Anthropic.
- `/status` mostra `Fast` somente quando o modo rápido está ativado.
## Diretivas detalhadas (/verbose ou /v)
- Níveis: `on` (mínimo) | `full` | `off` (padrão).
- Mensagem contendo apenas a diretiva alterna o detalhamento da sessão e responde `Verbose logging enabled.` / `Verbose logging disabled.`; níveis inválidos retornam uma dica sem alterar o estado.
- Mensagem contendo apenas diretiva alterna o modo detalhado da sessão e responde `Verbose logging enabled.` / `Verbose logging disabled.`; níveis inválidos retornam uma dica sem alterar o estado.
- `/verbose off` armazena uma substituição explícita da sessão; limpe-a pela UI de Sessões escolhendo `inherit`.
- Diretiva inline afeta somente essa mensagem; padrões de sessão/globais se aplicam nos demais casos.
- Envie `/verbose` (ou `/verbose:`) sem argumento para ver o nível detalhado atual.
- Quando o modo detalhado está ligado, agentes que emitem resultados estruturados de ferramentas (Pi, outros agentes JSON) enviam cada chamada de ferramenta de volta como sua própria mensagem somente de metadados, prefixada com `<emoji> <tool-name>: <arg>` quando disponível (caminho/comando). Esses resumos de ferramentas são enviados assim que cada ferramenta inicia (bolhas separadas), não como deltas de streaming.
- Resumos de falha de ferramentas permanecem visíveis no modo normal, mas sufixos de detalhe de erro bruto ficam ocultos, a menos que o detalhamento esteja `on` ou `full`.
- Quando o detalhamento está `full`, saídas de ferramentas também são encaminhadas após a conclusão (bolha separada, truncada para um tamanho seguro). Se você alternar `/verbose on|full|off` enquanto uma execução está em andamento, bolhas de ferramentas subsequentes respeitam a nova configuração.
- Quando o modo detalhado está ativado, agentes que emitem resultados de ferramenta estruturados (Pi, outros agentes JSON) enviam cada chamada de ferramenta de volta como sua própria mensagem somente de metadados, prefixada com `<emoji> <tool-name>: <arg>` quando disponível (caminho/comando). Esses resumos de ferramenta são enviados assim que cada ferramenta começa (balões separados), não como deltas de streaming.
- Resumos de falha de ferramenta permanecem visíveis no modo normal, mas sufixos de detalhe de erro bruto ficam ocultos, a menos que o modo detalhado seja `on` ou `full`.
- Quando o modo detalhado é `full`, as saídas de ferramenta também são encaminhadas após a conclusão (balão separado, truncado para um tamanho seguro). Se você alternar `/verbose on|full|off` enquanto uma execução está em andamento, os balões de ferramenta subsequentes respeitarão a nova configuração.
## Diretivas de rastreamento de Plugin (/trace)
- Níveis: `on` | `off` (padrão).
- Mensagem contendo apenas a diretiva alterna a saída de rastreamento de Plugin da sessão e responde `Plugin trace enabled.` / `Plugin trace disabled.`.
- Mensagem contendo apenas diretiva alterna a saída de rastreamento de Plugin da sessão e responde `Plugin trace enabled.` / `Plugin trace disabled.`.
- Diretiva inline afeta somente essa mensagem; padrões de sessão/globais se aplicam nos demais casos.
- Envie `/trace` (ou `/trace:`) sem argumento para ver o nível de rastreamento atual.
- `/trace` é mais restrito que `/verbose`: ele expõe somente linhas de rastreamento/depuração pertencentes a plugins, como resumos de depuração de Active Memory.
- `/trace` é mais estreito que `/verbose`: expõe apenas linhas de rastreamento/depuração pertencentes a plugins, como resumos de depuração de Active Memory.
- Linhas de rastreamento podem aparecer em `/status` e como uma mensagem diagnóstica de acompanhamento após a resposta normal do assistente.
## Visibilidade do raciocínio (/reasoning)
## Visibilidade de raciocínio (/reasoning)
- Níveis: `on|off|stream`.
- Mensagem contendo apenas a diretiva alterna se blocos de pensamento são exibidos nas respostas.
- Mensagem contendo apenas diretiva alterna se blocos de raciocínio são mostrados nas respostas.
- Quando ativado, o raciocínio é enviado como uma **mensagem separada** prefixada com `Reasoning:`.
- `stream` (somente Telegram): transmite o raciocínio para a bolha de rascunho do Telegram enquanto a resposta é gerada e depois envia a resposta final sem raciocínio.
- `stream` (somente Telegram): transmite o raciocínio para o balão de rascunho do Telegram enquanto a resposta está sendo gerada e depois envia a resposta final sem raciocínio.
- Alias: `/reason`.
- Envie `/reasoning` (ou `/reasoning:`) sem argumento para ver o nível de raciocínio atual.
- Ordem de resolução: diretiva inline, depois substituição da sessão, depois padrão por agente (`agents.list[].reasoningDefault`), depois fallback (`off`).
Tags de raciocínio de modelo local malformadas são tratadas de forma conservadora. Blocos fechados `<think>...</think>` permanecem ocultos em respostas normais, e raciocínio não fechado após texto já visível também fica oculto. Se uma resposta estiver totalmente envolvida em uma única tag de abertura não fechada e, de outra forma, seria entregue como texto vazio, o OpenClaw remove a tag de abertura malformada e entrega o texto restante.
Tags de raciocínio de modelo local malformadas são tratadas de forma conservadora. Blocos fechados `<think>...</think>` permanecem ocultos em respostas normais, e raciocínio não fechado após texto já visível também fica oculto. Se uma resposta estiver totalmente envolvida em uma única tag de abertura não fechada e, de outra forma, seria entregue como texto vazio, OpenClaw remove a tag de abertura malformada e entrega o texto restante.
## Relacionado
- A documentação do modo elevado está em [Modo elevado](/pt-BR/tools/elevated).
- A documentação do modo elevado fica em [Modo elevado](/pt-BR/tools/elevated).
## Heartbeats
- O corpo da sondagem de Heartbeat é o prompt de Heartbeat configurado (padrão: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Diretivas inline em uma mensagem de Heartbeat se aplicam normalmente (mas evite alterar padrões de sessão a partir de Heartbeats).
- A entrega de Heartbeat usa por padrão somente o payload final. Para também enviar a mensagem `Reasoning:` separada (quando disponível), defina `agents.defaults.heartbeat.includeReasoning: true` ou `agents.list[].heartbeat.includeReasoning: true` por agente.
- O corpo da sonda de Heartbeat é o prompt de Heartbeat configurado (padrão: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Diretivas inline em uma mensagem de Heartbeat se aplicam normalmente (mas evite alterar padrões de sessão a partir de Heartbeats).
- A entrega de Heartbeat usa por padrão apenas o payload final. Para também enviar a mensagem `Reasoning:` separada (quando disponível), defina `agents.defaults.heartbeat.includeReasoning: true` ou `agents.list[].heartbeat.includeReasoning: true` por agente.
## UI do chat web
## UI de chat web
- O seletor de pensamento do chat web espelha o nível armazenado da sessão a partir do armazenamento/configuração da sessão recebida quando a página carrega.
- Escolher outro nível grava a substituição da sessão imediatamente via `sessions.patch`; ele não espera o próximo envio e não é uma substituição `thinkingOnce` de uso único.
- A primeira opção é sempre `Default (<resolved level>)`, onde o padrão resolvido vem do perfil de pensamento do provedor do modelo da sessão ativa mais a mesma lógica de fallback que `/status` e `session_status` usam.
- O seletor usa `thinkingLevels` retornado pela linha/padrões de sessão do Gateway, com `thinkingOptions` mantido como uma lista legada de rótulos. A UI do navegador não mantém sua própria lista de regex de provedores; os plugins são responsáveis pelos conjuntos de níveis específicos do modelo.
- `/think:<level>` ainda funciona e atualiza o mesmo nível de sessão armazenado, para que diretivas de chat e o seletor permaneçam sincronizados.
- O seletor de raciocínio do chat web espelha o nível armazenado da sessão a partir do repositório/configuração da sessão de entrada quando a página carrega.
- Selecionar outro nível grava a substituição da sessão imediatamente via `sessions.patch`; ele não espera o próximo envio e não é uma substituição única `thinkingOnce`.
- A primeira opção é sempre `Default (<resolved level>)`, em que o padrão resolvido vem do perfil de raciocínio do provedor do modelo da sessão ativa mais a mesma lógica de fallback que `/status` e `session_status` usam.
- O seletor usa `thinkingLevels` retornado pela linha/padrões da sessão do Gateway, com `thinkingOptions` mantido como uma lista legada de rótulos. A UI do navegador não mantém sua própria lista de regex de provedor; plugins possuem conjuntos de níveis específicos de modelo.
- `/think:<level>` ainda funciona e atualiza o mesmo nível de sessão armazenado, então diretivas de chat e o seletor permanecem sincronizados.
## Perfis de provedor
- Plugins de provedor podem expor `resolveThinkingProfile(ctx)` para definir os níveis compatíveis do modelo e o padrão.
- Plugins de provedor que fazem proxy de modelos Claude devem reutilizar `resolveClaudeThinkingProfile(modelId)` de `openclaw/plugin-sdk/provider-model-shared` para que os catálogos diretos da Anthropic e de proxy permaneçam alinhados.
- Plugins de provedor que fazem proxy de modelos Claude devem reutilizar `resolveClaudeThinkingProfile(modelId)` de `openclaw/plugin-sdk/provider-model-shared` para que os catálogos diretos da Anthropic e os catálogos de proxy permaneçam alinhados.
- Cada nível de perfil tem um `id` canônico armazenado (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `adaptive` ou `max`) e pode incluir um `label` de exibição. Provedores binários usam `{ id: "low", label: "on" }`.
- Plugins de ferramenta que precisam validar uma substituição explícita de raciocínio devem usar `api.runtime.agent.resolveThinkingPolicy({ provider, model })` mais `api.runtime.agent.normalizeThinkingLevel(...)`; eles não devem manter suas próprias listas de níveis de provedor/modelo.
- Plugins de ferramenta com acesso a metadados configurados de modelo personalizado podem passar `catalog` para `resolveThinkingPolicy` para que adesões em `compat.supportedReasoningEfforts` sejam refletidas na validação do lado do Plugin.
- Plugins de ferramenta que precisam validar uma substituição explícita de raciocínio devem usar `api.runtime.agent.resolveThinkingPolicy({ provider, model })` junto com `api.runtime.agent.normalizeThinkingLevel(...)`; eles não devem manter suas próprias listas de níveis por provedor/modelo.
- Plugins de ferramenta com acesso a metadados configurados de modelos personalizados podem passar `catalog` para `resolveThinkingPolicy` para que adesões de `compat.supportedReasoningEfforts` sejam refletidas na validação do lado do Plugin.
- Hooks legados publicados (`supportsXHighThinking`, `isBinaryThinking` e `resolveDefaultThinkingLevel`) permanecem como adaptadores de compatibilidade, mas novos conjuntos de níveis personalizados devem usar `resolveThinkingProfile`.
- Linhas/padrões do Gateway expõem `thinkingLevels`, `thinkingOptions` e `thinkingDefault` para que clientes de ACP/bate-papo renderizem os mesmos ids e rótulos de perfil que a validação em tempo de execução usa.
- Linhas/padrões do Gateway expõem `thinkingLevels`, `thinkingOptions` e `thinkingDefault` para que clientes ACP/chat renderizem os mesmos ids e rótulos de perfil que a validação em tempo de execução usa.