diff --git a/docs/pt-BR/channels/slack.md b/docs/pt-BR/channels/slack.md index f25c601da..f8884654d 100644 --- a/docs/pt-BR/channels/slack.md +++ b/docs/pt-BR/channels/slack.md @@ -1,20 +1,20 @@ --- read_when: - Ao configurar o Slack ou depurar o modo socket/HTTP do Slack -summary: Configuração e comportamento em tempo de execução do Slack (Socket Mode + URLs de solicitação HTTP) +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-07T05:27:29Z" + generated_at: "2026-04-08T05:27:44Z" model: gpt-5.4 provider: openai - source_hash: 2b8fd2cc6c638ee82069f0af2c2b6f6f49c87da709b941433a0343724a9907ea + source_hash: cad132131ddce688517def7c14703ad314441c67aacc4cc2a2a721e1d1c01942 source_path: channels/slack.md workflow: 15 --- # Slack -Status: pronto para produção para DMs + canais por meio de integrações de apps do Slack. O modo padrão é Socket Mode; URLs de solicitação HTTP também são compatíveis. +Status: pronto para produção para DMs + canais por meio de integrações de app do Slack. O modo padrão é Socket Mode; URLs de solicitação HTTP também são compatíveis. @@ -33,7 +33,7 @@ Status: pronto para produção para DMs + canais por meio de integrações de ap - + 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 seu app @@ -42,7 +42,7 @@ Status: pronto para produção para DMs + canais por meio de integrações de ap - instale o app e copie o **Bot Token** (`xoxb-...`) exibido - + ```json5 { @@ -57,7 +57,7 @@ Status: pronto para produção para DMs + canais por meio de integrações de ap } ``` - Fallback por variável de ambiente (somente conta padrão): + Fallback por env (somente conta padrão): ```bash SLACK_APP_TOKEN=xapp-... @@ -66,7 +66,7 @@ SLACK_BOT_TOKEN=xoxb-... - + ```bash openclaw gateway @@ -79,7 +79,7 @@ openclaw gateway - + 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 seu app @@ -89,7 +89,7 @@ openclaw gateway - + ```json5 { @@ -108,12 +108,12 @@ openclaw gateway Use caminhos de webhook exclusivos para HTTP com várias contas - Dê a cada conta um `webhookPath` distinto (o padrão é `/slack/events`) para que os registros não entrem em conflito. + Dê a cada conta um `webhookPath` distinto (padrão `/slack/events`) para que os registros não entrem em conflito. - + ```bash openclaw gateway @@ -125,7 +125,7 @@ openclaw gateway -## Lista de verificação de manifesto e escopos +## Checklist de manifesto e escopos @@ -294,9 +294,10 @@ openclaw gateway 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:`. + - Se você configurar `channels.slack.userToken`, os escopos típicos de leitura são: + Se você configurar `channels.slack.userToken`, os escopos de leitura típicos são: - `channels:history`, `groups:history`, `im:history`, `mpim:history` - `channels:read`, `groups:read`, `im:read`, `mpim:read` @@ -304,7 +305,7 @@ openclaw gateway - `reactions:read` - `pins:read` - `emoji:read` - - `search:read` (se você depende de leituras da busca do Slack) + - `search:read` (se você depender de leituras da pesquisa do Slack) @@ -315,23 +316,23 @@ openclaw gateway - O modo HTTP exige `botToken` + `signingSecret`. - `botToken`, `appToken`, `signingSecret` e `userToken` aceitam strings em texto simples ou objetos SecretRef. -- Tokens na configuração substituem o fallback por variável de ambiente. -- O fallback por variável de ambiente `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` se aplica apenas à conta padrão. -- `userToken` (`xoxp-...`) é somente de configuração (sem fallback por variável de ambiente) e assume por padrão comportamento somente leitura (`userTokenReadOnly: true`). +- Os tokens da configuração substituem o fallback por env. +- O fallback por env `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` se aplica apenas à conta padrão. +- `userToken` (`xoxp-...`) é somente de configuração (sem fallback por env) e usa comportamento somente leitura por padrão (`userTokenReadOnly: true`). Comportamento do snapshot de status: -- A inspeção da conta do Slack rastreia campos `*Source` e `*Status` +- 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 fonte secreta não inline, mas o caminho atual de comando/runtime + ou outra fonte de segredo não inline, mas o caminho atual de comando/tempo de execução não conseguiu resolver o valor real. - No modo HTTP, `signingSecretStatus` é incluído; em Socket Mode, o par obrigatório é `botTokenStatus` + `appTokenStatus`. -Para ações/leituras de diretório, o token de usuário pode ser priorizado quando configurado. Para escritas, o token de bot continua sendo o preferido; escritas com token de usuário só são permitidas quando `userTokenReadOnly: false` e o token de bot não está disponível. +Para ações/leituras de diretório, o token de usuário pode ser preferido quando configurado. Para escritas, o token de bot continua sendo preferido; escritas com token de usuário só são permitidas quando `userTokenReadOnly: false` e o token de bot não está disponível. ## Ações e controles @@ -366,10 +367,10 @@ As ações atuais de mensagem do Slack incluem `send`, `upload-file`, `download- - `dm.enabled` (padrão true) - `channels.slack.allowFrom` (preferido) - `dm.allowFrom` (legado) - - `dm.groupEnabled` (DMs em grupo têm padrão false) - - `dm.groupChannels` (lista de permissões opcional para MPIM) + - `dm.groupEnabled` (DMs em grupo com padrão false) + - `dm.groupChannels` (allowlist opcional de MPIM) - Precedência de várias contas: + Precedência em várias contas: - `channels.slack.accounts.default.allowFrom` aplica-se apenas à conta `default`. - Contas nomeadas herdam `channels.slack.allowFrom` quando seu próprio `allowFrom` não está definido. @@ -386,15 +387,15 @@ As ações atuais de mensagem do Slack incluem `send`, `upload-file`, `download- - `allowlist` - `disabled` - A lista de permissões de canal fica em `channels.slack.channels` e deve usar IDs estáveis de canal. + A allowlist de canais fica em `channels.slack.channels` e deve usar IDs de canal estáveis. - Observação de runtime: se `channels.slack` estiver completamente ausente (configuração somente por variável de ambiente), o runtime usa `groupPolicy="allowlist"` como fallback e registra um aviso (mesmo se `channels.defaults.groupPolicy` estiver definido). + Observação de tempo de execução: se `channels.slack` estiver totalmente ausente (configuração somente por env), o tempo de execução usa `groupPolicy="allowlist"` como fallback e registra um aviso (mesmo que `channels.defaults.groupPolicy` esteja definido). Resolução de nome/ID: - - entradas da lista de permissões de canal e da lista de permissões de DM são resolvidas na inicialização quando o acesso por token permite + - entradas de allowlist de canais e entradas de allowlist de DM são resolvidas na inicialização quando o acesso por token permite - entradas não resolvidas por nome de canal são mantidas como configuradas, mas ignoradas para roteamento por padrão - - a autorização de entrada e o roteamento de canal usam IDs primeiro por padrão; correspondência direta por nome de usuário/slug exige `channels.slack.dangerouslyAllowNameMatching: true` + - a autorização de entrada e o roteamento de canal usam ID primeiro por padrão; correspondência direta de nome de usuário/slug exige `channels.slack.dangerouslyAllowNameMatching: true` @@ -407,16 +408,16 @@ As ações atuais de mensagem do Slack incluem `send`, `upload-file`, `download- - padrões regex de menção (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`) - comportamento implícito de resposta em thread ao bot (desativado quando `thread.requireExplicitMention` é `true`) - Controles por canal (`channels.slack.channels.`; nomes somente por resolução na inicialização ou `dangerouslyAllowNameMatching`): + Controles por canal (`channels.slack.channels.`; nomes somente via resolução na inicialização ou `dangerouslyAllowNameMatching`): - `requireMention` - - `users` (lista de permissões) + - `users` (allowlist) - `allowBots` - `skills` - `systemPrompt` - `tools`, `toolsBySender` - - formato de chave de `toolsBySender`: `id:`, `e164:`, `username:`, `name:` ou curinga `"*"` - (chaves legadas sem prefixo ainda são mapeadas apenas para `id:`) + - formato da chave `toolsBySender`: `id:`, `e164:`, `username:`, `name:` ou coringa `"*"` + (chaves legadas sem prefixo ainda são mapeadas somente para `id:`) @@ -428,32 +429,32 @@ As ações atuais de mensagem do Slack incluem `send`, `upload-file`, `download- - Sessões de canal: `agent::slack:channel:`. - Respostas em thread podem criar sufixos de sessão de thread (`:thread:`) 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 desativar). -- `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 existentes da thread são buscadas quando uma nova sessão de thread é iniciada (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 só responda a menções `@bot` explícitas 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 `requireMention`. -Controles de encadeamento de respostas: +Controles de encadeamento de resposta: - `channels.slack.replyToMode`: `off|first|all|batched` (padrão `off`) - `channels.slack.replyToModeByChatType`: por `direct|group|channel` - fallback legado para chats diretos: `channels.slack.dm.replyToMode` -Tags manuais de resposta são compatíveis: +Há suporte para tags manuais de resposta: - `[[reply_to_current]]` - `[[reply_to:]]` -Observação: `replyToMode="off"` desativa **todo** o encadeamento de respostas no Slack, incluindo tags explícitas `[[reply_to_*]]`. Isso difere do Telegram, onde tags explícitas ainda são respeitadas no modo `"off"`. A diferença reflete os modelos de thread da plataforma: as threads do Slack ocultam mensagens do canal, enquanto as respostas do Telegram permanecem visíveis no fluxo principal do chat. +Observação: `replyToMode="off"` desativa **todo** o encadeamento de respostas no Slack, incluindo tags explícitas `[[reply_to_*]]`. Isso difere do Telegram, em que as tags explícitas ainda são respeitadas no modo `"off"`. A diferença reflete os modelos de thread das plataformas: as threads do Slack ocultam mensagens do canal, enquanto as respostas do Telegram continuam visíveis no fluxo principal do chat. ## Reações de confirmação -`ackReaction` envia um emoji de confirmação enquanto o OpenClaw está processando uma mensagem de entrada. +`ackReaction` envia um emoji de confirmação enquanto o OpenClaw está processando uma mensagem recebida. Ordem de resolução: - `channels.slack.accounts..ackReaction` - `channels.slack.ackReaction` - `messages.ackReaction` -- fallback para emoji da identidade do agente (`agents.list[].identity.emoji`, senão "👀") +- fallback para o emoji de identidade do agente (`agents.list[].identity.emoji`, caso contrário "👀") Observações: @@ -462,27 +463,31 @@ Observações: ## Streaming de texto -`channels.slack.streaming` controla o comportamento de prévia ao vivo: +`channels.slack.streaming` controla o comportamento de visualização ao vivo: -- `off`: desativa o streaming de prévia ao vivo. -- `partial` (padrão): substitui o texto de prévia pela saída parcial mais recente. -- `block`: acrescenta atualizações de prévia em blocos. +- `off`: desativa o streaming de visualização ao vivo. +- `partial` (padrão): substitui o texto da visualização pela saída parcial mais recente. +- `block`: acrescenta atualizações de visualização em blocos. - `progress`: mostra texto de status de progresso durante a geração e depois envia o texto final. -`channels.slack.nativeStreaming` controla o streaming nativo de texto do Slack quando `streaming` é `partial` (padrão: `true`). +`channels.slack.streaming.nativeTransport` controla o streaming nativo de texto do Slack quando `channels.slack.streaming.mode` é `partial` (padrão: `true`). -- Uma thread de resposta precisa estar disponível para que o streaming nativo de texto apareça. A seleção da thread ainda segue `replyToMode`. Sem isso, a prévia normal em rascunho é usada. -- Mídia e payloads não textuais voltam para a entrega normal. -- Se o streaming falhar no meio da resposta, o OpenClaw volta para a entrega normal para os payloads restantes. +- Uma thread de resposta precisa estar disponível para que o streaming nativo de texto e o status da thread do assistente do Slack apareçam. A seleção da thread ainda segue `replyToMode`. +- Raízes de canais e chats em grupo ainda podem usar a visualização normal de rascunho quando o streaming nativo não estiver disponível. +- DMs do Slack de nível superior permanecem fora de thread por padrão, então não mostram a visualização no estilo de thread; use respostas em thread ou `typingReaction` se quiser progresso visível nelas. +- Cargas de mídia e não textuais usam fallback para entrega normal. +- Se o streaming falhar no meio da resposta, o OpenClaw usa fallback para entrega normal para as cargas restantes. -Use prévia em rascunho em vez do streaming nativo de texto do Slack: +Use a visualização de rascunho em vez do streaming nativo de texto do Slack: ```json5 { channels: { slack: { - streaming: "partial", - nativeStreaming: false, + streaming: { + mode: "partial", + nativeTransport: false, + }, }, }, } @@ -490,12 +495,13 @@ Use prévia em rascunho em vez do streaming nativo de texto do Slack: Chaves legadas: -- `channels.slack.streamMode` (`replace | status_final | append`) é migrado automaticamente para `channels.slack.streaming`. -- boolean `channels.slack.streaming` é migrado automaticamente para `channels.slack.nativeStreaming`. +- `channels.slack.streamMode` (`replace | status_final | append`) é migrado automaticamente para `channels.slack.streaming.mode`. +- booleano `channels.slack.streaming` é migrado automaticamente para `channels.slack.streaming.mode` e `channels.slack.streaming.nativeTransport`. +- `channels.slack.nativeStreaming` legado é migrado automaticamente para `channels.slack.streaming.nativeTransport`. ## Fallback de reação de digitação -`typingReaction` adiciona uma reação temporária à mensagem recebida no 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...". +`typingReaction` adiciona uma reação temporária à mensagem recebida no Slack enquanto o OpenClaw processa uma resposta e depois a remove quando a execução termina. Isso é mais útil fora de respostas em thread, que usam um indicador padrão de status "is typing...". Ordem de resolução: @@ -505,23 +511,23 @@ Ordem de resolução: Observações: - O Slack espera shortcodes (por exemplo, `"hourglass_flowing_sand"`). -- A reação é best-effort e a limpeza é tentada automaticamente depois que a resposta ou o caminho de falha termina. +- A reação é de melhor esforço e a limpeza é tentada automaticamente após a conclusão da resposta ou do caminho de falha. ## Mídia, fragmentação e entrega - - Anexos de arquivo do Slack são baixados de URLs privadas hospedadas pelo Slack (fluxo de solicitação autenticado por token) e gravados no armazenamento de mídia quando a busca é bem-sucedida e os limites de tamanho permitem. + + Os anexos de arquivo do Slack são baixados de URLs privadas hospedadas pelo Slack (fluxo de solicitação autenticado por token) e gravados no armazenamento de mídia quando a busca é bem-sucedida e os limites de tamanho permitem. - O limite de tamanho de entrada em runtime tem padrão de `20MB`, a menos que seja substituído por `channels.slack.mediaMaxMb`. + O limite de tamanho de entrada em tempo de execução tem padrão de `20MB`, a menos que seja substituído por `channels.slack.mediaMaxMb`. - fragmentos de texto usam `channels.slack.textChunkLimit` (padrão 4000) - - `channels.slack.chunkMode="newline"` ativa 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 + - `channels.slack.chunkMode="newline"` ativa 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 de saída segue `channels.slack.mediaMaxMb` quando configurado; caso contrário, os envios do canal usam os padrões por tipo MIME do pipeline de mídia @@ -530,24 +536,24 @@ Observações: - `user:` para DMs - `channel:` para canais - As DMs do Slack são abertas pelas APIs de conversa do Slack ao enviar para destinos de usuário. + As DMs do Slack são abertas por APIs de conversa do Slack ao enviar para destinos de usuário. ## Comandos e comportamento de slash -- O modo automático de comando nativo está **desativado** para Slack (`commands.native: "auto"` não ativa comandos nativos do Slack). -- Ative os manipuladores nativos de comando do Slack com `channels.slack.commands.native: true` (ou global `commands.native: true`). -- Quando os comandos nativos estão ativados, registre os comandos de barra correspondentes no Slack (nomes `/`), com uma exceção: +- O modo automático de comando nativo fica **desativado** para Slack (`commands.native: "auto"` não ativa comandos nativos do Slack). +- Ative os manipuladores de comando nativo do Slack com `channels.slack.commands.native: true` (ou global `commands.native: true`). +- Quando os comandos nativos estão ativados, registre comandos de barra correspondentes no Slack (nomes `/`), com uma exceção: - registre `/agentstatus` para o comando de status (o Slack reserva `/status`) -- Se os comandos nativos não estiverem ativados, você pode executar um único comando de barra configurado por meio de `channels.slack.slashCommand`. -- Menus nativos de argumentos agora adaptam sua estratégia de renderização: - - até 5 opções: blocos de botão - - de 6 a 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 manipuladores de opções de interatividade estão disponíveis - - se valores de opção codificados excederem os limites do Slack, o fluxo volta para botões -- Para payloads longos de opção, menus de argumento de comando de barra usam um diálogo de confirmação antes de despachar um valor selecionado. +- Se os comandos nativos não estiverem ativados, você pode executar um único comando de barra configurado por `channels.slack.slashCommand`. +- Os menus nativos de argumentos agora adaptam sua estratégia de renderização: + - até 5 opções: blocos de botões + - 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 os manipuladores de opções de interatividade estão disponíveis + - se os valores de opção codificados excederem os limites do Slack, o fluxo usa fallback para botões +- Para cargas longas de opções, os menus de argumentos de comando de barra usam um diálogo de confirmação antes de despachar um valor selecionado. Configurações padrão de comando de barra: @@ -556,15 +562,15 @@ Configurações padrão de comando de barra: - `sessionPrefix: "slack:slash"` - `ephemeral: true` -Sessões de slash usam chaves isoladas: +As sessões de slash usam chaves isoladas: - `agent::slack:slash:` -e ainda roteiam a execução do comando em relação à sessão de conversa de destino (`CommandTargetSessionKey`). +e ainda roteiam a execução do comando para a sessão de conversa de destino (`CommandTargetSessionKey`). ## Respostas interativas -O Slack pode renderizar controles interativos de resposta criados pelo agente, mas esse recurso está desativado por padrão. +O Slack pode renderizar controles interativos de resposta criados pelo agente, mas esse recurso fica desativado por padrão. Ative globalmente: @@ -580,7 +586,7 @@ Ative globalmente: } ``` -Ou ative somente para uma conta do Slack: +Ou ative para apenas uma conta do Slack: ```json5 { @@ -598,31 +604,30 @@ Ou ative somente para uma conta do Slack: } ``` -Quando ativado, agentes podem emitir diretivas de resposta exclusivas do Slack: +Quando ativado, os agentes podem emitir diretivas de resposta exclusivas do Slack: - `[[slack_buttons: Approve:approve, Reject:reject]]` - `[[slack_select: Choose a target | Canary:canary, Production:production]]` -Essas diretivas são compiladas em 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 em Slack Block Kit e roteiam cliques ou seleções de volta pelo caminho existente de eventos de interação do Slack. 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 pelo agente. -- 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 um payload de blocos inválido. +- Se os blocos interativos gerados excederem os limites do Slack Block Kit, o OpenClaw usa fallback para a resposta de texto original em vez de enviar uma carga de blocos inválida. ## Aprovações de exec no Slack -O Slack pode atuar como um cliente nativo de aprovação com botões interativos e interações, em vez de recorrer à Web UI ou ao terminal. +O Slack pode atuar como um cliente nativo de aprovação com botões interativos e interações, em vez de usar fallback para a Web UI ou terminal. -- Aprovações de exec usam `channels.slack.execApprovals.*` para roteamento nativo em DM/canal. -- Aprovações de plugin ainda podem ser resolvidas pela mesma superfície nativa de botões do Slack quando a solicitação já chega ao Slack e o tipo de 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. +- As aprovações de exec usam `channels.slack.execApprovals.*` para roteamento nativo em DM/canal. +- As aprovações de plugin ainda podem ser resolvidas pela mesma superfície nativa de botões do Slack quando a solicitação já chega ao Slack e o tipo de id de aprovação é `plugin:`. +- A autorização do aprovador ainda é aplicada: apenas 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 que outros canais. Quando `interactivity` está ativado nas configurações do seu app do Slack, os 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 -deve incluir um comando manual `/approve` somente quando o resultado da ferramenta disser que -aprovações no chat não estão disponíveis ou que a aprovação manual é o único caminho. +deve incluir um comando manual `/approve` apenas quando o resultado da ferramenta indicar que aprovações por chat não estão disponíveis ou que a aprovação manual é o único caminho. Caminho de configuração: @@ -633,7 +638,7 @@ Caminho de configuração: O Slack ativa automaticamente aprovações nativas de exec quando `enabled` não está definido ou é `"auto"` e pelo menos um aprovador é resolvido. Defina `enabled: false` para desativar explicitamente o Slack como cliente nativo de aprovação. -Defina `enabled: true` para forçar aprovações nativas quando aprovadores forem resolvidos. +Defina `enabled: true` para forçar aprovações nativas quando os aprovadores forem resolvidos. Comportamento padrão sem configuração explícita de aprovação de exec no Slack: @@ -646,7 +651,7 @@ Comportamento padrão sem configuração explícita de aprovação de exec no Sl ``` A configuração explícita nativa do Slack só é necessária quando você quer substituir aprovadores, adicionar filtros ou -optar pela entrega no chat de origem: +optar por entrega no chat de origem: ```json5 { @@ -662,24 +667,24 @@ optar pela entrega no chat de origem: } ``` -O encaminhamento compartilhado de `approvals.exec` é separado. Use-o somente quando prompts de aprovação de exec também precisarem -ser encaminhados para outros chats ou destinos 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 +O encaminhamento compartilhado `approvals.exec` é separado. Use-o somente quando os prompts de aprovação de exec também precisarem +ser roteados para outros chats ou destinos explícitos fora de banda. O encaminhamento compartilhado `approvals.plugin` também é +separado; os botões nativos do Slack ainda podem resolver aprovações de plugin quando essas solicitações já chegam ao Slack. -O mesmo chat `/approve` 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 o modelo completo de encaminhamento de aprovações. +O mesmo chat com `/approve` 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 o modelo completo de encaminhamento de aprovações. ## Eventos e comportamento operacional -- Edições/exclusões de mensagem/transmissões de thread são mapeadas para eventos de sistema. -- Eventos de adicionar/remover reação são mapeados para eventos de sistema. -- Eventos de entrada/saída de membro, canal criado/renomeado e adicionar/remover pin são mapeados para eventos de sistema. +- Edições/exclusões de mensagens/transmissões de thread são mapeadas para eventos do sistema. +- Eventos de adicionar/remover reação são mapeados para eventos do sistema. +- Eventos de entrada/saída de membro, canal criado/renomeado e adicionar/remover pin são mapeados para eventos do sistema. - `channel_id_changed` pode migrar chaves de configuração de canal quando `configWrites` está ativado. - Metadados de tópico/finalidade 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 do histórico da thread são filtrados pelas listas configuradas de permissões de remetente quando aplicável. -- Ações de bloco e interações de modal emitem eventos de sistema estruturados `Slack interaction: ...` com campos ricos de payload: +- O autor inicial da thread e a semeadura inicial de contexto do histórico da thread são filtrados por allowlists de remetente configuradas, quando aplicável. +- Ações de bloco e interações de modal emitem eventos estruturados de sistema `Slack interaction: ...` com campos ricos de carga: - ações de bloco: valores selecionados, rótulos, valores de seletor e metadados `workflow_*` - - eventos de modal `view_submission` e `view_closed` com metadados de canal roteados e entradas de formulário + - eventos modais `view_submission` e `view_closed` com metadados de canal roteados e entradas de formulário ## Ponteiros de referência de configuração @@ -688,12 +693,12 @@ Referência principal: - [Referência de configuração - Slack](/pt-BR/gateway/configuration-reference#slack) Campos de Slack de alto sinal: - - modo/auth: `mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*` + - modo/autenticação: `mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*` - acesso a DM: `dm.enabled`, `dmPolicy`, `allowFrom` (legado: `dm.policy`, `dm.allowFrom`), `dm.groupEnabled`, `dm.groupChannels` - - alternância de compatibilidade: `dangerouslyAllowNameMatching` (último recurso; mantenha desativado a menos que seja necessário) + - alternância de compatibilidade: `dangerouslyAllowNameMatching` (quebra-galho; mantenha desativado, a menos que seja necessário) - acesso a canal: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention` - threading/histórico: `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` - - entrega: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `nativeStreaming` + - entrega: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `streaming.nativeTransport` - operações/recursos: `configWrites`, `commands.native`, `slashCommand.*`, `actions.*`, `userToken`, `userTokenReadOnly` ## Solução de problemas @@ -703,9 +708,9 @@ Referência principal: Verifique, nesta ordem: - `groupPolicy` - - lista de permissões de canal (`channels.slack.channels`) + - allowlist de canais (`channels.slack.channels`) - `requireMention` - - lista de permissões `users` por canal + - allowlist `users` por canal Comandos úteis: @@ -722,7 +727,7 @@ openclaw doctor - `channels.slack.dm.enabled` - `channels.slack.dmPolicy` (ou legado `channels.slack.dm.policy`) - - aprovações de pareamento / entradas de lista de permissões + - aprovações de pareamento / entradas de allowlist ```bash openclaw pairing list slack @@ -730,37 +735,37 @@ openclaw pairing list slack - + Valide os tokens de bot + app e a ativação do Socket Mode nas configurações do app do Slack. Se `openclaw channels status --probe --json` mostrar `botTokenStatus` ou `appTokenStatus: "configured_unavailable"`, a conta do Slack está - configurada, mas o runtime atual não conseguiu resolver o valor + configurada, mas o tempo de execução atual não conseguiu resolver o valor respaldado por SecretRef. - + Valide: - signing secret - caminho do webhook - - URLs de solicitação do Slack (Events + Interactivity + Slash Commands) + - URLs de solicitação do Slack (Eventos + Interatividade + Comandos de barra) - `webhookPath` exclusivo por conta HTTP Se `signingSecretStatus: "configured_unavailable"` aparecer nos snapshots - da conta, a conta HTTP está configurada, mas o runtime atual não conseguiu + de conta, a conta HTTP está configurada, mas o tempo de execução atual não conseguiu resolver o signing secret respaldado por SecretRef. - - Verifique se a sua intenção era: + + Verifique se sua intenção era: - modo de comando nativo (`channels.slack.commands.native: true`) com comandos de barra correspondentes registrados no Slack - ou modo de comando de barra único (`channels.slack.slashCommand.enabled: true`) - Verifique também `commands.useAccessGroups` e as listas de permissões de canal/usuário. + Verifique também `commands.useAccessGroups` e allowlists de canal/usuário. diff --git a/docs/pt-BR/concepts/memory.md b/docs/pt-BR/concepts/memory.md index 5058154c8..b12f76340 100644 --- a/docs/pt-BR/concepts/memory.md +++ b/docs/pt-BR/concepts/memory.md @@ -1,14 +1,14 @@ --- read_when: - Você quer entender como a memória funciona - - Você quer saber em quais arquivos de memória escrever + - Você quer saber quais arquivos de memória escrever summary: Como o OpenClaw se lembra das coisas entre sessões title: Visão geral da memória x-i18n: - generated_at: "2026-04-06T03:06:38Z" + generated_at: "2026-04-08T05:26:41Z" model: gpt-5.4 provider: openai - source_hash: d19d4fa9c4b3232b7a97f7a382311d2a375b562040de15e9fe4a0b1990b825e7 + source_hash: 3bb8552341b0b651609edaaae826a22fdc535d240aed4fad4af4b069454004af source_path: concepts/memory.md workflow: 15 --- @@ -16,19 +16,19 @@ x-i18n: # Visão geral da memória O OpenClaw se lembra das coisas gravando **arquivos Markdown simples** no -workspace do seu agente. O modelo só "se lembra" do que é salvo em disco -- não +workspace do seu agente. O modelo só “se lembra” do que é salvo em disco -- não há estado oculto. ## Como funciona Seu agente tem três arquivos relacionados à memória: -- **`MEMORY.md`** -- memória de longo prazo. Fatos duráveis, preferências e +- **`MEMORY.md`** -- memória de longo prazo. Fatos duradouros, preferências e decisões. Carregado no início de toda sessão de DM. -- **`memory/YYYY-MM-DD.md`** -- notas diárias. Contexto em andamento e - observações. As notas de hoje e de ontem são carregadas automaticamente. +- **`memory/YYYY-MM-DD.md`** -- notas diárias. Contexto contínuo e observações. + As notas de hoje e de ontem são carregadas automaticamente. - **`DREAMS.md`** (experimental, opcional) -- Diário de Sonhos e resumos das - varreduras de sonho para revisão humana. + varreduras de sonhos para revisão humana. Esses arquivos ficam no workspace do agente (padrão `~/.openclaw/workspace`). @@ -41,11 +41,34 @@ eu prefiro TypeScript." Ele gravará isso no arquivo apropriado. O agente tem duas ferramentas para trabalhar com memória: -- **`memory_search`** -- encontra notas relevantes usando busca semântica, mesmo - quando a formulação difere da original. -- **`memory_get`** -- lê um arquivo de memória específico ou um intervalo de linhas. +- **`memory_search`** -- encontra notas relevantes usando busca semântica, + mesmo quando a formulação difere da original. +- **`memory_get`** -- lê um arquivo de memória específico ou um intervalo de + linhas. -Ambas as ferramentas são fornecidas pelo plugin de memória ativo (padrão: `memory-core`). +Ambas as ferramentas são fornecidas pelo plugin de memória ativo (padrão: +`memory-core`). + +## Plugin complementar Memory Wiki + +Se você quiser que a memória duradoura se comporte mais como uma base de +conhecimento mantida do que apenas notas brutas, use o plugin integrado +`memory-wiki`. + +O `memory-wiki` compila o conhecimento duradouro em um cofre wiki com: + +- estrutura de páginas determinística +- afirmações e evidências estruturadas +- rastreamento de contradições e atualidade +- painéis gerados +- resumos compilados para consumidores do agente/runtime +- ferramentas nativas de wiki como `wiki_search`, `wiki_get`, `wiki_apply` e `wiki_lint` + +Ele não substitui o plugin de memória ativo. O plugin de memória ativo ainda +controla recordação, promoção e sonhos. O `memory-wiki` adiciona uma camada de +conhecimento rica em procedência ao lado dele. + +Veja [Memory Wiki](/pt-BR/plugins/memory-wiki). ## Busca de memória @@ -57,77 +80,88 @@ provedor compatível. O OpenClaw detecta automaticamente seu provedor de embeddings a partir das -chaves de API disponíveis. Se você tiver uma chave OpenAI, Gemini, Voyage ou +chaves de API disponíveis. Se você tiver uma chave da OpenAI, Gemini, Voyage ou Mistral configurada, a busca de memória será ativada automaticamente. -Para detalhes sobre como a busca funciona, opções de ajuste e configuração de -provedor, consulte [Busca de memória](/pt-BR/concepts/memory-search). +Para detalhes sobre como a busca funciona, opções de ajuste e configuração do +provedor, veja [Memory Search](/pt-BR/concepts/memory-search). ## Backends de memória -Baseado em SQLite. Funciona imediatamente com busca por palavra-chave, similaridade vetorial e -busca híbrida. Sem dependências extras. +Baseado em SQLite. Funciona imediatamente com busca por palavra-chave, +similaridade vetorial e busca híbrida. Sem dependências extras. -Sidecar local-first com reranking, expansão de consulta e a capacidade de indexar -diretórios fora do workspace. +Sidecar local-first com reranqueamento, expansão de consulta e a capacidade de +indexar diretórios fora do workspace. -Memória entre sessões nativa para IA com modelagem de usuário, busca semântica e -consciência multiagente. Instalação por plugin. +Memória entre sessões nativa de IA com modelagem de usuário, busca semântica e +consciência de múltiplos agentes. Instalação por plugin. -## Flush automático da memória +## Camada wiki de conhecimento + + + +Compila a memória duradoura em um cofre wiki rico em procedência com +afirmações, painéis, modo bridge e fluxos de trabalho compatíveis com Obsidian. + + + +## Descarga automática de memória Antes que a [compactação](/pt-BR/concepts/compaction) resuma sua conversa, o OpenClaw -executa um turno silencioso que lembra o agente de salvar contexto importante em -arquivos de memória. Isso vem ativado por padrão -- você não precisa configurar nada. +executa um turno silencioso que lembra o agente de salvar contexto importante +em arquivos de memória. Isso vem ativado por padrão -- você não precisa +configurar nada. -O flush da memória evita perda de contexto durante a compactação. Se o seu +A descarga de memória evita perda de contexto durante a compactação. Se o seu agente tiver fatos importantes na conversa que ainda não foram gravados em um -arquivo, eles serão salvos automaticamente antes de o resumo acontecer. +arquivo, eles serão salvos automaticamente antes que o resumo aconteça. -## Dreaming (experimental) +## Sonhos (experimental) -Dreaming é uma etapa opcional de consolidação de memória em segundo plano. Ela coleta -sinais de curto prazo, pontua candidatos e promove apenas itens qualificados para a -memória de longo prazo (`MEMORY.md`). +Sonhos é uma etapa opcional de consolidação de memória em segundo plano. Ela +coleta sinais de curto prazo, pontua candidatos e promove apenas itens +qualificados para a memória de longo prazo (`MEMORY.md`). Ela foi projetada para manter a memória de longo prazo com alto sinal: -- **Opt-in**: desativada por padrão. -- **Agendada**: quando ativado, `memory-core` gerencia automaticamente um job cron recorrente - para uma varredura completa de dreaming. -- **Com limiares**: as promoções precisam passar por critérios de pontuação, frequência de recuperação e - diversidade de consultas. -- **Revisável**: resumos de fase e entradas de diário são gravados em `DREAMS.md` - para revisão humana. +- **Opt-in**: desativado por padrão. +- **Agendado**: quando ativado, o `memory-core` gerencia automaticamente um job + recorrente de cron para uma varredura completa de sonhos. +- **Com limiar**: as promoções precisam passar por critérios de pontuação, + frequência de recordação e diversidade de consulta. +- **Revisável**: resumos de fase e entradas do diário são gravados em + `DREAMS.md` para revisão humana. -Para comportamento por fase, sinais de pontuação e detalhes do Diário de Sonhos, consulte -[Dreaming (experimental)](/concepts/dreaming). +Para comportamento por fase, sinais de pontuação e detalhes do Diário de +Sonhos, veja [Dreaming (experimental)](/pt-BR/concepts/dreaming). ## CLI ```bash -openclaw memory status # Verifica o status do índice e do provedor -openclaw memory search "query" # Pesquisa pela linha de comando -openclaw memory index --force # Reconstrói o índice +openclaw memory status # Verificar status do índice e do provedor +openclaw memory search "query" # Pesquisar pela linha de comando +openclaw memory index --force # Reconstruir o índice ``` ## Leitura adicional - [Builtin Memory Engine](/pt-BR/concepts/memory-builtin) -- backend SQLite padrão - [QMD Memory Engine](/pt-BR/concepts/memory-qmd) -- sidecar local-first avançado -- [Honcho Memory](/pt-BR/concepts/memory-honcho) -- memória entre sessões nativa para IA -- [Busca de memória](/pt-BR/concepts/memory-search) -- pipeline de busca, provedores e +- [Honcho Memory](/pt-BR/concepts/memory-honcho) -- memória nativa de IA entre sessões +- [Memory Wiki](/pt-BR/plugins/memory-wiki) -- cofre de conhecimento compilado e ferramentas nativas de wiki +- [Memory Search](/pt-BR/concepts/memory-search) -- pipeline de busca, provedores e ajuste -- [Dreaming (experimental)](/concepts/dreaming) -- promoção em segundo plano - da recuperação de curto prazo para a memória de longo prazo -- [Referência de configuração de memória](/pt-BR/reference/memory-config) -- todos os parâmetros de configuração -- [Compactação](/pt-BR/concepts/compaction) -- como a compactação interage com a memória +- [Dreaming (experimental)](/pt-BR/concepts/dreaming) -- promoção em segundo plano + da recordação de curto prazo para a memória de longo prazo +- [Memory configuration reference](/pt-BR/reference/memory-config) -- todos os ajustes de configuração +- [Compaction](/pt-BR/concepts/compaction) -- como a compactação interage com a memória diff --git a/docs/pt-BR/concepts/model-providers.md b/docs/pt-BR/concepts/model-providers.md index eb61a4cc5..8f3780ea4 100644 --- a/docs/pt-BR/concepts/model-providers.md +++ b/docs/pt-BR/concepts/model-providers.md @@ -5,10 +5,10 @@ read_when: summary: Visão geral dos provedores de modelos com exemplos de configuração + fluxos da CLI title: Provedores de modelos x-i18n: - generated_at: "2026-04-08T02:15:49Z" + generated_at: "2026-04-08T05:28:35Z" model: gpt-5.4 provider: openai - source_hash: 26b36a2bc19a28a7ef39aa8e81a0050fea1d452ac4969122e5cdf8755e690258 + source_hash: 558ac9e34b67fcc3dd6791a01bebc17e1c34152fa6c5611593d681e8cfa532d9 source_path: concepts/model-providers.md workflow: 15 --- @@ -21,20 +21,21 @@ Para regras de seleção de modelos, consulte [/concepts/models](/pt-BR/concepts ## Regras rápidas - As referências de modelo usam `provider/model` (exemplo: `opencode/claude-opus-4-6`). -- Se você definir `agents.defaults.models`, isso se torna a allowlist. +- Se você definir `agents.defaults.models`, isso se tornará a lista de permissões. - Auxiliares da CLI: `openclaw onboard`, `openclaw models list`, `openclaw models set `. -- As regras de runtime de fallback, sondas de cooldown e persistência de substituição de sessão - estão documentadas em [/concepts/model-failover](/pt-BR/concepts/model-failover). -- `models.providers.*.models[].contextWindow` é metadado nativo do modelo; - `models.providers.*.models[].contextTokens` é o limite efetivo em runtime. -- Plugins de provedor podem injetar catálogos de modelos via `registerProvider({ catalog })`; +- Regras de fallback em tempo de execução, sondagens de cooldown e persistência + de substituição de sessão estão documentadas em + [/concepts/model-failover](/pt-BR/concepts/model-failover). +- `models.providers.*.models[].contextWindow` são metadados nativos do modelo; + `models.providers.*.models[].contextTokens` é o limite efetivo em tempo de execução. +- Plugins de provedor podem injetar catálogos de modelos por meio de `registerProvider({ catalog })`; o OpenClaw mescla essa saída em `models.providers` antes de gravar `models.json`. -- Manifestos de provedor podem declarar `providerAuthEnvVars` para que sondas genéricas - de autenticação baseadas em variáveis de ambiente não precisem carregar o runtime do plugin. O mapa - restante de variáveis de ambiente do núcleo agora fica apenas para provedores não baseados em plugin/do núcleo - e alguns casos genéricos de precedência, como onboarding Anthropic com prioridade para chave de API. -- Plugins de provedor também podem controlar o comportamento de runtime do provedor via +- Manifestos de provedor podem declarar `providerAuthEnvVars` para que sondagens + genéricas de autenticação baseadas em env não precisem carregar o runtime do plugin. O mapa + restante de variáveis de ambiente do core agora é apenas para provedores não-plugin/core e alguns + casos genéricos de precedência, como onboarding com prioridade para chave de API da Anthropic. +- Plugins de provedor também podem controlar o comportamento do runtime do provedor por meio de `normalizeModelId`, `normalizeTransport`, `normalizeConfig`, `applyNativeStreamingUsageCompat`, `resolveConfigApiKey`, `resolveSyntheticAuth`, `shouldDeferSyntheticProfileAuth`, @@ -52,198 +53,198 @@ Para regras de seleção de modelos, consulte [/concepts/models](/pt-BR/concepts `resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef`, `prepareRuntimeAuth`, `resolveUsageAuth`, `fetchUsageSnapshot`, e `onModelSelected`. -- Observação: `capabilities` do runtime do provedor são metadados compartilhados do executor (família - do provedor, peculiaridades de transcrição/ferramentas, dicas de transporte/cache). Isso não é o - mesmo que o [modelo de capacidades públicas](/pt-BR/plugins/architecture#public-capability-model), +- Observação: `capabilities` do runtime do provedor são metadados compartilhados do runner (família do provedor, + particularidades de transcrição/ferramentas, dicas de transporte/cache). Não é o + mesmo que o [modelo público de capacidades](/pt-BR/plugins/architecture#public-capability-model) que descreve o que um plugin registra (inferência de texto, fala etc.). ## Comportamento de provedor controlado por plugin -Agora os plugins de provedor podem controlar a maior parte da lógica específica do provedor, enquanto o OpenClaw mantém +Os plugins de provedor agora podem controlar a maior parte da lógica específica do provedor, enquanto o OpenClaw mantém o loop genérico de inferência. Divisão típica: -- `auth[].run` / `auth[].runNonInteractive`: o provedor controla os fluxos - de onboarding/login para `openclaw onboard`, `openclaw models auth` e configuração headless +- `auth[].run` / `auth[].runNonInteractive`: o provedor controla os fluxos de onboarding/login + para `openclaw onboard`, `openclaw models auth` e configuração sem interface - `wizard.setup` / `wizard.modelPicker`: o provedor controla rótulos de escolha de autenticação, - aliases legados, dicas de allowlist de onboarding e entradas de configuração nos seletores de onboarding/modelo + aliases legados, dicas de lista de permissões no onboarding e entradas de configuração nos seletores de onboarding/modelo - `catalog`: o provedor aparece em `models.providers` -- `normalizeModelId`: o provedor normaliza IDs de modelo legados/prévia antes da +- `normalizeModelId`: o provedor normaliza ids de modelos legados/prévia antes da busca ou canonização - `normalizeTransport`: o provedor normaliza `api` / `baseUrl` da família de transporte antes da montagem genérica do modelo; o OpenClaw verifica primeiro o provedor correspondente, depois outros plugins de provedor com suporte a hooks até que um realmente altere o transporte -- `normalizeConfig`: o provedor normaliza a configuração `models.providers.` antes - de o runtime usá-la; o OpenClaw verifica primeiro o provedor correspondente, depois outros +- `normalizeConfig`: o provedor normaliza a configuração `models.providers.` antes de o + runtime usá-la; o OpenClaw verifica primeiro o provedor correspondente, depois outros plugins de provedor com suporte a hooks até que um realmente altere a configuração. Se nenhum hook de provedor reescrever a configuração, os auxiliares agrupados da família Google ainda - normalizam as entradas de provedor Google compatíveis. -- `applyNativeStreamingUsageCompat`: o provedor aplica regravações de compatibilidade de uso nativo em streaming orientadas por endpoint para provedores de configuração -- `resolveConfigApiKey`: o provedor resolve autenticação por marcador de ambiente para provedores de configuração - sem forçar o carregamento completo da autenticação de runtime. `amazon-bedrock` também tem um - resolvedor interno de marcador de ambiente AWS aqui, embora a autenticação de runtime do Bedrock use - a cadeia padrão do AWS SDK. -- `resolveSyntheticAuth`: o provedor pode expor disponibilidade de autenticação local/self-hosted ou outra - autenticação baseada em configuração sem persistir segredos em texto simples + normalizam as entradas compatíveis de provedores Google. +- `applyNativeStreamingUsageCompat`: o provedor aplica reescritas de compatibilidade de uso de streaming nativo orientadas por endpoint para provedores de configuração +- `resolveConfigApiKey`: o provedor resolve autenticação por marcador env para provedores de configuração + sem forçar o carregamento completo da autenticação em runtime. `amazon-bedrock` também tem um + resolvedor embutido de marcador env da AWS aqui, embora a autenticação de runtime do Bedrock use + a cadeia padrão do SDK da AWS. +- `resolveSyntheticAuth`: o provedor pode expor disponibilidade de autenticação + local/self-hosted ou outra autenticação baseada em configuração sem persistir segredos em texto simples - `shouldDeferSyntheticProfileAuth`: o provedor pode marcar placeholders sintéticos de perfil armazenados - como de precedência inferior à autenticação baseada em ambiente/configuração -- `resolveDynamicModel`: o provedor aceita IDs de modelo ainda não presentes no + com precedência menor que a autenticação baseada em env/configuração +- `resolveDynamicModel`: o provedor aceita ids de modelos ainda não presentes no catálogo estático local -- `prepareDynamicModel`: o provedor precisa de uma atualização de metadados antes de tentar - novamente a resolução dinâmica -- `normalizeResolvedModel`: o provedor precisa de regravações de transporte ou URL base -- `contributeResolvedModelCompat`: o provedor contribui com flags de compatibilidade para seus - modelos do fornecedor, mesmo quando eles chegam por meio de outro transporte compatível -- `capabilities`: o provedor publica peculiaridades de transcrição/ferramentas/família de provedor -- `normalizeToolSchemas`: o provedor limpa os esquemas de ferramenta antes que o - executor incorporado os veja +- `prepareDynamicModel`: o provedor precisa de uma atualização de metadados antes de tentar novamente + a resolução dinâmica +- `normalizeResolvedModel`: o provedor precisa de reescritas de transporte ou URL base +- `contributeResolvedModelCompat`: o provedor contribui flags de compatibilidade para seus + modelos do fornecedor mesmo quando eles chegam por outro transporte compatível +- `capabilities`: o provedor publica particularidades de transcrição/ferramentas/família do provedor +- `normalizeToolSchemas`: o provedor limpa esquemas de ferramentas antes que o + runner incorporado os veja - `inspectToolSchemas`: o provedor expõe avisos de esquema específicos do transporte após a normalização -- `resolveReasoningOutputMode`: o provedor escolhe contratos de saída de raciocínio - nativos ou marcados +- `resolveReasoningOutputMode`: o provedor escolhe contratos nativos vs marcados + de saída de raciocínio - `prepareExtraParams`: o provedor define padrões ou normaliza parâmetros de requisição por modelo - `createStreamFn`: o provedor substitui o caminho normal de stream por um transporte totalmente personalizado -- `wrapStreamFn`: o provedor aplica wrappers de compatibilidade de cabeçalhos/corpo/modelo da requisição -- `resolveTransportTurnState`: o provedor fornece cabeçalhos nativos por turno do transporte - ou metadados -- `resolveWebSocketSessionPolicy`: o provedor fornece cabeçalhos nativos de sessão WebSocket - ou política de cooldown da sessão +- `wrapStreamFn`: o provedor aplica wrappers de compatibilidade a cabeçalhos/corpo/modelo da requisição +- `resolveTransportTurnState`: o provedor fornece + cabeçalhos ou metadados nativos de transporte por turno +- `resolveWebSocketSessionPolicy`: o provedor fornece + cabeçalhos de sessão nativos de WebSocket ou política de cooldown da sessão - `createEmbeddingProvider`: o provedor controla o comportamento de embeddings de memória quando isso - pertence ao plugin do provedor em vez do switchboard central de embeddings + pertence ao plugin do provedor em vez do comutador central de embeddings do core - `formatApiKey`: o provedor formata perfis de autenticação armazenados para a string - `apiKey` de runtime esperada pelo transporte + `apiKey` esperada pelo transporte em runtime - `refreshOAuth`: o provedor controla a atualização de OAuth quando os - atualizadores compartilhados de `pi-ai` não são suficientes -- `buildAuthDoctorHint`: o provedor acrescenta orientações de reparo quando a atualização de OAuth + atualizadores compartilhados `pi-ai` não são suficientes +- `buildAuthDoctorHint`: o provedor acrescenta orientação de reparo quando a atualização de OAuth falha - `matchesContextOverflowError`: o provedor reconhece erros específicos do provedor - de estouro da janela de contexto que heurísticas genéricas deixariam passar -- `classifyFailoverReason`: o provedor mapeia erros brutos específicos do provedor de transporte/API - para motivos de failover, como limite de taxa ou sobrecarga -- `isCacheTtlEligible`: o provedor decide quais IDs de modelo upstream oferecem suporte a TTL de cache de prompt + de estouro de janela de contexto que as heurísticas genéricas não detectariam +- `classifyFailoverReason`: o provedor mapeia erros brutos específicos do provedor em transporte/API + para razões de failover, como limite de taxa ou sobrecarga +- `isCacheTtlEligible`: o provedor decide quais ids de modelo upstream suportam TTL de cache de prompt - `buildMissingAuthMessage`: o provedor substitui o erro genérico do armazenamento de autenticação por uma dica de recuperação específica do provedor - `suppressBuiltInModel`: o provedor oculta linhas upstream desatualizadas e pode retornar um erro controlado pelo fornecedor para falhas de resolução direta -- `augmentModelCatalog`: o provedor acrescenta linhas sintéticas/finais do catálogo após +- `augmentModelCatalog`: o provedor acrescenta linhas sintéticas/finais de catálogo após descoberta e mesclagem de configuração - `isBinaryThinking`: o provedor controla a UX de pensamento binário ligado/desligado -- `supportsXHighThinking`: o provedor inclui modelos selecionados em `xhigh` +- `supportsXHighThinking`: o provedor habilita `xhigh` para modelos selecionados - `resolveDefaultThinkingLevel`: o provedor controla a política padrão de `/think` para uma família de modelos - `applyConfigDefaults`: o provedor aplica padrões globais específicos do provedor - durante a materialização da configuração com base no modo de autenticação, ambiente ou família de modelos -- `isModernModelRef`: o provedor controla a correspondência de modelo preferido em live/smoke -- `prepareRuntimeAuth`: o provedor transforma uma credencial configurada em um token - de runtime de curta duração + durante a materialização da configuração com base no modo de autenticação, env ou família de modelo +- `isModernModelRef`: o provedor controla a correspondência de modelo preferido para live/smoke +- `prepareRuntimeAuth`: o provedor converte uma credencial configurada em um token de runtime + de curta duração - `resolveUsageAuth`: o provedor resolve credenciais de uso/cota para `/usage` - e superfícies relacionadas de status/relatórios + e superfícies relacionadas de status/relatório - `fetchUsageSnapshot`: o provedor controla a busca/análise do endpoint de uso, enquanto - o núcleo ainda controla a estrutura de resumo e a formatação + o core ainda controla o shell de resumo e a formatação - `onModelSelected`: o provedor executa efeitos colaterais pós-seleção, como telemetria ou bookkeeping de sessão controlado pelo provedor -Exemplos agrupados atuais: +Exemplos agrupados atualmente: -- `anthropic`: fallback de compatibilidade futura para Claude 4.6, dicas de reparo de autenticação, busca de endpoint - de uso, metadados de cache-TTL/família de provedor e padrões globais - de configuração sensíveis à autenticação -- `amazon-bedrock`: correspondência de estouro de contexto controlada pelo provedor e classificação - de motivo de failover para erros Bedrock específicos de throttling/não pronto, além - da família compartilhada de replay `anthropic-by-model` para guardas de política de replay somente para Claude - em tráfego Anthropic -- `anthropic-vertex`: guardas de política de replay somente para Claude em tráfego +- `anthropic`: fallback de compatibilidade futura do Claude 4.6, dicas de reparo de autenticação, busca de + endpoint de uso, metadados de TTL de cache/família do provedor e padrões globais de + configuração sensíveis à autenticação +- `amazon-bedrock`: correspondência de estouro de contexto controlada pelo provedor e classificação de + motivo de failover para erros específicos do Bedrock de throttling/não pronto, além + da família compartilhada `anthropic-by-model` de replay para proteções de política de replay + apenas para Claude no tráfego Anthropic +- `anthropic-vertex`: proteções de política de replay apenas para Claude no tráfego de mensagens Anthropic -- `openrouter`: IDs de modelo pass-through, wrappers de requisição, dicas de capacidade do provedor, - sanitização de assinatura de pensamento Gemini em tráfego Gemini por proxy, - injeção de raciocínio de proxy por meio da família de stream `openrouter-thinking`, - encaminhamento de metadados de roteamento e política de cache-TTL -- `github-copilot`: onboarding/login por dispositivo, fallback de modelo compatível com versões futuras, - dicas de transcrição de pensamento Claude, troca de token em runtime e busca de endpoint - de uso -- `openai`: fallback de compatibilidade futura para GPT-5.4, normalização direta do transporte OpenAI, - dicas de autenticação ausente sensíveis a Codex, supressão de Spark, linhas sintéticas - de catálogo OpenAI/Codex, política de pensamento/modelo live, normalização de aliases - de token de uso (`input` / `output` e famílias `prompt` / `completion`), a - família compartilhada de stream `openai-responses-defaults` para wrappers nativos OpenAI/Codex, - metadados de família de provedor, registro agrupado de provedor de geração de imagens +- `openrouter`: ids de modelo pass-through, wrappers de requisição, dicas de capacidade do provedor, + sanitização de assinatura de pensamento do Gemini em tráfego Gemini via proxy, injeção de + raciocínio do proxy por meio da família de stream `openrouter-thinking`, encaminhamento de + metadados de roteamento e política de TTL de cache +- `github-copilot`: onboarding/login do dispositivo, fallback de modelo com compatibilidade futura, + dicas de transcrição de pensamento do Claude, troca de token em runtime e busca do endpoint de + uso +- `openai`: fallback de compatibilidade futura do GPT-5.4, normalização direta de + transporte OpenAI, dicas de autenticação ausente conscientes de Codex, supressão do Spark, linhas sintéticas de + catálogo OpenAI/Codex, política de pensamento/modelo live, normalização de alias de token de uso + (`input` / `output` e famílias `prompt` / `completion`), a família compartilhada de stream + `openai-responses-defaults` para wrappers nativos OpenAI/Codex, + metadados da família do provedor, registro agrupado de provedor de geração de imagem para `gpt-image-1` e registro agrupado de provedor de geração de vídeo para `sora-2` -- `google` e `google-gemini-cli`: fallback de compatibilidade futura para Gemini 3.1, - validação nativa de replay Gemini, sanitização de replay de bootstrap, modo - de saída de raciocínio marcado, correspondência de modelo moderno, registro agrupado de provedor de geração - de imagens para modelos Gemini image-preview e registro agrupado de - provedor de geração de vídeo para modelos Veo; o OAuth do Gemini CLI também - controla formatação de token de perfil de autenticação, análise de token de uso e busca - de endpoint de cota para superfícies de uso -- `moonshot`: transporte compartilhado, normalização de payload de pensamento controlada por plugin -- `kilocode`: transporte compartilhado, cabeçalhos de requisição controlados por plugin, payload de raciocínio - normalização, sanitização de assinatura de pensamento proxy-Gemini e política de cache-TTL -- `zai`: fallback de compatibilidade futura para GLM-5, padrões de `tool_stream`, política de cache-TTL, - política de pensamento binário/modelo live e autenticação de uso + busca de cota; - IDs desconhecidos `glm-5*` são sintetizados a partir do modelo agrupado `glm-4.7` -- `xai`: normalização nativa do transporte Responses, regravações do alias `/fast` para - variantes rápidas de Grok, padrão `tool_stream`, limpeza de esquema de ferramenta / +- `google` e `google-gemini-cli`: fallback de compatibilidade futura do Gemini 3.1, + validação nativa de replay do Gemini, sanitização de replay no bootstrap, modo marcado + de saída de raciocínio, correspondência de modelo moderno, registro agrupado de provedor de geração de imagem + para modelos Gemini image-preview e registro agrupado + de provedor de geração de vídeo para modelos Veo; o OAuth do Gemini CLI também + controla a formatação do token de perfil de autenticação, a análise do token de uso e a busca do endpoint de cota + para superfícies de uso +- `moonshot`: transporte compartilhado, normalização de payload de pensamento controlada pelo plugin +- `kilocode`: transporte compartilhado, cabeçalhos de requisição controlados pelo plugin, normalização de payload + de raciocínio, sanitização de assinatura de pensamento do Gemini via proxy e política de TTL de + cache +- `zai`: fallback de compatibilidade futura do GLM-5, padrões `tool_stream`, política de TTL de + cache, política de pensamento binário/modelo live e autenticação de uso + busca de cota; + ids desconhecidos `glm-5*` são sintetizados a partir do template agrupado `glm-4.7` +- `xai`: normalização nativa do transporte Responses, reescritas de alias `/fast` para + variantes rápidas do Grok, padrão `tool_stream`, limpeza de esquema de ferramenta / payload de raciocínio específica do xAI e registro agrupado de provedor de geração de vídeo para `grok-imagine-video` -- `mistral`: metadados de capacidade controlados por plugin -- `opencode` e `opencode-go`: metadados de capacidade controlados por plugin, além de - sanitização de assinatura de pensamento proxy-Gemini -- `alibaba`: catálogo de geração de vídeo controlado por plugin para referências diretas a modelos Wan +- `mistral`: metadados de capacidade controlados pelo plugin +- `opencode` e `opencode-go`: metadados de capacidade controlados pelo plugin, além + de sanitização de assinatura de pensamento do Gemini via proxy +- `alibaba`: catálogo de geração de vídeo controlado pelo plugin para referências diretas a modelos Wan como `alibaba/wan2.6-t2v` -- `byteplus`: catálogos controlados por plugin, além de registro agrupado de provedor de geração de vídeo - para modelos Seedance de texto para vídeo/imagem para vídeo -- `fal`: registro agrupado de provedor de geração de vídeo para provedor hospedado de terceiros - de geração de imagens para modelos de imagem FLUX, além de registro agrupado - de provedor de geração de vídeo para modelos de vídeo hospedados de terceiros +- `byteplus`: catálogos controlados pelo plugin, além de registro agrupado de provedor de geração de vídeo + para modelos Seedance text-to-video/image-to-video +- `fal`: registro agrupado de provedor de geração de vídeo para terceiros hospedados + e registro agrupado de provedor de geração de imagem para modelos de imagem FLUX, além de registro agrupado + de provedor de geração de vídeo para modelos de vídeo de terceiros hospedados - `cloudflare-ai-gateway`, `huggingface`, `kimi`, `nvidia`, `qianfan`, `stepfun`, `synthetic`, `venice`, `vercel-ai-gateway` e `volcengine`: - apenas catálogos controlados por plugin -- `qwen`: catálogos controlados por plugin para modelos de texto, além de registros compartilhados - de provedores de compreensão de mídia e geração de vídeo para suas - superfícies multimodais; a geração de vídeo do Qwen usa os endpoints de vídeo Standard DashScope + apenas catálogos controlados pelo plugin +- `qwen`: catálogos controlados pelo plugin para modelos de texto, além de registros compartilhados + de provedores de compreensão de mídia e geração de vídeo para suas superfícies + multimodais; a geração de vídeo do Qwen usa os endpoints de vídeo Standard DashScope com modelos Wan agrupados como `wan2.6-t2v` e `wan2.7-r2v` -- `runway`: registro controlado por plugin de provedor de geração de vídeo para modelos nativos +- `runway`: registro de provedor de geração de vídeo controlado pelo plugin para modelos nativos baseados em tarefas do Runway, como `gen4.5` -- `minimax`: catálogos controlados por plugin, registro agrupado de provedor de geração de vídeo +- `minimax`: catálogos controlados pelo plugin, registro agrupado de provedor de geração de vídeo para modelos de vídeo Hailuo, registro agrupado de provedor de geração de imagem - para `image-01`, seleção híbrida de política de replay Anthropic/OpenAI - e lógica de autenticação/snapshot de uso -- `together`: catálogos controlados por plugin, além de registro agrupado de provedor de geração de vídeo + para `image-01`, seleção híbrida de política de replay Anthropic/OpenAI e lógica de autenticação/snapshot de uso +- `together`: catálogos controlados pelo plugin, além de registro agrupado de provedor de geração de vídeo para modelos de vídeo Wan -- `xiaomi`: catálogos controlados por plugin, além de lógica de autenticação/snapshot de uso +- `xiaomi`: catálogos controlados pelo plugin, além de lógica de autenticação/snapshot de uso -O plugin agrupado `openai` agora controla ambos os IDs de provedor: `openai` e +O plugin agrupado `openai` agora controla ambos os ids de provedor: `openai` e `openai-codex`. Isso cobre provedores que ainda se encaixam nos transportes normais do OpenClaw. Um provedor -que precise de um executor de requisição totalmente personalizado pertence a uma superfície -de extensão separada e mais profunda. +que precise de um executor de requisições totalmente personalizado é uma superfície de extensão +separada e mais profunda. ## Rotação de chaves de API - Suporta rotação genérica de provedor para provedores selecionados. -- Configure múltiplas chaves via: - - `OPENCLAW_LIVE__KEY` (única substituição live, prioridade mais alta) +- Configure várias chaves por meio de: + - `OPENCLAW_LIVE__KEY` (substituição live única, maior prioridade) - `_API_KEYS` (lista separada por vírgula ou ponto e vírgula) - `_API_KEY` (chave primária) - - `_API_KEY_*` (lista numerada, por exemplo `_API_KEY_1`) + - `_API_KEY_*` (lista numerada, ex.: `_API_KEY_1`) - Para provedores Google, `GOOGLE_API_KEY` também é incluída como fallback. - A ordem de seleção de chaves preserva a prioridade e remove valores duplicados. -- As requisições são repetidas com a próxima chave apenas em respostas de limite de taxa (por +- As requisições são tentadas novamente com a próxima chave apenas em respostas de limite de taxa (por exemplo `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` ou mensagens periódicas de limite de uso). -- Falhas que não sejam de limite de taxa falham imediatamente; nenhuma rotação de chave é tentada. -- Quando todas as chaves candidatas falham, o erro final da última tentativa é retornado. +- Falhas que não são de limite de taxa falham imediatamente; nenhuma rotação de chave é tentada. +- Quando todas as chaves candidatas falham, o erro final é retornado a partir da última tentativa. ## Provedores integrados (catálogo pi-ai) O OpenClaw vem com o catálogo pi‑ai. Esses provedores não exigem -configuração em `models.providers`; basta definir a autenticação + escolher um modelo. +configuração `models.providers`; basta definir a autenticação + escolher um modelo. ### OpenAI @@ -255,14 +256,14 @@ configuração em `models.providers`; basta definir a autenticação + escolher - O transporte padrão é `auto` (WebSocket primeiro, fallback para SSE) - Substitua por modelo via `agents.defaults.models["openai/"].params.transport` (`"sse"`, `"websocket"` ou `"auto"`) - O aquecimento do WebSocket do OpenAI Responses vem ativado por padrão via `params.openaiWsWarmup` (`true`/`false`) -- O processamento prioritário da OpenAI pode ser ativado via `agents.defaults.models["openai/"].params.serviceTier` +- O processamento prioritário da OpenAI pode ser ativado por meio de `agents.defaults.models["openai/"].params.serviceTier` - `/fast` e `params.fastMode` mapeiam requisições diretas `openai/*` Responses para `service_tier=priority` em `api.openai.com` - Use `params.serviceTier` quando quiser uma camada explícita em vez do toggle compartilhado `/fast` - Cabeçalhos ocultos de atribuição do OpenClaw (`originator`, `version`, - `User-Agent`) se aplicam apenas ao tráfego nativo da OpenAI para `api.openai.com`, não a + `User-Agent`) se aplicam apenas ao tráfego nativo OpenAI para `api.openai.com`, não a proxies genéricos compatíveis com OpenAI -- As rotas nativas da OpenAI também mantêm `store` do Responses, dicas de cache de prompt e - modelagem de payload de compatibilidade de raciocínio da OpenAI; rotas por proxy não +- Rotas nativas OpenAI também mantêm `store` do Responses, dicas de cache de prompt e + modelagem de payload de compatibilidade de raciocínio OpenAI; rotas proxy não - `openai/gpt-5.3-codex-spark` é intencionalmente suprimido no OpenClaw porque a API live da OpenAI o rejeita; Spark é tratado apenas como Codex ```json5 @@ -278,9 +279,9 @@ configuração em `models.providers`; basta definir a autenticação + escolher - Rotação opcional: `ANTHROPIC_API_KEYS`, `ANTHROPIC_API_KEY_1`, `ANTHROPIC_API_KEY_2`, além de `OPENCLAW_LIVE_ANTHROPIC_KEY` (substituição única) - Modelo de exemplo: `anthropic/claude-opus-4-6` - CLI: `openclaw onboard --auth-choice apiKey` -- Requisições públicas diretas à Anthropic suportam o toggle compartilhado `/fast` e `params.fastMode`, incluindo tráfego autenticado com chave de API e OAuth enviado a `api.anthropic.com`; o OpenClaw mapeia isso para `service_tier` da Anthropic (`auto` vs `standard_only`) -- Observação sobre Anthropic: a equipe da Anthropic nos informou que o uso estilo Claude CLI no OpenClaw é permitido novamente, então o OpenClaw trata a reutilização do Claude CLI e o uso de `claude -p` como autorizados para esta integração, a menos que a Anthropic publique uma nova política. -- O token de configuração da Anthropic continua disponível como um caminho de token compatível no OpenClaw, mas o OpenClaw agora prefere a reutilização do Claude CLI e `claude -p` quando disponíveis. +- Requisições públicas diretas à Anthropic suportam o toggle compartilhado `/fast` e `params.fastMode`, incluindo tráfego autenticado por chave de API e OAuth enviado para `api.anthropic.com`; o OpenClaw mapeia isso para `service_tier` da Anthropic (`auto` vs `standard_only`) +- Observação da Anthropic: a equipe da Anthropic nos informou que o uso do Claude CLI no estilo OpenClaw está novamente permitido, então o OpenClaw trata a reutilização do Claude CLI e o uso de `claude -p` como permitidos para esta integração, a menos que a Anthropic publique uma nova política. +- O token de configuração da Anthropic continua disponível como um caminho de token suportado pelo OpenClaw, mas o OpenClaw agora prefere a reutilização do Claude CLI e `claude -p` quando disponíveis. ```json5 { @@ -298,11 +299,11 @@ configuração em `models.providers`; basta definir a autenticação + escolher - Substitua por modelo via `agents.defaults.models["openai-codex/"].params.transport` (`"sse"`, `"websocket"` ou `"auto"`) - `params.serviceTier` também é encaminhado em requisições nativas do Codex Responses (`chatgpt.com/backend-api`) - Cabeçalhos ocultos de atribuição do OpenClaw (`originator`, `version`, - `User-Agent`) são anexados apenas ao tráfego nativo de Codex para + `User-Agent`) são anexados apenas ao tráfego nativo Codex para `chatgpt.com/backend-api`, não a proxies genéricos compatíveis com OpenAI -- Compartilha o mesmo toggle `/fast` e a mesma configuração `params.fastMode` de `openai/*` direto; o OpenClaw mapeia isso para `service_tier=priority` +- Compartilha o mesmo toggle `/fast` e a configuração `params.fastMode` de `openai/*` direto; o OpenClaw mapeia isso para `service_tier=priority` - `openai-codex/gpt-5.3-codex-spark` continua disponível quando o catálogo OAuth do Codex o expõe; depende de entitlement -- `openai-codex/gpt-5.4` mantém `contextWindow = 1050000` nativo e um `contextTokens = 272000` padrão em runtime; substitua o limite de runtime com `models.providers.openai-codex.models[].contextTokens` +- `openai-codex/gpt-5.4` mantém `contextWindow = 1050000` nativo e um padrão de runtime `contextTokens = 272000`; substitua o limite de runtime com `models.providers.openai-codex.models[].contextTokens` - Observação de política: o OAuth do OpenAI Codex é explicitamente compatível com ferramentas/fluxos de trabalho externos como o OpenClaw. ```json5 @@ -325,9 +326,9 @@ configuração em `models.providers`; basta definir a autenticação + escolher ### Outras opções hospedadas no estilo assinatura -- [Qwen Cloud](/pt-BR/providers/qwen): superfície de provedor do Qwen Cloud, além de mapeamento de endpoint Alibaba DashScope e Coding Plan -- [MiniMax](/pt-BR/providers/minimax): acesso ao OAuth ou à chave de API do MiniMax Coding Plan -- [GLM Models](/pt-BR/providers/glm): Z.AI Coding Plan ou endpoints gerais de API +- [Qwen Cloud](/pt-BR/providers/qwen): superfície de provedor Qwen Cloud, além de mapeamento de endpoint do Alibaba DashScope e Coding Plan +- [MiniMax](/pt-BR/providers/minimax): acesso ao OAuth ou chave de API do MiniMax Coding Plan +- [GLM Models](/pt-BR/providers/glm): endpoints do Z.AI Coding Plan ou API geral ### OpenCode @@ -347,9 +348,9 @@ configuração em `models.providers`; basta definir a autenticação + escolher - Provedor: `google` - Autenticação: `GEMINI_API_KEY` -- Rotação opcional: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, fallback para `GOOGLE_API_KEY` e `OPENCLAW_LIVE_GEMINI_KEY` (substituição única) +- Rotação opcional: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, fallback `GOOGLE_API_KEY` e `OPENCLAW_LIVE_GEMINI_KEY` (substituição única) - Modelos de exemplo: `google/gemini-3.1-pro-preview`, `google/gemini-3-flash-preview` -- Compatibilidade: configuração legada do OpenClaw que usa `google/gemini-3.1-flash-preview` é normalizada para `google/gemini-3-flash-preview` +- Compatibilidade: a configuração legada do OpenClaw usando `google/gemini-3.1-flash-preview` é normalizada para `google/gemini-3-flash-preview` - CLI: `openclaw onboard --auth-choice gemini-api-key` - Execuções diretas do Gemini também aceitam `agents.defaults.models["google/"].params.cachedContent` (ou o legado `cached_content`) para encaminhar um identificador nativo do provedor @@ -358,8 +359,8 @@ configuração em `models.providers`; basta definir a autenticação + escolher ### Google Vertex e Gemini CLI - Provedores: `google-vertex`, `google-gemini-cli` -- Autenticação: Vertex usa gcloud ADC; Gemini CLI usa seu fluxo OAuth -- Atenção: o OAuth do Gemini CLI no OpenClaw é uma integração não oficial. Alguns usuários relataram restrições em contas Google após usar clientes de terceiros. Revise os termos do Google e use uma conta não crítica se optar por prosseguir. +- Autenticação: o Vertex usa gcloud ADC; o Gemini CLI usa seu fluxo OAuth +- Cuidado: o OAuth do Gemini CLI no OpenClaw é uma integração não oficial. Alguns usuários relataram restrições de conta Google após usar clientes de terceiros. Revise os termos do Google e use uma conta não crítica se optar por continuar. - O OAuth do Gemini CLI é distribuído como parte do plugin agrupado `google`. - Instale primeiro o Gemini CLI: - `brew install gemini-cli` @@ -367,7 +368,7 @@ configuração em `models.providers`; basta definir a autenticação + escolher - Ative: `openclaw plugins enable google` - Login: `openclaw models auth login --provider google-gemini-cli --set-default` - Modelo padrão: `google-gemini-cli/gemini-3-flash-preview` - - Observação: você **não** cola um client id nem um secret em `openclaw.json`. O fluxo de login da CLI armazena + - Observação: você **não** cola um client id nem secret em `openclaw.json`. O fluxo de login da CLI armazena tokens em perfis de autenticação no host do gateway. - Se as requisições falharem após o login, defina `GOOGLE_CLOUD_PROJECT` ou `GOOGLE_CLOUD_PROJECT_ID` no host do gateway. - Respostas JSON do Gemini CLI são analisadas a partir de `response`; o uso recorre a @@ -377,10 +378,10 @@ configuração em `models.providers`; basta definir a autenticação + escolher - Provedor: `zai` - Autenticação: `ZAI_API_KEY` -- Modelo de exemplo: `zai/glm-5` +- Modelo de exemplo: `zai/glm-5.1` - CLI: `openclaw onboard --auth-choice zai-api-key` - Aliases: `z.ai/*` e `z-ai/*` são normalizados para `zai/*` - - `zai-api-key` detecta automaticamente o endpoint correspondente da Z.AI; `zai-coding-global`, `zai-coding-cn`, `zai-global` e `zai-cn` forçam uma superfície específica + - `zai-api-key` detecta automaticamente o endpoint Z.AI correspondente; `zai-coding-global`, `zai-coding-cn`, `zai-global` e `zai-cn` forçam uma superfície específica ### Vercel AI Gateway @@ -399,7 +400,7 @@ configuração em `models.providers`; basta definir a autenticação + escolher - O catálogo estático de fallback inclui `kilocode/kilo/auto`; a descoberta live em `https://api.kilo.ai/api/gateway/models` pode expandir ainda mais o catálogo em runtime. -- O roteamento upstream exato por trás de `kilocode/kilo/auto` é controlado pelo Kilo Gateway, +- O roteamento exato upstream por trás de `kilocode/kilo/auto` é controlado pelo Kilo Gateway, não codificado diretamente no OpenClaw. Consulte [/providers/kilocode](/pt-BR/providers/kilocode) para detalhes de configuração. @@ -410,24 +411,24 @@ Consulte [/providers/kilocode](/pt-BR/providers/kilocode) para detalhes de confi - Modelo de exemplo: `openrouter/auto` - O OpenClaw aplica os cabeçalhos documentados de atribuição de aplicativo do OpenRouter apenas quando a requisição realmente tem como destino `openrouter.ai` -- Os marcadores `cache_control` específicos do OpenRouter para Anthropic também são limitados a - rotas verificadas do OpenRouter, não a URLs arbitrárias de proxy -- O OpenRouter continua no caminho compatível com OpenAI em estilo proxy, então a modelagem - nativa de requisição exclusiva da OpenAI (`serviceTier`, `store` do Responses, - dicas de cache de prompt, payloads de compatibilidade de raciocínio da OpenAI) não é encaminhada -- Referências do OpenRouter baseadas em Gemini mantêm apenas a sanitização de assinatura - de pensamento proxy-Gemini; validação de replay nativa do Gemini e regravações de bootstrap permanecem desativadas +- Marcadores `cache_control` específicos do OpenRouter para Anthropic também são limitados a + rotas verificadas do OpenRouter, não a URLs de proxy arbitrárias +- O OpenRouter permanece no caminho compatível com OpenAI no estilo proxy, então a modelagem nativa + de requisição exclusiva da OpenAI (`serviceTier`, `store` do Responses, + dicas de cache de prompt, payloads de compatibilidade de raciocínio OpenAI) não é encaminhada +- Referências do OpenRouter baseadas em Gemini mantêm apenas a sanitização de assinatura de pensamento do Gemini via proxy; + a validação nativa de replay do Gemini e as reescritas de bootstrap permanecem desativadas - Kilo Gateway: `kilocode` (`KILOCODE_API_KEY`) - Modelo de exemplo: `kilocode/kilo/auto` -- Referências Kilo baseadas em Gemini mantêm o mesmo caminho de sanitização de assinatura - de pensamento proxy-Gemini; `kilocode/kilo/auto` e outras - dicas de proxy sem suporte a raciocínio pulam a injeção de raciocínio por proxy +- Referências do Kilo baseadas em Gemini mantêm o mesmo caminho de sanitização de + assinatura de pensamento do Gemini via proxy; `kilocode/kilo/auto` e outras dicas + de proxy sem suporte a raciocínio ignoram a injeção de raciocínio do proxy - MiniMax: `minimax` (chave de API) e `minimax-portal` (OAuth) - Autenticação: `MINIMAX_API_KEY` para `minimax`; `MINIMAX_OAUTH_TOKEN` ou `MINIMAX_API_KEY` para `minimax-portal` - Modelo de exemplo: `minimax/MiniMax-M2.7` ou `minimax-portal/MiniMax-M2.7` -- A configuração de onboarding/chave de API do MiniMax grava definições explícitas do modelo M2.7 com +- A configuração do onboarding/chave de API do MiniMax grava definições explícitas de modelo M2.7 com `input: ["text", "image"]`; o catálogo agrupado do provedor mantém as referências de chat - apenas como texto até que a configuração desse provedor seja materializada + como somente texto até que a configuração do provedor seja materializada - Moonshot: `moonshot` (`MOONSHOT_API_KEY`) - Modelo de exemplo: `moonshot/kimi-k2.5` - Kimi Coding: `kimi` (`KIMI_API_KEY` ou `KIMICODE_API_KEY`) @@ -453,10 +454,10 @@ Consulte [/providers/kilocode](/pt-BR/providers/kilocode) para detalhes de confi - BytePlus: `byteplus` (`BYTEPLUS_API_KEY`) - Modelo de exemplo: `byteplus-plan/ark-code-latest` - xAI: `xai` (`XAI_API_KEY`) - - Requisições nativas agrupadas do xAI usam o caminho xAI Responses - - `/fast` ou `params.fastMode: true` regravam `grok-3`, `grok-3-mini`, + - Requisições xAI agrupadas nativas usam o caminho xAI Responses + - `/fast` ou `params.fastMode: true` reescreve `grok-3`, `grok-3-mini`, `grok-4` e `grok-4-0709` para suas variantes `*-fast` - - `tool_stream` vem ativado por padrão; defina + - `tool_stream` fica ativado por padrão; defina `agents.defaults.models["xai/"].params.tool_stream` como `false` para desativá-lo - Mistral: `mistral` (`MISTRAL_API_KEY`) @@ -464,14 +465,14 @@ Consulte [/providers/kilocode](/pt-BR/providers/kilocode) para detalhes de confi - CLI: `openclaw onboard --auth-choice mistral-api-key` - Groq: `groq` (`GROQ_API_KEY`) - Cerebras: `cerebras` (`CEREBRAS_API_KEY`) - - Modelos GLM no Cerebras usam os IDs `zai-glm-4.7` e `zai-glm-4.6`. + - Modelos GLM no Cerebras usam os ids `zai-glm-4.7` e `zai-glm-4.6`. - URL base compatível com OpenAI: `https://api.cerebras.ai/v1`. - GitHub Copilot: `github-copilot` (`COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN`) - Modelo de exemplo do Hugging Face Inference: `huggingface/deepseek-ai/DeepSeek-R1`; CLI: `openclaw onboard --auth-choice huggingface-api-key`. Consulte [Hugging Face (Inference)](/pt-BR/providers/huggingface). -## Provedores via `models.providers` (customizado/URL base) +## Provedores via `models.providers` (personalizado/URL base) -Use `models.providers` (ou `models.json`) para adicionar provedores **customizados** ou +Use `models.providers` (ou `models.json`) para adicionar provedores **personalizados** ou proxies compatíveis com OpenAI/Anthropic. Muitos dos plugins de provedor agrupados abaixo já publicam um catálogo padrão. @@ -480,7 +481,7 @@ URL base, os cabeçalhos ou a lista de modelos padrão. ### Moonshot AI (Kimi) -O Moonshot é fornecido como plugin de provedor agrupado. Use o provedor integrado por +O Moonshot é distribuído como um plugin de provedor agrupado. Use o provedor integrado por padrão e adicione uma entrada explícita `models.providers.moonshot` apenas quando precisar substituir a URL base ou os metadados do modelo: @@ -489,7 +490,7 @@ precisar substituir a URL base ou os metadados do modelo: - Modelo de exemplo: `moonshot/kimi-k2.5` - CLI: `openclaw onboard --auth-choice moonshot-api-key` ou `openclaw onboard --auth-choice moonshot-api-key-cn` -IDs de modelo do Kimi K2: +IDs de modelo Kimi K2: [//]: # "moonshot-kimi-k2-model-refs:start" @@ -521,7 +522,7 @@ IDs de modelo do Kimi K2: ### Kimi Coding -O Kimi Coding usa o endpoint compatível com Anthropic da Moonshot AI: +O Kimi Coding usa o endpoint compatível com Anthropic do Moonshot AI: - Provedor: `kimi` - Autenticação: `KIMI_API_KEY` @@ -536,7 +537,7 @@ O Kimi Coding usa o endpoint compatível com Anthropic da Moonshot AI: } ``` -O legado `kimi/k2p5` continua aceito como ID de modelo de compatibilidade. +O legado `kimi/k2p5` continua aceito como id de modelo de compatibilidade. ### Volcano Engine (Doubao) @@ -555,13 +556,13 @@ O Volcano Engine (火山引擎) fornece acesso ao Doubao e outros modelos na Chi } ``` -O onboarding usa a superfície de coding por padrão, mas o catálogo geral `volcengine/*` +O onboarding usa por padrão a superfície de coding, mas o catálogo geral `volcengine/*` é registrado ao mesmo tempo. -Nos seletores de onboarding/configuração de modelo, a escolha de autenticação do Volcengine prioriza ambos os -itens `volcengine/*` e `volcengine-plan/*`. Se esses modelos ainda não tiverem sido carregados, -o OpenClaw volta ao catálogo sem filtro em vez de mostrar um seletor vazio -com escopo de provedor. +Nos seletores de modelo de onboarding/configuração, a escolha de autenticação do Volcengine +prefere linhas `volcengine/*` e `volcengine-plan/*`. Se esses modelos ainda não estiverem carregados, +o OpenClaw recorre ao catálogo sem filtro em vez de mostrar um seletor +vazio com escopo de provedor. Modelos disponíveis: @@ -579,7 +580,7 @@ Modelos de coding (`volcengine-plan`): - `volcengine-plan/kimi-k2-thinking` - `volcengine-plan/glm-4.7` -### BytePlus (Internacional) +### BytePlus (internacional) O BytePlus ARK fornece acesso aos mesmos modelos do Volcano Engine para usuários internacionais. @@ -596,13 +597,13 @@ O BytePlus ARK fornece acesso aos mesmos modelos do Volcano Engine para usuário } ``` -O onboarding usa a superfície de coding por padrão, mas o catálogo geral `byteplus/*` +O onboarding usa por padrão a superfície de coding, mas o catálogo geral `byteplus/*` é registrado ao mesmo tempo. -Nos seletores de onboarding/configuração de modelo, a escolha de autenticação do BytePlus prioriza ambos os -itens `byteplus/*` e `byteplus-plan/*`. Se esses modelos ainda não tiverem sido carregados, -o OpenClaw volta ao catálogo sem filtro em vez de mostrar um seletor vazio -com escopo de provedor. +Nos seletores de modelo de onboarding/configuração, a escolha de autenticação do BytePlus +prefere linhas `byteplus/*` e `byteplus-plan/*`. Se esses modelos ainda não estiverem carregados, +o OpenClaw recorre ao catálogo sem filtro em vez de mostrar um seletor +vazio com escopo de provedor. Modelos disponíveis: @@ -648,34 +649,34 @@ O Synthetic fornece modelos compatíveis com Anthropic por trás do provedor `sy ### MiniMax -O MiniMax é configurado via `models.providers` porque usa endpoints customizados: +O MiniMax é configurado por meio de `models.providers` porque usa endpoints personalizados: -- MiniMax OAuth (Global): `--auth-choice minimax-global-oauth` +- MiniMax OAuth (global): `--auth-choice minimax-global-oauth` - MiniMax OAuth (CN): `--auth-choice minimax-cn-oauth` -- Chave de API do MiniMax (Global): `--auth-choice minimax-global-api` -- Chave de API do MiniMax (CN): `--auth-choice minimax-cn-api` +- Chave de API MiniMax (global): `--auth-choice minimax-global-api` +- Chave de API MiniMax (CN): `--auth-choice minimax-cn-api` - Autenticação: `MINIMAX_API_KEY` para `minimax`; `MINIMAX_OAUTH_TOKEN` ou `MINIMAX_API_KEY` para `minimax-portal` Consulte [/providers/minimax](/pt-BR/providers/minimax) para detalhes de configuração, opções de modelo e trechos de configuração. -No caminho de streaming compatível com Anthropic do MiniMax, o OpenClaw desativa thinking por -padrão, a menos que você o defina explicitamente, e `/fast on` regrava +No caminho de streaming compatível com Anthropic do MiniMax, o OpenClaw desativa o thinking por +padrão, a menos que você o defina explicitamente, e `/fast on` reescreve `MiniMax-M2.7` para `MiniMax-M2.7-highspeed`. -Divisão de capacidades controladas por plugin: +Divisão de capacidade controlada por plugin: - Os padrões de texto/chat permanecem em `minimax/MiniMax-M2.7` - A geração de imagem é `minimax/image-01` ou `minimax-portal/image-01` -- A compreensão de imagem é controlada por plugin com `MiniMax-VL-01` em ambos os caminhos de autenticação do MiniMax -- A pesquisa na web permanece no ID de provedor `minimax` +- A compreensão de imagem é `MiniMax-VL-01` controlado por plugin em ambos os caminhos de autenticação do MiniMax +- A busca na web permanece no id de provedor `minimax` ### Ollama -O Ollama é fornecido como plugin de provedor agrupado e usa a API nativa do Ollama: +O Ollama é distribuído como um plugin de provedor agrupado e usa a API nativa do Ollama: - Provedor: `ollama` -- Autenticação: não é necessária (servidor local) +- Autenticação: nenhuma obrigatória (servidor local) - Modelo de exemplo: `ollama/llama3.3` - Instalação: [https://ollama.com/download](https://ollama.com/download) @@ -692,15 +693,15 @@ ollama pull llama3.3 } ``` -O Ollama é detectado localmente em `http://127.0.0.1:11434` quando você ativa a opção com +O Ollama é detectado localmente em `http://127.0.0.1:11434` quando você opta por isso com `OLLAMA_API_KEY`, e o plugin de provedor agrupado adiciona o Ollama diretamente ao -`openclaw onboard` e ao seletor de modelo. Consulte [/providers/ollama](/pt-BR/providers/ollama) -para onboarding, modo local/nuvem e configuração personalizada. +`openclaw onboard` e ao seletor de modelos. Consulte [/providers/ollama](/pt-BR/providers/ollama) +para onboarding, modo nuvem/local e configuração personalizada. ### vLLM -O vLLM é fornecido como plugin de provedor agrupado para servidores -compatíveis com OpenAI locais/self-hosted: +O vLLM é distribuído como um plugin de provedor agrupado para servidores locais/self-hosted +compatíveis com OpenAI: - Provedor: `vllm` - Autenticação: opcional (depende do seu servidor) @@ -712,7 +713,7 @@ Para ativar a descoberta automática localmente (qualquer valor funciona se seu export VLLM_API_KEY="vllm-local" ``` -Depois defina um modelo (substitua por um dos IDs retornados por `/v1/models`): +Em seguida, defina um modelo (substitua por um dos ids retornados por `/v1/models`): ```json5 { @@ -726,8 +727,8 @@ Consulte [/providers/vllm](/pt-BR/providers/vllm) para detalhes. ### SGLang -O SGLang é fornecido como plugin de provedor agrupado para servidores -compatíveis com OpenAI self-hosted rápidos: +O SGLang é distribuído como um plugin de provedor agrupado para servidores self-hosted rápidos +compatíveis com OpenAI: - Provedor: `sglang` - Autenticação: opcional (depende do seu servidor) @@ -740,7 +741,7 @@ exigir autenticação): export SGLANG_API_KEY="sglang-local" ``` -Depois defina um modelo (substitua por um dos IDs retornados por `/v1/models`): +Em seguida, defina um modelo (substitua por um dos ids retornados por `/v1/models`): ```json5 { @@ -789,23 +790,23 @@ Exemplo (compatível com OpenAI): Observações: -- Para provedores customizados, `reasoning`, `input`, `cost`, `contextWindow` e `maxTokens` são opcionais. - Quando omitidos, o OpenClaw usa estes padrões: +- Para provedores personalizados, `reasoning`, `input`, `cost`, `contextWindow` e `maxTokens` são opcionais. + Quando omitidos, o OpenClaw usa por padrão: - `reasoning: false` - `input: ["text"]` - `cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }` - `contextWindow: 200000` - `maxTokens: 8192` - Recomendado: defina valores explícitos que correspondam aos limites do seu proxy/modelo. -- Para `api: "openai-completions"` em endpoints não nativos (qualquer `baseUrl` não vazia cujo host não seja `api.openai.com`), o OpenClaw força `compat.supportsDeveloperRole: false` para evitar erros 400 do provedor para papéis `developer` não compatíveis. -- Rotas compatíveis com OpenAI em estilo proxy também pulam a modelagem nativa de requisição exclusiva da OpenAI: - sem `service_tier`, sem `store` do Responses, sem dicas de cache de prompt, sem - modelagem de payload de compatibilidade de raciocínio da OpenAI e sem cabeçalhos ocultos - de atribuição do OpenClaw. -- Se `baseUrl` estiver vazia/omitida, o OpenClaw mantém o comportamento padrão da OpenAI (que resolve para `api.openai.com`). -- Por segurança, um `compat.supportsDeveloperRole: true` explícito ainda é sobrescrito em endpoints não nativos `openai-completions`. +- Para `api: "openai-completions"` em endpoints não nativos (qualquer `baseUrl` não vazio cujo host não seja `api.openai.com`), o OpenClaw força `compat.supportsDeveloperRole: false` para evitar erros 400 do provedor para papéis `developer` não compatíveis. +- Rotas no estilo proxy compatíveis com OpenAI também ignoram a modelagem nativa + de requisição exclusiva da OpenAI: sem `service_tier`, sem `store` do Responses, sem + dicas de cache de prompt, sem modelagem de payload de compatibilidade de raciocínio OpenAI e sem cabeçalhos + ocultos de atribuição do OpenClaw. +- Se `baseUrl` estiver vazio/omitido, o OpenClaw mantém o comportamento padrão da OpenAI (que resolve para `api.openai.com`). +- Por segurança, um `compat.supportsDeveloperRole: true` explícito ainda é sobrescrito em endpoints `openai-completions` não nativos. -## Exemplos de CLI +## Exemplos da CLI ```bash openclaw onboard --auth-choice opencode-zen @@ -817,7 +818,7 @@ Consulte também: [/gateway/configuration](/pt-BR/gateway/configuration) para ex ## Relacionado -- [Models](/pt-BR/concepts/models) — configuração de modelos e aliases -- [Model Failover](/pt-BR/concepts/model-failover) — cadeias de fallback e comportamento de repetição +- [Models](/pt-BR/concepts/models) — configuração e aliases de modelos +- [Model Failover](/pt-BR/concepts/model-failover) — cadeias de fallback e comportamento de nova tentativa - [Configuration Reference](/pt-BR/gateway/configuration-reference#agent-defaults) — chaves de configuração de modelo - [Providers](/pt-BR/providers) — guias de configuração por provedor diff --git a/docs/pt-BR/concepts/qa-e2e-automation.md b/docs/pt-BR/concepts/qa-e2e-automation.md index d6f3aad3a..6e27e762b 100644 --- a/docs/pt-BR/concepts/qa-e2e-automation.md +++ b/docs/pt-BR/concepts/qa-e2e-automation.md @@ -1,37 +1,37 @@ --- read_when: - - Expandindo o qa-lab ou o qa-channel - - Adicionando cenários de QA com suporte do repositório - - Criando automação de QA com maior realismo em torno do Dashboard do Gateway -summary: Estrutura da automação privada de QA para qa-lab, qa-channel, cenários semeados e relatórios de protocolo + - Ao estender qa-lab ou qa-channel + - Ao adicionar cenários de QA com suporte do repositório + - Ao criar automação de QA com maior realismo em torno do painel do Gateway +summary: Formato da automação privada de QA para qa-lab, qa-channel, cenários predefinidos e relatórios de protocolo title: Automação E2E de QA x-i18n: - generated_at: "2026-04-08T02:14:06Z" + generated_at: "2026-04-08T05:26:34Z" model: gpt-5.4 provider: openai - source_hash: 3b4aa5acc8e77303f4045d4f04372494cae21b89d2fdaba856dbb4855ced9d27 + source_hash: 57da147dc06abf9620290104e01a83b42182db1806514114fd9e8467492cda99 source_path: concepts/qa-e2e-automation.md workflow: 15 --- # Automação E2E de QA -A stack privada de QA foi projetada para exercitar o OpenClaw de uma forma mais -realista, no formato de canal, do que um único teste unitário consegue. +A pilha privada de QA foi criada para exercitar o OpenClaw de uma forma mais +realista e moldada por canais do que um único teste unitário consegue. -Partes atuais: +Peças atuais: -- `extensions/qa-channel`: canal de mensagens sintético com superfícies de DM, canal, thread, +- `extensions/qa-channel`: canal de mensagens sintético com superfícies de MD, canal, thread, reação, edição e exclusão. - `extensions/qa-lab`: UI de depuração e barramento de QA para observar a transcrição, injetar mensagens de entrada e exportar um relatório em Markdown. -- `qa/`: recursos semeados com suporte do repositório para a tarefa inicial e cenários +- `qa/`: recursos predefinidos com suporte do repositório para a tarefa inicial e cenários básicos de QA. -O fluxo atual do operador de QA é um site de QA com dois painéis: +O fluxo atual do operador de QA é um site de QA em dois painéis: -- Esquerda: Dashboard do Gateway (Control UI) com o agente. -- Direita: QA Lab, mostrando a transcrição no estilo do Slack e o plano de cenário. +- Esquerda: painel do Gateway (Control UI) com o agente. +- Direita: QA Lab, mostrando a transcrição em estilo Slack e o plano de cenário. Execute com: @@ -39,13 +39,13 @@ Execute com: pnpm qa:lab:up ``` -Isso compila o site de QA, inicia a trilha de gateway com suporte do Docker e expõe a +Isso compila o site de QA, inicia a trilha do gateway com suporte do Docker e expõe a página do QA Lab, onde um operador ou loop de automação pode dar ao agente uma missão de QA, observar o comportamento real do canal e registrar o que funcionou, falhou ou permaneceu bloqueado. Para uma iteração mais rápida da UI do QA Lab sem recompilar a imagem Docker a cada vez, -inicie a stack com um bundle do QA Lab montado por bind mount: +inicie a pilha com um bundle do QA Lab montado por bind: ```bash pnpm openclaw qa docker-build-image @@ -56,37 +56,38 @@ pnpm qa:lab:watch `qa:lab:up:fast` mantém os serviços Docker em uma imagem pré-compilada e faz bind mount de `extensions/qa-lab/web/dist` no contêiner `qa-lab`. `qa:lab:watch` -recompila esse bundle quando há mudanças, e o navegador recarrega automaticamente quando o hash +recompila esse bundle a cada alteração, e o navegador recarrega automaticamente quando o hash do recurso do QA Lab muda. -## Sementes com suporte do repositório +## Recursos predefinidos com suporte do repositório -Os recursos semeados ficam em `qa/`: +Os recursos predefinidos ficam em `qa/`: -- `qa/scenarios.md` +- `qa/scenarios/index.md` +- `qa/scenarios/*.md` Eles ficam intencionalmente no git para que o plano de QA seja visível tanto para humanos quanto para o -agente. A lista básica deve permanecer ampla o suficiente para cobrir: +agente. A lista básica deve continuar ampla o suficiente para cobrir: -- chat por DM e canal +- chat por MD e em canal - comportamento de thread -- ciclo de vida de ações de mensagem +- ciclo de vida de ações de mensagens - callbacks de cron - recuperação de memória - troca de modelo -- handoff para subagente +- transferência para subagente - leitura do repositório e da documentação -- uma pequena tarefa de build, como Lobster Invaders +- uma pequena tarefa de compilação, como Lobster Invaders ## Relatórios -O `qa-lab` exporta um relatório de protocolo em Markdown a partir da linha do tempo observada do barramento. +`qa-lab` exporta um relatório de protocolo em Markdown a partir da linha do tempo observada do barramento. O relatório deve responder: - O que funcionou - O que falhou - O que permaneceu bloqueado -- Quais cenários de acompanhamento valem a pena adicionar +- Quais cenários de acompanhamento vale a pena adicionar ## Documentação relacionada diff --git a/docs/pt-BR/concepts/streaming.md b/docs/pt-BR/concepts/streaming.md index 748889043..f2621436e 100644 --- a/docs/pt-BR/concepts/streaming.md +++ b/docs/pt-BR/concepts/streaming.md @@ -1,31 +1,31 @@ --- read_when: - - Explicar como streaming ou chunking funcionam nos canais - - Alterar o comportamento de block streaming ou channel chunking - - Depurar respostas em bloco duplicadas/antecipadas ou streaming de prévia por canal -summary: Comportamento de streaming + chunking (respostas em blocos, streaming de prévia por canal, mapeamento de modos) -title: Streaming e Chunking + - Explicar como o streaming ou a fragmentação funcionam nos canais + - Alterar o streaming em blocos ou o comportamento de fragmentação do canal + - Depurar respostas em bloco duplicadas/antecipadas ou streaming de prévia do canal +summary: Comportamento de streaming + fragmentação (respostas em blocos, streaming de prévia do canal, mapeamento de modos) +title: Streaming e Fragmentação x-i18n: - generated_at: "2026-04-05T12:40:41Z" + generated_at: "2026-04-08T05:26:46Z" model: gpt-5.4 provider: openai - source_hash: 44b0d08c7eafcb32030ef7c8d5719c2ea2d34e4bac5fdad8cc8b3f4e9e9fad97 + source_hash: a8e847bb7da890818cd79dec7777f6ae488e6d6c0468e948e56b6b6c598e0000 source_path: concepts/streaming.md workflow: 15 --- -# Streaming + chunking +# Streaming + fragmentação -O OpenClaw tem duas camadas separadas de streaming: +O OpenClaw tem duas camadas de streaming separadas: -- **Streaming em blocos (canais):** emite **blocos** concluídos à medida que o assistente escreve. Essas são mensagens normais do canal (não deltas de token). +- **Streaming em blocos (canais):** emite **blocos** concluídos conforme o assistente escreve. Essas são mensagens normais do canal (não deltas de token). - **Streaming de prévia (Telegram/Discord/Slack):** atualiza uma **mensagem de prévia** temporária durante a geração. -Hoje, **não existe streaming real de delta de token** para mensagens de canal. O streaming de prévia é baseado em mensagens (envio + edições/anexos). +Atualmente, **não há streaming real de deltas de token** para mensagens do canal. O streaming de prévia é baseado em mensagens (envio + edições/anexos). -## Streaming em blocos (mensagens de canal) +## Streaming em blocos (mensagens do canal) -O streaming em blocos envia a saída do assistente em partes mais amplas à medida que ela fica disponível. +O streaming em blocos envia a saída do assistente em fragmentos maiores conforme ela fica disponível. ``` Model output @@ -40,72 +40,72 @@ Model output Legenda: - `text_delta/events`: eventos de stream do modelo (podem ser esparsos para modelos sem streaming). -- `chunker`: `EmbeddedBlockChunker` aplicando limites mínimo/máximo + preferência de quebra. -- `channel send`: mensagens reais de saída (respostas em blocos). +- `chunker`: `EmbeddedBlockChunker` aplicando limites mínimos/máximos + preferência de quebra. +- `channel send`: mensagens de saída reais (respostas em bloco). **Controles:** - `agents.defaults.blockStreamingDefault`: `"on"`/`"off"` (padrão: desativado). -- Substituições por canal: `*.blockStreaming` (e variantes por conta) para forçar `"on"`/`"off"` por canal. +- Sobrescritas por canal: `*.blockStreaming` (e variantes por conta) para forçar `"on"`/`"off"` por canal. - `agents.defaults.blockStreamingBreak`: `"text_end"` ou `"message_end"`. - `agents.defaults.blockStreamingChunk`: `{ minChars, maxChars, breakPreference? }`. - `agents.defaults.blockStreamingCoalesce`: `{ minChars?, maxChars?, idleMs? }` (mescla blocos transmitidos antes do envio). - Limite rígido do canal: `*.textChunkLimit` (por exemplo, `channels.whatsapp.textChunkLimit`). -- Modo de chunking do canal: `*.chunkMode` (`length` é o padrão, `newline` divide em linhas em branco (limites de parágrafo) antes da divisão por tamanho). +- Modo de fragmentação do canal: `*.chunkMode` (`length` por padrão, `newline` divide em linhas em branco [limites de parágrafo] antes da fragmentação por comprimento). - Limite flexível do Discord: `channels.discord.maxLinesPerMessage` (padrão: 17) divide respostas altas para evitar corte na UI. **Semântica de limites:** -- `text_end`: transmite blocos assim que o chunker os emite; faz flush em cada `text_end`. -- `message_end`: espera a mensagem do assistente terminar e então faz flush da saída armazenada. +- `text_end`: transmite blocos assim que o chunker os emite; descarrega em cada `text_end`. +- `message_end`: espera até que a mensagem do assistente termine e, então, descarrega a saída em buffer. -`message_end` ainda usa o chunker se o texto em buffer exceder `maxChars`, então ele pode emitir vários chunks no final. +`message_end` ainda usa o chunker se o texto em buffer exceder `maxChars`, então ele pode emitir vários fragmentos no final. -## Algoritmo de chunking (limites baixo/alto) +## Algoritmo de fragmentação (limites baixo/alto) -O chunking em blocos é implementado por `EmbeddedBlockChunker`: +A fragmentação em blocos é implementada por `EmbeddedBlockChunker`: - **Limite baixo:** não emite até que o buffer >= `minChars` (a menos que seja forçado). - **Limite alto:** prefere divisões antes de `maxChars`; se forçado, divide em `maxChars`. - **Preferência de quebra:** `paragraph` → `newline` → `sentence` → `whitespace` → quebra rígida. -- **Code fences:** nunca divide dentro de fences; quando forçado em `maxChars`, fecha + reabre a fence para manter o Markdown válido. +- **Blocos de código:** nunca divide dentro de blocos; quando é forçado em `maxChars`, fecha + reabre o bloco para manter o Markdown válido. -`maxChars` é limitado por `textChunkLimit` do canal, então você não pode exceder os limites por canal. +`maxChars` é limitado a `textChunkLimit` do canal, então você não pode exceder os limites por canal. ## Coalescência (mesclar blocos transmitidos) -Quando o streaming em blocos está habilitado, o OpenClaw pode **mesclar chunks de bloco consecutivos** -antes de enviá-los. Isso reduz o “spam de linha única” e ainda fornece +Quando o streaming em blocos está ativado, o OpenClaw pode **mesclar fragmentos consecutivos de blocos** +antes de enviá-los. Isso reduz o “spam de linha única” enquanto ainda fornece saída progressiva. -- A coalescência espera por **intervalos de inatividade** (`idleMs`) antes de fazer flush. -- Buffers são limitados por `maxChars` e fazem flush se o excederem. -- `minChars` impede o envio de fragmentos minúsculos até que texto suficiente se acumule - (o flush final sempre envia o texto restante). -- O separador é derivado de `blockStreamingChunk.breakPreference` +- A coalescência espera por **intervalos de inatividade** (`idleMs`) antes de descarregar. +- Os buffers são limitados por `maxChars` e serão descarregados se o excederem. +- `minChars` evita que fragmentos muito pequenos sejam enviados até que texto suficiente se acumule + (o descarregamento final sempre envia o texto restante). +- O joiner é derivado de `blockStreamingChunk.breakPreference` (`paragraph` → `\n\n`, `newline` → `\n`, `sentence` → espaço). -- Há substituições por canal disponíveis via `*.blockStreamingCoalesce` (incluindo configurações por conta). -- O `minChars` padrão de coalescência é elevado para 1500 em Signal/Slack/Discord, a menos que seja substituído. +- Sobrescritas por canal estão disponíveis via `*.blockStreamingCoalesce` (incluindo configs por conta). +- O valor padrão de coalescência `minChars` é elevado para 1500 em Signal/Slack/Discord, a menos que seja sobrescrito. -## Ritmo mais humano entre blocos +## Ritmo humano entre blocos -Quando o streaming em blocos está habilitado, você pode adicionar uma **pausa aleatória** -entre respostas em bloco (depois do primeiro bloco). Isso faz respostas em várias bolhas parecerem +Quando o streaming em blocos está ativado, você pode adicionar uma **pausa aleatória** entre +respostas em bloco (após o primeiro bloco). Isso faz com que respostas em várias bolhas pareçam mais naturais. -- Configuração: `agents.defaults.humanDelay` (substituível por agente via `agents.list[].humanDelay`). +- Configuração: `agents.defaults.humanDelay` (sobrescreva por agente via `agents.list[].humanDelay`). - Modos: `off` (padrão), `natural` (800–2500ms), `custom` (`minMs`/`maxMs`). -- Aplica-se apenas a **respostas em bloco**, não a respostas finais nem resumos de ferramentas. +- Aplica-se apenas a **respostas em bloco**, não a respostas finais nem a resumos de ferramentas. -## "Transmitir chunks ou tudo" +## "Transmitir fragmentos ou tudo" Isso corresponde a: -- **Transmitir chunks:** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"` (emite durante a geração). Canais não Telegram também precisam de `*.blockStreaming: true`. -- **Transmitir tudo no final:** `blockStreamingBreak: "message_end"` (faz flush uma vez, possivelmente em vários chunks se for muito longo). +- **Transmitir fragmentos:** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"` (emite conforme avança). Canais que não sejam Telegram também precisam de `*.blockStreaming: true`. +- **Transmitir tudo no final:** `blockStreamingBreak: "message_end"` (descarrega uma vez, possivelmente em vários fragmentos se for muito longo). - **Sem streaming em blocos:** `blockStreamingDefault: "off"` (apenas resposta final). -**Observação sobre canais:** o streaming em blocos fica **desativado, a menos que** +**Observação sobre canais:** O streaming em blocos fica **desativado, a menos que** `*.blockStreaming` seja explicitamente definido como `true`. Os canais podem transmitir uma prévia ao vivo (`channels..streaming`) sem respostas em bloco. @@ -118,51 +118,52 @@ Chave canônica: `channels..streaming` Modos: -- `off`: desabilita o streaming de prévia. +- `off`: desativa o streaming de prévia. - `partial`: uma única prévia que é substituída pelo texto mais recente. -- `block`: atualizações da prévia em etapas com chunking/anexos. +- `block`: atualizações de prévia em etapas fragmentadas/anexadas. - `progress`: prévia de progresso/status durante a geração, resposta final ao concluir. ### Mapeamento por canal -| Canal | `off` | `partial` | `block` | `progress` | -| -------- | ----- | --------- | ------- | ------------------ | +| Canal | `off` | `partial` | `block` | `progress` | +| -------- | ----- | --------- | ------- | ----------------- | | Telegram | ✅ | ✅ | ✅ | mapeia para `partial` | | Discord | ✅ | ✅ | ✅ | mapeia para `partial` | -| Slack | ✅ | ✅ | ✅ | ✅ | +| Slack | ✅ | ✅ | ✅ | ✅ | -Apenas para Slack: +Somente no Slack: -- `channels.slack.nativeStreaming` alterna chamadas da API nativa de streaming do Slack quando `streaming=partial` (padrão: `true`). +- `channels.slack.streaming.nativeTransport` alterna chamadas da API nativa de streaming do Slack quando `channels.slack.streaming.mode="partial"` (padrão: `true`). +- O streaming nativo do Slack e o status de thread do assistente no Slack exigem um destino de thread de resposta; DMs de nível superior não mostram essa prévia no estilo de thread. Migração de chave legada: -- Telegram: `streamMode` + booleano `streaming` migram automaticamente para o enum `streaming`. -- Discord: `streamMode` + booleano `streaming` migram automaticamente para o enum `streaming`. -- Slack: `streamMode` migra automaticamente para o enum `streaming`; o booleano `streaming` migra automaticamente para `nativeStreaming`. +- Telegram: `streamMode` + booleano `streaming` são migrados automaticamente para o enum `streaming`. +- Discord: `streamMode` + booleano `streaming` são migrados automaticamente para o enum `streaming`. +- Slack: `streamMode` é migrado automaticamente para `streaming.mode`; o booleano `streaming` é migrado automaticamente para `streaming.mode` mais `streaming.nativeTransport`; o legado `nativeStreaming` é migrado automaticamente para `streaming.nativeTransport`. -### Comportamento em runtime +### Comportamento em tempo de execução Telegram: - Usa atualizações de prévia com `sendMessage` + `editMessageText` em DMs e grupos/tópicos. -- O streaming de prévia é ignorado quando o streaming em blocos do Telegram está explicitamente habilitado (para evitar streaming duplo). -- `/reasoning stream` pode gravar raciocínio na prévia. +- O streaming de prévia é ignorado quando o streaming em blocos do Telegram está explicitamente ativado (para evitar streaming duplo). +- `/reasoning stream` pode gravar o raciocínio na prévia. Discord: -- Usa envio + edição de mensagens de prévia. -- O modo `block` usa chunking de rascunho (`draftChunk`). -- O streaming de prévia é ignorado quando o streaming em blocos do Discord está explicitamente habilitado. +- Usa mensagens de prévia com envio + edição. +- O modo `block` usa fragmentação de rascunho (`draftChunk`). +- O streaming de prévia é ignorado quando o streaming em blocos do Discord está explicitamente ativado. Slack: - `partial` pode usar o streaming nativo do Slack (`chat.startStream`/`append`/`stop`) quando disponível. - `block` usa prévias de rascunho no estilo append. -- `progress` usa texto de prévia de status e depois a resposta final. +- `progress` usa texto de prévia de status e, depois, a resposta final. -## Relacionados +## Relacionado -- [Mensagens](/concepts/messages) — ciclo de vida e entrega de mensagens -- [Retry](/concepts/retry) — comportamento de nova tentativa em falha de entrega -- [Canais](/channels) — suporte a streaming por canal +- [Mensagens](/pt-BR/concepts/messages) — ciclo de vida e entrega de mensagens +- [Retry](/pt-BR/concepts/retry) — comportamento de repetição em falhas de entrega +- [Canais](/pt-BR/channels) — suporte a streaming por canal diff --git a/docs/pt-BR/gateway/configuration-reference.md b/docs/pt-BR/gateway/configuration-reference.md index aaddeffc9..bfbd29cb3 100644 --- a/docs/pt-BR/gateway/configuration-reference.md +++ b/docs/pt-BR/gateway/configuration-reference.md @@ -1,23 +1,37 @@ --- read_when: - - Você precisa da semântica exata ou dos valores padrão de configuração em nível de campo + - Você precisa da semântica exata ou dos padrões de configuração no nível de campo - Você está validando blocos de configuração de canal, modelo, gateway ou ferramenta -summary: Referência completa de cada chave de configuração do OpenClaw, padrões e configurações de canais -title: Referência de configuração +summary: Referência de configuração do gateway para chaves centrais do OpenClaw, padrões e links para referências dedicadas de subsistemas +title: Referência de Configuração x-i18n: - generated_at: "2026-04-08T02:20:08Z" + generated_at: "2026-04-08T05:31:19Z" model: gpt-5.4 provider: openai - source_hash: 2c7991b948cbbb7954a3e26280089ab00088e7f4878ec0b0540c3c9acf222ebb + source_hash: 2f9ab34fb56897a77cb038d95bea21e8530d8f0402b66d1ee97c73822a1e8fd4 source_path: gateway/configuration-reference.md workflow: 15 --- -# Referência de configuração +# Referência de Configuração -Todos os campos disponíveis em `~/.openclaw/openclaw.json`. Para uma visão geral orientada a tarefas, consulte [Configuration](/pt-BR/gateway/configuration). +Referência central de configuração para `~/.openclaw/openclaw.json`. Para uma visão geral orientada a tarefas, consulte [Configuration](/pt-BR/gateway/configuration). -O formato da configuração é **JSON5** (comentários + vírgulas finais permitidos). Todos os campos são opcionais — o OpenClaw usa padrões seguros quando são omitidos. +Esta página cobre as principais superfícies de configuração do OpenClaw e aponta para outras páginas quando um subsistema tem sua própria referência mais detalhada. Ela **não** tenta incluir em linha todo catálogo de comandos de canal/plugin nem todos os parâmetros profundos de memória/QMD em uma única página. + +Fonte da verdade no código: + +- `openclaw config schema` imprime o JSON Schema em tempo real usado para validação e a Control UI, com metadados de pacotes/plugin/canal mesclados quando disponíveis +- `config.schema.lookup` retorna um nó de schema com escopo de caminho para ferramentas de detalhamento +- `pnpm config:docs:check` / `pnpm config:docs:gen` validam o hash de baseline da documentação de configuração em relação à superfície atual do schema + +Referências detalhadas dedicadas: + +- [Referência de configuração de memória](/pt-BR/reference/memory-config) para `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` e configuração de dreaming em `plugins.entries.memory-core.config.dreaming` +- [Comandos Slash](/pt-BR/tools/slash-commands) para o catálogo atual de comandos embutidos + empacotados +- páginas do canal/plugin responsável para superfícies de comando específicas do canal + +O formato de configuração é **JSON5** (comentários + vírgulas à direita permitidos). Todos os campos são opcionais — o OpenClaw usa padrões seguros quando omitidos. --- @@ -25,32 +39,32 @@ O formato da configuração é **JSON5** (comentários + vírgulas finais permit Cada canal inicia automaticamente quando sua seção de configuração existe (a menos que `enabled: false`). -### Acesso a mensagens diretas e grupos +### Acesso por DM e grupo -Todos os canais oferecem suporte a políticas de mensagens diretas e políticas de grupo: +Todos os canais oferecem suporte a políticas de DM e políticas de grupo: -| Política de mensagem direta | Comportamento | -| --------------------------- | -------------------------------------------------------------- | -| `pairing` (padrão) | Remetentes desconhecidos recebem um código de pareamento único; o proprietário deve aprovar | -| `allowlist` | Apenas remetentes em `allowFrom` (ou no armazenamento de permissões de pareamento) | -| `open` | Permitir todas as mensagens diretas recebidas (requer `allowFrom: ["*"]`) | -| `disabled` | Ignorar todas as mensagens diretas recebidas | +| Política de DM | Comportamento | +| ------------------- | ------------------------------------------------------------- | +| `pairing` (padrão) | Remetentes desconhecidos recebem um código de pareamento único; o proprietário precisa aprovar | +| `allowlist` | Apenas remetentes em `allowFrom` (ou no armazenamento de permitidos por pareamento) | +| `open` | Permite todas as DMs recebidas (requer `allowFrom: ["*"]`) | +| `disabled` | Ignora todas as DMs recebidas | -| Política de grupo | Comportamento | -| ----------------------- | ----------------------------------------------------- | -| `allowlist` (padrão) | Apenas grupos que correspondem à lista de permissões configurada | -| `open` | Ignora listas de permissões de grupo (a exigência de menção ainda se aplica) | -| `disabled` | Bloqueia todas as mensagens de grupo/sala | +| Política de grupo | Comportamento | +| --------------------- | ----------------------------------------------------- | +| `allowlist` (padrão) | Apenas grupos que correspondem à lista de permissões configurada | +| `open` | Ignora listas de permissões de grupo (a exigência de menção ainda se aplica) | +| `disabled` | Bloqueia todas as mensagens de grupo/sala | `channels.defaults.groupPolicy` define o padrão quando `groupPolicy` de um provedor não está definido. -Os códigos de pareamento expiram após 1 hora. As solicitações pendentes de pareamento por mensagem direta são limitadas a **3 por canal**. -Se um bloco de provedor estiver totalmente ausente (`channels.` ausente), a política de grupo em tempo de execução recorre a `allowlist` (falha fechada) com um aviso na inicialização. +Os códigos de pareamento expiram após 1 hora. Solicitações pendentes de pareamento de DM têm limite de **3 por canal**. +Se um bloco de provedor estiver totalmente ausente (`channels.` ausente), a política de grupo em tempo de execução recai para `allowlist` (falha fechada) com um aviso na inicialização. ### Substituições de modelo por canal -Use `channels.modelByChannel` para fixar IDs de canal específicos a um modelo. Os valores aceitam `provider/model` ou aliases de modelo configurados. O mapeamento de canal se aplica quando uma sessão ainda não tem uma substituição de modelo (por exemplo, definida via `/model`). +Use `channels.modelByChannel` para fixar IDs de canal específicos a um modelo. Os valores aceitam `provider/model` ou aliases de modelo configurados. O mapeamento de canal é aplicado quando uma sessão ainda não tem uma substituição de modelo (por exemplo, definida via `/model`). ```json5 { @@ -91,11 +105,11 @@ Use `channels.defaults` para comportamento compartilhado de política de grupo e } ``` -- `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 o contexto citado/em thread/histórico), `allowlist` (inclui contexto apenas de remetentes permitidos), `allowlist_quote` (igual a allowlist, mas mantém contexto explícito de citação/resposta). Substituição por canal: `channels..contextVisibility`. -- `channels.defaults.heartbeat.showOk`: inclui status de canais saudáveis na saída do heartbeat. +- `channels.defaults.groupPolicy`: política de grupo de fallback quando `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 contexto citado/de thread/histórico), `allowlist` (inclui contexto apenas de remetentes permitidos), `allowlist_quote` (igual a allowlist, mas mantém contexto explícito de citação/resposta). Substituição por canal: `channels..contextVisibility`. +- `channels.defaults.heartbeat.showOk`: inclui status saudáveis de canal na saída do heartbeat. - `channels.defaults.heartbeat.showAlerts`: inclui status degradados/com erro na saída do heartbeat. -- `channels.defaults.heartbeat.useIndicator`: renderiza a saída do heartbeat em estilo compacto de indicador. +- `channels.defaults.heartbeat.useIndicator`: renderiza saída de heartbeat compacta no estilo indicador. ### WhatsApp @@ -110,7 +124,7 @@ O WhatsApp funciona pelo canal web do gateway (Baileys Web). Ele inicia automati textChunkLimit: 4000, chunkMode: "length", // length | newline mediaMaxMb: 50, - sendReadReceipts: true, // ticks azuis (false no modo de conversa consigo mesmo) + sendReadReceipts: true, // blue ticks (false in self-chat mode) groups: { "*": { requireMention: true }, }, @@ -150,9 +164,9 @@ O WhatsApp funciona pelo canal web do gateway (Baileys Web). Ele inicia automati } ``` -- Os comandos de saída usam por padrão a conta `default` se ela existir; caso contrário, usam o primeiro ID de conta configurado (ordenado). -- `channels.whatsapp.defaultAccount` opcional substitui essa seleção padrão da conta quando corresponde a um ID de conta configurado. -- O diretório legado de autenticação Baileys de conta única é migrado por `openclaw doctor` para `whatsapp/default`. +- Comandos de saída usam a conta `default` por padrão, se presente; caso contrário, usam o primeiro ID de conta configurado (ordenado). +- `channels.whatsapp.defaultAccount` opcional substitui essa seleção padrão de conta de fallback quando corresponde a um ID de conta configurado. +- O diretório legado de autenticação Baileys de conta única é migrado pelo `openclaw doctor` para `whatsapp/default`. - Substituições por conta: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. @@ -211,13 +225,13 @@ O WhatsApp funciona pelo canal web do gateway (Baileys Web). Ele inicia automati } ``` -- Token do bot: `channels.telegram.botToken` ou `channels.telegram.tokenFile` (somente arquivo comum; links simbólicos são rejeitados), com `TELEGRAM_BOT_TOKEN` como fallback para a conta padrão. -- `channels.telegram.defaultAccount` opcional substitui a seleção da 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` emite um aviso quando isso está ausente ou inválido. -- `configWrites: false` bloqueia gravações de configuração iniciadas pelo Telegram (migrações de IDs 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 o formato canônico `chatId:topic:topicId` em `match.peer.id`). A semântica dos campos é compartilhada em [ACP Agents](/pt-BR/tools/acp-agents#channel-specific-settings). -- As prévias de streaming do Telegram usam `sendMessage` + `editMessageText` (funciona em conversas diretas e em grupo). -- Política de retry: consulte [Retry policy](/pt-BR/concepts/retry). +- Token do bot: `channels.telegram.botToken` ou `channels.telegram.tokenFile` (apenas arquivo regular; symlinks rejeitados), com `TELEGRAM_BOT_TOKEN` como fallback para a conta padrã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 por 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 de nível superior `bindings[]` com `type: "acp"` configuram vínculos ACP persistentes para tópicos de fórum (use o formato canônico `chatId:topic:topicId` em `match.peer.id`). A semântica dos campos é compartilhada em [ACP Agents](/pt-BR/tools/acp-agents#channel-specific-settings). +- As prévias de streaming do Telegram usam `sendMessage` + `editMessageText` (funciona em chats diretos e em grupo). +- Política de retry: consulte [Política de retry](/pt-BR/concepts/retry). ### Discord @@ -320,35 +334,35 @@ O WhatsApp funciona pelo canal web do gateway (Baileys Web). Ele inicia automati ``` - Token: `channels.discord.token`, com `DISCORD_BOT_TOKEN` como fallback para a conta padrão. -- Chamadas diretas de saída que fornecem um `token` explícito do Discord usam esse token na chamada; as configurações de retry/política da conta ainda vêm da conta selecionada no snapshot ativo de runtime. -- `channels.discord.defaultAccount` opcional substitui a seleção da conta padrão quando corresponde a um ID de conta configurado. -- Use `user:` (DM) ou `channel:` (canal de guilda) para destinos de entrega; IDs numéricos sem prefixo são rejeitados. -- Slugs de guilda ficam em minúsculas com espaços substituídos por `-`; chaves de canal usam o nome em slug (sem `#`). Prefira IDs de guilda. -- Mensagens criadas por bots são ignoradas por padrão. `allowBots: true` as habilita; use `allowBots: "mentions"` para aceitar somente mensagens de bots que mencionem o bot (mensagens próprias continuam filtradas). -- `channels.discord.guilds..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. -- `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) +- Chamadas diretas de saída que fornecem um `token` explícito do Discord usam esse token para a chamada; as configurações de retry/política da conta ainda vêm da conta selecionada no snapshot ativo de tempo de execução. +- `channels.discord.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um ID de conta configurado. +- Use `user:` (DM) ou `channel:` (canal de guild) para alvos de entrega; IDs numéricos simples são rejeitados. +- Slugs de guild são em minúsculas com espaços substituídos por `-`; chaves de canal usam o nome em slug (sem `#`). Prefira IDs de guild. +- Mensagens de autoria de bots são ignoradas por padrão. `allowBots: true` as habilita; use `allowBots: "mentions"` para aceitar apenas mensagens de bot que mencionem o bot (as próprias mensagens continuam filtradas). +- `channels.discord.guilds..ignoreOtherMentions` (e substituições por canal) descarta mensagens que mencionem outro usuário ou cargo, mas não o bot (excluindo @everyone/@here). +- `maxLinesPerMessage` (padrão 17) divide mensagens altas mesmo quando abaixo de 2000 caracteres. +- `channels.discord.threadBindings` controla roteamento vinculado a threads do Discord: + - `enabled`: substituição do Discord para recursos de sessão vinculada 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` desativa) - `maxAgeHours`: substituição do Discord para idade máxima rígida em horas (`0` desativa) - - `spawnSubagentSessions`: chave de adesão para criação/vinculação automática de thread por `sessions_spawn({ thread: true })` -- Entradas `bindings[]` de nível superior com `type: "acp"` configuram vínculos ACP persistentes para canais e threads (use o ID do canal/thread em `match.peer.id`). A semântica dos campos é compartilhada em [ACP Agents](/pt-BR/tools/acp-agents#channel-specific-settings). + - `spawnSubagentSessions`: chave de ativação para criação/vinculação automática de thread por `sessions_spawn({ thread: true })` +- Entradas de nível superior `bindings[]` com `type: "acp"` configuram vínculos ACP persistentes para canais e threads (use o ID do canal/thread em `match.peer.id`). A semântica dos campos é compartilhada em [ACP Agents](/pt-BR/tools/acp-agents#channel-specific-settings). - `channels.discord.ui.components.accentColor` define a cor de destaque para contêineres de componentes v2 do Discord. - `channels.discord.voice` habilita conversas em canais de voz do Discord e substituições opcionais de auto-join + TTS. -- `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 e entrando novamente em uma sessão de voz após falhas repetidas de descriptografia. -- `channels.discord.streaming` é a chave canônica do modo de streaming. Os valores legados `streamMode` e `streaming` booleano são migrados automaticamente. -- `channels.discord.autoPresence` mapeia a disponibilidade em runtime para a presença do bot (saudável => online, degradado => idle, exausto => dnd) e permite substituições opcionais de texto de status. -- `channels.discord.dangerouslyAllowNameMatching` reativa correspondência por nome/tag mutável (modo de compatibilidade break-glass). -- `channels.discord.execApprovals`: entrega de aprovações de exec nativa do Discord e autorização de aprovadores. - - `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`. +- `channels.discord.voice.daveEncryption` e `channels.discord.voice.decryptionFailureTolerance` são repassados para opções DAVE de `@discordjs/voice` (`true` e `24` por padrão). +- O OpenClaw também tenta recuperar recepção de voz saindo e reentrando em uma sessão de voz após falhas repetidas de descriptografia. +- `channels.discord.streaming` é a chave canônica de modo de streaming. Os valores legados `streamMode` e booleanos `streaming` são migrados automaticamente. +- `channels.discord.autoPresence` mapeia a disponibilidade em tempo de execução para presença do bot (saudável => online, degradado => idle, esgotado => dnd) e permite substituições opcionais de texto de status. +- `channels.discord.dangerouslyAllowNameMatching` reabilita correspondência por nome/tag mutáveis (modo de compatibilidade de emergência). +- `channels.discord.execApprovals`: entrega nativa do Discord para aprovações de exec 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. Usa `commands.ownerAllowFrom` como fallback quando omitido. - `agentFilter`: lista opcional de IDs de agente permitidos. Omita para encaminhar aprovações para todos os agentes. - `sessionFilter`: padrões opcionais de chave de sessão (substring ou regex). - - `target`: onde enviar solicitações de aprovação. `"dm"` (padrão) envia para DMs dos aprovadores, `"channel"` envia para o canal de origem, `"both"` envia para ambos. Quando o alvo inclui `"channel"`, os botões só podem ser usados por aprovadores resolvidos. - - `cleanupAfterResolve`: quando `true`, exclui DMs de aprovação após aprovação, recusa ou timeout. + - `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 alvo 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 de reação:** `off` (nenhum), `own` (mensagens do bot, padrão), `all` (todas as mensagens), `allowlist` (de `guilds..users` em todas as mensagens). +**Modos de notificação de reação:** `off` (nenhuma), `own` (mensagens do bot, padrão), `all` (todas as mensagens), `allowlist` (de `guilds..users` em todas as mensagens). ### Google Chat @@ -379,11 +393,11 @@ O WhatsApp funciona pelo canal web do gateway (Baileys Web). Ele inicia automati } ``` -- JSON da conta de serviço: inline (`serviceAccount`) ou por arquivo (`serviceAccountFile`). -- SecretRef da conta de serviço também é compatível (`serviceAccountRef`). -- Fallbacks de ambiente: `GOOGLE_CHAT_SERVICE_ACCOUNT` ou `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. -- Use `spaces/` ou `users/` para destinos de entrega. -- `channels.googlechat.dangerouslyAllowNameMatching` reativa correspondência por principal de email mutável (modo de compatibilidade break-glass). +- JSON de conta de serviço: embutido (`serviceAccount`) ou baseado em arquivo (`serviceAccountFile`). +- SecretRef para conta de serviço também é suportado (`serviceAccountRef`). +- Fallbacks por variável de ambiente: `GOOGLE_CHAT_SERVICE_ACCOUNT` ou `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. +- Use `spaces/` ou `users/` para alvos de entrega. +- `channels.googlechat.dangerouslyAllowNameMatching` reabilita correspondência por principal de email mutável (modo de compatibilidade de emergência). ### Slack @@ -433,8 +447,10 @@ O WhatsApp funciona pelo canal web do gateway (Baileys Web). Ele inicia automati typingReaction: "hourglass_flowing_sand", textChunkLimit: 4000, chunkMode: "length", - streaming: "partial", // off | partial | block | progress (preview mode) - nativeStreaming: true, // use Slack native streaming API when streaming=partial + streaming: { + mode: "partial", // off | partial | block | progress + nativeTransport: true, // use Slack native streaming API when mode=partial + }, mediaMaxMb: 20, execApprovals: { enabled: "auto", // true | false | "auto" @@ -448,33 +464,39 @@ O WhatsApp funciona pelo canal web do gateway (Baileys Web). Ele inicia automati } ``` -- **Modo socket** requer `botToken` e `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` para fallback de ambiente da conta padrão). +- **Modo socket** requer `botToken` e `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` para fallback por variável de ambiente da conta padrão). - **Modo HTTP** requer `botToken` mais `signingSecret` (na raiz ou por conta). -- `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 foi configurada por SecretRef, mas o caminho atual de comando/runtime não conseguiu resolver o valor do segredo. +- `botToken`, `appToken`, `signingSecret` e `userToken` aceitam strings em texto simples + ou objetos SecretRef. +- Snapshots de conta do Slack expõem campos por credencial de origem/status, 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/tempo de execução não pôde + 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` é a chave canônica do modo de streaming. Os valores legados `streamMode` e `streaming` booleano são migrados automaticamente. -- Use `user:` (DM) ou `channel:` para destinos de entrega. +- `channels.slack.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um ID de conta configurado. +- `channels.slack.streaming.mode` é a chave canônica de modo de streaming do Slack. `channels.slack.streaming.nativeTransport` controla o transporte nativo de streaming do Slack. Os valores legados `streamMode`, booleanos `streaming` e `nativeStreaming` são migrados automaticamente. +- Use `user:` (DM) ou `channel:` para alvos de entrega. **Modos de notificação de reação:** `off`, `own` (padrão), `all`, `allowlist` (de `reactionAllowlist`). -**Isolamento de sessão por thread:** `thread.historyScope` é por thread (padrão) ou compartilhado entre 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. -- `typingReaction` adiciona uma reação temporária à mensagem recebida do Slack enquanto uma resposta está em execução, depois a remove ao concluir. Use um shortcode de emoji do Slack, como `"hourglass_flowing_sand"`. -- `channels.slack.execApprovals`: entrega de aprovações 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"`). +- O streaming nativo do Slack, junto com o status no estilo assistente do Slack "está digitando..." em thread, requer um alvo de resposta em thread. DMs de nível superior permanecem fora de thread 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 recebida do Slack enquanto uma resposta está em execução e a remove ao concluir. Use um shortcode de emoji do Slack, como `"hourglass_flowing_sand"`. +- `channels.slack.execApprovals`: entrega nativa do Slack para aprovações de exec e autorização de aprovadores. Mesmo schema 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 | ativado | Reagir + listar reações | -| messages | ativado | Ler/enviar/editar/excluir | -| pins | ativado | Fixar/desafixar/listar | -| memberInfo | ativado | Informações do membro | -| emojiList | ativado | Lista de emojis personalizados | +| 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 | ### Mattermost -O Mattermost é distribuído como plugin: `openclaw plugins install @openclaw/mattermost`. +Mattermost é distribuído como plugin: `openclaw plugins install @openclaw/mattermost`. ```json5 { @@ -504,19 +526,23 @@ O Mattermost é distribuído como plugin: `openclaw plugins install @openclaw/ma } ``` -Modos de chat: `oncall` (responde em @menção, padrão), `onmessage` (toda mensagem), `onchar` (mensagens que começam com prefixo de gatilho). +Modos de chat: `oncall` (responde a @menção, padrão), `onmessage` (toda mensagem), `onchar` (mensagens começando com prefixo de gatilho). -Quando os comandos nativos do Mattermost estão habilitados: +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 nativos de slash são autenticados com os tokens por comando retornados pelo Mattermost durante o registro do slash command. 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 do callback. +- `commands.callbackUrl` deve resolver para o endpoint do gateway OpenClaw e estar acessível a partir do servidor Mattermost. +- Callbacks nativos de slash são autenticados com os tokens por comando retornados + pelo Mattermost durante o registro do slash command. 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 do 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..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. +- `channels.mattermost.groups..requireMention`: substituição por canal para exigência de menção (`"*"` para padrão). +- `channels.mattermost.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um ID de conta configurado. ### Signal @@ -525,7 +551,7 @@ Quando os comandos nativos do Mattermost estão habilitados: channels: { signal: { enabled: true, - account: "+15555550123", // vinculação opcional de conta + account: "+15555550123", // optional account binding dmPolicy: "pairing", allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"], configWrites: true, @@ -539,9 +565,9 @@ Quando os 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 em uma identidade específica de conta Signal. +- `channels.signal.account`: fixa a inicialização do canal em uma identidade específica de conta do Signal. - `channels.signal.configWrites`: permite ou nega gravações de configuração iniciadas pelo Signal. -- `channels.signal.defaultAccount` opcional substitui a seleção da conta padrão quando corresponde a um ID de conta configurado. +- `channels.signal.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um ID de conta configurado. ### BlueBubbles @@ -553,21 +579,21 @@ BlueBubbles é o caminho recomendado para iMessage (baseado em plugin, configura bluebubbles: { enabled: true, dmPolicy: "pairing", - // serverUrl, password, webhookPath, controles de grupo e ações avançadas: - // consulte /channels/bluebubbles + // serverUrl, password, webhookPath, group controls, and advanced actions: + // see /channels/bluebubbles }, }, } ``` -- Caminhos de chave principal cobertos aqui: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. -- `channels.bluebubbles.defaultAccount` opcional substitui a seleção da conta padrão quando corresponde a um ID de conta configurado. -- Entradas `bindings[]` de nível superior com `type: "acp"` podem vincular conversas BlueBubbles a sessões ACP persistentes. Use um identificador ou string de destino BlueBubbles (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) em `match.peer.id`. Semântica compartilhada dos campos: [ACP Agents](/pt-BR/tools/acp-agents#channel-specific-settings). +- Caminhos de chave centrais 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 de nível superior `bindings[]` com `type: "acp"` podem vincular conversas do BlueBubbles a sessões ACP persistentes. Use um identificador BlueBubbles ou string de alvo (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) em `match.peer.id`. Semântica compartilhada dos campos: [ACP Agents](/pt-BR/tools/acp-agents#channel-specific-settings). - A configuração completa do canal BlueBubbles está documentada em [BlueBubbles](/pt-BR/channels/bluebubbles). ### iMessage -O OpenClaw inicia `imsg rpc` (JSON-RPC sobre stdio). Nenhum daemon ou porta é necessário. +O OpenClaw inicia `imsg rpc` (JSON-RPC sobre stdio). Não é necessário daemon nem porta. ```json5 { @@ -591,15 +617,15 @@ O OpenClaw inicia `imsg rpc` (JSON-RPC sobre stdio). Nenhum daemon ou porta é n } ``` -- `channels.imessage.defaultAccount` opcional substitui a seleção da conta padrão quando corresponde a um ID de conta configurado. +- `channels.imessage.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um ID de conta configurado. - Requer Full Disk Access ao banco de dados do Messages. -- Prefira destinos `chat_id:`. Use `imsg chats --limit 20` para listar chats. -- `cliPath` pode apontar para um wrapper SSH; defina `remoteHost` (`host` ou `user@host`) para recuperação de anexos por SCP. +- Prefira alvos `chat_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 com SCP. - `attachmentRoots` e `remoteAttachmentRoots` restringem caminhos de anexos recebidos (padrão: `/Users/*/Library/Messages/Attachments`). -- O SCP usa verificação estrita de chave de host, então garanta que a chave do host relay já exista em `~/.ssh/known_hosts`. +- O SCP usa verificação estrita de chave do host, então garanta que a chave do host relay 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 iMessage a sessões ACP persistentes. Use um identificador normalizado ou destino explícito de chat (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) em `match.peer.id`. Semântica compartilhada dos campos: [ACP Agents](/pt-BR/tools/acp-agents#channel-specific-settings). +- Entradas de nível superior `bindings[]` com `type: "acp"` podem vincular conversas do iMessage a sessões ACP persistentes. Use um identificador normalizado ou alvo explícito de chat (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) em `match.peer.id`. Semântica compartilhada dos campos: [ACP Agents](/pt-BR/tools/acp-agents#channel-specific-settings). @@ -612,7 +638,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -O Matrix é baseado em extensão e configurado em `channels.matrix`. +O Matrix é suportado por extensão e configurado em `channels.matrix`. ```json5 { @@ -642,25 +668,25 @@ O Matrix é baseado em extensão e configurado em `channels.matrix`. } ``` -- 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 um proxy HTTP(S) explícito. Contas nomeadas podem substituí-lo com `channels.matrix.accounts..proxy`. -- `channels.matrix.network.dangerouslyAllowPrivateNetwork` permite homeservers privados/internos. `proxy` e essa adesão de rede são controles independentes. +- Autenticação por token usa `accessToken`; autenticação por senha usa `userId` + `password`. +- `channels.matrix.proxy` roteia tráfego HTTP do Matrix por um proxy HTTP(S) explícito. Contas nomeadas podem substituí-lo com `channels.matrix.accounts..proxy`. +- `channels.matrix.network.dangerouslyAllowPrivateNetwork` permite homeservers privados/internos. `proxy` e essa ativação de rede são controles independentes. - `channels.matrix.defaultAccount` seleciona a conta preferida em configurações com várias contas. -- `channels.matrix.autoJoin` tem como padrão `off`, então salas convidadas e convites novos no estilo DM são ignorados até que você defina `autoJoin: "allowlist"` com `autoJoinAllowlist` ou `autoJoin: "always"`. -- `channels.matrix.execApprovals`: entrega de aprovações de exec nativa do Matrix e autorização de aprovadores. - - `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 Matrix (por exemplo `@owner:example.org`) autorizados a aprovar solicitações de exec. +- `channels.matrix.autoJoin` tem padrão `off`, então salas convidadas e novos convites no estilo DM são ignorados até que você defina `autoJoin: "allowlist"` com `autoJoinAllowlist` ou `autoJoin: "always"`. +- `channels.matrix.execApprovals`: entrega nativa do Matrix para aprovações de exec 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 Matrix (por exemplo `@owner:example.org`) autorizados a aprovar solicitações de exec. - `agentFilter`: lista opcional de IDs de agente permitidos. Omita para encaminhar aprovações para todos os agentes. - `sessionFilter`: padrões opcionais de chave de sessão (substring ou regex). - - `target`: onde enviar solicitações de aprovação. `"dm"` (padrão), `"channel"` (sala de origem) ou `"both"`. + - `target`: onde enviar prompts de aprovação. `"dm"` (padrão), `"channel"` (sala de origem) ou `"both"`. - Substituições por conta: `channels.matrix.accounts..execApprovals`. -- `channels.matrix.dm.sessionScope` controla como mensagens diretas do Matrix se agrupam em sessões: `per-user` (padrão) compartilha pelo peer roteado, enquanto `per-room` isola cada sala de DM. -- Sondas de status do Matrix e pesquisas 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). +- `channels.matrix.dm.sessionScope` controla como DMs do Matrix são agrupadas em sessões: `per-user` (padrão) compartilha por peer roteado, enquanto `per-room` isola cada sala de DM. +- Probes de status do Matrix e pesquisas ao diretório em tempo real 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 setup estão documentados em [Matrix](/pt-BR/channels/matrix). ### Microsoft Teams -Microsoft Teams é baseado em extensão e configurado em `channels.msteams`. +Microsoft Teams é suportado por extensão e configurado em `channels.msteams`. ```json5 { @@ -668,19 +694,19 @@ Microsoft Teams é baseado em extensão e configurado em `channels.msteams`. msteams: { enabled: true, configWrites: true, - // appId, appPassword, tenantId, webhook, políticas de equipe/canal: - // consulte /channels/msteams + // appId, appPassword, tenantId, webhook, team/channel policies: + // see /channels/msteams }, }, } ``` -- Caminhos de chave principal cobertos aqui: `channels.msteams`, `channels.msteams.configWrites`. +- Caminhos de chave centrais cobertos aqui: `channels.msteams`, `channels.msteams.configWrites`. - A configuração completa do Teams (credenciais, webhook, política de DM/grupo, substituições por equipe/canal) está documentada em [Microsoft Teams](/pt-BR/channels/msteams). ### IRC -IRC é baseado em extensão e configurado em `channels.irc`. +IRC é suportado por extensão e configurado em `channels.irc`. ```json5 { @@ -701,9 +727,9 @@ IRC é baseado em extensão e configurado em `channels.irc`. } ``` -- Caminhos de chave principal cobertos aqui: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. -- `channels.irc.defaultAccount` opcional substitui a seleção da conta padrão quando corresponde a um ID de conta configurado. -- A configuração completa do canal IRC (host/porta/TLS/canais/listas de permissão/exigência de menção) está documentada em [IRC](/pt-BR/channels/irc). +- Caminhos de chave centrais 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/listas de permissões/exigência de menção) está documentada em [IRC](/pt-BR/channels/irc). ### Várias contas (todos os canais) @@ -729,12 +755,12 @@ Execute várias contas por canal (cada uma com seu próprio `accountId`): ``` - `default` é usado quando `accountId` é omitido (CLI + roteamento). -- Tokens de ambiente só se aplicam à conta **default**. -- Configurações base do canal se aplicam a todas as contas, a menos que sejam substituídas por conta. +- Tokens de ambiente se aplicam apenas à conta **default**. +- 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 via `openclaw channels add` (ou onboarding de canal) enquanto ainda estiver em uma configuração de canal de conta única no nível superior, o OpenClaw primeiro promove os valores de conta única no 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 move esses valores para `channels..accounts.default`; o Matrix pode preservar um alvo nomeado/padrão correspondente existente. -- Vínculos existentes apenas do canal (sem `accountId`) continuam correspondendo à conta padrão; vínculos com escopo de conta continuam opcionais. -- `openclaw doctor --fix` também corrige formatos mistos movendo valores de conta única no nível superior com escopo de conta para a conta promovida escolhida para aquele canal. A maioria dos canais usa `accounts.default`; o Matrix pode preservar um alvo nomeado/padrão correspondente existente. +- Se você adicionar uma conta não padrão via `openclaw channels add` (ou onboarding de canal) enquanto ainda estiver em uma configuração de canal de conta única no topo, o OpenClaw promove primeiro os valores de conta única do topo 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..accounts.default`; o Matrix pode preservar um alvo nomeado/padrão correspondente já existente. +- Vínculos existentes apenas por canal (sem `accountId`) continuam correspondendo à conta padrão; vínculos com escopo por conta continuam opcionais. +- `openclaw doctor --fix` também repara formas mistas movendo valores de conta única do topo com escopo de conta para a conta promovida escolhida para esse canal. A maioria dos canais usa `accounts.default`; o Matrix pode preservar um alvo nomeado/padrão correspondente já existente. ### Outros canais de extensão @@ -743,11 +769,11 @@ Consulte o índice completo de canais: [Channels](/pt-BR/channels). ### Exigência de menção em chats de grupo -Mensagens de grupo, por padrão, **exigem menção** (menção por metadados ou padrões regex seguros). Aplica-se a chats em grupo do WhatsApp, Telegram, Discord, Google Chat e iMessage. +Mensagens de grupo exigem **menção** por padrão (menção em metadados ou padrões regex seguros). Isso se aplica a chats em grupo de WhatsApp, Telegram, Discord, Google Chat e iMessage. **Tipos de menção:** -- **Menções por metadados**: menções nativas da plataforma com @. Ignoradas no modo de conversa consigo mesmo do WhatsApp. +- **Menções em 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. - A exigência de menção só é aplicada quando a detecção é possível (menções nativas ou pelo menos um padrão). @@ -764,7 +790,7 @@ Mensagens de grupo, por padrão, **exigem menção** (menção por metadados ou `messages.groupChat.historyLimit` define o padrão global. Os canais podem substituir com `channels..historyLimit` (ou por conta). Defina `0` para desativar. -#### Limites de histórico de mensagens diretas +#### Limites de histórico de DM ```json5 { @@ -779,13 +805,13 @@ Mensagens de grupo, por padrão, **exigem menção** (menção por metadados ou } ``` -Resolução: substituição por DM → padrão do provedor → sem limite (tudo é mantido). +Resolução: substituição por DM → padrão do provedor → sem limite (tudo mantido). -Compatível com: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`. +Suportado: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`. -#### Modo de conversa consigo mesmo +#### Modo autochat -Inclua seu próprio número em `allowFrom` para ativar o modo de conversa consigo mesmo (ignora menções nativas com @, responde apenas a padrões de texto): +Inclua seu próprio número em `allowFrom` para habilitar o modo autochat (ignora @menções nativas, responde apenas a padrões de texto): ```json5 { @@ -812,12 +838,18 @@ Inclua seu próprio número em `allowFrom` para ativar o modo de conversa consig { commands: { native: "auto", // register native commands when supported + nativeSkills: "auto", // register native skill commands when supported text: true, // parse /commands in chat messages bash: false, // allow ! (alias: /bash) bashForegroundMs: 2000, config: false, // allow /config + mcp: false, // allow /mcp + plugins: false, // allow /plugins debug: false, // allow /debug - restart: false, // allow /restart + gateway restart tool + restart: true, // allow /restart + gateway restart tool + ownerAllowFrom: ["discord:123456789012345678"], + ownerDisplay: "raw", // raw | hash + ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}", allowFrom: { "*": ["user1"], discord: ["user:123"], @@ -829,22 +861,38 @@ Inclua seu próprio número em `allowFrom` para ativar o modo de conversa consig -- Comandos de texto devem ser mensagens **autônomas** com `/` no início. -- `native: "auto"` ativa comandos nativos para Discord/Telegram e deixa Slack desativado. -- Substitua por canal: `channels.discord.commands.native` (bool ou `"auto"`). `false` limpa comandos registrados anteriormente. -- `channels.telegram.customCommands` adiciona entradas extras ao menu do bot no Telegram. -- `bash: true` ativa `! ` para shell do host. Requer `tools.elevated.enabled` e remetente em `tools.elevated.allowFrom.`. -- `config: true` ativa `/config` (lê/grava `openclaw.json`). Para clientes `chat.send` do gateway, gravações persistentes por `/config set|unset` também exigem `operator.admin`; `/config show` somente leitura permanece disponível para clientes normais com escopo de escrita de operador. +- Este bloco configura superfícies de comando. Para o catálogo atual de comandos embutidos + empacotados, consulte [Slash Commands](/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 canal/plugin, como QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memória `/dreaming`, phone-control `/phone` e Talk `/voice`, estão documentados em suas páginas de canal/plugin e em [Slash Commands](/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 desligado. +- `nativeSkills: "auto"` ativa comandos nativos de skill para Discord/Telegram e mantém Slack desligado. +- Substitua por canal: `channels.discord.commands.native` (bool ou `"auto"`). `false` limpa comandos previamente registrados. +- Substitua o registro nativo de skill por canal com `channels..commands.nativeSkills`. +- `channels.telegram.customCommands` adiciona entradas extras ao menu do bot do Telegram. +- `bash: true` habilita `! ` para shell do host. Requer `tools.elevated.enabled` e remetente em `tools.elevated.allowFrom.`. +- `config: true` habilita `/config` (lê/grava `openclaw.json`). Para clientes de gateway `chat.send`, gravações persistentes de `/config set|unset` também exigem `operator.admin`; o `/config show` somente leitura continua disponível para clientes operadores normais com escopo de escrita. +- `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. - `channels..configWrites` controla mutações de configuração por canal (padrão: true). -- Para canais com várias contas, `channels..accounts..configWrites` também controla gravações direcionadas àquela conta (por exemplo `/allowlist --config --account ` ou `/config set channels..accounts....`). -- `allowFrom` é por provedor. Quando definido, é a **única** fonte de autorização (listas de permissão/pareamento do canal e `useAccessGroups` são ignorados). -- `useAccessGroups: false` permite que comandos ignorem políticas de grupo de acesso quando `allowFrom` não está definido. +- Para canais com várias contas, `channels..accounts..configWrites` também controla gravações que atinjam essa conta (por exemplo `/allowlist --config --account ` ou `/config set channels..accounts....`). +- `restart: false` desabilita `/restart` e ações da ferramenta de reinício do gateway. Padrão: `true`. +- `ownerAllowFrom` é a lista explícita de permitidos do proprietário para comandos/ferramentas exclusivas 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 hash. +- `allowFrom` é por provedor. Quando definido, ele é a **única** fonte de autorização (listas de permissões/pareamento do canal e `useAccessGroups` são ignorados). +- `useAccessGroups: false` permite que comandos contornem políticas de grupo de acesso quando `allowFrom` não está definido. +- Mapa da documentação de comandos: + - catálogo embutido + empacotado: [Slash Commands](/pt-BR/tools/slash-commands) + - superfícies de comando específicas por canal: [Channels](/pt-BR/channels) + - comandos do QQ Bot: [QQ Bot](/pt-BR/channels/qqbot) + - comandos de pareamento: [Pairing](/pt-BR/channels/pairing) + - comando card do LINE: [LINE](/pt-BR/channels/line) + - memory dreaming: [Dreaming](/pt-BR/concepts/dreaming) --- -## Padrões do agente +## Padrões de agente ### `agents.defaults.workspace` @@ -858,7 +906,7 @@ Padrão: `~/.openclaw/workspace`. ### `agents.defaults.repoRoot` -Raiz opcional do repositório mostrada na linha Runtime do prompt do sistema. Se não estiver definida, o OpenClaw detecta automaticamente subindo a partir do workspace. +Raiz opcional do repositório exibida na linha Runtime do prompt do sistema. Se não estiver definida, o OpenClaw detecta automaticamente caminhando para cima a partir do workspace. ```json5 { @@ -868,7 +916,7 @@ Raiz opcional do repositório mostrada na linha Runtime do prompt do sistema. Se ### `agents.defaults.skills` -Lista opcional padrão de permissão de Skills para agentes que não definem +Lista opcional padrão de Skills permitidas para agentes que não definem `agents.list[].skills`. ```json5 @@ -884,10 +932,11 @@ Lista opcional padrão de permissão de Skills para agentes que não definem } ``` -- Omita `agents.defaults.skills` para Skills sem restrição por padrão. +- 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 não vazia em `agents.list[].skills` é o conjunto final para aquele agente; ela não é mesclada com os padrões. +- Defina `agents.list[].skills: []` para nenhuma skill. +- 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` @@ -903,7 +952,7 @@ Desativa a criação automática de arquivos bootstrap do workspace (`AGENTS.md` Controla quando arquivos bootstrap do workspace são injetados no prompt do sistema. Padrão: `"always"`. -- `"continuation-skip"`: turnos seguros de continuação (após uma resposta completa do assistente) pulam a reinjeção do bootstrap do workspace, reduzindo o tamanho do prompt. Execuções de heartbeat e tentativas após compactação ainda recompõem o contexto. +- `"continuation-skip"`: turnos seguros de continuação (após uma resposta concluída do assistente) ignoram a reinjeção do bootstrap do workspace, reduzindo o tamanho do prompt. Execuções de heartbeat e tentativas após compactação ainda recriam o contexto. ```json5 { @@ -913,7 +962,7 @@ Controla quando arquivos bootstrap do workspace são injetados no prompt do sist ### `agents.defaults.bootstrapMaxChars` -Máximo de caracteres por arquivo bootstrap do workspace antes de truncar. Padrão: `20000`. +Máximo de caracteres por arquivo bootstrap do workspace antes do truncamento. Padrão: `20000`. ```json5 { @@ -948,10 +997,10 @@ Padrão: `"once"`. ### `agents.defaults.imageMaxDimensionPx` -Tamanho máximo em pixels do lado mais longo 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 de chamadas ao provedor. Padrão: `1200`. -Valores menores geralmente reduzem o uso de vision tokens e o tamanho da carga da solicitação em execuções com muitas capturas de tela. +Valores menores geralmente reduzem o uso de tokens de visão e o tamanho da carga da solicitação em execuções com muitas capturas de tela. Valores maiores preservam mais detalhes visuais. ```json5 @@ -972,7 +1021,7 @@ Fuso horário para o contexto do prompt do sistema (não para timestamps de mens ### `agents.defaults.timeFormat` -Formato de hora no prompt do sistema. Padrão: `auto` (preferência do sistema operacional). +Formato de hora no prompt do sistema. Padrão: `auto` (preferência do SO). ```json5 { @@ -1025,43 +1074,43 @@ Formato de hora no prompt do sistema. Padrão: `auto` (preferência do sistema o } ``` -- `model`: aceita uma string (`"provider/model"`) ou um objeto (`{ primary, fallbacks }`). - - A forma string define apenas o modelo principal. - - A forma objeto define o principal mais modelos ordenados de failover. -- `imageModel`: aceita uma string (`"provider/model"`) ou um objeto (`{ primary, fallbacks }`). +- `model`: aceita string (`"provider/model"`) ou objeto (`{ primary, fallbacks }`). + - O formato string define apenas o modelo primário. + - O formato objeto define o primário mais modelos de failover ordenados. +- `imageModel`: aceita string (`"provider/model"`) ou objeto (`{ primary, fallbacks }`). - Usado pelo caminho da ferramenta `image` como configuração de modelo de visão. - - Também usado como roteamento de fallback quando o modelo selecionado/padrão não aceita entrada de imagem. -- `imageGenerationModel`: aceita uma string (`"provider/model"`) ou um objeto (`{ primary, fallbacks }`). + - Também usado como roteamento de fallback quando o modelo selecionado/padrão não consegue aceitar entrada de imagem. +- `imageGenerationModel`: aceita string (`"provider/model"`) ou objeto (`{ primary, fallbacks }`). - Usado pela capacidade compartilhada de geração de imagem e qualquer futura superfície de ferramenta/plugin que gere imagens. - - Valores típicos: `google/gemini-3.1-flash-image-preview` para geração nativa de imagem do Gemini, `fal/fal-ai/flux/dev` para fal, ou `openai/gpt-image-1` para OpenAI Images. + - Valores típicos: `google/gemini-3.1-flash-image-preview` para geração nativa de imagem no Gemini, `fal/fal-ai/flux/dev` para fal ou `openai/gpt-image-1` para OpenAI Images. - Se você selecionar diretamente um provider/model, configure também a autenticação/chave de API correspondente do provedor (por exemplo `GEMINI_API_KEY` ou `GOOGLE_API_KEY` para `google/*`, `OPENAI_API_KEY` para `openai/*`, `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 provedores restantes registrados de geração de imagem em ordem de ID do provedor. -- `musicGenerationModel`: aceita uma string (`"provider/model"`) ou um objeto (`{ primary, fallbacks }`). - - Usado pela capacidade compartilhada de geração de música e pela ferramenta integrada `music_generate`. + - 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 de geração de imagem registrados em ordem de ID do provedor. +- `musicGenerationModel`: aceita string (`"provider/model"`) ou objeto (`{ primary, fallbacks }`). + - Usado pela capacidade compartilhada de geração de música e pela ferramenta embutida `music_generate`. - Valores típicos: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview` ou `minimax/music-2.5+`. - - 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 provedores restantes registrados de geração de música em ordem de ID do provedor. + - 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 de geração musical registrados em ordem de ID do provedor. - Se você selecionar diretamente um provider/model, configure também a autenticação/chave de API correspondente do provedor. -- `videoGenerationModel`: aceita uma string (`"provider/model"`) ou um objeto (`{ primary, fallbacks }`). - - Usado pela capacidade compartilhada de geração de vídeo e pela ferramenta integrada `video_generate`. +- `videoGenerationModel`: aceita string (`"provider/model"`) ou objeto (`{ primary, fallbacks }`). + - Usado pela capacidade compartilhada de geração de vídeo e pela ferramenta embutida `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 provedores restantes registrados de geração de vídeo em ordem de ID do provedor. + - 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 de geração de vídeo registrados em ordem de ID do provedor. - Se você selecionar diretamente um provider/model, configure também a autenticação/chave de API correspondente do provedor. - - O provedor integrado de geração de vídeo Qwen atualmente oferece suporte a no máximo 1 vídeo de saída, 1 imagem de entrada, 4 vídeos de entrada, duração de 10 segundos e opções em nível de provedor `size`, `aspectRatio`, `resolution`, `audio` e `watermark`. -- `pdfModel`: aceita uma string (`"provider/model"`) ou um objeto (`{ primary, fallbacks }`). + - O provedor empacotado de geração de vídeo Qwen atualmente suporta até 1 vídeo de saída, 1 imagem de entrada, 4 vídeos de entrada, duração de 10 segundos e opções no nível do provedor `size`, `aspectRatio`, `resolution`, `audio` e `watermark`. +- `pdfModel`: aceita string (`"provider/model"`) ou objeto (`{ primary, fallbacks }`). - Usado pela ferramenta `pdf` para roteamento de modelo. - - Se omitido, a ferramenta PDF recorre a `imageModel` e depois ao modelo resolvido da sessão/padrão. + - Se omitido, a ferramenta PDF recai para `imageModel` e depois para 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`: máximo padrão de páginas consideradas pelo modo de fallback de extração na ferramenta `pdf`. -- `verboseDefault`: nível detalhado padrão para agentes. Valores: `"off"`, `"on"`, `"full"`. Padrão: `"off"`. +- `verboseDefault`: nível padrão de verbose para agentes. Valores: `"off"`, `"on"`, `"full"`. Padrão: `"off"`. - `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.4`). Se você omitir o provedor, o OpenClaw tenta primeiro um alias, depois uma correspondência única de provedor configurado para esse ID exato de modelo e só então recorre ao provedor padrão configurado (comportamento de compatibilidade obsoleto, então prefira `provider/model` explícito). Se esse provedor não expuser mais o modelo padrão configurado, o OpenClaw recorre ao primeiro provedor/modelo configurado em vez de exibir um padrão obsoleto de provedor removido. -- `models`: catálogo de modelos configurado e lista de permissão para `/model`. Cada entrada pode incluir `alias` (atalho) e `params` (específicos do provedor, por exemplo `temperature`, `maxTokens`, `cacheRetention`, `context1m`). -- `params`: parâmetros globais padrão do provedor aplicados a todos os modelos. Definidos 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. Consulte [Prompt Caching](/pt-BR/reference/prompt-caching) para detalhes. -- Gravadores de configuração que alteram esses 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. -- `maxConcurrent`: máximo de execuções paralelas de agentes entre sessões (cada sessão continua serializada). Padrão: 4. +- `model.primary`: formato `provider/model` (por exemplo `openai/gpt-5.4`). Se você omitir o provedor, o OpenClaw tenta primeiro um alias, depois uma correspondência única de provedor configurado para esse ID exato de modelo e só então recai para o provedor padrão configurado (comportamento de compatibilidade obsoleto, então prefira `provider/model` explícito). Se esse provedor não expõe mais o modelo padrão configurado, o OpenClaw recai para o primeiro provedor/modelo configurado em vez de apresentar um padrão obsoleto de provedor removido. +- `models`: catálogo configurado de modelos e lista de permitidos para `/model`. Cada entrada pode incluir `alias` (atalho) e `params` (específicos do provedor, por exemplo `temperature`, `maxTokens`, `cacheRetention`, `context1m`). +- `params`: parâmetros padrão globais do provedor aplicados a todos os modelos. Definidos em `agents.defaults.params` (por exemplo `{ cacheRetention: "long" }`). +- Precedência de mesclagem de `params` (config): `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 [Prompt Caching](/pt-BR/reference/prompt-caching) para detalhes. +- Gravadores de configuração que alteram esses campos (por exemplo `/models set`, `/models set-image` e comandos de adicionar/remover fallback) salvam a forma canônica de objeto e preservam listas existentes de fallback quando possível. +- `maxConcurrent`: máximo de execuções paralelas de agente entre sessões (cada sessão ainda é serializada). Padrão: 4. -**Atalhos de alias integrados** (só se aplicam quando o modelo está em `agents.defaults.models`): +**Atalhos de alias embutidos** (só se aplicam quando o modelo está em `agents.defaults.models`): | Alias | Modelo | | ------------------- | -------------------------------------- | @@ -1074,15 +1123,15 @@ Formato de hora no prompt do sistema. Padrão: `auto` (preferência do sistema o | `gemini-flash` | `google/gemini-3-flash-preview` | | `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` | -Seus aliases configurados sempre prevalecem sobre os padrões. +Seus aliases configurados sempre têm prioridade sobre os padrões. -Modelos Z.AI GLM-4.x ativam automaticamente o modo de thinking, a menos que você defina `--thinking off` ou defina `agents.defaults.models["zai/"].params.thinking` por conta própria. +Modelos Z.AI GLM-4.x ativam automaticamente o modo thinking, a menos que você defina `--thinking off` ou configure `agents.defaults.models["zai/"].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/"].params.tool_stream` como `false` para desativá-lo. -Modelos Anthropic Claude 4.6 usam `adaptive` por padrão para thinking quando nenhum nível explícito é definido. +Modelos Anthropic Claude 4.6 usam `adaptive` como padrão para thinking quando nenhum nível explícito é definido. ### `agents.defaults.cliBackends` -Backends opcionais de CLI para execuções de fallback somente texto (sem chamadas de ferramenta). Útil como backup quando provedores de API falham. +Backends opcionais de CLI para execuções de fallback somente texto (sem chamadas de ferramenta). Úteis como backup quando provedores de API falham. ```json5 { @@ -1110,9 +1159,9 @@ Backends opcionais de CLI para execuções de fallback somente texto (sem chamad } ``` -- Backends de CLI são voltados a texto; ferramentas sempre ficam desativadas. -- Sessões são compatíveis quando `sessionArg` está definido. -- Passagem de imagem é compatível quando `imageArg` aceita caminhos de arquivo. +- Backends de CLI são orientados a texto; ferramentas ficam sempre desativadas. +- Sessões são suportadas quando `sessionArg` está definido. +- Passagem de imagem é suportada quando `imageArg` aceita caminhos de arquivo. ### `agents.defaults.heartbeat` @@ -1142,10 +1191,10 @@ 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 `0m` para desativar. -- `suppressToolErrorWarnings`: quando true, suprime cargas de aviso de erro de ferramenta durante execuções de heartbeat. -- `directPolicy`: política de entrega direta/DM. `allow` (padrão) permite entrega a alvo direto. `block` suprime entrega a alvo direto e emite `reason=dm-blocked`. -- `lightContext`: quando true, execuções de heartbeat usam contexto bootstrap leve e mantêm apenas `HEARTBEAT.md` entre os arquivos bootstrap do workspace. -- `isolatedSession`: quando true, cada execução de heartbeat roda em uma sessão nova sem histórico anterior de conversa. Mesmo padrão de isolamento de cron `sessionTarget: "isolated"`. Reduz o custo de tokens por heartbeat de ~100K para ~2-5K tokens. +- `suppressToolErrorWarnings`: quando true, suprime payloads de aviso de erro de ferramenta durante execuções de heartbeat. +- `directPolicy`: política de entrega direta/DM. `allow` (padrão) permite entrega ao alvo direto. `block` suprime entrega ao alvo direto e emite `reason=dm-blocked`. +- `lightContext`: quando true, execuções de heartbeat usam contexto bootstrap leve e mantêm apenas `HEARTBEAT.md` dos arquivos bootstrap do workspace. +- `isolatedSession`: quando true, cada heartbeat roda em uma sessão nova sem histórico prévio de conversa. Mesmo padrão de isolamento do cron `sessionTarget: "isolated"`. Reduz o custo por heartbeat de ~100K para ~2-5K tokens. - Por agente: defina `agents.list[].heartbeat`. Quando qualquer agente define `heartbeat`, **somente esses agentes** executam heartbeats. - Heartbeats executam turnos completos de agente — intervalos menores consomem mais tokens. @@ -1178,18 +1227,18 @@ Execuções periódicas de heartbeat. ``` - `mode`: `default` ou `safeguard` (sumarização em blocos para históricos longos). Consulte [Compaction](/pt-BR/concepts/compaction). -- `provider`: ID de um plugin de provedor de compactação registrado. Quando definido, `summarize()` do provedor é chamado em vez da sumarização LLM integrada. Em caso de falha, recorre ao integrado. Definir um provedor força `mode: "safeguard"`. Consulte [Compaction](/pt-BR/concepts/compaction). -- `timeoutSeconds`: máximo de segundos permitidos para uma única operação de compactação antes que o OpenClaw a aborte. Padrão: `900`. -- `identifierPolicy`: `strict` (padrão), `off` ou `custom`. `strict` antepõe orientação integrada de retenção de identificadores opacos durante a sumarização da compactação. +- `provider`: id de um plugin de provedor de compactação registrado. Quando definido, o `summarize()` do provedor é chamado em vez da sumarização LLM embutida. Reverte para a embutida em caso de falha. Definir um provider força `mode: "safeguard"`. Consulte [Compaction](/pt-BR/concepts/compaction). +- `timeoutSeconds`: máximo de segundos permitido para uma única operação de compactação antes de o OpenClaw abortá-la. Padrão: `900`. +- `identifierPolicy`: `strict` (padrão), `off` ou `custom`. `strict` adiciona orientação embutida de preservação de identificadores opacos durante a sumarização de compactação. - `identifierInstructions`: texto opcional personalizado de preservação de identificadores usado quando `identifierPolicy=custom`. -- `postCompactionSections`: nomes opcionais de seções H2/H3 de `AGENTS.md` para reinjetar após a compactação. O padrão é `["Session Startup", "Red Lines"]`; defina `[]` para desativar a reinjeção. Quando não definido ou explicitamente definido 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` apenas para sumarização de compactação. Use isso quando a sessão principal deve manter um modelo, mas os resumos de compactação devem rodar em outro; quando não definido, a compactação usa o modelo principal da sessão. +- `postCompactionSections`: nomes opcionais de seções H2/H3 do AGENTS.md a serem reinjetadas após a compactação. 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, cabeçalhos antigos `Every Session`/`Safety` também são aceitos como fallback legado. +- `model`: substituição opcional `provider/model-id` apenas para a sumarização de compactação. Use isto quando a sessão principal deve manter um modelo, mas os resumos de compactação devem rodar em outro; quando não definido, a compactação usa o modelo primário da sessão. - `notifyUser`: quando `true`, envia um aviso breve ao usuário quando a compactação começa (por exemplo, "Compactando contexto..."). Desativado por padrão para manter a compactação silenciosa. -- `memoryFlush`: turno silencioso com agente antes da compactação automática para armazenar memórias persistentes. Ignorado quando o workspace está em modo somente leitura. +- `memoryFlush`: turno silencioso agentivo antes da autocompactação para armazenar memórias duráveis. Ignorado quando o workspace é somente leitura. ### `agents.defaults.contextPruning` -Remove **resultados antigos de ferramentas** do contexto em memória antes de enviá-lo ao LLM. **Não** modifica o histórico da sessão em disco. +Remove **resultados antigos de ferramenta** do contexto em memória antes de enviar ao LLM. **Não** modifica o histórico da sessão em disco. ```json5 { @@ -1213,23 +1262,23 @@ Remove **resultados antigos de ferramentas** do contexto em memória antes de en -- `mode: "cache-ttl"` ativa as passagens de poda. -- `ttl` controla com que frequência a poda pode ser executada novamente (após o último toque no cache). -- A poda primeiro faz soft-trim em resultados de ferramenta grandes demais e depois faz hard-clear em resultados mais antigos, se necessário. +- `mode: "cache-ttl"` habilita passes de pruning. +- `ttl` controla com que frequência o pruning pode ser executado novamente (após o último toque no cache). +- O pruning primeiro aplica soft-trim em resultados grandes de ferramenta e depois faz hard-clear em resultados antigos, se necessário. -**Soft-trim** mantém o começo + fim e insere `...` no meio. +**Soft-trim** mantém o início + fim e insere `...` no meio. **Hard-clear** substitui todo o resultado da ferramenta pelo placeholder. Observações: -- Blocos de imagem nunca são reduzidos/limpos. +- Blocos de imagem nunca são truncados/limpos. - As proporções são baseadas em caracteres (aproximadas), não em contagens exatas de tokens. -- Se existirem menos de `keepLastAssistants` mensagens do assistente, a poda é ignorada. +- Se houver menos que `keepLastAssistants` mensagens do assistente, o pruning é ignorado. -Consulte [Session Pruning](/pt-BR/concepts/session-pruning) para detalhes de comportamento. +Consulte [Session Pruning](/pt-BR/concepts/session-pruning) para detalhes do comportamento. ### Block streaming @@ -1247,7 +1296,7 @@ Consulte [Session Pruning](/pt-BR/concepts/session-pruning) para detalhes de com } ``` -- Canais que não sejam Telegram exigem `*.blockStreaming: true` explícito para ativar respostas em blocos. +- Canais que não são Telegram exigem `*.blockStreaming: true` explícito para habilitar respostas em bloco. - Substituições por canal: `channels..blockStreamingCoalesce` (e variantes por conta). Signal/Slack/Discord/Google Chat usam por padrão `minChars: 1500`. - `humanDelay`: pausa aleatória entre respostas em bloco. `natural` = 800–2500ms. Substituição por agente: `agents.list[].humanDelay`. @@ -1275,7 +1324,7 @@ Consulte [Typing Indicators](/pt-BR/concepts/typing-indicators). ### `agents.defaults.sandbox` -Sandboxing opcional para o agente embutido. Consulte [Sandboxing](/pt-BR/gateway/sandboxing) para o guia completo. +Sandbox opcional para o agente embutido. Consulte [Sandboxing](/pt-BR/gateway/sandboxing) para o guia completo. ```json5 { @@ -1374,42 +1423,42 @@ Sandboxing opcional para o agente embutido. Consulte [Sandboxing](/pt-BR/gateway **Backend:** -- `docker`: runtime local Docker (padrão) +- `docker`: runtime Docker local (padrão) - `ssh`: runtime remoto genérico baseado em SSH - `openshell`: runtime OpenShell -Quando `backend: "openshell"` é selecionado, as configurações específicas do runtime passam para +Quando `backend: "openshell"` é selecionado, configurações específicas do runtime passam para `plugins.entries.openshell.config`. **Configuração do backend SSH:** -- `target`: destino SSH no formato `user@host[:port]` +- `target`: alvo 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 ao OpenSSH -- `identityData` / `certificateData` / `knownHostsData`: conteúdo inline ou SecretRefs que o OpenClaw materializa em arquivos temporários em runtime -- `strictHostKeyChecking` / `updateHostKeys`: controles da política de chave de host do OpenSSH +- `identityFile` / `certificateFile` / `knownHostsFile`: arquivos locais existentes repassados ao OpenSSH +- `identityData` / `certificateData` / `knownHostsData`: conteúdos em linha 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 prioridade sobre `identityFile` +- `certificateData` tem prioridade sobre `certificateFile` +- `knownHostsData` tem prioridade 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 sandbox **Comportamento do backend SSH:** -- inicializa o workspace remoto uma vez após criar ou recriar +- semeia 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 via SSH -- não sincroniza automaticamente alterações remotas de volta para o host -- não oferece suporte a contêineres de navegador do sandbox +- não sincroniza automaticamente mudanças remotas de volta para o host +- não oferece suporte a contêineres de navegador em sandbox **Acesso ao workspace:** -- `none`: workspace do sandbox por escopo em `~/.openclaw/sandboxes` -- `ro`: workspace do sandbox em `/workspace`, workspace do agente montado em `/agent` somente leitura -- `rw`: workspace do agente montado em `/workspace` leitura/escrita +- `none`: workspace sandbox por escopo em `~/.openclaw/sandboxes` +- `ro`: workspace sandbox em `/workspace`, workspace do agente montado como somente leitura em `/agent` +- `rw`: workspace do agente montado como leitura/escrita em `/workspace` **Escopo:** @@ -1445,30 +1494,30 @@ Quando `backend: "openshell"` é selecionado, as configurações específicas do **Modo OpenShell:** -- `mirror`: inicializa o remoto a partir do local antes de `exec`, sincroniza de volta depois; o workspace local permanece canônico -- `remote`: inicializa o remoto uma vez quando o sandbox é criado e depois mantém o workspace remoto como canônico +- `mirror`: semeia o remoto a partir do local antes de exec, sincroniza de volta após exec; o workspace local permanece canônico +- `remote`: semeia o remoto uma vez quando o sandbox é criado e então mantém o workspace remoto como canônico -No modo `remote`, edições locais do host feitas fora do OpenClaw não são sincronizadas automaticamente para o sandbox após a etapa inicial. -O transporte é SSH para o sandbox OpenShell, mas o plugin controla o ciclo de vida do sandbox e a sincronização opcional mirror. +No modo `remote`, edições locais no host feitas fora do OpenClaw não são sincronizadas automaticamente para o sandbox após a etapa de semeadura. +O transporte é SSH para dentro do sandbox OpenShell, mas o plugin é responsável pelo ciclo de vida do sandbox e pela sincronização opcional no modo mirror. -**`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. +**`setupCommand`** executa 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. -**Contêineres usam por padrão `network: "none"`** — defina `"bridge"` (ou uma rede bridge personalizada) se o agente precisar de acesso de saída. +**Contêineres usam `network: "none"` por padrão** — defina `"bridge"` (ou uma rede bridge personalizada) se o agente precisar de acesso de saída. `"host"` é bloqueado. `"container:"` é bloqueado por padrão, a menos que você defina explicitamente -`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (break-glass). +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (uso de emergência). **Anexos recebidos** 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. -**Navegador em sandbox** (`sandbox.browser.enabled`): Chromium + CDP em um contêiner. A URL do noVNC é injetada no prompt do sistema. Não exige `browser.enabled` em `openclaw.json`. -O acesso de observação por 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). +**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 observador via 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) bloqueia sessões sandbox de apontar para o navegador do host. -- `network` usa por padrão `openclaw-sandbox-browser` (rede bridge dedicada). Defina `bridge` somente quando você quiser explicitamente conectividade global da bridge. -- `cdpSourceRange` opcionalmente restringe a entrada de 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 somente no contêiner do navegador sandbox. Quando definido (inclusive `[]`), 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 em contêiner: +- `allowHostControl: false` (padrão) bloqueia sessões em sandbox de mirar no navegador do host. +- `network` tem como padrão `openclaw-sandbox-browser` (rede bridge dedicada). Defina `bridge` apenas quando quiser explicitamente conectividade global de bridge. +- `cdpSourceRange` opcionalmente restringe 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. +- 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=` - `--user-data-dir=${HOME}/.chrome` @@ -1485,22 +1534,23 @@ O acesso de observação por noVNC usa autenticação VNC por padrão, e o OpenC - `--renderer-process-limit=2` - `--no-zygote` - `--metrics-recording-only` - - `--disable-extensions` (ativado por padrão) + - `--disable-extensions` (habilitado por padrão) - `--disable-3d-apis`, `--disable-software-rasterizer` e `--disable-gpu` são - ativados por padrão e podem ser desativados com + habilitados por padrão e podem ser desativados com `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` se o uso de WebGL/3D exigir isso. - - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` reativa extensões se seu fluxo de trabalho depender delas. + - `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=`; defina `0` para usar o - limite padrão de processos do Chromium. - - mais `--no-sandbox` e `--disable-setuid-sandbox` quando `noSandbox` está ativado. + limite de processos padrão do Chromium. + - além de `--no-sandbox` e `--disable-setuid-sandbox` quando `noSandbox` estiver habilitado. - Os padrões são a linha de base da imagem do contêiner; use uma imagem de navegador personalizada com um entrypoint personalizado para alterar os padrões do contêiner. -Sandboxing de navegador e `sandbox.docker.binds` atualmente são exclusivos do Docker. +O sandbox de navegador e `sandbox.docker.binds` atualmente funcionam apenas com Docker. -Crie as imagens: +Criar imagens: ```bash scripts/sandbox-setup.sh # main sandbox image @@ -1556,25 +1606,25 @@ scripts/sandbox-browser-setup.sh # optional browser image ``` - `id`: ID estável do agente (obrigatório). -- `default`: quando vários são definidos, o primeiro vence (um aviso é registrado). Se nenhum for definido, a primeira entrada da lista é a padrão. -- `model`: a forma string substitui apenas `primary`; a forma objeto `{ primary, fallbacks }` substitui ambos (`[]` desativa fallbacks globais). Jobs de 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 isso para substituições específicas do agente como `cacheRetention`, `temperature` ou `maxTokens` sem duplicar todo o catálogo de modelos. -- `skills`: lista opcional de permissão 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. +- `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`: o formato string substitui apenas `primary`; o formato objeto `{ primary, fallbacks }` substitui ambos (`[]` desabilita fallbacks globais). Tarefas 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 do modelo selecionado 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. +- `skills`: lista opcional de Skills permitidas 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 skill. - `thinkingDefault`: nível padrão opcional de thinking por agente (`off | minimal | low | medium | high | xhigh | adaptive`). Substitui `agents.defaults.thinkingDefault` para este agente quando não há substituição por mensagem ou sessão. -- `reasoningDefault`: substituição opcional por agente para visibilidade de reasoning (`on | off | stream`). Aplica-se quando não há substituição por mensagem ou sessão. +- `reasoningDefault`: visibilidade padrão opcional de reasoning por agente (`on | off | stream`). Aplica-se quando não há substituição por mensagem ou sessão. - `fastModeDefault`: padrão opcional por agente para modo rápido (`true | false`). Aplica-se quando não há substituição por mensagem ou sessão. -- `runtime`: descritor opcional de runtime por agente. Use `type: "acp"` com padrões `runtime.acp` (`agent`, `backend`, `mode`, `cwd`) quando o agente deve usar sessões do harness ACP por padrão. +- `runtime`: descritor opcional de runtime por agente. Use `type: "acp"` com padrões `runtime.acp` (`agent`, `backend`, `mode`, `cwd`) quando o agente deve usar por padrão sessões do harness ACP. - `identity.avatar`: caminho relativo ao workspace, URL `http(s)` ou URI `data:`. - `identity` deriva padrões: `ackReaction` a partir de `emoji`, `mentionPatterns` a partir de `name`/`emoji`. -- `subagents.allowAgents`: lista de permissão de IDs de agente para `sessions_spawn` (`["*"]` = qualquer; padrão: somente o mesmo agente). -- Proteção de herança do sandbox: se a sessão solicitante estiver em sandbox, `sessions_spawn` rejeita alvos que executariam sem sandbox. +- `subagents.allowAgents`: lista de IDs de agentes permitidos para `sessions_spawn` (`["*"]` = qualquer um; padrão: apenas o mesmo agente). +- Proteção de herança de sandbox: se a sessão solicitante estiver em sandbox, `sessions_spawn` rejeita alvos que executariam sem sandbox. - `subagents.requireAgentId`: quando true, bloqueia chamadas `sessions_spawn` que omitem `agentId` (força seleção explícita de perfil; padrão: false). --- -## Roteamento com vários agentes +## Roteamento multiagente -Execute vários agentes isolados dentro de um Gateway. Consulte [Multi-Agent](/pt-BR/concepts/multi-agent). +Execute vários agentes isolados dentro de um único Gateway. Consulte [Multi-Agent](/pt-BR/concepts/multi-agent). ```json5 { @@ -1591,9 +1641,9 @@ Execute vários agentes isolados dentro de um Gateway. Consulte [Multi-Agent](/p } ``` -### Campos de correspondência de binding +### Campos de correspondência do vínculo -- `type` (opcional): `route` para roteamento normal (tipo ausente assume route), `acp` para vínculos persistentes de conversa ACP. +- `type` (opcional): `route` para roteamento normal (tipo ausente equivale a route), `acp` para vínculos 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 }`) @@ -1606,12 +1656,12 @@ Execute vários agentes isolados dentro de um Gateway. Consulte [Multi-Agent](/p 2. `match.guildId` 3. `match.teamId` 4. `match.accountId` (exato, sem peer/guild/team) -5. `match.accountId: "*"` (em todo o canal) +5. `match.accountId: "*"` (abrangente ao canal) 6. Agente padrão -Dentro de cada nível, a primeira entrada correspondente de `bindings` vence. +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 binding de route 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 vínculo de rota acima. ### Perfis de acesso por agente @@ -1763,33 +1813,33 @@ Consulte [Multi-Agent Sandbox & Tools](/pt-BR/tools/multi-agent-sandbox-tools) p - **`scope`**: estratégia base de agrupamento de sessão 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 de um contexto de canal compartilham uma única sessão (use apenas quando o contexto compartilhado for intencional). -- **`dmScope`**: como mensagens diretas são agrupadas. - - `main`: todas as mensagens diretas compartilham a sessão principal. + - `global`: todos os participantes em um contexto de canal compartilham uma única sessão (use apenas quando contexto compartilhado for intencional). +- **`dmScope`**: como DMs são agrupadas. + - `main`: todas as DMs compartilham a sessão principal. - `per-peer`: isola por ID do 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 com prefixo de provedor para compartilhamento de sessão entre canais. -- **`reset`**: política primária de reset. `daily` redefine em `atHour` no horário local; `idle` redefine após `idleMinutes`. Quando ambos estão configurados, vence o que expirar primeiro. -- **`resetByType`**: substituições por tipo (`direct`, `group`, `thread`). O valor legado `dm` é aceito como alias para `direct`. -- **`parentForkMaxTokens`**: máximo de `totalTokens` da sessão pai permitido ao criar uma sessão de thread derivada (padrão `100000`). - - Se `totalTokens` da sessão pai estiver acima desse valor, o OpenClaw inicia uma nova sessão de thread em vez de herdar o histórico de transcrição da sessão pai. - - Defina `0` para desativar essa proteção e sempre permitir fork do pai. +- **`identityLinks`**: mapeia IDs canônicos para peers prefixados por provedor para compartilhamento de sessão entre canais. +- **`reset`**: política primária de reset. `daily` reinicia em `atHour` no horário local; `idle` reinicia após `idleMinutes`. Quando ambos estão configurados, o que expirar primeiro vence. +- **`resetByType`**: substituições por tipo (`direct`, `group`, `thread`). O legado `dm` é aceito como alias para `direct`. +- **`parentForkMaxTokens`**: máximo permitido de `totalTokens` na sessão pai ao criar uma sessão de thread bifurcada (padrão `100000`). + - Se `totalTokens` da sessão pai estiver acima desse valor, o OpenClaw inicia uma nova sessão de thread em vez de herdar o histórico da transcrição da sessão pai. + - Defina `0` para desativar essa proteção e sempre permitir bifurcação da sessão pai. - **`mainKey`**: campo legado. O runtime agora sempre usa `"main"` para o bucket principal de chat direto. -- **`agentToAgent.maxPingPongTurns`**: número máximo de turnos de resposta entre agentes em trocas entre agentes (inteiro, intervalo: `0`–`5`). `0` desativa encadeamento ping-pong. -- **`sendPolicy`**: corresponde por `channel`, `chatType` (`direct|group|channel`, com alias legado `dm`), `keyPrefix` ou `rawKeyPrefix`. A primeira negação vence. +- **`agentToAgent.maxPingPongTurns`**: número máximo de turnos de resposta de ida e volta entre agentes durante trocas entre agentes (inteiro, intervalo: `0`–`5`). `0` desativa encadeamento ping-pong. +- **`sendPolicy`**: faz correspondência 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. - - `mode`: `warn` emite apenas avisos; `enforce` aplica limpeza. - - `pruneAfter`: limite de idade para entradas obsoletas (padrão `30d`). + - `mode`: `warn` emite apenas avisos; `enforce` aplica a limpeza. + - `pruneAfter`: corte de idade para entradas antigas (padrão `30d`). - `maxEntries`: número máximo de entradas em `sessions.json` (padrão `500`). - `rotateBytes`: rotaciona `sessions.json` quando excede esse tamanho (padrão `10mb`). - `resetArchiveRetention`: retenção para arquivos de transcrição `*.reset.`. Por padrão usa `pruneAfter`; defina `false` para desativar. - - `maxDiskBytes`: orçamento opcional rígido de disco para o diretório de sessões. No modo `warn`, registra avisos; no modo `enforce`, remove primeiro os artefatos/sessões mais antigos. + - `maxDiskBytes`: orçamento opcional de disco para o 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 limpeza por orçamento. O padrão é `80%` de `maxDiskBytes`. - **`threadBindings`**: padrões globais para recursos de sessão vinculados a thread. - - `enabled`: chave mestre padrão (provedores podem substituir; Discord usa `channels.discord.threadBindings.enabled`) - - `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) + - `enabled`: chave mestra padrão (provedores podem substituir; Discord usa `channels.discord.threadBindings.enabled`) + - `idleHours`: padrão de desfoco automático por inatividade em horas (`0` desativa; provedores podem substituir) + - `maxAgeHours`: padrão de idade máxima rígida em horas (`0` desativa; provedores podem substituir) @@ -1833,32 +1883,32 @@ Resolução (o mais específico vence): conta → canal → global. `""` desativ **Variáveis de template:** -| 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 atual de thinking | `high`, `low`, `off` | -| `{identity.name}` | Nome da identidade do agente | (igual a `"auto"`) | +| `{provider}` | Nome do provedor | `anthropic` | +| `{thinkingLevel}` | Nível atual de thinking | `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}`. ### Reação de confirmação -- O padrão é `identity.emoji` do agente ativo; caso contrário `"👀"`. Defina `""` para desativar. +- O padrão é `identity.emoji` do agente ativo; caso contrário, `"👀"`. Defina `""` para desativar. - Substituições por canal: `channels..ackReaction`, `channels..accounts..ackReaction`. - Ordem de resolução: conta → canal → `messages.ackReaction` → fallback da identidade. - Escopo: `group-mentions` (padrão), `group-all`, `direct`, `all`. -- `removeAckAfterReply`: remove a confirmação após resposta no Slack, Discord e Telegram. -- `messages.statusReactions.enabled`: ativa reações de status do ciclo de vida no Slack, Discord e Telegram. - No Slack e Discord, se não definido, mantém reações de status ativadas quando reações de confirmação estão ativas. - No Telegram, defina explicitamente como `true` para ativar reações de status do ciclo de vida. +- `removeAckAfterReply`: remove a confirmação após a resposta em Slack, Discord e Telegram. +- `messages.statusReactions.enabled`: habilita reações de status de ciclo de vida em Slack, Discord e Telegram. + Em Slack e Discord, deixar sem definir mantém reações de status habilitadas quando reações de confirmação estão ativas. + No Telegram, defina explicitamente como `true` para habilitar reações de status de ciclo de vida. ### Debounce de entrada -Agrupa mensagens rápidas somente texto do mesmo remetente em um único turno do agente. Mídia/anexos forçam flush imediato. Comandos de controle ignoram o debounce. +Agrupa mensagens rápidas somente texto do mesmo remetente em um único turno de agente. Mídia/anexos descarregam imediatamente. Comandos de controle ignoram o debounce. -### TTS (text-to-speech) +### TTS (texto para fala) ```json5 { @@ -1899,11 +1949,11 @@ Agrupa mensagens rápidas somente texto do mesmo remetente em um único turno do } ``` -- `auto` controla TTS automático. `/tts off|always|inbound|tagged` substitui por sessão. -- `summaryModel` substitui `agents.defaults.model.primary` para resumo automático. -- `modelOverrides` está ativado por padrão; `modelOverrides.allowProvider` tem padrão `false` (adesão explícita). -- As chaves de API usam fallback para `ELEVENLABS_API_KEY`/`XI_API_KEY` e `OPENAI_API_KEY`. -- `openai.baseUrl` substitui o endpoint TTS da OpenAI. A ordem de resolução é configuração, depois `OPENAI_TTS_BASE_URL`, depois `https://api.openai.com/v1`. +- `auto` controla o modo padrão de auto-TTS: `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 autorresumo. +- `modelOverrides` é habilitado por padrão; `modelOverrides.allowProvider` tem padrão `false` (ativação opcional). +- Chaves de API usam `ELEVENLABS_API_KEY`/`XI_API_KEY` e `OPENAI_API_KEY` como fallback. +- `openai.baseUrl` substitui o endpoint TTS da OpenAI. A ordem de resolução é config, depois `OPENAI_TTS_BASE_URL`, depois `https://api.openai.com/v1`. - Quando `openai.baseUrl` aponta para um endpoint que não é da OpenAI, o OpenClaw o trata como um servidor TTS compatível com OpenAI e relaxa a validação de modelo/voz. --- @@ -1934,12 +1984,12 @@ Padrões para o modo Talk (macOS/iOS/Android). } ``` -- `talk.provider` deve corresponder a uma chave em `talk.providers` quando vários provedores Talk estiverem configurados. -- Chaves planas legadas de Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) são apenas para compatibilidade e são migradas automaticamente para `talk.providers.`. -- IDs de voz usam fallback para `ELEVENLABS_VOICE_ID` ou `SAG_VOICE_ID`. +- `talk.provider` deve corresponder a uma chave em `talk.providers` quando vários provedores de Talk estiverem configurados. +- Chaves legadas planas de Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) são compatibilidade apenas e são migradas automaticamente para `talk.providers.`. +- IDs de voz usam `ELEVENLABS_VOICE_ID` ou `SAG_VOICE_ID` como fallback. - `providers.*.apiKey` aceita strings em texto simples ou objetos SecretRef. - O fallback `ELEVENLABS_API_KEY` só se aplica quando nenhuma chave de API de Talk está configurada. -- `providers.*.voiceAliases` permite que diretivas Talk usem nomes amigáveis. +- `providers.*.voiceAliases` permite que diretivas de Talk usem nomes amigáveis. - `silenceTimeoutMs` controla quanto tempo o modo Talk espera 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 no macOS e Android, 900 ms no iOS`). --- @@ -1948,37 +1998,37 @@ Padrões para o modo Talk (macOS/iOS/Android). ### Perfis de ferramenta -`tools.profile` define uma lista de permissão base antes de `tools.allow`/`tools.deny`: +`tools.profile` define uma lista base de permitidos antes de `tools.allow`/`tools.deny`: -No onboarding local, novas configurações locais usam por padrão `tools.profile: "coding"` quando não definido (perfis explícitos existentes são preservados). +O onboarding local define por padrão novas configurações locais como `tools.profile: "coding"` quando ausente (perfis explícitos existentes são preservados). | Perfil | Inclui | | ----------- | ----------------------------------------------------------------------------------------------------------------------------- | | `minimal` | apenas `session_status` | | `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` | | `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | -| `full` | Sem restrição (igual a não definido) | +| `full` | Sem restrição (igual a não definir) | ### Grupos de ferramentas -| Grupo | Ferramentas | -| ------------------ | ----------------------------------------------------------------------------------------------------------------------- | -| `group:runtime` | `exec`, `process`, `code_execution` (`bash` é aceito como alias para `exec`) | -| `group:fs` | `read`, `write`, `edit`, `apply_patch` | +| Grupo | Ferramentas | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------- | +| `group:runtime` | `exec`, `process`, `code_execution` (`bash` é aceito como 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` | -| `group:web` | `web_search`, `x_search`, `web_fetch` | -| `group:ui` | `browser`, `canvas` | -| `group:automation` | `cron`, `gateway` | -| `group:messaging` | `message` | -| `group:nodes` | `nodes` | -| `group:agents` | `agents_list` | -| `group:media` | `image`, `image_generate`, `video_generate`, `tts` | -| `group:openclaw` | Todas as ferramentas integradas (exclui plugins de provedor) | +| `group:memory` | `memory_search`, `memory_get` | +| `group:web` | `web_search`, `x_search`, `web_fetch` | +| `group:ui` | `browser`, `canvas` | +| `group:automation` | `cron`, `gateway` | +| `group:messaging` | `message` | +| `group:nodes` | `nodes` | +| `group:agents` | `agents_list` | +| `group:media` | `image`, `image_generate`, `video_generate`, `tts` | +| `group:openclaw` | Todas as ferramentas embutidas (exclui plugins de provedor) | ### `tools.allow` / `tools.deny` -Política global de permissão/negação de ferramentas (negação vence). Não diferencia maiúsculas de minúsculas, oferece suporte a curingas `*`. Aplicada mesmo quando o sandbox Docker está desativado. +Política global de permitir/negar ferramentas (negação vence). Não diferencia maiúsculas de minúsculas, suporta curingas `*`. Aplicado mesmo quando o sandbox Docker está desligado. ```json5 { @@ -2004,7 +2054,7 @@ Restringe ainda mais ferramentas para provedores ou modelos específicos. Ordem: ### `tools.elevated` -Controla acesso elevado de exec fora do sandbox: +Controla acesso exec elevado fora do sandbox: ```json5 { @@ -2022,7 +2072,7 @@ Controla acesso elevado de exec fora do sandbox: - A substituição por agente (`agents.list[].tools.elevated`) só pode restringir ainda mais. - `/elevated on|off|ask|full` armazena o estado por sessão; diretivas inline se aplicam a uma única mensagem. -- `exec` elevado ignora o sandboxing e usa o caminho de escape configurado (`gateway` por padrão, ou `node` quando o alvo de exec é `node`). +- `exec` elevado contorna o sandbox e usa o caminho de escape configurado (`gateway` por padrão, ou `node` quando o alvo exec é `node`). ### `tools.exec` @@ -2046,7 +2096,7 @@ Controla acesso elevado de exec fora do sandbox: ### `tools.loopDetection` -As verificações de segurança de loop de ferramenta são **desativadas por padrão**. Defina `enabled: true` para ativar a detecção. +Verificações de segurança para loops de ferramenta são **desativadas por padrão**. Defina `enabled: true` para ativar a detecção. As configurações podem ser definidas globalmente em `tools.loopDetection` e substituídas por agente em `agents.list[].tools.loopDetection`. ```json5 @@ -2068,13 +2118,13 @@ As configurações podem ser definidas globalmente em `tools.loopDetection` e su } ``` -- `historySize`: máximo de histórico de chamadas de ferramenta mantido para análise de loop. -- `warningThreshold`: limite de padrão repetitivo sem progresso para avisos. -- `criticalThreshold`: limite repetitivo maior para bloquear loops críticos. -- `globalCircuitBreakerThreshold`: limite rígido de parada para qualquer execução sem progresso. +- `historySize`: máximo de histórico de chamadas de ferramenta retido para análise de loop. +- `warningThreshold`: limite de padrão repetido sem progresso para avisos. +- `criticalThreshold`: limite repetido mais alto para bloquear loops críticos. +- `globalCircuitBreakerThreshold`: limite de parada rígida para qualquer execução sem progresso. - `detectors.genericRepeat`: avisa sobre chamadas repetidas da mesma ferramenta/com os mesmos argumentos. -- `detectors.knownPollNoProgress`: avisa/bloqueia ferramentas conhecidas de poll (`process.poll`, `command_status` etc.). -- `detectors.pingPong`: avisa/bloqueia padrões alternados sem progresso em pares. +- `detectors.knownPollNoProgress`: avisa/bloqueia ferramentas de polling conhecidas (`process.poll`, `command_status` etc.). +- `detectors.pingPong`: avisa/bloqueia padrões alternados em pares sem progresso. - Se `warningThreshold >= criticalThreshold` ou `criticalThreshold >= globalCircuitBreakerThreshold`, a validação falha. ### `tools.web` @@ -2146,13 +2196,13 @@ Configura entendimento de mídia recebida (imagem/áudio/vídeo): **Entrada de provedor** (`type: "provider"` ou omitido): - `provider`: ID do provedor de API (`openai`, `anthropic`, `google`/`gemini`, `groq` etc.) -- `model`: substituição de ID de modelo +- `model`: substituição de ID do modelo - `profile` / `preferredProfile`: seleção de perfil em `auth-profiles.json` **Entrada de CLI** (`type: "cli"`): -- `command`: executável a ser rodado -- `args`: argumentos com template (compatível com `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` etc.) +- `command`: executável a ser executado +- `args`: argumentos com template (suporta `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` etc.) **Campos comuns:** @@ -2165,8 +2215,8 @@ A autenticação do provedor segue a ordem padrão: `auth-profiles.json` → var **Campos de conclusão assíncrona:** - `asyncCompletion.directSend`: quando `true`, tarefas assíncronas concluídas de `music_generate` - e `video_generate` tentam primeiro a entrega direta ao canal. Padrão: `false` - (caminho legado de ativação da sessão solicitante/entrega pelo modelo). + e `video_generate` tentam primeiro entrega direta ao canal. Padrão: `false` + (caminho legado de despertar sessão solicitante/entrega por modelo). @@ -2204,13 +2254,13 @@ Observações: - `self`: apenas a chave da sessão atual. - `tree`: sessão atual + sessões geradas pela sessão atual (subagentes). -- `agent`: qualquer sessão pertencente ao ID do agente atual (pode incluir outros usuários se você executar sessões per-sender sob o mesmo ID de agente). -- `all`: qualquer sessão. O direcionamento entre agentes ainda requer `tools.agentToAgent`. -- Restrição por sandbox: quando a sessão atual está em sandbox e `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, a visibilidade é forçada para `tree` mesmo se `tools.sessions.visibility="all"`. +- `agent`: qualquer sessão pertencente ao ID do agente atual (pode incluir outros usuários se você executar sessões por remetente sob o mesmo ID de agente). +- `all`: qualquer sessão. Direcionamento entre agentes ainda exige `tools.agentToAgent`. +- Limite do sandbox: quando a sessão atual está em sandbox e `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, a visibilidade é forçada para `tree` mesmo que `tools.sessions.visibility="all"`. ### `tools.sessions_spawn` -Controla o suporte a anexos inline para `sessions_spawn`. +Controla suporte a anexos inline para `sessions_spawn`. ```json5 { @@ -2230,16 +2280,16 @@ Controla o suporte a anexos inline para `sessions_spawn`. Observações: -- Anexos só são compatíveis com `runtime: "subagent"`. O runtime ACP os rejeita. -- Os arquivos são materializados no workspace filho em `.openclaw/attachments//` com um `.manifest.json`. +- Anexos são suportados apenas para `runtime: "subagent"`. O runtime ACP os rejeita. +- Arquivos são materializados no workspace filho em `.openclaw/attachments//` com um `.manifest.json`. - O conteúdo dos anexos é automaticamente redigido da persistência da transcrição. -- Entradas em base64 são validadas com verificações rigorosas de alfabeto/preenchimento e proteção de tamanho antes da decodificação. -- As permissões de arquivo são `0700` para diretórios e `0600` para arquivos. -- A limpeza segue a política `cleanup`: `delete` sempre remove anexos; `keep` os mantém apenas quando `retainOnSessionKeep: true`. +- Entradas base64 são validadas com verificações estritas de alfabeto/padding e proteção de tamanho antes da decodificação. +- Permissões de arquivo são `0700` para diretórios e `0600` para arquivos. +- A limpeza segue a política `cleanup`: `delete` sempre remove anexos; `keep` os retém apenas quando `retainOnSessionKeep: true`. ### `tools.experimental` -Flags experimentais para ferramentas integradas. Padrão desligado, a menos que uma regra de ativação automática específica do runtime se aplique. +Sinalizadores experimentais de ferramentas embutidas. O padrão é desligado, a menos que uma regra automática específica de runtime se aplique. ```json5 { @@ -2253,9 +2303,9 @@ Flags experimentais para ferramentas integradas. Padrão desligado, a menos que Observações: -- `planTool`: ativa a ferramenta estruturada experimental `update_plan` para acompanhamento de trabalho não trivial em múltiplas etapas. -- Padrão: `false` para provedores que não sejam OpenAI. Execuções OpenAI e OpenAI Codex a ativam automaticamente. -- Quando ativada, o prompt do sistema também adiciona orientação de uso para que o modelo só a use em trabalho substancial e mantenha no máximo uma etapa `in_progress`. +- `planTool`: habilita a ferramenta estruturada `update_plan` para acompanhamento de trabalho não trivial em várias etapas. +- Padrão: `false` para provedores que não são OpenAI. Execuções OpenAI e OpenAI Codex a habilitam automaticamente quando não definida; defina `false` para desativar essa ativação automática. +- Quando habilitada, o prompt do sistema também adiciona orientação de uso para que o modelo a utilize apenas para trabalho substancial e mantenha no máximo uma etapa `in_progress`. ### `agents.defaults.subagents` @@ -2276,15 +2326,15 @@ Observações: ``` - `model`: modelo padrão para subagentes gerados. Se omitido, subagentes herdam o modelo do chamador. -- `allowAgents`: lista padrão de permissão de IDs de agente alvo para `sessions_spawn` quando o agente solicitante não define seu próprio `subagents.allowAgents` (`["*"]` = qualquer; padrão: somente o mesmo agente). +- `allowAgents`: lista padrão de IDs de agentes permitidos para `sessions_spawn` quando o agente solicitante não define seu próprio `subagents.allowAgents` (`["*"]` = qualquer um; padrão: apenas o mesmo agente). - `runTimeoutSeconds`: timeout padrão (segundos) para `sessions_spawn` quando a chamada da ferramenta omite `runTimeoutSeconds`. `0` significa sem timeout. -- Política de ferramentas por subagente: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. +- Política de ferramenta por subagente: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. --- -## Provedores personalizados e URLs base +## Provedores personalizados e base URLs -O OpenClaw usa o catálogo de modelos integrado. Adicione provedores personalizados via `models.providers` na configuração ou `~/.openclaw/agents//agent/models.json`. +O OpenClaw usa o catálogo de modelos embutido. Adicione provedores personalizados via `models.providers` na configuração ou `~/.openclaw/agents//agent/models.json`. ```json5 { @@ -2316,38 +2366,38 @@ O OpenClaw usa o catálogo de modelos integrado. Adicione provedores personaliza - Use `authHeader: true` + `headers` para necessidades personalizadas de autenticação. - Substitua a raiz de configuração do agente com `OPENCLAW_AGENT_DIR` (ou `PI_CODING_AGENT_DIR`, um alias legado de variável de ambiente). - Precedência de mesclagem para IDs de provedor correspondentes: - - Valores não vazios de `baseUrl` em `models.json` do agente prevalecem. - - Valores não vazios de `apiKey` do agente prevalecem somente quando esse provedor não é gerenciado por SecretRef no contexto atual de configuração/perfil de autenticação. - - Valores `apiKey` de provedor gerenciados por SecretRef são atualizados a partir de marcadores de origem (`ENV_VAR_NAME` para refs de ambiente, `secretref-managed` para refs de arquivo/exec) em vez de persistir segredos resolvidos. - - Valores de header de provedor gerenciados por SecretRef são atualizados a partir de marcadores de origem (`secretref-env:ENV_VAR_NAME` para refs de ambiente, `secretref-managed` para refs de arquivo/exec). + - Valores não vazios de `baseUrl` em `models.json` do agente têm prioridade. + - Valores não vazios de `apiKey` do agente têm prioridade apenas quando esse provedor não é gerenciado por SecretRef no contexto atual de config/perfil de autenticação. + - Valores `apiKey` de provedor gerenciados por SecretRef são atualizados a partir de marcadores de origem (`ENV_VAR_NAME` para refs de env, `secretref-managed` para refs de file/exec) em vez de persistir segredos resolvidos. + - Valores de cabeçalho de provedor gerenciados por SecretRef são atualizados a partir de marcadores de origem (`secretref-env:ENV_VAR_NAME` para refs de env, `secretref-managed` para refs de file/exec). - `apiKey`/`baseUrl` vazios ou ausentes no agente recorrem a `models.providers` na configuração. - - `contextWindow`/`maxTokens` de modelo correspondente usam o maior valor entre a configuração explícita e os valores implícitos do catálogo. + - `contextWindow`/`maxTokens` de modelo correspondente usam o valor mais alto entre configuração explícita e valores implícitos do catálogo. - `contextTokens` de modelo correspondente preserva um limite explícito de runtime quando presente; use-o para limitar o contexto efetivo sem alterar os metadados nativos do modelo. - Use `models.mode: "replace"` quando quiser que a configuração reescreva totalmente `models.json`. - - A persistência de marcadores é autoritativa da origem: os marcadores são gravados a partir do snapshot ativo de configuração de origem (pré-resolução), não a partir dos valores reais de segredo resolvidos em runtime. + - A persistência de marcadores é autoritativa pela origem: marcadores são gravados a partir do snapshot ativo de configuração de origem (pré-resolução), não a partir de valores secretos resolvidos em runtime. ### Detalhes dos campos do provedor - `models.mode`: comportamento do catálogo de provedores (`merge` ou `replace`). -- `models.providers`: mapa de provedores personalizados com chave pelo ID do provedor. -- `models.providers.*.api`: adaptador de requisição (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai` etc.). -- `models.providers.*.apiKey`: credencial do provedor (prefira SecretRef/substituição por ambiente). +- `models.providers`: mapa de provedores personalizados indexado por ID do provedor. +- `models.providers.*.api`: adaptador de requisição (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai` etc). +- `models.providers.*.apiKey`: credencial do provedor (prefira SecretRef/substituição por variável de ambiente). - `models.providers.*.auth`: estratégia de autenticação (`api-key`, `token`, `oauth`, `aws-sdk`). - `models.providers.*.injectNumCtxForOpenAICompat`: para Ollama + `openai-completions`, injeta `options.num_ctx` nas requisições (padrão: `true`). -- `models.providers.*.authHeader`: força o transporte da credencial no header `Authorization` quando necessário. +- `models.providers.*.authHeader`: força transporte da credencial no cabeçalho `Authorization` quando necessário. - `models.providers.*.baseUrl`: URL base da API upstream. -- `models.providers.*.headers`: headers estáticos extras para roteamento por proxy/tenant. -- `models.providers.*.request`: substituições de transporte para requisições HTTP do provedor de modelo. - - `request.headers`: headers extras (mesclados com os padrões do provedor). Os valores aceitam SecretRef. - - `request.auth`: substituição da estratégia de autenticação. Modos: `"provider-default"` (usa a autenticação integrada do provedor), `"authorization-bearer"` (com `token`), `"header"` (com `headerName`, `value`, `prefix` opcional). - - `request.proxy`: substituição de proxy HTTP. Modos: `"env-proxy"` (usa variáveis de ambiente `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (com `url`). Ambos os modos aceitam um subobjeto opcional `tls`. - - `request.tls`: substituição TLS para conexões diretas. Campos: `ca`, `cert`, `key`, `passphrase` (todos aceitam SecretRef), `serverName`, `insecureSkipVerify`. +- `models.providers.*.headers`: cabeçalhos estáticos extras para roteamento de proxy/tenant. +- `models.providers.*.request`: substituições de transporte para requisições HTTP do provedor de modelos. + - `request.headers`: cabeçalhos extras (mesclados com os padrões do provedor). Valores aceitam SecretRef. + - `request.auth`: substituição da estratégia de autenticação. Modos: `"provider-default"` (usa a autenticação embutida do provedor), `"authorization-bearer"` (com `token`), `"header"` (com `headerName`, `value`, `prefix` opcional). + - `request.proxy`: substituição de proxy HTTP. Modos: `"env-proxy"` (usa variáveis `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (com `url`). Ambos os modos aceitam um subobjeto `tls` opcional. + - `request.tls`: substituição de TLS para conexões diretas. Campos: `ca`, `cert`, `key`, `passphrase` (todos aceitam SecretRef), `serverName`, `insecureSkipVerify`. - `models.providers.*.models`: entradas explícitas do catálogo de modelos do provedor. -- `models.providers.*.models.*.contextWindow`: metadados nativos da janela de contexto do modelo. -- `models.providers.*.models.*.contextTokens`: limite opcional de contexto em runtime. Use isso quando quiser um orçamento de contexto efetivo menor do que o `contextWindow` nativo do modelo. -- `models.providers.*.models.*.compat.supportsDeveloperRole`: dica opcional de compatibilidade. Para `api: "openai-completions"` com `baseUrl` não nativa e não vazia (host não `api.openai.com`), o OpenClaw força isso para `false` em runtime. `baseUrl` vazio/omitido mantém o comportamento padrão da OpenAI. -- `models.providers.*.models.*.compat.requiresStringContent`: dica opcional de compatibilidade para endpoints de chat compatíveis com OpenAI que aceitam apenas string. Quando `true`, o OpenClaw achata arrays `messages[].content` puramente textuais em strings simples antes de enviar a requisição. -- `plugins.entries.amazon-bedrock.config.discovery`: raiz das configurações de autodiscovery do Bedrock. +- `models.providers.*.models.*.contextWindow`: metadados da janela nativa de contexto do modelo. +- `models.providers.*.models.*.contextTokens`: limite opcional de contexto em runtime. Use isto quando quiser um orçamento de contexto efetivo menor do que o `contextWindow` nativo do modelo. +- `models.providers.*.models.*.compat.supportsDeveloperRole`: dica opcional de compatibilidade. Para `api: "openai-completions"` com `baseUrl` não nativa e não vazia (host diferente de `api.openai.com`), o OpenClaw força isso para `false` em runtime. `baseUrl` vazio/omitido mantém o comportamento padrão da OpenAI. +- `models.providers.*.models.*.compat.requiresStringContent`: dica opcional de compatibilidade para endpoints de chat compatíveis com OpenAI que aceitam apenas string. Quando `true`, o OpenClaw achata arrays puros de texto em `messages[].content` para strings simples antes de enviar a requisição. +- `plugins.entries.amazon-bedrock.config.discovery`: raiz das configurações de autodescoberta do Bedrock. - `plugins.entries.amazon-bedrock.config.discovery.enabled`: ativa/desativa descoberta implícita. - `plugins.entries.amazon-bedrock.config.discovery.region`: região AWS para descoberta. - `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: filtro opcional por ID de provedor para descoberta direcionada. @@ -2408,7 +2458,7 @@ Use `cerebras/zai-glm-4.7` para Cerebras; `zai/glm-4.7` para Z.AI direto. } ``` -Defina `OPENCODE_API_KEY` (ou `OPENCODE_ZEN_API_KEY`). Use referências `opencode/...` para o catálogo Zen ou `opencode-go/...` para o catálogo Go. Atalho: `openclaw onboard --auth-choice opencode-zen` ou `openclaw onboard --auth-choice opencode-go`. +Defina `OPENCODE_API_KEY` (ou `OPENCODE_ZEN_API_KEY`). Use refs `opencode/...` para o catálogo Zen ou refs `opencode-go/...` para o catálogo Go. Atalho: `openclaw onboard --auth-choice opencode-zen` ou `openclaw onboard --auth-choice opencode-go`. @@ -2429,7 +2479,7 @@ Defina `ZAI_API_KEY`. `z.ai/*` e `z-ai/*` são aliases aceitos. Atalho: `opencla - Endpoint geral: `https://api.z.ai/api/paas/v4` - Endpoint de coding (padrão): `https://api.z.ai/api/coding/paas/v4` -- Para o endpoint geral, defina um provedor personalizado com a substituição de URL base. +- Para o endpoint geral, defina um provedor personalizado com substituição de base URL. @@ -2468,11 +2518,11 @@ Defina `ZAI_API_KEY`. `z.ai/*` e `z-ai/*` são aliases aceitos. Atalho: `opencla } ``` -Para o endpoint na China: `baseUrl: "https://api.moonshot.cn/v1"` ou `openclaw onboard --auth-choice moonshot-api-key-cn`. +Para o endpoint da China: `baseUrl: "https://api.moonshot.cn/v1"` ou `openclaw onboard --auth-choice moonshot-api-key-cn`. -Endpoints nativos da Moonshot anunciam compatibilidade de uso de streaming no transporte compartilhado -`openai-completions`, e o OpenClaw agora baseia isso em capacidades do endpoint -em vez de apenas no ID de provedor integrado. +Os endpoints nativos da Moonshot anunciam compatibilidade de uso de streaming no transporte compartilhado +`openai-completions`, e o OpenClaw agora decide isso com base nas +capacidades do endpoint em vez de apenas no ID do provedor embutido. @@ -2490,7 +2540,7 @@ em vez de apenas no ID de provedor integrado. } ``` -Compatível com Anthropic, provedor integrado. Atalho: `openclaw onboard --auth-choice kimi-code-api-key`. +Compatível com Anthropic, provedor embutido. Atalho: `openclaw onboard --auth-choice kimi-code-api-key`. @@ -2529,7 +2579,7 @@ Compatível com Anthropic, provedor integrado. Atalho: `openclaw onboard --auth- } ``` -A URL base deve omitir `/v1` (o cliente Anthropic acrescenta isso). Atalho: `openclaw onboard --auth-choice synthetic-api-key`. +A base URL deve omitir `/v1` (o cliente Anthropic a acrescenta). Atalho: `openclaw onboard --auth-choice synthetic-api-key`. @@ -2572,7 +2622,7 @@ A URL base deve omitir `/v1` (o cliente Anthropic acrescenta isso). Atalho: `ope Defina `MINIMAX_API_KEY`. Atalhos: `openclaw onboard --auth-choice minimax-global-api` ou `openclaw onboard --auth-choice minimax-cn-api`. -O catálogo de modelos agora usa por padrão apenas M2.7. +O catálogo de modelos agora usa apenas M2.7 por padrão. No caminho de streaming compatível com Anthropic, o OpenClaw desativa o thinking do MiniMax por padrão, a menos que você defina `thinking` explicitamente. `/fast on` ou `params.fastMode: true` reescreve `MiniMax-M2.7` para @@ -2582,7 +2632,7 @@ por padrão, a menos que você defina `thinking` explicitamente. `/fast on` ou -Consulte [Local Models](/pt-BR/gateway/local-models). Resumindo: execute um grande modelo local pela Responses API do LM Studio em hardware robusto; mantenha modelos hospedados mesclados para fallback. +Consulte [Local Models](/pt-BR/gateway/local-models). Resumindo: execute um grande modelo local via API Responses do LM Studio em hardware robusto; mantenha modelos hospedados mesclados para fallback. @@ -2613,12 +2663,14 @@ Consulte [Local Models](/pt-BR/gateway/local-models). Resumindo: execute um gran } ``` -- `allowBundled`: lista opcional de permissão apenas para Skills empacotadas (Skills gerenciadas/do workspace não são afetadas). -- `load.extraDirs`: raízes extras compartilhadas de Skills (menor precedência). -- `install.preferBrew`: quando true, prefere instaladores Homebrew quando `brew` está disponível antes de recorrer a outros tipos de instalador. -- `install.nodeManager`: preferência de instalador Node para especificações `metadata.openclaw.install` (`npm` | `pnpm` | `yarn` | `bun`). -- `entries..enabled: false` desativa uma Skill mesmo se estiver empacotada/instalada. -- `entries..apiKey`: conveniência de chave de API para Skills que declaram uma variável de ambiente principal (string em texto simples ou objeto SecretRef). +- `allowBundled`: lista opcional de permitidos apenas para Skills empacotadas (Skills gerenciadas/do workspace não são afetadas). +- `load.extraDirs`: raízes extras compartilhadas de Skill (menor precedência). +- `install.preferBrew`: quando true, prefere instaladores Homebrew quando `brew` está + disponível antes de recorrer a outros tipos de instalador. +- `install.nodeManager`: preferência de instalador Node para especificações `metadata.openclaw.install` + (`npm` | `pnpm` | `yarn` | `bun`). +- `entries..enabled: false` desativa uma skill mesmo se estiver empacotada/instalada. +- `entries..apiKey`: campo de conveniência para Skills que declaram uma variável primária de ambiente (string em texto simples ou objeto SecretRef). --- @@ -2647,40 +2699,46 @@ Consulte [Local Models](/pt-BR/gateway/local-models). Resumindo: execute um gran ``` - Carregados de `~/.openclaw/extensions`, `/.openclaw/extensions` e `plugins.load.paths`. -- A descoberta aceita plugins nativos do OpenClaw, além de bundles compatíveis do Codex e Claude, incluindo bundles do Claude sem manifesto no layout padrão. -- **Mudanças de configuração exigem reinício do gateway.** -- `allow`: lista opcional de permissão (somente os plugins listados carregam). `deny` vence. -- `plugins.entries..apiKey`: campo de conveniência para chave de API em nível de plugin (quando compatível com o plugin). -- `plugins.entries..env`: mapa de variáveis de ambiente no escopo do plugin. -- `plugins.entries..hooks.allowPromptInjection`: quando `false`, o core bloqueia `before_prompt_build` e ignora campos que alteram o prompt vindos do legado `before_agent_start`, preservando `modelOverride` e `providerOverride` legados. Aplica-se a hooks nativos de plugin e diretórios de hook oferecidos por bundles compatíveis. +- A descoberta aceita plugins nativos OpenClaw e pacotes compatíveis de Codex e Claude, incluindo pacotes Claude sem manifesto no layout padrão. +- **Alterações de configuração exigem reinício do gateway.** +- `allow`: lista opcional de permitidos (somente plugins listados são carregados). `deny` prevalece. +- `plugins.entries..apiKey`: campo de conveniência para chave de API no nível do plugin (quando suportado pelo plugin). +- `plugins.entries..env`: mapa de variáveis de ambiente com escopo do plugin. +- `plugins.entries..hooks.allowPromptInjection`: quando `false`, o core bloqueia `before_prompt_build` e ignora campos que alteram prompt de `before_agent_start` legado, preservando `modelOverride` e `providerOverride` legados. Aplica-se a hooks de plugin nativo e diretórios de hook suportados fornecidos por pacotes. - `plugins.entries..subagent.allowModelOverride`: confia explicitamente neste plugin para solicitar substituições por execução de `provider` e `model` em execuções de subagente em segundo plano. -- `plugins.entries..subagent.allowedModels`: lista opcional de permissão de alvos canônicos `provider/model` para substituições confiáveis de subagente. Use `"*"` somente quando você quiser intencionalmente permitir qualquer modelo. -- `plugins.entries..config`: objeto de configuração definido pelo plugin (validado pelo esquema de plugin nativo do OpenClaw, quando disponível). -- `plugins.entries.firecrawl.config.webFetch`: configurações do provedor web-fetch Firecrawl. - - `apiKey`: chave de API do Firecrawl (aceita SecretRef). Usa `plugins.entries.firecrawl.config.webSearch.apiKey`, legado `tools.web.fetch.firecrawl.apiKey` ou variável de ambiente `FIRECRAWL_API_KEY` como fallback. +- `plugins.entries..subagent.allowedModels`: lista opcional de permitidos de alvos canônicos `provider/model` para substituições confiáveis de subagente. Use `"*"` apenas quando quiser intencionalmente permitir qualquer modelo. +- `plugins.entries..config`: objeto de configuração definido pelo plugin (validado pelo schema de plugin nativo OpenClaw quando disponível). +- `plugins.entries.firecrawl.config.webFetch`: configurações do provedor Firecrawl de web fetch. + - `apiKey`: chave de API do Firecrawl (aceita SecretRef). Usa como fallback `plugins.entries.firecrawl.config.webSearch.apiKey`, `tools.web.fetch.firecrawl.apiKey` legado ou variável de ambiente `FIRECRAWL_API_KEY`. - `baseUrl`: URL base da API Firecrawl (padrão: `https://api.firecrawl.dev`). - - `onlyMainContent`: extrai somente o conteúdo principal das páginas (padrão: `true`). + - `onlyMainContent`: extrai apenas o conteúdo principal das páginas (padrão: `true`). - `maxAgeMs`: idade máxima do cache em milissegundos (padrão: `172800000` / 2 dias). - - `timeoutSeconds`: timeout da requisição de scrape em segundos (padrão: `60`). -- `plugins.entries.xai.config.xSearch`: configurações do X Search da xAI (busca web do Grok). - - `enabled`: ativa o provedor X Search. - - `model`: modelo Grok a usar para busca (por exemplo `"grok-4-1-fast"`). + - `timeoutSeconds`: timeout da requisição de scraping em segundos (padrão: `60`). +- `plugins.entries.xai.config.xSearch`: configurações do xAI X Search (busca web Grok). + - `enabled`: habilita o provedor X Search. + - `model`: modelo Grok a ser usado para busca (por exemplo `"grok-4-1-fast"`). - `plugins.entries.memory-core.config.dreaming`: configurações de memory dreaming (experimental). Consulte [Dreaming](/pt-BR/concepts/dreaming) para fases e limites. - - `enabled`: chave mestre do dreaming (padrão `false`). - - `frequency`: cadência cron para cada varredura completa de dreaming (`"0 3 * * *"` por padrão). - - política de fase e limites são detalhes de implementação (não são chaves de configuração voltadas ao usuário). -- Plugins Claude bundle ativados também podem contribuir com padrões embutidos do Pi de `settings.json`; o OpenClaw os aplica como configurações sanitizadas de agente, não como patches brutos de configuração do OpenClaw. -- `plugins.slots.memory`: escolhe o ID do plugin de memória ativo, ou `"none"` para desativar plugins de memória. -- `plugins.slots.contextEngine`: escolhe o ID do plugin de engine de contexto ativo; o padrão é `"legacy"` a menos que você instale e selecione outro engine. + - `enabled`: chave mestra de dreaming (padrão `false`). + - `frequency`: cadência cron de cada varredura completa de dreaming (`"0 3 * * *"` por padrão). + - política de fases e limites são detalhes de implementação (não são chaves de configuração voltadas ao usuário). +- A configuração completa de memória está em [Referência de configuração de memória](/pt-BR/reference/memory-config): + - `agents.defaults.memorySearch.*` + - `memory.backend` + - `memory.citations` + - `memory.qmd.*` + - `plugins.entries.memory-core.config.dreaming` +- Plugins Claude bundle habilitados também podem contribuir com padrões Pi embutidos de `settings.json`; o OpenClaw os aplica como configurações sanitizadas de agente, não como patches brutos de configuração do OpenClaw. +- `plugins.slots.memory`: escolha o ID do plugin de memória ativo, ou `"none"` para desativar plugins de memória. +- `plugins.slots.contextEngine`: escolha o ID do plugin de mecanismo de contexto ativo; o padrão é `"legacy"` até que você instale e selecione outro mecanismo. - `plugins.installs`: metadados de instalação gerenciados pela CLI usados por `openclaw plugins update`. - Inclui `source`, `spec`, `sourcePath`, `installPath`, `version`, `resolvedName`, `resolvedVersion`, `resolvedSpec`, `integrity`, `shasum`, `resolvedAt`, `installedAt`. - - Trate `plugins.installs.*` como estado gerenciado; prefira comandos da CLI em vez de edições manuais. + - Trate `plugins.installs.*` como estado gerenciado; prefira comandos da CLI a edições manuais. Consulte [Plugins](/pt-BR/tools/plugin). --- -## Navegador +## Browser ```json5 { @@ -2716,24 +2774,24 @@ Consulte [Plugins](/pt-BR/tools/plugin). } ``` -- `evaluateEnabled: false` desativa `act:evaluate` e `wait --fn`. -- `ssrfPolicy.dangerouslyAllowPrivateNetwork` usa por padrão `true` quando não definido (modelo de rede confiável). -- Defina `ssrfPolicy.dangerouslyAllowPrivateNetwork: false` para navegação estrita do navegador apenas em rede pública. -- No modo estrito, endpoints de perfil CDP remoto (`profiles.*.cdpUrl`) ficam sujeitos ao mesmo bloqueio de rede privada durante verificações de alcance/descoberta. -- `ssrfPolicy.allowPrivateNetwork` continua compatível como alias legado. +- `evaluateEnabled: false` desabilita `act:evaluate` e `wait --fn`. +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` assume o valor padrão `true` quando não definido (modelo de rede confiável). +- Defina `ssrfPolicy.dangerouslyAllowPrivateNetwork: false` para navegação estrita do browser apenas em rede pública. +- No modo estrito, endpoints remotos de perfil CDP (`profiles.*.cdpUrl`) estão sujeitos ao mesmo bloqueio de rede privada durante verificações de alcance/descoberta. +- `ssrfPolicy.allowPrivateNetwork` continua suportado como alias legado. - No modo estrito, use `ssrfPolicy.hostnameAllowlist` e `ssrfPolicy.allowedHostnames` para exceções explícitas. -- Perfis remotos são somente anexação (iniciar/parar/reset desativados). +- Perfis remotos são somente attach (start/stop/reset desativados). - `profiles.*.cdpUrl` aceita `http://`, `https://`, `ws://` e `wss://`. Use HTTP(S) quando quiser que o OpenClaw descubra `/json/version`; use WS(S) quando seu provedor fornecer uma URL WebSocket direta do DevTools. -- Perfis `existing-session` são apenas do host e usam Chrome MCP em vez de CDP. -- Perfis `existing-session` podem definir `userDataDir` para apontar para um perfil específico - de navegador baseado em Chromium, como Brave ou Edge. +- Perfis `existing-session` funcionam apenas no host e usam Chrome MCP em vez de CDP. +- Perfis `existing-session` podem definir `userDataDir` para direcionar um perfil + específico de navegador baseado em Chromium, como Brave ou Edge. - Perfis `existing-session` mantêm os limites atuais de rota do Chrome MCP: - ações orientadas por snapshot/ref em vez de alvo por seletor CSS, hooks de upload de arquivo único, - sem substituição de timeout de diálogo, sem `wait --load networkidle`, e sem - `responsebody`, exportação PDF, interceptação de download ou ações em lote. -- Perfis `openclaw` gerenciados localmente atribuem automaticamente `cdpPort` e `cdpUrl`; só + ações guiadas por snapshot/ref em vez de direcionamento por seletor CSS, hooks + de upload de um único arquivo, sem substituições de timeout de diálogo, sem `wait --load networkidle` + e sem `responsebody`, exportação para PDF, interceptação de download ou ações em lote. +- Perfis locais gerenciados `openclaw` atribuem automaticamente `cdpPort` e `cdpUrl`; só defina `cdpUrl` explicitamente para CDP remoto. - Ordem de autodetecção: navegador padrão se for baseado em Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. - Serviço de controle: somente loopback (porta derivada de `gateway.port`, padrão `18791`). @@ -2756,8 +2814,8 @@ Consulte [Plugins](/pt-BR/tools/plugin). } ``` -- `seamColor`: cor de destaque para o chrome da UI do app nativo (matiz da bolha no modo Talk etc.). -- `assistant`: substituição da identidade da Control UI. Usa a identidade do agente ativo como fallback. +- `seamColor`: cor de destaque para o chrome da UI nativa do app (tingimento da bolha do Talk Mode etc.). +- `assistant`: substituição de identidade da Control UI. Usa a identidade do agente ativo como fallback. --- @@ -2824,36 +2882,14 @@ Consulte [Plugins](/pt-BR/tools/plugin). -- `mode`: `local` (executa gateway) ou `remote` (conecta a um gateway remoto). O gateway se recusa a iniciar a menos que seja `local`. +- `mode`: `local` (executa o gateway) ou `remote` (conecta a um gateway remoto). O gateway se recusa a iniciar a menos que esteja em `local`. - `port`: porta multiplexada única para WS + HTTP. Precedência: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. -- `bind`: `auto`, `loopback` (padrão), `lan` (`0.0.0.0`), `tailnet` (somente IP Tailscale) ou `custom`. -- **Aliases legados de bind**: use valores de modo bind em `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), não aliases de host (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). -- **Observação sobre Docker**: o bind padrão `loopback` escuta em `127.0.0.1` dentro do contêiner. Com rede bridge do Docker (`-p 18789:18789`), o tráfego chega em `eth0`, então o gateway fica inacessível. Use `--network host` ou defina `bind: "lan"` (ou `bind: "custom"` com `customBindHost: "0.0.0.0"`) para escutar em todas as interfaces. -- **Auth**: exigida por padrão. Binds que não sejam loopback exigem autenticação do gateway. Na prática, isso significa um token/senha compartilhado ou um proxy reverso com reconhecimento de identidade e `gateway.auth.mode: "trusted-proxy"`. O assistente de onboarding gera um token por padrão. -- Se `gateway.auth.token` e `gateway.auth.password` estiverem ambos configurados (incluindo SecretRefs), defina `gateway.auth.mode` explicitamente como `token` ou `password`. Inicialização e fluxos de instalação/reparo de serviço falham quando ambos estão configurados e o modo está ausente. -- `gateway.auth.mode: "none"`: modo explícito sem autenticação. Use apenas para configurações confiáveis de loopback local; essa opção intencionalmente não é oferecida nos prompts de onboarding. -- `gateway.auth.mode: "trusted-proxy"`: delega autenticação a um proxy reverso com reconhecimento de identidade e confia em headers de identidade vindos de `gateway.trustedProxies` (consulte [Trusted Proxy Auth](/pt-BR/gateway/trusted-proxy-auth)). Esse modo espera uma origem de proxy **não loopback**; proxies reversos loopback no mesmo host não satisfazem autenticação trusted-proxy. -- `gateway.auth.allowTailscale`: quando `true`, headers de identidade do Tailscale Serve podem satisfazer a autenticação da Control UI/WebSocket (verificados via `tailscale whois`). Endpoints da API HTTP **não** usam essa autenticação por header do Tailscale; seguem o modo normal de autenticação HTTP do gateway. Esse fluxo sem token assume que o host do gateway é confiável. O padrão é `true` quando `tailscale.mode = "serve"`. -- `gateway.auth.rateLimit`: limitador opcional para falhas de autenticação. Aplica-se por IP de cliente e por escopo de autenticação (segredo compartilhado e token de dispositivo são rastreados de forma independente). Tentativas bloqueadas retornam `429` + `Retry-After`. - - No caminho assíncrono da Control UI do Tailscale Serve, tentativas falhas para o mesmo `{scope, clientIp}` são serializadas antes da gravação da falha. Portanto, tentativas ruins concorrentes do mesmo cliente podem acionar o limitador na segunda requisição, em vez de ambas passarem como incompatibilidades simples. - - `gateway.auth.rateLimit.exemptLoopback` usa por padrão `true`; defina `false` quando quiser intencionalmente limitar também o tráfego localhost (para ambientes de teste ou implantações estritas com proxy). -- Tentativas de autenticação WS originadas do navegador são sempre limitadas com a isenção de loopback desativada (defesa em profundidade contra brute force de localhost baseado em navegador). -- Em loopback, esses bloqueios para origens do navegador são isolados por valor normalizado de `Origin`, então falhas repetidas de uma origem localhost não bloqueiam automaticamente outra origem diferente. -- `tailscale.mode`: `serve` (somente tailnet, bind loopback) ou `funnel` (público, requer autenticação). -- `controlUi.allowedOrigins`: lista explícita de permissão de origem do navegador para conexões WebSocket ao Gateway. Obrigatória quando clientes de navegador são esperados de origens que não sejam loopback. -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: modo perigoso que ativa fallback de origem por header Host para implantações que dependem intencionalmente da política de origem por header Host. -- `remote.transport`: `ssh` (padrão) ou `direct` (ws/wss). Para `direct`, `remote.url` deve ser `ws://` ou `wss://`. -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: substituição break-glass no lado do cliente que permite `ws://` em texto simples para IPs confiáveis de rede privada; o padrão continua sendo permitir texto simples apenas em loopback. -- `gateway.remote.token` / `.password` são campos de credencial do cliente remoto. Eles não configuram a autenticação do gateway por si só. -- `gateway.push.apns.relay.baseUrl`: URL base HTTPS para o relay APNs externo usado por builds oficiais/TestFlight do iOS depois que publicam registros baseados em relay para o gateway. Essa URL deve corresponder à URL do relay compilada no build iOS. -- `gateway.push.apns.relay.timeoutMs`: timeout de envio do gateway para o relay em milissegundos. Padrão: `10000`. -- Registros baseados em relay são delegados a uma identidade específica do gateway. O app iOS emparelhado busca `gateway.identity.get`, inclui essa identidade no registro do relay e encaminha ao gateway uma permissão de envio no escopo do registro. Outro gateway não pode reutilizar esse registro armazenado. -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: substituições temporárias por ambiente para a configuração de relay acima. -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: escape hatch somente para desenvolvimento para URLs de relay HTTP em loopback. URLs de relay em produção devem permanecer em HTTPS. -- `gateway.channelHealthCheckMinutes`: intervalo do monitor de saúde do canal em minutos. Defina `0` para desativar globalmente reinícios por monitor de saúde. Padrão: `5`. -- `gateway.channelStaleEventThresholdMinutes`: limite em minutos para socket obsoleto. Mantenha isso maior ou igual a `gateway.channelHealthCheckMinutes`. Padrão: `30`. -- `gateway.channelMaxRestartsPerHour`: máximo de reinícios do monitor de saúde por canal/conta em uma hora móvel. Padrão: `10`. -- `channels..healthMonitor.enabled`: desativação por canal para reinícios do monitor de saúde, mantendo o monitor global ativado. -- `channels..accounts..healthMonitor.enabled`: substituição por conta para canais com várias contas. Quando definida, tem precedência sobre a substituição em nível de canal. -- Caminhos locais de chamada ao gateway podem usar `gateway.remote.*` como fallback somente quando `gateway.auth.*` não está definido. -- Se `gateway.auth \ No newline at end of file +- `bind`: `auto`, `loopback` (padrão), `lan` (`0.0.0.0`), `tailnet` (apenas IP Tailscale) ou `custom`. +- **Aliases legados de bind**: use valores de modo de bind em `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), não aliases de host (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). +- **Observação sobre Docker**: o bind padrão `loopback` escuta em `127.0.0.1` dentro do contêiner. Com rede bridge do Docker (`-p 18789:18789`), o tráfego chega em `eth0`, então o gateway fica inacessível. Use `--network host`, ou defina `bind: "lan"` (ou `bind: "custom"` com `customBindHost: "0.0.0.0"`) para escutar em todas as interfaces. +- **Auth**: obrigatória por padrão. Binds não loopback exigem autenticação do gateway. Na prática isso significa um token/senha compartilhados ou um proxy reverso com reconhecimento de identidade usando `gateway.auth.mode: "trusted-proxy"`. O assistente de onboarding gera um token por padrão. +- Se `gateway.auth.token` e `gateway.auth.password` estiverem ambos configurados (incluindo SecretRefs), defina `gateway.auth.mode` explicitamente como `token` ou `password`. Fluxos de inicialização e instalação/reparo de serviço falham quando ambos estão configurados e o modo não está definido. +- `gateway.auth.mode: "none"`: modo explícito sem autenticação. Use apenas para configurações confiáveis locais em loopback; isto intencionalmente não é oferecido pelos prompts de onboarding. +- `gateway.auth.mode: "trusted-proxy"`: delega autenticação a um proxy reverso com reconhecimento de identidade e confia em cabeçalhos de identidade de `gateway.trustedProxies` (consulte [Trusted Proxy Auth](/pt-BR/gateway/trusted-proxy-auth)). Este modo espera uma origem de proxy **não loopback**; proxies reversos loopback no mesmo host não atendem a autenticação por trusted-proxy. +- `gateway.auth.allowTailscale`: quando `true`, cabeçalhos de identidade do Tailscale Serve podem satisfazer a autenticação da Control UI/WebSocket (verificados via `tailscale whois`). Endpoints da API HTTP **não** usam essa autenticação por cabeçalho do Tailscale; eles seguem o modo normal de autenticação HTTP do gateway. Esse fluxo sem token pressupõe que o host do gateway seja confiável. O padrão é `true` quando `tailscale.mode = "serve"`. +- `gateway.auth.rateLimit`: limitador opcional de falhas de autenticação. Aplica-se por IP do cliente e por escopo de autenticação (segredo compartilhado e token de dispositivo são acompanhados independentemente). Tentativas bloqueadas retornam `429` + `Retry-After \ No newline at end of file diff --git a/docs/pt-BR/gateway/configuration.md b/docs/pt-BR/gateway/configuration.md index 5bfde75a9..50f9d11ad 100644 --- a/docs/pt-BR/gateway/configuration.md +++ b/docs/pt-BR/gateway/configuration.md @@ -2,32 +2,32 @@ read_when: - Configurando o OpenClaw pela primeira vez - Procurando padrões comuns de configuração - - Navegando até seções específicas de configuração + - Navegando até seções específicas da configuração summary: 'Visão geral da configuração: tarefas comuns, configuração rápida e links para a referência completa' title: Configuração x-i18n: - generated_at: "2026-04-05T12:42:11Z" + generated_at: "2026-04-08T05:27:48Z" model: gpt-5.4 provider: openai - source_hash: a39a7de09c5f9540785ec67f37d435a7a86201f0f5f640dae663054f35976712 + source_hash: 199a1e515bd4003319e71593a2659bb883299a76ff67e273d92583df03c96604 source_path: gateway/configuration.md workflow: 15 --- # Configuração -O OpenClaw lê uma configuração opcional em **JSON5** de `~/.openclaw/openclaw.json`. +O OpenClaw lê uma configuração opcional em **JSON5** de `~/.openclaw/openclaw.json`. -Se o arquivo não existir, o OpenClaw usará padrões seguros. Motivos comuns para adicionar uma configuração: +Se o arquivo estiver ausente, o OpenClaw usará padrões seguros. Motivos comuns para adicionar uma configuração: -- Conectar canais e controlar quem pode enviar mensagens para o bot +- Conectar canais e controlar quem pode enviar mensagens ao bot - Definir modelos, ferramentas, sandboxing ou automação (cron, hooks) - Ajustar sessões, mídia, rede ou UI -Veja a [referência completa](/gateway/configuration-reference) para todos os campos disponíveis. +Consulte a [referência completa](/pt-BR/gateway/configuration-reference) para ver todos os campos disponíveis. -**Novo em configuração?** Comece com `openclaw onboard` para configuração interativa ou veja o guia [Exemplos de configuração](/gateway/configuration-examples) para configurações completas prontas para copiar e colar. +**Novo em configuração?** Comece com `openclaw onboard` para uma configuração interativa, ou confira o guia [Exemplos de configuração](/pt-BR/gateway/configuration-examples) para ver configurações completas de copiar e colar. ## Configuração mínima @@ -49,7 +49,7 @@ Veja a [referência completa](/gateway/configuration-reference) para todos os ca openclaw configure # assistente de configuração ``` - + ```bash openclaw config get agents.defaults.workspace openclaw config set agents.defaults.heartbeat.every "2h" @@ -58,31 +58,33 @@ Veja a [referência completa](/gateway/configuration-reference) para todos os ca Abra [http://127.0.0.1:18789](http://127.0.0.1:18789) e use a aba **Config**. - A UI de controle renderiza um formulário a partir do schema de configuração ativo, incluindo metadados de documentação `title` / `description` dos campos, além de schemas de plugins e canais quando disponíveis, com um editor **Raw JSON** como rota de escape. Para UIs de navegação detalhada e outras ferramentas, o gateway também expõe `config.schema.lookup` para buscar um único nó do schema com escopo de caminho, além de resumos imediatos dos filhos. + A UI de controle renderiza um formulário a partir do esquema de configuração ativo, incluindo metadados de documentação de campos `title` / `description`, além de esquemas de plugins e canais quando disponíveis, com um editor de **Raw JSON** como saída de emergência. Para UIs de navegação detalhada e outras ferramentas, o gateway também expõe `config.schema.lookup` para buscar um nó de esquema com escopo em um caminho mais resumos imediatos dos nós filhos. - Edite `~/.openclaw/openclaw.json` diretamente. O Gateway observa o arquivo e aplica as alterações automaticamente (veja [hot reload](#config-hot-reload)). + Edite `~/.openclaw/openclaw.json` diretamente. O Gateway monitora o arquivo e aplica as alterações automaticamente (consulte [hot reload](#config-hot-reload)). -## Validação estrita +## Validação rigorosa -O OpenClaw aceita apenas configurações que correspondem totalmente ao schema. Chaves desconhecidas, tipos malformados ou valores inválidos fazem o Gateway **se recusar a iniciar**. A única exceção no nível raiz é `$schema` (string), para que editores possam anexar metadados de JSON Schema. +O OpenClaw aceita apenas configurações que correspondam totalmente ao esquema. Chaves desconhecidas, tipos malformados ou valores inválidos fazem com que o Gateway **se recuse a iniciar**. A única exceção no nível raiz é `$schema` (string), para que editores possam anexar metadados de JSON Schema. -Observações sobre ferramentas de schema: +Observações sobre as ferramentas de esquema: -- `openclaw config schema` imprime a mesma família de JSON Schema usada pela UI de controle e pela validação de configuração. -- Os valores `title` e `description` dos campos são levados para a saída do schema para ferramentas de editor e formulário. -- Entradas de objeto aninhado, curinga (`*`) e item de array (`[]`) herdam os mesmos metadados de documentação quando há documentação de campo correspondente. +- `openclaw config schema` imprime a mesma família de JSON Schema usada pela UI de controle e pela validação da configuração. +- Trate essa saída de esquema como o contrato canônico legível por máquina para `openclaw.json`; esta visão geral e a referência de configuração a resumem. +- Os valores de `title` e `description` dos campos são carregados para a saída do esquema para ferramentas de editor e formulário. +- Entradas de objeto aninhado, curinga (`*`) e item de array (`[]`) herdam os mesmos metadados de documentação quando existe documentação de campo correspondente. - Ramos de composição `anyOf` / `oneOf` / `allOf` também herdam os mesmos metadados de documentação, para que variantes de união/interseção mantenham a mesma ajuda de campo. -- `config.schema.lookup` retorna um caminho de configuração normalizado com um nó de schema superficial (`title`, `description`, `type`, `enum`, `const`, limites comuns e campos de validação semelhantes), metadados de dica de UI correspondentes e resumos imediatos dos filhos para ferramentas de navegação detalhada. -- Schemas de plugin/canal em runtime são mesclados quando o gateway consegue carregar o registro atual de manifests. +- `config.schema.lookup` retorna um caminho de configuração normalizado com um nó de esquema superficial (`title`, `description`, `type`, `enum`, `const`, limites comuns e campos de validação semelhantes), metadados de dica de UI correspondentes e resumos imediatos dos nós filhos para ferramentas de navegação detalhada. +- Esquemas de plugin/canal em tempo de execução são mesclados quando o gateway consegue carregar o registro de manifestos atual. +- `pnpm config:docs:check` detecta divergência entre artefatos de baseline de configuração voltados à documentação e a superfície atual do esquema. Quando a validação falha: -- O Gateway não inicia +- O Gateway não inicializa - Apenas comandos de diagnóstico funcionam (`openclaw doctor`, `openclaw logs`, `openclaw health`, `openclaw status`) - Execute `openclaw doctor` para ver os problemas exatos - Execute `openclaw doctor --fix` (ou `--yes`) para aplicar correções @@ -91,18 +93,18 @@ Quando a validação falha: - Cada canal tem sua própria seção de configuração em `channels.`. Veja a página dedicada do canal para as etapas de configuração: + Cada canal tem sua própria seção de configuração em `channels.`. Consulte a página dedicada do canal para ver as etapas de configuração: - - [WhatsApp](/channels/whatsapp) — `channels.whatsapp` - - [Telegram](/channels/telegram) — `channels.telegram` - - [Discord](/channels/discord) — `channels.discord` - - [Feishu](/channels/feishu) — `channels.feishu` - - [Google Chat](/channels/googlechat) — `channels.googlechat` - - [Microsoft Teams](/channels/msteams) — `channels.msteams` - - [Slack](/channels/slack) — `channels.slack` - - [Signal](/channels/signal) — `channels.signal` - - [iMessage](/channels/imessage) — `channels.imessage` - - [Mattermost](/channels/mattermost) — `channels.mattermost` + - [WhatsApp](/pt-BR/channels/whatsapp) — `channels.whatsapp` + - [Telegram](/pt-BR/channels/telegram) — `channels.telegram` + - [Discord](/pt-BR/channels/discord) — `channels.discord` + - [Feishu](/pt-BR/channels/feishu) — `channels.feishu` + - [Google Chat](/pt-BR/channels/googlechat) — `channels.googlechat` + - [Microsoft Teams](/pt-BR/channels/msteams) — `channels.msteams` + - [Slack](/pt-BR/channels/slack) — `channels.slack` + - [Signal](/pt-BR/channels/signal) — `channels.signal` + - [iMessage](/pt-BR/channels/imessage) — `channels.imessage` + - [Mattermost](/pt-BR/channels/mattermost) — `channels.mattermost` Todos os canais compartilham o mesmo padrão de política de DM: @@ -122,7 +124,7 @@ Quando a validação falha: - Defina o modelo primário e fallbacks opcionais: + Defina o modelo principal e os fallbacks opcionais: ```json5 { @@ -141,30 +143,30 @@ Quando a validação falha: } ``` - - `agents.defaults.models` define o catálogo de modelos e funciona como allowlist para `/model`. - - Refs de modelo usam o formato `provider/model` (por exemplo `anthropic/claude-opus-4-6`). - - `agents.defaults.imageMaxDimensionPx` controla o redimensionamento de imagem para transcrição/ferramenta (padrão `1200`); valores menores geralmente reduzem o uso de tokens de visão em execuções com muitas capturas de tela. - - Veja [CLI de modelos](/concepts/models) para trocar modelos no chat e [Failover de modelo](/concepts/model-failover) para rotação de autenticação e comportamento de fallback. - - Para provedores personalizados/self-hosted, veja [Provedores personalizados](/gateway/configuration-reference#custom-providers-and-base-urls) na referência. + - `agents.defaults.models` define o catálogo de modelos e atua como allowlist para `/model`. + - As referências de modelo usam o formato `provider/model` (por exemplo, `anthropic/claude-opus-4-6`). + - `agents.defaults.imageMaxDimensionPx` controla o redimensionamento de imagens em transcrições/ferramentas (padrão `1200`); valores menores normalmente reduzem o uso de tokens de visão em execuções com muitas capturas de tela. + - Consulte [Models CLI](/pt-BR/concepts/models) para trocar de modelos no chat e [Model Failover](/pt-BR/concepts/model-failover) para rotação de autenticação e comportamento de fallback. + - Para provedores personalizados/autohospedados, consulte [provedores personalizados](/pt-BR/gateway/configuration-reference#custom-providers-and-base-urls) na referência. - + O acesso por DM é controlado por canal via `dmPolicy`: - - `"pairing"` (padrão): remetentes desconhecidos recebem um código de pareamento único para aprovação - - `"allowlist"`: apenas remetentes em `allowFrom` (ou no armazenamento de allowlist pareado) + - `"pairing"` (padrão): remetentes desconhecidos recebem um código de emparelhamento de uso único para aprovação + - `"allowlist"`: apenas remetentes em `allowFrom` (ou no armazenamento de permissões emparelhadas) - `"open"`: permite todas as DMs recebidas (requer `allowFrom: ["*"]`) - `"disabled"`: ignora todas as DMs Para grupos, use `groupPolicy` + `groupAllowFrom` ou allowlists específicas do canal. - Veja a [referência completa](/gateway/configuration-reference#dm-and-group-access) para detalhes por canal. + Consulte a [referência completa](/pt-BR/gateway/configuration-reference#dm-and-group-access) para detalhes por canal. - - Mensagens de grupo, por padrão, **exigem menção**. Configure padrões por agente: + + As mensagens de grupo, por padrão, **exigem menção**. Configure padrões por agente: ```json5 { @@ -186,9 +188,9 @@ Quando a validação falha: } ``` - - **Menções por metadados**: @menções nativas (toque para mencionar no WhatsApp, @bot no Telegram etc.) + - **Menções de metadados**: menções @ nativas (WhatsApp tocar para mencionar, Telegram @bot etc.) - **Padrões de texto**: padrões regex seguros em `mentionPatterns` - - Veja a [referência completa](/gateway/configuration-reference#group-chat-mention-gating) para substituições por canal e modo de self-chat. + - Consulte a [referência completa](/pt-BR/gateway/configuration-reference#group-chat-mention-gating) para substituições por canal e modo self-chat. @@ -202,9 +204,9 @@ Quando a validação falha: skills: ["github", "weather"], }, list: [ - { id: "writer" }, // herda github, weather - { id: "docs", skills: ["docs-search"] }, // substitui os padrões - { id: "locked-down", skills: [] }, // sem Skills + { id: "writer" }, // inherits github, weather + { id: "docs", skills: ["docs-search"] }, // replaces defaults + { id: "locked-down", skills: [] }, // no skills ], }, } @@ -212,13 +214,13 @@ Quando a validação falha: - Omita `agents.defaults.skills` para Skills irrestritas por padrão. - Omita `agents.list[].skills` para herdar os padrões. - - Defina `agents.list[].skills: []` para nenhuma Skill. - - Veja [Skills](/tools/skills), [Configuração de Skills](/tools/skills-config) e a [Referência de configuração](/gateway/configuration-reference#agentsdefaultsskills). + - Defina `agents.list[].skills: []` para não ter Skills. + - Consulte [Skills](/pt-BR/tools/skills), [configuração de Skills](/pt-BR/tools/skills-config) e a [Referência de configuração](/pt-BR/gateway/configuration-reference#agentsdefaultsskills). - Controle quão agressivamente o gateway reinicia canais que parecem obsoletos: + Controle com que agressividade o gateway reinicia canais que parecem obsoletos: ```json5 { @@ -240,20 +242,20 @@ Quando a validação falha: } ``` - - Defina `gateway.channelHealthCheckMinutes: 0` para desativar globalmente reinicializações do monitor de integridade. + - Defina `gateway.channelHealthCheckMinutes: 0` para desabilitar globalmente reinicializações do monitor de integridade. - `channelStaleEventThresholdMinutes` deve ser maior ou igual ao intervalo de verificação. - - Use `channels..healthMonitor.enabled` ou `channels..accounts..healthMonitor.enabled` para desativar reinicializações automáticas de um canal ou conta sem desativar o monitor global. - - Veja [Verificações de integridade](/gateway/health) para depuração operacional e a [referência completa](/gateway/configuration-reference#gateway) para todos os campos. + - Use `channels..healthMonitor.enabled` ou `channels..accounts..healthMonitor.enabled` para desabilitar reinicializações automáticas de um canal ou conta sem desabilitar o monitor global. + - Consulte [Health Checks](/pt-BR/gateway/health) para depuração operacional e a [referência completa](/pt-BR/gateway/configuration-reference#gateway) para todos os campos. - Sessões controlam continuidade e isolamento de conversa: + As sessões controlam continuidade e isolamento da conversa: ```json5 { session: { - dmScope: "per-channel-peer", // recomendado para múltiplos usuários + dmScope: "per-channel-peer", // recommended for multi-user threadBindings: { enabled: true, idleHours: 24, @@ -269,14 +271,14 @@ Quando a validação falha: ``` - `dmScope`: `main` (compartilhado) | `per-peer` | `per-channel-peer` | `per-account-channel-peer` - - `threadBindings`: padrões globais para roteamento de sessão vinculado a thread (o Discord oferece suporte a `/focus`, `/unfocus`, `/agents`, `/session idle` e `/session max-age`). - - Veja [Gerenciamento de sessão](/concepts/session) para escopo, links de identidade e política de envio. - - Veja a [referência completa](/gateway/configuration-reference#session) para todos os campos. + - `threadBindings`: padrões globais para roteamento de sessão vinculado a thread (Discord oferece suporte a `/focus`, `/unfocus`, `/agents`, `/session idle` e `/session max-age`). + - Consulte [Gerenciamento de sessões](/pt-BR/concepts/session) para escopo, links de identidade e política de envio. + - Consulte a [referência completa](/pt-BR/gateway/configuration-reference#session) para todos os campos. - Execute sessões de agente em contêineres Docker isolados: + Execute sessões de agentes em contêineres Docker isolados: ```json5 { @@ -293,7 +295,7 @@ Quando a validação falha: Crie a imagem primeiro: `scripts/sandbox-setup.sh` - Veja [Sandboxing](/gateway/sandboxing) para o guia completo e a [referência completa](/gateway/configuration-reference#agentsdefaultssandbox) para todas as opções. + Consulte [Sandboxing](/pt-BR/gateway/sandboxing) para o guia completo e a [referência completa](/pt-BR/gateway/configuration-reference#agentsdefaultssandbox) para todas as opções. @@ -309,7 +311,7 @@ Quando a validação falha: apns: { relay: { baseUrl: "https://relay.example.com", - // Opcional. Padrão: 10000 + // Optional. Default: 10000 timeoutMs: 10000, }, }, @@ -326,31 +328,31 @@ Quando a validação falha: O que isso faz: - - Permite que o gateway envie `push.test`, wake nudges e reconnect wakes por meio do relay externo. - - Usa uma concessão de envio com escopo de registro encaminhada pelo app iOS pareado. O gateway não precisa de um token de relay para toda a implantação. - - Vincula cada registro com relay à identidade do gateway com a qual o app iOS foi pareado, para que outro gateway não possa reutilizar o registro armazenado. - - Mantém builds locais/manuais do iOS em APNs direto. Envios com relay se aplicam apenas a builds oficiais distribuídas que se registraram pelo relay. - - Deve corresponder ao base URL do relay embutido na build oficial/TestFlight do iOS, para que o tráfego de registro e envio chegue à mesma implantação do relay. + - Permite que o gateway envie `push.test`, alertas de ativação e ativações de reconexão por meio do relay externo. + - Usa uma permissão de envio com escopo de registro encaminhada pelo app iOS emparelhado. O gateway não precisa de um token de relay de toda a implantação. + - Vincula cada registro com relay à identidade do gateway com a qual o app iOS foi emparelhado, para que outro gateway não possa reutilizar o registro armazenado. + - Mantém builds locais/manuais do iOS em APNs direto. Envios com relay se aplicam apenas a builds oficiais distribuídos que se registraram pelo relay. + - Deve corresponder ao URL base do relay incorporado ao build oficial/TestFlight do iOS, para que o tráfego de registro e envio chegue à mesma implantação de relay. - Fluxo completo: + Fluxo ponta a ponta: - 1. Instale uma build oficial/TestFlight do iOS compilada com o mesmo base URL do relay. + 1. Instale um build oficial/TestFlight do iOS compilado com o mesmo URL base do relay. 2. Configure `gateway.push.apns.relay.baseUrl` no gateway. - 3. Faça o pareamento do app iOS com o gateway e deixe tanto as sessões de nó quanto as de operador se conectarem. - 4. O app iOS busca a identidade do gateway, registra-se no relay usando App Attest mais o recibo do app e, em seguida, publica o payload `push.apns.register` com relay no gateway pareado. - 5. O gateway armazena o identificador do relay e a concessão de envio, depois os usa para `push.test`, wake nudges e reconnect wakes. + 3. Emparelhe o app iOS com o gateway e permita que as sessões de nó e operador se conectem. + 4. O app iOS busca a identidade do gateway, registra-se no relay usando App Attest junto com o recibo do app e então publica a carga `push.apns.register` com relay no gateway emparelhado. + 5. O gateway armazena o identificador do relay e a permissão de envio, depois os usa para `push.test`, alertas de ativação e ativações de reconexão. Observações operacionais: - - Se você trocar o app iOS para outro gateway, reconecte o app para que ele possa publicar um novo registro de relay vinculado a esse gateway. - - Se você distribuir uma nova build do iOS apontando para outra implantação de relay, o app atualiza seu registro de relay em cache em vez de reutilizar a origem antiga do relay. + - Se você mudar o app iOS para outro gateway, reconecte o app para que ele possa publicar um novo registro de relay vinculado àquele gateway. + - Se você distribuir um novo build do iOS apontando para outra implantação de relay, o app atualiza seu registro de relay em cache em vez de reutilizar a origem antiga do relay. Observação de compatibilidade: - - `OPENCLAW_APNS_RELAY_BASE_URL` e `OPENCLAW_APNS_RELAY_TIMEOUT_MS` ainda funcionam como substituições temporárias por ambiente. - - `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` continua sendo uma rota de escape de desenvolvimento somente para loopback; não persista URLs HTTP de relay na configuração. + - `OPENCLAW_APNS_RELAY_BASE_URL` e `OPENCLAW_APNS_RELAY_TIMEOUT_MS` ainda funcionam como substituições temporárias via variáveis de ambiente. + - `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` continua sendo uma válvula de escape apenas para desenvolvimento em loopback; não persista URLs HTTP de relay na configuração. - Veja [App iOS](/platforms/ios#relay-backed-push-for-official-builds) para o fluxo completo e [Fluxo de autenticação e confiança](/platforms/ios#authentication-and-trust-flow) para o modelo de segurança do relay. + Consulte [App iOS](/pt-BR/platforms/ios#relay-backed-push-for-official-builds) para o fluxo ponta a ponta e [Fluxo de autenticação e confiança](/pt-BR/platforms/ios#authentication-and-trust-flow) para o modelo de segurança do relay. @@ -368,14 +370,14 @@ Quando a validação falha: } ``` - - `every`: string de duração (`30m`, `2h`). Defina `0m` para desativar. + - `every`: string de duração (`30m`, `2h`). Defina `0m` para desabilitar. - `target`: `last` | `none` | `` (por exemplo `discord`, `matrix`, `telegram` ou `whatsapp`) - - `directPolicy`: `allow` (padrão) ou `block` para alvos de heartbeat em estilo DM - - Veja [Heartbeat](/gateway/heartbeat) para o guia completo. + - `directPolicy`: `allow` (padrão) ou `block` para destinos de heartbeat no estilo DM + - Consulte [Heartbeat](/pt-BR/gateway/heartbeat) para o guia completo. - + ```json5 { cron: { @@ -390,9 +392,9 @@ Quando a validação falha: } ``` - - `sessionRetention`: remove sessões concluídas de execuções isoladas de `sessions.json` (padrão `24h`; defina `false` para desativar). - - `runLog`: faz pruning de `cron/runs/.jsonl` por tamanho e linhas retidas. - - Veja [Jobs cron](/automation/cron-jobs) para visão geral do recurso e exemplos de CLI. + - `sessionRetention`: remove sessões isoladas de execução concluídas de `sessions.json` (padrão `24h`; defina `false` para desabilitar). + - `runLog`: remove conteúdo de `cron/runs/.jsonl` por tamanho e número de linhas retidas. + - Consulte [Tarefas cron](/pt-BR/automation/cron-jobs) para uma visão geral do recurso e exemplos de CLI. @@ -423,18 +425,18 @@ Quando a validação falha: Observação de segurança: - Trate todo conteúdo de payload de hook/webhook como entrada não confiável. - Use um `hooks.token` dedicado; não reutilize o token compartilhado do Gateway. - - A autenticação de hook é somente por cabeçalho (`Authorization: Bearer ...` ou `x-openclaw-token`); tokens em query string são rejeitados. + - A autenticação de hook é apenas por cabeçalho (`Authorization: Bearer ...` ou `x-openclaw-token`); tokens em query string são rejeitados. - `hooks.path` não pode ser `/`; mantenha a entrada de webhook em um subcaminho dedicado, como `/hooks`. - - Mantenha desativadas flags de bypass de conteúdo inseguro (`hooks.gmail.allowUnsafeExternalContent`, `hooks.mappings[].allowUnsafeExternalContent`), a menos que esteja fazendo depuração bem delimitada. + - Mantenha desabilitadas as flags de bypass de conteúdo inseguro (`hooks.gmail.allowUnsafeExternalContent`, `hooks.mappings[].allowUnsafeExternalContent`), a menos que esteja fazendo depuração bem delimitada. - Se você ativar `hooks.allowRequestSessionKey`, também defina `hooks.allowedSessionKeyPrefixes` para limitar chaves de sessão escolhidas pelo chamador. - - Para agentes acionados por hooks, prefira camadas fortes e modernas de modelo e política estrita de ferramentas (por exemplo, apenas mensagens mais sandboxing sempre que possível). + - Para agentes acionados por hook, prefira camadas de modelo modernas e fortes e uma política rígida de ferramentas (por exemplo, apenas mensagens mais sandboxing quando possível). - Veja a [referência completa](/gateway/configuration-reference#hooks) para todas as opções de mapeamento e integração com Gmail. + Consulte a [referência completa](/pt-BR/gateway/configuration-reference#hooks) para todas as opções de mapeamento e integração com Gmail. - Execute múltiplos agentes isolados com workspaces e sessões separados: + Execute vários agentes isolados com workspaces e sessões separadas: ```json5 { @@ -451,7 +453,7 @@ Quando a validação falha: } ``` - Veja [Multi-Agent](/concepts/multi-agent) e a [referência completa](/gateway/configuration-reference#multi-agent-routing) para regras de binding e perfis de acesso por agente. + Consulte [Multi-Agent](/pt-BR/concepts/multi-agent) e a [referência completa](/pt-BR/gateway/configuration-reference#multi-agent-routing) para regras de binding e perfis de acesso por agente. @@ -469,28 +471,28 @@ Quando a validação falha: } ``` - - **Arquivo único**: substitui o objeto que o contém - - **Array de arquivos**: mesclado profundamente em ordem (o posterior prevalece) + - **Arquivo único**: substitui o objeto contido + - **Array de arquivos**: mesclagem profunda em ordem (o último prevalece) - **Chaves irmãs**: mescladas após os includes (substituem valores incluídos) - - **Includes aninhados**: compatíveis até 10 níveis de profundidade + - **Includes aninhados**: compatível com até 10 níveis de profundidade - **Caminhos relativos**: resolvidos em relação ao arquivo que inclui - **Tratamento de erros**: erros claros para arquivos ausentes, erros de parse e includes circulares -## Config hot reload +## Hot reload da configuração -O Gateway observa `~/.openclaw/openclaw.json` e aplica alterações automaticamente — não é necessário reinício manual para a maioria das configurações. +O Gateway monitora `~/.openclaw/openclaw.json` e aplica as alterações automaticamente — não é necessário reiniciar manualmente para a maioria das configurações. ### Modos de recarga -| Modo | Comportamento | -| --------------------- | -------------------------------------------------------------------------------------- | -| **`hybrid`** (padrão) | Aplica alterações seguras a quente imediatamente. Reinicia automaticamente para as críticas. | -| **`hot`** | Aplica somente alterações seguras a quente. Registra um aviso quando é necessário reiniciar — você cuida disso. | -| **`restart`** | Reinicia o Gateway em qualquer alteração de configuração, segura ou não. | -| **`off`** | Desativa a observação de arquivos. Alterações entram em vigor no próximo reinício manual. | +| Modo | Comportamento | +| ---------------------- | ------------------------------------------------------------------------------------- | +| **`hybrid`** (padrão) | Aplica a quente alterações seguras instantaneamente. Reinicia automaticamente para alterações críticas. | +| **`hot`** | Aplica a quente apenas alterações seguras. Registra um aviso quando é necessário reiniciar — você cuida disso. | +| **`restart`** | Reinicia o Gateway em qualquer alteração de configuração, segura ou não. | +| **`off`** | Desabilita o monitoramento do arquivo. As alterações entram em vigor na próxima reinicialização manual. | ```json5 { @@ -500,37 +502,37 @@ O Gateway observa `~/.openclaw/openclaw.json` e aplica alterações automaticame } ``` -### O que é aplicado a quente vs o que precisa de reinício +### O que é aplicado a quente vs o que exige reinicialização -A maioria dos campos é aplicada a quente sem indisponibilidade. No modo `hybrid`, alterações que exigem reinício são tratadas automaticamente. +A maioria dos campos é aplicada a quente sem indisponibilidade. No modo `hybrid`, alterações que exigem reinicialização são tratadas automaticamente. -| Categoria | Campos | Precisa reiniciar? | -| --------------------- | -------------------------------------------------------------------- | ------------------ | -| Canais | `channels.*`, `web` (WhatsApp) — todos os canais integrados e de extensão | Não | -| Agente e modelos | `agent`, `agents`, `models`, `routing` | Não | -| Automação | `hooks`, `cron`, `agent.heartbeat` | Não | -| Sessões e mensagens | `session`, `messages` | Não | -| Ferramentas e mídia | `tools`, `browser`, `skills`, `audio`, `talk` | Não | -| UI e diversos | `ui`, `logging`, `identity`, `bindings` | Não | -| Servidor do gateway | `gateway.*` (porta, bind, auth, tailscale, TLS, HTTP) | **Sim** | -| Infraestrutura | `discovery`, `canvasHost`, `plugins` | **Sim** | +| Categoria | Campos | Reinicialização necessária? | +| ------------------- | -------------------------------------------------------------------- | --------------------------- | +| Canais | `channels.*`, `web` (WhatsApp) — todos os canais integrados e de extensão | Não | +| Agente e modelos | `agent`, `agents`, `models`, `routing` | Não | +| Automação | `hooks`, `cron`, `agent.heartbeat` | Não | +| Sessões e mensagens | `session`, `messages` | Não | +| Ferramentas e mídia | `tools`, `browser`, `skills`, `audio`, `talk` | Não | +| UI e diversos | `ui`, `logging`, `identity`, `bindings` | Não | +| Servidor do gateway | `gateway.*` (port, bind, auth, tailscale, TLS, HTTP) | **Sim** | +| Infraestrutura | `discovery`, `canvasHost`, `plugins` | **Sim** | -`gateway.reload` e `gateway.remote` são exceções — alterá-los **não** dispara um reinício. +`gateway.reload` e `gateway.remote` são exceções — alterá-los **não** aciona uma reinicialização. ## RPC de configuração (atualizações programáticas) -RPCs de gravação do plano de controle (`config.apply`, `config.patch`, `update.run`) têm limite de taxa de **3 solicitações a cada 60 segundos** por `deviceId+clientIp`. Quando limitado, o RPC retorna `UNAVAILABLE` com `retryAfterMs`. +RPCs de escrita do plano de controle (`config.apply`, `config.patch`, `update.run`) têm limite de taxa de **3 solicitações por 60 segundos** por `deviceId+clientIp`. Quando o limite é atingido, o RPC retorna `UNAVAILABLE` com `retryAfterMs`. Fluxo seguro/padrão: -- `config.schema.lookup`: inspeciona uma subárvore de configuração com escopo de caminho com um nó de schema superficial, metadados de dica correspondentes e resumos imediatos dos filhos +- `config.schema.lookup`: inspeciona uma subárvore de configuração com escopo em um caminho com um nó de esquema superficial, metadados de dica correspondentes e resumos imediatos dos nós filhos - `config.get`: busca o snapshot atual + hash - `config.patch`: caminho preferido para atualização parcial -- `config.apply`: substituição completa da configuração apenas +- `config.apply`: substituição da configuração completa apenas - `update.run`: autoatualização + reinicialização explícitas Quando você não estiver substituindo a configuração inteira, prefira `config.schema.lookup` e depois `config.patch`. @@ -540,21 +542,21 @@ Quando você não estiver substituindo a configuração inteira, prefira `config Valida + grava a configuração completa e reinicia o Gateway em uma única etapa. - `config.apply` substitui a **configuração inteira**. Use `config.patch` para atualizações parciais ou `openclaw config set` para chaves únicas. + `config.apply` substitui a **configuração inteira**. Use `config.patch` para atualizações parciais, ou `openclaw config set` para chaves individuais. Parâmetros: - - `raw` (string) — payload JSON5 para a configuração inteira + - `raw` (string) — payload JSON5 da configuração inteira - `baseHash` (opcional) — hash da configuração de `config.get` (obrigatório quando a configuração existe) - - `sessionKey` (opcional) — chave de sessão para o ping de wake-up após o reinício - - `note` (opcional) — observação para o sentinel de reinício - - `restartDelayMs` (opcional) — atraso antes do reinício (padrão 2000) + - `sessionKey` (opcional) — chave de sessão para o ping de reativação após a reinicialização + - `note` (opcional) — observação para o sentinela de reinicialização + - `restartDelayMs` (opcional) — atraso antes da reinicialização (padrão 2000) - Solicitações de reinício são consolidadas enquanto uma já estiver pendente/em andamento, e um cooldown de 30 segundos é aplicado entre ciclos de reinício. + Solicitações de reinicialização são consolidadas quando já existe uma pendente/em andamento, e um cooldown de 30 segundos é aplicado entre ciclos de reinicialização. ```bash - openclaw gateway call config.get --params '{}' # capture payload.hash + openclaw gateway call config.get --params '{}' # capturar payload.hash openclaw gateway call config.apply --params '{ "raw": "{ agents: { defaults: { workspace: \"~/.openclaw/workspace\" } } }", "baseHash": "", @@ -565,19 +567,19 @@ Quando você não estiver substituindo a configuração inteira, prefira `config - Mescla uma atualização parcial na configuração existente (semântica de JSON merge patch): + Mescla uma atualização parcial à configuração existente (semântica de JSON merge patch): - Objetos são mesclados recursivamente - `null` exclui uma chave - - Arrays são substituídos + - Arrays substituem Parâmetros: - - `raw` (string) — JSON5 somente com as chaves a alterar + - `raw` (string) — JSON5 apenas com as chaves a alterar - `baseHash` (obrigatório) — hash da configuração de `config.get` - `sessionKey`, `note`, `restartDelayMs` — iguais a `config.apply` - O comportamento de reinício corresponde ao de `config.apply`: reinícios pendentes consolidados mais cooldown de 30 segundos entre ciclos de reinício. + O comportamento de reinicialização corresponde a `config.apply`: reinicializações pendentes consolidadas mais um cooldown de 30 segundos entre ciclos de reinicialização. ```bash openclaw gateway call config.patch --params '{ @@ -591,12 +593,12 @@ Quando você não estiver substituindo a configuração inteira, prefira `config ## Variáveis de ambiente -O OpenClaw lê variáveis de ambiente do processo pai, além de: +O OpenClaw lê variáveis de ambiente do processo pai mais: -- `.env` do diretório de trabalho atual (se existir) +- `.env` do diretório de trabalho atual (se presente) - `~/.openclaw/.env` (fallback global) -Nenhum desses arquivos substitui variáveis de ambiente existentes. Você também pode definir variáveis inline na configuração: +Nenhum dos arquivos substitui variáveis de ambiente já existentes. Você também pode definir variáveis de ambiente inline na configuração: ```json5 { @@ -608,7 +610,7 @@ Nenhum desses arquivos substitui variáveis de ambiente existentes. Você també ``` - Se ativado e as chaves esperadas não estiverem definidas, o OpenClaw executa seu shell de login e importa apenas as chaves ausentes: + Se ativado e as chaves esperadas não estiverem definidas, o OpenClaw executará seu shell de login e importará apenas as chaves ausentes: ```json5 { @@ -622,7 +624,7 @@ Equivalente em variável de ambiente: `OPENCLAW_LOAD_SHELL_ENV=1` - Referencie variáveis de ambiente em qualquer valor string da configuração com `${VAR_NAME}`: + Faça referência a variáveis de ambiente em qualquer valor de string da configuração com `${VAR_NAME}`: ```json5 { @@ -633,7 +635,7 @@ Equivalente em variável de ambiente: `OPENCLAW_LOAD_SHELL_ENV=1` Regras: -- Apenas nomes em maiúsculas correspondem: `[A-Z_][A-Z0-9_]*` +- Apenas nomes em maiúsculas são correspondidos: `[A-Z_][A-Z0-9_]*` - Variáveis ausentes/vazias geram erro no momento do carregamento - Escape com `$${VAR}` para saída literal - Funciona dentro de arquivos `$include` @@ -641,7 +643,7 @@ Regras: - + Para campos que oferecem suporte a objetos SecretRef, você pode usar: ```json5 @@ -674,16 +676,16 @@ Regras: } ``` -Detalhes de SecretRef (incluindo `secrets.providers` para `env`/`file`/`exec`) estão em [Gerenciamento de segredos](/gateway/secrets). -Caminhos de credenciais compatíveis estão listados em [Superfície de credenciais SecretRef](/reference/secretref-credential-surface). +Os detalhes de SecretRef (incluindo `secrets.providers` para `env`/`file`/`exec`) estão em [Gerenciamento de segredos](/pt-BR/gateway/secrets). +Os caminhos de credenciais com suporte estão listados em [Superfície de credenciais SecretRef](/pt-BR/reference/secretref-credential-surface). -Veja [Environment](/help/environment) para precedência e fontes completas. +Consulte [Ambiente](/pt-BR/help/environment) para ver precedência e fontes completas. ## Referência completa -Para a referência completa campo por campo, veja **[Referência de configuração](/gateway/configuration-reference)**. +Para a referência completa campo por campo, consulte **[Referência de configuração](/pt-BR/gateway/configuration-reference)**. --- -_Relacionado: [Exemplos de configuração](/gateway/configuration-examples) · [Referência de configuração](/gateway/configuration-reference) · [Doctor](/gateway/doctor)_ +_Relacionado: [Exemplos de configuração](/pt-BR/gateway/configuration-examples) · [Referência de configuração](/pt-BR/gateway/configuration-reference) · [Doctor](/pt-BR/gateway/doctor)_ diff --git a/docs/pt-BR/plugins/memory-wiki.md b/docs/pt-BR/plugins/memory-wiki.md new file mode 100644 index 000000000..0b08960ba --- /dev/null +++ b/docs/pt-BR/plugins/memory-wiki.md @@ -0,0 +1,368 @@ +--- +read_when: + - Você quer conhecimento persistente além de simples notas MEMORY.md + - Você está configurando o plugin empacotado memory-wiki + - Você quer entender wiki_search, wiki_get ou o modo bridge +summary: 'memory-wiki: cofre de conhecimento compilado com procedência, afirmações, painéis e modo bridge' +title: Wiki de Memória +x-i18n: + generated_at: "2026-04-08T05:26:51Z" + model: gpt-5.4 + provider: openai + source_hash: b78dd6a4ef4451dae6b53197bf0c7c2a2ba846b08e4a3a93c1026366b1598d82 + source_path: plugins/memory-wiki.md + workflow: 15 +--- + +# Wiki de Memória + +`memory-wiki` é um plugin empacotado que transforma memória durável em um +cofre de conhecimento compilado. + +Ele **não** substitui o plugin de memória ativo. O plugin de memória ativo ainda +é responsável por recuperação, promoção, indexação e dreaming. O `memory-wiki` +fica ao lado dele e compila conhecimento durável em uma wiki navegável com +páginas determinísticas, afirmações estruturadas, procedência, painéis e +resumos legíveis por máquina. + +Use-o quando você quiser que a memória se comporte mais como uma camada de +conhecimento mantida e menos como uma pilha de arquivos Markdown. + +## O que ele adiciona + +- Um cofre de wiki dedicado com layout de página determinístico +- Metadados estruturados de afirmações e evidências, não apenas prosa +- Procedência, confiança, contradições e perguntas em aberto no nível da página +- Resumos compilados para consumidores de agente/runtime +- Ferramentas nativas da wiki para search/get/apply/lint +- Modo bridge opcional que importa artefatos públicos do plugin de memória ativo +- Modo de renderização opcional compatível com Obsidian e integração com a CLI + +## Como ele se encaixa com a memória + +Pense na divisão assim: + +| Camada | Responsável por | +| ------------------------------------------------------- | ------------------------------------------------------------------------------------------ | +| Plugin de memória ativo (`memory-core`, QMD, Honcho, etc.) | Recuperação, busca semântica, promoção, dreaming, runtime de memória | +| `memory-wiki` | Páginas de wiki compiladas, sínteses ricas em procedência, painéis, search/get/apply específicos da wiki | + +Se o plugin de memória ativo expuser artefatos de recuperação compartilhados, o OpenClaw poderá buscar +nas duas camadas em uma única passagem com `memory_search corpus=all`. + +Quando você precisar de classificação específica da wiki, procedência ou acesso +direto à página, use as ferramentas nativas da wiki. + +## Modos de cofre + +O `memory-wiki` oferece suporte a três modos de cofre: + +### `isolated` + +Cofre próprio, fontes próprias, sem dependência de `memory-core`. + +Use isto quando quiser que a wiki seja seu próprio repositório de conhecimento curado. + +### `bridge` + +Lê artefatos públicos de memória e eventos de memória do plugin de memória ativo +por meio de interfaces públicas do SDK de plugin. + +Use isto quando quiser que a wiki compile e organize os artefatos exportados +pelo plugin de memória sem acessar internamente partes privadas do plugin. + +O modo bridge pode indexar: + +- artefatos de memória exportados +- relatórios de dream +- notas diárias +- arquivos raiz de memória +- logs de eventos de memória + +### `unsafe-local` + +Saída de escape explícita na mesma máquina para caminhos privados locais. + +Esse modo é intencionalmente experimental e não portátil. Use-o apenas quando +você entender o limite de confiança e precisar especificamente de acesso ao +sistema de arquivos local que o modo bridge não pode fornecer. + +## Layout do cofre + +O plugin inicializa um cofre assim: + +```text +/ + AGENTS.md + WIKI.md + index.md + inbox.md + entities/ + concepts/ + syntheses/ + sources/ + reports/ + _attachments/ + _views/ + .openclaw-wiki/ +``` + +O conteúdo gerenciado permanece dentro de blocos gerados. Blocos de notas +humanas são preservados. + +Os principais grupos de páginas são: + +- `sources/` para matéria-prima importada e páginas sustentadas por bridge +- `entities/` para coisas duráveis, pessoas, sistemas, projetos e objetos +- `concepts/` para ideias, abstrações, padrões e políticas +- `syntheses/` para resumos compilados e consolidações mantidas +- `reports/` para painéis gerados + +## Afirmações estruturadas e evidências + +As páginas podem carregar `claims` no frontmatter estruturado, não apenas texto livre. + +Cada afirmação pode incluir: + +- `id` +- `text` +- `status` +- `confidence` +- `evidence[]` +- `updatedAt` + +Entradas de evidência podem incluir: + +- `sourceId` +- `path` +- `lines` +- `weight` +- `note` +- `updatedAt` + +É isso que faz a wiki funcionar mais como uma camada de crenças do que como um +depósito passivo de notas. As afirmações podem ser rastreadas, pontuadas, +contestadas e resolvidas de volta às fontes. + +## Pipeline de compilação + +A etapa de compilação lê páginas da wiki, normaliza resumos e emite artefatos +estáveis voltados para máquina em: + +- `.openclaw-wiki/cache/agent-digest.json` +- `.openclaw-wiki/cache/claims.jsonl` + +Esses resumos existem para que agentes e código de runtime não precisem extrair +informações de páginas Markdown. + +A saída compilada também alimenta: + +- indexação inicial da wiki para fluxos de search/get +- busca de claim-id até a página proprietária +- suplementos compactos de prompt +- geração de relatórios/painéis + +## Painéis e relatórios de integridade + +Quando `render.createDashboards` está ativado, a compilação mantém painéis em +`reports/`. + +Os relatórios integrados incluem: + +- `reports/open-questions.md` +- `reports/contradictions.md` +- `reports/low-confidence.md` +- `reports/claim-health.md` +- `reports/stale-pages.md` + +Esses relatórios acompanham itens como: + +- grupos de notas de contradição +- grupos de afirmações concorrentes +- afirmações sem evidência estruturada +- páginas e afirmações com baixa confiança +- desatualização ou atualização desconhecida +- páginas com perguntas não resolvidas + +## Busca e recuperação + +O `memory-wiki` oferece suporte a dois backends de busca: + +- `shared`: usa o fluxo de busca de memória compartilhada quando disponível +- `local`: busca na wiki localmente + +Ele também oferece suporte a três corpora: + +- `wiki` +- `memory` +- `all` + +Comportamento importante: + +- `wiki_search` e `wiki_get` usam resumos compilados como primeira passagem quando possível +- ids de afirmação podem ser resolvidos de volta à página proprietária +- afirmações contestadas/desatualizadas/atuais influenciam a classificação +- rótulos de procedência podem ser preservados nos resultados + +Regra prática: + +- use `memory_search corpus=all` para uma passagem ampla de recuperação +- use `wiki_search` + `wiki_get` quando você se importa com classificação + específica da wiki, procedência ou estrutura de crenças no nível da página + +## Ferramentas do agente + +O plugin registra estas ferramentas: + +- `wiki_status` +- `wiki_search` +- `wiki_get` +- `wiki_apply` +- `wiki_lint` + +O que elas fazem: + +- `wiki_status`: modo de cofre atual, integridade, disponibilidade da CLI do Obsidian +- `wiki_search`: busca em páginas da wiki e, quando configurado, em corpora de memória compartilhada +- `wiki_get`: lê uma página da wiki por id/caminho ou usa o corpus de memória compartilhada como fallback +- `wiki_apply`: mutações estreitas de síntese/metadados sem cirurgia livre na página +- `wiki_lint`: verificações estruturais, lacunas de procedência, contradições, perguntas em aberto + +O plugin também registra um suplemento de corpus de memória não exclusivo, para +que `memory_search` e `memory_get` compartilhados possam alcançar a wiki quando o plugin de memória +ativo oferecer suporte à seleção de corpus. + +## Comportamento de prompt e contexto + +Quando `context.includeCompiledDigestPrompt` está ativado, seções de prompt de memória +anexam um snapshot compilado compacto de `agent-digest.json`. + +Esse snapshot é intencionalmente pequeno e de alto sinal: + +- apenas as principais páginas +- apenas as principais afirmações +- contagem de contradições +- contagem de perguntas +- qualificadores de confiança/atualização + +Isso é opt-in porque altera o formato do prompt e é principalmente útil para +mecanismos de contexto ou montagem legada de prompt que consumam explicitamente +suplementos de memória. + +## Configuração + +Coloque a configuração em `plugins.entries.memory-wiki.config`: + +```json5 +{ + plugins: { + entries: { + "memory-wiki": { + enabled: true, + config: { + vaultMode: "isolated", + vault: { + path: "~/.openclaw/wiki/main", + renderMode: "obsidian", + }, + obsidian: { + enabled: true, + useOfficialCli: true, + vaultName: "OpenClaw Wiki", + openAfterWrites: false, + }, + bridge: { + enabled: false, + readMemoryArtifacts: true, + indexDreamReports: true, + indexDailyNotes: true, + indexMemoryRoot: true, + followMemoryEvents: true, + }, + ingest: { + autoCompile: true, + maxConcurrentJobs: 1, + allowUrlIngest: true, + }, + search: { + backend: "shared", + corpus: "wiki", + }, + context: { + includeCompiledDigestPrompt: false, + }, + render: { + preserveHumanBlocks: true, + createBacklinks: true, + createDashboards: true, + }, + }, + }, + }, + }, +} +``` + +Principais opções: + +- `vaultMode`: `isolated`, `bridge`, `unsafe-local` +- `vault.renderMode`: `native` ou `obsidian` +- `bridge.readMemoryArtifacts`: importar artefatos públicos do plugin de memória ativo +- `bridge.followMemoryEvents`: incluir logs de eventos no modo bridge +- `search.backend`: `shared` ou `local` +- `search.corpus`: `wiki`, `memory` ou `all` +- `context.includeCompiledDigestPrompt`: anexar snapshot compacto do resumo às seções de prompt de memória +- `render.createBacklinks`: gerar blocos relacionados determinísticos +- `render.createDashboards`: gerar páginas de painel + +## CLI + +`memory-wiki` também expõe uma superfície de CLI de nível superior: + +```bash +openclaw wiki status +openclaw wiki doctor +openclaw wiki init +openclaw wiki ingest ./notes/alpha.md +openclaw wiki compile +openclaw wiki lint +openclaw wiki search "alpha" +openclaw wiki get entity.alpha +openclaw wiki apply synthesis "Alpha Summary" --body "..." --source-id source.alpha +openclaw wiki bridge import +openclaw wiki obsidian status +``` + +Consulte [CLI: wiki](/cli/wiki) para a referência completa de comandos. + +## Suporte ao Obsidian + +Quando `vault.renderMode` é `obsidian`, o plugin grava Markdown compatível com +Obsidian e pode opcionalmente usar a CLI oficial `obsidian`. + +Os fluxos de trabalho compatíveis incluem: + +- sondagem de status +- busca no cofre +- abrir uma página +- invocar um comando do Obsidian +- ir para a nota diária + +Isso é opcional. A wiki ainda funciona em modo nativo sem Obsidian. + +## Fluxo de trabalho recomendado + +1. Mantenha seu plugin de memória ativo para recuperação/promoção/dreaming. +2. Ative `memory-wiki`. +3. Comece com o modo `isolated`, a menos que você queira explicitamente o modo bridge. +4. Use `wiki_search` / `wiki_get` quando a procedência importar. +5. Use `wiki_apply` para sínteses estreitas ou atualizações de metadados. +6. Execute `wiki_lint` após alterações significativas. +7. Ative painéis se quiser visibilidade de desatualização/contradições. + +## Documentos relacionados + +- [Visão geral da memória](/pt-BR/concepts/memory) +- [CLI: memory](/cli/memory) +- [CLI: wiki](/cli/wiki) +- [Visão geral do SDK de plugin](/pt-BR/plugins/sdk-overview) diff --git a/docs/pt-BR/providers/glm.md b/docs/pt-BR/providers/glm.md index cc09bbb1e..673a5ac7a 100644 --- a/docs/pt-BR/providers/glm.md +++ b/docs/pt-BR/providers/glm.md @@ -1,39 +1,39 @@ --- read_when: - - Você quer modelos GLM no OpenClaw - - Você precisa da convenção de nomenclatura dos modelos e da configuração + - Você quer usar modelos GLM no OpenClaw + - Você precisa da convenção de nomenclatura e da configuração dos modelos summary: Visão geral da família de modelos GLM + como usá-la no OpenClaw title: Modelos GLM x-i18n: - generated_at: "2026-04-05T12:50:43Z" + generated_at: "2026-04-08T05:26:43Z" model: gpt-5.4 provider: openai - source_hash: 59622edab5094d991987f9788fbf08b33325e737e7ff88632b0c3ac89412d4c7 + source_hash: 79a55acfa139847b4b85dbc09f1068cbd2febb1e49f984a23ea9e3b43bc910eb source_path: providers/glm.md workflow: 15 --- # Modelos GLM -GLM é uma **família de modelos** (não uma empresa) disponível pela plataforma Z.AI. No OpenClaw, os modelos GLM -são acessados por meio do provedor `zai` e de IDs de modelo como `zai/glm-5`. +GLM é uma **família de modelos** (não uma empresa) disponível pela plataforma Z.AI. No OpenClaw, os +modelos GLM são acessados pelo provedor `zai` e por IDs de modelo como `zai/glm-5`. ## Configuração da CLI ```bash -# Generic API-key setup with endpoint auto-detection +# Configuração genérica com chave de API e detecção automática do endpoint openclaw onboard --auth-choice zai-api-key -# Coding Plan Global, recommended for Coding Plan users +# Coding Plan Global, recomendado para usuários do Coding Plan openclaw onboard --auth-choice zai-coding-global -# Coding Plan CN (China region), recommended for Coding Plan users +# Coding Plan CN (região da China), recomendado para usuários do Coding Plan openclaw onboard --auth-choice zai-coding-cn -# General API +# API geral openclaw onboard --auth-choice zai-global -# General API CN (China region) +# API geral CN (região da China) openclaw onboard --auth-choice zai-cn ``` @@ -42,17 +42,17 @@ openclaw onboard --auth-choice zai-cn ```json5 { env: { ZAI_API_KEY: "sk-..." }, - agents: { defaults: { model: { primary: "zai/glm-5" } } }, + agents: { defaults: { model: { primary: "zai/glm-5.1" } } }, } ``` `zai-api-key` permite que o OpenClaw detecte o endpoint Z.AI correspondente a partir da chave e aplique automaticamente a URL base correta. Use as opções regionais explícitas quando -quiser forçar uma superfície específica do Coding Plan ou da API geral. +quiser forçar um Coding Plan específico ou uma superfície específica da API geral. -## Modelos GLM empacotados atuais +## Modelos GLM atualmente incluídos no pacote -O OpenClaw atualmente inicializa o provedor empacotado `zai` com estas referências GLM: +No momento, o OpenClaw predefine estes refs GLM no provedor `zai` incluído no pacote: - `glm-5.1` - `glm-5` @@ -71,5 +71,5 @@ O OpenClaw atualmente inicializa o provedor empacotado `zai` com estas referênc ## Observações - As versões e a disponibilidade do GLM podem mudar; consulte a documentação da Z.AI para ver as informações mais recentes. -- A referência de modelo empacotado padrão é `zai/glm-5`. -- Para detalhes do provedor, consulte [/providers/zai](/providers/zai). +- O ref de modelo padrão incluído no pacote é `zai/glm-5.1`. +- Para detalhes do provedor, consulte [/providers/zai](/pt-BR/providers/zai). diff --git a/docs/pt-BR/providers/zai.md b/docs/pt-BR/providers/zai.md index cd85694ac..0603462fc 100644 --- a/docs/pt-BR/providers/zai.md +++ b/docs/pt-BR/providers/zai.md @@ -1,14 +1,14 @@ --- read_when: - - Você quer usar modelos Z.AI / GLM no OpenClaw + - Você quer usar Z.AI / modelos GLM no OpenClaw - Você precisa de uma configuração simples com ZAI_API_KEY summary: Use o Z.AI (modelos GLM) com o OpenClaw title: Z.AI x-i18n: - generated_at: "2026-04-05T12:51:59Z" + generated_at: "2026-04-08T05:26:49Z" model: gpt-5.4 provider: openai - source_hash: 48006cdd580484f0c62e2877b27a6a68d7bc44795b3e97a28213d95182d9acf9 + source_hash: 66cbd9813ee28d202dcae34debab1b0cf9927793acb00743c1c62b48d9e381f9 source_path: providers/zai.md workflow: 15 --- @@ -19,10 +19,10 @@ Z.AI é a plataforma de API para modelos **GLM**. Ela fornece APIs REST para GLM para autenticação. Crie sua chave de API no console do Z.AI. O OpenClaw usa o provedor `zai` com uma chave de API do Z.AI. -## Setup na CLI +## Configuração da CLI ```bash -# Setup genérico com chave de API e autodetecção de endpoint +# Configuração genérica com chave de API e detecção automática de endpoint openclaw onboard --auth-choice zai-api-key # Coding Plan Global, recomendado para usuários do Coding Plan @@ -43,12 +43,12 @@ openclaw onboard --auth-choice zai-cn ```json5 { env: { ZAI_API_KEY: "sk-..." }, - agents: { defaults: { model: { primary: "zai/glm-5" } } }, + agents: { defaults: { model: { primary: "zai/glm-5.1" } } }, } ``` -`zai-api-key` permite que o OpenClaw detecte o endpoint Z.AI correspondente a partir da chave e -aplique automaticamente a base URL correta. Use as opções regionais explícitas quando +`zai-api-key` permite que o OpenClaw detecte o endpoint correspondente do Z.AI a partir da chave +e aplique automaticamente a URL base correta. Use as opções regionais explícitas quando quiser forçar uma superfície específica do Coding Plan ou da API geral. ## Catálogo GLM integrado @@ -72,11 +72,11 @@ Atualmente, o OpenClaw inicializa o provedor integrado `zai` com: ## Observações - Os modelos GLM estão disponíveis como `zai/` (exemplo: `zai/glm-5`). -- Referência de modelo padrão integrada: `zai/glm-5` -- IDs desconhecidos `glm-5*` ainda são resolvidos de forma antecipada no caminho do provedor integrado - sintetizando metadados pertencentes ao provedor a partir do template `glm-4.7` quando o id +- Referência de modelo integrado padrão: `zai/glm-5.1` +- IDs `glm-5*` desconhecidos ainda são resolvidos por encaminhamento no caminho do provedor integrado + por meio da síntese de metadados pertencentes ao provedor a partir do modelo `glm-4.7` quando o id corresponde ao formato atual da família GLM-5. -- `tool_stream` vem habilitado por padrão para streaming de chamadas de ferramenta do Z.AI. Defina +- `tool_stream` vem ativado por padrão para streaming de chamadas de ferramenta do Z.AI. Defina `agents.defaults.models["zai/"].params.tool_stream` como `false` para desativá-lo. -- Veja [/providers/glm](/providers/glm) para a visão geral da família de modelos. +- Veja [/providers/glm](/pt-BR/providers/glm) para a visão geral da família de modelos. - O Z.AI usa autenticação Bearer com sua chave de API. diff --git a/docs/pt-BR/refactor/qa.md b/docs/pt-BR/refactor/qa.md index aedf26dda..393902603 100644 --- a/docs/pt-BR/refactor/qa.md +++ b/docs/pt-BR/refactor/qa.md @@ -1,9 +1,9 @@ --- x-i18n: - generated_at: "2026-04-08T02:18:23Z" + generated_at: "2026-04-08T05:27:22Z" model: gpt-5.4 provider: openai - source_hash: 0e156cc8e2fe946a0423862f937754a7caa1fe7e6863b50a80bff49a1c86e1e8 + source_hash: 4a9066b2a939c5a9ba69141d75405f0e8097997b523164340e2f0e9a0d5060dd source_path: refactor/qa.md workflow: 15 --- @@ -14,121 +14,126 @@ Status: migração fundamental concluída. ## Objetivo -Mover o QA do OpenClaw de um modelo de definição dividido para uma única fonte de verdade: +Mover o QA do OpenClaw de um modelo de definição dividida para uma única fonte da verdade: - metadados do cenário - prompts enviados ao modelo -- setup e teardown +- configuração e desmontagem - lógica do harness - asserções e critérios de sucesso -- artefatos e dicas de relatório +- artefatos e sugestões de relatório -O estado final desejado é um harness de QA genérico que carregue arquivos poderosos de definição de cenário em vez de codificar a maior parte do comportamento em TypeScript. +O estado final desejado é um harness de QA genérico que carrega arquivos poderosos de definição de cenários em vez de codificar a maior parte do comportamento em TypeScript. ## Estado atual -A principal fonte de verdade agora vive em `qa/scenarios.md`. +A fonte primária da verdade agora vive em `qa/scenarios/index.md` mais um arquivo por +cenário em `qa/scenarios/*.md`. Implementado: -- `qa/scenarios.md` - - pacote canônico de QA +- `qa/scenarios/index.md` + - metadados canônicos do pacote de QA - identidade do operador - - missão de kickoff + - missão inicial +- `qa/scenarios/*.md` + - um arquivo Markdown por cenário - metadados do cenário - - vínculos de handler + - associações de handlers + - configuração de execução específica do cenário - `extensions/qa-lab/src/scenario-catalog.ts` - - parser de pacote Markdown + validação com zod + - parser do pacote Markdown + validação com zod - `extensions/qa-lab/src/qa-agent-bootstrap.ts` - - renderização de plano a partir do pacote Markdown + - renderização do plano a partir do pacote Markdown - `extensions/qa-lab/src/qa-agent-workspace.ts` - - semeia arquivos de compatibilidade gerados mais `QA_SCENARIOS.md` + - gera arquivos de compatibilidade semeados mais `QA_SCENARIOS.md` - `extensions/qa-lab/src/suite.ts` - - seleciona cenários executáveis por meio de vínculos de handler definidos em Markdown -- Protocolo + UI do barramento de QA + - seleciona cenários executáveis por meio de associações de handlers definidas em Markdown +- protocolo do barramento de QA + UI - anexos inline genéricos para renderização de imagem/vídeo/áudio/arquivo Superfícies divididas restantes: - `extensions/qa-lab/src/suite.ts` - - ainda controla a maior parte da lógica executável personalizada de handlers + - ainda concentra a maior parte da lógica executável de handlers personalizados - `extensions/qa-lab/src/report.ts` - - ainda deriva a estrutura do relatório a partir das saídas de runtime + - ainda deriva a estrutura do relatório a partir das saídas em tempo de execução -Então a divisão da fonte de verdade foi corrigida, mas a execução ainda é majoritariamente apoiada por handlers, em vez de totalmente declarativa. +Portanto, a divisão da fonte da verdade foi corrigida, mas a execução ainda é majoritariamente baseada em handlers, e não totalmente declarativa. -## Como é a superfície real do cenário +## Como é a superfície real de cenários -Ler a suite atual mostra algumas classes distintas de cenário. +Ao ler a suíte atual, é possível ver algumas classes distintas de cenários. ### Interação simples -- baseline de canal -- baseline de DM +- linha de base de canal +- linha de base de MD - acompanhamento em thread - troca de modelo -- continuação de aprovação +- continuidade após aprovação - reação/edição/exclusão -### Mutação de configuração e runtime +### Mutação de configuração e tempo de execução -- desativação de Skill por patch de configuração -- despertar após reinício com aplicação de configuração -- mudança de capacidade após reinício de configuração -- verificação de drift do inventário de runtime +- patch de configuração para desabilitar skill +- aplicação de configuração com reativação após reinício +- inversão de capacidade após reinício da configuração +- verificação de divergência do inventário em tempo de execução ### Asserções de sistema de arquivos e repositório -- relatório de descoberta de código/docs -- build de Lobster Invaders +- relatório de descoberta de código/documentação +- compilar Lobster Invaders - busca de artefato de imagem gerada ### Orquestração de memória -- recordação de memória +- recuperação de memória - ferramentas de memória em contexto de canal -- fallback de falha de memória +- fallback em falha de memória - classificação de memória de sessão -- isolamento de memória por thread -- varredura de dreaming de memória +- isolamento de memória de thread +- varredura de sonho de memória -### Integração de ferramenta e plugin +### Integração de ferramentas e plugins -- chamada de plugin-tools MCP -- visibilidade de Skills -- instalação hot de Skill +- chamada de plugin-tools do MCP +- visibilidade de skill +- instalação dinâmica de skill - geração nativa de imagem - roundtrip de imagem - compreensão de imagem a partir de anexo -### Multiturno e múltiplos atores +### Vários turnos e vários atores -- handoff de subagent -- síntese de fanout de subagent +- transferência para subagente +- síntese com distribuição para subagentes - fluxos no estilo recuperação após reinício -Essas categorias importam porque elas orientam os requisitos da DSL. Uma lista simples de prompt + texto esperado não é suficiente. +Essas categorias são importantes porque orientam os requisitos da DSL. Uma lista simples de prompt + texto esperado não é suficiente. ## Direção -### Fonte única de verdade +### Fonte única da verdade -Use `qa/scenarios.md` como a fonte de verdade criada manualmente. +Usar `qa/scenarios/index.md` mais `qa/scenarios/*.md` como a fonte da verdade +autoral. -O pacote deve continuar sendo: +O pacote deve permanecer: -- legível por humanos em revisão -- parseável por máquina +- legível para humanos em revisão +- analisável por máquina - rico o suficiente para orientar: - - execução da suite + - execução da suíte - bootstrap do workspace de QA - metadados da UI do QA Lab - - prompts de docs/discovery - - geração de relatório + - prompts de documentação/descoberta + - geração de relatórios ### Formato de autoria preferido -Use Markdown como formato de nível superior, com YAML estruturado dentro dele. +Usar Markdown como formato de nível superior, com YAML estruturado dentro dele. Formato recomendado: @@ -137,13 +142,13 @@ Formato recomendado: - title - surface - tags - - refs de docs + - refs de documentação - refs de código - - substituições de modelo/provider + - substituições de modelo/provedor - pré-requisitos - seções em prosa - objetivo - - observações + - notas - dicas de depuração - blocos YAML delimitados - setup @@ -153,13 +158,13 @@ Formato recomendado: Isso oferece: -- melhor legibilidade em PRs do que JSON gigante +- melhor legibilidade em PR do que um JSON gigante - contexto mais rico do que YAML puro - parsing estrito e validação com zod JSON bruto é aceitável apenas como uma forma intermediária gerada. -## Formato proposto do arquivo de cenário +## Formato proposto para arquivo de cenário Exemplo: @@ -234,9 +239,9 @@ Verify generated media is reattached on the follow-up turn. ## Capacidades do runner que a DSL precisa cobrir -Com base na suite atual, o runner genérico precisa de mais do que execução de prompt. +Com base na suíte atual, o runner genérico precisa de mais do que execução de prompt. -### Ações de ambiente e setup +### Ações de ambiente e configuração - `bus.reset` - `gateway.waitHealthy` @@ -252,7 +257,7 @@ Com base na suite atual, o runner genérico precisa de mais do que execução de - `bus.injectInbound` - `bus.injectOutbound` -### Ações de configuração e runtime +### Ações de configuração e tempo de execução - `config.get` - `config.patch` @@ -300,45 +305,45 @@ Com base na suite atual, o runner genérico precisa de mais do que execução de - `cron.managedPresent` - `artifact.exists` -## Variáveis e referências de artefato +## Variáveis e referências a artefatos -A DSL precisa oferecer suporte a saídas salvas e referências posteriores. +A DSL deve dar suporte a saídas salvas e referências posteriores. -Exemplos da suite atual: +Exemplos da suíte atual: - criar uma thread e depois reutilizar `threadId` - criar uma sessão e depois reutilizar `sessionKey` -- gerar uma imagem e depois anexar o arquivo no próximo turno -- gerar uma string de marcador de wake e depois verificar se ela aparece mais tarde +- gerar uma imagem e depois anexar o arquivo no turno seguinte +- gerar uma string de marcador de reativação e depois verificar que ela aparece mais tarde Capacidades necessárias: - `saveAs` - `${vars.name}` - `${artifacts.name}` -- referências tipadas para caminhos, chaves de sessão, IDs de thread, marcadores, saídas de ferramenta +- referências tipadas para caminhos, chaves de sessão, ids de thread, marcadores e saídas de ferramentas -Sem suporte a variáveis, o harness continuará vazando lógica de cenário de volta para o TypeScript. +Sem suporte a variáveis, o harness continuará deixando a lógica de cenário vazar de volta para o TypeScript. -## O que deve continuar como escape hatch +## O que deve permanecer como escape hatch -Um runner totalmente declarativo puro não é realista na fase 1. +Um runner totalmente declarativo e puro não é realista na fase 1. Alguns cenários são inerentemente pesados em orquestração: -- varredura de dreaming de memória -- despertar após reinício com aplicação de configuração -- mudança de capacidade após reinício de configuração +- varredura de sonho de memória +- aplicação de configuração com reativação após reinício +- inversão de capacidade após reinício da configuração - resolução de artefato de imagem gerada por timestamp/caminho -- avaliação de discovery-report +- avaliação de relatório de descoberta -Por enquanto, estes devem usar handlers personalizados explícitos. +Por enquanto, eles devem usar handlers personalizados explícitos. Regra recomendada: - 85-90% declarativo - etapas `customHandler` explícitas para o restante mais difícil -- somente custom handlers nomeados e documentados +- apenas handlers personalizados nomeados e documentados - nenhum código inline anônimo no arquivo de cenário Isso mantém o mecanismo genérico limpo e ainda permite progresso. @@ -347,13 +352,13 @@ Isso mantém o mecanismo genérico limpo e ainda permite progresso. ### Atual -O Markdown de cenário já é a fonte de verdade para: +O Markdown de cenário já é a fonte da verdade para: -- execução da suite +- execução da suíte - arquivos de bootstrap do workspace - catálogo de cenários da UI do QA Lab -- metadados de relatório -- prompts de discovery +- metadados do relatório +- prompts de descoberta Compatibilidade gerada: @@ -367,67 +372,68 @@ Compatibilidade gerada: Concluído. -- adicionado `qa/scenarios.md` -- adicionado parser para conteúdo nomeado de pacote YAML em Markdown +- adicionado `qa/scenarios/index.md` +- cenários divididos em `qa/scenarios/*.md` +- adicionado parser para conteúdo nomeado do pacote Markdown YAML - validado com zod -- consumidores alterados para o pacote parseado +- consumidores alterados para usar o pacote parseado - removidos `qa/seed-scenarios.json` e `qa/QA_KICKOFF_TASK.md` no nível do repositório ### Fase 2: mecanismo genérico - dividir `extensions/qa-lab/src/suite.ts` em: - loader - - engine + - mecanismo - registro de ações - registro de asserções - - custom handlers -- manter funções auxiliares existentes como operações do engine + - handlers personalizados +- manter as funções auxiliares existentes como operações do mecanismo Entregável: -- engine executa cenários declarativos simples +- o mecanismo executa cenários declarativos simples -Começar com cenários que são majoritariamente prompt + espera + asserção: +Começar com cenários que são principalmente prompt + espera + asserção: - acompanhamento em thread - compreensão de imagem a partir de anexo -- visibilidade e invocação de Skill -- baseline de canal +- visibilidade e invocação de skill +- linha de base de canal Entregável: -- primeiros cenários reais definidos em Markdown sendo entregues pelo mecanismo genérico +- primeiros cenários reais definidos em Markdown enviados pelo mecanismo genérico ### Fase 4: migrar cenários intermediários - roundtrip de geração de imagem - ferramentas de memória em contexto de canal - classificação de memória de sessão -- handoff de subagent -- síntese de fanout de subagent +- transferência para subagente +- síntese com distribuição para subagentes Entregável: -- variáveis, artefatos, asserções de ferramenta e asserções de request log comprovadas +- variáveis, artefatos, asserções de ferramenta e asserções de log de requisição comprovados -### Fase 5: manter cenários difíceis em custom handlers +### Fase 5: manter cenários difíceis em handlers personalizados -- varredura de dreaming de memória -- despertar após reinício com aplicação de configuração -- mudança de capacidade após reinício de configuração -- inventário de runtime +- varredura de sonho de memória +- aplicação de configuração com reativação após reinício +- inversão de capacidade após reinício da configuração +- divergência do inventário em tempo de execução Entregável: -- mesmo formato de autoria, mas com blocos explícitos de etapa personalizada onde necessário +- mesmo formato de autoria, mas com blocos de etapas personalizadas explícitas quando necessário -### Fase 6: excluir mapa de cenários hardcoded +### Fase 6: excluir o mapa de cenários codificado Quando a cobertura do pacote estiver boa o suficiente: -- remover a maior parte da lógica condicional específica de cenário em TypeScript de `extensions/qa-lab/src/suite.ts` +- remover a maior parte da ramificação TypeScript específica de cenários de `extensions/qa-lab/src/suite.ts` -## Fake Slack / suporte a rich media +## Suporte a Slack falso / rich media O barramento de QA atual é focado em texto. @@ -439,7 +445,7 @@ Arquivos relevantes: - `extensions/qa-lab/src/bus-server.ts` - `extensions/qa-lab/web/src/ui-render.ts` -Hoje o barramento de QA oferece suporte a: +Hoje, o barramento de QA oferece suporte a: - texto - reações @@ -449,7 +455,7 @@ Ele ainda não modela anexos de mídia inline. ### Contrato de transporte necessário -Adicione um modelo genérico de anexo do barramento de QA: +Adicionar um modelo genérico de anexo do barramento de QA: ```ts type QaBusAttachment = { @@ -468,7 +474,7 @@ type QaBusAttachment = { }; ``` -Depois adicione `attachments?: QaBusAttachment[]` a: +Depois adicionar `attachments?: QaBusAttachment[]` a: - `QaBusMessage` - `QaBusInboundMessageInput` @@ -476,34 +482,34 @@ Depois adicione `attachments?: QaBusAttachment[]` a: ### Por que genérico primeiro -Não construa um modelo de mídia exclusivo para Slack. +Não construir um modelo de mídia exclusivo para Slack. Em vez disso: -- um modelo de transporte de QA genérico -- múltiplos renderizadores sobre ele +- um modelo genérico de transporte de QA +- vários renderizadores sobre ele - chat atual do QA Lab - - futuro fake Slack web - - quaisquer outras visualizações de transporte simulado + - futuro web de Slack falso + - qualquer outra visualização de transporte falsa Isso evita lógica duplicada e permite que cenários de mídia permaneçam agnósticos ao transporte. ### Trabalho de UI necessário -Atualize a UI de QA para renderizar: +Atualizar a UI de QA para renderizar: -- prévia de imagem inline +- pré-visualização de imagem inline - player de áudio inline - player de vídeo inline - chip de anexo de arquivo -A UI atual já consegue renderizar threads e reações, então a renderização de anexos deve ser adicionada sobre o mesmo modelo de card de mensagem. +A UI atual já consegue renderizar threads e reações, então a renderização de anexos deve ser adicionada sobre o mesmo modelo de cartão de mensagem. -### Trabalho de cenário viabilizado pelo transporte de mídia +### Trabalho de cenário habilitado pelo transporte de mídia -Quando os anexos passarem pelo barramento de QA, poderemos adicionar cenários mais ricos de chat simulado: +Quando os anexos passarem pelo barramento de QA, poderemos adicionar cenários mais ricos de chat falso: -- resposta inline com imagem no fake Slack +- resposta com imagem inline em Slack falso - compreensão de anexo de áudio - compreensão de anexo de vídeo - ordenação mista de anexos @@ -514,7 +520,7 @@ Quando os anexos passarem pelo barramento de QA, poderemos adicionar cenários m O próximo bloco de implementação deve ser: 1. adicionar loader de cenário em Markdown + schema zod -2. gerar o catálogo atual a partir do Markdown +2. gerar o catálogo atual a partir de Markdown 3. migrar primeiro alguns cenários simples 4. adicionar suporte genérico a anexos no barramento de QA 5. renderizar imagem inline na UI de QA @@ -522,13 +528,13 @@ O próximo bloco de implementação deve ser: Este é o menor caminho que comprova ambos os objetivos: -- QA genérico definido em Markdown -- superfícies de mensagens simuladas mais ricas +- QA genérico definido por Markdown +- superfícies de mensagens falsas mais ricas -## Questões em aberto +## Perguntas em aberto -- se arquivos de cenário devem permitir templates de prompt em Markdown embutidos com interpolação de variáveis +- se os arquivos de cenário devem permitir templates de prompt em Markdown embutidos com interpolação de variáveis - se setup/cleanup devem ser seções nomeadas ou apenas listas ordenadas de ações -- se referências de artefato devem ser fortemente tipadas no schema ou baseadas em string -- se custom handlers devem viver em um único registro ou em registros por superfície -- se o arquivo gerado de compatibilidade em JSON deve continuar versionado durante a migração +- se referências a artefatos devem ser fortemente tipadas no schema ou baseadas em string +- se handlers personalizados devem viver em um único registro ou em registros por superfície +- se o arquivo de compatibilidade JSON gerado deve permanecer versionado durante a migração diff --git a/docs/pt-BR/tools/slash-commands.md b/docs/pt-BR/tools/slash-commands.md index 620c0c194..774be25b0 100644 --- a/docs/pt-BR/tools/slash-commands.md +++ b/docs/pt-BR/tools/slash-commands.md @@ -2,34 +2,34 @@ read_when: - Usar ou configurar comandos de chat - Depurar roteamento de comandos ou permissões -summary: 'Comandos slash: texto vs nativo, configuração e comandos compatíveis' -title: Comandos slash +summary: 'Comandos slash: texto vs. nativo, configuração e comandos compatíveis' +title: Comandos Slash x-i18n: - generated_at: "2026-04-06T03:13:38Z" + generated_at: "2026-04-08T05:27:39Z" model: gpt-5.4 provider: openai - source_hash: 417e35b9ddd87f25f6c019111b55b741046ea11039dde89210948185ced5696d + source_hash: 4a7ee7f1a8012058279b9e632889b291d4e659e4ec81209ca8978afbb9ad4b96 source_path: tools/slash-commands.md workflow: 15 --- # Comandos slash -Os comandos são tratados pelo Gateway. A maioria dos comandos deve ser enviada como uma mensagem **independente** que comece com `/`. -O comando de chat bash somente-host usa `! ` (com `/bash ` como alias). +Os comandos são tratados pelo Gateway. A maioria dos comandos deve ser enviada como uma mensagem **autônoma** que começa com `/`. +O comando de chat bash somente no host usa `! ` (com `/bash ` como alias). -Existem dois sistemas relacionados: +Há dois sistemas relacionados: -- **Comandos**: mensagens independentes `/...`. +- **Comandos**: mensagens autônomas `/...`. - **Diretivas**: `/think`, `/fast`, `/verbose`, `/reasoning`, `/elevated`, `/exec`, `/model`, `/queue`. - As diretivas são removidas da mensagem antes que o modelo a veja. - - Em mensagens normais de chat (não apenas de diretiva), elas são tratadas como “dicas inline” e **não** persistem configurações de sessão. - - Em mensagens apenas de diretiva (a mensagem contém apenas diretivas), elas persistem na sessão e respondem com uma confirmação. - - As diretivas só são aplicadas para **remetentes autorizados**. Se `commands.allowFrom` estiver definido, essa será a única - allowlist usada; caso contrário, a autorização vem de allowlists/pareamento do canal mais `commands.useAccessGroups`. + - Em mensagens normais de chat (não apenas com diretivas), elas são tratadas como “dicas inline” e **não** persistem as configurações da sessão. + - Em mensagens somente com diretivas (a mensagem contém apenas diretivas), elas persistem na sessão e respondem com uma confirmação. + - As diretivas só são aplicadas para **remetentes autorizados**. Se `commands.allowFrom` estiver definido, ele será a única + lista de permissões usada; caso contrário, a autorização virá das listas de permissões/emparelhamento do canal mais `commands.useAccessGroups`. Remetentes não autorizados veem as diretivas tratadas como texto simples. -Também há alguns **atalhos inline** (apenas para remetentes em allowlist/autorizados): `/help`, `/commands`, `/status`, `/whoami` (`/id`). +Há também alguns **atalhos inline** (apenas remetentes na allowlist/autorizados): `/help`, `/commands`, `/status`, `/whoami` (`/id`). Eles são executados imediatamente, são removidos antes que o modelo veja a mensagem, e o texto restante continua pelo fluxo normal. ## Configuração @@ -46,7 +46,10 @@ Eles são executados imediatamente, são removidos antes que o modelo veja a men mcp: false, plugins: false, debug: false, - restart: false, + restart: true, + ownerAllowFrom: ["discord:123456789012345678"], + ownerDisplay: "raw", + ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}", allowFrom: { "*": ["user1"], discord: ["user:123"], @@ -56,144 +59,179 @@ Eles são executados imediatamente, são removidos antes que o modelo veja a men } ``` -- `commands.text` (padrão `true`) habilita a análise de `/...` em mensagens de chat. - - Em superfícies sem comandos nativos (WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams), comandos de texto ainda funcionam mesmo se você definir isso como `false`. +- `commands.text` (padrão `true`) ativa a análise de `/...` em mensagens de chat. + - Em superfícies sem comandos nativos (WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams), os comandos de texto ainda funcionam mesmo se você definir isso como `false`. - `commands.native` (padrão `"auto"`) registra comandos nativos. - - Auto: ativado para Discord/Telegram; desativado para Slack (até você adicionar slash commands); ignorado para providers sem suporte nativo. - - Defina `channels.discord.commands.native`, `channels.telegram.commands.native` ou `channels.slack.commands.native` para sobrescrever por provider (bool ou `"auto"`). - - `false` limpa comandos previamente registrados no Discord/Telegram na inicialização. Comandos do Slack são gerenciados no app Slack e não são removidos automaticamente. -- `commands.nativeSkills` (padrão `"auto"`) registra comandos nativos de **skill** quando suportado. - - Auto: ativado para Discord/Telegram; desativado para Slack (o Slack exige criar um slash command por skill). - - Defina `channels.discord.commands.nativeSkills`, `channels.telegram.commands.nativeSkills` ou `channels.slack.commands.nativeSkills` para sobrescrever por provider (bool ou `"auto"`). -- `commands.bash` (padrão `false`) habilita `! ` para executar comandos de shell no host (`/bash ` é um alias; exige allowlists `tools.elevated`). -- `commands.bashForegroundMs` (padrão `2000`) controla quanto tempo o bash espera antes de alternar para modo em segundo plano (`0` envia imediatamente para segundo plano). -- `commands.config` (padrão `false`) habilita `/config` (lê/grava `openclaw.json`). -- `commands.mcp` (padrão `false`) habilita `/mcp` (lê/grava a configuração MCP gerenciada pelo OpenClaw em `mcp.servers`). -- `commands.plugins` (padrão `false`) habilita `/plugins` (descoberta/status de plugins mais controles de instalar + habilitar/desabilitar). -- `commands.debug` (padrão `false`) habilita `/debug` (sobrescritas apenas em runtime). -- `commands.allowFrom` (opcional) define uma allowlist por provider para autorização de comandos. Quando configurado, ela é a - única fonte de autorização para comandos e diretivas (`commands.useAccessGroups` e allowlists/pareamento do canal - são ignorados). Use `"*"` para um padrão global; chaves específicas do provider o sobrescrevem. + - Auto: ativado para Discord/Telegram; desativado para Slack (até você adicionar comandos slash); ignorado para provedores sem suporte nativo. + - Defina `channels.discord.commands.native`, `channels.telegram.commands.native` ou `channels.slack.commands.native` para sobrescrever por provedor (bool ou `"auto"`). + - `false` limpa comandos registrados anteriormente no Discord/Telegram na inicialização. Os comandos do Slack são gerenciados no app do Slack e não são removidos automaticamente. +- `commands.nativeSkills` (padrão `"auto"`) registra comandos nativos de **skill** quando compatível. + - Auto: ativado para Discord/Telegram; desativado para Slack (o Slack exige a criação de um comando slash por skill). + - Defina `channels.discord.commands.nativeSkills`, `channels.telegram.commands.nativeSkills` ou `channels.slack.commands.nativeSkills` para sobrescrever por provedor (bool ou `"auto"`). +- `commands.bash` (padrão `false`) ativa `! ` para executar comandos do shell no host (`/bash ` é um alias; exige allowlists de `tools.elevated`). +- `commands.bashForegroundMs` (padrão `2000`) controla por quanto tempo o bash espera antes de alternar para o modo em segundo plano (`0` coloca em segundo plano imediatamente). +- `commands.config` (padrão `false`) ativa `/config` (lê/grava `openclaw.json`). +- `commands.mcp` (padrão `false`) ativa `/mcp` (lê/grava a configuração de MCP gerenciada pelo OpenClaw em `mcp.servers`). +- `commands.plugins` (padrão `false`) ativa `/plugins` (descoberta/status de plugins mais controles de instalação + ativação/desativação). +- `commands.debug` (padrão `false`) ativa `/debug` (sobrescritas somente em tempo de execução). +- `commands.restart` (padrão `true`) ativa `/restart` mais ações de ferramenta de reinicialização do gateway. +- `commands.ownerAllowFrom` (opcional) define a allowlist explícita do proprietário para superfícies de comando/ferramenta somente do proprietário. Isso é separado de `commands.allowFrom`. +- `commands.ownerDisplay` controla como os ids do proprietário aparecem no prompt do sistema: `raw` ou `hash`. +- `commands.ownerDisplaySecret` opcionalmente define o segredo HMAC usado quando `commands.ownerDisplay="hash"`. +- `commands.allowFrom` (opcional) define uma allowlist por provedor para autorização de comandos. Quando configurado, ela é a + única fonte de autorização para comandos e diretivas (allowlists/emparelhamento do canal e `commands.useAccessGroups` + são ignorados). Use `"*"` para um padrão global; chaves específicas de provedor têm prioridade. - `commands.useAccessGroups` (padrão `true`) aplica allowlists/políticas a comandos quando `commands.allowFrom` não está definido. ## Lista de comandos -Texto + nativo (quando habilitado): +Fonte da verdade atual: -- `/help` -- `/commands` -- `/tools [compact|verbose]` (mostra o que o agente atual pode usar agora; `verbose` adiciona descrições) -- `/skill [input]` (executa uma skill pelo nome) -- `/status` (mostra o status atual; inclui uso/cota do provider para o provider de modelo atual quando disponível) -- `/tasks` (lista tarefas em segundo plano para a sessão atual; mostra detalhes de tarefas ativas e recentes com contagens locais de fallback por agente) -- `/allowlist` (listar/adicionar/remover entradas de allowlist) -- `/approve ` (resolve prompts de aprovação do exec; use a mensagem de aprovação pendente para ver as decisões disponíveis) -- `/context [list|detail|json]` (explica “contexto”; `detail` mostra tamanho por arquivo + por ferramenta + por skill + do prompt de sistema) -- `/btw ` (faz uma pergunta lateral efêmera sobre a sessão atual sem alterar o contexto futuro da sessão; consulte [/tools/btw](/pt-BR/tools/btw)) -- `/export-session [path]` (alias: `/export`) (exporta a sessão atual para HTML com o prompt completo de sistema) -- `/whoami` (mostra seu id de remetente; alias: `/id`) -- `/session idle ` (gerencia auto-unfocus por inatividade para bindings de thread focadas) -- `/session max-age ` (gerencia auto-unfocus de idade máxima rígida para bindings de thread focadas) -- `/subagents list|kill|log|info|send|steer|spawn` (inspeciona, controla ou cria execuções de subagentes para a sessão atual) -- `/acp spawn|cancel|steer|close|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|sessions` (inspeciona e controla sessões de runtime ACP) -- `/agents` (lista agentes vinculados à thread para esta sessão) -- `/focus ` (Discord: vincula esta thread, ou uma nova thread, a um destino de sessão/subagente) -- `/unfocus` (Discord: remove o binding atual da thread) -- `/kill ` (aborta imediatamente um ou todos os subagentes em execução desta sessão; sem mensagem de confirmação) -- `/steer ` (direciona um subagente em execução imediatamente: durante a execução quando possível, caso contrário aborta o trabalho atual e reinicia com a mensagem de direção) -- `/tell ` (alias de `/steer`) -- `/config show|get|set|unset` (persiste a configuração em disco, somente proprietário; exige `commands.config: true`) -- `/mcp show|get|set|unset` (gerencia a configuração do servidor MCP do OpenClaw, somente proprietário; exige `commands.mcp: true`) -- `/plugins list|show|get|install|enable|disable` (inspeciona plugins descobertos, instala novos e alterna ativação; somente proprietário para gravações; exige `commands.plugins: true`) - - `/plugin` é um alias de `/plugins`. - - `/plugin install ` aceita as mesmas specs de plugin de `openclaw plugins install`: caminho/arquivo local, pacote npm ou `clawhub:`. - - Gravações de habilitar/desabilitar ainda respondem com uma dica de restart. Em um gateway em primeiro plano monitorado, o OpenClaw pode executar esse restart automaticamente logo após a gravação. -- `/debug show|set|unset|reset` (sobrescritas em runtime, somente proprietário; exige `commands.debug: true`) -- `/usage off|tokens|full|cost` (rodapé de uso por resposta ou resumo de custo local) -- `/tts off|always|inbound|tagged|status|provider|limit|summary|audio` (controla TTS; consulte [/tts](/pt-BR/tools/tts)) - - Discord: o comando nativo é `/voice` (o Discord reserva `/tts`); o texto `/tts` ainda funciona. -- `/stop` -- `/restart` -- `/dock-telegram` (alias: `/dock_telegram`) (muda as respostas para Telegram) -- `/dock-discord` (alias: `/dock_discord`) (muda as respostas para Discord) -- `/dock-slack` (alias: `/dock_slack`) (muda as respostas para Slack) -- `/activation mention|always` (somente grupos) -- `/send on|off|inherit` (somente proprietário) -- `/reset` ou `/new [model]` (dica opcional de modelo; o restante é repassado) -- `/think ` (escolhas dinâmicas por modelo/provider; aliases: `/thinking`, `/t`) -- `/fast status|on|off` (omitir o argumento mostra o estado efetivo atual do fast-mode) -- `/verbose on|full|off` (alias: `/v`) -- `/reasoning on|off|stream` (alias: `/reason`; quando ativado, envia uma mensagem separada com o prefixo `Reasoning:`; `stream` = somente rascunho no Telegram) -- `/elevated on|off|ask|full` (alias: `/elev`; `full` ignora aprovações do exec) -- `/exec host= security= ask= node=` (envie `/exec` para ver o valor atual) -- `/model ` (alias: `/models`; ou `/` de `agents.defaults.models.*.alias`) -- `/queue ` (mais opções como `debounce:2s cap:25 drop:summarize`; envie `/queue` para ver as configurações atuais) -- `/bash ` (somente-host; alias de `! `; exige `commands.bash: true` + allowlists `tools.elevated`) -- `/dreaming [on|off|status|help]` (ativa/desativa dreaming global ou mostra status; consulte [Dreaming](/concepts/dreaming)) +- os built-ins do core vêm de `src/auto-reply/commands-registry.shared.ts` +- os comandos dock gerados vêm de `src/auto-reply/commands-registry.data.ts` +- os comandos de plugin vêm de chamadas `registerCommand()` do plugin +- a disponibilidade real no seu gateway ainda depende de flags de configuração, da superfície do canal e de plugins instalados/ativados -Somente texto: +### Comandos built-in do core -- `/compact [instructions]` (consulte [/concepts/compaction](/pt-BR/concepts/compaction)) -- `! ` (somente-host; um por vez; use `!poll` + `!stop` para jobs de longa duração) -- `!poll` (verifica saída / status; aceita `sessionId` opcional; `/bash poll` também funciona) -- `!stop` (interrompe o job bash em execução; aceita `sessionId` opcional; `/bash stop` também funciona) +Comandos built-in disponíveis hoje: + +- `/new [model]` inicia uma nova sessão; `/reset` é o alias de redefinição. +- `/compact [instructions]` compacta o contexto da sessão. Veja [/concepts/compaction](/pt-BR/concepts/compaction). +- `/stop` aborta a execução atual. +- `/session idle ` e `/session max-age ` gerenciam a expiração do vínculo com a thread. +- `/think ` define o nível de raciocínio. Aliases: `/thinking`, `/t`. +- `/verbose on|off|full` alterna a saída detalhada. Alias: `/v`. +- `/fast [status|on|off]` mostra ou define o modo rápido. +- `/reasoning [on|off|stream]` alterna a visibilidade do raciocínio. Alias: `/reason`. +- `/elevated [on|off|ask|full]` alterna o modo elevado. Alias: `/elev`. +- `/exec host= security= ask= node=` mostra ou define os padrões de execução. +- `/model [name|#|status]` mostra ou define o modelo. +- `/models [provider] [page] [limit=|size=|all]` lista provedores ou modelos de um provedor. +- `/queue ` gerencia o comportamento da fila (`steer`, `interrupt`, `followup`, `collect`, `steer-backlog`) mais opções como `debounce:2s cap:25 drop:summarize`. +- `/help` mostra o resumo curto de ajuda. +- `/commands` mostra o catálogo gerado de comandos. +- `/tools [compact|verbose]` mostra o que o agente atual pode usar neste momento. +- `/status` mostra o status em tempo de execução, incluindo uso/cota do provedor quando disponível. +- `/tasks` lista tarefas em segundo plano ativas/recentes da sessão atual. +- `/context [list|detail|json]` explica como o contexto é montado. +- `/export-session [path]` exporta a sessão atual para HTML. Alias: `/export`. +- `/whoami` mostra seu id de remetente. Alias: `/id`. +- `/skill [input]` executa uma skill pelo nome. +- `/allowlist [list|add|remove] ...` gerencia entradas da allowlist. Somente texto. +- `/approve ` resolve prompts de aprovação de exec. +- `/btw ` faz uma pergunta paralela sem alterar o contexto futuro da sessão. Veja [/tools/btw](/pt-BR/tools/btw). +- `/subagents list|kill|log|info|send|steer|spawn` gerencia execuções de subagentes para a sessão atual. +- `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` gerencia sessões ACP e opções de tempo de execução. +- `/focus ` vincula a thread atual do Discord ou o tópico/conversa do Telegram a um alvo de sessão. +- `/unfocus` remove o vínculo atual. +- `/agents` lista agentes vinculados a threads da sessão atual. +- `/kill ` aborta um ou todos os subagentes em execução. +- `/steer ` envia direcionamento para um subagente em execução. Alias: `/tell`. +- `/config show|get|set|unset` lê ou grava `openclaw.json`. Somente proprietário. Exige `commands.config: true`. +- `/mcp show|get|set|unset` lê ou grava a configuração do servidor MCP gerenciada pelo OpenClaw em `mcp.servers`. Somente proprietário. Exige `commands.mcp: true`. +- `/plugins list|inspect|show|get|install|enable|disable` inspeciona ou altera o estado de plugins. `/plugin` é um alias. Somente proprietário para gravações. Exige `commands.plugins: true`. +- `/debug show|set|unset|reset` gerencia sobrescritas de configuração somente em tempo de execução. Somente proprietário. Exige `commands.debug: true`. +- `/usage off|tokens|full|cost` controla o rodapé de uso por resposta ou imprime um resumo local de custos. +- `/tts on|off|status|provider|limit|summary|audio|help` controla TTS. Veja [/tools/tts](/pt-BR/tools/tts). +- `/restart` reinicia o OpenClaw quando ativado. Padrão: ativado; defina `commands.restart: false` para desativá-lo. +- `/activation mention|always` define o modo de ativação em grupo. +- `/send on|off|inherit` define a política de envio. Somente proprietário. +- `/bash ` executa um comando de shell no host. Somente texto. Alias: `! `. Exige `commands.bash: true` mais allowlists de `tools.elevated`. +- `!poll [sessionId]` verifica um job bash em segundo plano. +- `!stop [sessionId]` interrompe um job bash em segundo plano. + +### Comandos dock gerados + +Os comandos dock são gerados a partir de plugins de canal com suporte a comando nativo. Conjunto empacotado atual: + +- `/dock-discord` (alias: `/dock_discord`) +- `/dock-mattermost` (alias: `/dock_mattermost`) +- `/dock-slack` (alias: `/dock_slack`) +- `/dock-telegram` (alias: `/dock_telegram`) + +### Comandos de plugins empacotados + +Plugins empacotados podem adicionar mais comandos slash. Comandos empacotados atuais neste repositório: + +- `/dreaming [on|off|status|help]` alterna o dreaming de memória. Veja [Dreaming](/pt-BR/concepts/dreaming). +- `/pair [qr|status|pending|approve|cleanup|notify]` gerencia o fluxo de emparelhamento/configuração do dispositivo. Veja [Pairing](/pt-BR/channels/pairing). +- `/phone status|arm [duration]|disarm` ativa temporariamente comandos de nó de telefone de alto risco. +- `/voice status|list [limit]|set ` gerencia a configuração de voz do Talk. No Discord, o nome do comando nativo é `/talkvoice`. +- `/card ...` envia predefinições de rich card do LINE. Veja [LINE](/pt-BR/channels/line). +- Comandos exclusivos do QQBot: + - `/bot-ping` + - `/bot-version` + - `/bot-help` + - `/bot-upgrade` + - `/bot-logs` + +### Comandos dinâmicos de skill + +Skills invocáveis pelo usuário também são expostas como comandos slash: + +- `/skill [input]` sempre funciona como ponto de entrada genérico. +- skills também podem aparecer como comandos diretos como `/prose` quando a skill/o plugin os registra. +- o registro de comandos nativos de skill é controlado por `commands.nativeSkills` e `channels..commands.nativeSkills`. Observações: - Os comandos aceitam um `:` opcional entre o comando e os argumentos (por exemplo, `/think: high`, `/send: on`, `/help:`). -- `/new ` aceita um alias de modelo, `provider/model` ou um nome de provider (correspondência aproximada); se não houver correspondência, o texto é tratado como corpo da mensagem. -- Para o detalhamento completo de uso por provider, use `openclaw status --usage`. +- `/new ` aceita um alias de modelo, `provider/model` ou um nome de provedor (correspondência aproximada); se não houver correspondência, o texto será tratado como corpo da mensagem. +- Para o detalhamento completo de uso por provedor, use `openclaw status --usage`. - `/allowlist add|remove` exige `commands.config=true` e respeita `configWrites` do canal. -- Em canais com múltiplas contas, `/allowlist --account ` voltado para configuração e `/config set channels..accounts....` também respeitam `configWrites` da conta de destino. -- `/usage` controla o rodapé de uso por resposta; `/usage cost` imprime um resumo de custo local a partir dos logs de sessão do OpenClaw. -- `/restart` vem habilitado por padrão; defina `commands.restart: false` para desativá-lo. -- Comando nativo exclusivo do Discord: `/vc join|leave|status` controla canais de voz (exige `channels.discord.voice` e comandos nativos; não disponível como texto). -- Comandos de binding de thread do Discord (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`) exigem que bindings efetivos de thread estejam habilitados (`session.threadBindings.enabled` e/ou `channels.discord.threadBindings.enabled`). -- Referência do comando ACP e comportamento de runtime: [Agentes ACP](/pt-BR/tools/acp-agents). -- `/verbose` serve para depuração e visibilidade extra; mantenha-o **desativado** no uso normal. -- `/fast on|off` persiste uma sobrescrita de sessão. Use a opção `inherit` na UI de Sessões para limpá-la e voltar ao padrão da configuração. -- `/fast` é específico de provider: OpenAI/OpenAI Codex o mapeiam para `service_tier=priority` em endpoints nativos Responses, enquanto requisições Anthropic públicas diretas, incluindo tráfego autenticado por OAuth enviado para `api.anthropic.com`, o mapeiam para `service_tier=auto` ou `standard_only`. Consulte [OpenAI](/pt-BR/providers/openai) e [Anthropic](/pt-BR/providers/anthropic). -- Resumos de falha de ferramenta ainda são mostrados quando relevante, mas texto detalhado de falha só é incluído quando `/verbose` está `on` ou `full`. -- `/reasoning` (e `/verbose`) são arriscados em grupos: podem revelar raciocínio interno ou saída de ferramenta que você não pretendia expor. Prefira deixá-los desativados, especialmente em chats em grupo. -- `/model` persiste imediatamente o novo modelo da sessão. +- Em canais com várias contas, `/allowlist --account ` direcionado à configuração e `/config set channels..accounts....` também respeitam `configWrites` da conta de destino. +- `/usage` controla o rodapé de uso por resposta; `/usage cost` imprime um resumo local de custos a partir dos logs de sessão do OpenClaw. +- `/restart` é ativado por padrão; defina `commands.restart: false` para desativá-lo. +- `/plugins install ` aceita as mesmas especificações de plugin que `openclaw plugins install`: caminho/arquivo local, pacote npm ou `clawhub:`. +- `/plugins enable|disable` atualiza a configuração do plugin e pode solicitar uma reinicialização. +- Comando nativo exclusivo do Discord: `/vc join|leave|status` controla canais de voz (exige `channels.discord.voice` e comandos nativos; não está disponível como texto). +- Os comandos de vínculo com thread do Discord (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`) exigem que os vínculos efetivos com thread estejam ativados (`session.threadBindings.enabled` e/ou `channels.discord.threadBindings.enabled`). +- Referência de comandos ACP e comportamento em tempo de execução: [ACP Agents](/pt-BR/tools/acp-agents). +- `/verbose` é destinado a depuração e visibilidade extra; mantenha-o **desativado** no uso normal. +- `/fast on|off` persiste uma sobrescrita de sessão. Use a opção `inherit` da UI de Sessões para limpá-la e voltar aos padrões da configuração. +- `/fast` é específico do provedor: OpenAI/OpenAI Codex o mapeiam para `service_tier=priority` em endpoints nativos de Responses, enquanto solicitações públicas diretas ao Anthropic, incluindo tráfego autenticado por OAuth enviado para `api.anthropic.com`, o mapeiam para `service_tier=auto` ou `standard_only`. Veja [OpenAI](/pt-BR/providers/openai) e [Anthropic](/pt-BR/providers/anthropic). +- Resumos de falha de ferramenta ainda são mostrados quando relevantes, mas o texto detalhado da falha só é incluído quando `/verbose` está `on` ou `full`. +- `/reasoning` (e `/verbose`) são arriscados em ambientes de grupo: eles podem revelar raciocínio interno ou saída de ferramenta que você não pretendia expor. Prefira deixá-los desativados, especialmente em chats em grupo. +- `/model` persiste o novo modelo da sessão imediatamente. - Se o agente estiver ocioso, a próxima execução o usará imediatamente. -- Se já houver uma execução ativa, o OpenClaw marca uma troca ao vivo como pendente e só reinicia no novo modelo em um ponto de nova tentativa limpo. -- Se a atividade de ferramenta ou a saída da resposta já tiver começado, a troca pendente pode permanecer na fila até uma oportunidade posterior de nova tentativa ou até o próximo turno do usuário. -- **Caminho rápido:** mensagens somente de comando de remetentes em allowlist são tratadas imediatamente (ignorando fila + modelo). -- **Bloqueio por menção em grupos:** mensagens somente de comando de remetentes em allowlist ignoram exigências de menção. -- **Atalhos inline (somente remetentes em allowlist):** determinados comandos também funcionam quando embutidos em uma mensagem normal e são removidos antes que o modelo veja o restante. - - Exemplo: `hey /status` aciona uma resposta de status, e o texto restante continua pelo fluxo normal. +- Se já houver uma execução ativa, o OpenClaw marca uma troca ao vivo como pendente e só reinicia no novo modelo em um ponto limpo de tentativa. +- Se a atividade de ferramenta ou a saída de resposta já tiver começado, a troca pendente pode ficar na fila até uma oportunidade posterior de tentativa ou até o próximo turno do usuário. +- **Caminho rápido:** mensagens somente de comando de remetentes na allowlist são tratadas imediatamente (ignoram fila + modelo). +- **Gate de menção em grupo:** mensagens somente de comando de remetentes na allowlist ignoram requisitos de menção. +- **Atalhos inline (apenas remetentes na allowlist):** certos comandos também funcionam quando embutidos em uma mensagem normal e são removidos antes que o modelo veja o texto restante. + - Exemplo: `hey /status` dispara uma resposta de status, e o texto restante continua pelo fluxo normal. - Atualmente: `/help`, `/commands`, `/status`, `/whoami` (`/id`). - Mensagens somente de comando não autorizadas são ignoradas silenciosamente, e tokens inline `/...` são tratados como texto simples. -- **Comandos de skill:** Skills `user-invocable` são expostas como comandos slash. Os nomes são saneados para `a-z0-9_` (máx. 32 caracteres); colisões recebem sufixos numéricos (por exemplo `_2`). +- **Comandos de skill:** skills `user-invocable` são expostas como comandos slash. Os nomes são sanitizados para `a-z0-9_` (máximo de 32 caracteres); colisões recebem sufixos numéricos (por exemplo, `_2`). - `/skill [input]` executa uma skill pelo nome (útil quando limites de comandos nativos impedem comandos por skill). - - Por padrão, comandos de skill são encaminhados ao modelo como uma solicitação normal. - - As Skills podem opcionalmente declarar `command-dispatch: tool` para rotear o comando diretamente a uma ferramenta (determinístico, sem modelo). - - Exemplo: `/prose` (plugin OpenProse) — consulte [OpenProse](/pt-BR/prose). -- **Argumentos de comando nativo:** o Discord usa autocomplete para opções dinâmicas (e menus com botões quando você omite argumentos obrigatórios). Telegram e Slack mostram um menu com botões quando um comando suporta escolhas e você omite o argumento. + - Por padrão, os comandos de skill são encaminhados ao modelo como uma solicitação normal. + - Skills podem opcionalmente declarar `command-dispatch: tool` para rotear o comando diretamente para uma ferramenta (determinístico, sem modelo). + - Exemplo: `/prose` (plugin OpenProse) — veja [OpenProse](/pt-BR/prose). +- **Argumentos de comando nativo:** o Discord usa preenchimento automático para opções dinâmicas (e menus de botão quando você omite argumentos obrigatórios). Telegram e Slack mostram um menu de botões quando um comando aceita escolhas e você omite o argumento. ## `/tools` -`/tools` responde a uma pergunta de runtime, não a uma pergunta de configuração: **o que este agente pode usar agora +`/tools` responde a uma pergunta de tempo de execução, não a uma pergunta de configuração: **o que este agente pode usar agora nesta conversa**. - O padrão de `/tools` é compacto e otimizado para leitura rápida. - `/tools verbose` adiciona descrições curtas. -- Superfícies de comando nativo que suportam argumentos expõem a mesma mudança de modo como `compact|verbose`. -- Os resultados têm escopo de sessão, então mudar agente, canal, thread, autorização do remetente ou modelo pode - alterar a saída. -- `/tools` inclui ferramentas realmente alcançáveis em runtime, incluindo ferramentas do core, ferramentas - de plugin conectadas e ferramentas pertencentes ao canal. +- Superfícies de comando nativo com suporte a argumentos expõem o mesmo seletor de modo `compact|verbose`. +- Os resultados são limitados ao escopo da sessão, então mudar agente, canal, thread, autorização do remetente ou modelo pode + mudar a saída. +- `/tools` inclui ferramentas realmente acessíveis em tempo de execução, incluindo ferramentas do core, ferramentas + de plugins conectados e ferramentas pertencentes ao canal. -Para editar perfis e sobrescritas, use o painel Tools da Control UI ou superfícies de configuração/catálogo em vez de -tratar `/tools` como um catálogo estático. +Para editar perfil e sobrescritas, use o painel Tools da UI de Controle ou superfícies de configuração/catálogo em vez +de tratar `/tools` como um catálogo estático. ## Superfícies de uso (o que aparece onde) -- **Uso/cota do provider** (exemplo: “Claude 80% left”) aparece em `/status` para o provider do modelo atual quando o rastreamento de uso está habilitado. O OpenClaw normaliza janelas de provider para `% left`; para MiniMax, campos de porcentagem apenas de restante são invertidos antes da exibição, e respostas `model_remains` preferem a entrada do modelo de chat mais um rótulo de plano marcado por modelo. -- **Linhas de tokens/cache** em `/status` podem usar como fallback a entrada de uso mais recente da transcrição quando o snapshot da sessão ao vivo for escasso. Valores vivos existentes e não zero ainda prevalecem, e o fallback da transcrição também pode recuperar o rótulo do modelo de runtime ativo mais um total maior voltado ao prompt quando os totais armazenados estiverem ausentes ou forem menores. -- **Tokens/custo por resposta** são controlados por `/usage off|tokens|full` (acrescentados às respostas normais). -- `/model status` trata de **modelos/auth/endpoints**, não de uso. +- **Uso/cota do provedor** (exemplo: “Claude 80% restante”) aparece em `/status` para o provedor de modelo atual quando o rastreamento de uso está ativado. O OpenClaw normaliza janelas de provedor para `% restante`; para o MiniMax, campos percentuais apenas de restante são invertidos antes da exibição, e respostas `model_remains` preferem a entrada do modelo de chat mais um rótulo de plano com tag de modelo. +- **Linhas de token/cache** em `/status` podem recorrer à entrada de uso mais recente do transcript quando o snapshot da sessão ativa é escasso. Valores ativos não nulos ainda têm prioridade, e o fallback do transcript também pode recuperar o rótulo do modelo de tempo de execução ativo mais um total maior orientado a prompt quando os totais armazenados estão ausentes ou são menores. +- **Tokens/custo por resposta** é controlado por `/usage off|tokens|full` (anexado às respostas normais). +- `/model status` é sobre **modelos/auth/endpoints**, não sobre uso. ## Seleção de modelo (`/model`) @@ -212,14 +250,14 @@ Exemplos: Observações: -- `/model` e `/model list` mostram um seletor compacto numerado (família de modelo + providers disponíveis). -- No Discord, `/model` e `/models` abrem um seletor interativo com menus suspensos de provider e modelo mais uma etapa Submit. -- `/model <#>` seleciona a partir desse seletor (e prefere o provider atual quando possível). -- `/model status` mostra a visualização detalhada, incluindo endpoint configurado do provider (`baseUrl`) e modo de API (`api`) quando disponíveis. +- `/model` e `/model list` mostram um seletor compacto e numerado (família do modelo + provedores disponíveis). +- No Discord, `/model` e `/models` abrem um seletor interativo com dropdowns de provedor e modelo mais uma etapa Submit. +- `/model <#>` seleciona a partir desse seletor (e prefere o provedor atual quando possível). +- `/model status` mostra a visualização detalhada, incluindo o endpoint configurado do provedor (`baseUrl`) e o modo de API (`api`) quando disponível. ## Sobrescritas de depuração -`/debug` permite definir sobrescritas de configuração **somente em runtime** (em memória, não em disco). Somente proprietário. Desativado por padrão; habilite com `commands.debug: true`. +`/debug` permite definir sobrescritas de configuração **somente em tempo de execução** (memória, não disco). Somente proprietário. Desativado por padrão; ative com `commands.debug: true`. Exemplos: @@ -234,11 +272,11 @@ Exemplos: Observações: - As sobrescritas se aplicam imediatamente a novas leituras de configuração, mas **não** gravam em `openclaw.json`. -- Use `/debug reset` para limpar todas as sobrescritas e voltar à configuração em disco. +- Use `/debug reset` para limpar todas as sobrescritas e retornar à configuração em disco. ## Atualizações de configuração -`/config` grava na sua configuração em disco (`openclaw.json`). Somente proprietário. Desativado por padrão; habilite com `commands.config: true`. +`/config` grava na sua configuração em disco (`openclaw.json`). Somente proprietário. Desativado por padrão; ative com `commands.config: true`. Exemplos: @@ -252,12 +290,12 @@ Exemplos: Observações: -- A configuração é validada antes da gravação; mudanças inválidas são rejeitadas. -- Atualizações feitas por `/config` persistem após restart. +- A configuração é validada antes da gravação; alterações inválidas são rejeitadas. +- As atualizações de `/config` persistem entre reinicializações. ## Atualizações de MCP -`/mcp` grava definições de servidor MCP gerenciadas pelo OpenClaw em `mcp.servers`. Somente proprietário. Desativado por padrão; habilite com `commands.mcp: true`. +`/mcp` grava definições de servidor MCP gerenciadas pelo OpenClaw em `mcp.servers`. Somente proprietário. Desativado por padrão; ative com `commands.mcp: true`. Exemplos: @@ -270,12 +308,12 @@ Exemplos: Observações: -- `/mcp` armazena a configuração na configuração do OpenClaw, não nas settings do projeto pertencentes ao Pi. -- Adaptadores de runtime decidem quais transportes são realmente executáveis. +- `/mcp` armazena a configuração na configuração do OpenClaw, não nas configurações de projeto pertencentes ao Pi. +- Adaptadores de tempo de execução decidem quais transportes são realmente executáveis. ## Atualizações de plugin -`/plugins` permite que operadores inspecionem plugins descobertos e alternem a habilitação na configuração. Fluxos somente leitura podem usar `/plugin` como alias. Desativado por padrão; habilite com `commands.plugins: true`. +`/plugins` permite que operadores inspecionem plugins descobertos e alternem a ativação na configuração. Fluxos somente leitura podem usar `/plugin` como alias. Desativado por padrão; ative com `commands.plugins: true`. Exemplos: @@ -289,9 +327,9 @@ Exemplos: Observações: -- `/plugins list` e `/plugins show` usam descoberta real de plugins com base no workspace atual mais a configuração em disco. +- `/plugins list` e `/plugins show` usam descoberta real de plugins no workspace atual mais a configuração em disco. - `/plugins enable|disable` atualiza apenas a configuração do plugin; não instala nem desinstala plugins. -- Após mudanças de habilitação/desabilitação, reinicie o gateway para aplicá-las. +- Após alterações de ativação/desativação, reinicie o gateway para aplicá-las. ## Observações sobre superfícies @@ -299,22 +337,22 @@ Observações: - **Comandos nativos** usam sessões isoladas: - Discord: `agent::discord:slash:` - Slack: `agent::slack:slash:` (prefixo configurável via `channels.slack.slashCommand.sessionPrefix`) - - Telegram: `telegram:slash:` (tem como alvo a sessão do chat via `CommandTargetSessionKey`) -- **`/stop`** tem como alvo a sessão de chat ativa para poder abortar a execução atual. -- **Slack:** `channels.slack.slashCommand` ainda tem suporte para um único comando no estilo `/openclaw`. Se você habilitar `commands.native`, deverá criar um slash command do Slack por comando integrado (mesmos nomes de `/help`). Menus de argumentos de comando para Slack são entregues como botões efêmeros do Block Kit. + - Telegram: `telegram:slash:` (direciona para a sessão do chat via `CommandTargetSessionKey`) +- **`/stop`** tem como alvo a sessão ativa de chat para poder abortar a execução atual. +- **Slack:** `channels.slack.slashCommand` ainda é compatível para um único comando no estilo `/openclaw`. Se você ativar `commands.native`, precisará criar um comando slash do Slack para cada comando built-in (mesmos nomes de `/help`). Menus de argumentos de comando para o Slack são entregues como botões Block Kit efêmeros. - Exceção nativa do Slack: registre `/agentstatus` (não `/status`) porque o Slack reserva `/status`. O texto `/status` ainda funciona em mensagens do Slack. -## Perguntas laterais BTW +## Perguntas paralelas com BTW -`/btw` é uma **pergunta lateral** rápida sobre a sessão atual. +`/btw` é uma **pergunta paralela** rápida sobre a sessão atual. Diferentemente do chat normal: -- ela usa a sessão atual como contexto de fundo, -- é executada como uma chamada separada **sem ferramentas** e única, -- não altera o contexto futuro da sessão, -- não é gravada no histórico da transcrição, -- é entregue como um resultado lateral ao vivo em vez de uma mensagem normal do assistente. +- ele usa a sessão atual como contexto de fundo, +- ele é executado como uma chamada isolada **sem ferramentas**, +- ele não altera o contexto futuro da sessão, +- ele não é gravado no histórico do transcript, +- ele é entregue como um resultado paralelo ao vivo em vez de uma mensagem normal do assistente. Isso torna `/btw` útil quando você quer um esclarecimento temporário enquanto a tarefa principal continua. @@ -325,5 +363,5 @@ Exemplo: /btw o que estamos fazendo agora? ``` -Consulte [Perguntas laterais BTW](/pt-BR/tools/btw) para ver o comportamento completo e -os detalhes de UX do cliente. +Veja [BTW Side Questions](/pt-BR/tools/btw) para o comportamento completo e detalhes +da UX do cliente. diff --git a/docs/pt-BR/tools/tts.md b/docs/pt-BR/tools/tts.md index a9b3e1ba5..89241ec24 100644 --- a/docs/pt-BR/tools/tts.md +++ b/docs/pt-BR/tools/tts.md @@ -1,57 +1,57 @@ --- read_when: - - Habilitando text-to-speech para respostas - - Configurando provedores ou limites de TTS - - Usando comandos /tts -summary: Text-to-speech (TTS) para respostas de saída -title: Text-to-Speech + - Ativar texto para fala para respostas + - Configurar provedores ou limites de TTS + - Usar comandos /tts +summary: Texto para fala (TTS) para respostas enviadas +title: Texto para fala x-i18n: - generated_at: "2026-04-05T12:56:56Z" + generated_at: "2026-04-08T05:27:32Z" model: gpt-5.4 provider: openai - source_hash: 8487c8acef7585bd4eb5e3b39e2a063ebc6b5f0103524abdcbadd3a7781ffc46 + source_hash: 6e0fbcaf61282733c134f682e05a71f94d2169c03a85131ce9ad233c71a1e533 source_path: tools/tts.md workflow: 15 --- -# Text-to-speech (TTS) +# Texto para fala (TTS) -O OpenClaw pode converter respostas de saída em áudio usando ElevenLabs, Microsoft, MiniMax ou OpenAI. -Funciona em qualquer lugar onde o OpenClaw possa enviar áudio. +O OpenClaw pode converter respostas enviadas em áudio usando ElevenLabs, Microsoft, MiniMax ou OpenAI. +Ele funciona em qualquer lugar onde o OpenClaw possa enviar áudio. ## Serviços compatíveis - **ElevenLabs** (provedor principal ou de fallback) -- **Microsoft** (provedor principal ou de fallback; a implementação incluída atual usa `node-edge-tts`) +- **Microsoft** (provedor principal ou de fallback; a implementação integrada atual usa `node-edge-tts`) - **MiniMax** (provedor principal ou de fallback; usa a API T2A v2) - **OpenAI** (provedor principal ou de fallback; também usado para resumos) -### Observações sobre o Microsoft speech +### Observações sobre a fala da Microsoft -O provedor de fala da Microsoft incluído atualmente usa o serviço online de +Atualmente, o provedor integrado de fala da Microsoft usa o serviço online de TTS neural do Microsoft Edge por meio da biblioteca `node-edge-tts`. É um serviço hospedado (não local), usa endpoints da Microsoft e não exige chave de API. O `node-edge-tts` expõe opções de configuração de fala e formatos de saída, mas -nem todas as opções são compatíveis com o serviço. Configuração legada e entrada de diretiva -usando `edge` ainda funcionam e são normalizadas para `microsoft`. +nem todas as opções são compatíveis com o serviço. Configuração legada e entrada +de diretiva usando `edge` ainda funcionam e são normalizadas para `microsoft`. -Como esse caminho usa um serviço web público sem SLA ou cota publicados, -trate-o como melhor esforço. Se você precisar de limites garantidos e suporte, use OpenAI -ou ElevenLabs. +Como esse caminho é um serviço web público sem SLA ou cota publicados, +trate-o como melhor esforço. Se você precisar de limites garantidos e suporte, +use OpenAI ou ElevenLabs. ## Chaves opcionais -Se você quiser OpenAI, ElevenLabs ou MiniMax: +Se você quiser usar OpenAI, ElevenLabs ou MiniMax: - `ELEVENLABS_API_KEY` (ou `XI_API_KEY`) - `MINIMAX_API_KEY` - `OPENAI_API_KEY` -O Microsoft speech **não** exige chave de API. +A fala da Microsoft **não** exige chave de API. Se vários provedores estiverem configurados, o provedor selecionado será usado primeiro e os demais serão opções de fallback. O resumo automático usa o `summaryModel` configurado (ou `agents.defaults.model.primary`), -portanto esse provedor também deve estar autenticado se você habilitar resumos. +portanto esse provedor também precisa estar autenticado se você ativar resumos. ## Links dos serviços @@ -59,24 +59,24 @@ portanto esse provedor também deve estar autenticado se você habilitar resumos - [Referência da API de áudio da OpenAI](https://platform.openai.com/docs/api-reference/audio) - [Text to Speech da ElevenLabs](https://elevenlabs.io/docs/api-reference/text-to-speech) - [Autenticação da ElevenLabs](https://elevenlabs.io/docs/api-reference/authentication) -- [API MiniMax T2A v2](https://platform.minimaxi.com/document/T2A%20V2) +- [API T2A v2 da MiniMax](https://platform.minimaxi.com/document/T2A%20V2) - [node-edge-tts](https://github.com/SchneeHertz/node-edge-tts) - [Formatos de saída do Microsoft Speech](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech#audio-outputs) -## Isso está habilitado por padrão? +## Está ativado por padrão? -Não. O auto‑TTS vem **desativado** por padrão. Habilite-o na configuração com -`messages.tts.auto` ou por sessão com `/tts always` (alias: `/tts on`). +Não. O TTS automático vem **desativado** por padrão. Ative-o na configuração com +`messages.tts.auto` ou localmente com `/tts on`. Quando `messages.tts.provider` não está definido, o OpenClaw escolhe o primeiro provedor de fala configurado na ordem de seleção automática do registro. ## Configuração -A configuração de TTS fica em `messages.tts` no `openclaw.json`. +A configuração de TTS fica em `messages.tts` em `openclaw.json`. O esquema completo está em [Configuração do Gateway](/pt-BR/gateway/configuration). -### Configuração mínima (habilitar + provedor) +### Configuração mínima (ativar + provedor) ```json5 { @@ -177,7 +177,7 @@ O esquema completo está em [Configuração do Gateway](/pt-BR/gateway/configura } ``` -### Desabilitar o Microsoft speech +### Desativar a fala da Microsoft ```json5 { @@ -220,7 +220,7 @@ O esquema completo está em [Configuração do Gateway](/pt-BR/gateway/configura } ``` -### Desabilitar resumo automático para respostas longas +### Desativar resumo automático para respostas longas ```json5 { @@ -240,28 +240,28 @@ Depois execute: ### Observações sobre os campos -- `auto`: modo de auto‑TTS (`off`, `always`, `inbound`, `tagged`). - - `inbound` envia áudio apenas após uma mensagem de voz recebida. - - `tagged` envia áudio apenas quando a resposta inclui tags `[[tts]]`. +- `auto`: modo de TTS automático (`off`, `always`, `inbound`, `tagged`). + - `inbound` só envia áudio após uma mensagem de voz recebida. + - `tagged` só envia áudio quando a resposta inclui tags `[[tts]]`. - `enabled`: alternância legada (o doctor migra isso para `auto`). - `mode`: `"final"` (padrão) ou `"all"` (inclui respostas de ferramenta/bloco). - `provider`: id do provedor de fala, como `"elevenlabs"`, `"microsoft"`, `"minimax"` ou `"openai"` (o fallback é automático). -- Se `provider` **não estiver definido**, o OpenClaw usa o primeiro provedor de fala configurado na ordem de seleção automática do registro. -- O `provider: "edge"` legado ainda funciona e é normalizado para `microsoft`. +- Se `provider` estiver **não definido**, o OpenClaw usa o primeiro provedor de fala configurado na ordem de seleção automática do registro. +- O legado `provider: "edge"` ainda funciona e é normalizado para `microsoft`. - `summaryModel`: modelo barato opcional para resumo automático; o padrão é `agents.defaults.model.primary`. - Aceita `provider/model` ou um alias de modelo configurado. - `modelOverrides`: permite que o modelo emita diretivas de TTS (ativado por padrão). - `allowProvider` tem padrão `false` (troca de provedor é opt-in). -- `providers.`: configurações do provedor, indexadas pelo id do provedor de fala. -- Blocos diretos de provedor legados (`messages.tts.openai`, `messages.tts.elevenlabs`, `messages.tts.microsoft`, `messages.tts.edge`) são migrados automaticamente para `messages.tts.providers.` no carregamento. -- `maxTextLength`: limite rígido para entrada de TTS (caracteres). `/tts audio` falha se excedido. +- `providers.`: configurações pertencentes ao provedor, indexadas pelo id do provedor de fala. +- Blocos legados diretos de provedor (`messages.tts.openai`, `messages.tts.elevenlabs`, `messages.tts.microsoft`, `messages.tts.edge`) são migrados automaticamente para `messages.tts.providers.` no carregamento. +- `maxTextLength`: limite rígido para entrada de TTS (caracteres). `/tts audio` falha se for excedido. - `timeoutMs`: tempo limite da solicitação (ms). - `prefsPath`: substitui o caminho local do JSON de preferências (provedor/limite/resumo). -- Os valores de `apiKey` usam como fallback variáveis de ambiente (`ELEVENLABS_API_KEY`/`XI_API_KEY`, `MINIMAX_API_KEY`, `OPENAI_API_KEY`). +- Valores de `apiKey` usam fallback para variáveis de ambiente (`ELEVENLABS_API_KEY`/`XI_API_KEY`, `MINIMAX_API_KEY`, `OPENAI_API_KEY`). - `providers.elevenlabs.baseUrl`: substitui a URL base da API da ElevenLabs. - `providers.openai.baseUrl`: substitui o endpoint de TTS da OpenAI. - Ordem de resolução: `messages.tts.providers.openai.baseUrl` -> `OPENAI_TTS_BASE_URL` -> `https://api.openai.com/v1` - - Valores diferentes do padrão são tratados como endpoints de TTS compatíveis com OpenAI, então nomes personalizados de modelo e voz são aceitos. + - Valores não padrão são tratados como endpoints de TTS compatíveis com OpenAI, portanto nomes personalizados de modelo e voz são aceitos. - `providers.elevenlabs.voiceSettings`: - `stability`, `similarityBoost`, `style`: `0..1` - `useSpeakerBoost`: `true|false` @@ -269,57 +269,57 @@ Depois execute: - `providers.elevenlabs.applyTextNormalization`: `auto|on|off` - `providers.elevenlabs.languageCode`: ISO 639-1 de 2 letras (ex.: `en`, `de`) - `providers.elevenlabs.seed`: inteiro `0..4294967295` (determinismo de melhor esforço) -- `providers.minimax.baseUrl`: substitui a URL base da API MiniMax (padrão `https://api.minimax.io`, env: `MINIMAX_API_HOST`). +- `providers.minimax.baseUrl`: substitui a URL base da API da MiniMax (padrão `https://api.minimax.io`, env: `MINIMAX_API_HOST`). - `providers.minimax.model`: modelo de TTS (padrão `speech-2.8-hd`, env: `MINIMAX_TTS_MODEL`). - `providers.minimax.voiceId`: identificador de voz (padrão `English_expressive_narrator`, env: `MINIMAX_TTS_VOICE_ID`). - `providers.minimax.speed`: velocidade de reprodução `0.5..2.0` (padrão 1.0). - `providers.minimax.vol`: volume `(0, 10]` (padrão 1.0; deve ser maior que 0). - `providers.minimax.pitch`: deslocamento de tom `-12..12` (padrão 0). -- `providers.microsoft.enabled`: permite o uso do Microsoft speech (padrão `true`; sem chave de API). +- `providers.microsoft.enabled`: permite o uso da fala da Microsoft (padrão `true`; sem chave de API). - `providers.microsoft.voice`: nome da voz neural da Microsoft (ex.: `en-US-MichelleNeural`). - `providers.microsoft.lang`: código do idioma (ex.: `en-US`). - `providers.microsoft.outputFormat`: formato de saída da Microsoft (ex.: `audio-24khz-48kbitrate-mono-mp3`). - - Consulte os formatos de saída do Microsoft Speech para valores válidos; nem todos os formatos são compatíveis com o transporte incluído baseado em Edge. + - Veja os formatos de saída do Microsoft Speech para valores válidos; nem todos os formatos são compatíveis com o transporte integrado baseado em Edge. - `providers.microsoft.rate` / `providers.microsoft.pitch` / `providers.microsoft.volume`: strings de porcentagem (ex.: `+10%`, `-5%`). - `providers.microsoft.saveSubtitles`: grava legendas em JSON ao lado do arquivo de áudio. -- `providers.microsoft.proxy`: URL de proxy para solicitações do Microsoft speech. +- `providers.microsoft.proxy`: URL de proxy para solicitações de fala da Microsoft. - `providers.microsoft.timeoutMs`: substituição do tempo limite da solicitação (ms). - `edge.*`: alias legado para as mesmas configurações da Microsoft. -## Substituições guiadas pelo modelo (ativado por padrão) +## Substituições orientadas pelo modelo (ativado por padrão) Por padrão, o modelo **pode** emitir diretivas de TTS para uma única resposta. Quando `messages.tts.auto` é `tagged`, essas diretivas são necessárias para acionar o áudio. Quando ativado, o modelo pode emitir diretivas `[[tts:...]]` para substituir a voz -de uma única resposta, além de um bloco opcional `[[tts:text]]...[[/tts:text]]` para +em uma única resposta, além de um bloco opcional `[[tts:text]]...[[/tts:text]]` para fornecer tags expressivas (risadas, indicações de canto etc.) que devem aparecer apenas no áudio. -As diretivas `provider=...` são ignoradas a menos que `modelOverrides.allowProvider: true`. +Diretivas `provider=...` são ignoradas, a menos que `modelOverrides.allowProvider: true`. Exemplo de payload de resposta: ``` -Here you go. +Aqui está. [[tts:voiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]] -[[tts:text]](laughs) Read the song once more.[[/tts:text]] +[[tts:text]](ri) Leia a música mais uma vez.[[/tts:text]] ``` Chaves de diretiva disponíveis (quando ativadas): -- `provider` (id do provedor de fala registrado, por exemplo `openai`, `elevenlabs`, `minimax` ou `microsoft`; requer `allowProvider: true`) +- `provider` (id do provedor de fala registrado, por exemplo `openai`, `elevenlabs`, `minimax` ou `microsoft`; exige `allowProvider: true`) - `voice` (voz da OpenAI) ou `voiceId` (ElevenLabs / MiniMax) -- `model` (modelo de TTS da OpenAI, id do modelo da ElevenLabs ou modelo do MiniMax) +- `model` (modelo de TTS da OpenAI, id de modelo da ElevenLabs ou modelo da MiniMax) - `stability`, `similarityBoost`, `style`, `speed`, `useSpeakerBoost` -- `vol` / `volume` (volume do MiniMax, 0-10) -- `pitch` (tom do MiniMax, -12 a 12) +- `vol` / `volume` (volume da MiniMax, 0-10) +- `pitch` (tom da MiniMax, -12 a 12) - `applyTextNormalization` (`auto|on|off`) - `languageCode` (ISO 639-1) - `seed` -Desabilite todas as substituições do modelo: +Desative todas as substituições do modelo: ```json5 { @@ -333,7 +333,7 @@ Desabilite todas as substituições do modelo: } ``` -Allowlist opcional (habilita troca de provedor mantendo os outros controles configuráveis): +Allowlist opcional (ativa troca de provedor enquanto mantém outros controles configuráveis): ```json5 { @@ -351,7 +351,7 @@ Allowlist opcional (habilita troca de provedor mantendo os outros controles conf ## Preferências por usuário -Os comandos de barra gravam substituições locais em `prefsPath` (padrão: +Os comandos slash gravam substituições locais em `prefsPath` (padrão: `~/.openclaw/settings/tts.json`, substituível com `OPENCLAW_TTS_PREFS` ou `messages.tts.prefsPath`). @@ -359,7 +359,7 @@ Campos armazenados: - `enabled` - `provider` -- `maxLength` (limite para resumo; padrão 1500 caracteres) +- `maxLength` (limiar para resumo; padrão 1500 caracteres) - `summarize` (padrão `true`) Eles substituem `messages.tts.*` para esse host. @@ -367,25 +367,25 @@ Eles substituem `messages.tts.*` para esse host. ## Formatos de saída (fixos) - **Feishu / Matrix / Telegram / WhatsApp**: mensagem de voz Opus (`opus_48000_64` da ElevenLabs, `opus` da OpenAI). - - 48kHz / 64kbps é um bom equilíbrio para mensagem de voz. + - 48kHz / 64kbps é um bom equilíbrio para mensagens de voz. - **Outros canais**: MP3 (`mp3_44100_128` da ElevenLabs, `mp3` da OpenAI). - - 44.1kHz / 128kbps é o equilíbrio padrão para clareza de fala. + - 44,1kHz / 128kbps é o equilíbrio padrão para clareza da fala. - **MiniMax**: MP3 (modelo `speech-2.8-hd`, taxa de amostragem de 32kHz). O formato de nota de voz não é compatível nativamente; use OpenAI ou ElevenLabs para mensagens de voz Opus garantidas. - **Microsoft**: usa `microsoft.outputFormat` (padrão `audio-24khz-48kbitrate-mono-mp3`). - - O transporte incluído aceita um `outputFormat`, mas nem todos os formatos estão disponíveis no serviço. + - O transporte integrado aceita `outputFormat`, mas nem todos os formatos estão disponíveis no serviço. - Os valores de formato de saída seguem os formatos de saída do Microsoft Speech (incluindo Ogg/WebM Opus). - O `sendVoice` do Telegram aceita OGG/MP3/M4A; use OpenAI/ElevenLabs se você precisar de mensagens de voz Opus garantidas. - Se o formato de saída configurado da Microsoft falhar, o OpenClaw tenta novamente com MP3. -Os formatos de saída OpenAI/ElevenLabs são fixos por canal (veja acima). +Os formatos de saída da OpenAI/ElevenLabs são fixos por canal (veja acima). -## Comportamento do auto-TTS +## Comportamento do TTS automático -Quando habilitado, o OpenClaw: +Quando ativado, o OpenClaw: - ignora TTS se a resposta já contiver mídia ou uma diretiva `MEDIA:`. - ignora respostas muito curtas (< 10 caracteres). -- resume respostas longas quando habilitado usando `agents.defaults.model.primary` (ou `summaryModel`). +- resume respostas longas, quando ativado, usando `agents.defaults.model.primary` (ou `summaryModel`). - anexa o áudio gerado à resposta. Se a resposta exceder `maxLength` e o resumo estiver desativado (ou não houver chave de API para o @@ -395,31 +395,29 @@ será ignorado e a resposta de texto normal será enviada. ## Diagrama de fluxo ``` -Reply -> TTS enabled? - no -> send text - yes -> has media / MEDIA: / short? - yes -> send text - no -> length > limit? - no -> TTS -> attach audio - yes -> summary enabled? - no -> send text - yes -> summarize (summaryModel or agents.defaults.model.primary) - -> TTS -> attach audio +Resposta -> TTS ativado? + não -> enviar texto + sim -> tem mídia / MEDIA: / curta? + sim -> enviar texto + não -> comprimento > limite? + não -> TTS -> anexar áudio + sim -> resumo ativado? + não -> enviar texto + sim -> resumir (summaryModel ou agents.defaults.model.primary) + -> TTS -> anexar áudio ``` -## Uso do comando de barra +## Uso do comando slash Há um único comando: `/tts`. -Consulte [Comandos de barra](/tools/slash-commands) para detalhes de habilitação. +Veja [Comandos slash](/pt-BR/tools/slash-commands) para detalhes de ativação. -Observação sobre o Discord: `/tts` é um comando nativo do Discord, então o OpenClaw registra -`/voice` como comando nativo lá. O texto `/tts ...` ainda funciona. +Observação para Discord: `/tts` é um comando integrado do Discord, então o OpenClaw registra +`/voice` como o comando nativo lá. O texto `/tts ...` ainda funciona. ``` /tts off -/tts always -/tts inbound -/tts tagged +/tts on /tts status /tts provider openai /tts limit 2000 @@ -429,16 +427,18 @@ Observação sobre o Discord: `/tts` é um comando nativo do Discord, então o O Observações: -- Os comandos exigem um remetente autorizado (as regras de allowlist/proprietário continuam valendo). -- `commands.text` ou o registro de comandos nativos devem estar habilitados. -- `off|always|inbound|tagged` são alternâncias por sessão (`/tts on` é um alias para `/tts always`). -- `limit` e `summary` são armazenados em preferências locais, não na configuração principal. -- `/tts audio` gera uma resposta de áudio única (não ativa o TTS). +- Os comandos exigem um remetente autorizado (regras de allowlist/proprietário ainda se aplicam). +- `commands.text` ou o registro de comando nativo precisa estar ativado. +- A configuração `messages.tts.auto` aceita `off|always|inbound|tagged`. +- `/tts on` grava a preferência local de TTS como `always`; `/tts off` a grava como `off`. +- Use a configuração quando quiser padrões `inbound` ou `tagged`. +- `limit` e `summary` são armazenados nas preferências locais, não na configuração principal. +- `/tts audio` gera uma resposta de áudio pontual (não ativa o TTS). - `/tts status` inclui visibilidade de fallback para a tentativa mais recente: - fallback com sucesso: `Fallback: -> ` mais `Attempts: ...` - falha: `Error: ...` mais `Attempts: ...` - diagnósticos detalhados: `Attempt details: provider:outcome(reasonCode) latency` -- Falhas de API da OpenAI e da ElevenLabs agora incluem detalhes de erro do provedor já analisados e o id da solicitação (quando retornado pelo provedor), e isso aparece em erros/logs de TTS. +- Falhas de API da OpenAI e da ElevenLabs agora incluem detalhes de erro do provedor analisados e o id da solicitação (quando retornado pelo provedor), o que é exibido em erros/logs de TTS. ## Ferramenta do agente