From 81a4b42d69d7a6a2068382f80d48b7c62a91eebf Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Wed, 15 Apr 2026 19:52:10 +0000 Subject: [PATCH] chore(i18n): refresh pt-BR translations --- docs/pt-BR/channels/matrix.md | 455 ++--- docs/pt-BR/concepts/system-prompt.md | 135 +- docs/pt-BR/gateway/configuration-reference.md | 1468 +++++++++-------- docs/pt-BR/plugins/sdk-channel-plugins.md | 231 +-- docs/pt-BR/plugins/sdk-entrypoints.md | 161 +- docs/pt-BR/plugins/sdk-runtime.md | 169 +- docs/pt-BR/plugins/sdk-setup.md | 302 ++-- docs/pt-BR/plugins/sdk-testing.md | 70 +- docs/pt-BR/reference/token-use.md | 129 +- 9 files changed, 1663 insertions(+), 1457 deletions(-) diff --git a/docs/pt-BR/channels/matrix.md b/docs/pt-BR/channels/matrix.md index 35ed9e3d6..f141578e5 100644 --- a/docs/pt-BR/channels/matrix.md +++ b/docs/pt-BR/channels/matrix.md @@ -5,32 +5,32 @@ read_when: summary: Status do suporte ao Matrix, configuração inicial e exemplos de configuração title: Matrix x-i18n: - generated_at: "2026-04-15T05:33:50Z" + generated_at: "2026-04-15T19:41:33Z" model: gpt-5.4 provider: openai - source_hash: 631f6fdcfebc23136c1a66b04851a25c047535d13cceba5650b8b421bc3afcf8 + source_hash: bd730bb9d0c8a548ee48b20931b3222e9aa1e6e95f1390b0c236645e03f3576d source_path: channels/matrix.md workflow: 15 --- # Matrix -Matrix é um Plugin de canal incluído no OpenClaw. +Matrix é um Plugin de canal empacotado para o OpenClaw. Ele usa o `matrix-js-sdk` oficial e oferece suporte a DMs, salas, threads, mídia, reações, enquetes, localização e E2EE. -## Plugin incluído +## Plugin empacotado -O Matrix é distribuído como um Plugin incluído nas versões atuais do OpenClaw, então compilações empacotadas normais não precisam de uma instalação separada. +O Matrix é distribuído como um Plugin empacotado nas versões atuais do OpenClaw, então compilações empacotadas normais não precisam de uma instalação separada. -Se você estiver em uma compilação mais antiga ou em uma instalação personalizada que exclua o Matrix, instale-o manualmente: +Se você estiver em uma compilação mais antiga ou em uma instalação personalizada que exclui o Matrix, instale-o manualmente: -Instale pelo npm: +Instalar a partir do npm: ```bash openclaw plugins install @openclaw/matrix ``` -Instale a partir de um checkout local: +Instalar a partir de um checkout local: ```bash openclaw plugins install ./path/to/local/matrix-plugin @@ -40,7 +40,7 @@ Consulte [Plugins](/pt-BR/tools/plugin) para ver o comportamento dos plugins e a ## Configuração inicial -1. Verifique se o Plugin Matrix está disponível. +1. Certifique-se de que o Plugin Matrix esteja disponível. - As versões empacotadas atuais do OpenClaw já o incluem. - Instalações antigas/personalizadas podem adicioná-lo manualmente com os comandos acima. 2. Crie uma conta Matrix no seu homeserver. @@ -63,30 +63,30 @@ O assistente do Matrix solicita: - URL do homeserver - método de autenticação: token de acesso ou senha - ID do usuário (somente autenticação por senha) -- nome do dispositivo opcional +- nome opcional do dispositivo - se deve ativar E2EE -- se deve configurar acesso a salas e entrada automática por convite +- se deve configurar acesso à sala e entrada automática em convites -Comportamentos principais do assistente: +Principais comportamentos do assistente: -- Se as variáveis de ambiente de autenticação do Matrix já existirem e essa conta ainda não tiver autenticação salva na configuração, o assistente oferece um atalho de ambiente para manter a autenticação em variáveis de ambiente. +- Se as variáveis de ambiente de autenticação do Matrix já existirem e essa conta ainda não tiver autenticação salva na configuração, o assistente oferece um atalho de env para manter a autenticação nas variáveis de ambiente. - Os nomes das contas são normalizados para o ID da conta. Por exemplo, `Ops Bot` se torna `ops-bot`. -- Entradas de lista de permissões de DM aceitam `@user:server` diretamente; nomes de exibição só funcionam quando a busca em diretório ao vivo encontra uma correspondência exata. -- Entradas de lista de permissões de sala aceitam IDs de sala e aliases diretamente. Prefira `!room:server` ou `#alias:server`; nomes não resolvidos são ignorados em tempo de execução pela resolução da lista de permissões. -- No modo de lista de permissões para entrada automática por convite, use apenas destinos de convite estáveis: `!roomId:server`, `#alias:server` ou `*`. Nomes simples de salas são rejeitados. -- Para resolver nomes de salas antes de salvar, use `openclaw channels resolve --channel matrix "Project Room"`. +- Entradas da allowlist de DM aceitam `@user:server` diretamente; nomes de exibição só funcionam quando a busca ao vivo no diretório encontra uma correspondência exata. +- Entradas da allowlist de sala aceitam IDs e aliases de sala diretamente. Prefira `!room:server` ou `#alias:server`; nomes não resolvidos são ignorados em tempo de execução pela resolução da allowlist. +- No modo de allowlist para entrada automática em convites, use apenas destinos de convite estáveis: `!roomId:server`, `#alias:server` ou `*`. Nomes simples de sala são rejeitados. +- Para resolver nomes de sala antes de salvar, use `openclaw channels resolve --channel matrix "Project Room"`. -`channels.matrix.autoJoin` tem o padrão `off`. +`channels.matrix.autoJoin` tem como padrão `off`. -Se você deixá-lo sem definir, o bot não entrará em salas convidadas nem em convites novos no estilo DM, então ele não aparecerá em novos grupos nem em DMs por convite, a menos que você entre manualmente primeiro. +Se você deixá-lo sem definir, o bot não entrará em salas convidadas nem em convites novos no estilo DM, então ele não aparecerá em novos grupos ou DMs convidadas, a menos que você entre manualmente primeiro. Defina `autoJoin: "allowlist"` junto com `autoJoinAllowlist` para restringir quais convites ele aceita, ou defina `autoJoin: "always"` se quiser que ele entre em todos os convites. No modo `allowlist`, `autoJoinAllowlist` aceita apenas `!roomId:server`, `#alias:server` ou `*`. -Exemplo de lista de permissões: +Exemplo de allowlist: ```json5 { @@ -149,7 +149,7 @@ Configuração baseada em senha (o token é armazenado em cache após o login): O Matrix armazena credenciais em cache em `~/.openclaw/credentials/matrix/`. A conta padrão usa `credentials.json`; contas nomeadas usam `credentials-.json`. -Quando existem credenciais em cache nesse local, o OpenClaw trata o Matrix como configurado para configuração inicial, doctor e detecção de status do canal, mesmo que a autenticação atual não esteja definida diretamente na configuração. +Quando existem credenciais em cache ali, o OpenClaw trata o Matrix como configurado para configuração inicial, doctor e descoberta de status do canal, mesmo que a autenticação atual não esteja definida diretamente na configuração. Equivalentes em variáveis de ambiente (usados quando a chave de configuração não está definida): @@ -160,7 +160,7 @@ Equivalentes em variáveis de ambiente (usados quando a chave de configuração - `MATRIX_DEVICE_ID` - `MATRIX_DEVICE_NAME` -Para contas não padrão, use variáveis de ambiente com escopo por conta: +Para contas não padrão, use variáveis de ambiente com escopo de conta: - `MATRIX__HOMESERVER` - `MATRIX__ACCESS_TOKEN` @@ -179,14 +179,14 @@ Para o ID de conta normalizado `ops-bot`, use: - `MATRIX_OPS_X2D_BOT_HOMESERVER` - `MATRIX_OPS_X2D_BOT_ACCESS_TOKEN` -O Matrix escapa a pontuação nos IDs de conta para manter as variáveis de ambiente com escopo livres de colisão. -Por exemplo, `-` se torna `_X2D_`, então `ops-prod` é mapeado para `MATRIX_OPS_X2D_PROD_*`. +O Matrix escapa a pontuação nos IDs de conta para manter variáveis de ambiente com escopo sem colisões. +Por exemplo, `-` se torna `_X2D_`, então `ops-prod` mapeia para `MATRIX_OPS_X2D_PROD_*`. O assistente interativo só oferece o atalho de variável de ambiente quando essas variáveis de autenticação já estão presentes e a conta selecionada ainda não tem autenticação do Matrix salva na configuração. ## Exemplo de configuração -Esta é uma configuração base prática com pareamento de DM, lista de permissões de sala e E2EE ativado: +Esta é uma configuração base prática com emparelhamento de DM, allowlist de sala e E2EE ativado: ```json5 { @@ -225,9 +225,9 @@ Esta é uma configuração base prática com pareamento de DM, lista de permiss ## Prévias de streaming -O streaming de respostas do Matrix é opcional. +O streaming de respostas do Matrix é opt-in. -Defina `channels.matrix.streaming` como `"partial"` quando quiser que o OpenClaw envie uma única resposta de prévia ao vivo, edite essa prévia no mesmo lugar enquanto o modelo gera texto e depois a finalize quando a resposta terminar: +Defina `channels.matrix.streaming` como `"partial"` quando quiser que o OpenClaw envie uma única resposta de prévia ao vivo, edite essa prévia no mesmo lugar enquanto o modelo gera texto e depois a finalize quando a resposta estiver pronta: ```json5 { @@ -240,34 +240,34 @@ Defina `channels.matrix.streaming` como `"partial"` quando quiser que o OpenClaw ``` - `streaming: "off"` é o padrão. O OpenClaw espera a resposta final e a envia uma única vez. -- `streaming: "partial"` cria uma mensagem de prévia editável para o bloco atual do assistente usando mensagens de texto normais do Matrix. Isso preserva o comportamento legado de notificação baseado na primeira prévia do Matrix, então clientes padrão podem notificar com o primeiro texto transmitido em streaming em vez do bloco concluído. -- `streaming: "quiet"` cria uma prévia silenciosa editável para o bloco atual do assistente. Use isso apenas quando você também configurar regras de push do destinatário para edições de prévia finalizadas. -- `blockStreaming: true` ativa mensagens de progresso separadas do Matrix. Com o streaming de prévia ativado, o Matrix mantém o rascunho ao vivo do bloco atual e preserva os blocos concluídos como mensagens separadas. +- `streaming: "partial"` cria uma mensagem de prévia editável para o bloco atual do assistente usando mensagens de texto normais do Matrix. Isso preserva o comportamento legado do Matrix de notificação na primeira prévia, então clientes padrão podem notificar com base no primeiro texto transmitido em streaming em vez do bloco concluído. +- `streaming: "quiet"` cria uma prévia editável silenciosa para o bloco atual do assistente. Use isso apenas quando você também configurar regras de push do destinatário para edições de prévia finalizadas. +- `blockStreaming: true` ativa mensagens separadas de progresso do Matrix. Com o streaming de prévia ativado, o Matrix mantém o rascunho ao vivo para o bloco atual e preserva blocos concluídos como mensagens separadas. - Quando o streaming de prévia está ativado e `blockStreaming` está desativado, o Matrix edita o rascunho ao vivo no mesmo lugar e finaliza esse mesmo evento quando o bloco ou o turno termina. -- Se a prévia não couber mais em um único evento do Matrix, o OpenClaw interrompe o streaming de prévia e volta à entrega final normal. -- Respostas com mídia ainda enviam anexos normalmente. Se uma prévia antiga não puder mais ser reutilizada com segurança, o OpenClaw a remove antes de enviar a resposta final com mídia. +- Se a prévia não couber mais em um único evento do Matrix, o OpenClaw interrompe o streaming de prévia e volta para a entrega final normal. +- Respostas com mídia ainda enviam anexos normalmente. Se uma prévia antiga não puder mais ser reutilizada com segurança, o OpenClaw a redige antes de enviar a resposta final com mídia. - Edições de prévia geram chamadas extras à API do Matrix. Deixe o streaming desativado se quiser o comportamento mais conservador em relação a limite de taxa. `blockStreaming` não ativa prévias em rascunho por si só. -Use `streaming: "partial"` ou `streaming: "quiet"` para edições de prévia; depois adicione `blockStreaming: true` somente se você também quiser que os blocos concluídos do assistente permaneçam visíveis como mensagens de progresso separadas. +Use `streaming: "partial"` ou `streaming: "quiet"` para edições de prévia; depois adicione `blockStreaming: true` apenas se também quiser que os blocos concluídos do assistente permaneçam visíveis como mensagens de progresso separadas. -Se você precisar de notificações padrão do Matrix sem regras de push personalizadas, use `streaming: "partial"` para o comportamento baseado na primeira prévia ou deixe `streaming` desativado para entrega somente final. Com `streaming: "off"`: +Se você precisar de notificações padrão do Matrix sem regras de push personalizadas, use `streaming: "partial"` para o comportamento de prévia primeiro ou deixe `streaming` desativado para entrega somente final. Com `streaming: "off"`: -- `blockStreaming: true` envia cada bloco concluído como uma mensagem normal notificável do Matrix. -- `blockStreaming: false` envia apenas a resposta final concluída como uma mensagem normal notificável do Matrix. +- `blockStreaming: true` envia cada bloco concluído como uma mensagem normal do Matrix com notificação. +- `blockStreaming: false` envia apenas a resposta final concluída como uma mensagem normal do Matrix com notificação. ### Regras de push auto-hospedadas para prévias silenciosas finalizadas -Se você executa sua própria infraestrutura Matrix e quer que prévias silenciosas notifiquem apenas quando um bloco ou resposta final for concluído, defina `streaming: "quiet"` e adicione uma regra de push por usuário para edições de prévia finalizadas. +Se você executa sua própria infraestrutura Matrix e quer que prévias silenciosas notifiquem apenas quando um bloco ou a resposta final estiver concluída, defina `streaming: "quiet"` e adicione uma regra de push por usuário para edições de prévia finalizadas. -Normalmente isso é uma configuração do usuário destinatário, não uma alteração de configuração global do homeserver: +Normalmente isso é uma configuração do usuário destinatário, não uma alteração global de configuração do homeserver: Mapa rápido antes de começar: - usuário destinatário = a pessoa que deve receber a notificação -- usuário bot = a conta Matrix do OpenClaw que envia a resposta -- use o token de acesso do usuário destinatário nas chamadas de API abaixo -- faça a correspondência de `sender` na regra de push com o MXID completo do usuário bot +- usuário do bot = a conta Matrix do OpenClaw que envia a resposta +- use o token de acesso do usuário destinatário para as chamadas de API abaixo +- faça `sender` na regra de push corresponder ao MXID completo do usuário do bot 1. Configure o OpenClaw para usar prévias silenciosas: @@ -281,12 +281,12 @@ Mapa rápido antes de começar: } ``` -2. Certifique-se de que a conta destinatária já recebe notificações push normais do Matrix. As regras de prévia silenciosa só funcionam se esse usuário já tiver pushers/dispositivos funcionando. +2. Certifique-se de que a conta destinatária já receba notificações push normais do Matrix. Regras de prévia silenciosa só funcionam se esse usuário já tiver pushers/dispositivos funcionando. 3. Obtenha o token de acesso do usuário destinatário. - Use o token do usuário que recebe, não o token do bot. - - Reutilizar um token de sessão de cliente existente geralmente é a opção mais fácil. - - Se você precisar gerar um token novo, pode fazer login pela API Client-Server padrão do Matrix: + - Reutilizar um token de sessão de cliente existente geralmente é o mais fácil. + - Se precisar gerar um token novo, você pode fazer login pela API Client-Server padrão do Matrix: ```bash curl -sS -X POST \ @@ -310,7 +310,7 @@ curl -sS \ "https://matrix.example.org/_matrix/client/v3/pushers" ``` -Se isso retornar zero pushers/dispositivos ativos, corrija primeiro as notificações normais do Matrix antes de adicionar a regra do OpenClaw abaixo. +Se isso retornar sem pushers/dispositivos ativos, corrija primeiro as notificações normais do Matrix antes de adicionar a regra do OpenClaw abaixo. O OpenClaw marca edições finalizadas de prévia somente de texto com: @@ -352,21 +352,21 @@ curl -sS -X PUT \ Substitua estes valores antes de executar o comando: -- `https://matrix.example.org`: a URL base do seu homeserver -- `$USER_ACCESS_TOKEN`: o token de acesso do usuário que recebe -- `openclaw-finalized-preview-botname`: um ID de regra único para este bot para este usuário que recebe +- `https://matrix.example.org`: URL base do seu homeserver +- `$USER_ACCESS_TOKEN`: token de acesso do usuário que recebe +- `openclaw-finalized-preview-botname`: um ID de regra exclusivo para este bot para este usuário que recebe - `@bot:example.org`: o MXID do seu bot Matrix do OpenClaw, não o MXID do usuário que recebe Importante para configurações com vários bots: - As regras de push são indexadas por `ruleId`. Executar `PUT` novamente no mesmo ID de regra atualiza essa única regra. -- Se um mesmo usuário destinatário deve receber notificações de várias contas de bot Matrix do OpenClaw, crie uma regra por bot com um ID de regra único para cada correspondência de remetente. +- Se um usuário destinatário precisar notificar para várias contas de bot Matrix do OpenClaw, crie uma regra por bot com um ID de regra exclusivo para cada correspondência de remetente. - Um padrão simples é `openclaw-finalized-preview-`, como `openclaw-finalized-preview-ops` ou `openclaw-finalized-preview-support`. -A regra é avaliada com base no remetente do evento: +A regra é avaliada em relação ao remetente do evento: - autentique com o token do usuário destinatário -- faça a correspondência de `sender` com o MXID do bot OpenClaw +- faça `sender` corresponder ao MXID do bot OpenClaw 6. Verifique se a regra existe: @@ -376,7 +376,7 @@ curl -sS \ "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname" ``` -7. Teste uma resposta em streaming. No modo silencioso, a sala deve mostrar uma prévia de rascunho silenciosa, e a edição final no mesmo lugar deve enviar uma notificação quando o bloco ou turno terminar. +7. Teste uma resposta em streaming. No modo silencioso, a sala deve mostrar uma prévia de rascunho silenciosa e a edição final no mesmo lugar deve notificar quando o bloco ou turno terminar. Se você precisar remover a regra depois, exclua esse mesmo ID de regra com o token do usuário destinatário: @@ -389,8 +389,8 @@ curl -sS -X DELETE \ Observações: - Crie a regra com o token de acesso do usuário destinatário, não com o token do bot. -- Novas regras `override` definidas pelo usuário são inseridas antes das regras padrão de supressão, então nenhum parâmetro extra de ordenação é necessário. -- Isso afeta apenas edições de prévia somente de texto que o OpenClaw pode finalizar com segurança no mesmo lugar. Fallbacks de mídia e fallbacks de prévia obsoleta ainda usam a entrega normal do Matrix. +- Novas regras `override` definidas pelo usuário são inseridas antes das regras de supressão padrão, então nenhum parâmetro extra de ordenação é necessário. +- Isso afeta apenas edições de prévia somente de texto que o OpenClaw consegue finalizar com segurança no mesmo lugar. Fallbacks de mídia e fallbacks de prévia antiga ainda usam a entrega normal do Matrix. - Se `GET /_matrix/client/v3/pushers` não mostrar pushers, o usuário ainda não tem entrega de push do Matrix funcionando para essa conta/dispositivo. #### Synapse @@ -399,22 +399,22 @@ Para o Synapse, a configuração acima normalmente já é suficiente por si só: - Nenhuma alteração especial em `homeserver.yaml` é necessária para notificações de prévia finalizada do OpenClaw. - Se sua implantação do Synapse já envia notificações push normais do Matrix, o token do usuário + a chamada `pushrules` acima são a principal etapa de configuração. -- Se você executa o Synapse atrás de um proxy reverso ou workers, verifique se `/_matrix/client/.../pushrules/` chega corretamente ao Synapse. -- Se você executa workers do Synapse, verifique se os pushers estão saudáveis. A entrega de push é tratada pelo processo principal ou por `synapse.app.pusher` / workers de pusher configurados. +- Se você executa o Synapse atrás de um proxy reverso ou workers, certifique-se de que `/_matrix/client/.../pushrules/` chegue corretamente ao Synapse. +- Se você executa workers do Synapse, certifique-se de que os pushers estejam íntegros. A entrega de push é tratada pelo processo principal ou por `synapse.app.pusher` / workers de pusher configurados. #### Tuwunel -Para o Tuwunel, use o mesmo fluxo de configuração e a chamada de API `pushrules` mostrados acima: +Para o Tuwunel, use o mesmo fluxo de configuração e a mesma chamada de API `pushrules` mostrados acima: - Nenhuma configuração específica do Tuwunel é necessária para o próprio marcador de prévia finalizada. - Se as notificações normais do Matrix já funcionam para esse usuário, o token do usuário + a chamada `pushrules` acima são a principal etapa de configuração. -- Se as notificações parecerem desaparecer enquanto o usuário está ativo em outro dispositivo, verifique se `suppress_push_when_active` está ativado. O Tuwunel adicionou essa opção no Tuwunel 1.4.2 em 12 de setembro de 2025, e ela pode suprimir intencionalmente pushes para outros dispositivos enquanto um dispositivo está ativo. +- Se as notificações parecerem desaparecer enquanto o usuário estiver ativo em outro dispositivo, verifique se `suppress_push_when_active` está ativado. O Tuwunel adicionou essa opção no Tuwunel 1.4.2 em 12 de setembro de 2025, e ela pode suprimir intencionalmente pushes para outros dispositivos enquanto um dispositivo estiver ativo. ## Salas bot para bot -Por padrão, mensagens do Matrix vindas de outras contas Matrix do OpenClaw configuradas são ignoradas. +Por padrão, mensagens Matrix de outras contas Matrix configuradas do OpenClaw são ignoradas. -Use `allowBots` quando você quiser intencionalmente tráfego Matrix entre agentes: +Use `allowBots` quando você intencionalmente quiser tráfego Matrix entre agentes: ```json5 { @@ -432,18 +432,18 @@ Use `allowBots` quando você quiser intencionalmente tráfego Matrix entre agent ``` - `allowBots: true` aceita mensagens de outras contas de bot Matrix configuradas em salas e DMs permitidas. -- `allowBots: "mentions"` aceita essas mensagens apenas quando elas mencionam visivelmente este bot nas salas. DMs continuam permitidas. +- `allowBots: "mentions"` aceita essas mensagens apenas quando elas mencionam visivelmente este bot nas salas. DMs ainda são permitidas. - `groups..allowBots` substitui a configuração no nível da conta para uma sala. -- O OpenClaw ainda ignora mensagens do mesmo ID de usuário Matrix para evitar loops de autorresposta. +- O OpenClaw ainda ignora mensagens do mesmo ID de usuário Matrix para evitar loops de resposta a si mesmo. - O Matrix não expõe aqui um sinalizador nativo de bot; o OpenClaw trata "de autoria de bot" como "enviado por outra conta Matrix configurada neste Gateway OpenClaw". -Use listas de permissões de sala estritas e exigências de menção ao ativar tráfego bot para bot em salas compartilhadas. +Use allowlists rigorosas de sala e exigências de menção ao ativar tráfego bot para bot em salas compartilhadas. ## Criptografia e verificação -Em salas criptografadas (E2EE), eventos de imagem de saída usam `thumbnail_file` para que as prévias de imagem sejam criptografadas junto com o anexo completo. Salas não criptografadas continuam usando `thumbnail_url` simples. Nenhuma configuração é necessária — o Plugin detecta automaticamente o estado de E2EE. +Em salas criptografadas (E2EE), eventos de imagem de saída usam `thumbnail_file`, para que as prévias de imagem sejam criptografadas junto com o anexo completo. Salas não criptografadas ainda usam `thumbnail_url` simples. Nenhuma configuração é necessária — o Plugin detecta automaticamente o estado de E2EE. -Ativar criptografia: +Ative a criptografia: ```json5 { @@ -459,43 +459,43 @@ Ativar criptografia: } ``` -Verificar o status da verificação: +Verifique o status da verificação: ```bash openclaw matrix verify status ``` -Status detalhado (diagnósticos completos): +Status detalhado (diagnóstico completo): ```bash openclaw matrix verify status --verbose ``` -Incluir a chave de recuperação armazenada na saída legível por máquina: +Inclua a chave de recuperação armazenada na saída legível por máquina: ```bash openclaw matrix verify status --include-recovery-key --json ``` -Inicializar o estado de cross-signing e verificação: +Inicialize o estado de assinatura cruzada e verificação: ```bash openclaw matrix verify bootstrap ``` -Diagnósticos detalhados de bootstrap: +Diagnóstico detalhado da inicialização: ```bash openclaw matrix verify bootstrap --verbose ``` -Forçar uma redefinição nova da identidade de cross-signing antes do bootstrap: +Force uma redefinição nova da identidade de assinatura cruzada antes da inicialização: ```bash openclaw matrix verify bootstrap --force-reset-cross-signing ``` -Verificar este dispositivo com uma chave de recuperação: +Verifique este dispositivo com uma chave de recuperação: ```bash openclaw matrix verify device "" @@ -507,41 +507,41 @@ Detalhes detalhados da verificação do dispositivo: openclaw matrix verify device "" --verbose ``` -Verificar a integridade do backup de chaves de sala: +Verifique a integridade do backup de chaves de sala: ```bash openclaw matrix verify backup status ``` -Diagnósticos detalhados da integridade do backup: +Diagnóstico detalhado da integridade do backup: ```bash openclaw matrix verify backup status --verbose ``` -Restaurar chaves de sala do backup no servidor: +Restaure chaves de sala do backup do servidor: ```bash openclaw matrix verify backup restore ``` -Diagnósticos detalhados da restauração: +Diagnóstico detalhado da restauração: ```bash openclaw matrix verify backup restore --verbose ``` -Excluir o backup atual do servidor e criar uma nova base de backup. Se a chave de backup armazenada não puder ser carregada corretamente, essa redefinição também poderá recriar o armazenamento de segredos para que futuras inicializações a frio consigam carregar a nova chave de backup: +Exclua o backup atual do servidor e crie uma nova base de backup. Se a chave de backup armazenada não puder ser carregada corretamente, essa redefinição também pode recriar o armazenamento secreto para que futuras inicializações a frio consigam carregar a nova chave de backup: ```bash openclaw matrix verify backup reset --yes ``` -Todos os comandos `verify` são concisos por padrão (incluindo logs internos silenciosos do SDK) e só mostram diagnósticos detalhados com `--verbose`. +Todos os comandos `verify` são concisos por padrão (incluindo logging interno silencioso do SDK) e mostram diagnósticos detalhados apenas com `--verbose`. Use `--json` para saída completa legível por máquina ao criar scripts. -Em configurações com várias contas, os comandos CLI do Matrix usam a conta padrão implícita do Matrix, a menos que você passe `--account `. -Se você configurar várias contas nomeadas, defina primeiro `channels.matrix.defaultAccount`, ou essas operações implícitas da CLI vão parar e pedir que você escolha uma conta explicitamente. +Em configurações com várias contas, os comandos Matrix da CLI usam a conta padrão implícita do Matrix, a menos que você passe `--account `. +Se você configurar várias contas nomeadas, defina primeiro `channels.matrix.defaultAccount` ou essas operações implícitas da CLI irão parar e pedir que você escolha uma conta explicitamente. Use `--account` sempre que quiser que operações de verificação ou de dispositivo tenham como alvo explicitamente uma conta nomeada: ```bash @@ -550,40 +550,40 @@ openclaw matrix verify backup restore --account assistant openclaw matrix devices list --account assistant ``` -Quando a criptografia está desativada ou indisponível para uma conta nomeada, avisos do Matrix e erros de verificação apontam para a chave de configuração dessa conta, por exemplo `channels.matrix.accounts.assistant.encryption`. +Quando a criptografia estiver desativada ou indisponível para uma conta nomeada, avisos do Matrix e erros de verificação apontam para a chave de configuração dessa conta, por exemplo `channels.matrix.accounts.assistant.encryption`. ### O que "verificado" significa -O OpenClaw trata este dispositivo Matrix como verificado apenas quando ele é verificado pela sua própria identidade de cross-signing. +O OpenClaw trata este dispositivo Matrix como verificado somente quando ele é verificado pela sua própria identidade de assinatura cruzada. Na prática, `openclaw matrix verify status --verbose` expõe três sinais de confiança: - `Locally trusted`: este dispositivo é confiável apenas pelo cliente atual -- `Cross-signing verified`: o SDK informa que o dispositivo está verificado por cross-signing -- `Signed by owner`: o dispositivo é assinado pela sua própria chave de self-signing +- `Cross-signing verified`: o SDK informa o dispositivo como verificado por assinatura cruzada +- `Signed by owner`: o dispositivo é assinado pela sua própria chave de autoassinatura -`Verified by owner` só se torna `yes` quando há verificação por cross-signing ou assinatura pelo proprietário. -A confiança local, por si só, não é suficiente para o OpenClaw tratar o dispositivo como totalmente verificado. +`Verified by owner` passa a ser `yes` somente quando há verificação por assinatura cruzada ou assinatura do proprietário. +A confiança local por si só não basta para que o OpenClaw trate o dispositivo como totalmente verificado. -### O que o bootstrap faz +### O que a inicialização faz `openclaw matrix verify bootstrap` é o comando de reparo e configuração para contas Matrix criptografadas. -Ele faz tudo o seguinte, nesta ordem: +Ele faz tudo o que segue, nesta ordem: -- inicializa o armazenamento de segredos, reutilizando uma chave de recuperação existente quando possível -- inicializa o cross-signing e envia as chaves públicas de cross-signing ausentes -- tenta marcar e assinar por cross-signing o dispositivo atual -- cria um novo backup de chaves de sala no lado do servidor, se ainda não existir um +- inicializa o armazenamento secreto, reutilizando uma chave de recuperação existente quando possível +- inicializa a assinatura cruzada e envia chaves públicas de assinatura cruzada ausentes +- tenta marcar e assinar de forma cruzada o dispositivo atual +- cria um novo backup de chaves de sala no servidor se ainda não existir um -Se o homeserver exigir autenticação interativa para enviar chaves de cross-signing, o OpenClaw tenta o envio primeiro sem autenticação, depois com `m.login.dummy`, e depois com `m.login.password` quando `channels.matrix.password` está configurado. +Se o homeserver exigir autenticação interativa para enviar chaves de assinatura cruzada, o OpenClaw tenta o envio primeiro sem autenticação, depois com `m.login.dummy` e depois com `m.login.password` quando `channels.matrix.password` está configurado. -Use `--force-reset-cross-signing` apenas quando você quiser intencionalmente descartar a identidade atual de cross-signing e criar uma nova. +Use `--force-reset-cross-signing` somente quando você intencionalmente quiser descartar a identidade atual de assinatura cruzada e criar uma nova. -Se você quiser intencionalmente descartar o backup atual de chaves de sala e iniciar uma nova base de backup para mensagens futuras, use `openclaw matrix verify backup reset --yes`. -Faça isso apenas se aceitar que o histórico criptografado antigo irrecuperável continuará indisponível e que o OpenClaw pode recriar o armazenamento de segredos se o segredo atual de backup não puder ser carregado com segurança. +Se você intencionalmente quiser descartar o backup atual de chaves de sala e iniciar uma nova base de backup para mensagens futuras, use `openclaw matrix verify backup reset --yes`. +Faça isso apenas se aceitar que o histórico criptografado antigo irrecuperável continuará indisponível e que o OpenClaw pode recriar o armazenamento secreto se o segredo de backup atual não puder ser carregado com segurança. ### Nova base de backup -Se você quiser manter o funcionamento das futuras mensagens criptografadas e aceitar perder o histórico antigo irrecuperável, execute estes comandos em ordem: +Se você quiser manter o funcionamento de futuras mensagens criptografadas e aceitar perder histórico antigo irrecuperável, execute estes comandos na ordem: ```bash openclaw matrix verify backup reset --yes @@ -591,20 +591,21 @@ openclaw matrix verify backup status --verbose openclaw matrix verify status ``` -Adicione `--account ` a cada comando quando quiser direcionar explicitamente uma conta Matrix nomeada. +Adicione `--account ` a cada comando quando quiser ter como alvo explicitamente uma conta Matrix nomeada. ### Comportamento na inicialização Quando `encryption: true`, o Matrix define `startupVerification` como `"if-unverified"` por padrão. Na inicialização, se este dispositivo ainda não estiver verificado, o Matrix solicitará autoverificação em outro cliente Matrix, ignorará solicitações duplicadas enquanto uma já estiver pendente e aplicará um cooldown local antes de tentar novamente após reinicializações. -Tentativas de solicitação com falha tentam novamente mais cedo do que a criação bem-sucedida da solicitação por padrão. -Defina `startupVerification: "off"` para desativar solicitações automáticas na inicialização, ou ajuste `startupVerificationCooldownHours` se quiser uma janela de nova tentativa mais curta ou mais longa. +Tentativas de solicitação com falha são repetidas mais cedo do que a criação bem-sucedida de solicitações por padrão. +Defina `startupVerification: "off"` para desativar solicitações automáticas na inicialização ou ajuste `startupVerificationCooldownHours` se quiser uma janela de nova tentativa menor ou maior. A inicialização também executa automaticamente uma passagem conservadora de bootstrap de criptografia. -Essa passagem tenta reutilizar primeiro o armazenamento de segredos e a identidade de cross-signing atuais, e evita redefinir o cross-signing, a menos que você execute um fluxo explícito de reparo de bootstrap. +Essa passagem tenta reutilizar primeiro o armazenamento secreto atual e a identidade atual de assinatura cruzada, e evita redefinir a assinatura cruzada a menos que você execute um fluxo explícito de reparo de bootstrap. -Se a inicialização encontrar um estado de bootstrap quebrado e `channels.matrix.password` estiver configurado, o OpenClaw poderá tentar um caminho de reparo mais rigoroso. -Se o dispositivo atual já estiver assinado pelo proprietário, o OpenClaw preservará essa identidade em vez de redefini-la automaticamente. +Se a inicialização ainda encontrar um estado de bootstrap corrompido, o OpenClaw poderá tentar um caminho de reparo protegido mesmo quando `channels.matrix.password` não estiver configurado. +Se o homeserver exigir UIA baseada em senha para esse reparo, o OpenClaw registra um aviso e mantém a inicialização não fatal em vez de abortar o bot. +Se o dispositivo atual já estiver assinado pelo proprietário, o OpenClaw preserva essa identidade em vez de redefini-la automaticamente. Consulte [migração do Matrix](/pt-BR/install/migrating-matrix) para ver o fluxo completo de upgrade, limites, comandos de recuperação e mensagens comuns de migração. @@ -614,18 +615,18 @@ O Matrix publica avisos do ciclo de vida da verificação diretamente na DM estr Isso inclui: - avisos de solicitação de verificação -- avisos de verificação pronta (com orientação explícita "Verifique por emoji") +- avisos de verificação pronta (com orientação explícita "Verificar por emoji") - avisos de início e conclusão da verificação -- detalhes SAS (emoji e decimal), quando disponíveis +- detalhes de SAS (emoji e decimal) quando disponíveis Solicitações de verificação recebidas de outro cliente Matrix são rastreadas e aceitas automaticamente pelo OpenClaw. -Para fluxos de autoverificação, o OpenClaw também inicia automaticamente o fluxo SAS quando a verificação por emoji fica disponível e confirma o próprio lado. +Para fluxos de autoverificação, o OpenClaw também inicia automaticamente o fluxo SAS quando a verificação por emoji se torna disponível e confirma seu próprio lado. Para solicitações de verificação de outro usuário/dispositivo Matrix, o OpenClaw aceita automaticamente a solicitação e então espera que o fluxo SAS prossiga normalmente. -Ainda assim, você precisa comparar o SAS em emoji ou decimal no seu cliente Matrix e confirmar "They match" lá para concluir a verificação. +Você ainda precisa comparar o SAS em emoji ou decimal no seu cliente Matrix e confirmar "They match" lá para concluir a verificação. -O OpenClaw não aceita automaticamente de forma cega fluxos duplicados iniciados por ele mesmo. Na inicialização, ele não cria uma nova solicitação quando uma solicitação de autoverificação já está pendente. +O OpenClaw não aceita automaticamente fluxos duplicados iniciados por ele mesmo às cegas. A inicialização ignora a criação de uma nova solicitação quando uma solicitação de autoverificação já está pendente. -Avisos de protocolo/sistema de verificação não são encaminhados para o pipeline de chat do agente, então eles não produzem `NO_REPLY`. +Avisos de verificação de protocolo/sistema não são encaminhados para o pipeline de chat do agente, então eles não produzem `NO_REPLY`. ### Higiene de dispositivos @@ -642,18 +643,18 @@ Remova dispositivos antigos gerenciados pelo OpenClaw com: openclaw matrix devices prune-stale ``` -### Armazenamento criptográfico +### Armazenamento de criptografia -O E2EE do Matrix usa o caminho de criptografia Rust oficial do `matrix-js-sdk` no Node, com `fake-indexeddb` como shim do IndexedDB. O estado criptográfico é persistido em um arquivo de snapshot (`crypto-idb-snapshot.json`) e restaurado na inicialização. O arquivo de snapshot é um estado de execução sensível armazenado com permissões restritivas de arquivo. +A E2EE do Matrix usa o caminho de criptografia Rust oficial do `matrix-js-sdk` no Node, com `fake-indexeddb` como shim de IndexedDB. O estado criptográfico é persistido em um arquivo de snapshot (`crypto-idb-snapshot.json`) e restaurado na inicialização. O arquivo de snapshot é um estado de runtime sensível armazenado com permissões restritivas de arquivo. -O estado criptografado em execução fica em raízes por conta, por usuário e por hash de token em +O estado criptografado de runtime fica em raízes por conta, por usuário e por hash de token em `~/.openclaw/matrix/accounts//__//`. -Esse diretório contém o armazenamento de sincronização (`bot-storage.json`), armazenamento criptográfico (`crypto/`), +Esse diretório contém o armazenamento de sincronização (`bot-storage.json`), armazenamento de criptografia (`crypto/`), arquivo de chave de recuperação (`recovery-key.json`), snapshot do IndexedDB (`crypto-idb-snapshot.json`), -vínculos de thread (`thread-bindings.json`) e estado de verificação na inicialização (`startup-verification.json`). +bindings de thread (`thread-bindings.json`) e estado de verificação na inicialização (`startup-verification.json`). Quando o token muda, mas a identidade da conta permanece a mesma, o OpenClaw reutiliza a melhor raiz existente -para essa tupla conta/homeserver/usuário para que o estado anterior de sincronização, estado criptográfico, vínculos de thread -e estado de verificação na inicialização continuem visíveis. +para essa tupla de conta/homeserver/usuário, para que o estado anterior de sincronização, o estado criptográfico, os bindings de thread +e o estado de verificação na inicialização permaneçam visíveis. ## Gerenciamento de perfil @@ -664,47 +665,47 @@ openclaw matrix profile set --name "OpenClaw Assistant" openclaw matrix profile set --avatar-url https://cdn.example.org/avatar.png ``` -Adicione `--account ` quando quiser direcionar explicitamente uma conta Matrix nomeada. +Adicione `--account ` quando quiser ter como alvo explicitamente uma conta Matrix nomeada. -O Matrix aceita URLs de avatar `mxc://` diretamente. Quando você passa uma URL de avatar `http://` ou `https://`, o OpenClaw primeiro a envia para o Matrix e armazena a URL `mxc://` resolvida de volta em `channels.matrix.avatarUrl` (ou na substituição da conta selecionada). +O Matrix aceita URLs de avatar `mxc://` diretamente. Quando você passa uma URL de avatar `http://` ou `https://`, o OpenClaw primeiro faz upload dela para o Matrix e armazena a URL `mxc://` resolvida de volta em `channels.matrix.avatarUrl` (ou na substituição da conta selecionada). ## Threads -O Matrix oferece suporte a threads nativas do Matrix tanto para respostas automáticas quanto para envios da ferramenta de mensagem. +O Matrix oferece suporte a threads nativas do Matrix tanto para respostas automáticas quanto para envios da ferramenta de mensagens. -- `dm.sessionScope: "per-user"` (padrão) mantém o roteamento de DM do Matrix com escopo por remetente, para que várias salas de DM possam compartilhar uma sessão quando forem resolvidas para o mesmo par. -- `dm.sessionScope: "per-room"` isola cada sala de DM do Matrix em sua própria chave de sessão, ainda usando autenticação e verificações de lista de permissões normais de DM. -- Vínculos explícitos de conversa do Matrix ainda têm precedência sobre `dm.sessionScope`, então salas e threads vinculadas mantêm a sessão de destino escolhida. -- `threadReplies: "off"` mantém as respostas no nível superior e mantém as mensagens encadeadas de entrada na sessão pai. +- `dm.sessionScope: "per-user"` (padrão) mantém o roteamento de DM do Matrix com escopo por remetente, então várias salas de DM podem compartilhar uma sessão quando são resolvidas para o mesmo par. +- `dm.sessionScope: "per-room"` isola cada sala de DM do Matrix em sua própria chave de sessão enquanto ainda usa verificações normais de autenticação e allowlist de DM. +- Bindings explícitos de conversa do Matrix ainda têm prioridade sobre `dm.sessionScope`, então salas e threads vinculadas mantêm a sessão de destino escolhida. +- `threadReplies: "off"` mantém respostas no nível superior e mantém mensagens de thread recebidas na sessão pai. - `threadReplies: "inbound"` responde dentro de uma thread apenas quando a mensagem recebida já estava nessa thread. -- `threadReplies: "always"` mantém respostas de sala em uma thread enraizada na mensagem que acionou a resposta e roteia essa conversa pela sessão com escopo de thread correspondente a partir da primeira mensagem acionadora. -- `dm.threadReplies` substitui a configuração de nível superior apenas para DMs. Por exemplo, você pode manter threads de sala isoladas enquanto mantém DMs sem threads. -- Mensagens encadeadas recebidas incluem a mensagem raiz da thread como contexto extra do agente. -- Envios da ferramenta de mensagem herdam automaticamente a thread atual do Matrix quando o destino é a mesma sala, ou o mesmo destino de usuário em DM, a menos que um `threadId` explícito seja fornecido. -- A reutilização do mesmo destino de usuário em DM na mesma sessão só entra em ação quando os metadados da sessão atual comprovam o mesmo par de DM na mesma conta Matrix; caso contrário, o OpenClaw recorre ao roteamento normal com escopo por usuário. -- Quando o OpenClaw detecta que uma sala de DM do Matrix colide com outra sala de DM na mesma sessão compartilhada de DM do Matrix, ele publica um único `m.notice` nessa sala com a rota de escape `/focus` quando os vínculos de thread estão ativados e a dica `dm.sessionScope`. -- Vínculos de thread em execução são suportados para o Matrix. `/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` e `/acp spawn` vinculado a thread funcionam em salas e DMs do Matrix. -- `/focus` no nível superior de sala/DM do Matrix cria uma nova thread do Matrix e a vincula à sessão de destino quando `threadBindings.spawnSubagentSessions=true`. -- Executar `/focus` ou `/acp spawn --thread here` dentro de uma thread existente do Matrix vincula essa thread atual no lugar. +- `threadReplies: "always"` mantém respostas de sala em uma thread enraizada na mensagem que disparou e roteia essa conversa pela sessão com escopo de thread correspondente desde a primeira mensagem disparadora. +- `dm.threadReplies` substitui a configuração de nível superior apenas para DMs. Por exemplo, você pode manter threads de sala isoladas enquanto mantém DMs sem thread. +- Mensagens de thread recebidas incluem a mensagem raiz da thread como contexto adicional do agente. +- Envios da ferramenta de mensagens herdam automaticamente a thread atual do Matrix quando o destino é a mesma sala ou o mesmo destino de usuário de DM, a menos que um `threadId` explícito seja fornecido. +- A reutilização do destino de usuário de DM da mesma sessão só entra em ação quando os metadados da sessão atual comprovam o mesmo par de DM na mesma conta Matrix; caso contrário, o OpenClaw volta ao roteamento normal com escopo por usuário. +- Quando o OpenClaw detecta que uma sala de DM do Matrix colide com outra sala de DM na mesma sessão compartilhada de DM do Matrix, ele publica um `m.notice` único nessa sala com a rota de escape `/focus` quando bindings de thread estão ativados e com a dica `dm.sessionScope`. +- Bindings de thread em runtime são compatíveis com Matrix. `/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` e `/acp spawn` vinculado a thread funcionam em salas e DMs do Matrix. +- `/focus` de sala/DM do Matrix no nível superior cria uma nova thread do Matrix e a vincula à sessão de destino quando `threadBindings.spawnSubagentSessions=true`. +- Executar `/focus` ou `/acp spawn --thread here` dentro de uma thread existente do Matrix vincula essa thread atual em vez disso. -## Vínculos de conversa ACP +## Bindings de conversa ACP -Salas, DMs e threads existentes do Matrix podem ser transformadas em espaços de trabalho ACP duráveis sem mudar a superfície do chat. +Salas, DMs e threads Matrix existentes podem ser transformadas em workspaces ACP duráveis sem mudar a superfície de chat. -Fluxo rápido para operador: +Fluxo rápido do operador: - Execute `/acp spawn codex --bind here` dentro da DM, sala ou thread existente do Matrix que você quer continuar usando. -- Em uma DM ou sala Matrix de nível superior, a DM/sala atual continua sendo a superfície do chat e as mensagens futuras são roteadas para a sessão ACP criada. -- Dentro de uma thread existente do Matrix, `--bind here` vincula essa thread atual no lugar. -- `/new` e `/reset` redefinem a mesma sessão ACP vinculada no lugar. -- `/acp close` fecha a sessão ACP e remove o vínculo. +- Em uma DM ou sala Matrix de nível superior, a DM/sala atual continua sendo a superfície de chat e mensagens futuras são roteadas para a sessão ACP criada. +- Dentro de uma thread Matrix existente, `--bind here` vincula essa thread atual no mesmo lugar. +- `/new` e `/reset` redefinem a mesma sessão ACP vinculada no mesmo lugar. +- `/acp close` fecha a sessão ACP e remove o binding. Observações: - `--bind here` não cria uma thread filha do Matrix. - `threadBindings.spawnAcpSessions` só é necessário para `/acp spawn --thread auto|here`, quando o OpenClaw precisa criar ou vincular uma thread filha do Matrix. -### Configuração de vínculo de thread +### Configuração de binding de thread O Matrix herda padrões globais de `session.threadBindings` e também oferece suporte a substituições por canal: @@ -714,29 +715,29 @@ O Matrix herda padrões globais de `session.threadBindings` e também oferece su - `threadBindings.spawnSubagentSessions` - `threadBindings.spawnAcpSessions` -Os sinalizadores de criação vinculada a thread do Matrix são opt-in: +Sinalizadores de criação vinculada a thread do Matrix são opt-in: -- Defina `threadBindings.spawnSubagentSessions: true` para permitir que `/focus` no nível superior crie e vincule novas threads do Matrix. +- Defina `threadBindings.spawnSubagentSessions: true` para permitir que `/focus` de nível superior crie e vincule novas threads do Matrix. - Defina `threadBindings.spawnAcpSessions: true` para permitir que `/acp spawn --thread auto|here` vincule sessões ACP a threads do Matrix. ## Reações O Matrix oferece suporte a ações de reação de saída, notificações de reação de entrada e reações de confirmação de entrada. -- A ferramenta de reação de saída é controlada por `channels["matrix"].actions.reactions`. +- O ferramental de reação de saída é controlado por `channels["matrix"].actions.reactions`. - `react` adiciona uma reação a um evento específico do Matrix. -- `reactions` lista o resumo atual de reações de um evento específico do Matrix. +- `reactions` lista o resumo atual de reações para um evento específico do Matrix. - `emoji=""` remove as próprias reações da conta do bot nesse evento. - `remove: true` remove apenas a reação de emoji especificada da conta do bot. -O escopo das reações de confirmação é resolvido nesta ordem: +O escopo de reação de confirmação é resolvido nesta ordem padrão do OpenClaw: - `channels["matrix"].accounts..ackReaction` - `channels["matrix"].ackReaction` - `messages.ackReaction` -- fallback para o emoji de identidade do agente +- fallback para emoji da identidade do agente -O escopo da reação de confirmação é resolvido nesta ordem: +O escopo de reação de confirmação é resolvido nesta ordem: - `channels["matrix"].accounts..ackReactionScope` - `channels["matrix"].ackReactionScope` @@ -752,25 +753,25 @@ Comportamento: - `reactionNotifications: "own"` encaminha eventos `m.reaction` adicionados quando eles têm como alvo mensagens Matrix de autoria do bot. - `reactionNotifications: "off"` desativa eventos de sistema de reação. -- Remoções de reação não são sintetizadas em eventos de sistema porque o Matrix as expõe como redações, não como remoções autônomas de `m.reaction`. +- Remoções de reação não são sintetizadas em eventos de sistema porque o Matrix as expõe como redações, não como remoções independentes de `m.reaction`. -## Contexto de histórico +## Contexto do histórico -- `channels.matrix.historyLimit` controla quantas mensagens recentes da sala são incluídas como `InboundHistory` quando uma mensagem de sala do Matrix aciona o agente. Usa como fallback `messages.groupChat.historyLimit`; se ambos não estiverem definidos, o padrão efetivo é `0`. Defina `0` para desativar. +- `channels.matrix.historyLimit` controla quantas mensagens recentes da sala são incluídas como `InboundHistory` quando uma mensagem de sala do Matrix dispara o agente. Usa fallback para `messages.groupChat.historyLimit`; se ambos não estiverem definidos, o padrão efetivo é `0`. Defina `0` para desativar. - O histórico de sala do Matrix é somente da sala. DMs continuam usando o histórico normal da sessão. -- O histórico de sala do Matrix é apenas pendente: o OpenClaw armazena em buffer mensagens da sala que ainda não acionaram uma resposta e então captura esse intervalo quando uma menção ou outro gatilho chega. -- A mensagem gatilho atual não é incluída em `InboundHistory`; ela permanece no corpo principal de entrada daquele turno. -- Novas tentativas do mesmo evento do Matrix reutilizam o snapshot original do histórico em vez de avançar para mensagens mais recentes da sala. +- O histórico de sala do Matrix é somente pendente: o OpenClaw faz buffer de mensagens da sala que ainda não dispararam uma resposta e depois captura esse intervalo quando uma menção ou outro gatilho chega. +- A mensagem de gatilho atual não é incluída em `InboundHistory`; ela permanece no corpo principal de entrada para esse turno. +- Novas tentativas do mesmo evento Matrix reutilizam o snapshot do histórico original em vez de avançar para mensagens mais novas da sala. ## Visibilidade de contexto -O Matrix oferece suporte ao controle compartilhado `contextVisibility` para contexto suplementar de sala, como texto de resposta buscado, raízes de thread e histórico pendente. +O Matrix oferece suporte ao controle compartilhado `contextVisibility` para contexto complementar da sala, como texto de resposta buscado, raízes de thread e histórico pendente. -- `contextVisibility: "all"` é o padrão. O contexto suplementar é mantido como recebido. -- `contextVisibility: "allowlist"` filtra o contexto suplementar para remetentes permitidos pelas verificações ativas de lista de permissões de sala/usuário. +- `contextVisibility: "all"` é o padrão. O contexto complementar é mantido como recebido. +- `contextVisibility: "allowlist"` filtra o contexto complementar para remetentes permitidos pelas verificações ativas de allowlist de sala/usuário. - `contextVisibility: "allowlist_quote"` se comporta como `allowlist`, mas ainda mantém uma resposta citada explícita. -Essa configuração afeta a visibilidade do contexto suplementar, não se a própria mensagem de entrada pode acionar uma resposta. +Essa configuração afeta a visibilidade do contexto complementar, não se a própria mensagem de entrada pode disparar uma resposta. A autorização do gatilho ainda vem de `groupPolicy`, `groups`, `groupAllowFrom` e das configurações de política de DM. ## Política de DM e sala @@ -796,28 +797,28 @@ A autorização do gatilho ainda vem de `groupPolicy`, `groups`, `groupAllowFrom } ``` -Consulte [Groups](/pt-BR/channels/groups) para ver o comportamento de exigência de menção e lista de permissões. +Consulte [Groups](/pt-BR/channels/groups) para ver o comportamento de bloqueio por menção e allowlist. -Exemplo de pareamento para DMs do Matrix: +Exemplo de emparelhamento para DMs do Matrix: ```bash openclaw pairing list matrix openclaw pairing approve matrix ``` -Se um usuário Matrix não aprovado continuar enviando mensagens antes da aprovação, o OpenClaw reutiliza o mesmo código de pareamento pendente e pode enviar uma resposta de lembrete novamente após um curto cooldown em vez de gerar um novo código. +Se um usuário Matrix não aprovado continuar enviando mensagens antes da aprovação, o OpenClaw reutiliza o mesmo código de emparelhamento pendente e pode enviar uma resposta de lembrete novamente após um curto cooldown em vez de gerar um novo código. -Consulte [Pairing](/pt-BR/channels/pairing) para ver o fluxo compartilhado de pareamento de DM e o layout de armazenamento. +Consulte [Pairing](/pt-BR/channels/pairing) para ver o fluxo compartilhado de emparelhamento de DM e o layout de armazenamento. ## Reparo direto de sala -Se o estado de mensagem direta sair de sincronia, o OpenClaw pode acabar com mapeamentos `m.direct` obsoletos que apontam para salas individuais antigas em vez da DM ativa. Inspecione o mapeamento atual de um par com: +Se o estado de mensagem direta ficar dessincronizado, o OpenClaw pode acabar com mapeamentos `m.direct` antigos que apontam para salas individuais antigas em vez da DM ativa. Inspecione o mapeamento atual para um par com: ```bash openclaw matrix direct inspect --user-id @alice:example.org ``` -Repare-o com: +Repare com: ```bash openclaw matrix direct repair --user-id @alice:example.org @@ -826,52 +827,52 @@ openclaw matrix direct repair --user-id @alice:example.org O fluxo de reparo: - prefere uma DM estrita 1:1 que já esteja mapeada em `m.direct` -- recorre a qualquer DM estrita 1:1 atualmente ingressada com esse usuário -- cria uma nova sala direta e reescreve `m.direct` se não existir uma DM saudável +- usa fallback para qualquer DM estrita 1:1 atualmente ingressada com esse usuário +- cria uma nova sala direta e reescreve `m.direct` se não existir uma DM íntegra -O fluxo de reparo não exclui automaticamente salas antigas. Ele apenas escolhe a DM saudável e atualiza o mapeamento para que novos envios do Matrix, avisos de verificação e outros fluxos de mensagem direta voltem a apontar para a sala correta. +O fluxo de reparo não exclui salas antigas automaticamente. Ele apenas escolhe a DM íntegra e atualiza o mapeamento para que novos envios Matrix, avisos de verificação e outros fluxos de mensagem direta voltem a ter como alvo a sala correta. -## Aprovações de execução +## Aprovações de exec O Matrix pode atuar como um cliente nativo de aprovação para uma conta Matrix. Os controles nativos -de roteamento de DM/canal ainda ficam sob a configuração de aprovação de execução: +de roteamento de DM/canal ainda ficam na configuração de aprovação de exec: - `channels.matrix.execApprovals.enabled` -- `channels.matrix.execApprovals.approvers` (opcional; usa como fallback `channels.matrix.dm.allowFrom`) +- `channels.matrix.execApprovals.approvers` (opcional; usa fallback para `channels.matrix.dm.allowFrom`) - `channels.matrix.execApprovals.target` (`dm` | `channel` | `both`, padrão: `dm`) - `channels.matrix.execApprovals.agentFilter` - `channels.matrix.execApprovals.sessionFilter` -Os aprovadores devem ser IDs de usuário Matrix, como `@owner:example.org`. O Matrix ativa automaticamente aprovações nativas quando `enabled` não está definido ou é `"auto"` e pelo menos um aprovador pode ser resolvido. Aprovações de execução usam primeiro `execApprovals.approvers` e podem usar como fallback `channels.matrix.dm.allowFrom`. Aprovações de Plugin autorizam por meio de `channels.matrix.dm.allowFrom`. Defina `enabled: false` para desativar explicitamente o Matrix como cliente nativo de aprovação. Caso contrário, solicitações de aprovação recorrem a outras rotas de aprovação configuradas ou à política de fallback de aprovação. +Os aprovadores devem ser IDs de usuário Matrix como `@owner:example.org`. O Matrix ativa automaticamente aprovações nativas quando `enabled` não está definido ou é `"auto"` e pelo menos um aprovador pode ser resolvido. Aprovações de exec usam primeiro `execApprovals.approvers` e podem usar fallback para `channels.matrix.dm.allowFrom`. Aprovações de Plugin autorizam por meio de `channels.matrix.dm.allowFrom`. Defina `enabled: false` para desativar explicitamente o Matrix como cliente nativo de aprovação. Caso contrário, solicitações de aprovação usam fallback para outras rotas de aprovação configuradas ou para a política de fallback de aprovação. O roteamento nativo do Matrix oferece suporte a ambos os tipos de aprovação: -- `channels.matrix.execApprovals.*` controla o modo nativo de fanout por DM/canal para prompts de aprovação do Matrix. -- Aprovações de execução usam o conjunto de aprovadores de execução de `execApprovals.approvers` ou `channels.matrix.dm.allowFrom`. -- Aprovações de Plugin usam a lista de permissões de DM do Matrix em `channels.matrix.dm.allowFrom`. -- Atalhos de reação e atualizações de mensagem do Matrix se aplicam tanto a aprovações de execução quanto a aprovações de Plugin. +- `channels.matrix.execApprovals.*` controla o modo nativo de fanout em DM/canal para prompts de aprovação do Matrix. +- Aprovações de exec usam o conjunto de aprovadores de exec de `execApprovals.approvers` ou `channels.matrix.dm.allowFrom`. +- Aprovações de Plugin usam a allowlist de DM do Matrix de `channels.matrix.dm.allowFrom`. +- Atalhos de reação do Matrix e atualizações de mensagem se aplicam tanto a aprovações de exec quanto de Plugin. Regras de entrega: -- `target: "dm"` envia prompts de aprovação para as DMs dos aprovadores +- `target: "dm"` envia prompts de aprovação para DMs dos aprovadores - `target: "channel"` envia o prompt de volta para a sala ou DM Matrix de origem -- `target: "both"` envia para as DMs dos aprovadores e para a sala ou DM Matrix de origem +- `target: "both"` envia para DMs dos aprovadores e para a sala ou DM Matrix de origem -Os prompts de aprovação do Matrix semeiam atalhos de reação na mensagem principal de aprovação: +Prompts de aprovação do Matrix semeiam atalhos de reação na mensagem principal de aprovação: - `✅` = permitir uma vez - `❌` = negar -- `♾️` = permitir sempre quando essa decisão for permitida pela política efetiva de execução +- `♾️` = permitir sempre quando essa decisão for permitida pela política de exec efetiva Os aprovadores podem reagir nessa mensagem ou usar os comandos slash de fallback: `/approve allow-once`, `/approve allow-always` ou `/approve deny`. -Somente aprovadores resolvidos podem aprovar ou negar. Para aprovações de execução, a entrega por canal inclui o texto do comando, então só ative `channel` ou `both` em salas confiáveis. +Somente aprovadores resolvidos podem aprovar ou negar. Para aprovações de exec, a entrega por canal inclui o texto do comando, então ative `channel` ou `both` apenas em salas confiáveis. Substituição por conta: - `channels.matrix.accounts..execApprovals` -Documentação relacionada: [Aprovações de execução](/pt-BR/tools/exec-approvals) +Documentação relacionada: [Aprovações de exec](/pt-BR/tools/exec-approvals) ## Várias contas @@ -904,13 +905,13 @@ Documentação relacionada: [Aprovações de execução](/pt-BR/tools/exec-appro ``` Os valores de nível superior em `channels.matrix` atuam como padrões para contas nomeadas, a menos que uma conta os substitua. -Você pode restringir entradas de sala herdadas a uma conta Matrix com `groups..account`. -Entradas sem `account` permanecem compartilhadas entre todas as contas Matrix, e entradas com `account: "default"` continuam funcionando quando a conta padrão é configurada diretamente no nível superior em `channels.matrix.*`. -Padrões parciais compartilhados de autenticação não criam, por si só, uma conta padrão implícita separada. O OpenClaw só sintetiza a conta `default` de nível superior quando esse padrão tem autenticação nova (`homeserver` mais `accessToken`, ou `homeserver` mais `userId` e `password`); contas nomeadas ainda podem continuar detectáveis a partir de `homeserver` mais `userId` quando credenciais em cache satisfazem a autenticação mais tarde. -Se o Matrix já tiver exatamente uma conta nomeada, ou `defaultAccount` apontar para uma chave existente de conta nomeada, a promoção de reparo/configuração de conta única para várias contas preserva essa conta em vez de criar uma nova entrada `accounts.default`. Somente chaves de autenticação/bootstrap do Matrix são movidas para essa conta promovida; chaves compartilhadas de política de entrega permanecem no nível superior. -Defina `defaultAccount` quando quiser que o OpenClaw prefira uma conta Matrix nomeada para roteamento implícito, sondagem e operações da CLI. +Você pode limitar entradas de sala herdadas a uma conta Matrix com `groups..account`. +Entradas sem `account` permanecem compartilhadas entre todas as contas Matrix, e entradas com `account: "default"` ainda funcionam quando a conta padrão é configurada diretamente no nível superior em `channels.matrix.*`. +Padrões parciais compartilhados de autenticação não criam por si só uma conta padrão implícita separada. O OpenClaw só sintetiza a conta `default` de nível superior quando esse padrão tem autenticação nova (`homeserver` mais `accessToken`, ou `homeserver` mais `userId` e `password`); contas nomeadas ainda podem continuar detectáveis a partir de `homeserver` mais `userId` quando credenciais em cache satisfizerem a autenticação depois. +Se o Matrix já tiver exatamente uma conta nomeada, ou `defaultAccount` apontar para uma chave de conta nomeada existente, a promoção de reparo/configuração de conta única para várias contas preserva essa conta em vez de criar uma nova entrada `accounts.default`. Apenas chaves de autenticação/bootstrap do Matrix são movidas para essa conta promovida; chaves compartilhadas de política de entrega permanecem no nível superior. +Defina `defaultAccount` quando quiser que o OpenClaw prefira uma conta Matrix nomeada para roteamento implícito, sondagem e operações de CLI. Se várias contas Matrix estiverem configuradas e um ID de conta for `default`, o OpenClaw usa essa conta implicitamente mesmo quando `defaultAccount` não está definido. -Se você configurar várias contas nomeadas, defina `defaultAccount` ou passe `--account ` para comandos da CLI que dependem de seleção implícita de conta. +Se você configurar várias contas nomeadas, defina `defaultAccount` ou passe `--account ` para comandos de CLI que dependem da seleção implícita de conta. Passe `--account ` para `openclaw matrix verify ...` e `openclaw matrix devices ...` quando quiser substituir essa seleção implícita para um comando. Consulte [Referência de configuração](/pt-BR/gateway/configuration-reference#multi-account-all-channels) para ver o padrão compartilhado de várias contas. @@ -918,9 +919,9 @@ Consulte [Referência de configuração](/pt-BR/gateway/configuration-reference# ## Homeservers privados/LAN Por padrão, o OpenClaw bloqueia homeservers Matrix privados/internos para proteção contra SSRF, a menos que você -ative explicitamente essa permissão por conta. +ative isso explicitamente por conta. -Se seu homeserver estiver em localhost, em um IP de LAN/Tailscale ou em um nome de host interno, ative +Se seu homeserver roda em localhost, em um IP de LAN/Tailscale ou em um hostname interno, ative `network.dangerouslyAllowPrivateNetwork` para essa conta Matrix: ```json5 @@ -947,8 +948,8 @@ openclaw matrix account add \ --access-token syt_ops_xxx ``` -Essa permissão explícita permite apenas destinos privados/internos confiáveis. Homeservers públicos em texto simples, como -`http://matrix.example.org:8008`, continuam bloqueados. Prefira `https://` sempre que possível. +Esse opt-in permite apenas destinos privados/internos confiáveis. Homeservers públicos em texto simples como +`http://matrix.example.org:8008` continuam bloqueados. Prefira `https://` sempre que possível. ## Uso de proxy para tráfego Matrix @@ -967,85 +968,85 @@ Se sua implantação Matrix precisar de um proxy HTTP(S) de saída explícito, d ``` Contas nomeadas podem substituir o padrão de nível superior com `channels.matrix.accounts..proxy`. -O OpenClaw usa a mesma configuração de proxy para tráfego Matrix em execução e para sondas de status da conta. +O OpenClaw usa a mesma configuração de proxy para tráfego Matrix em runtime e para sondagens de status da conta. ## Resolução de destino -O Matrix aceita estes formatos de destino em qualquer lugar onde o OpenClaw pedir um destino de sala ou usuário: +O Matrix aceita estes formatos de destino em qualquer lugar onde o OpenClaw pedir um alvo de sala ou usuário: - Usuários: `@user:server`, `user:@user:server` ou `matrix:user:@user:server` - Salas: `!room:server`, `room:!room:server` ou `matrix:room:!room:server` - Aliases: `#alias:server`, `channel:#alias:server` ou `matrix:channel:#alias:server` -A busca ao vivo em diretório usa a conta Matrix autenticada: +A busca ao vivo no diretório usa a conta Matrix autenticada: -- Buscas de usuário consultam o diretório de usuários Matrix nesse homeserver. -- Buscas de sala aceitam diretamente IDs e aliases explícitos de sala e depois recorrem à busca por nomes de salas ingressadas para essa conta. -- A busca por nome de sala ingressada é feita em regime de melhor esforço. Se o nome de uma sala não puder ser resolvido para um ID ou alias, ele será ignorado pela resolução da lista de permissões em tempo de execução. +- Buscas de usuário consultam o diretório de usuários do Matrix nesse homeserver. +- Buscas de sala aceitam diretamente IDs e aliases explícitos de sala e depois usam fallback para pesquisar nomes de salas ingressadas para essa conta. +- A busca por nome de sala ingressada é best-effort. Se um nome de sala não puder ser resolvido para um ID ou alias, ele será ignorado pela resolução da allowlist em runtime. ## Referência de configuração - `enabled`: ativa ou desativa o canal. - `name`: rótulo opcional para a conta. -- `defaultAccount`: ID de conta preferido quando várias contas Matrix estiverem configuradas. +- `defaultAccount`: ID de conta preferido quando várias contas Matrix estão configuradas. - `homeserver`: URL do homeserver, por exemplo `https://matrix.example.org`. - `network.dangerouslyAllowPrivateNetwork`: permite que esta conta Matrix se conecte a homeservers privados/internos. Ative isso quando o homeserver for resolvido para `localhost`, um IP de LAN/Tailscale ou um host interno como `matrix-synapse`. - `proxy`: URL opcional de proxy HTTP(S) para tráfego Matrix. Contas nomeadas podem substituir o padrão de nível superior com seu próprio `proxy`. - `userId`: ID completo do usuário Matrix, por exemplo `@bot:example.org`. -- `accessToken`: token de acesso para autenticação baseada em token. Valores em texto simples e valores SecretRef são compatíveis com `channels.matrix.accessToken` e `channels.matrix.accounts..accessToken` nos provedores env/file/exec. Consulte [Gerenciamento de segredos](/pt-BR/gateway/secrets). +- `accessToken`: token de acesso para autenticação baseada em token. Valores em texto simples e valores SecretRef são compatíveis com `channels.matrix.accessToken` e `channels.matrix.accounts..accessToken` em provedores env/file/exec. Consulte [Gerenciamento de segredos](/pt-BR/gateway/secrets). - `password`: senha para login baseado em senha. Valores em texto simples e valores SecretRef são compatíveis. - `deviceId`: ID explícito do dispositivo Matrix. - `deviceName`: nome de exibição do dispositivo para login por senha. -- `avatarUrl`: URL armazenada do próprio avatar para sincronização de perfil e atualizações de `profile set`. +- `avatarUrl`: URL do próprio avatar armazenada para sincronização de perfil e atualizações de `profile set`. - `initialSyncLimit`: número máximo de eventos buscados durante a sincronização de inicialização. - `encryption`: ativa E2EE. -- `allowlistOnly`: quando `true`, atualiza a política de sala `open` para `allowlist` e força todas as políticas ativas de DM, exceto `disabled` (incluindo `pairing` e `open`), para `allowlist`. Não afeta políticas `disabled`. -- `allowBots`: permite mensagens de outras contas Matrix do OpenClaw configuradas (`true` ou `"mentions"`). +- `allowlistOnly`: quando `true`, faz upgrade da política de sala `open` para `allowlist` e força todas as políticas ativas de DM, exceto `disabled` (incluindo `pairing` e `open`), para `allowlist`. Não afeta políticas `disabled`. +- `allowBots`: permite mensagens de outras contas Matrix configuradas do OpenClaw (`true` ou `"mentions"`). - `groupPolicy`: `open`, `allowlist` ou `disabled`. -- `contextVisibility`: modo de visibilidade de contexto suplementar de sala (`all`, `allowlist`, `allowlist_quote`). -- `groupAllowFrom`: lista de permissões de IDs de usuário para tráfego de sala. As entradas devem ser IDs completos de usuário Matrix; nomes não resolvidos são ignorados em tempo de execução. -- `historyLimit`: número máximo de mensagens da sala a incluir como contexto de histórico de grupo. Usa como fallback `messages.groupChat.historyLimit`; se ambos não estiverem definidos, o padrão efetivo é `0`. Defina `0` para desativar. +- `contextVisibility`: modo de visibilidade de contexto complementar da sala (`all`, `allowlist`, `allowlist_quote`). +- `groupAllowFrom`: allowlist de IDs de usuário para tráfego de sala. As entradas devem ser IDs completos de usuário Matrix; nomes não resolvidos são ignorados em runtime. +- `historyLimit`: máximo de mensagens de sala a incluir como contexto de histórico de grupo. Usa fallback para `messages.groupChat.historyLimit`; se ambos não estiverem definidos, o padrão efetivo é `0`. Defina `0` para desativar. - `replyToMode`: `off`, `first`, `all` ou `batched`. -- `markdown`: configuração opcional de renderização de Markdown para texto Matrix de saída. +- `markdown`: configuração opcional de renderização Markdown para texto Matrix de saída. - `streaming`: `off` (padrão), `"partial"`, `"quiet"`, `true` ou `false`. `"partial"` e `true` ativam atualizações de rascunho com prévia primeiro usando mensagens de texto normais do Matrix. `"quiet"` usa avisos de prévia sem notificação para configurações auto-hospedadas com regras de push. `false` é equivalente a `"off"`. -- `blockStreaming`: `true` ativa mensagens de progresso separadas para blocos concluídos do assistente enquanto o streaming de prévia em rascunho está ativo. +- `blockStreaming`: `true` ativa mensagens de progresso separadas para blocos concluídos do assistente enquanto o streaming de prévia de rascunho está ativo. - `threadReplies`: `off`, `inbound` ou `always`. -- `threadBindings`: substituições por canal para roteamento e ciclo de vida de sessão vinculados a thread. +- `threadBindings`: substituições por canal para roteamento e ciclo de vida de sessão vinculada a thread. - `startupVerification`: modo automático de solicitação de autoverificação na inicialização (`if-unverified`, `off`). - `startupVerificationCooldownHours`: cooldown antes de tentar novamente solicitações automáticas de verificação na inicialização. -- `textChunkLimit`: tamanho de fragmento da mensagem de saída em caracteres (aplica-se quando `chunkMode` é `length`). +- `textChunkLimit`: tamanho do bloco de mensagem de saída em caracteres (aplica-se quando `chunkMode` é `length`). - `chunkMode`: `length` divide mensagens por contagem de caracteres; `newline` divide em limites de linha. -- `responsePrefix`: string opcional adicionada ao início de todas as respostas de saída deste canal. -- `ackReaction`: substituição opcional da reação de confirmação para este canal/conta. -- `ackReactionScope`: substituição opcional do escopo da reação de confirmação (`group-mentions`, `group-all`, `direct`, `all`, `none`, `off`). +- `responsePrefix`: string opcional adicionada no início de todas as respostas de saída deste canal. +- `ackReaction`: substituição opcional de reação de confirmação para este canal/conta. +- `ackReactionScope`: substituição opcional do escopo de reação de confirmação (`group-mentions`, `group-all`, `direct`, `all`, `none`, `off`). - `reactionNotifications`: modo de notificação de reação de entrada (`own`, `off`). - `mediaMaxMb`: limite de tamanho de mídia em MB para envios de saída e processamento de mídia de entrada. -- `autoJoin`: política de entrada automática por convite (`always`, `allowlist`, `off`). Padrão: `off`. Aplica-se a todos os convites do Matrix, incluindo convites no estilo DM. +- `autoJoin`: política de entrada automática por convite (`always`, `allowlist`, `off`). Padrão: `off`. Aplica-se a todos os convites Matrix, incluindo convites no estilo DM. - `autoJoinAllowlist`: salas/aliases permitidos quando `autoJoin` é `allowlist`. Entradas de alias são resolvidas para IDs de sala durante o tratamento do convite; o OpenClaw não confia no estado de alias declarado pela sala convidada. - `dm`: bloco de política de DM (`enabled`, `policy`, `allowFrom`, `sessionScope`, `threadReplies`). -- `dm.policy`: controla o acesso à DM depois que o OpenClaw entra na sala e a classifica como DM. Isso não altera se um convite é aceito automaticamente. -- `dm.allowFrom`: as entradas devem ser IDs completos de usuário Matrix, a menos que você já as tenha resolvido por meio de busca ao vivo em diretório. +- `dm.policy`: controla o acesso à DM depois que o OpenClaw entra na sala e a classifica como uma DM. Isso não altera se um convite é aceito automaticamente. +- `dm.allowFrom`: as entradas devem ser IDs completos de usuário Matrix, a menos que você já os tenha resolvido por meio da busca ao vivo no diretório. - `dm.sessionScope`: `per-user` (padrão) ou `per-room`. Use `per-room` quando quiser que cada sala de DM do Matrix mantenha contexto separado mesmo que o par seja o mesmo. -- `dm.threadReplies`: substituição da política de thread apenas para DM (`off`, `inbound`, `always`). Ela substitui a configuração de nível superior `threadReplies` tanto para o posicionamento da resposta quanto para o isolamento de sessão em DMs. -- `execApprovals`: entrega nativa de aprovações de execução do Matrix (`enabled`, `approvers`, `target`, `agentFilter`, `sessionFilter`). -- `execApprovals.approvers`: IDs de usuário Matrix autorizados a aprovar solicitações de execução. Opcional quando `dm.allowFrom` já identifica os aprovadores. +- `dm.threadReplies`: substituição de política de thread somente para DM (`off`, `inbound`, `always`). Ela substitui a configuração `threadReplies` de nível superior tanto para posicionamento de resposta quanto para isolamento de sessão em DMs. +- `execApprovals`: entrega nativa de aprovação de exec do Matrix (`enabled`, `approvers`, `target`, `agentFilter`, `sessionFilter`). +- `execApprovals.approvers`: IDs de usuário Matrix autorizados a aprovar solicitações de exec. Opcional quando `dm.allowFrom` já identifica os aprovadores. - `execApprovals.target`: `dm | channel | both` (padrão: `dm`). - `accounts`: substituições nomeadas por conta. Os valores de nível superior de `channels.matrix` atuam como padrões para essas entradas. -- `groups`: mapa de políticas por sala. Prefira IDs ou aliases de sala; nomes de sala não resolvidos são ignorados em tempo de execução. A identidade da sessão/do grupo usa o ID estável da sala após a resolução. +- `groups`: mapa de política por sala. Prefira IDs de sala ou aliases; nomes de sala não resolvidos são ignorados em runtime. A identidade de sessão/grupo usa o ID estável da sala após a resolução. - `groups..account`: restringe uma entrada de sala herdada a uma conta Matrix específica em configurações com várias contas. - `groups..allowBots`: substituição no nível da sala para remetentes de bots configurados (`true` ou `"mentions"`). -- `groups..users`: lista de permissões de remetentes por sala. +- `groups..users`: allowlist de remetentes por sala. - `groups..tools`: substituições por sala para permitir/negar ferramentas. -- `groups..autoReply`: substituição no nível da sala para exigência de menção. `true` desativa a exigência de menção para essa sala; `false` a força de volta. -- `groups..skills`: filtro opcional de Skills por sala. -- `groups..systemPrompt`: trecho opcional de prompt de sistema por sala. +- `groups..autoReply`: substituição no nível da sala para bloqueio por menção. `true` desativa exigências de menção para essa sala; `false` volta a forçá-las. +- `groups..skills`: filtro opcional de Skills no nível da sala. +- `groups..systemPrompt`: trecho opcional de system prompt no nível da sala. - `rooms`: alias legado para `groups`. - `actions`: controle por ação de ferramentas (`messages`, `reactions`, `pins`, `profile`, `memberInfo`, `channelInfo`, `verification`). -## Relacionado +## Relacionados - [Visão geral dos canais](/pt-BR/channels) — todos os canais compatíveis -- [Pairing](/pt-BR/channels/pairing) — autenticação de DM e fluxo de pareamento -- [Groups](/pt-BR/channels/groups) — comportamento de chat em grupo e exigência de menção -- [Roteamento de canais](/pt-BR/channels/channel-routing) — roteamento de sessão para mensagens -- [Segurança](/pt-BR/gateway/security) — modelo de acesso e reforço de segurança +- [Pairing](/pt-BR/channels/pairing) — autenticação de DM e fluxo de emparelhamento +- [Groups](/pt-BR/channels/groups) — comportamento de chat em grupo e bloqueio por menção +- [Roteamento de canal](/pt-BR/channels/channel-routing) — roteamento de sessão para mensagens +- [Segurança](/pt-BR/gateway/security) — modelo de acesso e proteção diff --git a/docs/pt-BR/concepts/system-prompt.md b/docs/pt-BR/concepts/system-prompt.md index 8a3b41c49..3561646e4 100644 --- a/docs/pt-BR/concepts/system-prompt.md +++ b/docs/pt-BR/concepts/system-prompt.md @@ -1,98 +1,98 @@ --- read_when: - - Editar o texto do prompt do sistema, a lista de ferramentas ou as seções de hora/heartbeat - - Alterar o comportamento de bootstrap do workspace ou da injeção de Skills -summary: O que o prompt do sistema do OpenClaw contém e como ele é montado -title: Prompt do sistema + - Editando o texto do prompt de sistema, a lista de ferramentas ou as seções de hora/Heartbeat + - Alterando o bootstrap do workspace ou o comportamento de injeção de Skills +summary: O que o prompt de sistema do OpenClaw contém e como ele é montado +title: Prompt de sistema x-i18n: - generated_at: "2026-04-12T05:33:09Z" + generated_at: "2026-04-15T19:41:35Z" model: gpt-5.4 provider: openai - source_hash: 057f01aac51f7737b5223f61f5d55e552d9011232aebb130426e269d8f6c257f + source_hash: c740e4646bc4980567338237bfb55126af0df72499ca00a48e4848d9a3608ab4 source_path: concepts/system-prompt.md workflow: 15 --- -# Prompt do sistema +# Prompt de sistema -O OpenClaw cria um prompt do sistema personalizado para cada execução de agente. O prompt é **de propriedade do OpenClaw** e não usa o prompt padrão do pi-coding-agent. +O OpenClaw monta um prompt de sistema personalizado para cada execução de agente. O prompt é **de propriedade do OpenClaw** e não usa o prompt padrão do pi-coding-agent. O prompt é montado pelo OpenClaw e injetado em cada execução de agente. -Plugins de provedor podem contribuir com orientações de prompt compatíveis com cache sem substituir o prompt completo de propriedade do OpenClaw. O runtime do provedor pode: +Plugins de provedor podem contribuir com orientações de prompt com reconhecimento de cache sem substituir todo o prompt de propriedade do OpenClaw. O runtime do provedor pode: - substituir um pequeno conjunto de seções centrais nomeadas (`interaction_style`, `tool_call_style`, `execution_bias`) - injetar um **prefixo estável** acima do limite de cache do prompt - injetar um **sufixo dinâmico** abaixo do limite de cache do prompt -Use contribuições de propriedade do provedor para ajustes específicos de famílias de modelos. Mantenha a mutação legada de prompt `before_prompt_build` para compatibilidade ou para mudanças de prompt realmente globais, não para o comportamento normal do provedor. +Use contribuições de propriedade do provedor para ajustes específicos de famílias de modelos. Mantenha a mutação legada de prompt `before_prompt_build` para compatibilidade ou mudanças de prompt realmente globais, não para o comportamento normal do provedor. ## Estrutura O prompt é intencionalmente compacto e usa seções fixas: -- **Ferramentas**: lembrete da fonte da verdade de ferramentas estruturadas mais orientações de runtime para uso de ferramentas. -- **Segurança**: lembrete curto de proteção para evitar comportamento de busca por poder ou de contorno de supervisão. +- **Ferramentas**: lembrete da fonte da verdade de ferramentas estruturadas, além de orientações de uso de ferramentas em runtime. +- **Segurança**: lembrete curto de proteção para evitar comportamento de busca de poder ou desvio de supervisão. - **Skills** (quando disponíveis): informa ao modelo como carregar instruções de skill sob demanda. - **Autoatualização do OpenClaw**: como inspecionar a configuração com segurança usando - `config.schema.lookup`, aplicar patch na configuração com `config.patch`, substituir a configuração completa com `config.apply` e executar `update.run` apenas mediante solicitação explícita do usuário. A ferramenta `gateway`, exclusiva do proprietário, também se recusa a reescrever + `config.schema.lookup`, aplicar patch na configuração com `config.patch`, substituir toda a + configuração com `config.apply` e executar `update.run` somente mediante solicitação explícita do usuário. A ferramenta `gateway`, restrita ao proprietário, também se recusa a reescrever `tools.exec.ask` / `tools.exec.security`, incluindo aliases legados `tools.bash.*` - que são normalizados para esses caminhos de exec protegidos. + que são normalizados para esses caminhos protegidos de exec. - **Workspace**: diretório de trabalho (`agents.defaults.workspace`). - **Documentação**: caminho local para a documentação do OpenClaw (repositório ou pacote npm) e quando lê-la. -- **Arquivos do workspace (injetados)**: indica que os arquivos de bootstrap estão incluídos abaixo. -- **Sandbox** (quando habilitado): indica runtime em sandbox, caminhos do sandbox e se exec com privilégios elevados está disponível. +- **Arquivos do Workspace (injetados)**: indica que os arquivos de bootstrap estão incluídos abaixo. +- **Sandbox** (quando habilitado): indica runtime em sandbox, caminhos do sandbox e se exec elevado está disponível. - **Data e hora atuais**: hora local do usuário, fuso horário e formato de hora. - **Tags de resposta**: sintaxe opcional de tags de resposta para provedores compatíveis. - **Heartbeats**: prompt de heartbeat e comportamento de confirmação, quando heartbeats estão habilitados para o agente padrão. - **Runtime**: host, SO, node, raiz do repositório (quando detectada), nível de raciocínio (uma linha). -- **Raciocínio**: nível atual de visibilidade + dica do toggle `/reasoning`. +- **Raciocínio**: nível atual de visibilidade + dica de alternância com /reasoning. A seção Ferramentas também inclui orientações de runtime para trabalhos de longa duração: -- use cron para acompanhamento futuro (`check back later`, lembretes, trabalho recorrente) - em vez de loops de sleep com `exec`, truques de atraso com `yieldMs` ou polling repetido de `process` -- use `exec` / `process` apenas para comandos que começam agora e continuam em execução +- use Cron para acompanhamento futuro (`check back later`, lembretes, trabalho recorrente) + em vez de loops de `exec` com sleep, truques de atraso com `yieldMs` ou polling repetido de `process` +- use `exec` / `process` apenas para comandos que começam agora e continuam rodando em segundo plano -- quando o wake automático por conclusão estiver habilitado, inicie o comando uma vez e confie - no caminho de wake baseado em push quando ele emitir saída ou falhar +- quando o despertar automático na conclusão estiver habilitado, inicie o comando uma vez e confie no caminho de despertar baseado em push quando ele emitir saída ou falhar - use `process` para logs, status, entrada ou intervenção quando precisar inspecionar um comando em execução - se a tarefa for maior, prefira `sessions_spawn`; a conclusão de subagentes é - baseada em push e é anunciada automaticamente de volta ao solicitante -- não faça polling de `subagents list` / `sessions_list` em loop apenas para aguardar + baseada em push e anunciada automaticamente de volta ao solicitante +- não faça polling de `subagents list` / `sessions_list` em loop apenas para esperar a conclusão Quando a ferramenta experimental `update_plan` está habilitada, Ferramentas também informa ao -modelo para usá-la apenas em trabalhos não triviais com múltiplas etapas, manter exatamente uma +modelo para usá-la apenas em trabalhos não triviais de várias etapas, manter exatamente uma etapa `in_progress` e evitar repetir o plano inteiro após cada atualização. -As proteções de segurança no prompt do sistema são consultivas. Elas orientam o comportamento do modelo, mas não impõem política. Use política de ferramentas, aprovações de exec, sandboxing e listas de permissões de canais para imposição rígida; operadores podem desativá-las por design. +As proteções de segurança no prompt de sistema são orientativas. Elas orientam o comportamento do modelo, mas não impõem política. Use política de ferramentas, aprovações de exec, sandboxing e allowlists de canais para imposição rígida; operadores podem desabilitar isso por design. -Em canais com cartões/botões de aprovação nativos, o prompt de runtime agora informa ao -agente para depender primeiro dessa UI de aprovação nativa. Ele só deve incluir um comando manual -`/approve` 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. +Em canais com cartões/botões de aprovação nativos, o prompt de runtime agora instrui o +agente a confiar primeiro nessa interface nativa de aprovação. Ele só deve incluir um comando manual +`/approve` quando o resultado da ferramenta informar que aprovações no chat não estão disponíveis ou +que aprovação manual é o único caminho. ## Modos de prompt -O OpenClaw pode renderizar prompts do sistema menores para subagentes. O runtime define um +O OpenClaw pode renderizar prompts de sistema menores para subagentes. O runtime define um `promptMode` para cada execução (não é uma configuração voltada ao usuário): - `full` (padrão): inclui todas as seções acima. -- `minimal`: usado para subagentes; omite **Skills**, **Recuperação de memória**, **Autoatualização do OpenClaw**, **Aliases de modelo**, **Identidade do usuário**, **Tags de resposta**, - **Mensagens**, **Respostas silenciosas** e **Heartbeats**. Ferramentas, **Segurança**, +- `minimal`: usado para subagentes; omite **Skills**, **Recordação de Memória**, **Autoatualização do OpenClaw**, **Aliases de modelos**, **Identidade do usuário**, **Tags de resposta**, + **Mensageria**, **Respostas silenciosas** e **Heartbeats**. Ferramentas, **Segurança**, Workspace, Sandbox, Data e hora atuais (quando conhecidas), Runtime e contexto injetado continuam disponíveis. -- `none`: retorna apenas a linha de identidade base. +- `none`: retorna apenas a linha base de identidade. Quando `promptMode=minimal`, prompts extras injetados são rotulados como **Contexto do subagente** -em vez de **Contexto do chat em grupo**. +em vez de **Contexto de chat em grupo**. ## Injeção de bootstrap do workspace -Os arquivos de bootstrap são aparados e anexados em **Contexto do projeto** para que o modelo veja o contexto de identidade e perfil sem precisar fazer leituras explícitas: +Os arquivos de bootstrap são recortados e anexados em **Contexto do projeto** para que o modelo veja o contexto de identidade e perfil sem precisar de leituras explícitas: - `AGENTS.md` - `SOUL.md` @@ -100,49 +100,49 @@ Os arquivos de bootstrap são aparados e anexados em **Contexto do projeto** par - `IDENTITY.md` - `USER.md` - `HEARTBEAT.md` -- `BOOTSTRAP.md` (apenas em workspaces totalmente novos) +- `BOOTSTRAP.md` (somente em workspaces totalmente novos) - `MEMORY.md` quando presente, caso contrário `memory.md` como fallback em minúsculas -Todos esses arquivos são **injetados na janela de contexto** em cada turno, a menos que -se aplique um gate específico do arquivo. `HEARTBEAT.md` é omitido em execuções normais quando -heartbeats estão desabilitados para o agente padrão ou quando -`agents.defaults.heartbeat.includeSystemPromptSection` é false. Mantenha os arquivos injetados concisos — especialmente `MEMORY.md`, que pode crescer com o tempo e levar a uso de contexto inesperadamente alto e compactação mais frequente. +Todos esses arquivos são **injetados na janela de contexto** em toda rodada, a menos que +se aplique um bloqueio específico do arquivo. `HEARTBEAT.md` é omitido em execuções normais quando +heartbeats estão desabilitados para o agente padrão ou +`agents.defaults.heartbeat.includeSystemPromptSection` é false. Mantenha os arquivos injetados concisos — especialmente `MEMORY.md`, que pode crescer com o tempo e levar a uso de contexto inesperadamente alto e compaction mais frequente. -> **Observação:** arquivos diários `memory/*.md` **não** fazem parte do bootstrap normal de -> Contexto do projeto. Em turnos comuns, eles são acessados sob demanda por meio das -> ferramentas `memory_search` e `memory_get`, portanto não contam contra a janela de -> contexto, a menos que o modelo os leia explicitamente. Turnos simples de `/new` e -> `/reset` são a exceção: o runtime pode prependar memória diária recente -> como um bloco único de contexto de inicialização para esse primeiro turno. +> **Observação:** arquivos diários `memory/*.md` **não** fazem parte do Contexto do projeto +> normal do bootstrap. Em rodadas comuns, eles são acessados sob demanda por meio das +> ferramentas `memory_search` e `memory_get`, portanto não contam contra a +> janela de contexto, a menos que o modelo os leia explicitamente. Rodadas simples de `/new` e +> `/reset` são a exceção: o runtime pode antepor memória diária recente +> como um bloco único de contexto inicial para essa primeira rodada. Arquivos grandes são truncados com um marcador. O tamanho máximo por arquivo é controlado por `agents.defaults.bootstrapMaxChars` (padrão: 20000). O conteúdo total de bootstrap injetado -entre os arquivos é limitado por `agents.defaults.bootstrapTotalMaxChars` +entre arquivos é limitado por `agents.defaults.bootstrapTotalMaxChars` (padrão: 150000). Arquivos ausentes injetam um marcador curto de arquivo ausente. Quando ocorre truncamento, o OpenClaw pode injetar um bloco de aviso em Contexto do projeto; controle isso com `agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always`; padrão: `once`). -Sessões de subagente injetam apenas `AGENTS.md` e `TOOLS.md` (os outros arquivos de bootstrap +Sessões de subagentes injetam apenas `AGENTS.md` e `TOOLS.md` (outros arquivos de bootstrap são filtrados para manter pequeno o contexto do subagente). -Hooks internos podem interceptar esta etapa via `agent:bootstrap` para modificar ou substituir +Hooks internos podem interceptar esta etapa por meio de `agent:bootstrap` para mutar ou substituir os arquivos de bootstrap injetados (por exemplo, trocando `SOUL.md` por uma persona alternativa). Se você quiser fazer o agente soar menos genérico, comece com [Guia de personalidade do SOUL.md](/pt-BR/concepts/soul). -Para inspecionar quanto cada arquivo injetado contribui (bruto vs. injetado, truncamento, além da sobrecarga do schema de ferramentas), use `/context list` ou `/context detail`. Veja [Contexto](/pt-BR/concepts/context). +Para inspecionar quanto cada arquivo injetado contribui (bruto vs injetado, truncamento, além da sobrecarga do schema da ferramenta), use `/context list` ou `/context detail`. Veja [Contexto](/pt-BR/concepts/context). -## Tratamento de tempo +## Tratamento de hora -O prompt do sistema inclui uma seção dedicada **Data e hora atuais** quando o -fuso horário do usuário é conhecido. Para manter o cache do prompt estável, agora ele inclui apenas o +O prompt de sistema inclui uma seção dedicada **Data e hora atuais** quando o +fuso horário do usuário é conhecido. Para manter o cache do prompt estável, agora ela inclui apenas o **fuso horário** (sem relógio dinâmico nem formato de hora). Use `session_status` quando o agente precisar da hora atual; o cartão de status inclui uma linha de timestamp. A mesma ferramenta também pode opcionalmente definir uma substituição -de modelo por sessão (`model=default` a limpa). +de modelo por sessão (`model=default` a remove). Configure com: @@ -156,10 +156,10 @@ Veja [Data e hora](/pt-BR/date-time) para detalhes completos do comportamento. Quando existem skills elegíveis, o OpenClaw injeta uma **lista compacta de skills disponíveis** (`formatSkillsForPrompt`) que inclui o **caminho do arquivo** de cada skill. O prompt instrui o modelo a usar `read` para carregar o SKILL.md no local listado -(workspace, gerenciado ou empacotado). Se não houver skills elegíveis, a seção -Skills é omitida. +(workspace, gerenciado ou empacotado). Se não houver skills elegíveis, a +seção Skills é omitida. -A elegibilidade inclui gates de metadados da skill, verificações de ambiente/configuração de runtime +A elegibilidade inclui bloqueios de metadados da skill, verificações de ambiente/configuração de runtime e a allowlist efetiva de skills do agente quando `agents.defaults.skills` ou `agents.list[].skills` está configurado. @@ -173,13 +173,26 @@ e a allowlist efetiva de skills do agente quando `agents.defaults.skills` ou ``` -Isso mantém o prompt base pequeno, ao mesmo tempo que ainda permite uso direcionado de skills. +Isso mantém o prompt base pequeno enquanto ainda permite uso direcionado de skills. + +O orçamento da lista de skills pertence ao subsistema de skills: + +- Padrão global: `skills.limits.maxSkillsPromptChars` +- Sobrescrita por agente: `agents.list[].skillsLimits.maxSkillsPromptChars` + +Trechos genéricos limitados de runtime usam uma superfície diferente: + +- `agents.defaults.contextLimits.*` +- `agents.list[].contextLimits.*` + +Essa separação mantém o dimensionamento de skills separado do dimensionamento de leitura/injeção de runtime, como +`memory_get`, resultados de ferramentas ao vivo e atualizações de `AGENTS.md` após compaction. ## Documentação -Quando disponível, o prompt do sistema inclui uma seção **Documentação** que aponta para o +Quando disponível, o prompt de sistema inclui uma seção **Documentação** que aponta para o diretório local da documentação do OpenClaw (seja `docs/` no workspace do repositório ou a documentação do pacote npm empacotado) e também menciona o espelho público, o repositório de origem, o Discord da comunidade e o ClawHub ([https://clawhub.ai](https://clawhub.ai)) para descoberta de skills. O prompt instrui o modelo a consultar primeiro a documentação local -para comportamento, comandos, configuração ou arquitetura do OpenClaw e a executar +para comportamento, comandos, configuração ou arquitetura do OpenClaw, e a executar `openclaw status` por conta própria quando possível (pedindo ao usuário apenas quando não tiver acesso). diff --git a/docs/pt-BR/gateway/configuration-reference.md b/docs/pt-BR/gateway/configuration-reference.md index 9773faa31..8141c79c6 100644 --- a/docs/pt-BR/gateway/configuration-reference.md +++ b/docs/pt-BR/gateway/configuration-reference.md @@ -1,14 +1,14 @@ --- read_when: - - Você precisa da semântica exata da configuração em nível de campo ou dos valores padrão + - Você precisa da semântica exata ou dos padrões de configuração em nível de campo - Você está validando blocos de configuração de canal, modelo, Gateway ou ferramenta summary: Referência de configuração do Gateway para chaves principais do OpenClaw, padrões e links para referências dedicadas de subsistemas title: Referência de configuração x-i18n: - generated_at: "2026-04-15T14:40:46Z" + generated_at: "2026-04-15T19:41:36Z" model: gpt-5.4 provider: openai - source_hash: 7a4da3b41d0304389bd6359aac1185c231e529781b607656ab352f8a8104bdba + source_hash: 2bdb0f3e56e4a4d767fb4d6150526ae9b3926ef5b213b458001f41d02762436d source_path: gateway/configuration-reference.md workflow: 15 --- @@ -17,21 +17,21 @@ x-i18n: Referência principal de configuração para `~/.openclaw/openclaw.json`. Para uma visão geral orientada a tarefas, consulte [Configuration](/pt-BR/gateway/configuration). -Esta página cobre as principais superfícies de configuração do OpenClaw e direciona para outras páginas quando um subsistema tem sua própria referência mais aprofundada. Ela **não** tenta incluir em uma única página todos os catálogos de comandos pertencentes a canais/plugins nem todos os parâmetros detalhados de memória/QMD. +Esta página cobre as principais superfícies de configuração do OpenClaw e aponta para outras referências quando um subsistema tem sua própria documentação mais aprofundada. Ela **não** tenta incorporar em uma única página todo catálogo de comandos pertencente a canal/Plugin nem todos os ajustes avançados de memória/QMD. -Fonte de verdade no código: +Fonte de verdade do código: -- `openclaw config schema` imprime o JSON Schema em uso para validação e para a Control UI, com metadados de bundled/plugin/channel mesclados quando disponíveis -- `config.schema.lookup` retorna um nó do 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 +- `openclaw config schema` imprime o JSON Schema em tempo real usado para validação e pela Control UI, com metadados agrupados de bundles/plugins/canais quando disponíveis +- `config.schema.lookup` retorna um nó do schema limitado a um caminho para ferramentas de exploração detalhada +- `pnpm config:docs:check` / `pnpm config:docs:gen` validam o hash da linha de base da documentação de configuração em relação à superfície atual do schema Referências aprofundadas 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 integrados + bundled -- páginas do canal/plugin proprietário para superfícies de comandos específicas do canal +- [Referência de configuração de memória](/pt-BR/reference/memory-config) para `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` e a configuração de dreaming em `plugins.entries.memory-core.config.dreaming` +- [Comandos de barra](/pt-BR/tools/slash-commands) para o catálogo atual de comandos internos + agrupados +- páginas do canal/Plugin responsável para superfícies de comando específicas de canal -O formato de 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. +O formato de configuração é **JSON5** (comentários + vírgulas finais permitidos). Todos os campos são opcionais — o OpenClaw usa padrões seguros quando omitidos. --- @@ -43,28 +43,28 @@ Cada canal inicia automaticamente quando sua seção de configuração existe (a Todos os canais oferecem suporte a políticas de DM e políticas de grupo: -| Política de DM | Comportamento | -| ------------------- | -------------------------------------------------------------- | -| `pairing` (padrão) | Remetentes desconhecidos recebem um código de pareamento único; o proprietário deve aprovar | -| `allowlist` | Apenas remetentes em `allowFrom` (ou armazenamento de permissões pareado) | -| `open` | Permitir todas as DMs recebidas (requer `allowFrom: ["*"]`) | -| `disabled` | Ignorar todas as DMs recebidas | +| Política de DM | 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 pareado) | +| `open` | Permitir todas as DMs recebidas (requer `allowFrom: ["*"]`) | +| `disabled` | Ignorar todas as DMs recebidas | -| Política de grupo | Comportamento | -| --------------------- | ------------------------------------------------------ | -| `allowlist` (padrão) | Apenas grupos que correspondem à lista de permissões configurada | -| `open` | Ignorar listas de permissões de grupo (o bloqueio por menção ainda se aplica) | -| `disabled` | Bloquear todas as mensagens de grupo/sala | +| Política de grupo | Comportamento | +| ---------------------- | ----------------------------------------------------- | +| `allowlist` (padrão) | Apenas grupos que correspondem à lista de permissões configurada | +| `open` | Ignorar listas de permissão de grupo (o bloqueio por menção ainda se aplica) | +| `disabled` | Bloquear todas as mensagens de grupo/sala | `channels.defaults.groupPolicy` define o padrão quando o `groupPolicy` de um provedor não está definido. Os códigos de pareamento expiram após 1 hora. Solicitações pendentes de pareamento por DM são limitadas a **3 por canal**. -Se um bloco de provedor estiver ausente por completo (`channels.` ausente), a política de grupo em tempo de execução recorre a `allowlist` (fail-closed) com um aviso na inicialização. +Se um bloco de provedor estiver totalmente ausente (`channels.` ausente), a política de grupo em tempo de execução usa `allowlist` como padrão (fail-closed), com um aviso na inicialização. ### Substituições de modelo por canal -Use `channels.modelByChannel` para fixar IDs de canal específicos em um modelo. Os valores aceitam `provider/model` ou aliases de modelo configurados. O mapeamento do 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 se aplica quando uma sessão ainda não tem uma substituição de modelo (por exemplo, definida via `/model`). ```json5 { @@ -85,9 +85,9 @@ Use `channels.modelByChannel` para fixar IDs de canal específicos em um modelo. } ``` -### Padrões e Heartbeat de canais +### Padrões de canal e Heartbeat -Use `channels.defaults` para o comportamento compartilhado de política de grupo e Heartbeat entre provedores: +Use `channels.defaults` para compartilhar comportamento de política de grupo e Heartbeat entre provedores: ```json5 { @@ -106,14 +106,14 @@ Use `channels.defaults` para o comportamento compartilhado de política de grupo ``` - `channels.defaults.groupPolicy`: política de grupo de fallback quando o `groupPolicy` em nível de provedor não está definido. -- `channels.defaults.contextVisibility`: modo padrão de visibilidade de contexto suplementar para todos os canais. Valores: `all` (padrão, inclui todo o contexto citado/em thread/histórico), `allowlist` (inclui apenas contexto de remetentes na lista de permissões), `allowlist_quote` (igual a allowlist, mas mantém contexto explícito de citação/resposta). Substituição por canal: `channels..contextVisibility`. -- `channels.defaults.heartbeat.showOk`: inclui status saudáveis dos canais na saída do Heartbeat. -- `channels.defaults.heartbeat.showAlerts`: inclui status degradados/com erro na saída do Heartbeat. -- `channels.defaults.heartbeat.useIndicator`: renderiza uma saída compacta do Heartbeat no estilo indicador. +- `channels.defaults.contextVisibility`: modo padrão de visibilidade de contexto suplementar para todos os canais. Valores: `all` (padrão, inclui todo contexto citado/em thread/no histórico), `allowlist` (inclui apenas contexto 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`: incluir status saudáveis de canal na saída do Heartbeat. +- `channels.defaults.heartbeat.showAlerts`: incluir status degradados/com erro na saída do Heartbeat. +- `channels.defaults.heartbeat.useIndicator`: renderizar saída do Heartbeat compacta no estilo indicador. ### WhatsApp -O WhatsApp é executado pelo canal web do Gateway (Baileys Web). Ele inicia automaticamente quando existe uma sessão vinculada. +O WhatsApp funciona pelo canal web do gateway (Baileys Web). Ele inicia automaticamente quando existe uma sessão vinculada. ```json5 { @@ -124,7 +124,7 @@ O WhatsApp é executado pelo canal web do Gateway (Baileys Web). Ele inicia auto textChunkLimit: 4000, chunkMode: "length", // length | newline mediaMaxMb: 50, - sendReadReceipts: true, // marcações azuis (false no modo de conversa consigo mesmo) + sendReadReceipts: true, // blue ticks (false in self-chat mode) groups: { "*": { requireMention: true }, }, @@ -164,9 +164,9 @@ O WhatsApp é executado pelo canal web do Gateway (Baileys Web). Ele inicia auto } ``` -- Os comandos de saída usam a conta `default` por padrão, se ela existir; caso contrário, a primeira ID de conta configurada (ordenada). -- `channels.whatsapp.defaultAccount` opcional substitui essa seleção padrão da conta fallback quando corresponde a uma ID de conta configurada. -- O diretório de autenticação legado de conta única do Baileys é migrado por `openclaw doctor` para `whatsapp/default`. +- Os comandos de saída usam por padrão a conta `default`, se presente; caso contrário, o primeiro ID de conta configurado (ordenado). +- `channels.whatsapp.defaultAccount` opcional substitui essa seleção padrão de 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`. - Substituições por conta: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. @@ -202,7 +202,7 @@ O WhatsApp é executado pelo canal web do Gateway (Baileys Web). Ele inicia auto historyLimit: 50, replyToMode: "first", // off | first | all | batched linkPreview: true, - streaming: "partial", // off | partial | block | progress (padrão: off; habilite explicitamente para evitar limites de taxa de edição de pré-visualização) + streaming: "partial", // off | partial | block | progress (default: off; opt in explicitly to avoid preview-edit rate limits) actions: { reactions: true, sendMessage: true }, reactionNotifications: "own", // off | own | all mediaMaxMb: 100, @@ -225,13 +225,13 @@ O WhatsApp é executado pelo canal web do Gateway (Baileys Web). Ele inicia auto } ``` -- Token do bot: `channels.telegram.botToken` ou `channels.telegram.tokenFile` (apenas arquivo regular; symlinks 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 uma ID de conta configurada. +- 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` emite um aviso quando isso está ausente ou inválido. - `configWrites: false` bloqueia gravações de configuração iniciadas pelo Telegram (migrações de ID de supergrupo, `/config set|unset`). -- Entradas `bindings[]` de nível superior com `type: "acp"` configuram vínculos persistentes de ACP 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 [Agentes ACP](/pt-BR/tools/acp-agents#channel-specific-settings). -- As pré-visualizações de streaming do Telegram usam `sendMessage` + `editMessageText` (funciona em chats diretos e em grupo). -- Política de repetição: consulte [Política de repetição](/pt-BR/concepts/retry). +- Entradas `bindings[]` de nível superior com `type: "acp"` configuram bindings persistentes de ACP 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 stream 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 @@ -286,7 +286,7 @@ O WhatsApp é executado pelo canal web do Gateway (Baileys Web). Ele inicia auto historyLimit: 20, textChunkLimit: 2000, chunkMode: "length", // length | newline - streaming: "off", // off | partial | block | progress (progress é mapeado para partial no Discord) + streaming: "off", // off | partial | block | progress (progress maps to partial on Discord) maxLinesPerMessage: 17, ui: { components: { @@ -297,7 +297,7 @@ O WhatsApp é executado pelo canal web do Gateway (Baileys Web). Ele inicia auto enabled: true, idleHours: 24, maxAgeHours: 0, - spawnSubagentSessions: false, // opt-in para sessions_spawn({ thread: true }) + spawnSubagentSessions: false, // opt-in for sessions_spawn({ thread: true }) }, voice: { enabled: true, @@ -334,33 +334,33 @@ O WhatsApp é executado pelo canal web do Gateway (Baileys Web). Ele inicia auto ``` - Token: `channels.discord.token`, com `DISCORD_BOT_TOKEN` como fallback para a conta padrão. -- Chamadas diretas de saída que fornecem um `token` do Discord explícito usam esse token para a chamada; as configurações de repetição/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 da conta padrão quando corresponde a uma ID de conta configurada. -- Use `user:` (DM) ou `channel:` (canal de guild) para destinos de entrega; IDs numéricas simples são rejeitadas. -- Slugs de guild usam letras minúsculas com espaços substituídos por `-`; chaves de canal usam o nome em slug (sem `#`). Prefira IDs de guild. +- 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 em 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 sem prefixo 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 criadas por bots são ignoradas por padrão. `allowBots: true` as habilita; use `allowBots: "mentions"` para aceitar apenas mensagens de bot que mencionem o bot (mensagens próprias ainda são filtradas). -- `channels.discord.guilds..ignoreOtherMentions` (e substituições em nível de canal) descarta mensagens que mencionam outro usuário ou função, mas não o bot (excluindo @everyone/@here). +- `channels.discord.guilds..ignoreOtherMentions` (e substituições no nível de 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 têm menos de 2000 caracteres. - `channels.discord.threadBindings` controla o roteamento vinculado a threads do Discord: - `enabled`: substituição do Discord para recursos de sessão vinculados a thread (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` e entrega/roteamento vinculados) - `idleHours`: substituição do Discord para desfoco automático por inatividade em horas (`0` desabilita) - `maxAgeHours`: substituição do Discord para idade máxima rígida em horas (`0` desabilita) - - `spawnSubagentSessions`: chave de ativação opcional para criação/vinculação automática de thread com `sessions_spawn({ thread: true })` -- Entradas `bindings[]` de nível superior com `type: "acp"` configuram vínculos persistentes de ACP para canais e threads (use a id do canal/thread em `match.peer.id`). A semântica dos campos é compartilhada em [Agentes ACP](/pt-BR/tools/acp-agents#channel-specific-settings). + - `spawnSubagentSessions`: chave de ativação para criação/vinculação automática de thread em `sessions_spawn({ thread: true })` +- Entradas `bindings[]` de nível superior com `type: "acp"` configuram bindings persistentes de ACP 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 entrada automática + 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 a recepção 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 booleanos de `streaming` são migrados automaticamente. -- `channels.discord.autoPresence` mapeia a disponibilidade em tempo de execução para a 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 mutável de nome/tag (modo de compatibilidade de emergência). -- `channels.discord.execApprovals`: entrega nativa de aprovação de exec no Discord e autorização de aprovadores. - - `enabled`: `true`, `false` ou `"auto"` (padrão). No modo automático, as aprovações de exec são ativadas quando os aprovadores podem ser resolvidos a partir de `approvers` ou `commands.ownerAllowFrom`. - - `approvers`: IDs de usuário do Discord autorizadas a aprovar solicitações de exec. Usa `commands.ownerAllowFrom` como fallback quando omitido. - - `agentFilter`: lista de permissões opcional de IDs de agente. Omita para encaminhar aprovações para todos os agentes. +- 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 stream. Os valores legados `streamMode` e booleanos `streaming` são migrados automaticamente. +- `channels.discord.autoPresence` mapeia a disponibilidade em tempo de execução para a presença do bot (healthy => online, degraded => idle, exhausted => dnd) e permite substituições opcionais de texto de status. +- `channels.discord.dangerouslyAllowNameMatching` reabilita a correspondência por nome/tag mutável (modo de compatibilidade break-glass). +- `channels.discord.execApprovals`: entrega de aprovação de exec nativa do Discord e autorização de aprovadores. + - `enabled`: `true`, `false` ou `"auto"` (padrão). No modo automático, aprovações de exec são ativadas quando os 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`: allowlist opcional de IDs de agente. Omita para encaminhar aprovações para todos os agentes. - `sessionFilter`: padrões opcionais de chave de sessão (substring ou regex). - - `target`: onde enviar prompts de aprovação. `"dm"` (padrão) envia para DMs do aprovador, `"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. + - `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, recusa 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). @@ -394,10 +394,10 @@ O WhatsApp é executado pelo canal web do Gateway (Baileys Web). Ele inicia auto ``` - JSON da conta de serviço: embutido (`serviceAccount`) ou baseado em arquivo (`serviceAccountFile`). -- SecretRef de conta de serviço também é compatível (`serviceAccountRef`). +- SecretRef para 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` reabilita correspondência mutável de principal de email (modo de compatibilidade de emergência). +- Use `spaces/` ou `users/` para alvos de entrega. +- `channels.googlechat.dangerouslyAllowNameMatching` reabilita a correspondência mutável de principal de e-mail (modo de compatibilidade break-glass). ### Slack @@ -449,7 +449,7 @@ O WhatsApp é executado pelo canal web do Gateway (Baileys Web). Ele inicia auto chunkMode: "length", streaming: { mode: "partial", // off | partial | block | progress - nativeTransport: true, // usar a API nativa de streaming do Slack quando mode=partial + nativeTransport: true, // use Slack native streaming API when mode=partial }, mediaMaxMb: 20, execApprovals: { @@ -464,35 +464,35 @@ O WhatsApp é executado pelo canal web do Gateway (Baileys Web). Ele inicia auto } ``` -- **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` como fallback 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. +- `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 meio de SecretRef, mas o caminho atual de comando/tempo de execução não conseguiu + configurada por SecretRef, mas o caminho atual de comando/runtime 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 uma ID de conta configurada. -- `channels.slack.streaming.mode` é a chave canônica do modo de streaming do Slack. `channels.slack.streaming.nativeTransport` controla o transporte nativo de streaming do Slack. Os valores legados `streamMode`, booleanos de `streaming` e `nativeStreaming` 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 do modo de stream do Slack. `channels.slack.streaming.nativeTransport` controla o transporte de streaming nativo 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 em todo o canal. `thread.inheritParent` copia a transcrição do canal pai para novas threads. +**Isolamento de sessão por thread:** `thread.historyScope` é por thread (padrão) ou compartilhado pelo canal. `thread.inheritParent` copia a transcrição do canal pai para novas threads. -- O streaming nativo do Slack, junto com o status de thread “is typing...” no estilo assistant do Slack, requer um alvo de resposta em thread. DMs de nível superior ficam fora de thread por padrão, então usam `typingReaction` ou entrega normal em vez da pré-visualização no estilo de thread. -- `typingReaction` adiciona uma reação temporária à mensagem recebida no Slack enquanto uma resposta está em andamento, depois a remove na conclusão. Use um shortcode de emoji do Slack, como `"hourglass_flowing_sand"`. -- `channels.slack.execApprovals`: entrega nativa de aprovação de exec no Slack 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"`). +- O streaming nativo do Slack mais o status de thread no estilo “is typing...” do assistente do Slack exigem 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 de aprovação de exec nativa do Slack 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ções | Padrão | Observações | +| -------------- | -------- | ----------------------- | +| reactions | enabled | Reagir + listar reações | +| messages | enabled | Ler/enviar/editar/excluir | +| pins | enabled | Fixar/desafixar/listar | +| memberInfo | enabled | Informações do membro | +| emojiList | enabled | Lista de emojis personalizados | ### Mattermost @@ -513,10 +513,10 @@ O Mattermost é distribuído como um Plugin: `openclaw plugins install @openclaw "team-channel-id": { requireMention: false }, }, commands: { - native: true, // ativação opcional + native: true, // opt-in nativeSkills: true, callbackPath: "/api/channels/mattermost/command", - // URL explícita opcional para implantações com proxy reverso/públicas + // Optional explicit URL for reverse-proxy/public deployments callbackUrl: "https://gateway.example.com/api/channels/mattermost/command", }, textChunkLimit: 4000, @@ -526,23 +526,23 @@ O Mattermost é distribuído como um Plugin: `openclaw plugins install @openclaw } ``` -Modos de chat: `oncall` (responde a @menção, padrão), `onmessage` (toda mensagem), `onchar` (mensagens que começam com o prefixo de acionamento). +Modos de chat: `oncall` (responde a menção com @, padrão), `onmessage` (toda mensagem), `onchar` (mensagens que começam com um prefixo de gatilho). Quando os 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 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 + pelo Mattermost durante o registro do comando de barra. Se o registro falhar ou + nenhum comando for ativado, o OpenClaw rejeita callbacks com `Unauthorized: invalid command token.` -- Para hosts de callback privados/tailnet/internos, o Mattermost pode exigir - que `ServiceSettings.AllowedUntrustedInternalConnections` inclua o host/domínio do callback. +- 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`: permitir ou negar gravações de configuração iniciadas pelo Mattermost. - `channels.mattermost.requireMention`: exigir `@mention` antes de responder em canais. -- `channels.mattermost.groups..requireMention`: substituição por canal para bloqueio por menção (`"*"` para padrão). -- `channels.mattermost.defaultAccount` opcional substitui a seleção da conta padrão quando corresponde a uma ID de conta configurada. +- `channels.mattermost.groups..requireMention`: substituição de bloqueio por menção por canal (`"*"` para padrão). +- `channels.mattermost.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um ID de conta configurado. ### Signal @@ -551,7 +551,7 @@ Quando os comandos nativos do Mattermost estão habilitados: channels: { signal: { enabled: true, - account: "+15555550123", // vínculo opcional de conta + account: "+15555550123", // optional account binding dmPolicy: "pairing", allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"], configWrites: true, @@ -565,13 +565,13 @@ 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 a uma identidade de conta específica do 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 uma ID de conta configurada. +- `channels.signal.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um ID de conta configurado. ### BlueBubbles -BlueBubbles é o caminho recomendado para iMessage (com suporte de Plugin, configurado em `channels.bluebubbles`). +BlueBubbles é o caminho recomendado para iMessage (com Plugin de suporte, configurado em `channels.bluebubbles`). ```json5 { @@ -579,16 +579,16 @@ BlueBubbles é o caminho recomendado para iMessage (com suporte de Plugin, confi bluebubbles: { enabled: true, dmPolicy: "pairing", - // serverUrl, password, webhookPath, controles de grupo e ações avançadas: - // veja /channels/bluebubbles + // serverUrl, password, webhookPath, group controls, and advanced actions: + // see /channels/bluebubbles }, }, } ``` - Caminhos de chave principais cobertos aqui: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. -- `channels.bluebubbles.defaultAccount` opcional substitui a seleção da conta padrão quando corresponde a uma ID de conta configurada. -- Entradas `bindings[]` de nível superior com `type: "acp"` podem vincular conversas do BlueBubbles a sessões persistentes de ACP. Use um identificador BlueBubbles ou string de destino (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) em `match.peer.id`. Semântica compartilhada dos campos: [Agentes ACP](/pt-BR/tools/acp-agents#channel-specific-settings). +- `channels.bluebubbles.defaultAccount` opcional substitui a seleção de conta padrão quando corresponde a um ID de conta configurado. +- Entradas `bindings[]` de nível superior com `type: "acp"` podem vincular conversas do BlueBubbles a sessões persistentes de ACP. Use um identificador ou string de destino do 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). - A configuração completa do canal BlueBubbles está documentada em [BlueBubbles](/pt-BR/channels/bluebubbles). ### iMessage @@ -617,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 uma ID de conta configurada. +- `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 conversas. -- `cliPath` pode apontar para um wrapper SSH; defina `remoteHost` (`host` ou `user@host`) para buscar anexos via 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 por SCP. - `attachmentRoots` e `remoteAttachmentRoots` restringem caminhos de anexos recebidos (padrão: `/Users/*/Library/Messages/Attachments`). -- O SCP usa verificação estrita de chave do host, então garanta que a chave do host de retransmissão já exista em `~/.ssh/known_hosts`. +- SCP usa verificação estrita de chave de host, então certifique-se de que a chave do host de retransmissão já exista em `~/.ssh/known_hosts`. - `channels.imessage.configWrites`: permite ou nega gravações de configuração iniciadas pelo iMessage. -- Entradas `bindings[]` de nível superior com `type: "acp"` podem vincular conversas do iMessage a sessões persistentes de ACP. Use um identificador normalizado ou destino explícito de conversa (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) em `match.peer.id`. Semântica compartilhada dos campos: [Agentes ACP](/pt-BR/tools/acp-agents#channel-specific-settings). +- Entradas `bindings[]` de nível superior com `type: "acp"` podem vincular conversas do iMessage a sessões persistentes de ACP. 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). @@ -638,7 +638,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -O Matrix tem suporte por extensão e é configurado em `channels.matrix`. +Matrix tem suporte por extensão e é configurado em `channels.matrix`. ```json5 { @@ -669,24 +669,24 @@ O Matrix tem suporte por 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 ativação opcional de rede são controles independentes. +- `channels.matrix.proxy` roteia o tráfego HTTP do Matrix por um proxy HTTP(S) explícito. Contas nomeadas podem sobrescrevê-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 novos convites no estilo DM são ignorados até você definir `autoJoin: "allowlist"` com `autoJoinAllowlist` ou `autoJoin: "always"`. -- `channels.matrix.execApprovals`: entrega nativa de aprovação de exec no Matrix e autorização de aprovadores. - - `enabled`: `true`, `false` ou `"auto"` (padrão). No modo automático, as aprovações de exec são ativadas quando os aprovadores podem ser resolvidos a partir de `approvers` ou `commands.ownerAllowFrom`. - - `approvers`: IDs de usuário do Matrix (por exemplo `@owner:example.org`) autorizadas a aprovar solicitações de exec. - - `agentFilter`: lista de permissões opcional de IDs de agente. Omita para encaminhar aprovações para todos os agentes. +- `channels.matrix.autoJoin` usa `off` por padrão, 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 de aprovação de exec nativa do Matrix e autorização de aprovadores. + - `enabled`: `true`, `false` ou `"auto"` (padrão). No modo automático, aprovações de exec são ativadas quando os 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. + - `agentFilter`: allowlist opcional de IDs de agente. Omita para encaminhar aprovações para todos os agentes. - `sessionFilter`: padrões opcionais de chave de sessão (substring ou regex). - `target`: onde enviar prompts de aprovação. `"dm"` (padrão), `"channel"` (sala de origem) ou `"both"`. - Substituições por conta: `channels.matrix.accounts..execApprovals`. - `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. -- Sondas de status do Matrix e consultas ao diretório ao vivo usam a mesma política de proxy que o tráfego em tempo de execução. -- A configuração completa do Matrix, regras de destino e exemplos de configuração estão documentados em [Matrix](/pt-BR/channels/matrix). +- Sondas de status do Matrix e consultas ao diretório ativo usam a mesma política de proxy do tráfego em tempo de execução. +- A configuração completa do Matrix, regras de direcionamento e exemplos de configuração estão documentados em [Matrix](/pt-BR/channels/matrix). ### Microsoft Teams -O Microsoft Teams tem suporte por extensão e é configurado em `channels.msteams`. +Microsoft Teams tem suporte por extensão e é configurado em `channels.msteams`. ```json5 { @@ -694,19 +694,19 @@ O Microsoft Teams tem suporte por extensão e é configurado em `channels.msteam msteams: { enabled: true, configWrites: true, - // appId, appPassword, tenantId, webhook, políticas de equipe/canal: - // veja /channels/msteams + // appId, appPassword, tenantId, webhook, team/channel policies: + // see /channels/msteams }, }, } ``` - Caminhos de chave principais cobertos aqui: `channels.msteams`, `channels.msteams.configWrites`. -- A configuração completa do Teams (credenciais, webhook, política de DM/grupo, substituições por equipe/por canal) está documentada em [Microsoft Teams](/pt-BR/channels/msteams). +- A configuração completa do Teams (credenciais, Webhook, política de DM/grupo, substituições por equipe/por canal) está documentada em [Microsoft Teams](/pt-BR/channels/msteams). ### IRC -O IRC tem suporte por extensão e é configurado em `channels.irc`. +IRC tem suporte por extensão e é configurado em `channels.irc`. ```json5 { @@ -728,8 +728,8 @@ O IRC tem suporte por extensão e é configurado em `channels.irc`. ``` - Caminhos de chave principais cobertos aqui: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. -- `channels.irc.defaultAccount` opcional substitui a seleção da conta padrão quando corresponde a uma ID de conta configurada. -- A configuração completa do canal IRC (host/porta/TLS/canais/listas de permissões/bloqueio por menção) está documentada em [IRC](/pt-BR/channels/irc). +- `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ão/bloqueio por menção) está documentada em [IRC](/pt-BR/channels/irc). ### Várias contas (todos os canais) @@ -755,25 +755,25 @@ 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**. -- As configurações básicas 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 base 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 valores de conta única do 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 destino nomeado/padrão existente correspondente. -- Vínculos existentes apenas de 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 do nível superior com escopo de conta para a conta promovida escolhida para esse canal. A maioria dos canais usa `accounts.default`; o Matrix pode preservar um destino nomeado/padrão existente correspondente. +- 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 os move para `channels..accounts.default`; o Matrix pode preservar um alvo nomeado/padrão correspondente já existente. +- Bindings existentes apenas de canal (sem `accountId`) continuam correspondendo à conta padrão; bindings 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 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 Muitos canais de extensão são configurados como `channels.` e documentados em suas páginas dedicadas de canal (por exemplo Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat e Twitch). Consulte o índice completo de canais: [Channels](/pt-BR/channels). -### Bloqueio por menção em chats de grupo +### Bloqueio por menção em chat 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, por padrão, **exigem menção** (menção nos metadados ou padrões regex seguros). Aplica-se a chats de grupo de WhatsApp, Telegram, Discord, Google Chat e iMessage. **Tipos de menção:** -- **Menções por metadados**: @menções nativas da plataforma. Ignoradas no modo de conversa consigo mesmo do WhatsApp. +- **Menções de metadados**: menções nativas com @ da plataforma. Ignoradas no modo de conversa consigo mesmo do WhatsApp. - **Padrões de texto**: padrões regex seguros em `agents.list[].groupChat.mentionPatterns`. Padrões inválidos e repetições aninhadas inseguras são ignorados. - O bloqueio por menção só é aplicado quando a detecção é possível (menções nativas ou pelo menos um padrão). @@ -788,7 +788,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 desabilitar. +`messages.groupChat.historyLimit` define o padrão global. Os canais podem sobrescrever com `channels..historyLimit` (ou por conta). Defina `0` para desabilitar. #### Limites de histórico de DM @@ -805,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 (todos retidos). +Resolução: substituição por DM → padrão do provedor → sem limite (tudo é mantido). Compatível com: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`. #### Modo de conversa consigo mesmo -Inclua seu próprio número em `allowFrom` para habilitar o modo de conversa consigo mesmo (ignora @menções nativas, responde apenas a padrões de texto): +Inclua seu próprio número em `allowFrom` para habilitar o modo de conversa consigo mesmo (ignora menções nativas com @, responde apenas a padrões de texto): ```json5 { @@ -832,21 +832,21 @@ Inclua seu próprio número em `allowFrom` para habilitar o modo de conversa con } ``` -### Comandos (tratamento de comandos de chat) +### Comandos (tratamento de comandos no chat) ```json5 { commands: { - native: "auto", // registrar comandos nativos quando compatível - nativeSkills: "auto", // registrar comandos nativos de Skills quando compatível - text: true, // analisar /commands em mensagens de chat - bash: false, // permitir ! (alias: /bash) + 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, // permitir /config - mcp: false, // permitir /mcp - plugins: false, // permitir /plugins - debug: false, // permitir /debug - restart: true, // permitir /restart + ferramenta de reinicialização do gateway + config: false, // allow /config + mcp: false, // allow /mcp + plugins: false, // allow /plugins + debug: false, // allow /debug + restart: true, // allow /restart + gateway restart tool ownerAllowFrom: ["discord:123456789012345678"], ownerDisplay: "raw", // raw | hash ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}", @@ -861,28 +861,28 @@ Inclua seu próprio número em `allowFrom` para habilitar o modo de conversa con -- Este bloco configura superfícies de comandos. Para o catálogo atual de comandos integrados + bundled, consulte [Comandos Slash](/pt-BR/tools/slash-commands). -- Esta página é uma **referência de chaves de configuração**, não o catálogo completo de comandos. Comandos pertencentes a canais/plugins, como `/bot-ping` `/bot-help` `/bot-logs` do QQ Bot, `/card` do LINE, `/pair` do device-pair, `/dreaming` da memória, `/phone` do phone-control e `/voice` do Talk, estão documentados em suas páginas de canal/plugin e também em [Comandos Slash](/pt-BR/tools/slash-commands). -- Comandos de texto devem ser mensagens **autônomas** com `/` no início. -- `native: "auto"` ativa comandos nativos para Discord/Telegram e mantém o Slack desativado. -- `nativeSkills: "auto"` ativa comandos nativos de Skills para Discord/Telegram e mantém o Slack desativado. -- Substitua por canal com: `channels.discord.commands.native` (bool ou `"auto"`). `false` limpa comandos registrados anteriormente. +- Este bloco configura as superfícies de comando. Para o catálogo atual de comandos internos + agrupados, 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 canais/Plugins, como QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/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 desativado. +- `nativeSkills: "auto"` ativa comandos nativos de Skills para Discord/Telegram e mantém Slack desativado. +- Substituição por canal: `channels.discord.commands.native` (bool ou `"auto"`). `false` limpa comandos registrados anteriormente. - Substitua o registro nativo de Skills por canal com `channels..commands.nativeSkills`. - `channels.telegram.customCommands` adiciona entradas extras ao menu do bot do Telegram. - `bash: true` habilita `! ` para o shell do host. Requer `tools.elevated.enabled` e remetente em `tools.elevated.allowFrom.`. -- `config: true` habilita `/config` (lê/grava `openclaw.json`). Para clientes `chat.send` do Gateway, gravações persistentes com `/config set|unset` também exigem `operator.admin`; a opção somente leitura `/config show` continua disponível para clientes normais do operador com escopo de gravação. +- `config: true` habilita `/config` (lê/grava `openclaw.json`). Para clientes de gateway `chat.send`, gravações persistentes com `/config set|unset` também exigem `operator.admin`; `/config show` somente leitura continua disponível para clientes normais de operador com escopo de gravação. - `mcp: true` habilita `/mcp` para configuração de servidor MCP gerenciada pelo OpenClaw em `mcp.servers`. -- `plugins: true` habilita `/plugins` para descoberta de plugins, instalação e controles de habilitar/desabilitar. +- `plugins: true` habilita `/plugins` para descoberta de Plugin, instalação e controles de ativação/desativação. - `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 a essa conta (por exemplo `/allowlist --config --account ` ou `/config set channels..accounts....`). -- `restart: false` desabilita `/restart` e ações da ferramenta de reinicialização do Gateway. Padrão: `true`. -- `ownerAllowFrom` é a lista explícita de permissões do proprietário para comandos/ferramentas exclusivos do proprietário. Ela é separada de `allowFrom`. -- `ownerDisplay: "hash"` aplica hash às IDs do proprietário no prompt do sistema. Defina `ownerDisplaySecret` para controlar o hash. -- `allowFrom` é por provedor. Quando definido, é a **única** fonte de autorização (listas de permissões/pareamento do canal e `useAccessGroups` são ignorados). -- `useAccessGroups: false` permite que os comandos ignorem políticas de grupos de acesso quando `allowFrom` não está definido. +- Para canais com várias contas, `channels..accounts..configWrites` também controla gravações que têm essa conta como alvo (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 allowlist explícita de proprietários para comandos/ferramentas exclusivos do proprietário. É separada de `allowFrom`. +- `ownerDisplay: "hash"` aplica hash aos IDs do proprietário no prompt do sistema. Defina `ownerDisplaySecret` para controlar o hashing. +- `allowFrom` é por provedor. Quando definido, é a **única** fonte de autorização (as allowlists/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. - Mapa da documentação de comandos: - - catálogo integrado + bundled: [Comandos Slash](/pt-BR/tools/slash-commands) - - superfícies de comandos específicas de canal: [Channels](/pt-BR/channels) + - catálogo interno + agrupado: [Slash Commands](/pt-BR/tools/slash-commands) + - superfícies de comando específicas de canal: [Channels](/pt-BR/channels) - comandos do QQ Bot: [QQ Bot](/pt-BR/channels/qqbot) - comandos de pareamento: [Pairing](/pt-BR/channels/pairing) - comando de cartão do LINE: [LINE](/pt-BR/channels/line) @@ -906,7 +906,7 @@ Padrão: `~/.openclaw/workspace`. ### `agents.defaults.repoRoot` -Raiz opcional do repositório exibida 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 { @@ -916,7 +916,7 @@ Raiz opcional do repositório exibida na linha Runtime do prompt do sistema. Se ### `agents.defaults.skills` -Lista de permissões padrão opcional de Skills para agentes que não definem +Allowlist padrão opcional de Skills para agentes que não definem `agents.list[].skills`. ```json5 @@ -924,9 +924,9 @@ Lista de permissões padrão opcional de Skills para agentes que não definem agents: { defaults: { 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 ], }, } @@ -935,7 +935,7 @@ Lista de permissões padrão opcional de Skills para agentes que não definem - Omita `agents.defaults.skills` para Skills irrestritas por padrão. - Omita `agents.list[].skills` para herdar os padrões. - Defina `agents.list[].skills: []` para nenhuma Skill. -- Uma lista não vazia em `agents.list[].skills` é o conjunto final para esse agente; ela +- Uma lista não vazia em `agents.list[].skills` é o conjunto final desse agente; ela não é mesclada com os padrões. ### `agents.defaults.skipBootstrap` @@ -950,9 +950,9 @@ Desabilita a criação automática de arquivos bootstrap do workspace (`AGENTS.m ### `agents.defaults.contextInjection` -Controla quando os arquivos bootstrap do workspace são injetados no prompt do sistema. Padrão: `"always"`. +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 concluída do assistente) pulam a reinjeção do bootstrap do workspace, reduzindo o tamanho do prompt. Execuções de Heartbeat e novas tentativas após Compaction ainda reconstroem 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 Compaction ainda recriam o contexto. ```json5 { @@ -962,7 +962,7 @@ Controla quando os arquivos bootstrap do workspace são injetados no prompt do s ### `agents.defaults.bootstrapMaxChars` -Máximo de caracteres por arquivo bootstrap do workspace antes do truncamento. Padrão: `20000`. +Máximo de caracteres por arquivo bootstrap do workspace antes de truncamento. Padrão: `20000`. ```json5 { @@ -995,12 +995,148 @@ Padrão: `"once"`. } ``` +### Mapa de propriedade do orçamento de contexto + +O OpenClaw tem vários orçamentos de prompt/contexto de alto volume, e eles são +intencionalmente divididos por subsistema em vez de todos passarem por um único +ajuste genérico. + +- `agents.defaults.bootstrapMaxChars` / + `agents.defaults.bootstrapTotalMaxChars`: + injeção normal de bootstrap do workspace. +- `agents.defaults.startupContext.*`: + prelúdio de inicialização de uso único em `/new` e `/reset`, incluindo arquivos + recentes `memory/*.md` diários. +- `skills.limits.*`: + a lista compacta de Skills injetada no prompt do sistema. +- `agents.defaults.contextLimits.*`: + trechos limitados em tempo de execução e blocos injetados pertencentes ao runtime. +- `memory.qmd.limits.*`: + indexação de trechos de pesquisa de memória e dimensionamento de injeção. + +Use a substituição correspondente por agente apenas quando um agente precisar de +um orçamento diferente: + +- `agents.list[].skillsLimits.maxSkillsPromptChars` +- `agents.list[].contextLimits.*` + +#### `agents.defaults.startupContext` + +Controla o prelúdio de inicialização do primeiro turno injetado em execuções +simples de `/new` e `/reset`. + +```json5 +{ + agents: { + defaults: { + startupContext: { + enabled: true, + applyOn: ["new", "reset"], + dailyMemoryDays: 2, + maxFileBytes: 16384, + maxFileChars: 1200, + maxTotalChars: 2800, + }, + }, + }, +} +``` + +#### `agents.defaults.contextLimits` + +Padrões compartilhados para superfícies de contexto limitadas em tempo de execução. + +```json5 +{ + agents: { + defaults: { + contextLimits: { + memoryGetMaxChars: 12000, + memoryGetDefaultLines: 120, + toolResultMaxChars: 16000, + postCompactionMaxChars: 1800, + }, + }, + }, +} +``` + +- `memoryGetMaxChars`: limite padrão de trecho de `memory_get` antes que metadados + de truncamento e aviso de continuação sejam adicionados. +- `memoryGetDefaultLines`: janela padrão de linhas de `memory_get` quando `lines` é + omitido. +- `toolResultMaxChars`: limite de resultado de ferramenta em tempo real usado para + resultados persistidos e recuperação de overflow. +- `postCompactionMaxChars`: limite de trecho de `AGENTS.md` usado durante injeção + de atualização pós-Compaction. + +#### `agents.list[].contextLimits` + +Substituição por agente para os ajustes compartilhados de `contextLimits`. Campos omitidos herdam +de `agents.defaults.contextLimits`. + +```json5 +{ + agents: { + defaults: { + contextLimits: { + memoryGetMaxChars: 12000, + toolResultMaxChars: 16000, + }, + }, + list: [ + { + id: "tiny-local", + contextLimits: { + memoryGetMaxChars: 6000, + toolResultMaxChars: 8000, + }, + }, + ], + }, +} +``` + +#### `skills.limits.maxSkillsPromptChars` + +Limite global para a lista compacta de Skills injetada no prompt do sistema. Isso +não afeta a leitura de arquivos `SKILL.md` sob demanda. + +```json5 +{ + skills: { + limits: { + maxSkillsPromptChars: 18000, + }, + }, +} +``` + +#### `agents.list[].skillsLimits.maxSkillsPromptChars` + +Substituição por agente para o orçamento de prompt de Skills. + +```json5 +{ + agents: { + list: [ + { + id: "tiny-local", + skillsLimits: { + maxSkillsPromptChars: 6000, + }, + }, + ], + }, +} +``` + ### `agents.defaults.imageMaxDimensionPx` -Tamanho máximo em pixels do lado mais longo da imagem em blocos de imagem de transcrição/ferramenta antes de 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 tokens de visão e o tamanho da carga útil da solicitação em execuções com muitas capturas de tela. +Valores menores normalmente reduzem o uso de tokens de visão e o tamanho da carga da requisição em execuções com muitas capturas de tela. Valores maiores preservam mais detalhes visuais. ```json5 @@ -1011,7 +1147,7 @@ Valores maiores preservam mais detalhes visuais. ### `agents.defaults.userTimezone` -Fuso horário para o contexto do prompt do sistema (não para timestamps de mensagens). Usa o fuso horário do host como fallback. +Fuso horário para o contexto do prompt do sistema (não para timestamps de mensagens). Usa como fallback o fuso horário do host. ```json5 { @@ -1059,9 +1195,9 @@ Formato de hora no prompt do sistema. Padrão: `auto` (preferência do SO). primary: "anthropic/claude-opus-4-6", fallbacks: ["openai/gpt-5.4-mini"], }, - params: { cacheRetention: "long" }, // parâmetros globais padrão do provedor + params: { cacheRetention: "long" }, // global default provider params embeddedHarness: { - runtime: "auto", // auto | pi | id de harness registrado, por exemplo codex + runtime: "auto", // auto | pi | registered harness id, e.g. codex fallback: "pi", // pi | none }, pdfMaxBytesMb: 10, @@ -1079,48 +1215,48 @@ Formato de hora no prompt do sistema. Padrão: `auto` (preferência do SO). ``` - `model`: aceita uma string (`"provider/model"`) ou um objeto (`{ primary, fallbacks }`). - - A forma em string define apenas o modelo primário. - - A forma em objeto define o primário mais modelos de failover em ordem. + - A forma string define apenas o modelo principal. + - A forma objeto define o principal mais modelos de failover ordenados. - `imageModel`: aceita uma string (`"provider/model"`) ou um objeto (`{ primary, fallbacks }`). - - Usado pelo caminho da ferramenta `image` como sua configuração de modelo de visão. - - Também usado como roteamento de fallback quando o modelo selecionado/padrão não aceita entrada de imagem. + - 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 pode aceitar entrada de imagem. - `imageGenerationModel`: aceita uma string (`"provider/model"`) ou um objeto (`{ primary, fallbacks }`). - - Usado pela capacidade compartilhada de geração de imagem e por 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. - - 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 demais provedores de geração de imagem registrados, na ordem do ID do provedor. + - Usado pela capacidade compartilhada de geração de imagem e por 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. + - Se você selecionar um provedor/modelo diretamente, 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 provedor padrão com autenticação configurada. Ele tenta primeiro o provedor padrão atual e depois os demais provedores de geração de imagem registrados, na ordem do 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`. + - Usado pela capacidade compartilhada de geração de música e pela ferramenta interna `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 demais provedores de geração de música registrados, na ordem do ID do provedor. - - Se você selecionar diretamente um provider/model, configure também a autenticação/chave de API correspondente do provedor. + - Se omitido, `music_generate` ainda pode inferir um provedor padrão com autenticação configurada. Ele tenta primeiro o provedor padrão atual e depois os demais provedores de geração de música registrados, na ordem do ID do provedor. + - Se você selecionar um provedor/modelo diretamente, 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`. + - Usado pela capacidade compartilhada de geração de vídeo e pela ferramenta interna `video_generate`. - Valores típicos: `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash` ou `qwen/wan2.7-r2v`. - - Se omitido, `video_generate` ainda pode inferir um padrão de provedor com autenticação. Ele tenta primeiro o provedor padrão atual e depois os demais provedores de geração de vídeo registrados, na ordem do ID do provedor. - - Se você selecionar diretamente um provider/model, configure também a autenticação/chave de API correspondente do provedor. - - O provedor bundled de geração de vídeo Qwen 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 em nível de provedor `size`, `aspectRatio`, `resolution`, `audio` e `watermark`. + - Se omitido, `video_generate` ainda pode inferir um provedor padrão com autenticação configurada. Ele tenta primeiro o provedor padrão atual e depois os demais provedores de geração de vídeo registrados, na ordem do ID do provedor. + - Se você selecionar um provedor/modelo diretamente, configure também a autenticação/chave de API correspondente do provedor. + - O provedor agrupado de geração de vídeo Qwen 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 }`). - 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 usa `imageModel` como fallback e, depois, o modelo resolvido da sessão/padrão. - `pdfMaxBytesMb`: limite padrão de tamanho de PDF para a ferramenta `pdf` quando `maxBytesMb` não é passado no momento da chamada. - `pdfMaxPages`: máximo padrão de páginas consideradas pelo modo de fallback de extração na ferramenta `pdf`. -- `verboseDefault`: nível padrão de verbosidade para agentes. Valores: `"off"`, `"on"`, `"full"`. Padrão: `"off"`. +- `verboseDefault`: nível verbose padrão 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 provider/model configurado em vez de expor um padrão obsoleto de provedor removido. -- `models`: o catálogo de modelos configurado e a lista de permissões para `/model`. Cada entrada pode incluir `alias` (atalho) e `params` (específicos do provedor, por exemplo `temperature`, `maxTokens`, `cacheRetention`, `context1m`). +- `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 usa o provedor padrão configurado como fallback (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 usa o primeiro provedor/modelo configurado como fallback em vez de expor um padrão obsoleto de provedor removido. +- `models`: o catálogo de modelos configurado e a allowlist para `/model`. Cada entrada pode incluir `alias` (atalho) e `params` (específicos do provedor, por exemplo `temperature`, `maxTokens`, `cacheRetention`, `context1m`). - `params`: parâmetros globais padrão do provedor aplicados a todos os modelos. Defina 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), depois `agents.list[].params` (ID de agente correspondente) substitui por chave. Consulte [Prompt Caching](/pt-BR/reference/prompt-caching) para detalhes. -- `embeddedHarness`: política padrão de runtime embutido de baixo nível para agentes. Use `runtime: "auto"` para permitir que harnesses de plugins registrados assumam modelos compatíveis, `runtime: "pi"` para forçar o harness PI integrado ou um ID de harness registrado, como `runtime: "codex"`. Defina `fallback: "none"` para desabilitar o fallback automático para PI. -- 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 em objeto e preservam listas de fallback existentes quando possível. +- Precedência de mesclagem de `params` (config): `agents.defaults.params` (base global) é sobrescrito por `agents.defaults.models["provider/model"].params` (por modelo), depois `agents.list[].params` (ID de agente correspondente) sobrescreve por chave. Consulte [Prompt Caching](/pt-BR/reference/prompt-caching) para detalhes. +- `embeddedHarness`: política padrão de runtime de agente embutido de baixo nível. Use `runtime: "auto"` para permitir que harnesses de Plugin registrados assumam modelos compatíveis, `runtime: "pi"` para forçar o harness PI interno, ou um ID de harness registrado, como `runtime: "codex"`. Defina `fallback: "none"` para desabilitar o fallback automático para PI. +- 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 ainda é serializada). Padrão: 4. ### `agents.defaults.embeddedHarness` `embeddedHarness` controla qual executor de baixo nível executa turnos de agentes embutidos. A maioria das implantações deve manter o padrão `{ runtime: "auto", fallback: "pi" }`. -Use-o quando um plugin confiável fornecer um harness nativo, como o harness -bundled do servidor de app Codex. +Use-o quando um Plugin confiável fornecer um harness nativo, como o harness +agrupado do servidor de app Codex. ```json5 { @@ -1136,13 +1272,13 @@ bundled do servidor de app Codex. } ``` -- `runtime`: `"auto"`, `"pi"` ou um ID de harness de plugin registrado. O Plugin bundled Codex registra `codex`. -- `fallback`: `"pi"` ou `"none"`. `"pi"` mantém o harness PI integrado como fallback de compatibilidade. `"none"` faz com que a seleção de harness de plugin ausente ou não compatível falhe em vez de usar silenciosamente o PI. -- Substituições por ambiente: `OPENCLAW_AGENT_RUNTIME=` substitui `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=none` desabilita o fallback para PI nesse processo. +- `runtime`: `"auto"`, `"pi"` ou um ID de harness de Plugin registrado. O Plugin agrupado Codex registra `codex`. +- `fallback`: `"pi"` ou `"none"`. `"pi"` mantém o harness PI interno como fallback de compatibilidade. `"none"` faz com que a seleção ausente ou incompatível de harness de Plugin falhe em vez de usar PI silenciosamente. +- Substituições por ambiente: `OPENCLAW_AGENT_RUNTIME=` sobrescreve `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=none` desabilita o fallback para PI nesse processo. - Para implantações somente com Codex, defina `model: "codex/gpt-5.4"`, `embeddedHarness.runtime: "codex"` e `embeddedHarness.fallback: "none"`. -- Isso controla apenas o harness de chat embutido. Geração de mídia, visão, PDF, música, vídeo e TTS ainda usam suas configurações de provider/model. +- Isso controla apenas o harness de chat embutido. Geração de mídia, visão, PDF, música, vídeo e TTS continuam usando suas configurações de provedor/modelo. -**Atalhos de alias integrados** (só se aplicam quando o modelo está em `agents.defaults.models`): +**Atalhos de alias internos** (aplicam-se apenas quando o modelo está em `agents.defaults.models`): | Alias | Modelo | | ------------------- | -------------------------------------- | @@ -1155,15 +1291,15 @@ bundled do servidor de app Codex. | `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 GLM-4.x da Z.AI habilitam 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 GLM-4.x habilitam automaticamente o modo thinking, a menos que você defina `--thinking off` ou configure `agents.defaults.models["zai/"].params.thinking` manualmente. Modelos Z.AI habilitam `tool_stream` por padrão para streaming de chamadas de ferramenta. Defina `agents.defaults.models["zai/"].params.tool_stream` como `false` para desabilitá-lo. -Modelos Claude 4.6 da Anthropic usam `adaptive` thinking por padrão quando nenhum nível explícito de thinking é definido. +Modelos Anthropic Claude 4.6 usam `adaptive` como padrão para thinking quando nenhum nível explícito de thinking é 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 { @@ -1191,13 +1327,13 @@ Backends opcionais de CLI para execuções de fallback somente texto (sem chamad } ``` -- Backends de CLI são orientados a texto; ferramentas são sempre desabilitadas. +- Backends de CLI são voltados a texto; ferramentas são sempre desabilitadas. - Sessões são compatíveis quando `sessionArg` está definido. -- Passagem de imagem é compatível quando `imageArg` aceita caminhos de arquivo. +- Repasse de imagem é compatível quando `imageArg` aceita caminhos de arquivo. ### `agents.defaults.systemPromptOverride` -Substitui todo o prompt do sistema montado pelo OpenClaw por uma string fixa. Defina no nível padrão (`agents.defaults.systemPromptOverride`) ou por agente (`agents.list[].systemPromptOverride`). Valores por agente têm precedência; um valor vazio ou só com espaços é ignorado. Útil para experimentos controlados de prompt. +Substitui todo o prompt do sistema montado pelo OpenClaw por uma string fixa. Defina no nível padrão (`agents.defaults.systemPromptOverride`) ou por agente (`agents.list[].systemPromptOverride`). Valores por agente têm precedência; um valor vazio ou apenas com espaços em branco é ignorado. Útil para experimentos controlados de prompt. ```json5 { @@ -1218,16 +1354,16 @@ Execuções periódicas de Heartbeat. agents: { defaults: { heartbeat: { - every: "30m", // 0m desabilita + every: "30m", // 0m disables model: "openai/gpt-5.4-mini", includeReasoning: false, - includeSystemPromptSection: true, // padrão: true; false omite a seção Heartbeat do prompt do sistema - lightContext: false, // padrão: false; true mantém apenas HEARTBEAT.md dos arquivos bootstrap do workspace - isolatedSession: false, // padrão: false; true executa cada Heartbeat em uma sessão nova (sem histórico de conversa) + includeSystemPromptSection: true, // default: true; false omits the Heartbeat section from the system prompt + lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files + isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history) session: "main", to: "+15555550123", - directPolicy: "allow", // allow (padrão) | block - target: "none", // padrão: none | opções: last | whatsapp | telegram | discord | ... + directPolicy: "allow", // allow (default) | block + target: "none", // default: none | options: last | whatsapp | telegram | discord | ... prompt: "Read HEARTBEAT.md if it exists...", ackMaxChars: 300, suppressToolErrorWarnings: false, @@ -1239,12 +1375,12 @@ 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 desabilitar. -- `includeSystemPromptSection`: quando false, omite a seção Heartbeat do prompt do sistema e pula a injeção de `HEARTBEAT.md` no contexto bootstrap. Padrão: `true`. -- `suppressToolErrorWarnings`: quando true, suprime cargas úteis de aviso de erro de ferramenta durante execuções de Heartbeat. -- `timeoutSeconds`: tempo máximo em segundos permitido para um turno de agente do Heartbeat antes de ele ser abortado. Deixe sem definir para usar `agents.defaults.timeoutSeconds`. +- `includeSystemPromptSection`: quando false, omite a seção Heartbeat do prompt do sistema e ignora a injeção de `HEARTBEAT.md` no contexto bootstrap. Padrão: `true`. +- `suppressToolErrorWarnings`: quando true, suprime cargas de aviso de erro de ferramenta durante execuções de Heartbeat. +- `timeoutSeconds`: tempo máximo em segundos permitido para um turno de agente de Heartbeat antes de ser abortado. Deixe sem definir para usar `agents.defaults.timeoutSeconds`. - `directPolicy`: política de entrega direta/DM. `allow` (padrão) permite entrega com alvo direto. `block` suprime entrega com 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 é executado em uma sessão nova, sem histórico de conversa anterior. Mesmo padrão de isolamento que o Cron `sessionTarget: "isolated"`. Reduz o custo de tokens por Heartbeat de ~100K para ~2-5K tokens. +- `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 Heartbeat é executado 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. - Por agente: defina `agents.list[].heartbeat`. Quando qualquer agente define `heartbeat`, **apenas esses agentes** executam Heartbeat. - Heartbeats executam turnos completos de agente — intervalos menores consomem mais tokens. @@ -1256,14 +1392,14 @@ Execuções periódicas de Heartbeat. defaults: { compaction: { mode: "safeguard", // default | safeguard - provider: "my-provider", // id de um Plugin de provedor de Compaction registrado (opcional) + provider: "my-provider", // id of a registered compaction provider plugin (optional) timeoutSeconds: 900, reserveTokensFloor: 24000, identifierPolicy: "strict", // strict | off | custom - identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // usado quando identifierPolicy=custom - postCompactionSections: ["Session Startup", "Red Lines"], // [] desabilita a reinjeção - model: "openrouter/anthropic/claude-sonnet-4-6", // substituição opcional de modelo apenas para Compaction - notifyUser: true, // envia um aviso breve quando a Compaction começa (padrão: false) + identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // used when identifierPolicy=custom + postCompactionSections: ["Session Startup", "Red Lines"], // [] disables reinjection + model: "openrouter/anthropic/claude-sonnet-4-6", // optional compaction-only model override + notifyUser: true, // send a brief notice when compaction starts (default: false) memoryFlush: { enabled: true, softThresholdTokens: 6000, @@ -1277,18 +1413,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 Compaction registrado. Quando definido, o `summarize()` do provedor é chamado em vez da sumarização LLM integrada. Em caso de falha, recorre à integrada. Definir um provedor força `mode: "safeguard"`. Consulte [Compaction](/pt-BR/concepts/compaction). +- `provider`: id de um Plugin de provedor de Compaction registrado. Quando definido, o `summarize()` do provedor é chamado em vez da sumarização interna por LLM. Em caso de falha, usa o interno como fallback. 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 Compaction antes de o OpenClaw abortá-la. Padrão: `900`. -- `identifierPolicy`: `strict` (padrão), `off` ou `custom`. `strict` prefixa a orientação integrada de retenção de identificadores opacos durante a sumarização de Compaction. -- `identifierInstructions`: texto personalizado opcional de preservação de identificadores usado quando `identifierPolicy=custom`. -- `postCompactionSections`: nomes opcionais de seções H2/H3 de AGENTS.md para reinjetar após a Compaction. O padrão é `["Session Startup", "Red Lines"]`; defina `[]` para desabilitar a reinjeção. Quando não definido ou definido explicitamente como 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 sumarização de Compaction. Use isso quando a sessão principal deve manter um modelo, mas os resumos de Compaction devem ser executados em outro; quando não definido, a Compaction usa o modelo primário da sessão. +- `identifierPolicy`: `strict` (padrão), `off` ou `custom`. `strict` adiciona orientação interna de retenção de identificadores opacos durante a sumarização de Compaction. +- `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 Compaction. O padrão é `["Session Startup", "Red Lines"]`; defina `[]` para desabilitar a reinjeção. Quando não definido ou explicitamente definido para esse par padrão, os títulos antigos `Every Session`/`Safety` também são aceitos como fallback legado. +- `model`: substituição opcional `provider/model-id` apenas para sumarização de Compaction. Use isto quando a sessão principal deve manter um modelo, mas os resumos de Compaction devem usar outro; quando não definido, a Compaction usa o modelo principal da sessão. - `notifyUser`: quando `true`, envia um aviso breve ao usuário quando a Compaction começa (por exemplo, "Compacting context..."). Desabilitado por padrão para manter a Compaction silenciosa. -- `memoryFlush`: turno silencioso e agentic antes da Compaction automática para armazenar memórias duráveis. Ignorado quando o workspace está em modo somente leitura. +- `memoryFlush`: turno agentivo silencioso antes da Compaction automática 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 enviar para o LLM. **Não** modifica o histórico da sessão em disco. +Remove **resultados antigos de ferramentas** do contexto em memória antes do envio ao LLM. **Não** modifica o histórico da sessão em disco. ```json5 { @@ -1296,7 +1432,7 @@ Remove **resultados antigos de ferramentas** do contexto em memória antes de en defaults: { contextPruning: { mode: "cache-ttl", // off | cache-ttl - ttl: "1h", // duração (ms/s/m/h), unidade padrão: minutos + ttl: "1h", // duration (ms/s/m/h), default unit: minutes keepLastAssistants: 3, softTrimRatio: 0.3, hardClearRatio: 0.5, @@ -1312,23 +1448,23 @@ Remove **resultados antigos de ferramentas** do contexto em memória antes de en -- `mode: "cache-ttl"` habilita passagens de limpeza. -- `ttl` controla com que frequência a limpeza pode ser executada novamente (após o último toque no cache). -- A limpeza primeiro faz truncamento suave de resultados de ferramenta grandes demais, depois limpa totalmente resultados de ferramenta mais antigos, se necessário. +- `mode: "cache-ttl"` habilita passagens de remoção. +- `ttl` controla com que frequência a remoção pode ser executada novamente (após o último toque de cache). +- A remoção primeiro faz truncamento leve de resultados de ferramenta superdimensionados, depois limpa integralmente resultados de ferramenta mais antigos, se necessário. -**Soft-trim** mantém o início + o fim e insere `...` no meio. +**Truncamento leve** mantém o começo + fim e insere `...` no meio. -**Hard-clear** substitui o resultado inteiro da ferramenta pelo placeholder. +**Limpeza integral** substitui todo o resultado da ferramenta pelo placeholder. Observações: - 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 limpeza será ignorada. +- Se existirem menos de `keepLastAssistants` mensagens do assistente, a remoção é ignorada. -Consulte [Session Pruning](/pt-BR/concepts/session-pruning) para detalhes de comportamento. +Consulte [Session Pruning](/pt-BR/concepts/session-pruning) para detalhes do comportamento. ### Streaming em blocos @@ -1346,8 +1482,8 @@ Consulte [Session Pruning](/pt-BR/concepts/session-pruning) para detalhes de com } ``` -- 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`. +- Canais que não sejam 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 `minChars: 1500` por padrão. - `humanDelay`: pausa aleatória entre respostas em bloco. `natural` = 800–2500ms. Substituição por agente: `agents.list[].humanDelay`. Consulte [Streaming](/pt-BR/concepts/streaming) para detalhes de comportamento + fragmentação. @@ -1420,7 +1556,7 @@ Sandbox opcional para o agente embutido. Consulte [Sandboxing](/pt-BR/gateway/sa identityFile: "~/.ssh/id_ed25519", certificateFile: "~/.ssh/id_ed25519-cert.pub", knownHostsFile: "~/.ssh/known_hosts", - // SecretRefs / conteúdos embutidos também são compatíveis: + // SecretRefs / inline contents also supported: // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" }, // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" }, // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" }, @@ -1474,7 +1610,7 @@ Sandbox opcional para o agente embutido. Consulte [Sandboxing](/pt-BR/gateway/sa **Backend:** - `docker`: runtime local do Docker (padrão) -- `ssh`: runtime remoto genérico com suporte de SSH +- `ssh`: runtime remoto genérico com suporte via SSH - `openshell`: runtime OpenShell Quando `backend: "openshell"` é selecionado, as configurações específicas de runtime passam para @@ -1482,32 +1618,32 @@ Quando `backend: "openshell"` é selecionado, as configurações específicas de **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 para o OpenSSH +- `identityFile` / `certificateFile` / `knownHostsFile`: arquivos locais existentes passados ao OpenSSH - `identityData` / `certificateData` / `knownHostsData`: conteúdos embutidos 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 +- `strictHostKeyChecking` / `updateHostKeys`: ajustes de política de chave de host do OpenSSH **Precedência de autenticação SSH:** -- `identityData` tem precedência sobre `identityFile` -- `certificateData` tem precedência sobre `certificateFile` -- `knownHostsData` tem precedência sobre `knownHostsFile` -- Valores `*Data` com suporte de SecretRef são resolvidos a partir do snapshot ativo do runtime de segredos antes de a sessão sandbox começar +- `identityData` tem prioridade sobre `identityFile` +- `certificateData` tem prioridade sobre `certificateFile` +- `knownHostsData` tem prioridade sobre `knownHostsFile` +- Valores `*Data` com suporte de SecretRef são resolvidos a partir do snapshot ativo do runtime de segredos antes do início da sessão do sandbox **Comportamento do backend SSH:** -- semeia 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 por SSH - não sincroniza automaticamente alterações remotas de volta para o host -- não é compatível com contêineres de navegador em sandbox +- não oferece suporte a contêineres de navegador do sandbox **Acesso ao workspace:** -- `none`: workspace sandbox por escopo em `~/.openclaw/sandboxes` -- `ro`: workspace sandbox em `/workspace`, workspace do agente montado como somente leitura em `/agent` +- `none`: workspace do sandbox por escopo em `~/.openclaw/sandboxes` +- `ro`: workspace do sandbox em `/workspace`, workspace do agente montado como somente leitura em `/agent` - `rw`: workspace do agente montado com leitura/gravação em `/workspace` **Escopo:** @@ -1529,10 +1665,10 @@ Quando `backend: "openshell"` é selecionado, as configurações específicas de from: "openclaw", remoteWorkspaceDir: "/sandbox", remoteAgentWorkspaceDir: "/agent", - gateway: "lab", // opcional - gatewayEndpoint: "https://lab.example", // opcional - policy: "strict", // id de política OpenShell opcional - providers: ["openai"], // opcional + gateway: "lab", // optional + gatewayEndpoint: "https://lab.example", // optional + policy: "strict", // optional OpenShell policy id + providers: ["openai"], // optional autoProviders: true, timeoutSeconds: 120, }, @@ -1544,30 +1680,30 @@ Quando `backend: "openshell"` é selecionado, as configurações específicas de **Modo OpenShell:** -- `mirror`: semeia o remoto a partir do local antes do exec, sincroniza de volta após o exec; o workspace local permanece canônico -- `remote`: semeia o remoto uma vez quando o sandbox é criado, 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 depois mantém o workspace remoto como canônico -No modo `remote`, edições locais no host feitas fora do OpenClaw não são sincronizadas automaticamente para o sandbox após a etapa de semeadura. -O transporte é SSH para dentro do sandbox OpenShell, mas o Plugin é o proprietário do ciclo de vida do sandbox e da sincronização espelho opcional. +No modo `remote`, edições locais no host feitas fora do OpenClaw não são sincronizadas automaticamente com o sandbox após a etapa inicial de semeadura. +O transporte é feito por SSH para o sandbox OpenShell, mas o Plugin é o responsável pelo ciclo de vida do sandbox e pela sincronização opcional em espelho. -**`setupCommand`** é executado uma vez após a criação do contêiner (via `sh -lc`). Precisa de saída de rede, raiz gravável e usuário root. +**`setupCommand`** é executado uma vez após a criação do contêiner (via `sh -lc`). Requer saída de rede, raiz gravável e usuário root. -**Contêineres usam por padrão `network: "none"`** — defina como `"bridge"` (ou uma rede bridge personalizada) se o agente precisar de acesso de saída. +**Contêineres usam `network: "none"` por padrão** — defina `"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` (modo de emergência). +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (modo break-glass). **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 requer `browser.enabled` em `openclaw.json`. -O acesso de 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). +O acesso de 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 em sandbox de direcionarem para o navegador do host. -- `network` usa por padrão `openclaw-sandbox-browser` (rede bridge dedicada). Defina como `bridge` apenas quando quiser explicitamente conectividade global de 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 em sandbox. Quando definido (inclusive `[]`), ele 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 com contêiner: +- `allowHostControl: false` (padrão) impede que sessões em sandbox tenham como alvo o navegador do host. +- `network` usa `openclaw-sandbox-browser` como padrão (rede bridge dedicada). Defina `bridge` apenas quando quiser explicitamente conectividade global de bridge. +- `cdpSourceRange` restringe opcionalmente a entrada do 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 com contêineres: - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` @@ -1593,18 +1729,17 @@ O acesso de observador via noVNC usa autenticação VNC por padrão, e o OpenCla - `--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` estiver habilitado. - - Os padrões são a baseline da imagem do contêiner; use uma imagem de navegador personalizada com um entrypoint - personalizado para alterar os padrões do contêiner. + - além de `--no-sandbox` e `--disable-setuid-sandbox` quando `noSandbox` está 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. -O sandbox de navegador e `sandbox.docker.binds` são compatíveis apenas com Docker. +Sandbox de navegador e `sandbox.docker.binds` são compatíveis apenas com Docker. Criar imagens: ```bash -scripts/sandbox-setup.sh # imagem principal de sandbox +scripts/sandbox-setup.sh # imagem principal do sandbox scripts/sandbox-browser-setup.sh # imagem opcional do navegador ``` @@ -1620,13 +1755,13 @@ scripts/sandbox-browser-setup.sh # imagem opcional do navegador name: "Main Agent", workspace: "~/.openclaw/workspace", agentDir: "~/.openclaw/agents/main/agent", - model: "anthropic/claude-opus-4-6", // ou { primary, fallbacks } - thinkingDefault: "high", // substituição por agente para nível de thinking - reasoningDefault: "on", // substituição por agente para visibilidade de reasoning - fastModeDefault: false, // substituição por agente para fast mode + model: "anthropic/claude-opus-4-6", // or { primary, fallbacks } + thinkingDefault: "high", // per-agent thinking level override + reasoningDefault: "on", // per-agent reasoning visibility override + fastModeDefault: false, // per-agent fast mode override embeddedHarness: { runtime: "auto", fallback: "pi" }, - params: { cacheRetention: "none" }, // substitui por chave os params correspondentes de defaults.models - skills: ["docs-search"], // substitui agents.defaults.skills quando definido + params: { cacheRetention: "none" }, // overrides matching defaults.models params by key + skills: ["docs-search"], // replaces agents.defaults.skills when set identity: { name: "Samantha", theme: "helpful sloth", @@ -1658,20 +1793,20 @@ scripts/sandbox-browser-setup.sh # imagem opcional do navegador ``` - `id`: ID estável do agente (obrigatório). -- `default`: quando vários são definidos, o primeiro prevalece (um aviso é registrado). Se nenhum for definido, a primeira entrada da lista é o padrão. -- `model`: a forma em string substitui apenas `primary`; a forma em objeto `{ primary, fallbacks }` substitui ambos (`[]` desabilita fallbacks globais). Tarefas de Cron que substituem apenas `primary` ainda herdam fallbacks padrão, a menos que você defina `fallbacks: []`. -- `params`: params de stream por agente, mesclados sobre a entrada do modelo selecionado 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 de permissões opcional de Skills por agente. Se omitida, o agente herda `agents.defaults.skills` quando definido; uma lista explícita substitui os padrões em vez de mesclar, e `[]` significa nenhuma Skill. -- `thinkingDefault`: substituição opcional por agente para o nível padrão de thinking (`off | minimal | low | medium | high | xhigh | adaptive`). Substitui `agents.defaults.thinkingDefault` para esse agente quando não há substituição por mensagem ou sessão. -- `reasoningDefault`: substituição opcional por agente para a visibilidade padrão de reasoning (`on | off | stream`). Aplica-se quando não há substituição de reasoning por mensagem ou sessão. +- `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 (`[]` desabilita 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`: allowlist opcional de Skills por agente. Se omitido, 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 esse agente 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 de reasoning por mensagem ou sessão. - `fastModeDefault`: padrão opcional por agente para fast mode (`true | false`). Aplica-se quando não há substituição de fast mode por mensagem ou sessão. -- `embeddedHarness`: substituição opcional por agente para a política de harness de baixo nível. Use `{ runtime: "codex", fallback: "none" }` para tornar um agente somente Codex enquanto outros agentes mantêm o fallback padrão para PI. -- `runtime`: descritor opcional de runtime por agente. Use `type: "acp"` com padrões em `runtime.acp` (`agent`, `backend`, `mode`, `cwd`) quando o agente deve usar por padrão sessões de harness ACP. +- `embeddedHarness`: substituição opcional por agente da política de harness de baixo nível. Use `{ runtime: "codex", fallback: "none" }` para tornar um agente exclusivo do Codex enquanto outros agentes mantêm o fallback PI padrão. +- `runtime`: descritor opcional de runtime por agente. Use `type: "acp"` com padrões em `runtime.acp` (`agent`, `backend`, `mode`, `cwd`) quando o agente deve usar sessões de harness ACP por padrão. - `identity.avatar`: caminho relativo ao workspace, URL `http(s)` ou URI `data:`. -- `identity` deriva padrões: `ackReaction` de `emoji`, `mentionPatterns` de `name`/`emoji`. -- `subagents.allowAgents`: lista de permissões de IDs de agente para `sessions_spawn` (`["*"]` = qualquer; padrão: apenas o mesmo agente). +- `identity` deriva padrões: `ackReaction` a partir de `emoji`, `mentionPatterns` a partir de `name`/`emoji`. +- `subagents.allowAgents`: allowlist de IDs de agente 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 seriam executados sem sandbox. -- `subagents.requireAgentId`: quando true, bloqueia chamadas de `sessions_spawn` que omitem `agentId` (força seleção explícita de perfil; padrão: false). +- `subagents.requireAgentId`: quando true, bloqueia chamadas `sessions_spawn` que omitem `agentId` (força seleção explícita de perfil; padrão: false). --- @@ -1696,25 +1831,25 @@ Execute vários agentes isolados dentro de um Gateway. Consulte [Multi-Agent](/p ### Campos de correspondência de binding -- `type` (opcional): `route` para roteamento normal (a ausência de type usa route por padrão), `acp` para vínculos persistentes de conversa ACP. +- `type` (opcional): `route` para roteamento normal (a ausência de type usa route como padrão), `acp` para bindings persistentes de conversa ACP. - `match.channel` (obrigatório) - `match.accountId` (opcional; `*` = qualquer conta; omitido = conta padrão) - `match.peer` (opcional; `{ kind: direct|group|channel, id }`) -- `match.guildId` / `match.teamId` (opcional; específico do canal) -- `acp` (opcional; somente para entradas `type: "acp"`): `{ mode, label, cwd, backend }` +- `match.guildId` / `match.teamId` (opcional; específicos do canal) +- `acp` (opcional; apenas para entradas `type: "acp"`): `{ mode, label, cwd, backend }` **Ordem determinística de correspondência:** 1. `match.peer` 2. `match.guildId` 3. `match.teamId` -4. `match.accountId` (exato, sem peer/guild/team) +4. `match.accountId` (exata, sem peer/guild/team) 5. `match.accountId: "*"` (em todo o canal) 6. Agente padrão -Dentro de cada camada, a primeira entrada correspondente em `bindings` prevalece. +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 camadas de binding de rota acima. +Para entradas `type: "acp"`, o OpenClaw resolve pela identidade exata da conversa (`match.channel` + conta + `match.peer.id`) e não usa a ordem de níveis de bindings de rota acima. ### Perfis de acesso por agente @@ -1765,7 +1900,7 @@ Para entradas `type: "acp"`, o OpenClaw resolve pela identidade exata da convers - + ```json5 { @@ -1837,22 +1972,22 @@ Consulte [Multi-Agent Sandbox & Tools](/pt-BR/tools/multi-agent-sandbox-tools) p }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", - parentForkMaxTokens: 100000, // ignora fork de thread pai acima desta contagem de tokens (0 desabilita) + parentForkMaxTokens: 100000, // skip parent-thread fork above this token count (0 disables) maintenance: { mode: "warn", // warn | enforce pruneAfter: "30d", maxEntries: 500, rotateBytes: "10mb", - resetArchiveRetention: "30d", // duração ou false - maxDiskBytes: "500mb", // orçamento rígido opcional - highWaterBytes: "400mb", // alvo opcional de limpeza + resetArchiveRetention: "30d", // duration or false + maxDiskBytes: "500mb", // optional hard budget + highWaterBytes: "400mb", // optional cleanup target }, threadBindings: { enabled: true, - idleHours: 24, // padrão de desfoco automático por inatividade em horas (`0` desabilita) - maxAgeHours: 0, // padrão de idade máxima rígida em horas (`0` desabilita) + idleHours: 24, // default inactivity auto-unfocus in hours (`0` disables) + maxAgeHours: 0, // default hard max age in hours (`0` disables) }, - mainKey: "main", // legado (o runtime sempre usa "main") + mainKey: "main", // legacy (runtime always uses "main") agentToAgent: { maxPingPongTurns: 5 }, sendPolicy: { rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }], @@ -1864,35 +1999,35 @@ Consulte [Multi-Agent Sandbox & Tools](/pt-BR/tools/multi-agent-sandbox-tools) p -- **`scope`**: estratégia base de agrupamento de sessões para contextos de chat em grupo. +- **`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 em um contexto de canal compartilham uma única sessão (use apenas quando o contexto compartilhado for intencional). -- **`dmScope`**: como as DMs são agrupadas. +- **`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-peer`: isola por ID do remetente entre canais. - `per-channel-peer`: isola por canal + remetente (recomendado para caixas de entrada com vários usuários). - `per-account-channel-peer`: isola por conta + canal + remetente (recomendado para várias contas). -- **`identityLinks`**: mapeia ids canônicas para peers com prefixo de provedor para compartilhamento de sessão entre canais. -- **`reset`**: política principal de reset. `daily` reinicia em `atHour` no horário local; `idle` reinicia após `idleMinutes`. Quando ambos estão configurados, vence o que expirar primeiro. -- **`resetByType`**: substituições por tipo (`direct`, `group`, `thread`). O legado `dm` é aceito como alias de `direct`. -- **`parentForkMaxTokens`**: máximo de `totalTokens` da sessão pai permitido ao criar uma sessão de thread bifurcada (padrão `100000`). - - Se `totalTokens` do pai estiver acima desse valor, o OpenClaw inicia uma nova sessão de thread em vez de herdar o histórico da transcrição da sessão pai. - - Defina `0` para desabilitar essa proteção e sempre permitir a bifurcação da sessão pai. +- **`identityLinks`**: mapeia IDs canônicos para peers com prefixo de provedor para compartilhamento de sessão entre canais. +- **`reset`**: política principal de reset. `daily` redefine em `atHour` no horário local; `idle` redefine após `idleMinutes`. Quando ambos estão configurados, o primeiro a expirar vence. +- **`resetByType`**: substituições por tipo (`direct`, `group`, `thread`). O 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 desabilitar essa proteção e sempre permitir a derivação da sessão pai. - **`mainKey`**: campo legado. O runtime sempre usa `"main"` para o bucket principal de chat direto. -- **`agentToAgent.maxPingPongTurns`**: número máximo de turnos de resposta entre agentes durante trocas agente-para-agente (inteiro, intervalo: `0`–`5`). `0` desabilita o encadeamento ping-pong. -- **`sendPolicy`**: faz correspondência por `channel`, `chatType` (`direct|group|channel`, com alias legado `dm`), `keyPrefix` ou `rawKeyPrefix`. A primeira negação prevalece. -- **`maintenance`**: controles de limpeza + retenção do armazenamento de sessão. +- **`agentToAgent.maxPingPongTurns`**: número máximo de turnos de resposta de volta entre agentes durante trocas agente-a-agente (inteiro, intervalo: `0`–`5`). `0` desabilita o encadeamento ping-pong. +- **`sendPolicy`**: 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 a limpeza. - - `pruneAfter`: corte de idade para entradas obsoletas (padrão `30d`). + - `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 ultrapassa esse tamanho (padrão `10mb`). - - `resetArchiveRetention`: retenção para arquivos de arquivo de transcrição `*.reset.`. O padrão segue `pruneAfter`; defina `false` para desabilitar. - - `maxDiskBytes`: orçamento opcional de disco para o diretório de sessões. No modo `warn`, registra avisos; no modo `enforce`, remove primeiro artefatos/sessões mais antigos. - - `highWaterBytes`: alvo opcional após a limpeza por orçamento. O padrão é `80%` de `maxDiskBytes`. + - `rotateBytes`: rotaciona `sessions.json` quando excede esse tamanho (padrão `10mb`). + - `resetArchiveRetention`: retenção para arquivos de transcrição `*.reset.`. Usa `pruneAfter` como padrão; defina `false` para desabilitar. + - `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 a limpeza do orçamento. Usa `80%` de `maxDiskBytes` como padrão. - **`threadBindings`**: padrões globais para recursos de sessão vinculados a thread. - - `enabled`: chave mestre padrão (provedores podem substituir; o Discord usa `channels.discord.threadBindings.enabled`) - - `idleHours`: padrão de desfoco automático por inatividade em horas (`0` desabilita; provedores podem substituir) - - `maxAgeHours`: padrão de idade máxima rígida em horas (`0` desabilita; provedores podem substituir) + - `enabled`: chave mestra padrão (provedores podem substituir; o Discord usa `channels.discord.threadBindings.enabled`) + - `idleHours`: desfoco automático padrão por inatividade em horas (`0` desabilita; provedores podem substituir) + - `maxAgeHours`: idade máxima rígida padrão em horas (`0` desabilita; provedores podem substituir) @@ -1903,7 +2038,7 @@ Consulte [Multi-Agent Sandbox & Tools](/pt-BR/tools/multi-agent-sandbox-tools) p ```json5 { messages: { - responsePrefix: "🦞", // ou "auto" + responsePrefix: "🦞", // or "auto" ackReaction: "👀", ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all removeAckAfterReply: false, @@ -1918,7 +2053,7 @@ Consulte [Multi-Agent Sandbox & Tools](/pt-BR/tools/multi-agent-sandbox-tools) p }, }, inbound: { - debounceMs: 2000, // 0 desabilita + debounceMs: 2000, // 0 disables byChannel: { whatsapp: 5000, slack: 1500, @@ -1932,34 +2067,34 @@ Consulte [Multi-Agent Sandbox & Tools](/pt-BR/tools/multi-agent-sandbox-tools) p Substituições por canal/conta: `channels..responsePrefix`, `channels..accounts..responsePrefix`. -Resolução (o mais específico vence): conta → canal → global. `""` desabilita e interrompe a cascata. `"auto"` deriva `[{identity.name}]`. +Resolução (a mais específica vence): conta → canal → global. `""` desabilita e interrompe a cascata. `"auto"` deriva `[{identity.name}]`. **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 desabilitar. +- Usa por padrão `identity.emoji` do agente ativo; caso contrário, `"👀"`. Defina `""` para desabilitar. - Substituições por canal: `channels..ackReaction`, `channels..accounts..ackReaction`. -- Ordem de resolução: conta → canal → `messages.ackReaction` → fallback de identidade. +- 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 a resposta no Slack, Discord e Telegram. -- `messages.statusReactions.enabled`: habilita reações de status do ciclo de vida no Slack, Discord e Telegram. - No Slack e no Discord, deixar sem definir mantém as 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 do ciclo de vida. +- `messages.statusReactions.enabled`: habilita reações de status de ciclo de vida no Slack, Discord e Telegram. + No Slack e no Discord, se não definido, 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 de texto do mesmo remetente em um único turno de agente. Mídia/anexos disparam envio 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 são descarregados imediatamente. Comandos de controle ignoram o debounce. ### TTS (texto para fala) @@ -2004,10 +2139,10 @@ Agrupa mensagens rápidas somente de texto do mesmo remetente em um único turno - `auto` controla o modo padrão de TTS automático: `off`, `always`, `inbound` ou `tagged`. `/tts on|off` pode substituir preferências locais, e `/tts status` mostra o estado efetivo. - `summaryModel` substitui `agents.defaults.model.primary` para resumo automático. -- `modelOverrides` é habilitado por padrão; `modelOverrides.allowProvider` usa `false` por padrão (ativação opcional). -- Chaves de API usam fallback para `ELEVENLABS_API_KEY`/`XI_API_KEY` e `OPENAI_API_KEY`. -- `openai.baseUrl` substitui o endpoint de TTS da OpenAI. A ordem de resolução é config, depois `OPENAI_TTS_BASE_URL`, depois `https://api.openai.com/v1`. -- Quando `openai.baseUrl` aponta para um endpoint que não é da OpenAI, o OpenClaw o trata como um servidor TTS compatível com OpenAI e flexibiliza a validação de modelo/voz. +- `modelOverrides` é habilitado por padrão; `modelOverrides.allowProvider` usa `false` como padrão (ativação opcional). +- Chaves de API usam como fallback `ELEVENLABS_API_KEY`/`XI_API_KEY` e `OPENAI_API_KEY`. +- `openai.baseUrl` substitui o endpoint de TTS da OpenAI. A ordem de resolução é configuração, depois `OPENAI_TTS_BASE_URL`, depois `https://api.openai.com/v1`. +- Quando `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. --- @@ -2039,11 +2174,11 @@ Padrões para o modo Talk (macOS/iOS/Android). - `talk.provider` deve corresponder a uma chave em `talk.providers` quando vários provedores de Talk estiverem configurados. - Chaves planas legadas de Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) 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`. +- IDs de voz usam como fallback `ELEVENLABS_VOICE_ID` ou `SAG_VOICE_ID`. - `providers.*.apiKey` aceita strings em texto simples ou objetos SecretRef. - O fallback `ELEVENLABS_API_KEY` se aplica apenas quando nenhuma chave de API de Talk está configurada. -- `providers.*.voiceAliases` permite que diretivas do 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`). +- `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. Se não definido, mantém a janela de pausa padrão da plataforma (`700 ms no macOS e Android, 900 ms no iOS`). --- @@ -2051,37 +2186,37 @@ Padrões para o modo Talk (macOS/iOS/Android). ### Perfis de ferramenta -`tools.profile` define uma lista de permissões base antes de `tools.allow`/`tools.deny`: +`tools.profile` define uma allowlist base antes de `tools.allow`/`tools.deny`: -O onboarding local usa por padrão `tools.profile: "coding"` em novas configurações locais quando não definido (perfis explícitos existentes são preservados). +O onboarding local define novas configurações locais com `tools.profile: "coding"` quando não definido (perfis explícitos existentes são preservados). -| Perfil | Inclui | -| ----------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `minimal` | apenas `session_status` | +| 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) | +| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | +| `full` | Sem restrição (igual a não definir) | -### Grupos de ferramenta +### Grupos de ferramentas -| Grupo | Ferramentas | -| ------------------ | ----------------------------------------------------------------------------------------------------------------------- | -| `group:runtime` | `exec`, `process`, `code_execution` (`bash` é aceito como alias de `exec`) | -| `group:fs` | `read`, `write`, `edit`, `apply_patch` | +| Grupo | Ferramentas | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------ | +| `group:runtime` | `exec`, `process`, `code_execution` (`bash` é aceito como alias de `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 internas (exclui Plugins de provedor) | ### `tools.allow` / `tools.deny` -Política global de permitir/negar ferramentas (negação prevalece). Não diferencia maiúsculas de minúsculas e aceita 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, oferece suporte a curingas `*`. Aplicada mesmo quando o sandbox Docker está desativado. ```json5 { @@ -2091,7 +2226,7 @@ Política global de permitir/negar ferramentas (negação prevalece). Não difer ### `tools.byProvider` -Restringe ainda mais ferramentas para provedores ou modelos específicos. Ordem: perfil base → perfil do provedor → permitir/negar. +Restringe ainda mais ferramentas para provedores ou modelos específicos. Ordem: perfil base → perfil do provedor → allow/deny. ```json5 { @@ -2107,7 +2242,7 @@ Restringe ainda mais ferramentas para provedores ou modelos específicos. Ordem: ### `tools.elevated` -Controla acesso elevado de exec fora do sandbox: +Controla acesso elevado de `exec` fora do sandbox: ```json5 { @@ -2149,8 +2284,8 @@ Controla acesso elevado de exec fora do sandbox: ### `tools.loopDetection` -As verificações de segurança contra loop de ferramenta ficam **desabilitadas 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`. +As verificações de segurança de loop de ferramenta ficam **desabilitadas por padrão**. Defina `enabled: true` para ativar a detecção. +As configurações podem ser definidas globalmente em `tools.loopDetection` e sobrescritas por agente em `agents.list[].tools.loopDetection`. ```json5 { @@ -2172,12 +2307,12 @@ 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 repetido sem progresso para avisos. -- `criticalThreshold`: limite repetido mais alto para bloquear loops críticos. -- `globalCircuitBreakerThreshold`: limite de parada total para qualquer execução sem progresso. +- `warningThreshold`: limite de padrão repetitivo sem progresso para avisos. +- `criticalThreshold`: limite repetitivo 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 em ferramentas de polling conhecidas (`process.poll`, `command_status` etc.). -- `detectors.pingPong`: avisa/bloqueia em padrões alternados de pares sem progresso. +- `detectors.knownPollNoProgress`: avisa/bloqueia ferramentas de polling conhecidas (`process.poll`, `command_status` etc.). +- `detectors.pingPong`: avisa/bloqueia padrões alternados de pares sem progresso. - Se `warningThreshold >= criticalThreshold` ou `criticalThreshold >= globalCircuitBreakerThreshold`, a validação falha. ### `tools.web` @@ -2188,14 +2323,14 @@ As configurações podem ser definidas globalmente em `tools.loopDetection` e su web: { search: { enabled: true, - apiKey: "brave_api_key", // ou env BRAVE_API_KEY + apiKey: "brave_api_key", // or BRAVE_API_KEY env maxResults: 5, timeoutSeconds: 30, cacheTtlMinutes: 15, }, fetch: { enabled: true, - provider: "firecrawl", // opcional; omita para detecção automática + provider: "firecrawl", // optional; omit for auto-detect maxChars: 50000, maxCharsCap: 50000, maxResponseBytes: 2000000, @@ -2212,7 +2347,7 @@ As configurações podem ser definidas globalmente em `tools.loopDetection` e su ### `tools.media` -Configura entendimento de mídia recebida (imagem/áudio/vídeo): +Configura o entendimento de mídia recebida (imagem/áudio/vídeo): ```json5 { @@ -2220,7 +2355,7 @@ Configura entendimento de mídia recebida (imagem/áudio/vídeo): media: { concurrency: 2, asyncCompletion: { - directSend: false, // ativação opcional: envia música/vídeo assíncronos concluídos diretamente ao canal + directSend: false, // opt-in: send finished async music/video directly to the channel }, audio: { enabled: true, @@ -2248,20 +2383,20 @@ 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 do id do modelo -- `profile` / `preferredProfile`: seleção de perfil em `auth-profiles.json` +- `provider`: ID do provedor de API (`openai`, `anthropic`, `google`/`gemini`, `groq` etc.) +- `model`: substituição de ID de modelo +- `profile` / `preferredProfile`: seleção de perfil de `auth-profiles.json` -**Entrada CLI** (`type: "cli"`): +**Entrada de CLI** (`type: "cli"`): - `command`: executável a ser executado -- `args`: argumentos com template (compatível com `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` etc.) +- `args`: argumentos com template (oferece suporte a `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` etc.) **Campos comuns:** - `capabilities`: lista opcional (`image`, `audio`, `video`). Padrões: `openai`/`anthropic`/`minimax` → image, `google` → image+audio+video, `groq` → audio. - `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: substituições por entrada. -- Falhas recorrem à próxima entrada. +- Falhas usam a próxima entrada como fallback. A autenticação do provedor segue a ordem padrão: `auth-profiles.json` → variáveis de ambiente → `models.providers.*.apiKey`. @@ -2269,7 +2404,7 @@ A autenticação do provedor segue a ordem padrão: `auth-profiles.json` → var - `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 wake/model-delivery da sessão solicitante). + (caminho legado de despertar sessão solicitante/entrega por modelo). @@ -2288,9 +2423,9 @@ A autenticação do provedor segue a ordem padrão: `auth-profiles.json` → var ### `tools.sessions` -Controla quais sessões podem ser direcionadas pelas ferramentas de sessão (`sessions_list`, `sessions_history`, `sessions_send`). +Controla quais sessões podem ser alvo das ferramentas de sessão (`sessions_list`, `sessions_history`, `sessions_send`). -Padrão: `tree` (sessão atual + sessões geradas por ela, como subagentes). +Padrão: `tree` (sessão atual + sessões iniciadas por ela, como subagentes). ```json5 { @@ -2306,8 +2441,8 @@ Padrão: `tree` (sessão atual + sessões geradas por ela, como subagentes). 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 por remetente sob o mesmo id de agente). +- `tree`: sessão atual + sessões iniciadas 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 por remetente sob o mesmo ID de agente). - `all`: qualquer sessão. O direcionamento entre agentes ainda exige `tools.agentToAgent`. - Restrição de 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"`. @@ -2320,11 +2455,11 @@ Controla o suporte a anexos inline para `sessions_spawn`. tools: { sessions_spawn: { attachments: { - enabled: false, // ativação opcional: defina true para permitir anexos de arquivo inline - maxTotalBytes: 5242880, // 5 MB no total entre todos os arquivos + enabled: false, // opt-in: set true to allow inline file attachments + maxTotalBytes: 5242880, // 5 MB total across all files maxFiles: 50, - maxFileBytes: 1048576, // 1 MB por arquivo - retainOnSessionKeep: false, // mantém anexos quando cleanup="keep" + maxFileBytes: 1048576, // 1 MB per file + retainOnSessionKeep: false, // keep attachments when cleanup="keep" }, }, }, @@ -2333,22 +2468,22 @@ Controla o suporte a anexos inline para `sessions_spawn`. Observações: -- Anexos são compatíveis apenas 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ó são compatíveis com `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 estritas de alfabeto/preenchimento e uma proteção de tamanho antes da decodificação. +- Entradas em Base64 são validadas com verificações estritas 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`. +- A limpeza segue a política `cleanup`: `delete` sempre remove anexos; `keep` os retém apenas quando `retainOnSessionKeep: true`. ### `tools.experimental` -Flags experimentais de ferramentas integradas. Desativadas por padrão, a menos que se aplique uma regra de ativação automática estrita-agentic do GPT-5. +Flags experimentais de ferramentas internas. Desligadas por padrão, a menos que uma regra de autoativação strict-agentic GPT-5 se aplique. ```json5 { tools: { experimental: { - planTool: true, // habilita update_plan experimental + planTool: true, // enable experimental update_plan }, }, } @@ -2356,9 +2491,9 @@ Flags experimentais de ferramentas integradas. Desativadas por padrão, a menos Observações: -- `planTool`: habilita a ferramenta estruturada `update_plan` para acompanhamento de trabalho não trivial com várias etapas. -- Padrão: `false`, a menos que `agents.defaults.embeddedPi.executionContract` (ou uma substituição por agente) esteja definido como `"strict-agentic"` para uma execução da família GPT-5 da OpenAI ou OpenAI Codex. Defina `true` para forçar a ferramenta fora desse escopo, ou `false` para mantê-la desativada mesmo em execuções GPT-5 strict-agentic. -- Quando habilitada, 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 como `in_progress`. +- `planTool`: habilita a ferramenta estruturada experimental `update_plan` para rastreamento de trabalho não trivial em várias etapas. +- Padrão: `false`, a menos que `agents.defaults.embeddedPi.executionContract` (ou uma substituição por agente) esteja definido como `"strict-agentic"` para uma execução da família GPT-5 da OpenAI ou OpenAI Codex. Defina `true` para forçar a ferramenta fora desse escopo, ou `false` para mantê-la desabilitada mesmo em execuções strict-agentic GPT-5. +- Quando habilitada, o prompt do sistema também adiciona orientações de uso para que o modelo só a use em trabalho substancial e mantenha no máximo uma etapa `in_progress`. ### `agents.defaults.subagents` @@ -2378,21 +2513,21 @@ Observações: } ``` -- `model`: modelo padrão para subagentes gerados. Se omitido, os subagentes herdam o modelo do chamador. -- `allowAgents`: lista de permissões padrão de IDs de agente de destino para `sessions_spawn` quando o agente solicitante não define seu próprio `subagents.allowAgents` (`["*"]` = qualquer; padrão: apenas o mesmo agente). +- `model`: modelo padrão para subagentes iniciados. Se omitido, os subagentes herdam o modelo do chamador. +- `allowAgents`: allowlist padrão de IDs de agente de destino 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 -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 interno de modelos. Adicione provedores personalizados via `models.providers` na configuração ou `~/.openclaw/agents//agent/models.json`. ```json5 { models: { - mode: "merge", // merge (padrão) | replace + mode: "merge", // merge (default) | replace providers: { "custom-proxy": { baseUrl: "http://localhost:4000/v1", @@ -2416,50 +2551,50 @@ O OpenClaw usa o catálogo de modelos integrado. Adicione provedores personaliza } ``` -- Use `authHeader: true` + `headers` para necessidades de autenticação personalizada. +- Use `authHeader: true` + `headers` para necessidades de autenticação personalizadas. - 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 `baseUrl` não vazios de `models.json` do agente prevalecem. - - Valores `apiKey` não vazios do agente prevalecem apenas quando esse provedor não é gerenciado por SecretRef no contexto atual de config/perfil de autenticação. + - 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 ambiente, `secretref-managed` para refs de arquivo/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 ambiente, `secretref-managed` para refs de arquivo/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 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 metadados nativos do modelo. - - Use `models.mode: "replace"` quando quiser que a configuração reescreva totalmente `models.json`. + - `apiKey`/`baseUrl` do agente vazios ou ausentes usam como fallback `models.providers` na configuração. + - `contextWindow`/`maxTokens` do modelo correspondente usam o valor mais alto entre a configuração explícita e os valores implícitos do catálogo. + - `contextTokens` do modelo correspondente preserva um limite explícito de runtime quando presente; use-o para limitar o contexto efetivo sem alterar metadados nativos do modelo. + - Use `models.mode: "replace"` quando quiser que a configuração reescreva completamente `models.json`. - A persistência de marcadores é autoritativa pela origem: os marcadores são gravados a partir do snapshot ativo da configuração de origem (pré-resolução), não a partir dos 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 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 substituição por SecretRef/env). +- `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 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 cabeçalho `Authorization` quando necessário. - `models.providers.*.baseUrl`: URL base da API upstream. - `models.providers.*.headers`: cabeçalhos estáticos extras para roteamento por proxy/tenant. -- `models.providers.*.request`: substituições de transporte para requisições HTTP de provedor de modelo. - - `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 integrada do provedor), `"authorization-bearer"` (com `token`), `"header"` (com `headerName`, `value`, `prefix` opcional). - - `request.proxy`: substituição do 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`. +- `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). Os valores aceitam SecretRef. + - `request.auth`: substituição da estratégia de autenticação. Modos: `"provider-default"` (usa a autenticação interna 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 `tls` opcional. - `request.tls`: substituição de TLS para conexões diretas. Campos: `ca`, `cert`, `key`, `passphrase` (todos aceitam SecretRef), `serverName`, `insecureSkipVerify`. - - `request.allowPrivateNetwork`: quando `true`, permite HTTPS para `baseUrl` quando o DNS resolve para intervalos privados, CGNAT ou semelhantes, via a proteção de fetch HTTP do provedor (ativação opcional do operador para endpoints OpenAI-compatíveis autohospedados e confiáveis). WebSocket usa o mesmo `request` para cabeçalhos/TLS, mas não esse bloqueio SSRF de fetch. Padrão `false`. + - `request.allowPrivateNetwork`: quando `true`, permite HTTPS para `baseUrl` quando o DNS resolve para faixas privadas, CGNAT ou similares, via a proteção SSRF de fetch HTTP do provedor (ativação do operador para endpoints confiáveis autohospedados compatíveis com OpenAI). WebSocket usa o mesmo `request` para cabeçalhos/TLS, mas não essa barreira SSRF de fetch. Padrão `false`. - `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 efetivo de contexto menor 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 de `messages[].content` de texto puro em strings simples antes de enviar a requisição. -- `plugins.entries.amazon-bedrock.config.discovery`: raiz das configurações de descoberta automática 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 de id de provedor para descoberta direcionada. -- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: intervalo de polling para atualização da descoberta. +- `models.providers.*.models.*.contextWindow`: metadados da janela de contexto nativa do modelo. +- `models.providers.*.models.*.contextTokens`: limite opcional de contexto em runtime. Use isto quando quiser um orçamento de contexto efetivo menor que o `contextWindow` nativo do modelo. +- `models.providers.*.models.*.compat.supportsDeveloperRole`: dica opcional de compatibilidade. Para `api: "openai-completions"` com `baseUrl` não vazio e não nativo (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 `messages[].content` compostos apenas por texto em strings simples antes de enviar a requisição. +- `plugins.entries.amazon-bedrock.config.discovery`: raiz das configurações de autodiscovery do Bedrock. +- `plugins.entries.amazon-bedrock.config.discovery.enabled`: ativa/desativa o discovery implícito. +- `plugins.entries.amazon-bedrock.config.discovery.region`: região AWS para discovery. +- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: filtro opcional de ID de provedor para discovery direcionado. +- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: intervalo de polling para atualização do discovery. - `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: janela de contexto de fallback para modelos descobertos. - `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: máximo de tokens de saída de fallback para modelos descobertos. -### Exemplos de provedor +### Exemplos de provedores @@ -2512,7 +2647,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 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`. +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`. @@ -2532,8 +2667,8 @@ Defina `OPENCODE_API_KEY` (ou `OPENCODE_ZEN_API_KEY`). Use refs `opencode/...` p Defina `ZAI_API_KEY`. `z.ai/*` e `z-ai/*` são aliases aceitos. Atalho: `openclaw onboard --auth-choice zai-api-key`. - Endpoint geral: `https://api.z.ai/api/paas/v4` -- Endpoint de código (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. +- Endpoint de codificação (padrão): `https://api.z.ai/api/coding/paas/v4` +- Para o endpoint geral, defina um provedor personalizado com substituição da URL base. @@ -2575,8 +2710,8 @@ Defina `ZAI_API_KEY`. `z.ai/*` e `z-ai/*` são aliases aceitos. Atalho: `opencla 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 usa os recursos do endpoint -em vez de se basear apenas no id integrado do provedor. +`openai-completions`, e o OpenClaw baseia isso nas capacidades do endpoint +em vez de apenas no ID interno do provedor. @@ -2594,7 +2729,7 @@ em vez de se basear apenas no id integrado do provedor. } ``` -Compatível com Anthropic, provedor integrado. Atalho: `openclaw onboard --auth-choice kimi-code-api-key`. +Compatível com Anthropic, provedor interno. Atalho: `openclaw onboard --auth-choice kimi-code-api-key`. @@ -2676,7 +2811,7 @@ A URL base deve omitir `/v1` (o cliente Anthropic a acrescenta). Atalho: `opencl 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 usa por padrão apenas M2.7. +O catálogo de modelos usa apenas M2.7 por padrão. No caminho de streaming compatível com Anthropic, o OpenClaw desabilita 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 @@ -2686,7 +2821,7 @@ por padrão, a menos que você defina `thinking` explicitamente. `/fast on` ou -Consulte [Modelos locais](/pt-BR/gateway/local-models). Resumindo: execute um modelo local grande via LM Studio Responses API em hardware robusto; mantenha modelos hospedados mesclados para fallback. +Consulte [Local Models](/pt-BR/gateway/local-models). Em resumo: execute um grande modelo local via API Responses do LM Studio em hardware robusto; mantenha modelos hospedados mesclados para fallback. @@ -2707,7 +2842,7 @@ Consulte [Modelos locais](/pt-BR/gateway/local-models). Resumindo: execute um mo }, entries: { "image-lab": { - apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // ou string em texto simples + apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" }, }, peekaboo: { enabled: true }, @@ -2717,14 +2852,14 @@ Consulte [Modelos locais](/pt-BR/gateway/local-models). Resumindo: execute um mo } ``` -- `allowBundled`: lista de permissões opcional apenas para Skills bundled (Skills gerenciadas/do workspace não são afetadas). -- `load.extraDirs`: raízes extras de Skills compartilhadas (menor precedência). +- `allowBundled`: allowlist opcional apenas para Skills agrupadas (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 gerenciador Node para especificações + 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` desabilita uma Skill mesmo se estiver bundled/instalada. -- `entries..apiKey`: conveniência para Skills que declaram uma variável de ambiente principal (string em texto simples ou objeto SecretRef). +- `entries..enabled: false` desabilita uma Skill mesmo que esteja agrupada/instalada. +- `entries..apiKey`: conveniência para Skills que declaram uma variável de ambiente primária (string em texto simples ou objeto SecretRef). --- @@ -2752,38 +2887,38 @@ Consulte [Modelos locais](/pt-BR/gateway/local-models). Resumindo: execute um mo } ``` -- Carregado de `~/.openclaw/extensions`, `/.openclaw/extensions` e `plugins.load.paths`. -- A descoberta aceita plugins nativos do OpenClaw, além de bundles Codex compatíveis e bundles Claude, incluindo bundles Claude sem manifesto no layout padrão. -- **Mudanças de configuração exigem reinicialização do Gateway.** -- `allow`: lista de permissões opcional (somente plugins listados são carregados). `deny` prevalece. -- `plugins.entries..apiKey`: campo de conveniência de chave de API no nível do plugin (quando compatível com o plugin). -- `plugins.entries..env`: mapa de variáveis de ambiente com escopo de plugin. -- `plugins.entries..hooks.allowPromptInjection`: quando `false`, o core bloqueia `before_prompt_build` e ignora campos de mutação de prompt de `before_agent_start` legado, preservando `modelOverride` e `providerOverride` legados. Aplica-se a hooks de plugins nativos e a diretórios de hooks fornecidos por bundles compatíveis. -- `plugins.entries..subagent.allowModelOverride`: confia explicitamente neste plugin para solicitar substituições por execução de `provider` e `model` para execuções de subagentes em segundo plano. -- `plugins.entries..subagent.allowedModels`: lista de permissões opcional de alvos canônicos `provider/model` para substituições confiáveis de subagente. Use `"*"` apenas quando você realmente quiser permitir qualquer modelo. -- `plugins.entries..config`: objeto de configuração definido pelo plugin (validado pelo schema nativo do plugin OpenClaw quando disponível). -- `plugins.entries.firecrawl.config.webFetch`: configurações do provedor de busca web Firecrawl. - - `apiKey`: chave de API do Firecrawl (aceita SecretRef). Usa fallback para `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`). +- Carregado de `~/.openclaw/extensions`, `/.openclaw/extensions`, além de `plugins.load.paths`. +- O discovery aceita Plugins nativos do OpenClaw, além de bundles compatíveis do Codex e do Claude, incluindo bundles do Claude sem manifesto no layout padrão. +- **Mudanças de configuração exigem reinicialização do gateway.** +- `allow`: allowlist opcional (apenas Plugins listados são carregados). `deny` vence. +- `plugins.entries..apiKey`: campo de conveniência de chave de API em nível de Plugin (quando compatível com o Plugin). +- `plugins.entries..env`: mapa de variáveis de ambiente com escopo do Plugin. +- `plugins.entries..hooks.allowPromptInjection`: quando `false`, o núcleo bloqueia `before_prompt_build` e ignora campos que modificam prompt do legado `before_agent_start`, preservando `modelOverride` e `providerOverride` legados. Aplica-se a hooks nativos de Plugin e a diretórios de hooks fornecidos por bundle compatíveis. +- `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`: allowlist opcional 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 do OpenClaw quando disponível). +- `plugins.entries.firecrawl.config.webFetch`: configurações do provedor Firecrawl para web fetch. + - `apiKey`: chave de API do Firecrawl (aceita SecretRef). Usa como fallback `plugins.entries.firecrawl.config.webSearch.apiKey`, o legado `tools.web.fetch.firecrawl.apiKey` ou a variável de ambiente `FIRECRAWL_API_KEY`. + - `baseUrl`: URL base da API do Firecrawl (padrão: `https://api.firecrawl.dev`). - `onlyMainContent`: extrai apenas o conteúdo principal das páginas (padrão: `true`). - `maxAgeMs`: idade máxima de cache em milissegundos (padrão: `172800000` / 2 dias). - - `timeoutSeconds`: timeout de requisição de scraping em segundos (padrão: `60`). -- `plugins.entries.xai.config.xSearch`: configurações do xAI X Search (busca web do Grok). + - `timeoutSeconds`: timeout da requisição de scraping em segundos (padrão: `60`). +- `plugins.entries.xai.config.xSearch`: configurações do X Search da xAI (busca web do Grok). - `enabled`: habilita o provedor X Search. - `model`: modelo Grok a usar para busca (por exemplo `"grok-4-1-fast"`). -- `plugins.entries.memory-core.config.dreaming`: configurações de dreaming da memória. Consulte [Dreaming](/pt-BR/concepts/dreaming) para fases e limites. - - `enabled`: chave mestre de dreaming (padrão `false`). - - `frequency`: cadência Cron para cada varredura completa de dreaming (padrão `"0 3 * * *"`). +- `plugins.entries.memory-core.config.dreaming`: configurações de dreaming de memória. Consulte [Dreaming](/pt-BR/concepts/dreaming) para fases e limites. + - `enabled`: chave mestra de 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). -- A configuração completa de memória está em [Referência de configuração de memória](/pt-BR/reference/memory-config): +- A configuração completa de memória está em [Memory configuration reference](/pt-BR/reference/memory-config): - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` - Plugins de bundle Claude habilitados também podem contribuir com padrões embutidos de Pi a partir 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 desabilitar plugins de memória. -- `plugins.slots.contextEngine`: escolhe o id do plugin ativo do mecanismo de contexto; o padrão é `"legacy"` a menos que você instale e selecione outro mecanismo. +- `plugins.slots.memory`: escolhe o ID do Plugin de memória ativo, ou `"none"` para desabilitar Plugins de memória. +- `plugins.slots.contextEngine`: escolhe o ID do Plugin de mecanismo de contexto ativo; usa `"legacy"` como padrão 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. @@ -2801,8 +2936,8 @@ Consulte [Plugins](/pt-BR/tools/plugin). evaluateEnabled: true, defaultProfile: "user", ssrfPolicy: { - // dangerouslyAllowPrivateNetwork: true, // ative apenas para acesso confiável a rede privada - // allowPrivateNetwork: true, // alias legado + // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access + // allowPrivateNetwork: true, // legacy alias // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], }, @@ -2831,23 +2966,23 @@ Consulte [Plugins](/pt-BR/tools/plugin). - `evaluateEnabled: false` desabilita `act:evaluate` e `wait --fn`. - `ssrfPolicy.dangerouslyAllowPrivateNetwork` fica desabilitado quando não definido, então a navegação do navegador permanece estrita por padrão. - Defina `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` apenas quando confiar intencionalmente na navegação do navegador em rede privada. -- No modo estrito, endpoints de perfil CDP remoto (`profiles.*.cdpUrl`) estão sujeitos ao mesmo bloqueio de rede privada durante verificações de alcance/descoberta. +- No modo estrito, endpoints remotos de perfil CDP (`profiles.*.cdpUrl`) estão sujeitos ao mesmo bloqueio de rede privada durante verificações de alcance/discovery. - `ssrfPolicy.allowPrivateNetwork` continua compatível como alias legado. - No modo estrito, use `ssrfPolicy.hostnameAllowlist` e `ssrfPolicy.allowedHostnames` para exceções explícitas. -- Perfis remotos são somente de conexão (iniciar/parar/redefinir desabilitados). +- Perfis remotos são somente attach (iniciar/parar/redefinir desabilitados). - `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 DevTools direta. -- Perfis `existing-session` são apenas do host e usam Chrome MCP em vez de CDP. -- Perfis `existing-session` podem definir `userDataDir` para direcionar um perfil específico + quando seu provedor fornecer uma URL WebSocket direta do DevTools. +- Perfis `existing-session` funcionam apenas no 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` mantêm os limites atuais de rota do Chrome MCP: +- Perfis `existing-session` mantêm os limites atuais da rota Chrome MCP: ações baseadas em snapshot/ref em vez de direcionamento por seletor CSS, hooks - de upload de arquivo único, sem substituições de timeout de diálogo, sem - `wait --load networkidle` e sem `responsebody`, exportação de PDF, interceptação + de upload de um único arquivo, sem substituições de timeout de diálogo, sem + `wait --load networkidle`, e sem `responsebody`, exportação de PDF, interceptação de download ou ações em lote. -- Perfis `openclaw` locais gerenciados atribuem automaticamente `cdpPort` e `cdpUrl`; defina - `cdpUrl` explicitamente apenas para CDP remoto. +- 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: apenas loopback (porta derivada de `gateway.port`, padrão `18791`). - `extraArgs` acrescenta flags extras de inicialização ao Chromium local (por exemplo @@ -2863,14 +2998,14 @@ Consulte [Plugins](/pt-BR/tools/plugin). seamColor: "#FF4500", assistant: { name: "OpenClaw", - avatar: "CB", // emoji, texto curto, URL de imagem ou URI de dados + avatar: "CB", // emoji, short text, image URL, or data URI }, }, } ``` - `seamColor`: cor de destaque para o chrome da UI do app nativo (matiz da bolha do modo Talk etc.). -- `assistant`: substituição de identidade da Control UI. Usa a identidade do agente ativo como fallback. +- `assistant`: substituição de identidade da Control UI. Usa como fallback a identidade do agente ativo. --- @@ -2885,8 +3020,8 @@ Consulte [Plugins](/pt-BR/tools/plugin). auth: { mode: "token", // none | token | password | trusted-proxy token: "your-token", - // password: "your-password", // ou OPENCLAW_GATEWAY_PASSWORD - // trustedProxy: { userHeader: "x-forwarded-user" }, // para mode=trusted-proxy; veja /gateway/trusted-proxy-auth + // password: "your-password", // or OPENCLAW_GATEWAY_PASSWORD + // trustedProxy: { userHeader: "x-forwarded-user" }, // for mode=trusted-proxy; see /gateway/trusted-proxy-auth allowTailscale: true, rateLimit: { maxAttempts: 10, @@ -2904,9 +3039,9 @@ Consulte [Plugins](/pt-BR/tools/plugin). basePath: "/openclaw", // root: "dist/control-ui", // embedSandbox: "scripts", // strict | scripts | trusted - // allowExternalEmbedUrls: false, // perigoso: permite URLs de embed http(s) externas absolutas - // allowedOrigins: ["https://control.example.com"], // obrigatório para Control UI fora de loopback - // dangerouslyAllowHostHeaderOriginFallback: false, // modo perigoso de fallback de origem por cabeçalho Host + // allowExternalEmbedUrls: false, // dangerous: allow absolute external http(s) embed URLs + // allowedOrigins: ["https://control.example.com"], // required for non-loopback Control UI + // dangerouslyAllowHostHeaderOriginFallback: false, // dangerous Host-header origin fallback mode // allowInsecureAuth: false, // dangerouslyDisableDeviceAuth: false, }, @@ -2917,12 +3052,12 @@ Consulte [Plugins](/pt-BR/tools/plugin). // password: "your-password", }, trustedProxies: ["10.0.0.1"], - // Opcional. Padrão false. + // Optional. Default false. allowRealIpFallback: false, tools: { - // Negações HTTP adicionais de /tools/invoke + // Additional /tools/invoke HTTP denies deny: ["browser"], - // Remove ferramentas da lista padrão de negação HTTP + // Remove tools from the default HTTP deny list allow: ["gateway"], }, push: { @@ -2939,44 +3074,44 @@ Consulte [Plugins](/pt-BR/tools/plugin). -- `mode`: `local` (executa o 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 do Tailscale) ou `custom`. +- `bind`: `auto`, `loopback` (padrão), `lan` (`0.0.0.0`), `tailnet` (apenas IP do 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**: exigida por padrão. Binds fora de loopback exigem auth do gateway. Na prática, isso significa um token/senha compartilhado ou um proxy reverso com reconhecimento de identidade com `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`. Os fluxos de inicialização e de instalação/reparo do serviço falham quando ambos estão configurados e o modo não está definido. +- **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 fora de loopback exigem auth do gateway. Na prática, isso significa um token/senha compartilhado 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`. A inicialização e os fluxos de instalação/reparo do serviço falham quando ambos estão configurados e o modo não está definido. - `gateway.auth.mode: "none"`: modo explícito sem auth. Use apenas para configurações confiáveis de local loopback; isso intencionalmente não é oferecido pelos prompts de onboarding. -- `gateway.auth.mode: "trusted-proxy"`: delega a auth a um proxy reverso com reconhecimento de identidade e confia em cabeçalhos de identidade de `gateway.trustedProxies` (consulte [Auth de proxy confiável](/pt-BR/gateway/trusted-proxy-auth)). Esse modo espera uma origem de proxy **fora de loopback**; proxies reversos em loopback no mesmo host não satisfazem a auth de trusted-proxy. -- `gateway.auth.allowTailscale`: quando `true`, cabeçalhos de identidade do Tailscale Serve podem satisfazer a auth da Control UI/WebSocket (verificados via `tailscale whois`). Endpoints de API HTTP **não** usam essa auth por cabeçalho do Tailscale; eles seguem o modo normal de auth HTTP do gateway. Esse fluxo sem token pressupõe que o host do gateway é confiável. O padrão é `true` quando `tailscale.mode = "serve"`. +- `gateway.auth.mode: "trusted-proxy"`: delega auth a um proxy reverso com reconhecimento de identidade e confia nos cabeçalhos de identidade de `gateway.trustedProxies` (consulte [Trusted Proxy Auth](/pt-BR/gateway/trusted-proxy-auth)). Esse modo espera uma origem de proxy **fora de loopback**; proxies reversos loopback no mesmo host não satisfazem a auth trusted-proxy. +- `gateway.auth.allowTailscale`: quando `true`, cabeçalhos de identidade do Tailscale Serve podem satisfazer a auth da Control UI/WebSocket (verificados via `tailscale whois`). Endpoints da API HTTP **não** usam essa auth por cabeçalho do Tailscale; eles seguem o modo normal de auth HTTP do gateway. Esse fluxo sem token presume que o host do gateway é confiável. Usa `true` como padrão quando `tailscale.mode = "serve"`. - `gateway.auth.rateLimit`: limitador opcional de falhas de auth. Aplica-se por IP do cliente e por escopo de auth (segredo compartilhado e token de dispositivo são rastreados independentemente). Tentativas bloqueadas retornam `429` + `Retry-After`. - - No caminho assíncrono da Control UI do Tailscale Serve, tentativas com falha 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 `true` por padrão; defina `false` quando você intencionalmente quiser limitar também o tráfego de localhost (para ambientes de teste ou implantações estritas com proxy). -- Tentativas de auth de WS com origem em navegador são sempre limitadas com a isenção de loopback desabilitada (defesa em profundidade contra força bruta de localhost baseada em navegador). -- Em loopback, esses bloqueios para origem de navegador são isolados por valor normalizado de `Origin`, - então falhas repetidas de uma origem localhost não bloqueiam automaticamente - uma origem diferente. -- `tailscale.mode`: `serve` (somente tailnet, bind loopback) ou `funnel` (público, exige auth). -- `controlUi.allowedOrigins`: lista explícita de permissões de origem do navegador para conexões WebSocket do Gateway. Obrigatória quando clientes de navegador são esperados a partir de origens fora de loopback. -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: modo perigoso que habilita fallback de origem por cabeçalho Host para implantações que dependem intencionalmente de política de origem baseada em cabeçalho Host. + - No caminho assíncrono da Control UI do Tailscale Serve, tentativas com falha para o mesmo `{scope, clientIp}` são serializadas antes da gravação da falha. Assim, tentativas ruins concorrentes do mesmo cliente podem disparar o limitador na segunda requisição em vez de ambas passarem em paralelo como incompatibilidades simples. + - `gateway.auth.rateLimit.exemptLoopback` usa `true` como padrão; defina `false` quando quiser intencionalmente limitar também o tráfego localhost (para ambientes de teste ou implantações estritas com proxy). +- Tentativas de auth WS com origem de navegador são sempre limitadas, com isenção de loopback desabilitada (defesa em profundidade contra força bruta de localhost baseada em navegador). +- Em loopback, esses bloqueios de origem de navegador são isolados por valor + `Origin` normalizado, então falhas repetidas de uma origem localhost não + bloqueiam automaticamente uma origem diferente. +- `tailscale.mode`: `serve` (somente tailnet, bind loopback) ou `funnel` (público, requer auth). +- `controlUi.allowedOrigins`: allowlist explícita de origem de navegador para conexões WebSocket do Gateway. Obrigatória quando se espera clientes de navegador a partir de origens fora de loopback. +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: modo perigoso que habilita fallback de origem pelo cabeçalho Host para implantações que dependem intencionalmente da política de origem baseada em Host header. - `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 de emergência do lado do cliente que permite `ws://` em texto simples para IPs confiáveis de rede privada; o padrão continua sendo somente loopback para texto simples. -- `gateway.remote.token` / `.password` são campos de credenciais do cliente remoto. Eles não configuram a auth do gateway por si só. -- `gateway.push.apns.relay.baseUrl`: URL HTTPS base para o relay APNs externo usado por builds oficiais/TestFlight do iOS depois que eles publicam registros com suporte de relay no gateway. Essa URL deve corresponder à URL do relay compilada na build do iOS. -- `gateway.push.apns.relay.timeoutMs`: timeout de envio do gateway para o relay em milissegundos. O padrão é `10000`. -- Registros com suporte de relay são delegados a uma identidade específica do gateway. O app iOS pareado busca `gateway.identity.get`, inclui essa identidade no registro do relay e encaminha uma permissão de envio com escopo de registro ao gateway. Outro gateway não pode reutilizar esse registro armazenado. +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: substituição break-glass no lado do cliente que permite `ws://` em texto puro para IPs confiáveis de rede privada; o padrão continua sendo texto puro apenas para loopback. +- `gateway.remote.token` / `.password` são campos de credencial do cliente remoto. Eles não configuram a auth do gateway por si só. +- `gateway.push.apns.relay.baseUrl`: URL HTTPS base para o relay APNs externo usado por builds oficiais/TestFlight do iOS após publicarem registros com relay para o gateway. Essa URL deve corresponder à URL do relay compilada no build do iOS. +- `gateway.push.apns.relay.timeoutMs`: timeout de envio do gateway para o relay em milissegundos. Padrão: `10000`. +- Registros com relay são delegados a uma identidade específica de gateway. O app iOS pareado busca `gateway.identity.get`, inclui essa identidade no registro do relay e encaminha uma permissão de envio com escopo de registro ao gateway. 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 apenas para desenvolvimento para URLs HTTP de relay em loopback. URLs de relay de produção devem permanecer em HTTPS. -- `gateway.channelHealthCheckMinutes`: intervalo do monitor de saúde do canal em minutos. Defina `0` para desabilitar globalmente reinicializações do monitor de saúde. Padrão: `5`. -- `gateway.channelStaleEventThresholdMinutes`: limite de socket obsoleto em minutos. Mantenha isso maior ou igual a `gateway.channelHealthCheckMinutes`. Padrão: `30`. -- `gateway.channelMaxRestartsPerHour`: máximo de reinicializações do monitor de saúde por canal/conta em uma hora contínua. Padrão: `10`. -- `channels..healthMonitor.enabled`: opção de desativação por canal para reinicializações do monitor de saúde, mantendo o monitor global habilitado. +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: escape hatch apenas para desenvolvimento para URLs HTTP de relay em loopback. URLs de relay em produção devem permanecer em HTTPS. +- `gateway.channelHealthCheckMinutes`: intervalo, em minutos, do monitor de integridade de canal. Defina `0` para desabilitar globalmente reinicializações pelo monitor de integridade. Padrão: `5`. +- `gateway.channelStaleEventThresholdMinutes`: limite, em minutos, para socket obsoleto. Mantenha este valor maior ou igual a `gateway.channelHealthCheckMinutes`. Padrão: `30`. +- `gateway.channelMaxRestartsPerHour`: máximo de reinicializações por monitor de integridade por canal/conta em uma hora móvel. Padrão: `10`. +- `channels..healthMonitor.enabled`: desativação opcional por canal para reinicializações do monitor de integridade, mantendo o monitor global habilitado. - `channels..accounts..healthMonitor.enabled`: substituição por conta para canais com várias contas. Quando definido, tem precedência sobre a substituição em nível de canal. - Caminhos de chamada do gateway local podem usar `gateway.remote.*` como fallback apenas quando `gateway.auth.*` não está definido. -- Se `gateway.auth.token` / `gateway.auth.password` estiver explicitamente configurado via SecretRef e não resolvido, a resolução falha em modo fail-closed (sem mascaramento por fallback remoto). -- `trustedProxies`: IPs de proxy reverso que encerram TLS ou injetam cabeçalhos de cliente encaminhado. Liste apenas proxies que você controla. Entradas de loopback continuam válidas para configurações de proxy no mesmo host/detecção local (por exemplo Tailscale Serve ou um proxy reverso local), mas elas **não** tornam requisições em loopback elegíveis para `gateway.auth.mode: "trusted-proxy"`. +- Se `gateway.auth.token` / `gateway.auth.password` estiver explicitamente configurado via SecretRef e não resolvido, a resolução falha em modo fechado (sem fallback remoto encobrindo). +- `trustedProxies`: IPs de proxies reversos que terminam TLS ou injetam cabeçalhos de cliente encaminhado. Liste apenas proxies sob seu controle. Entradas loopback ainda são válidas para configurações de detecção local/proxy no mesmo host (por exemplo Tailscale Serve ou um proxy reverso local), mas elas **não** tornam requisições loopback elegíveis para `gateway.auth.mode: "trusted-proxy"`. - `allowRealIpFallback`: quando `true`, o gateway aceita `X-Real-IP` se `X-Forwarded-For` estiver ausente. Padrão `false` para comportamento fail-closed. -- `gateway.tools.deny`: nomes extras de ferramentas bloqueados para HTTP `POST /tools/invoke` (estende a lista padrão de negação). +- `gateway.tools.deny`: nomes extras de ferramentas bloqueadas para HTTP `POST /tools/invoke` (estende a lista padrão de negação). - `gateway.tools.allow`: remove nomes de ferramentas da lista padrão de negação HTTP. @@ -2984,19 +3119,19 @@ Consulte [Plugins](/pt-BR/tools/plugin). ### Endpoints compatíveis com OpenAI - Chat Completions: desabilitado por padrão. Habilite com `gateway.http.endpoints.chatCompletions.enabled: true`. -- Responses API: `gateway.http.endpoints.responses.enabled`. -- Endurecimento de entrada por URL do Responses: +- API Responses: `gateway.http.endpoints.responses.enabled`. +- Endurecimento de entrada por URL em Responses: - `gateway.http.endpoints.responses.maxUrlParts` - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` - Listas de permissões vazias são tratadas como não definidas; use `gateway.http.endpoints.responses.files.allowUrl=false` + Allowlists vazias são tratadas como não definidas; use `gateway.http.endpoints.responses.files.allowUrl=false` e/ou `gateway.http.endpoints.responses.images.allowUrl=false` para desabilitar a busca por URL. - Cabeçalho opcional de endurecimento de resposta: - - `gateway.http.securityHeaders.strictTransportSecurity` (defina apenas para origens HTTPS que você controla; consulte [Auth de proxy confiável](/pt-BR/gateway/trusted-proxy-auth#tls-termination-and-hsts)) + - `gateway.http.securityHeaders.strictTransportSecurity` (defina apenas para origens HTTPS sob seu controle; consulte [Trusted Proxy Auth](/pt-BR/gateway/trusted-proxy-auth#tls-termination-and-hsts)) -### Isolamento de múltiplas instâncias +### Isolamento de várias instâncias -Execute vários gateways em um host com portas e diretórios de estado exclusivos: +Execute vários gateways em um único host com portas e diretórios de estado exclusivos: ```bash OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ @@ -3006,7 +3141,7 @@ openclaw gateway --port 19001 Flags de conveniência: `--dev` (usa `~/.openclaw-dev` + porta `19001`), `--profile ` (usa `~/.openclaw-`). -Consulte [Múltiplos Gateways](/pt-BR/gateway/multiple-gateways). +Consulte [Multiple Gateways](/pt-BR/gateway/multiple-gateways). ### `gateway.tls` @@ -3026,9 +3161,9 @@ Consulte [Múltiplos Gateways](/pt-BR/gateway/multiple-gateways). - `enabled`: habilita terminação TLS no listener do gateway (HTTPS/WSS) (padrão: `false`). - `autoGenerate`: gera automaticamente um par local de certificado/chave autoassinado quando arquivos explícitos não estão configurados; apenas para uso local/dev. -- `certPath`: caminho no sistema de arquivos para o arquivo de certificado TLS. -- `keyPath`: caminho no sistema de arquivos para o arquivo de chave privada TLS; mantenha permissões restritas. -- `caPath`: caminho opcional para bundle de CA para verificação de cliente ou cadeias de confiança personalizadas. +- `certPath`: caminho no sistema de arquivos para o arquivo do certificado TLS. +- `keyPath`: caminho no sistema de arquivos para o arquivo da chave privada TLS; mantenha permissões restritas. +- `caPath`: caminho opcional do bundle de CA para verificação de cliente ou cadeias de confiança personalizadas. ### `gateway.reload` @@ -3045,12 +3180,12 @@ Consulte [Múltiplos Gateways](/pt-BR/gateway/multiple-gateways). ``` - `mode`: controla como edições de configuração são aplicadas em runtime. - - `"off"`: ignora edições ao vivo; mudanças exigem reinicialização explícita. - - `"restart"`: sempre reinicia o processo do gateway ao mudar a configuração. - - `"hot"`: aplica mudanças em processo, sem reiniciar. - - `"hybrid"` (padrão): tenta hot reload primeiro; recorre à reinicialização se necessário. -- `debounceMs`: janela de debounce em ms antes de as mudanças de configuração serem aplicadas (inteiro não negativo). -- `deferralTimeoutMs`: tempo máximo em ms de espera por operações em andamento antes de forçar uma reinicialização (padrão: `300000` = 5 minutos). + - `"off"`: ignora edições em tempo real; mudanças exigem reinicialização explícita. + - `"restart"`: sempre reinicia o processo do gateway em caso de mudança de configuração. + - `"hot"`: aplica mudanças no processo sem reinicializar. + - `"hybrid"` (padrão): tenta hot reload primeiro; usa reinicialização como fallback se necessário. +- `debounceMs`: janela de debounce em ms antes de aplicar mudanças de configuração (inteiro não negativo). +- `deferralTimeoutMs`: tempo máximo em ms para esperar operações em andamento antes de forçar uma reinicialização (padrão: `300000` = 5 minutos). --- @@ -3094,30 +3229,30 @@ Observações de validação e segurança: - `hooks.enabled=true` exige `hooks.token` não vazio. - `hooks.token` deve ser **diferente** de `gateway.auth.token`; reutilizar o token do Gateway é rejeitado. -- `hooks.path` não pode ser `/`; use um subcaminho dedicado como `/hooks`. +- `hooks.path` não pode ser `/`; use um subcaminho dedicado, como `/hooks`. - Se `hooks.allowRequestSessionKey=true`, restrinja `hooks.allowedSessionKeyPrefixes` (por exemplo `["hook:"]`). **Endpoints:** - `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }` - `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }` - - `sessionKey` da carga útil da requisição é aceito apenas quando `hooks.allowRequestSessionKey=true` (padrão: `false`). + - `sessionKey` da carga da requisição é aceito apenas quando `hooks.allowRequestSessionKey=true` (padrão: `false`). - `POST /hooks/` → resolvido via `hooks.mappings` - `match.path` corresponde ao subcaminho após `/hooks` (por exemplo `/hooks/gmail` → `gmail`). -- `match.source` corresponde a um campo da carga útil para caminhos genéricos. -- Templates como `{{messages[0].subject}}` leem da carga útil. +- `match.source` corresponde a um campo da carga para caminhos genéricos. +- Templates como `{{messages[0].subject}}` leem a partir da carga. - `transform` pode apontar para um módulo JS/TS que retorna uma ação de hook. - - `transform.module` deve ser um caminho relativo e permanecer dentro de `hooks.transformsDir` (caminhos absolutos e travessia de diretório são rejeitados). -- `agentId` roteia para um agente específico; IDs desconhecidas recorrem ao padrão. -- `allowedAgentIds`: restringe o roteamento explícito (`*` ou omitido = permite todos, `[]` = nega todos). + - `transform.module` deve ser um caminho relativo e permanecer dentro de `hooks.transformsDir` (caminhos absolutos e travessia são rejeitados). +- `agentId` roteia para um agente específico; IDs desconhecidos usam o agente padrão como fallback. +- `allowedAgentIds`: restringe roteamento explícito (`*` ou omitido = permite todos, `[]` = nega todos). - `defaultSessionKey`: chave de sessão fixa opcional para execuções de agente por hook sem `sessionKey` explícito. - `allowRequestSessionKey`: permite que chamadores de `/hooks/agent` definam `sessionKey` (padrão: `false`). -- `allowedSessionKeyPrefixes`: lista de permissões opcional de prefixos para valores explícitos de `sessionKey` (requisição + mapeamento), por exemplo `["hook:"]`. -- `deliver: true` envia a resposta final para um canal; `channel` usa `last` por padrão. -- `model` substitui o LLM para esta execução do hook (deve ser permitido se o catálogo de modelos estiver definido). +- `allowedSessionKeyPrefixes`: allowlist opcional de prefixos para valores explícitos de `sessionKey` (requisição + mapeamento), por exemplo `["hook:"]`. +- `deliver: true` envia a resposta final para um canal; `channel` usa `last` como padrão. +- `model` substitui o LLM para esta execução de hook (deve ser permitido se o catálogo de modelos estiver definido). @@ -3156,18 +3291,18 @@ Observações de validação e segurança: canvasHost: { root: "~/.openclaw/workspace/canvas", liveReload: true, - // enabled: false, // ou OPENCLAW_SKIP_CANVAS_HOST=1 + // enabled: false, // or OPENCLAW_SKIP_CANVAS_HOST=1 }, } ``` -- Serve HTML/CSS/JS editáveis pelo agente e A2UI por HTTP sob a porta do Gateway: +- Serve HTML/CSS/JS editáveis pelo agente e A2UI por HTTP na porta do Gateway: - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` -- Somente local: mantenha `gateway.bind: "loopback"` (padrão). -- Binds fora de loopback: rotas do canvas exigem auth do Gateway (token/password/trusted-proxy), igual às outras superfícies HTTP do Gateway. -- WebViews de Node normalmente não enviam cabeçalhos de auth; depois que um Node é pareado e conectado, o Gateway anuncia URLs de capacidade com escopo de Node para acesso a canvas/A2UI. -- URLs de capacidade são vinculadas à sessão WS ativa do Node e expiram rapidamente. Não é usado fallback baseado em IP. +- Apenas local: mantenha `gateway.bind: "loopback"` (padrão). +- Binds fora de loopback: rotas de canvas exigem auth do Gateway (token/senha/trusted-proxy), assim como outras superfícies HTTP do Gateway. +- Normalmente, Node WebViews não enviam cabeçalhos de auth; depois que um node é pareado e conectado, o Gateway anuncia URLs de capacidade com escopo do node para acesso a canvas/A2UI. +- URLs de capacidade são vinculadas à sessão WS ativa do node e expiram rapidamente. Fallback baseado em IP não é usado. - Injeta cliente de live reload no HTML servido. - Cria automaticamente um `index.html` inicial quando vazio. - Também serve A2UI em `/__openclaw__/a2ui/`. @@ -3176,7 +3311,7 @@ Observações de validação e segurança: --- -## Descoberta +## Discovery ### mDNS (Bonjour) @@ -3192,9 +3327,9 @@ Observações de validação e segurança: - `minimal` (padrão): omite `cliPath` + `sshPort` dos registros TXT. - `full`: inclui `cliPath` + `sshPort`. -- O hostname usa `openclaw` por padrão. Substitua com `OPENCLAW_MDNS_HOSTNAME`. +- O hostname usa `openclaw` como padrão. Substitua com `OPENCLAW_MDNS_HOSTNAME`. -### Área ampla (DNS-SD) +### Wide-area (DNS-SD) ```json5 { @@ -3204,7 +3339,7 @@ Observações de validação e segurança: } ``` -Grava uma zona DNS-SD unicast em `~/.openclaw/dns/`. Para descoberta entre redes, combine com um servidor DNS (CoreDNS recomendado) + DNS dividido do Tailscale. +Grava uma zona DNS-SD unicast em `~/.openclaw/dns/`. Para discovery entre redes, combine com um servidor DNS (CoreDNS recomendado) + split DNS do Tailscale. Configuração: `openclaw dns setup --apply`. @@ -3230,13 +3365,13 @@ Configuração: `openclaw dns setup --apply`. ``` - Variáveis de ambiente inline são aplicadas apenas se o ambiente do processo não tiver a chave. -- Arquivos `.env`: `.env` do diretório atual + `~/.openclaw/.env` (nenhum substitui variáveis existentes). -- `shellEnv`: importa chaves esperadas ausentes do perfil do seu shell de login. +- Arquivos `.env`: `.env` do CWD + `~/.openclaw/.env` (nenhum substitui variáveis existentes). +- `shellEnv`: importa chaves esperadas ausentes a partir do perfil do seu shell de login. - Consulte [Environment](/pt-BR/help/environment) para a precedência completa. ### Substituição de variável de ambiente -Referencie variáveis de ambiente em qualquer string de configuração com `${VAR_NAME}`: +Faça referência a variáveis de ambiente em qualquer string de configuração com `${VAR_NAME}`: ```json5 { @@ -3248,14 +3383,14 @@ Referencie variáveis de ambiente em qualquer string de configuração com `${VA - Apenas nomes em maiúsculas são correspondidos: `[A-Z_][A-Z0-9_]*`. - Variáveis ausentes/vazias geram erro no carregamento da configuração. -- Escape com `$${VAR}` para um `${VAR}` literal. +- Escape com `$${VAR}` para um literal `${VAR}`. - Funciona com `$include`. --- ## Segredos -Referências de segredo são aditivas: valores em texto simples continuam funcionando. +Refs de segredo são aditivas: valores em texto simples continuam funcionando. ### `SecretRef` @@ -3271,13 +3406,13 @@ Validação: - padrão de id para `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$` - `source: "file"` id: ponteiro JSON absoluto (por exemplo `"/providers/openai/apiKey"`) - padrão de id para `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` -- ids com `source: "exec"` não devem conter segmentos de caminho delimitados por `/` iguais a `.` ou `..` (por exemplo `a/../b` é rejeitado) +- IDs de `source: "exec"` não devem conter segmentos de caminho delimitados por `/` iguais a `.` ou `..` (por exemplo `a/../b` é rejeitado) -### Superfície de credenciais compatível +### Superfície de credencial compatível -- Matriz canônica: [Superfície de credenciais SecretRef](/pt-BR/reference/secretref-credential-surface) -- `secrets apply` direciona caminhos de credenciais compatíveis em `openclaw.json`. -- Referências em `auth-profiles.json` estão incluídas na resolução em runtime e na cobertura de auditoria. +- Matriz canônica: [SecretRef Credential Surface](/pt-BR/reference/secretref-credential-surface) +- `secrets apply` tem como alvo caminhos de credencial compatíveis em `openclaw.json`. +- Refs de `auth-profiles.json` estão incluídas na resolução em runtime e na cobertura de auditoria. ### Configuração de provedores de segredo @@ -3285,7 +3420,7 @@ Validação: { secrets: { providers: { - default: { source: "env" }, // provedor explícito de env opcional + default: { source: "env" }, // optional explicit env provider filemain: { source: "file", path: "~/.openclaw/secrets.json", @@ -3309,13 +3444,13 @@ Validação: Observações: -- O provedor `file` é compatível com `mode: "json"` e `mode: "singleValue"` (`id` deve ser `"value"` no modo singleValue). -- O provedor `exec` exige um caminho `command` absoluto e usa cargas úteis de protocolo em stdin/stdout. -- Por padrão, caminhos de comando com symlink são rejeitados. Defina `allowSymlinkCommand: true` para permitir caminhos com symlink enquanto valida o caminho alvo resolvido. -- Se `trustedDirs` estiver configurado, a verificação de diretório confiável se aplica ao caminho alvo resolvido. -- O ambiente do processo filho `exec` é mínimo por padrão; passe variáveis necessárias explicitamente com `passEnv`. -- Referências de segredo são resolvidas no momento da ativação em um snapshot em memória, depois os caminhos de requisição leem apenas o snapshot. -- A filtragem de superfície ativa se aplica durante a ativação: refs não resolvidas em superfícies habilitadas falham a inicialização/reload, enquanto superfícies inativas são ignoradas com diagnósticos. +- O provedor `file` aceita `mode: "json"` e `mode: "singleValue"` (`id` deve ser `"value"` no modo singleValue). +- O provedor `exec` exige um caminho `command` absoluto e usa cargas do protocolo em stdin/stdout. +- Por padrão, caminhos de comando symlink são rejeitados. Defina `allowSymlinkCommand: true` para permitir caminhos symlink, validando o caminho de destino resolvido. +- Se `trustedDirs` estiver configurado, a verificação de diretório confiável se aplica ao caminho de destino resolvido. +- O ambiente filho de `exec` é mínimo por padrão; passe explicitamente variáveis necessárias com `passEnv`. +- Refs de segredo são resolvidas no momento da ativação em um snapshot em memória, e depois os caminhos de requisição leem apenas esse snapshot. +- A filtragem de superfície ativa se aplica durante a ativação: refs não resolvidas em superfícies habilitadas fazem a inicialização/reload falhar, enquanto superfícies inativas são ignoradas com diagnósticos. --- @@ -3338,12 +3473,12 @@ Observações: ``` - Perfis por agente são armazenados em `/auth-profiles.json`. -- `auth-profiles.json` é compatível com refs em nível de valor (`keyRef` para `api_key`, `tokenRef` para `token`) para modos de credencial estática. -- Perfis em modo OAuth (`auth.profiles..mode = "oauth"`) não são compatíveis com credenciais de auth-profile com suporte de SecretRef. -- Credenciais estáticas de runtime vêm de snapshots resolvidos em memória; entradas legadas estáticas de `auth.json` são removidas quando descobertas. -- Importações legadas de OAuth de `~/.openclaw/credentials/oauth.json`. +- `auth-profiles.json` aceita refs em nível de valor (`keyRef` para `api_key`, `tokenRef` para `token`) para modos de credencial estática. +- Perfis em modo OAuth (`auth.profiles..mode = "oauth"`) não aceitam credenciais de perfil de auth com suporte de SecretRef. +- Credenciais estáticas de runtime vêm de snapshots resolvidos em memória; entradas estáticas legadas de `auth.json` são limpas quando encontradas. +- Importações legadas de OAuth vêm de `~/.openclaw/credentials/oauth.json`. - Consulte [OAuth](/pt-BR/concepts/oauth). -- Comportamento do runtime de segredos e ferramentas de `audit/configure/apply`: [Gerenciamento de segredos](/pt-BR/gateway/secrets). +- Comportamento do runtime de segredos e ferramentas `audit/configure/apply`: [Secrets Management](/pt-BR/gateway/secrets). ### `auth.cooldowns` @@ -3365,21 +3500,20 @@ Observações: } ``` -- `billingBackoffHours`: backoff base em horas quando um perfil falha por erros reais - de cobrança/crédito insuficiente (padrão: `5`). Texto explícito de cobrança ainda pode - cair aqui mesmo em respostas `401`/`403`, mas matchers de texto específicos de provedor - permanecem restritos ao provedor ao qual pertencem (por exemplo OpenRouter - `Key limit exceeded`). Mensagens de janela de uso `402` com nova tentativa permitida ou - de limite de gasto de organização/workspace permanecem no caminho `rate_limit` - em vez disso. +- `billingBackoffHours`: backoff base em horas quando um perfil falha por erros reais de + cobrança/crédito insuficiente (padrão: `5`). Texto explícito de cobrança ainda pode + cair aqui mesmo em respostas `401`/`403`, mas correspondências de texto + específicas de provedor permanecem restritas ao provedor que as define (por exemplo OpenRouter + `Key limit exceeded`). Mensagens HTTP `402` retryable de janela de uso ou + limite de gasto de organização/workspace permanecem no caminho `rate_limit`. - `billingBackoffHoursByProvider`: substituições opcionais por provedor para horas de backoff de cobrança. -- `billingMaxHours`: limite máximo em horas para crescimento exponencial do backoff de cobrança (padrão: `24`). +- `billingMaxHours`: limite em horas para crescimento exponencial do backoff de cobrança (padrão: `24`). - `authPermanentBackoffMinutes`: backoff base em minutos para falhas `auth_permanent` de alta confiança (padrão: `10`). -- `authPermanentMaxMinutes`: limite máximo em minutos para crescimento do backoff de `auth_permanent` (padrão: `60`). -- `failureWindowHours`: janela contínua em horas usada para contadores de backoff (padrão: `24`). -- `overloadedProfileRotations`: máximo de rotações de auth-profile do mesmo provedor para erros de sobrecarga antes de mudar para fallback de modelo (padrão: `1`). Formatos de provedor ocupado como `ModelNotReadyException` caem aqui. +- `authPermanentMaxMinutes`: limite em minutos para crescimento do backoff de `auth_permanent` (padrão: `60`). +- `failureWindowHours`: janela móvel em horas usada para contadores de backoff (padrão: `24`). +- `overloadedProfileRotations`: máximo de rotações de perfil de auth do mesmo provedor para erros de sobrecarga antes de mudar para fallback de modelo (padrão: `1`). Formatos de provedor ocupado, como `ModelNotReadyException`, caem aqui. - `overloadedBackoffMs`: atraso fixo antes de tentar novamente uma rotação de provedor/perfil sobrecarregado (padrão: `0`). -- `rateLimitedProfileRotations`: máximo de rotações de auth-profile do mesmo provedor para erros de limite de taxa antes de mudar para fallback de modelo (padrão: `1`). Esse bucket de limite de taxa inclui textos no formato do provedor, como `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` e `resource exhausted`. +- `rateLimitedProfileRotations`: máximo de rotações de perfil de auth do mesmo provedor para erros de limite de taxa antes de mudar para fallback de modelo (padrão: `1`). Esse bucket de limite de taxa inclui texto com formato de provedor, como `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` e `resource exhausted`. --- @@ -3400,7 +3534,7 @@ Observações: - Arquivo de log padrão: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`. - Defina `logging.file` para um caminho estável. -- `consoleLevel` sobe para `debug` com `--verbose`. +- `consoleLevel` sobe para `debug` quando `--verbose`. - `maxFileBytes`: tamanho máximo do arquivo de log em bytes antes que gravações sejam suprimidas (inteiro positivo; padrão: `524288000` = 500 MB). Use rotação externa de logs para implantações de produção. --- @@ -3438,10 +3572,10 @@ Observações: } ``` -- `enabled`: chave mestre para saída de instrumentação (padrão: `true`). -- `flags`: array de strings de flag que habilitam saída de log direcionada (aceita curingas como `"telegram.*"` ou `"*"`). -- `stuckSessionWarnMs`: limite de idade em ms para emitir avisos de sessão travada enquanto uma sessão permanece em estado de processamento. -- `otel.enabled`: habilita o pipeline de exportação OpenTelemetry (padrão: `false`). +- `enabled`: chave mestra para saída de instrumentação (padrão: `true`). +- `flags`: array de strings de flag que habilita saída de log direcionada (oferece suporte a curingas como `"telegram.*"` ou `"*"`). +- `stuckSessionWarnMs`: limite de idade em ms para emitir avisos de sessão travada enquanto uma sessão permanece no estado de processamento. +- `otel.enabled`: habilita o pipeline de exportação do OpenTelemetry (padrão: `false`). - `otel.endpoint`: URL do coletor para exportação OTel. - `otel.protocol`: `"http/protobuf"` (padrão) ou `"grpc"`. - `otel.headers`: cabeçalhos extras de metadados HTTP/gRPC enviados com requisições de exportação OTel. @@ -3451,7 +3585,7 @@ Observações: - `otel.flushIntervalMs`: intervalo periódico de flush de telemetria em ms. - `cacheTrace.enabled`: registra snapshots de rastreamento de cache para execuções embutidas (padrão: `false`). - `cacheTrace.filePath`: caminho de saída para JSONL de rastreamento de cache (padrão: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). -- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: controlam o que é incluído na saída de rastreamento de cache (todos usam `true` por padrão). +- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: controlam o que é incluído na saída de rastreamento de cache (todos usam `true` como padrão). --- @@ -3475,10 +3609,10 @@ Observações: - `channel`: canal de release para instalações npm/git — `"stable"`, `"beta"` ou `"dev"`. - `checkOnStart`: verifica atualizações npm quando o gateway inicia (padrão: `true`). -- `auto.enabled`: habilita atualização automática em segundo plano para instalações de pacote (padrão: `false`). -- `auto.stableDelayHours`: atraso mínimo em horas antes da aplicação automática no canal estável (padrão: `6`; máximo: `168`). -- `auto.stableJitterHours`: janela extra de distribuição de rollout do canal estável em horas (padrão: `12`; máximo: `168`). -- `auto.betaCheckIntervalHours`: frequência com que verificações do canal beta são executadas, em horas (padrão: `1`; máximo: `24`). +- `auto.enabled`: habilita atualização automática em segundo plano para instalações por pacote (padrão: `false`). +- `auto.stableDelayHours`: atraso mínimo em horas antes da aplicação automática no canal estável (padrão: `6`; máx.: `168`). +- `auto.stableJitterHours`: janela extra de distribuição de rollout do canal estável em horas (padrão: `12`; máx.: `168`). +- `auto.betaCheckIntervalHours`: frequência, em horas, das verificações no canal beta (padrão: `1`; máx.: `24`). --- @@ -3511,22 +3645,22 @@ Observações: } ``` -- `enabled`: chave global de recurso do ACP (padrão: `false`). +- `enabled`: chave global de recurso ACP (padrão: `false`). - `dispatch.enabled`: chave independente para despacho de turno de sessão ACP (padrão: `true`). Defina `false` para manter comandos ACP disponíveis enquanto bloqueia a execução. -- `backend`: id padrão do backend de runtime ACP (deve corresponder a um Plugin de runtime ACP registrado). -- `defaultAgent`: id do agente alvo de fallback do ACP quando os spawns não especificam um alvo explícito. -- `allowedAgents`: lista de permissões de IDs de agente permitidas para sessões de runtime ACP; vazio significa nenhuma restrição adicional. +- `backend`: ID padrão do backend de runtime ACP (deve corresponder a um Plugin de runtime ACP registrado). +- `defaultAgent`: ID do agente ACP de fallback quando spawns não especificam um alvo explícito. +- `allowedAgents`: allowlist de IDs de agente permitidos para sessões de runtime ACP; vazio significa nenhuma restrição adicional. - `maxConcurrentSessions`: máximo de sessões ACP ativas simultaneamente. -- `stream.coalesceIdleMs`: janela de flush por inatividade em ms para texto em streaming. -- `stream.maxChunkChars`: tamanho máximo do bloco antes de dividir a projeção de bloco em streaming. +- `stream.coalesceIdleMs`: janela de flush por inatividade em ms para texto transmitido. +- `stream.maxChunkChars`: tamanho máximo de bloco antes da divisão da projeção do bloco transmitido. - `stream.repeatSuppression`: suprime linhas repetidas de status/ferramenta por turno (padrão: `true`). - `stream.deliveryMode`: `"live"` transmite incrementalmente; `"final_only"` faz buffer até eventos terminais do turno. -- `stream.hiddenBoundarySeparator`: separador antes de texto visível após eventos ocultos de ferramenta (padrão: `"paragraph"`). +- `stream.hiddenBoundarySeparator`: separador antes do texto visível após eventos ocultos de ferramenta (padrão: `"paragraph"`). - `stream.maxOutputChars`: máximo de caracteres de saída do assistente projetados por turno ACP. - `stream.maxSessionUpdateChars`: máximo de caracteres para linhas projetadas de status/atualização ACP. -- `stream.tagVisibility`: registro de nomes de tag para substituições booleanas de visibilidade em eventos em streaming. -- `runtime.ttlMinutes`: TTL de inatividade em minutos para workers de sessão ACP antes de serem elegíveis para limpeza. -- `runtime.installCommand`: comando de instalação opcional a executar ao inicializar um ambiente de runtime ACP. +- `stream.tagVisibility`: registro de nomes de tag para substituições booleanas de visibilidade em eventos transmitidos. +- `runtime.ttlMinutes`: TTL de inatividade em minutos para workers de sessão ACP antes de ficarem elegíveis para limpeza. +- `runtime.installCommand`: comando de instalação opcional a ser executado ao inicializar um ambiente de runtime ACP. --- @@ -3545,12 +3679,12 @@ Observações: - `cli.banner.taglineMode` controla o estilo da tagline do banner: - `"random"` (padrão): taglines rotativas engraçadas/sazonais. - `"default"`: tagline neutra fixa (`All your chats, one OpenClaw.`). - - `"off"`: sem texto de tagline (o título/versão do banner ainda é mostrado). -- Para ocultar o banner inteiro (não apenas as taglines), defina a variável de ambiente `OPENCLAW_HIDE_BANNER=1`. + - `"off"`: sem texto de tagline (título/versão do banner continuam visíveis). +- Para ocultar o banner inteiro (não apenas taglines), defina a variável de ambiente `OPENCLAW_HIDE_BANNER=1`. --- -## Assistente +## Wizard Metadados gravados por fluxos guiados de configuração da CLI (`onboard`, `configure`, `doctor`): @@ -3605,22 +3739,22 @@ As builds atuais não incluem mais a bridge TCP. Nodes se conectam pelo WebSocke cron: { enabled: true, maxConcurrentRuns: 2, - webhook: "https://example.invalid/legacy", // fallback legado obsoleto para jobs armazenados com notify:true - webhookToken: "replace-with-dedicated-token", // token bearer opcional para auth de webhook de saída - sessionRetention: "24h", // string de duração ou false + webhook: "https://example.invalid/legacy", // deprecated fallback for stored notify:true jobs + webhookToken: "replace-with-dedicated-token", // optional bearer token for outbound webhook auth + sessionRetention: "24h", // duration string or false runLog: { - maxBytes: "2mb", // padrão 2_000_000 bytes - keepLines: 2000, // padrão 2000 + maxBytes: "2mb", // default 2_000_000 bytes + keepLines: 2000, // default 2000 }, }, } ``` -- `sessionRetention`: por quanto tempo manter sessões concluídas de execuções isoladas do Cron antes de removê-las de `sessions.json`. Também controla a limpeza de transcrições arquivadas excluídas do Cron. Padrão: `24h`; defina `false` para desabilitar. -- `runLog.maxBytes`: tamanho máximo por arquivo de log de execução (`cron/runs/.jsonl`) antes da limpeza. Padrão: `2_000_000` bytes. -- `runLog.keepLines`: linhas mais recentes mantidas quando a limpeza do log de execução é acionada. Padrão: `2000`. -- `webhookToken`: token bearer usado para entrega POST de webhook do Cron (`delivery.mode = "webhook"`); se omitido, nenhum cabeçalho de auth é enviado. -- `webhook`: URL de webhook legada obsoleta de fallback (http/https) usada apenas para jobs armazenados que ainda têm `notify: true`. +- `sessionRetention`: por quanto tempo manter sessões concluídas de execuções isoladas de Cron antes de removê-las de `sessions.json`. Também controla a limpeza de transcrições arquivadas e excluídas de Cron. Padrão: `24h`; defina `false` para desabilitar. +- `runLog.maxBytes`: tamanho máximo por arquivo de log de execução (`cron/runs/.jsonl`) antes da remoção. Padrão: `2_000_000` bytes. +- `runLog.keepLines`: linhas mais recentes mantidas quando a remoção do log de execução é disparada. Padrão: `2000`. +- `webhookToken`: token bearer usado para entrega POST de Webhook do Cron (`delivery.mode = "webhook"`); se omitido, nenhum cabeçalho de auth é enviado. +- `webhook`: URL de Webhook de fallback legada e obsoleta (http/https), usada apenas para jobs armazenados que ainda tenham `notify: true`. ### `cron.retry` @@ -3636,9 +3770,9 @@ As builds atuais não incluem mais a bridge TCP. Nodes se conectam pelo WebSocke } ``` -- `maxAttempts`: máximo de novas tentativas para jobs de execução única em erros transitórios (padrão: `3`; intervalo: `0`–`10`). -- `backoffMs`: array de atrasos de backoff em ms para cada tentativa de nova execução (padrão: `[30000, 60000, 300000]`; 1–10 entradas). -- `retryOn`: tipos de erro que acionam novas tentativas — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Omita para tentar novamente em todos os tipos transitórios. +- `maxAttempts`: máximo de tentativas para jobs de execução única em erros transitórios (padrão: `3`; intervalo: `0`–`10`). +- `backoffMs`: array de atrasos de backoff em ms para cada tentativa de retry (padrão: `[30000, 60000, 300000]`; 1–10 entradas). +- `retryOn`: tipos de erro que disparam retries — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Omita para tentar novamente todos os tipos transitórios. Aplica-se apenas a jobs de Cron de execução única. Jobs recorrentes usam tratamento de falha separado. @@ -3659,10 +3793,10 @@ Aplica-se apenas a jobs de Cron de execução única. Jobs recorrentes usam trat ``` - `enabled`: habilita alertas de falha para jobs de Cron (padrão: `false`). -- `after`: falhas consecutivas antes de um alerta ser disparado (inteiro positivo, mín.: `1`). -- `cooldownMs`: mínimo de milissegundos entre alertas repetidos para o mesmo job (inteiro não negativo). -- `mode`: modo de entrega — `"announce"` envia por mensagem de canal; `"webhook"` faz POST no webhook configurado. -- `accountId`: id opcional de conta ou canal para definir o escopo da entrega do alerta. +- `after`: falhas consecutivas antes de disparar um alerta (inteiro positivo, mín.: `1`). +- `cooldownMs`: milissegundos mínimos entre alertas repetidos para o mesmo job (inteiro não negativo). +- `mode`: modo de entrega — `"announce"` envia por mensagem de canal; `"webhook"` publica no Webhook configurado. +- `accountId`: ID opcional de conta ou canal para delimitar a entrega do alerta. ### `cron.failureDestination` @@ -3679,16 +3813,16 @@ Aplica-se apenas a jobs de Cron de execução única. Jobs recorrentes usam trat } ``` -- Destino padrão para notificações de falha do Cron em todos os jobs. -- `mode`: `"announce"` ou `"webhook"`; usa `"announce"` por padrão quando existem dados de destino suficientes. +- Destino padrão para notificações de falha de Cron em todos os jobs. +- `mode`: `"announce"` ou `"webhook"`; usa `"announce"` como padrão quando existem dados de destino suficientes. - `channel`: substituição de canal para entrega por announce. `"last"` reutiliza o último canal de entrega conhecido. -- `to`: destino explícito de announce ou URL de webhook. Obrigatório no modo webhook. +- `to`: alvo explícito de announce ou URL de Webhook. Obrigatório para o modo webhook. - `accountId`: substituição opcional de conta para entrega. - `delivery.failureDestination` por job substitui esse padrão global. -- Quando nem o destino global nem o por job estiver definido, jobs que já entregam via `announce` recorrem a esse alvo principal de announce em caso de falha. +- Quando nem o destino global nem o destino por job de falha estão definidos, jobs que já entregam via `announce` usam como fallback esse alvo principal de announce em caso de falha. - `delivery.failureDestination` só é compatível com jobs `sessionTarget="isolated"`, a menos que o `delivery.mode` principal do job seja `"webhook"`. -Consulte [Jobs de Cron](/pt-BR/automation/cron-jobs). Execuções isoladas do Cron são rastreadas como [tarefas em segundo plano](/pt-BR/automation/tasks). +Consulte [Cron Jobs](/pt-BR/automation/cron-jobs). Execuções isoladas de Cron são rastreadas como [background tasks](/pt-BR/automation/tasks). --- @@ -3696,27 +3830,27 @@ Consulte [Jobs de Cron](/pt-BR/automation/cron-jobs). Execuções isoladas do Cr Placeholders de template expandidos em `tools.media.models[].args`: -| Variável | Descrição | -| ------------------ | ------------------------------------------------- | -| `{{Body}}` | Corpo completo da mensagem recebida | +| Variável | Descrição | +| ------------------ | ----------------------------------------------- | +| `{{Body}}` | Corpo completo da mensagem recebida | | `{{RawBody}}` | Corpo bruto (sem wrappers de histórico/remetente) | -| `{{BodyStripped}}` | Corpo com menções de grupo removidas | -| `{{From}}` | Identificador do remetente | -| `{{To}}` | Identificador de destino | -| `{{MessageSid}}` | id da mensagem do canal | -| `{{SessionId}}` | UUID da sessão atual | -| `{{IsNewSession}}` | `"true"` quando uma nova sessão é criada | -| `{{MediaUrl}}` | pseudo-URL da mídia recebida | -| `{{MediaPath}}` | caminho local da mídia | -| `{{MediaType}}` | tipo de mídia (image/audio/document/…) | -| `{{Transcript}}` | transcrição do áudio | -| `{{Prompt}}` | prompt de mídia resolvido para entradas CLI | -| `{{MaxChars}}` | máximo de caracteres de saída resolvido para entradas CLI | -| `{{ChatType}}` | `"direct"` ou `"group"` | -| `{{GroupSubject}}` | assunto do grupo (best effort) | -| `{{GroupMembers}}` | prévia de membros do grupo (best effort) | -| `{{SenderName}}` | nome de exibição do remetente (best effort) | -| `{{SenderE164}}` | número de telefone do remetente (best effort) | +| `{{BodyStripped}}` | Corpo com menções de grupo removidas | +| `{{From}}` | Identificador do remetente | +| `{{To}}` | Identificador de destino | +| `{{MessageSid}}` | ID da mensagem do canal | +| `{{SessionId}}` | UUID da sessão atual | +| `{{IsNewSession}}` | `"true"` quando uma nova sessão é criada | +| `{{MediaUrl}}` | pseudo-URL da mídia recebida | +| `{{MediaPath}}` | caminho local da mídia | +| `{{MediaType}}` | tipo de mídia (image/audio/document/…) | +| `{{Transcript}}` | transcrição do áudio | +| `{{Prompt}}` | prompt de mídia resolvido para entradas de CLI | +| `{{MaxChars}}` | máximo de caracteres de saída resolvido para entradas de CLI | +| `{{ChatType}}` | `"direct"` ou `"group"` | +| `{{GroupSubject}}` | assunto do grupo (melhor esforço) | +| `{{GroupMembers}}` | prévia dos membros do grupo (melhor esforço) | +| `{{SenderName}}` | nome de exibição do remetente (melhor esforço) | +| `{{SenderE164}}` | número de telefone do remetente (melhor esforço) | | `{{Provider}}` | dica de provedor (whatsapp, telegram, discord etc.) | --- @@ -3738,13 +3872,13 @@ Divida a configuração em vários arquivos: **Comportamento de mesclagem:** -- Arquivo único: substitui o objeto que o contém. -- Array de arquivos: mesclagem profunda em ordem (os posteriores substituem os anteriores). -- Chaves irmãs: mescladas após os includes (substituem valores incluídos). +- Arquivo único: substitui o objeto contêiner. +- Array de arquivos: mesclado profundamente em ordem (os posteriores substituem os anteriores). +- Chaves irmãs: mescladas após os includes (substituem os valores incluídos). - Includes aninhados: até 10 níveis de profundidade. -- Caminhos: resolvidos em relação ao arquivo que inclui, mas devem permanecer dentro do diretório de configuração de nível superior (`dirname` de `openclaw.json`). Formas absolutas/`../` são permitidas apenas quando ainda se resolvem dentro desse limite. +- Caminhos: resolvidos em relação ao arquivo que inclui, mas devem permanecer dentro do diretório de configuração de nível superior (`dirname` de `openclaw.json`). Formatos absolutos/`../` são permitidos apenas quando ainda resolvem dentro desse limite. - Erros: mensagens claras para arquivos ausentes, erros de parse e includes circulares. --- -_Relacionado: [Configuration](/pt-BR/gateway/configuration) · [Exemplos de configuração](/pt-BR/gateway/configuration-examples) · [Doctor](/pt-BR/gateway/doctor)_ +_Relacionado: [Configuration](/pt-BR/gateway/configuration) · [Configuration Examples](/pt-BR/gateway/configuration-examples) · [Doctor](/pt-BR/gateway/doctor)_ diff --git a/docs/pt-BR/plugins/sdk-channel-plugins.md b/docs/pt-BR/plugins/sdk-channel-plugins.md index 6f3db3b69..7020e07a9 100644 --- a/docs/pt-BR/plugins/sdk-channel-plugins.md +++ b/docs/pt-BR/plugins/sdk-channel-plugins.md @@ -7,19 +7,19 @@ sidebarTitle: Channel Plugins summary: Guia passo a passo para criar um Plugin de canal de mensagens para OpenClaw title: Criando Plugins de canal x-i18n: - generated_at: "2026-04-15T05:33:50Z" + generated_at: "2026-04-15T19:41:41Z" model: gpt-5.4 provider: openai - source_hash: a7f4c746fe3163a8880e14c433f4db4a1475535d91716a53fb879551d8d62f65 + source_hash: 80e47e61d1e47738361692522b79aff276544446c58a7b41afe5296635dfad4b source_path: plugins/sdk-channel-plugins.md workflow: 15 --- # Criando Plugins de canal -Este guia apresenta a criação de um Plugin de canal que conecta o OpenClaw a uma +Este guia mostra como criar um Plugin de canal que conecta o OpenClaw a uma plataforma de mensagens. Ao final, você terá um canal funcional com segurança em DM, -pareamento, encadeamento de respostas e mensagens de saída. +emparelhamento, encadeamento de respostas e mensagens de saída. Se você ainda não criou nenhum Plugin do OpenClaw antes, leia @@ -29,86 +29,86 @@ pareamento, encadeamento de respostas e mensagens de saída. ## Como os Plugins de canal funcionam -Plugins de canal não precisam de suas próprias ferramentas de enviar/editar/reagir. O OpenClaw mantém uma +Os Plugins de canal não precisam de suas próprias ferramentas de enviar/editar/reagir. O OpenClaw mantém uma ferramenta `message` compartilhada no core. Seu Plugin é responsável por: - **Configuração** — resolução de conta e assistente de configuração - **Segurança** — política de DM e listas de permissão -- **Pareamento** — fluxo de aprovação de DM -- **Gramática de sessão** — como IDs de conversa específicos do provedor são mapeados para chats base, IDs de thread e fallbacks de pai +- **Emparelhamento** — fluxo de aprovação de DM +- **Gramática de sessão** — como ids de conversa específicos do provedor são mapeados para chats base, ids de thread e fallbacks de pai - **Saída** — envio de texto, mídia e enquetes para a plataforma - **Encadeamento** — como as respostas são encadeadas -O core é responsável pela ferramenta `message` compartilhada, pelo encadeamento de prompts, pelo formato externo da chave de sessão, -pela contabilidade genérica de `:thread:` e pelo dispatch. +O core é responsável pela ferramenta de mensagem compartilhada, pela integração com o prompt, pelo formato externo da chave de sessão, +pela lógica genérica de `:thread:`, e pelo despacho. -Se o seu canal adicionar parâmetros à ferramenta de mensagem que transportam origens de mídia, exponha esses -nomes de parâmetros por meio de `describeMessageTool(...).mediaSourceParams`. O core usa -essa lista explícita para normalização de caminho no sandbox e política de acesso a mídia de saída, -então Plugins não precisam de casos especiais no core compartilhado para parâmetros específicos do provedor +Se o seu canal adicionar parâmetros da ferramenta de mensagem que carregam fontes de mídia, exponha esses +nomes de parâmetro por meio de `describeMessageTool(...).mediaSourceParams`. O core usa +essa lista explícita para normalização de caminho em sandbox e política de acesso +a mídia de saída, para que os Plugins não precisem de casos especiais no core compartilhado para parâmetros específicos do provedor, como avatar, anexo ou imagem de capa. Prefira retornar um mapa indexado por ação, como `{ "set-profile": ["avatarUrl", "avatarPath"] }`, para que ações não relacionadas não herdem os argumentos de mídia de outra ação. Um array simples ainda funciona para parâmetros que são intencionalmente compartilhados entre todas as ações expostas. -Se a sua plataforma armazena escopo extra dentro de IDs de conversa, mantenha essa análise -no Plugin com `messaging.resolveSessionConversation(...)`. Esse é o hook canônico -para mapear `rawId` para o ID base da conversa, ID opcional de thread, +Se a sua plataforma armazenar escopo extra dentro dos ids de conversa, mantenha essa lógica de parsing +no Plugin com `messaging.resolveSessionConversation(...)`. Esse é o hook canônico para mapear +`rawId` para o id da conversa base, id opcional de thread, `baseConversationId` explícito e quaisquer `parentConversationCandidates`. -Ao retornar `parentConversationCandidates`, mantenha-os ordenados do -pai mais específico para a conversa pai mais ampla/base. +Quando você retornar `parentConversationCandidates`, mantenha-os ordenados do +pai mais específico para a conversa base/mais ampla. -Plugins empacotados que precisam da mesma análise antes que o registro de canal seja inicializado -também podem expor um arquivo `session-key-api.ts` de nível superior com uma exportação -correspondente `resolveSessionConversation(...)`. O core usa essa superfície segura para bootstrap +Plugins empacotados que precisam do mesmo parsing antes de o registro de canais ser inicializado +também podem expor um arquivo de nível superior `session-key-api.ts` com uma exportação +`resolveSessionConversation(...)` correspondente. O core usa essa superfície segura para bootstrap apenas quando o registro de Plugins em runtime ainda não está disponível. -`messaging.resolveParentConversationCandidates(...)` continua disponível como um -fallback legado de compatibilidade quando um Plugin só precisa de fallbacks de pai além -do ID genérico/bruto. Se ambos os hooks existirem, o core usa primeiro -`resolveSessionConversation(...).parentConversationCandidates` e só então +`messaging.resolveParentConversationCandidates(...)` continua disponível como +fallback legado de compatibilidade quando um Plugin só precisa de fallbacks de pai +sobre o id genérico/raw. Se ambos os hooks existirem, o core usa +`resolveSessionConversation(...).parentConversationCandidates` primeiro e só recorre a `resolveParentConversationCandidates(...)` quando o hook canônico -não os inclui. +os omite. ## Aprovações e capacidades do canal -A maioria dos Plugins de canal não precisa de código específico para aprovação. +A maioria dos Plugins de canal não precisa de código específico para aprovações. - O core é responsável por `/approve` no mesmo chat, payloads compartilhados de botão de aprovação e entrega genérica de fallback. -- Prefira um único objeto `approvalCapability` no Plugin de canal quando o canal precisar de comportamento específico de aprovação. -- `ChannelPlugin.approvals` foi removido. Coloque fatos de entrega/renderização/autenticação/aprovação nativa em `approvalCapability`. -- `plugin.auth` é apenas para login/logout; o core não lê mais hooks de autenticação de aprovação desse objeto. -- `approvalCapability.authorizeActorAction` e `approvalCapability.getActionAvailabilityState` são a interface canônica de autenticação de aprovação. -- Use `approvalCapability.getActionAvailabilityState` para disponibilidade de autenticação de aprovação no mesmo chat. -- Se o seu canal expõe aprovações nativas de execução, use `approvalCapability.getExecInitiatingSurfaceState` para o estado da superfície iniciadora/cliente nativo quando ele diferir da autenticação de aprovação no mesmo chat. O core usa esse hook específico de execução para distinguir `enabled` de `disabled`, decidir se o canal iniciador oferece suporte a aprovações nativas de execução e incluir o canal nas orientações de fallback de cliente nativo. `createApproverRestrictedNativeApprovalCapability(...)` preenche isso para o caso comum. -- Use `outbound.shouldSuppressLocalPayloadPrompt` ou `outbound.beforeDeliverPayload` para comportamento específico do canal no ciclo de vida do payload, como ocultar prompts locais de aprovação duplicados ou enviar indicadores de digitação antes da entrega. -- Use `approvalCapability.delivery` apenas para roteamento de aprovação nativa ou supressão de fallback. -- Use `approvalCapability.nativeRuntime` para fatos de aprovação nativa pertencentes ao canal. Mantenha isso lazy em entrypoints quentes do canal com `createLazyChannelApprovalNativeRuntimeAdapter(...)`, que pode importar seu módulo de runtime sob demanda enquanto ainda permite que o core monte o ciclo de vida de aprovação. +- Prefira um único objeto `approvalCapability` no Plugin de canal quando o canal precisar de comportamento específico para aprovações. +- `ChannelPlugin.approvals` foi removido. Coloque fatos de entrega/renderização/autorização nativa de aprovação em `approvalCapability`. +- `plugin.auth` é apenas para login/logout; o core não lê mais hooks de autorização de aprovação desse objeto. +- `approvalCapability.authorizeActorAction` e `approvalCapability.getActionAvailabilityState` são a superfície canônica para autorização de aprovação. +- Use `approvalCapability.getActionAvailabilityState` para disponibilidade de autorização de aprovação no mesmo chat. +- Se o seu canal expuser aprovações nativas de execução, use `approvalCapability.getExecInitiatingSurfaceState` para o estado da superfície iniciadora/cliente nativo quando ele diferir da autorização de aprovação no mesmo chat. O core usa esse hook específico de execução para distinguir `enabled` de `disabled`, decidir se o canal iniciador oferece suporte a aprovações nativas de execução e incluir o canal na orientação de fallback do cliente nativo. `createApproverRestrictedNativeApprovalCapability(...)` preenche isso para o caso comum. +- Use `outbound.shouldSuppressLocalPayloadPrompt` ou `outbound.beforeDeliverPayload` para comportamento específico do canal no ciclo de vida do payload, como ocultar prompts locais duplicados de aprovação ou enviar indicadores de digitação antes da entrega. +- Use `approvalCapability.delivery` apenas para roteamento nativo de aprovação ou supressão de fallback. +- Use `approvalCapability.nativeRuntime` para fatos de aprovação nativa controlados pelo canal. Mantenha-o lazy em pontos de entrada críticos do canal com `createLazyChannelApprovalNativeRuntimeAdapter(...)`, que pode importar seu módulo de runtime sob demanda e ainda permitir que o core monte o ciclo de vida da aprovação. - Use `approvalCapability.render` apenas quando um canal realmente precisar de payloads de aprovação personalizados em vez do renderizador compartilhado. -- Use `approvalCapability.describeExecApprovalSetup` quando o canal quiser que a resposta do caminho desabilitado explique exatamente quais controles de configuração são necessários para habilitar aprovações nativas de execução. O hook recebe `{ channel, channelLabel, accountId }`; canais com contas nomeadas devem renderizar caminhos com escopo por conta, como `channels..accounts..execApprovals.*`, em vez de padrões no nível superior. -- Se um canal puder inferir identidades estáveis de DM semelhantes a proprietário a partir da configuração existente, use `createResolvedApproverActionAuthAdapter` de `openclaw/plugin-sdk/approval-runtime` para restringir `/approve` no mesmo chat sem adicionar lógica específica de aprovação ao core. -- Se um canal precisar de entrega de aprovação nativa, mantenha o código do canal focado em normalização de destino e fatos de transporte/apresentação. Use `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver` e `createApproverRestrictedNativeApprovalCapability` de `openclaw/plugin-sdk/approval-runtime`. Coloque os fatos específicos do canal atrás de `approvalCapability.nativeRuntime`, idealmente por meio de `createChannelApprovalNativeRuntimeAdapter(...)` ou `createLazyChannelApprovalNativeRuntimeAdapter(...)`, para que o core possa montar o handler e controlar filtragem de requisições, roteamento, deduplicação, expiração, assinatura do Gateway e avisos de redirecionamento. `nativeRuntime` é dividido em algumas interfaces menores: -- `availability` — se a conta está configurada e se uma requisição deve ser tratada -- `presentation` — mapeia o modelo de visualização de aprovação compartilhado para payloads nativos pendentes/resolvidos/expirados ou ações finais -- `transport` — prepara destinos e envia/atualiza/remove mensagens nativas de aprovação -- `interactions` — hooks opcionais de bind/unbind/clear-action para botões ou reações nativas +- Use `approvalCapability.describeExecApprovalSetup` quando o canal quiser que a resposta do caminho desabilitado explique exatamente quais opções de configuração são necessárias para habilitar aprovações nativas de execução. O hook recebe `{ channel, channelLabel, accountId }`; canais com contas nomeadas devem renderizar caminhos com escopo de conta, como `channels..accounts..execApprovals.*`, em vez de padrões de nível superior. +- Se um canal puder inferir identidades estáveis semelhantes a proprietário em DM a partir da configuração existente, use `createResolvedApproverActionAuthAdapter` de `openclaw/plugin-sdk/approval-runtime` para restringir `/approve` no mesmo chat sem adicionar lógica específica de aprovação ao core. +- Se um canal precisar de entrega nativa de aprovação, mantenha o código do canal focado em normalização de alvo mais fatos de transporte/apresentação. Use `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver` e `createApproverRestrictedNativeApprovalCapability` de `openclaw/plugin-sdk/approval-runtime`. Coloque os fatos específicos do canal atrás de `approvalCapability.nativeRuntime`, idealmente por meio de `createChannelApprovalNativeRuntimeAdapter(...)` ou `createLazyChannelApprovalNativeRuntimeAdapter(...)`, para que o core possa montar o handler e controlar filtragem de solicitações, roteamento, eliminação de duplicatas, expiração, assinatura do Gateway e avisos de roteamento para outro local. `nativeRuntime` é dividido em algumas superfícies menores: +- `availability` — se a conta está configurada e se uma solicitação deve ser tratada +- `presentation` — mapeia o modelo de visualização compartilhado de aprovação em payloads nativos pendentes/resolvidos/expirados ou ações finais +- `transport` — prepara alvos e envia/atualiza/remove mensagens nativas de aprovação +- `interactions` — hooks opcionais de bind/unbind/clear-action para botões nativos ou reações - `observe` — hooks opcionais de diagnóstico de entrega -- Se o canal precisar de objetos pertencentes ao runtime, como cliente, token, app Bolt ou receptor de Webhook, registre-os por meio de `openclaw/plugin-sdk/channel-runtime-context`. O registro genérico de contexto de runtime permite que o core inicialize handlers orientados por capacidade a partir do estado de inicialização do canal sem adicionar cola específica de aprovação. -- Recorra a `createChannelApprovalHandler` ou `createChannelNativeApprovalRuntime` de nível mais baixo apenas quando a interface orientada por capacidade ainda não for expressiva o suficiente. -- Canais de aprovação nativa devem rotear tanto `accountId` quanto `approvalKind` por meio desses helpers. `accountId` mantém a política de aprovação multiconta limitada à conta de bot correta, e `approvalKind` mantém o comportamento de aprovação de execução vs Plugin disponível para o canal sem ramificações codificadas no core. -- O core agora também é responsável pelos avisos de redirecionamento de aprovação. Plugins de canal não devem enviar suas próprias mensagens de acompanhamento do tipo "a aprovação foi para DMs / outro canal" a partir de `createChannelNativeApprovalRuntime`; em vez disso, exponha roteamento preciso de origem + DM do aprovador por meio dos helpers compartilhados de capacidade de aprovação e deixe o core agregar as entregas reais antes de publicar qualquer aviso de volta no chat iniciador. -- Preserve o tipo do ID de aprovação entregue de ponta a ponta. Clientes nativos não devem - adivinhar nem reescrever o roteamento de aprovação de execução vs Plugin com base no estado local do canal. +- Se o canal precisar de objetos controlados pelo runtime, como um cliente, token, app Bolt ou receptor de Webhook, registre-os por meio de `openclaw/plugin-sdk/channel-runtime-context`. O registro genérico de contexto de runtime permite que o core inicialize handlers orientados por capacidade a partir do estado de inicialização do canal sem adicionar glue de wrapper específico para aprovação. +- Recorra a `createChannelApprovalHandler` ou `createChannelNativeApprovalRuntime` de nível mais baixo apenas quando a superfície orientada por capacidade ainda não for expressiva o suficiente. +- Canais com aprovação nativa devem rotear `accountId` e `approvalKind` por esses helpers. `accountId` mantém a política de aprovação multiconta restrita à conta de bot correta, e `approvalKind` mantém o comportamento de aprovação de execução vs Plugin disponível para o canal sem ramificações codificadas no core. +- O core agora também é responsável por avisos de redirecionamento de aprovação. Plugins de canal não devem enviar suas próprias mensagens de acompanhamento do tipo "a aprovação foi para DMs / outro canal" a partir de `createChannelNativeApprovalRuntime`; em vez disso, exponha roteamento preciso de origem + DM do aprovador por meio dos helpers compartilhados de capacidade de aprovação e deixe o core agregar as entregas reais antes de publicar qualquer aviso de volta no chat iniciador. +- Preserve a categoria do id de aprovação entregue de ponta a ponta. Clientes nativos não devem + inferir nem reescrever o roteamento de aprovação de execução vs Plugin com base no estado local do canal. - Diferentes tipos de aprovação podem expor intencionalmente diferentes superfícies nativas. - Exemplos empacotados atuais: - - O Slack mantém o roteamento nativo de aprovação disponível tanto para IDs de execução quanto de Plugin. - - O Matrix mantém o mesmo roteamento nativo de DM/canal e a mesma UX de reação para aprovações de execução - e de Plugin, ao mesmo tempo que ainda permite que a autenticação varie por tipo de aprovação. -- `createApproverRestrictedNativeApprovalAdapter` ainda existe como wrapper de compatibilidade, mas novos códigos devem preferir o builder de capacidade e expor `approvalCapability` no Plugin. + Exemplos atuais empacotados: + - O Slack mantém o roteamento nativo de aprovação disponível tanto para ids de execução quanto de Plugin. + - O Matrix mantém o mesmo roteamento nativo por DM/canal e a mesma UX de reação para aprovações de execução + e de Plugin, ao mesmo tempo em que ainda permite que a autorização difira por tipo de aprovação. +- `createApproverRestrictedNativeApprovalAdapter` ainda existe como wrapper de compatibilidade, mas código novo deve preferir o builder de capacidade e expor `approvalCapability` no Plugin. -Para entrypoints quentes do canal, prefira os subcaminhos de runtime mais específicos quando você -precisar de apenas uma parte dessa família: +Para pontos de entrada críticos do canal, prefira os subcaminhos de runtime mais específicos quando você só +precisar de uma parte dessa família: - `openclaw/plugin-sdk/approval-auth-runtime` - `openclaw/plugin-sdk/approval-client-runtime` @@ -136,29 +136,31 @@ Especificamente para setup: `createSetupInputPresenceValidator`), saída de nota de consulta, `promptResolvedAllowFrom`, `splitSetupEntries` e os builders delegados de proxy de setup -- `openclaw/plugin-sdk/setup-adapter-runtime` é a interface estreita sensível a ambiente +- `openclaw/plugin-sdk/setup-adapter-runtime` é a superfície estreita de adaptador com reconhecimento de env para `createEnvPatchedAccountSetupAdapter` -- `openclaw/plugin-sdk/channel-setup` cobre os builders de setup de instalação opcional - além de alguns primitivos seguros para setup: +- `openclaw/plugin-sdk/channel-setup` cobre os builders de setup com instalação opcional + além de algumas primitivas seguras para setup: `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, -Se o seu canal oferece suporte a setup ou autenticação orientados por variáveis de ambiente e fluxos genéricos de inicialização/configuração -devem conhecer esses nomes de variáveis antes do carregamento em runtime, declare-os no -manifesto do Plugin com `channelEnvVars`. Mantenha `envVars` do runtime do canal ou constantes locais apenas para cópia voltada ao operador. +Se o seu canal oferecer suporte a setup ou auth orientados por env e os fluxos genéricos de inicialização/configuração +precisarem conhecer esses nomes de env antes de o runtime ser carregado, declare-os no +manifesto do Plugin com `channelEnvVars`. Mantenha `envVars` do runtime do canal ou constantes locais apenas +para cópia voltada ao operador. `createOptionalChannelSetupWizard`, `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled` e `splitSetupEntries` -- use a interface mais ampla `openclaw/plugin-sdk/setup` apenas quando também precisar dos +- use a superfície mais ampla `openclaw/plugin-sdk/setup` apenas quando você também precisar dos helpers compartilhados mais pesados de setup/configuração, como `moveSingleAccountChannelSectionToDefaultAccount(...)` Se o seu canal só quiser anunciar "instale este Plugin primeiro" em superfícies de setup, prefira `createOptionalChannelSetupSurface(...)`. O -adaptador/assistente gerado falha de forma fechada em gravações de configuração e finalização, e reutiliza -a mesma mensagem de instalação obrigatória em validação, finalização e texto de link da documentação. +adaptador/assistente gerado falha em modo fechado em gravações de configuração e finalização, e reutiliza +a mesma mensagem de instalação obrigatória em validação, finalização e cópia +de link da documentação. -Para outros caminhos quentes do canal, prefira os helpers estreitos em vez de superfícies +Para outros caminhos críticos do canal, prefira os helpers específicos em vez de superfícies legadas mais amplas: - `openclaw/plugin-sdk/account-core`, @@ -167,38 +169,38 @@ legadas mais amplas: `openclaw/plugin-sdk/account-helpers` para configuração multiconta e fallback de conta padrão - `openclaw/plugin-sdk/inbound-envelope` e - `openclaw/plugin-sdk/inbound-reply-dispatch` para encadeamento de rota/envelope de entrada e - record-and-dispatch -- `openclaw/plugin-sdk/messaging-targets` para análise e correspondência de destino + `openclaw/plugin-sdk/inbound-reply-dispatch` para rota/envelope de entrada e + integração de registro e despacho +- `openclaw/plugin-sdk/messaging-targets` para parsing/correspondência de alvos - `openclaw/plugin-sdk/outbound-media` e - `openclaw/plugin-sdk/outbound-runtime` para carregamento de mídia e delegates de - identidade/envio de saída -- `openclaw/plugin-sdk/thread-bindings-runtime` para ciclo de vida de vínculo de thread - e registro de adaptador -- `openclaw/plugin-sdk/agent-media-payload` apenas quando um layout legado de campo - de payload de agente/mídia ainda for necessário -- `openclaw/plugin-sdk/telegram-command-config` para normalização de comandos personalizados do Telegram, validação de duplicidade/conflito e um contrato de configuração de comando estável para fallback + `openclaw/plugin-sdk/outbound-runtime` para carregamento de mídia mais delegados + de identidade/envio de saída +- `openclaw/plugin-sdk/thread-bindings-runtime` para ciclo de vida de vinculação de thread + e registro de adaptadores +- `openclaw/plugin-sdk/agent-media-payload` apenas quando um layout de campo legado de payload de agente/mídia + ainda for necessário +- `openclaw/plugin-sdk/telegram-command-config` para normalização de comandos personalizados do Telegram, validação de duplicatas/conflitos e um contrato de configuração de comando estável em fallback -Canais somente com autenticação geralmente podem parar no caminho padrão: o core lida com aprovações e o Plugin apenas expõe capacidades de saída/autenticação. Canais de aprovação nativa, como Matrix, Slack, Telegram e transportes de chat personalizados, devem usar os helpers nativos compartilhados em vez de implementar seu próprio ciclo de vida de aprovação. +Canais somente com auth normalmente podem ficar no caminho padrão: o core trata as aprovações e o Plugin apenas expõe capacidades de saída/auth. Canais com aprovação nativa, como Matrix, Slack, Telegram e transportes de chat personalizados, devem usar os helpers nativos compartilhados em vez de implementar seu próprio ciclo de vida de aprovação. ## Política de menção de entrada Mantenha o tratamento de menções de entrada dividido em duas camadas: -- coleta de evidências pertencente ao Plugin +- coleta de evidências controlada pelo Plugin - avaliação de política compartilhada Use `openclaw/plugin-sdk/channel-inbound` para a camada compartilhada. -Bom ajuste para lógica local do Plugin: +Bom encaixe para lógica local do Plugin: - detecção de resposta ao bot - detecção de citação do bot -- verificações de participação na thread +- verificações de participação em thread - exclusões de mensagens de serviço/sistema - caches nativos da plataforma necessários para comprovar a participação do bot -Bom ajuste para o helper compartilhado: +Bom encaixe para o helper compartilhado: - `requireMention` - resultado explícito de menção @@ -259,8 +261,8 @@ Plugins de canal empacotados que já dependem de injeção em runtime: - `resolveInboundMentionDecision` Os helpers mais antigos `resolveMentionGating*` permanecem em -`openclaw/plugin-sdk/channel-inbound` apenas como exportações de compatibilidade. Novos códigos -devem usar `resolveInboundMentionDecision({ facts, policy })`. +`openclaw/plugin-sdk/channel-inbound` apenas como exports de compatibilidade. Código novo +deve usar `resolveInboundMentionDecision({ facts, policy })`. ## Passo a passo @@ -269,7 +271,7 @@ devem usar `resolveInboundMentionDecision({ facts, policy })`. Crie os arquivos padrão do Plugin. O campo `channel` em `package.json` é o que torna este um Plugin de canal. Para a superfície completa de metadados do pacote, - consulte [Configuração e Setup de Plugin](/pt-BR/plugins/sdk-setup#openclaw-channel): + veja [Setup e Configuração do Plugin](/pt-BR/plugins/sdk-setup#openclaw-channel): ```json package.json @@ -283,7 +285,7 @@ devem usar `resolveInboundMentionDecision({ facts, policy })`. "channel": { "id": "acme-chat", "label": "Acme Chat", - "blurb": "Connect OpenClaw to Acme Chat." + "blurb": "Conecte o OpenClaw ao Acme Chat." } } } @@ -295,7 +297,7 @@ devem usar `resolveInboundMentionDecision({ facts, policy })`. "kind": "channel", "channels": ["acme-chat"], "name": "Acme Chat", - "description": "Acme Chat channel plugin", + "description": "Plugin de canal do Acme Chat", "configSchema": { "type": "object", "additionalProperties": false, @@ -319,7 +321,7 @@ devem usar `resolveInboundMentionDecision({ facts, policy })`. - A interface `ChannelPlugin` tem muitas superfícies opcionais de adaptador. Comece com + A interface `ChannelPlugin` tem muitas superfícies de adaptador opcionais. Comece com o mínimo — `id` e `setup` — e adicione adaptadores conforme necessário. Crie `src/channel.ts`: @@ -416,17 +418,17 @@ devem usar `resolveInboundMentionDecision({ facts, policy })`. ``` - Em vez de implementar interfaces de adaptador de baixo nível manualmente, você passa + Em vez de implementar manualmente interfaces de adaptador de baixo nível, você passa opções declarativas e o builder as compõe: | Opção | O que ela conecta | | --- | --- | - | `security.dm` | Resolver de segurança de DM com escopo a partir de campos de configuração | - | `pairing.text` | Fluxo de pareamento de DM baseado em texto com troca de código | - | `threading` | Resolver de modo reply-to (fixo, com escopo por conta ou personalizado) | - | `outbound.attachedResults` | Funções de envio que retornam metadados de resultado (IDs de mensagem) | + | `security.dm` | Resolvedor de segurança de DM com escopo a partir dos campos de configuração | + | `pairing.text` | Fluxo de emparelhamento por DM baseado em texto com troca de código | + | `threading` | Resolvedor de modo reply-to (fixo, com escopo de conta ou personalizado) | + | `outbound.attachedResults` | Funções de envio que retornam metadados do resultado (ids de mensagem) | - Você também pode passar objetos brutos de adaptador em vez de opções declarativas + Você também pode passar objetos de adaptador brutos em vez das opções declarativas se precisar de controle total. @@ -468,15 +470,15 @@ devem usar `resolveInboundMentionDecision({ facts, policy })`. }); ``` - Coloque descritores de CLI pertencentes ao canal em `registerCliMetadata(...)` para que o OpenClaw + Coloque descritores de CLI controlados pelo canal em `registerCliMetadata(...)` para que o OpenClaw possa mostrá-los na ajuda raiz sem ativar o runtime completo do canal, enquanto carregamentos completos normais ainda capturam os mesmos descritores para o registro - real dos comandos. Mantenha `registerFull(...)` para trabalho exclusivo de runtime. + real de comandos. Mantenha `registerFull(...)` para trabalho somente de runtime. Se `registerFull(...)` registrar métodos RPC do Gateway, use um prefixo específico do Plugin. Namespaces administrativos do core (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) permanecem reservados e sempre resolvem para `operator.admin`. - `defineChannelPluginEntry` lida automaticamente com a divisão de modo de registro. Consulte + `defineChannelPluginEntry` trata automaticamente a divisão de modo de registro. Veja [Pontos de entrada](/pt-BR/plugins/sdk-entrypoints#definechannelpluginentry) para todas as opções. @@ -494,13 +496,18 @@ devem usar `resolveInboundMentionDecision({ facts, policy })`. O OpenClaw carrega isso em vez da entrada completa quando o canal está desabilitado ou não configurado. Isso evita puxar código pesado de runtime durante fluxos de setup. - Consulte [Setup e Configuração](/pt-BR/plugins/sdk-setup#setup-entry) para detalhes. + Veja [Setup e Configuração](/pt-BR/plugins/sdk-setup#setup-entry) para detalhes. + + Canais empacotados do workspace que dividem exports seguras para setup em módulos + auxiliares podem usar `defineBundledChannelSetupEntry(...)` de + `openclaw/plugin-sdk/channel-entry-contract` quando também precisarem de um + setter explícito de runtime em tempo de setup. - Seu Plugin precisa receber mensagens da plataforma e encaminhá-las ao - OpenClaw. O padrão típico é um Webhook que verifica a requisição e + Seu Plugin precisa receber mensagens da plataforma e encaminhá-las para o + OpenClaw. O padrão típico é um Webhook que verifica a solicitação e a despacha por meio do handler de entrada do seu canal: ```typescript @@ -534,7 +541,7 @@ devem usar `resolveInboundMentionDecision({ facts, policy })`. -Escreva testes colocados ao lado do código em `src/channel.test.ts`: +Escreva testes colocados lado a lado em `src/channel.test.ts`: ```typescript src/channel.test.ts import { describe, it, expect } from "vitest"; @@ -572,7 +579,7 @@ Escreva testes colocados ao lado do código em `src/channel.test.ts`: pnpm test -- /acme-chat/ ``` - Para helpers de teste compartilhados, consulte [Testes](/pt-BR/plugins/sdk-testing). + Para helpers de teste compartilhados, veja [Testes](/pt-BR/plugins/sdk-testing). @@ -581,12 +588,12 @@ Escreva testes colocados ao lado do código em `src/channel.test.ts`: ``` /acme-chat/ -├── package.json # metadados de openclaw.channel +├── package.json # metadados openclaw.channel ├── openclaw.plugin.json # Manifesto com schema de configuração ├── index.ts # defineChannelPluginEntry ├── setup-entry.ts # defineSetupPluginEntry -├── api.ts # Exportações públicas (opcional) -├── runtime-api.ts # Exportações internas de runtime (opcional) +├── api.ts # Exports públicos (opcional) +├── runtime-api.ts # Exports internos de runtime (opcional) └── src/ ├── channel.ts # ChannelPlugin via createChatChannelPlugin ├── channel.test.ts # Testes @@ -598,12 +605,12 @@ Escreva testes colocados ao lado do código em `src/channel.test.ts`: - Modos de resposta fixos, com escopo por conta ou personalizados + Modos de resposta fixos, com escopo de conta ou personalizados describeMessageTool e descoberta de ações - + inferTargetChatType, looksLikeId, resolveTarget @@ -612,15 +619,15 @@ Escreva testes colocados ao lado do código em `src/channel.test.ts`: -Algumas interfaces auxiliares empacotadas ainda existem para manutenção e -compatibilidade de Plugins empacotados. Elas não são o padrão recomendado para novos Plugins de canal; -prefira os subcaminhos genéricos de canal/setup/resposta/runtime da superfície -comum do SDK, a menos que você esteja mantendo diretamente essa família de Plugins empacotados. +Algumas superfícies auxiliares de Plugins empacotados ainda existem para manutenção de Plugins empacotados e +compatibilidade. Elas não são o padrão recomendado para novos Plugins de canal; +prefira os subcaminhos genéricos de canal/setup/resposta/runtime da superfície comum do SDK, +a menos que você esteja mantendo diretamente essa família de Plugins empacotados. ## Próximos passos - [Plugins de provedor](/pt-BR/plugins/sdk-provider-plugins) — se o seu Plugin também fornece modelos -- [Visão geral do SDK](/pt-BR/plugins/sdk-overview) — referência completa de importação de subcaminhos +- [Visão geral do SDK](/pt-BR/plugins/sdk-overview) — referência completa de imports por subcaminho - [Testes do SDK](/pt-BR/plugins/sdk-testing) — utilitários de teste e testes de contrato -- [Manifesto de Plugin](/pt-BR/plugins/manifest) — schema completo do manifesto +- [Manifesto do Plugin](/pt-BR/plugins/manifest) — schema completo do manifesto diff --git a/docs/pt-BR/plugins/sdk-entrypoints.md b/docs/pt-BR/plugins/sdk-entrypoints.md index 2514bb69e..11dfbfa64 100644 --- a/docs/pt-BR/plugins/sdk-entrypoints.md +++ b/docs/pt-BR/plugins/sdk-entrypoints.md @@ -1,36 +1,36 @@ --- read_when: - - Você precisa da assinatura de tipo exata de definePluginEntry ou defineChannelPluginEntry - - Você quer entender o modo de registro (completo vs setup vs metadados de CLI) - - Você está consultando as opções de ponto de entrada + - Você precisa da assinatura de tipo exata de `definePluginEntry` ou `defineChannelPluginEntry` + - Você quer entender o modo de registro (completo vs configuração vs metadados da CLI) + - Você está procurando opções de ponto de entrada sidebarTitle: Entry Points -summary: Referência para definePluginEntry, defineChannelPluginEntry e defineSetupPluginEntry -title: Pontos de entrada de plugin +summary: Referência para `definePluginEntry`, `defineChannelPluginEntry` e `defineSetupPluginEntry` +title: Pontos de entrada do Plugin x-i18n: - generated_at: "2026-04-05T12:49:09Z" + generated_at: "2026-04-15T19:41:37Z" model: gpt-5.4 provider: openai - source_hash: 799dbfe71e681dd8ba929a7a631dfe745c3c5c69530126fea2f9c137b120f51f + source_hash: aabca25bc9b8ff1b5bb4852bafe83640ffeba006ea6b6a8eff4e2c37a10f1fe4 source_path: plugins/sdk-entrypoints.md workflow: 15 --- -# Pontos de entrada de plugin +# Pontos de entrada do Plugin -Todo plugin exporta um objeto de entrada padrão. O SDK fornece três helpers para +Todo Plugin exporta um objeto de entrada padrão. O SDK fornece três helpers para criá-los. - **Procurando um passo a passo?** Consulte [Plugins de canal](/plugins/sdk-channel-plugins) - ou [Plugins de provedor](/plugins/sdk-provider-plugins) para guias passo a passo. + **Procurando um passo a passo?** Veja [Plugins de canal](/pt-BR/plugins/sdk-channel-plugins) + ou [Plugins de provedor](/pt-BR/plugins/sdk-provider-plugins) para guias passo a passo. ## `definePluginEntry` **Importação:** `openclaw/plugin-sdk/plugin-entry` -Para plugins de provedor, plugins de ferramenta, plugins de hook e tudo o que **não** -for um canal de mensagens. +Para plugins de provedor, plugins de ferramenta, plugins de hook e qualquer coisa que **não** +seja um canal de mensagens. ```typescript import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; @@ -56,22 +56,22 @@ export default definePluginEntry({ | `name` | `string` | Sim | — | | `description` | `string` | Sim | — | | `kind` | `string` | Não | — | -| `configSchema` | `OpenClawPluginConfigSchema \| () => OpenClawPluginConfigSchema` | Não | Schema de objeto vazio | +| `configSchema` | `OpenClawPluginConfigSchema \| () => OpenClawPluginConfigSchema` | Não | Esquema de objeto vazio | | `register` | `(api: OpenClawPluginApi) => void` | Sim | — | - `id` deve corresponder ao seu manifesto `openclaw.plugin.json`. - `kind` é para slots exclusivos: `"memory"` ou `"context-engine"`. - `configSchema` pode ser uma função para avaliação preguiçosa. -- O OpenClaw resolve e memoiza esse schema no primeiro acesso, portanto builders de schema - caros são executados apenas uma vez. +- O OpenClaw resolve e memoriza esse esquema no primeiro acesso, então builders de esquema + custosos são executados apenas uma vez. ## `defineChannelPluginEntry` **Importação:** `openclaw/plugin-sdk/channel-core` -Encapsula `definePluginEntry` com a infraestrutura específica de canal. Chama automaticamente -`api.registerChannel({ plugin })`, expõe uma seam opcional de metadados de CLI para ajuda na raiz -e controla `registerFull` de acordo com o modo de registro. +Encapsula `definePluginEntry` com a integração específica de canal. Chama +automaticamente `api.registerChannel({ plugin })`, expõe uma costura opcional de metadados +da CLI de ajuda raiz e controla `registerFull` com base no modo de registro. ```typescript import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; @@ -97,29 +97,29 @@ export default defineChannelPluginEntry({ | `name` | `string` | Sim | — | | `description` | `string` | Sim | — | | `plugin` | `ChannelPlugin` | Sim | — | -| `configSchema` | `OpenClawPluginConfigSchema \| () => OpenClawPluginConfigSchema` | Não | Schema de objeto vazio | +| `configSchema` | `OpenClawPluginConfigSchema \| () => OpenClawPluginConfigSchema` | Não | Esquema de objeto vazio | | `setRuntime` | `(runtime: PluginRuntime) => void` | Não | — | | `registerCliMetadata` | `(api: OpenClawPluginApi) => void` | Não | — | | `registerFull` | `(api: OpenClawPluginApi) => void` | Não | — | - `setRuntime` é chamado durante o registro para que você possa armazenar a referência de runtime - (normalmente por meio de `createPluginRuntimeStore`). Ele é ignorado durante a captura - de metadados de CLI. + (normalmente via `createPluginRuntimeStore`). Ele é ignorado durante a captura + de metadados da CLI. - `registerCliMetadata` é executado tanto durante `api.registrationMode === "cli-metadata"` quanto durante `api.registrationMode === "full"`. - Use-o como o local canônico para descritores de CLI pertencentes ao canal, para que a ajuda - na raiz permaneça sem ativação, enquanto o registro normal de comandos da CLI continua compatível - com carregamentos completos de plugin. -- `registerFull` é executado apenas quando `api.registrationMode === "full"`. Ele é ignorado - durante o carregamento somente de setup. -- Assim como `definePluginEntry`, `configSchema` pode ser uma factory preguiçosa e o OpenClaw - memoiza o schema resolvido no primeiro acesso. -- Para comandos de CLI na raiz pertencentes ao plugin, prefira `api.registerCli(..., { descriptors: [...] })` - quando quiser que o comando permaneça com lazy-loading sem desaparecer da árvore de parsing - da CLI na raiz. Para plugins de canal, prefira registrar esses descritores - em `registerCliMetadata(...)` e manter `registerFull(...)` focado em trabalho somente de runtime. -- Se `registerFull(...)` também registrar métodos RPC de gateway, mantenha-os em um - prefixo específico do plugin. Namespaces administrativos principais reservados (`config.*`, + Use-o como o lugar canônico para descritores de CLI pertencentes ao canal, para que a ajuda + raiz não ative o carregamento enquanto o registro normal de comandos da CLI continua compatível + com carregamentos completos do Plugin. +- `registerFull` só é executado quando `api.registrationMode === "full"`. Ele é ignorado + durante o carregamento somente de configuração. +- Assim como `definePluginEntry`, `configSchema` pode ser uma fábrica preguiçosa e o OpenClaw + memoriza o esquema resolvido no primeiro acesso. +- Para comandos raiz da CLI pertencentes ao Plugin, prefira `api.registerCli(..., { descriptors: [...] })` + quando você quiser que o comando permaneça com carregamento preguiçoso sem desaparecer da + árvore de parsing da CLI raiz. Para plugins de canal, prefira registrar esses descritores + em `registerCliMetadata(...)` e mantenha `registerFull(...)` focado em trabalho somente de runtime. +- Se `registerFull(...)` também registrar métodos RPC do Gateway, mantenha-os em um + prefixo específico do Plugin. Namespaces administrativos centrais reservados (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) são sempre forçados para `operator.admin`. @@ -128,7 +128,7 @@ export default defineChannelPluginEntry({ **Importação:** `openclaw/plugin-sdk/channel-core` Para o arquivo leve `setup-entry.ts`. Retorna apenas `{ plugin }`, sem -infraestrutura de runtime ou de CLI. +integração de runtime nem de CLI. ```typescript import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core"; @@ -136,33 +136,58 @@ import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core"; export default defineSetupPluginEntry(myChannelPlugin); ``` -O OpenClaw carrega isso em vez da entrada completa quando um canal está desativado, -não configurado ou quando o carregamento adiado está ativado. Consulte -[Setup e config](/plugins/sdk-setup#setup-entry) para saber quando isso importa. +O OpenClaw carrega isso em vez da entrada completa quando um canal está desabilitado, +não configurado ou quando o carregamento adiado está ativado. Veja +[Configuração e setup](/pt-BR/plugins/sdk-setup#setup-entry) para saber quando isso importa. -Na prática, combine `defineSetupPluginEntry(...)` com as famílias restritas de helpers de setup: +Na prática, combine `defineSetupPluginEntry(...)` com as famílias estreitas de helpers de setup: - `openclaw/plugin-sdk/setup-runtime` para helpers de setup seguros para runtime, como adaptadores de patch de setup seguros para importação, saída de nota de consulta, `promptResolvedAllowFrom`, `splitSetupEntries` e proxies de setup delegados - `openclaw/plugin-sdk/channel-setup` para superfícies de setup de instalação opcional -- `openclaw/plugin-sdk/setup-tools` para helpers de CLI/arquivo/docs de setup/instalação +- `openclaw/plugin-sdk/setup-tools` para helpers de setup/instalação de CLI/arquivo/docs Mantenha SDKs pesados, registro de CLI e serviços de runtime de longa duração na entrada completa. +Canais empacotados do workspace que dividem superfícies de setup e runtime podem usar +`defineBundledChannelSetupEntry(...)` de +`openclaw/plugin-sdk/channel-entry-contract` em vez disso. Esse contrato permite que a +entrada de setup mantenha exportações de plugin/secrets seguras para setup enquanto ainda expõe +um setter de runtime: + +```typescript +import { defineBundledChannelSetupEntry } from "openclaw/plugin-sdk/channel-entry-contract"; + +export default defineBundledChannelSetupEntry({ + importMetaUrl: import.meta.url, + plugin: { + specifier: "./channel-plugin-api.js", + exportName: "myChannelPlugin", + }, + runtime: { + specifier: "./runtime-api.js", + exportName: "setMyChannelRuntime", + }, +}); +``` + +Use esse contrato empacotado apenas quando os fluxos de setup realmente precisarem de um setter +de runtime leve antes que a entrada completa do canal seja carregada. + ## Modo de registro -`api.registrationMode` informa ao seu plugin como ele foi carregado: +`api.registrationMode` informa ao seu Plugin como ele foi carregado: -| Modo | Quando | O que registrar | -| ----------------- | -------------------------------- | ---------------------------------------------------------------------------------------- | -| `"full"` | Inicialização normal do gateway | Tudo | -| `"setup-only"` | Canal desativado/não configurado | Apenas registro de canal | -| `"setup-runtime"` | Fluxo de setup com runtime disponível | Registro de canal mais apenas o runtime leve necessário antes de a entrada completa carregar | -| `"cli-metadata"` | Ajuda na raiz / captura de metadados de CLI | Apenas descritores de CLI | +| Modo | Quando | O que registrar | +| ----------------- | --------------------------------- | --------------------------------------------------------------------------------------- | +| `"full"` | Inicialização normal do Gateway | Tudo | +| `"setup-only"` | Canal desabilitado/não configurado | Apenas registro de canal | +| `"setup-runtime"` | Fluxo de setup com runtime disponível | Registro de canal mais apenas o runtime leve necessário antes do carregamento da entrada completa | +| `"cli-metadata"` | Ajuda raiz / captura de metadados da CLI | Apenas descritores de CLI | -`defineChannelPluginEntry` lida automaticamente com essa divisão. Se você usar +`defineChannelPluginEntry` lida com essa divisão automaticamente. Se você usar `definePluginEntry` diretamente para um canal, verifique o modo por conta própria: ```typescript @@ -181,36 +206,36 @@ register(api) { ``` Trate `"setup-runtime"` como a janela em que superfícies de inicialização somente de setup devem -existir sem reentrar no runtime completo do canal empacotado. Bons encaixes são -registro de canal, rotas HTTP seguras para setup, métodos de gateway seguros para setup e +existir sem reentrar no runtime completo do canal empacotado. Bons usos incluem +registro de canal, rotas HTTP seguras para setup, métodos do Gateway seguros para setup e helpers de setup delegados. Serviços pesados em segundo plano, registradores de CLI e -bootstraps de SDK de provedor/cliente ainda pertencem a `"full"`. +bootstraps de SDKs de provedor/cliente ainda pertencem a `"full"`. Especificamente para registradores de CLI: -- use `descriptors` quando o registrador possuir um ou mais comandos na raiz e você - quiser que o OpenClaw faça lazy-load do módulo real da CLI na primeira invocação -- garanta que esses descritores cubram todos os comandos de nível superior expostos pelo +- use `descriptors` quando o registrador possuir um ou mais comandos raiz e você + quiser que o OpenClaw carregue o módulo real da CLI de forma preguiçosa na primeira invocação +- certifique-se de que esses descritores cubram todos os comandos raiz de nível superior expostos pelo registrador -- use apenas `commands` para caminhos de compatibilidade eager +- use apenas `commands` somente para caminhos de compatibilidade ansiosos -## Formatos de plugin +## Formatos de Plugin -O OpenClaw classifica plugins carregados de acordo com seu comportamento de registro: +O OpenClaw classifica Plugins carregados pelo comportamento de registro deles: -| Formato | Descrição | -| --------------------- | ------------------------------------------------- | -| **plain-capability** | Um tipo de capacidade (por exemplo, apenas provedor) | +| Formato | Descrição | +| -------------------- | ------------------------------------------------- | +| **plain-capability** | Um tipo de capacidade (por exemplo, somente provedor) | | **hybrid-capability** | Vários tipos de capacidade (por exemplo, provedor + fala) | -| **hook-only** | Apenas hooks, sem capacidades | +| **hook-only** | Apenas hooks, sem capacidades | | **non-capability** | Ferramentas/comandos/serviços, mas sem capacidades | -Use `openclaw plugins inspect ` para ver o formato de um plugin. +Use `openclaw plugins inspect ` para ver o formato de um Plugin. ## Relacionado -- [Visão geral do SDK](/plugins/sdk-overview) — API de registro e referência de subcaminhos -- [Helpers de runtime](/plugins/sdk-runtime) — `api.runtime` e `createPluginRuntimeStore` -- [Setup e config](/plugins/sdk-setup) — manifesto, entrada de setup, carregamento adiado -- [Plugins de canal](/plugins/sdk-channel-plugins) — como criar o objeto `ChannelPlugin` -- [Plugins de provedor](/plugins/sdk-provider-plugins) — registro de provedor e hooks +- [Visão geral do SDK](/pt-BR/plugins/sdk-overview) — API de registro e referência de subpaths +- [Helpers de runtime](/pt-BR/plugins/sdk-runtime) — `api.runtime` e `createPluginRuntimeStore` +- [Setup e configuração](/pt-BR/plugins/sdk-setup) — manifesto, entrada de setup, carregamento adiado +- [Plugins de canal](/pt-BR/plugins/sdk-channel-plugins) — criando o objeto `ChannelPlugin` +- [Plugins de provedor](/pt-BR/plugins/sdk-provider-plugins) — registro de provedor e hooks diff --git a/docs/pt-BR/plugins/sdk-runtime.md b/docs/pt-BR/plugins/sdk-runtime.md index ab677ea5e..96804d081 100644 --- a/docs/pt-BR/plugins/sdk-runtime.md +++ b/docs/pt-BR/plugins/sdk-runtime.md @@ -1,28 +1,28 @@ --- read_when: - - Você precisa chamar auxiliares do núcleo a partir de um plugin (TTS, STT, geração de imagem, busca na web, subagent) + - Você precisa chamar auxiliares do núcleo a partir de um plugin (TTS, STT, geração de imagem, busca na web, subagente) - Você quer entender o que `api.runtime` expõe - - Você está acessando auxiliares de configuração, agente ou mídia a partir do código do plugin + - Você está acessando auxiliares de config, agente ou mídia a partir do código do plugin sidebarTitle: Runtime Helpers -summary: api.runtime -- os auxiliares de runtime injetados disponíveis para plugins -title: Auxiliares de runtime de plugin +summary: api.runtime -- os auxiliares de tempo de execução injetados disponíveis para plugins +title: Auxiliares de tempo de execução do Plugin x-i18n: - generated_at: "2026-04-11T02:46:37Z" + generated_at: "2026-04-15T19:41:36Z" model: gpt-5.4 provider: openai - source_hash: fbf8a6ecd970300f784b8aca20eed40ba12c83107abd27385bfdc3347d2544be + source_hash: c77a6e9cd48c84affa17dce684bbd0e072c8b63485e4a5d569f3793a4ea4f9c8 source_path: plugins/sdk-runtime.md workflow: 15 --- -# Auxiliares de runtime de plugin +# Auxiliares de tempo de execução do Plugin Referência para o objeto `api.runtime` injetado em todo plugin durante o -registro. Use estes auxiliares em vez de importar diretamente internos do host. +registro. Use esses auxiliares em vez de importar diretamente internos do host. - **Está procurando um guia passo a passo?** Consulte [Channel Plugins](/pt-BR/plugins/sdk-channel-plugins) - ou [Provider Plugins](/pt-BR/plugins/sdk-provider-plugins) para guias passo a passo + **Está procurando um passo a passo?** Consulte [Plugins de canal](/pt-BR/plugins/sdk-channel-plugins) + ou [Plugins de provedor](/pt-BR/plugins/sdk-provider-plugins) para guias passo a passo que mostram esses auxiliares em contexto. @@ -32,50 +32,51 @@ register(api) { } ``` -## Namespaces de runtime +## Namespaces de tempo de execução ### `api.runtime.agent` Identidade do agente, diretórios e gerenciamento de sessão. ```typescript -// Resolver o diretório de trabalho do agente +// Resolve the agent's working directory const agentDir = api.runtime.agent.resolveAgentDir(cfg); -// Resolver o workspace do agente +// Resolve agent workspace const workspaceDir = api.runtime.agent.resolveAgentWorkspaceDir(cfg); -// Obter a identidade do agente +// Get agent identity const identity = api.runtime.agent.resolveAgentIdentity(cfg); -// Obter o nível de thinking padrão +// Get default thinking level const thinking = api.runtime.agent.resolveThinkingDefault(cfg, provider, model); -// Obter o tempo limite do agente +// Get agent timeout const timeoutMs = api.runtime.agent.resolveAgentTimeoutMs(cfg); -// Garantir que o workspace exista +// Ensure workspace exists await api.runtime.agent.ensureAgentWorkspace(cfg); -// Executar um turno de agente embutido +// Run an embedded agent turn const agentDir = api.runtime.agent.resolveAgentDir(cfg); const result = await api.runtime.agent.runEmbeddedAgent({ sessionId: "my-plugin:task-1", runId: crypto.randomUUID(), sessionFile: path.join(agentDir, "sessions", "my-plugin-task-1.jsonl"), workspaceDir: api.runtime.agent.resolveAgentWorkspaceDir(cfg), - prompt: "Resuma as alterações mais recentes", + prompt: "Summarize the latest changes", timeoutMs: api.runtime.agent.resolveAgentTimeoutMs(cfg), }); ``` `runEmbeddedAgent(...)` é o auxiliar neutro para iniciar um turno normal de -agente OpenClaw a partir do código do plugin. Ele usa a mesma resolução de -provedor/modelo e a mesma seleção de harness de agente que respostas acionadas por canal. +agente do OpenClaw a partir do código do plugin. Ele usa a mesma resolução de +provedor/modelo e a mesma seleção de harness de agente que as respostas +acionadas por canais. -`runEmbeddedPiAgent(...)` continua disponível como alias de compatibilidade. +`runEmbeddedPiAgent(...)` permanece como um alias de compatibilidade. -**Os auxiliares do armazenamento de sessão** ficam em `api.runtime.agent.session`: +**Os auxiliares de armazenamento de sessão** ficam em `api.runtime.agent.session`: ```typescript const storePath = api.runtime.agent.session.resolveStorePath(cfg); @@ -89,63 +90,65 @@ const filePath = api.runtime.agent.session.resolveSessionFilePath(cfg, sessionId Constantes padrão de modelo e provedor: ```typescript -const model = api.runtime.agent.defaults.model; // por exemplo "anthropic/claude-sonnet-4-6" -const provider = api.runtime.agent.defaults.provider; // por exemplo "anthropic" +const model = api.runtime.agent.defaults.model; // e.g. "anthropic/claude-sonnet-4-6" +const provider = api.runtime.agent.defaults.provider; // e.g. "anthropic" ``` ### `api.runtime.subagent` -Inicie e gerencie execuções de subagent em segundo plano. +Inicie e gerencie execuções de subagente em segundo plano. ```typescript -// Iniciar uma execução de subagent +// Start a subagent run const { runId } = await api.runtime.subagent.run({ sessionKey: "agent:main:subagent:search-helper", - message: "Expanda esta consulta em buscas de acompanhamento mais focadas.", - provider: "openai", // substituição opcional - model: "gpt-4.1-mini", // substituição opcional + message: "Expand this query into focused follow-up searches.", + provider: "openai", // optional override + model: "gpt-4.1-mini", // optional override deliver: false, }); -// Aguardar a conclusão +// Wait for completion const result = await api.runtime.subagent.waitForRun({ runId, timeoutMs: 30000 }); -// Ler mensagens da sessão +// Read session messages const { messages } = await api.runtime.subagent.getSessionMessages({ sessionKey: "agent:main:subagent:search-helper", limit: 10, }); -// Excluir uma sessão +// Delete a session await api.runtime.subagent.deleteSession({ sessionKey: "agent:main:subagent:search-helper", }); ``` - Substituições de modelo (`provider`/`model`) exigem ativação pelo operador via - `plugins.entries..subagent.allowModelOverride: true` na configuração. - Plugins não confiáveis ainda podem executar subagentes, mas solicitações de substituição são rejeitadas. + Substituições de modelo (`provider`/`model`) exigem opt-in do operador via + `plugins.entries..subagent.allowModelOverride: true` na config. + Plugins não confiáveis ainda podem executar subagentes, mas solicitações de + substituição são rejeitadas. ### `api.runtime.taskFlow` -Vincule um runtime de Task Flow a uma chave de sessão OpenClaw existente ou a um -contexto de ferramenta confiável e, em seguida, crie e gerencie Task Flows sem passar um proprietário em cada chamada. +Vincule um tempo de execução do TaskFlow a uma chave de sessão OpenClaw existente ou a um +contexto de ferramenta confiável, e então crie e gerencie TaskFlows sem passar um owner em +cada chamada. ```typescript const taskFlow = api.runtime.taskFlow.fromToolContext(ctx); const created = taskFlow.createManaged({ controllerId: "my-plugin/review-batch", - goal: "Revisar novos pull requests", + goal: "Review new pull requests", }); const child = taskFlow.runTask({ flowId: created.flowId, runtime: "acp", childSessionKey: "agent:main:subagent:reviewer", - task: "Revisar PR #123", + task: "Review PR #123", status: "running", startedAt: Date.now(), }); @@ -159,27 +162,27 @@ const waiting = taskFlow.setWaiting({ ``` Use `bindSession({ sessionKey, requesterOrigin })` quando você já tiver uma -chave de sessão OpenClaw confiável da sua própria camada de vínculo. Não vincule a partir de entrada bruta do -usuário. +chave de sessão OpenClaw confiável da sua própria camada de vinculação. Não faça vinculação a partir de +entrada bruta do usuário. ### `api.runtime.tts` Síntese de texto para fala. ```typescript -// TTS padrão +// Standard TTS const clip = await api.runtime.tts.textToSpeech({ - text: "Olá do OpenClaw", + text: "Hello from OpenClaw", cfg: api.config, }); -// TTS otimizado para telefonia +// Telephony-optimized TTS const telephonyClip = await api.runtime.tts.textToSpeechTelephony({ - text: "Olá do OpenClaw", + text: "Hello from OpenClaw", cfg: api.config, }); -// Listar vozes disponíveis +// List available voices const voices = await api.runtime.tts.listVoices({ provider: "elevenlabs", cfg: api.config, @@ -194,27 +197,27 @@ de áudio PCM + taxa de amostragem. Análise de imagem, áudio e vídeo. ```typescript -// Descrever uma imagem +// Describe an image const image = await api.runtime.mediaUnderstanding.describeImageFile({ filePath: "/tmp/inbound-photo.jpg", cfg: api.config, agentDir: "/tmp/agent", }); -// Transcrever áudio +// Transcribe audio const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ filePath: "/tmp/inbound-audio.ogg", cfg: api.config, - mime: "audio/ogg", // opcional, para quando o MIME não puder ser inferido + mime: "audio/ogg", // optional, for when MIME cannot be inferred }); -// Descrever um vídeo +// Describe a video const video = await api.runtime.mediaUnderstanding.describeVideoFile({ filePath: "/tmp/inbound-video.mp4", cfg: api.config, }); -// Análise genérica de arquivo +// Generic file analysis const result = await api.runtime.mediaUnderstanding.runFile({ filePath: "/tmp/inbound-file.pdf", cfg: api.config, @@ -224,7 +227,7 @@ const result = await api.runtime.mediaUnderstanding.runFile({ Retorna `{ text: undefined }` quando nenhuma saída é produzida (por exemplo, entrada ignorada). - `api.runtime.stt.transcribeAudioFile(...)` continua disponível como alias de compatibilidade + `api.runtime.stt.transcribeAudioFile(...)` permanece como um alias de compatibilidade para `api.runtime.mediaUnderstanding.transcribeAudioFile(...)`. @@ -234,7 +237,7 @@ Geração de imagem. ```typescript const result = await api.runtime.imageGeneration.generate({ - prompt: "Um robô pintando um pôr do sol", + prompt: "A robot painting a sunset", cfg: api.config, }); @@ -250,7 +253,7 @@ const providers = api.runtime.webSearch.listProviders({ config: api.config }); const result = await api.runtime.webSearch.search({ config: api.config, - args: { query: "SDK de plugins do OpenClaw", count: 5 }, + args: { query: "OpenClaw plugin SDK", count: 5 }, }); ``` @@ -269,7 +272,7 @@ const resized = await api.runtime.media.resizeToJpeg(buffer, { maxWidth: 800 }); ### `api.runtime.config` -Carregamento e gravação de configuração. +Carregamento e escrita de config. ```typescript const cfg = await api.runtime.config.loadConfig(); @@ -278,7 +281,7 @@ await api.runtime.config.writeConfigFile(cfg); ### `api.runtime.system` -Utilitários em nível de sistema. +Utilitários de nível de sistema. ```typescript await api.runtime.system.enqueueSystemEvent(event); @@ -302,7 +305,7 @@ api.runtime.events.onSessionTranscriptUpdate((update) => { ### `api.runtime.logging` -Logs. +Logging. ```typescript const verbose = api.runtime.logging.shouldLogVerbose(); @@ -331,7 +334,7 @@ const stateDir = api.runtime.state.resolveStateDir(); ### `api.runtime.tools` -Fábricas de ferramentas de memória e CLI. +Factories de ferramenta de memória e CLI. ```typescript const getTool = api.runtime.tools.createMemoryGetTool(/* ... */); @@ -341,10 +344,10 @@ api.runtime.tools.registerMemoryCli(/* ... */); ### `api.runtime.channel` -Auxiliares de runtime específicos de canal (disponíveis quando um plugin de canal é carregado). +Auxiliares de tempo de execução específicos do canal (disponíveis quando um Plugin de canal é carregado). -`api.runtime.channel.mentions` é a superfície compartilhada de política de menções de entrada para -plugins de canal incluídos que usam injeção de runtime: +`api.runtime.channel.mentions` é a superfície compartilhada de política de menção de entrada para +Plugins de canal empacotados que usam injeção de tempo de execução: ```typescript const mentionMatch = api.runtime.channel.mentions.matchesMentionWithExplicit(text, { @@ -379,56 +382,62 @@ Auxiliares de menção disponíveis: - `implicitMentionKindWhen` - `resolveInboundMentionDecision` -`api.runtime.channel.mentions` intencionalmente não expõe os auxiliares legados de compatibilidade -`resolveMentionGating*`. Prefira o caminho normalizado +`api.runtime.channel.mentions` intencionalmente não expõe os auxiliares de compatibilidade +antigos `resolveMentionGating*`. Prefira o caminho normalizado `{ facts, policy }`. -## Armazenando referências de runtime +## Armazenando referências de tempo de execução -Use `createPluginRuntimeStore` para armazenar a referência de runtime para uso fora +Use `createPluginRuntimeStore` para armazenar a referência de tempo de execução para uso fora do callback `register`: ```typescript import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store"; import type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store"; -const store = createPluginRuntimeStore("runtime de my-plugin não inicializado"); +const store = createPluginRuntimeStore({ + pluginId: "my-plugin", + errorMessage: "my-plugin runtime not initialized", +}); -// No seu ponto de entrada +// In your entry point export default defineChannelPluginEntry({ id: "my-plugin", name: "My Plugin", - description: "Exemplo", + description: "Example", plugin: myPlugin, setRuntime: store.setRuntime, }); -// Em outros arquivos +// In other files export function getRuntime() { - return store.getRuntime(); // lança erro se não estiver inicializado + return store.getRuntime(); // throws if not initialized } export function tryGetRuntime() { - return store.tryGetRuntime(); // retorna null se não estiver inicializado + return store.tryGetRuntime(); // returns null if not initialized } ``` +Prefira `pluginId` para a identidade do runtime-store. A forma de nível mais baixo `key` é +para casos incomuns em que um plugin intencionalmente precisa de mais de um slot de tempo de execução. + ## Outros campos de nível superior de `api` Além de `api.runtime`, o objeto API também fornece: | Campo | Tipo | Descrição | | ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- | -| `api.id` | `string` | ID do plugin | -| `api.name` | `string` | Nome de exibição do plugin | -| `api.config` | `OpenClawConfig` | Snapshot atual da configuração (snapshot ativo em memória do runtime quando disponível) | -| `api.pluginConfig` | `Record` | Configuração específica do plugin em `plugins.entries..config` | +| `api.id` | `string` | ID do Plugin | +| `api.name` | `string` | Nome de exibição do Plugin | +| `api.config` | `OpenClawConfig` | Snapshot atual da config (snapshot ativo em memória do tempo de execução quando disponível) | +| `api.pluginConfig` | `Record` | Config específica do Plugin em `plugins.entries..config` | | `api.logger` | `PluginLogger` | Logger com escopo (`debug`, `info`, `warn`, `error`) | | `api.registrationMode` | `PluginRegistrationMode` | Modo de carregamento atual; `"setup-runtime"` é a janela leve de inicialização/configuração antes da entrada completa | -| `api.resolvePath(input)` | `(string) => string` | Resolve um caminho relativo à raiz do plugin | +| `api.resolvePath(input)` | `(string) => string` | Resolve um caminho relativo à raiz do Plugin | ## Relacionado -- [SDK Overview](/pt-BR/plugins/sdk-overview) -- referência de subcaminhos -- [SDK Entry Points](/pt-BR/plugins/sdk-entrypoints) -- opções de `definePluginEntry` -- [Plugin Internals](/pt-BR/plugins/architecture) -- modelo de capacidades e registro +- [Visão geral do SDK](/pt-BR/plugins/sdk-overview) -- referência de subpath +- [Pontos de entrada do SDK](/pt-BR/plugins/sdk-entrypoints) -- opções de `definePluginEntry` +- [Internos do Plugin](/pt-BR/plugins/architecture) -- modelo de capacidades e registro diff --git a/docs/pt-BR/plugins/sdk-setup.md b/docs/pt-BR/plugins/sdk-setup.md index ff13b5e5e..73d13cdb2 100644 --- a/docs/pt-BR/plugins/sdk-setup.md +++ b/docs/pt-BR/plugins/sdk-setup.md @@ -1,35 +1,35 @@ --- read_when: - - Você está adicionando um assistente de setup a um plugin - - Você precisa entender setup-entry.ts versus index.ts - - Você está definindo schemas de configuração de plugin ou metadados openclaw no package.json + - Você está adicionando um assistente de configuração a um Plugin + - Você precisa entender `setup-entry.ts` versus `index.ts` + - Você está definindo esquemas de config do Plugin ou metadados `openclaw` no `package.json` sidebarTitle: Setup and Config -summary: Assistentes de setup, setup-entry.ts, schemas de configuração e metadados do package.json -title: Setup e configuração de plugins +summary: Assistentes de configuração, setup-entry.ts, esquemas de configuração e metadados do package.json +title: Configuração e Config do Plugin x-i18n: - generated_at: "2026-04-06T03:10:35Z" + generated_at: "2026-04-15T19:41:37Z" model: gpt-5.4 provider: openai - source_hash: eac2586516d27bcd94cc4c259fe6274c792b3f9938c7ddd6dbf04a6dbb988dc9 + source_hash: ddf28e25e381a4a38ac478e531586f59612e1a278732597375f87c2eeefc521b source_path: plugins/sdk-setup.md workflow: 15 --- -# Setup e configuração de plugins +# Configuração e Config do Plugin -Referência para empacotamento de plugin (metadados de `package.json`), manifestos -(`openclaw.plugin.json`), entradas de setup e schemas de configuração. +Referência para empacotamento de Plugin (metadados do `package.json`), manifestos +(`openclaw.plugin.json`), entradas de configuração e esquemas de config. **Está procurando um passo a passo?** Os guias práticos cobrem o empacotamento em contexto: - [Channel Plugins](/pt-BR/plugins/sdk-channel-plugins#step-1-package-and-manifest) e - [Provider Plugins](/pt-BR/plugins/sdk-provider-plugins#step-1-package-and-manifest). + [Plugins de Canal](/pt-BR/plugins/sdk-channel-plugins#step-1-package-and-manifest) e + [Plugins de Provedor](/pt-BR/plugins/sdk-provider-plugins#step-1-package-and-manifest). ## Metadados do pacote Seu `package.json` precisa de um campo `openclaw` que informe ao sistema de plugins o que -seu plugin fornece: +seu Plugin fornece: **Plugin de canal:** @@ -50,7 +50,7 @@ seu plugin fornece: } ``` -**Plugin de provedor / baseline de publicação no ClawHub:** +**Plugin de provedor / linha de base de publicação do ClawHub:** ```json openclaw-clawhub-package.json { @@ -71,47 +71,47 @@ seu plugin fornece: } ``` -Se você publicar o plugin externamente no ClawHub, esses campos `compat` e `build` +Se você publicar o Plugin externamente no ClawHub, esses campos `compat` e `build` serão obrigatórios. Os snippets canônicos de publicação ficam em `docs/snippets/plugin-publish/`. ### Campos `openclaw` -| Campo | Tipo | Descrição | -| ------------ | ---------- | --------------------------------------------------------------------------------------------------------- | -| `extensions` | `string[]` | Arquivos de ponto de entrada (relativos à raiz do pacote) | -| `setupEntry` | `string` | Entrada leve apenas para setup (opcional) | -| `channel` | `object` | Metadados do catálogo de canais para superfícies de setup, seletor, quickstart e status | -| `providers` | `string[]` | IDs de provedor registrados por este plugin | +| Campo | Tipo | Descrição | +| ------------ | ---------- | ----------------------------------------------------------------------------------------------------- | +| `extensions` | `string[]` | Arquivos de ponto de entrada (relativos à raiz do pacote) | +| `setupEntry` | `string` | Entrada leve apenas para configuração (opcional) | +| `channel` | `object` | Metadados do catálogo de canais para configuração, seletor, início rápido e superfícies de status | +| `providers` | `string[]` | IDs de provedores registrados por este Plugin | | `install` | `object` | Dicas de instalação: `npmSpec`, `localPath`, `defaultChoice`, `minHostVersion`, `allowInvalidConfigRecovery` | -| `startup` | `object` | Flags de comportamento de inicialização | +| `startup` | `object` | Flags de comportamento de inicialização | ### `openclaw.channel` -`openclaw.channel` são metadados leves de pacote para descoberta de canal e superfícies de setup -antes do carregamento do runtime. +`openclaw.channel` é um metadado barato de pacote para descoberta de canais e +superfícies de configuração antes que o runtime seja carregado. -| Campo | Tipo | O que significa | -| -------------------------------------- | ---------- | ------------------------------------------------------------------------------ | -| `id` | `string` | ID canônico do canal. | -| `label` | `string` | Rótulo principal do canal. | -| `selectionLabel` | `string` | Rótulo de seletor/setup quando deve diferir de `label`. | -| `detailLabel` | `string` | Rótulo de detalhe secundário para catálogos de canal e superfícies de status mais ricos. | -| `docsPath` | `string` | Caminho da documentação para links de setup e seleção. | -| `docsLabel` | `string` | Rótulo substituto usado para links de documentação quando deve diferir do id do canal. | -| `blurb` | `string` | Descrição curta de onboarding/catálogo. | -| `order` | `number` | Ordem de classificação em catálogos de canal. | -| `aliases` | `string[]` | Aliases extras de lookup para seleção de canal. | -| `preferOver` | `string[]` | IDs de plugin/canal de prioridade mais baixa sobre os quais este canal deve prevalecer. | -| `systemImage` | `string` | Nome opcional de ícone/system-image para catálogos de UI de canal. | -| `selectionDocsPrefix` | `string` | Texto de prefixo antes dos links de documentação em superfícies de seleção. | -| `selectionDocsOmitLabel` | `boolean` | Mostra o caminho da documentação diretamente em vez de um link rotulado nas cópias de seleção. | -| `selectionExtras` | `string[]` | Strings curtas extras anexadas na cópia de seleção. | +| Campo | Tipo | O que significa | +| -------------------------------------- | ---------- | ----------------------------------------------------------------------------- | +| `id` | `string` | ID canônico do canal. | +| `label` | `string` | Rótulo principal do canal. | +| `selectionLabel` | `string` | Rótulo do seletor/configuração quando deve ser diferente de `label`. | +| `detailLabel` | `string` | Rótulo de detalhe secundário para catálogos de canais e superfícies de status mais ricos. | +| `docsPath` | `string` | Caminho da documentação para links de configuração e seleção. | +| `docsLabel` | `string` | Rótulo substituto usado para links de documentação quando deve ser diferente do ID do canal. | +| `blurb` | `string` | Descrição curta para onboarding/catálogo. | +| `order` | `number` | Ordem de classificação em catálogos de canais. | +| `aliases` | `string[]` | Aliases extras de busca para seleção de canal. | +| `preferOver` | `string[]` | IDs de Plugin/canal de prioridade inferior que este canal deve superar. | +| `systemImage` | `string` | Nome opcional de ícone/imagem do sistema para catálogos de UI de canais. | +| `selectionDocsPrefix` | `string` | Texto de prefixo antes dos links de documentação nas superfícies de seleção. | +| `selectionDocsOmitLabel` | `boolean` | Mostra o caminho da documentação diretamente em vez de um link rotulado na cópia de seleção. | +| `selectionExtras` | `string[]` | Strings curtas extras anexadas na cópia de seleção. | | `markdownCapable` | `boolean` | Marca o canal como compatível com Markdown para decisões de formatação de saída. | -| `exposure` | `object` | Controles de visibilidade do canal para superfícies de setup, listas configuradas e documentação. | -| `quickstartAllowFrom` | `boolean` | Inclui este canal no fluxo padrão de setup `allowFrom` do quickstart. | -| `forceAccountBinding` | `boolean` | Exige vinculação explícita de conta mesmo quando existe apenas uma conta. | -| `preferSessionLookupForAnnounceTarget` | `boolean` | Prefere lookup de sessão ao resolver destinos de anúncio para este canal. | +| `exposure` | `object` | Controles de visibilidade do canal para configuração, listas configuradas e superfícies de documentação. | +| `quickstartAllowFrom` | `boolean` | Inclui este canal no fluxo padrão de configuração `allowFrom` de início rápido. | +| `forceAccountBinding` | `boolean` | Exige vínculo explícito de conta mesmo quando existe apenas uma conta. | +| `preferSessionLookupForAnnounceTarget` | `boolean` | Prefere busca de sessão ao resolver destinos de anúncio para este canal. | Exemplo: @@ -145,35 +145,35 @@ Exemplo: `exposure` oferece suporte a: -- `configured`: inclui o canal em superfícies de listagem configurada/estilo status -- `setup`: inclui o canal em seletores interativos de setup/configuração -- `docs`: marca o canal como público em superfícies de documentação/navegação +- `configured`: incluir o canal em superfícies de listagem no estilo configurado/status +- `setup`: incluir o canal em seletores interativos de configuração/configurar +- `docs`: marcar o canal como voltado ao público em superfícies de documentação/navegação -`showConfigured` e `showInSetup` continuam aceitos como aliases legados. Prefira +`showConfigured` e `showInSetup` continuam com suporte como aliases legados. Prefira `exposure`. ### `openclaw.install` -`openclaw.install` é metadado de pacote, não metadado de manifesto. +`openclaw.install` é um metadado de pacote, não um metadado de manifesto. | Campo | Tipo | O que significa | -| ---------------------------- | -------------------- | --------------------------------------------------------------------------------- | +| ---------------------------- | -------------------- | -------------------------------------------------------------------------------- | | `npmSpec` | `string` | Especificação npm canônica para fluxos de instalação/atualização. | -| `localPath` | `string` | Caminho de instalação local de desenvolvimento ou empacotada. | -| `defaultChoice` | `"npm"` \| `"local"` | Origem de instalação preferida quando ambas estão disponíveis. | -| `minHostVersion` | `string` | Versão mínima compatível do OpenClaw no formato `>=x.y.z`. | -| `allowInvalidConfigRecovery` | `boolean` | Permite que fluxos de reinstalação de plugin empacotado recuperem falhas específicas de configuração obsoleta. | +| `localPath` | `string` | Caminho local de desenvolvimento ou instalação empacotada. | +| `defaultChoice` | `"npm"` \| `"local"` | Fonte de instalação preferida quando ambas estiverem disponíveis. | +| `minHostVersion` | `string` | Versão mínima suportada do OpenClaw no formato `>=x.y.z`. | +| `allowInvalidConfigRecovery` | `boolean` | Permite que fluxos de reinstalação de Plugin empacotado recuperem falhas específicas de config obsoleta. | -Se `minHostVersion` estiver definido, tanto a instalação quanto o carregamento do registro de manifestos -o aplicarão. Hosts mais antigos ignoram o plugin; strings de versão inválidas são rejeitadas. +Se `minHostVersion` estiver definido, tanto a instalação quanto o carregamento do registro de manifesto o aplicarão. +Hosts mais antigos ignoram o Plugin; strings de versão inválidas são rejeitadas. -`allowInvalidConfigRecovery` não é um bypass geral para configurações quebradas. Ele existe -apenas para recuperação restrita de plugins empacotados, para que reinstalação/setup possa reparar sobras -conhecidas de upgrades, como um caminho ausente de plugin empacotado ou uma entrada obsoleta `channels.` -para esse mesmo plugin. Se a configuração estiver quebrada por motivos não relacionados, a instalação -ainda falha de forma fechada e orienta o operador a executar `openclaw doctor --fix`. +`allowInvalidConfigRecovery` não é um bypass geral para configs quebradas. É +para recuperação restrita apenas de Plugin empacotado, de modo que reinstalação/configuração possa reparar sobras conhecidas +de upgrade, como um caminho ausente de Plugin empacotado ou uma entrada obsoleta `channels.` +desse mesmo Plugin. Se a config estiver quebrada por motivos não relacionados, a instalação +ainda falhará de forma fechada e informará ao operador para executar `openclaw doctor --fix`. -### Carregamento completo adiado +### Adiamento do carregamento completo Plugins de canal podem optar por carregamento adiado com: @@ -189,26 +189,26 @@ Plugins de canal podem optar por carregamento adiado com: } ``` -Quando ativado, o OpenClaw carrega apenas `setupEntry` durante a fase de inicialização -pré-listen, mesmo para canais já configurados. A entrada completa carrega depois que o -gateway começa a escutar. +Quando ativado, o OpenClaw carrega apenas `setupEntry` durante a fase de +inicialização anterior ao listen, mesmo para canais já configurados. A entrada completa é carregada após o +gateway começar a escutar. - Ative o carregamento adiado apenas quando seu `setupEntry` registrar tudo de que o + Ative o carregamento adiado apenas quando seu `setupEntry` registrar tudo o que o gateway precisa antes de começar a escutar (registro de canal, rotas HTTP, - métodos do gateway). Se a entrada completa controlar capacidades obrigatórias de inicialização, mantenha + métodos do gateway). Se a entrada completa possuir recursos de inicialização obrigatórios, mantenha o comportamento padrão. -Se sua entrada de setup/completa registrar métodos RPC do gateway, mantenha-os em um -prefixo específico do plugin. Os namespaces administrativos reservados do core (`config.*`, -`exec.approvals.*`, `wizard.*`, `update.*`) continuam pertencendo ao core e sempre são resolvidos +Se sua entrada de configuração/completa registrar métodos RPC do gateway, mantenha-os em um +prefixo específico do Plugin. Namespaces administrativos reservados do core (`config.*`, +`exec.approvals.*`, `wizard.*`, `update.*`) continuam pertencendo ao core e sempre serão resolvidos para `operator.admin`. -## Manifesto do plugin +## Manifesto do Plugin -Todo plugin nativo deve incluir um `openclaw.plugin.json` na raiz do pacote. -O OpenClaw usa isso para validar a configuração sem executar o código do plugin. +Todo Plugin nativo deve incluir um `openclaw.plugin.json` na raiz do pacote. +O OpenClaw usa isso para validar a config sem executar código do Plugin. ```json { @@ -228,7 +228,7 @@ O OpenClaw usa isso para validar a configuração sem executar o código do plug } ``` -Para plugins de canal, adicione `kind` e `channels`: +Para Plugins de canal, adicione `kind` e `channels`: ```json { @@ -243,7 +243,7 @@ Para plugins de canal, adicione `kind` e `channels`: } ``` -Mesmo plugins sem configuração devem incluir um schema. Um schema vazio é válido: +Mesmo Plugins sem config devem incluir um esquema. Um esquema vazio é válido: ```json { @@ -255,25 +255,25 @@ Mesmo plugins sem configuração devem incluir um schema. Um schema vazio é vá } ``` -Consulte [Plugin Manifest](/pt-BR/plugins/manifest) para a referência completa do schema. +Consulte [Manifesto do Plugin](/pt-BR/plugins/manifest) para a referência completa do esquema. ## Publicação no ClawHub -Para pacotes de plugin, use o comando do ClawHub específico para pacote: +Para pacotes de Plugin, use o comando do ClawHub específico para pacotes: ```bash clawhub package publish your-org/your-plugin --dry-run clawhub package publish your-org/your-plugin ``` -O alias legado de publicação apenas para skill é para Skills. Pacotes de plugin devem +O alias legado de publicação apenas para Skills é para Skills. Pacotes de Plugin devem sempre usar `clawhub package publish`. -## Entrada de setup +## Entrada de configuração -O arquivo `setup-entry.ts` é uma alternativa leve ao `index.ts` que o -OpenClaw carrega quando precisa apenas das superfícies de setup (onboarding, reparo de configuração, -inspeção de canal desativado). +O arquivo `setup-entry.ts` é uma alternativa leve a `index.ts` que +o OpenClaw carrega quando precisa apenas das superfícies de configuração (onboarding, reparo +de config, inspeção de canal desativado). ```typescript // setup-entry.ts @@ -283,20 +283,26 @@ import { myChannelPlugin } from "./src/channel.js"; export default defineSetupPluginEntry(myChannelPlugin); ``` -Isso evita carregar código pesado de runtime (bibliotecas de criptografia, registros de CLI, -serviços em segundo plano) durante os fluxos de setup. +Isso evita carregar código pesado de runtime (bibliotecas de criptografia, registros +de CLI, serviços em segundo plano) durante fluxos de configuração. + +Canais empacotados do workspace que mantêm exportações seguras para configuração em módulos sidecar podem +usar `defineBundledChannelSetupEntry(...)` de +`openclaw/plugin-sdk/channel-entry-contract` em vez de +`defineSetupPluginEntry(...)`. Esse contrato empacotado também oferece suporte a uma exportação opcional +`runtime`, para que o wiring de runtime em tempo de configuração permaneça leve e explícito. **Quando o OpenClaw usa `setupEntry` em vez da entrada completa:** -- O canal está desativado, mas precisa de superfícies de setup/onboarding +- O canal está desativado, mas precisa de superfícies de configuração/onboarding - O canal está ativado, mas não configurado - O carregamento adiado está ativado (`deferConfiguredChannelFullLoadUntilAfterListen`) **O que `setupEntry` deve registrar:** -- O objeto do plugin de canal (via `defineSetupPluginEntry`) -- Quaisquer rotas HTTP necessárias antes do gateway escutar -- Quaisquer métodos de gateway necessários durante a inicialização +- O objeto do Plugin de canal (via `defineSetupPluginEntry`) +- Quaisquer rotas HTTP necessárias antes de o gateway entrar em listen +- Quaisquer métodos do gateway necessários durante a inicialização Esses métodos de gateway de inicialização ainda devem evitar namespaces administrativos reservados do core como `config.*` ou `update.*`. @@ -306,53 +312,53 @@ como `config.*` ou `update.*`. - Registros de CLI - Serviços em segundo plano - Imports pesados de runtime (crypto, SDKs) -- Métodos de gateway necessários apenas após a inicialização +- Métodos do gateway necessários apenas após a inicialização -### Imports restritos de helpers de setup +### Imports restritos de helpers de configuração -Para caminhos quentes apenas de setup, prefira as interfaces restritas de helper de setup em vez da -interface guarda-chuva mais ampla `plugin-sdk/setup` quando precisar apenas de parte da superfície de setup: +Para caminhos quentes apenas de configuração, prefira os seams restritos de helper de configuração em vez do umbrella mais amplo +`plugin-sdk/setup` quando você precisar apenas de parte da superfície de configuração: -| Caminho de importação | Use para | Exportações principais | -| ------------------------------------ | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `plugin-sdk/setup-runtime` | helpers de runtime em tempo de setup que permanecem disponíveis em `setupEntry` / inicialização adiada de canal | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | -| `plugin-sdk/setup-adapter-runtime` | adaptadores de setup de conta com reconhecimento de ambiente | `createEnvPatchedAccountSetupAdapter` | -| `plugin-sdk/setup-tools` | helpers de CLI/arquivo/documentação de setup/instalação | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | +| Caminho de importação | Use para | Exportações principais | +| ----------------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `plugin-sdk/setup-runtime` | helpers de runtime em tempo de configuração que permanecem disponíveis em `setupEntry` / inicialização adiada de canal | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | +| `plugin-sdk/setup-adapter-runtime` | adaptadores de configuração de conta com reconhecimento de ambiente | `createEnvPatchedAccountSetupAdapter` | +| `plugin-sdk/setup-tools` | helpers de CLI/arquivo/documentação para configuração/instalação | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | -Use a interface mais ampla `plugin-sdk/setup` quando quiser a caixa de ferramentas completa e compartilhada de setup, -incluindo helpers de patch de configuração, como +Use o seam mais amplo `plugin-sdk/setup` quando quiser a caixa de ferramentas completa e compartilhada de configuração, +incluindo helpers de patch de config como `moveSingleAccountChannelSectionToDefaultAccount(...)`. -Os adaptadores de patch de setup continuam seguros para importação em caminhos quentes. O lookup preguiçoso -da superfície de contrato empacotada para promoção de conta única significa que importar +Os adaptadores de patch de configuração continuam seguros para importação em caminhos quentes. A busca da superfície de contrato empacotada +para promoção de conta única é lazy, portanto importar `plugin-sdk/setup-runtime` não carrega antecipadamente a descoberta da superfície de contrato empacotada -antes de o adaptador ser realmente usado. +antes de o adaptador realmente ser usado. ### Promoção de conta única controlada pelo canal -Quando um canal é atualizado de uma configuração de nível superior de conta única para -`channels..accounts.*`, o comportamento compartilhado padrão é mover valores promovidos -com escopo de conta para `accounts.default`. +Quando um canal é atualizado de uma config de nível superior de conta única para +`channels..accounts.*`, o comportamento compartilhado padrão é mover valores +promovidos com escopo de conta para `accounts.default`. -Canais empacotados podem restringir ou substituir essa promoção por meio da sua -superfície de contrato de setup: +Canais empacotados podem restringir ou substituir essa promoção por meio de sua +superfície de contrato de configuração: - `singleAccountKeysToMove`: chaves extras de nível superior que devem ser movidas para a conta promovida -- `namedAccountPromotionKeys`: quando contas nomeadas já existem, apenas essas - chaves são movidas para a conta promovida; chaves compartilhadas de política/entrega permanecem na - raiz do canal +- `namedAccountPromotionKeys`: quando contas nomeadas já existem, apenas estas + chaves são movidas para a conta promovida; chaves compartilhadas de política/entrega permanecem na raiz + do canal - `resolveSingleAccountPromotionTarget(...)`: escolhe qual conta existente recebe os valores promovidos -Matrix é o exemplo empacotado atual. Se já existir exatamente uma conta Matrix nomeada, -ou se `defaultAccount` apontar para uma chave não canônica existente, como `Ops`, -a promoção preservará essa conta em vez de criar uma nova entrada -`accounts.default`. +Matrix é o exemplo empacotado atual. Se exatamente uma conta Matrix nomeada +já existir, ou se `defaultAccount` apontar para uma chave não canônica existente +como `Ops`, a promoção preserva essa conta em vez de criar uma nova +entrada `accounts.default`. -## Schema de configuração +## Esquema de config -A configuração do plugin é validada em relação ao JSON Schema no seu manifesto. Usuários +A config do Plugin é validada em relação ao JSON Schema no seu manifesto. Os usuários configuram plugins por meio de: ```json5 @@ -369,9 +375,9 @@ configuram plugins por meio de: } ``` -Seu plugin recebe essa configuração como `api.pluginConfig` durante o registro. +Seu Plugin recebe essa config como `api.pluginConfig` durante o registro. -Para configuração específica de canal, use a seção de configuração do canal: +Para config específica de canal, use a seção de config do canal: ```json5 { @@ -384,10 +390,10 @@ Para configuração específica de canal, use a seção de configuração do can } ``` -### Criando schemas de configuração de canal +### Criando esquemas de config de canal Use `buildChannelConfigSchema` de `openclaw/plugin-sdk/core` para converter um -schema Zod no wrapper `ChannelConfigSchema` que o OpenClaw valida: +esquema Zod no wrapper `ChannelConfigSchema` que o OpenClaw valida: ```typescript import { z } from "zod"; @@ -403,9 +409,9 @@ const accountSchema = z.object({ const configSchema = buildChannelConfigSchema(accountSchema); ``` -## Assistentes de setup +## Assistentes de configuração -Plugins de canal podem fornecer assistentes interativos de setup para `openclaw onboard`. +Plugins de canal podem fornecer assistentes interativos de configuração para `openclaw onboard`. O assistente é um objeto `ChannelSetupWizard` no `ChannelPlugin`: ```typescript @@ -441,21 +447,21 @@ const setupWizard: ChannelSetupWizard = { O tipo `ChannelSetupWizard` oferece suporte a `credentials`, `textInputs`, `dmPolicy`, `allowFrom`, `groupAccess`, `prepare`, `finalize` e mais. -Consulte pacotes de plugins empacotados (por exemplo o plugin Discord em `src/channel.setup.ts`) para +Consulte os pacotes de Plugin empacotados (por exemplo, o Plugin do Discord em `src/channel.setup.ts`) para exemplos completos. Para prompts de allowlist de DM que precisam apenas do fluxo padrão -`note -> prompt -> parse -> merge -> patch`, prefira os helpers compartilhados de setup +`note -> prompt -> parse -> merge -> patch`, prefira os helpers compartilhados de configuração de `openclaw/plugin-sdk/setup`: `createPromptParsedAllowFromForAccount(...)`, `createTopLevelChannelParsedAllowFromPrompt(...)` e `createNestedChannelParsedAllowFromPrompt(...)`. -Para blocos de status de setup de canal que variam apenas em rótulos, pontuações e linhas extras opcionais, +Para blocos de status de configuração de canal que variam apenas por rótulos, pontuações e linhas extras opcionais, prefira `createStandardChannelSetupStatus(...)` de -`openclaw/plugin-sdk/setup` em vez de criar manualmente o mesmo objeto `status` em -cada plugin. +`openclaw/plugin-sdk/setup` em vez de montar manualmente o mesmo objeto `status` em +cada Plugin. -Para superfícies de setup opcionais que devem aparecer apenas em certos contextos, use +Para superfícies opcionais de configuração que devem aparecer apenas em certos contextos, use `createOptionalChannelSetupSurface` de `openclaw/plugin-sdk/channel-setup`: ```typescript @@ -470,17 +476,17 @@ const setupSurface = createOptionalChannelSetupSurface({ // Returns { setupAdapter, setupWizard } ``` -`plugin-sdk/channel-setup` também expõe os builders de nível inferior +`plugin-sdk/channel-setup` também expõe os builders de nível mais baixo `createOptionalChannelSetupAdapter(...)` e -`createOptionalChannelSetupWizard(...)` quando você precisar apenas de metade +`createOptionalChannelSetupWizard(...)` quando você precisa apenas de uma metade dessa superfície de instalação opcional. -O adaptador/assistente opcional gerado falha de forma fechada em gravações reais de configuração. Eles +O adaptador/assistente opcional gerado falha de forma fechada em gravações reais de config. Eles reutilizam uma única mensagem de instalação obrigatória em `validateInput`, -`applyAccountConfig` e `finalize`, e acrescentam um link de documentação quando `docsPath` estiver +`applyAccountConfig` e `finalize`, e acrescentam um link de documentação quando `docsPath` está definido. -Para UIs de setup baseadas em binário, prefira os helpers delegados compartilhados em vez de +Para UIs de configuração baseadas em binário, prefira os helpers delegados compartilhados em vez de copiar a mesma cola de binário/status em cada canal: - `createDetectedBinaryStatus(...)` para blocos de status que variam apenas por rótulos, @@ -488,35 +494,35 @@ copiar a mesma cola de binário/status em cada canal: - `createCliPathTextInput(...)` para entradas de texto baseadas em caminho - `createDelegatedSetupWizardStatusResolvers(...)`, `createDelegatedPrepare(...)`, `createDelegatedFinalize(...)` e - `createDelegatedResolveConfigured(...)` quando `setupEntry` precisar encaminhar preguiçosamente para - um assistente completo mais pesado -- `createDelegatedTextInputShouldPrompt(...)` quando `setupEntry` só precisar - delegar uma decisão de `textInputs[*].shouldPrompt` + `createDelegatedResolveConfigured(...)` quando `setupEntry` precisa encaminhar para + um assistente completo mais pesado de forma lazy +- `createDelegatedTextInputShouldPrompt(...)` quando `setupEntry` precisa apenas + delegar uma decisão `textInputs[*].shouldPrompt` ## Publicação e instalação -**Plugins externos:** publique no [ClawHub](/pt-BR/tools/clawhub) ou npm e depois instale: +**Plugins externos:** publique no [ClawHub](/pt-BR/tools/clawhub) ou no npm e depois instale: ```bash openclaw plugins install @myorg/openclaw-my-plugin ``` O OpenClaw tenta primeiro o ClawHub e recorre automaticamente ao npm. Você também pode -forçar o ClawHub explicitamente: +forçar explicitamente o ClawHub: ```bash openclaw plugins install clawhub:@myorg/openclaw-my-plugin # somente ClawHub ``` -Não existe um override correspondente `npm:`. Use a especificação normal de pacote npm quando +Não existe uma substituição correspondente `npm:`. Use a especificação normal de pacote npm quando quiser o caminho npm após o fallback do ClawHub: ```bash openclaw plugins install @myorg/openclaw-my-plugin ``` -**Plugins no repositório:** coloque-os sob a árvore de workspace de plugins empacotados e eles serão -descobertos automaticamente durante a build. +**Plugins no repositório:** coloque-os na árvore de workspace de plugins empacotados e eles serão automaticamente +descobertos durante o build. **Os usuários podem instalar:** @@ -525,13 +531,13 @@ openclaw plugins install ``` - Para instalações obtidas do npm, `openclaw plugins install` executa - `npm install --ignore-scripts` (sem scripts de ciclo de vida). Mantenha as árvores de dependência - de plugin em JS/TS puro e evite pacotes que exijam builds em `postinstall`. + Para instalações vindas do npm, `openclaw plugins install` executa + `npm install --ignore-scripts` (sem scripts de ciclo de vida). Mantenha as árvores + de dependências do Plugin em JS/TS puro e evite pacotes que exijam builds em `postinstall`. ## Relacionado -- [SDK Entry Points](/pt-BR/plugins/sdk-entrypoints) -- `definePluginEntry` e `defineChannelPluginEntry` -- [Plugin Manifest](/pt-BR/plugins/manifest) -- referência completa do schema de manifesto -- [Building Plugins](/pt-BR/plugins/building-plugins) -- guia passo a passo de primeiros passos +- [Pontos de entrada do SDK](/pt-BR/plugins/sdk-entrypoints) -- `definePluginEntry` e `defineChannelPluginEntry` +- [Manifesto do Plugin](/pt-BR/plugins/manifest) -- referência completa do esquema do manifesto +- [Criando Plugins](/pt-BR/plugins/building-plugins) -- guia passo a passo para começar diff --git a/docs/pt-BR/plugins/sdk-testing.md b/docs/pt-BR/plugins/sdk-testing.md index 8932c7b1c..e3621022c 100644 --- a/docs/pt-BR/plugins/sdk-testing.md +++ b/docs/pt-BR/plugins/sdk-testing.md @@ -1,29 +1,28 @@ --- read_when: - - Você está escrevendo testes para um plugin - - Você precisa de utilitários de teste do SDK de plugin - - Você quer entender testes de contrato para plugins empacotados + - Você está escrevendo testes para um Plugin + - Você precisa de utilitários de teste do SDK de Plugin + - Você quer entender os testes de contrato para plugins empacotados sidebarTitle: Testing summary: Utilitários e padrões de teste para plugins do OpenClaw -title: Testes de Plugin +title: Teste de Plugin x-i18n: - generated_at: "2026-04-05T12:49:56Z" + generated_at: "2026-04-15T19:41:42Z" model: gpt-5.4 provider: openai - source_hash: 2e95ed58ed180feadad17bb5138bd09e3b45f1f3ecdff4e2fba4874bb80099fe + source_hash: 2f75bd3f3b5ba34b05786e0dd96d493c36db73a1d258998bf589e27e45c0bd09 source_path: plugins/sdk-testing.md workflow: 15 --- -# Testes de Plugin +# Teste de Plugin -Referência para utilitários de teste, padrões e aplicação de lint para -plugins do OpenClaw. +Referência para utilitários de teste, padrões e aplicação de lint para plugins do OpenClaw. **Procurando exemplos de teste?** Os guias práticos incluem exemplos de teste completos: - [Testes de plugin de canal](/plugins/sdk-channel-plugins#step-6-test) e - [Testes de plugin de provedor](/plugins/sdk-provider-plugins#step-6-test). + [Testes de Plugin de canal](/pt-BR/plugins/sdk-channel-plugins#step-6-test) e + [Testes de Plugin de provedor](/pt-BR/plugins/sdk-provider-plugins#step-6-test). ## Utilitários de teste @@ -42,11 +41,11 @@ import { ### Exportações disponíveis -| Exportação | Finalidade | -| ------------------------------------- | ------------------------------------------------------ | -| `installCommonResolveTargetErrorCases` | Casos de teste compartilhados para tratamento de erros de resolução de destino | -| `shouldAckReaction` | Verifica se um canal deve adicionar uma reação de ack | -| `removeAckReactionAfterReply` | Remove a reação de ack após a entrega da resposta | +| Export | Propósito | +| -------------------------------------- | -------------------------------------------------------- | +| `installCommonResolveTargetErrorCases` | Casos de teste compartilhados para tratamento de erros de resolução de alvo | +| `shouldAckReaction` | Verifica se um canal deve adicionar uma reação de confirmação | +| `removeAckReactionAfterReply` | Remove a reação de confirmação após a entrega da resposta | ### Tipos @@ -63,10 +62,9 @@ import type { } from "openclaw/plugin-sdk/testing"; ``` -## Testando a resolução de destino +## Testando a resolução de alvo -Use `installCommonResolveTargetErrorCases` para adicionar casos de erro padrão para -resolução de destino de canal: +Use `installCommonResolveTargetErrorCases` para adicionar casos de erro padrão para resolução de alvo do canal: ```typescript import { describe } from "vitest"; @@ -90,7 +88,7 @@ describe("my-channel target resolution", () => { ## Padrões de teste -### Testando unitariamente um plugin de canal +### Teste unitário de um Plugin de canal ```typescript import { describe, it, expect, vi } from "vitest"; @@ -126,7 +124,7 @@ describe("my-channel plugin", () => { }); ``` -### Testando unitariamente um plugin de provedor +### Teste unitário de um Plugin de provedor ```typescript import { describe, it, expect } from "vitest"; @@ -154,15 +152,18 @@ describe("my-provider plugin", () => { }); ``` -### Simulando o runtime do plugin +### Mockando o runtime do Plugin -Para código que usa `createPluginRuntimeStore`, simule o runtime nos testes: +Para código que usa `createPluginRuntimeStore`, faça mock do runtime nos testes: ```typescript import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store"; import type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store"; -const store = createPluginRuntimeStore("test runtime not set"); +const store = createPluginRuntimeStore({ + pluginId: "test-plugin", + errorMessage: "test runtime not set", +}); // In test setup const mockRuntime = { @@ -198,7 +199,7 @@ client.sendMessage = vi.fn().mockResolvedValue({ id: "msg-1" }); ## Testes de contrato (plugins no repositório) -Plugins empacotados têm testes de contrato que verificam a propriedade de registro: +Plugins empacotados têm testes de contrato que verificam a propriedade do registro: ```bash pnpm test -- src/plugins/contracts/ @@ -213,13 +214,13 @@ Esses testes verificam: ### Executando testes com escopo -Para um plugin específico: +Para um Plugin específico: ```bash pnpm test -- /my-channel/ ``` -Apenas para testes de contrato: +Somente para testes de contrato: ```bash pnpm test -- src/plugins/contracts/shape.contract.test.ts @@ -235,12 +236,11 @@ Três regras são aplicadas por `pnpm check` para plugins no repositório: 2. **Sem importações diretas de `src/`** -- plugins não podem importar `../../src/` diretamente 3. **Sem autoimportações** -- plugins não podem importar seu próprio subcaminho `plugin-sdk/` -Plugins externos não estão sujeitos a essas regras de lint, mas seguir os mesmos -padrões é recomendado. +Plugins externos não estão sujeitos a essas regras de lint, mas seguir os mesmos padrões é recomendado. ## Configuração de teste -O OpenClaw usa Vitest com limites de cobertura V8. Para testes de plugin: +O OpenClaw usa Vitest com limites de cobertura do V8. Para testes de Plugin: ```bash # Run all tests @@ -262,9 +262,9 @@ Se as execuções locais causarem pressão de memória: OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test ``` -## Relacionado +## Relacionados -- [Visão geral do SDK](/plugins/sdk-overview) -- convenções de importação -- [SDK Channel Plugins](/plugins/sdk-channel-plugins) -- interface de plugin de canal -- [SDK Provider Plugins](/plugins/sdk-provider-plugins) -- hooks de plugin de provedor -- [Criando Plugins](/plugins/building-plugins) -- guia de introdução +- [Visão geral do SDK](/pt-BR/plugins/sdk-overview) -- convenções de importação +- [SDK de Plugins de canal](/pt-BR/plugins/sdk-channel-plugins) -- interface de Plugin de canal +- [SDK de Plugins de provedor](/pt-BR/plugins/sdk-provider-plugins) -- hooks de Plugin de provedor +- [Criando Plugins](/pt-BR/plugins/building-plugins) -- guia de introdução diff --git a/docs/pt-BR/reference/token-use.md b/docs/pt-BR/reference/token-use.md index 7ea804506..576b22fb4 100644 --- a/docs/pt-BR/reference/token-use.md +++ b/docs/pt-BR/reference/token-use.md @@ -1,53 +1,67 @@ --- read_when: - Explicando o uso de tokens, custos ou janelas de contexto - - Depurando o crescimento do contexto ou o comportamento de compactação -summary: Como o OpenClaw monta o contexto do prompt e informa o uso de tokens + custos -title: Uso de tokens e custos + - Depurando o crescimento do contexto ou o comportamento de Compaction +summary: Como o OpenClaw constrói o contexto do prompt e informa o uso de tokens + custos +title: Uso de Tokens e Custos x-i18n: - generated_at: "2026-04-12T05:33:21Z" + generated_at: "2026-04-15T19:42:06Z" model: gpt-5.4 provider: openai - source_hash: f8c856549cd28b8364a640e6fa9ec26aa736895c7a993e96cbe85838e7df2dfb + source_hash: 9a706d3df8b2ea1136b3535d216c6b358e43aee2a31a4759824385e1345e6fe5 source_path: reference/token-use.md workflow: 15 --- # Uso de tokens e custos -O OpenClaw rastreia **tokens**, não caracteres. Os tokens são específicos de cada modelo, mas a maioria dos -modelos no estilo OpenAI tem uma média de ~4 caracteres por token em texto em inglês. +O OpenClaw rastreia **tokens**, não caracteres. Os tokens são específicos de cada modelo, mas a maioria dos modelos no estilo OpenAI tem média de ~4 caracteres por token para texto em inglês. -## Como o prompt do sistema é montado +## Como o prompt do sistema é construído O OpenClaw monta seu próprio prompt do sistema em cada execução. Ele inclui: - Lista de ferramentas + descrições curtas -- Lista de Skills (somente metadados; as instruções são carregadas sob demanda com `read`) +- Lista de Skills (somente metadados; as instruções são carregadas sob demanda com `read`). + O bloco compacto de Skills é limitado por `skills.limits.maxSkillsPromptChars`, + com substituição opcional por agente em + `agents.list[].skillsLimits.maxSkillsPromptChars`. - Instruções de autoatualização -- Arquivos de workspace + bootstrap (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md` quando novo, além de `MEMORY.md` quando presente ou `memory.md` como fallback em minúsculas). Arquivos grandes são truncados por `agents.defaults.bootstrapMaxChars` (padrão: 20000), e a injeção total de bootstrap é limitada por `agents.defaults.bootstrapTotalMaxChars` (padrão: 150000). Arquivos diários `memory/*.md` não fazem parte do prompt bootstrap normal; eles permanecem sob demanda por meio de ferramentas de memória em turnos comuns, mas `/new` e `/reset` sem nenhum argumento podem prefixar um bloco único de contexto de inicialização com memória diária recente para esse primeiro turno. Esse prelúdio de inicialização é controlado por `agents.defaults.startupContext`. +- Arquivos do workspace + bootstrap (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md` quando novo, além de `MEMORY.md` quando presente ou `memory.md` como alternativa em minúsculas). Arquivos grandes são truncados por `agents.defaults.bootstrapMaxChars` (padrão: 12000), e a injeção total de bootstrap é limitada por `agents.defaults.bootstrapTotalMaxChars` (padrão: 60000). Arquivos diários `memory/*.md` não fazem parte do prompt de bootstrap normal; eles permanecem sob demanda via ferramentas de memória em turnos comuns, mas `/new` e `/reset` sem argumentos podem prefixar um bloco único de contexto de inicialização com memória diária recente para esse primeiro turno. Esse prelúdio de inicialização é controlado por `agents.defaults.startupContext`. - Hora (UTC + fuso horário do usuário) -- Tags de resposta + comportamento de heartbeat +- Tags de resposta + comportamento de Heartbeat - Metadados de runtime (host/OS/model/thinking) -Veja o detalhamento completo em [Prompt do sistema](/pt-BR/concepts/system-prompt). +Veja a análise completa em [Prompt do sistema](/pt-BR/concepts/system-prompt). ## O que conta na janela de contexto Tudo o que o modelo recebe conta para o limite de contexto: - Prompt do sistema (todas as seções listadas acima) -- Histórico da conversa (mensagens do usuário + assistente) -- Chamadas de ferramentas e resultados de ferramentas +- Histórico da conversa (mensagens do usuário + do assistente) +- Chamadas de ferramenta e resultados de ferramenta - Anexos/transcrições (imagens, áudio, arquivos) -- Resumos de compactação e artefatos de poda +- Resumos de Compaction e artefatos de poda - Wrappers do provedor ou cabeçalhos de segurança (não visíveis, mas ainda contabilizados) -Para imagens, o OpenClaw reduz a escala das cargas de imagens de transcrição/ferramentas antes das chamadas ao provedor. +Algumas superfícies pesadas de runtime têm seus próprios limites explícitos: + +- `agents.defaults.contextLimits.memoryGetMaxChars` +- `agents.defaults.contextLimits.memoryGetDefaultLines` +- `agents.defaults.contextLimits.toolResultMaxChars` +- `agents.defaults.contextLimits.postCompactionMaxChars` + +As substituições por agente ficam em `agents.list[].contextLimits`. Esses ajustes são +para trechos limitados de runtime e blocos injetados de propriedade do runtime. Eles são +separados dos limites de bootstrap, dos limites de contexto de inicialização e dos +limites do prompt de Skills. + +Para imagens, o OpenClaw reduz a escala de cargas de imagem de transcrição/ferramenta antes das chamadas ao provedor. Use `agents.defaults.imageMaxDimensionPx` (padrão: `1200`) para ajustar isso: -- Valores menores geralmente reduzem o uso de vision tokens e o tamanho da carga. -- Valores maiores preservam mais detalhes visuais para OCR/capturas de tela com muita interface. +- Valores menores normalmente reduzem o uso de vision tokens e o tamanho da carga. +- Valores maiores preservam mais detalhes visuais para capturas de tela com muito OCR/UI. Para uma análise prática (por arquivo injetado, ferramentas, Skills e tamanho do prompt do sistema), use `/context list` ou `/context detail`. Veja [Contexto](/pt-BR/concepts/context). @@ -55,9 +69,9 @@ Para uma análise prática (por arquivo injetado, ferramentas, Skills e tamanho Use estes comandos no chat: -- `/status` → **cartão de status rico em emojis** com o modelo da sessão, uso de contexto, +- `/status` → **cartão de status rico em emoji** com o modelo da sessão, uso de contexto, tokens de entrada/saída da última resposta e **custo estimado** (somente chave de API). -- `/usage off|tokens|full` → adiciona um **rodapé de uso por resposta** a cada resposta. +- `/usage off|tokens|full` → acrescenta um **rodapé de uso por resposta** a cada resposta. - Persiste por sessão (armazenado como `responseUsage`). - Autenticação OAuth **oculta o custo** (somente tokens). - `/usage cost` → mostra um resumo local de custos a partir dos logs de sessão do OpenClaw. @@ -66,67 +80,64 @@ Outras superfícies: - **TUI/Web TUI:** `/status` + `/usage` são compatíveis. - **CLI:** `openclaw status --usage` e `openclaw channels list` mostram - janelas de cota normalizadas do provedor (`X% restantes`, não custos por resposta). + janelas de cota normalizadas do provedor (`X% restante`, não custos por resposta). Provedores atuais com janela de uso: Anthropic, GitHub Copilot, Gemini CLI, OpenAI Codex, MiniMax, Xiaomi e z.ai. -As superfícies de uso normalizam aliases comuns de campos nativos do provedor antes da exibição. -Para tráfego OpenAI-family Responses, isso inclui tanto `input_tokens` / -`output_tokens` quanto `prompt_tokens` / `completion_tokens`, para que nomes de campos -específicos do transporte não alterem `/status`, `/usage` ou resumos de sessão. -O uso de JSON do Gemini CLI também é normalizado: o texto da resposta vem de `response`, e +As superfícies de uso normalizam aliases comuns de campos nativos de provedores antes da exibição. +Para tráfego Responses da família OpenAI, isso inclui tanto `input_tokens` / +`output_tokens` quanto `prompt_tokens` / `completion_tokens`, de forma que nomes de campos específicos do transporte +não alterem `/status`, `/usage` ou os resumos da sessão. +O uso JSON do Gemini CLI também é normalizado: o texto da resposta vem de `response`, e `stats.cached` é mapeado para `cacheRead`, com `stats.input_tokens - stats.cached` -usado quando a CLI omite um campo explícito `stats.input`. -Para tráfego nativo OpenAI-family Responses, aliases de uso em WebSocket/SSE são -normalizados da mesma forma, e os totais usam como fallback entrada + saída normalizadas quando +usado quando a CLI omite um campo `stats.input` explícito. +Para tráfego Responses nativo da família OpenAI, aliases de uso de WebSocket/SSE são +normalizados da mesma forma, e os totais recorrem a entrada + saída normalizadas quando `total_tokens` está ausente ou é `0`. Quando o snapshot da sessão atual é esparso, `/status` e `session_status` também podem -recuperar contadores de tokens/cache e o rótulo do modelo de runtime ativo do log de uso -da transcrição mais recente. Valores ativos não zero existentes ainda têm precedência sobre -valores de fallback da transcrição, e totais maiores da transcrição orientados a prompt +recuperar contadores de tokens/cache e o rótulo do modelo de runtime ativo do log de uso da transcrição mais recente. Valores ativos diferentes de zero ainda têm precedência sobre valores de fallback da transcrição, e totais de transcrição maiores orientados a prompt podem prevalecer quando os totais armazenados estão ausentes ou são menores. A autenticação de uso para janelas de cota do provedor vem de hooks específicos do provedor quando -disponíveis; caso contrário, o OpenClaw usa como fallback a correspondência de credenciais OAuth/chave de API +disponíveis; caso contrário, o OpenClaw recorre à correspondência de credenciais OAuth/chave de API de perfis de autenticação, env ou config. ## Estimativa de custo (quando exibida) -Os custos são estimados a partir da configuração de preços do seu modelo: +Os custos são estimados com base na sua configuração de preços do modelo: ``` models.providers..models[].cost ``` Esses valores são **USD por 1M de tokens** para `input`, `output`, `cacheRead` e -`cacheWrite`. Se o preço estiver ausente, o OpenClaw mostrará apenas os tokens. Tokens OAuth -nunca mostram custo em dólar. +`cacheWrite`. Se o preço estiver ausente, o OpenClaw mostrará apenas tokens. Tokens OAuth +nunca mostram custo em dólares. -## Impacto de TTL de cache e poda +## Impacto do TTL de cache e da poda O cache de prompt do provedor só se aplica dentro da janela de TTL do cache. O OpenClaw pode -executar opcionalmente a **poda por cache-ttl**: ele poda a sessão assim que o TTL do cache -expira e, em seguida, redefine a janela de cache para que solicitações subsequentes possam reutilizar o -contexto recém-cacheado em vez de colocar todo o histórico em cache novamente. Isso mantém os custos -de escrita em cache mais baixos quando uma sessão fica ociosa além do TTL. +executar opcionalmente **cache-ttl pruning**: ele faz a poda da sessão quando o TTL do cache +expira e então redefine a janela de cache para que solicitações subsequentes possam reutilizar +o contexto recém-cacheado em vez de recachear o histórico completo. Isso mantém os custos de +gravação em cache mais baixos quando uma sessão fica ociosa além do TTL. Configure isso em [Configuração do Gateway](/pt-BR/gateway/configuration) e veja os detalhes do comportamento em [Poda de sessão](/pt-BR/concepts/session-pruning). -Heartbeat pode manter o cache **aquecido** durante intervalos de inatividade. Se o TTL do cache -do seu modelo for `1h`, definir o intervalo de heartbeat logo abaixo disso (por exemplo, `55m`) pode evitar -recolocar todo o prompt em cache, reduzindo os custos de escrita em cache. +O Heartbeat pode manter o cache **aquecido** durante períodos de inatividade. Se o TTL de cache +do seu modelo for `1h`, definir o intervalo de Heartbeat um pouco abaixo disso (por exemplo, `55m`) pode evitar +o recacheamento do prompt completo, reduzindo os custos de gravação em cache. -Em configurações multiagente, você pode manter uma configuração de modelo compartilhada e ajustar o comportamento -de cache por agente com `agents.list[].params.cacheRetention`. +Em configurações com vários agentes, você pode manter uma configuração de modelo compartilhada e ajustar o comportamento do cache +por agente com `agents.list[].params.cacheRetention`. -Para um guia completo de cada ajuste, veja [Prompt Caching](/pt-BR/reference/prompt-caching). +Para um guia completo parâmetro por parâmetro, veja [Prompt Caching](/pt-BR/reference/prompt-caching). -Para preços da API Anthropic, leituras de cache são significativamente mais baratas do que -tokens de entrada, enquanto gravações em cache são cobradas com um multiplicador maior. Veja os preços -de prompt caching da Anthropic para as taxas e multiplicadores de TTL mais recentes: +Para preços da API Anthropic, leituras de cache são significativamente mais baratas que +tokens de entrada, enquanto gravações em cache são cobradas com um multiplicador maior. Veja os preços de prompt caching da Anthropic para as tarifas e multiplicadores de TTL mais recentes: [https://docs.anthropic.com/docs/build-with-claude/prompt-caching](https://docs.anthropic.com/docs/build-with-claude/prompt-caching) -### Exemplo: manter cache de 1h aquecido com heartbeat +### Exemplo: manter o cache de 1h aquecido com Heartbeat ```yaml agents: @@ -151,7 +162,7 @@ agents: models: "anthropic/claude-opus-4-6": params: - cacheRetention: "long" # linha de base padrão para a maioria dos agentes + cacheRetention: "long" # baseline padrão para a maioria dos agentes list: - id: "research" default: true @@ -162,13 +173,13 @@ agents: cacheRetention: "none" # evita gravações em cache para notificações intermitentes ``` -`agents.list[].params` é mesclado sobre `params` do modelo selecionado, então você pode +`agents.list[].params` é mesclado sobre os `params` do modelo selecionado, então você pode substituir apenas `cacheRetention` e herdar os outros padrões do modelo sem alterações. -### Exemplo: habilitar o cabeçalho beta de contexto 1M da Anthropic +### Exemplo: ativar o cabeçalho beta de contexto 1M da Anthropic A janela de contexto de 1M da Anthropic atualmente é controlada por beta. O OpenClaw pode injetar o -valor `anthropic-beta` necessário quando você habilita `context1m` em modelos Opus +valor `anthropic-beta` necessário quando você ativa `context1m` em modelos Opus ou Sonnet compatíveis. ```yaml @@ -182,7 +193,7 @@ agents: Isso é mapeado para o cabeçalho beta `context-1m-2025-08-07` da Anthropic. -Isso só se aplica quando `context1m: true` está definido nessa entrada de modelo. +Isso só se aplica quando `context1m: true` está definido nessa entrada do modelo. Requisito: a credencial deve ser elegível para uso de contexto longo. Caso contrário, a Anthropic responde com um erro de limite de taxa do lado do provedor para essa solicitação. @@ -194,9 +205,9 @@ rejeita essa combinação com HTTP 401. ## Dicas para reduzir a pressão de tokens - Use `/compact` para resumir sessões longas. -- Corte saídas grandes de ferramentas nos seus fluxos de trabalho. -- Reduza `agents.defaults.imageMaxDimensionPx` para sessões com muitas capturas de tela. +- Reduza grandes saídas de ferramentas nos seus fluxos de trabalho. +- Diminua `agents.defaults.imageMaxDimensionPx` para sessões com muitas capturas de tela. - Mantenha descrições de Skills curtas (a lista de Skills é injetada no prompt). - Prefira modelos menores para trabalho exploratório e verboso. -Veja [Skills](/pt-BR/tools/skills) para a fórmula exata de overhead da lista de Skills. +Veja [Skills](/pt-BR/tools/skills) para a fórmula exata de sobrecarga da lista de Skills.