From 741e5b40899bda80f4b52968378ff7c662ce69af Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Mon, 20 Apr 2026 05:50:45 +0000 Subject: [PATCH] chore(i18n): refresh pt-BR translations --- docs/pt-BR/channels/telegram.md | 482 +++--- docs/pt-BR/concepts/qa-e2e-automation.md | 179 +- docs/pt-BR/gateway/configuration-reference.md | 1417 +++++++-------- docs/pt-BR/help/faq.md | 1542 ++++++++--------- docs/pt-BR/help/testing.md | 700 ++++---- docs/pt-BR/install/index.md | 104 +- docs/pt-BR/platforms/windows.md | 95 +- docs/pt-BR/start/setup.md | 104 +- docs/pt-BR/tools/browser.md | 466 ++--- 9 files changed, 2603 insertions(+), 2486 deletions(-) diff --git a/docs/pt-BR/channels/telegram.md b/docs/pt-BR/channels/telegram.md index e8c73ec09..f7a40c408 100644 --- a/docs/pt-BR/channels/telegram.md +++ b/docs/pt-BR/channels/telegram.md @@ -1,30 +1,30 @@ --- read_when: - - Trabalhando em recursos do Telegram ou webhooks -summary: Status de suporte do bot do Telegram, recursos e configuração + - Trabalhando em recursos do Telegram ou Webhooks +summary: Status do bot do Telegram, capacidades e configuração title: Telegram x-i18n: - generated_at: "2026-04-05T12:37:54Z" + generated_at: "2026-04-20T05:41:38Z" model: gpt-5.4 provider: openai - source_hash: 39fbf328375fbc5d08ec2e3eed58b19ee0afa102010ecbc02e074a310ced157e + source_hash: b9903fae98bca0c345aa86d5c29015539c375442524a34d26bd28181470b8477 source_path: channels/telegram.md workflow: 15 --- -# Telegram (Bot API) +# Telegram (API de Bot) -Status: pronto para produção para DMs de bot + grupos via grammY. Long polling é o modo padrão; o modo webhook é opcional. +Status: pronto para produção para DMs de bot + grupos via grammY. O modo padrão é long polling; o modo Webhook é opcional. - - A política padrão de DM para Telegram é `pairing`. + + A política padrão de DM para Telegram é pareamento. - + Diagnósticos entre canais e playbooks de reparo. - - Padrões completos de configuração de canal e exemplos. + + Padrões e exemplos completos de configuração de canal. @@ -34,7 +34,7 @@ Status: pronto para produção para DMs de bot + grupos via grammY. Long polling Abra o Telegram e converse com **@BotFather** (confirme que o identificador é exatamente `@BotFather`). - Execute `/newbot`, siga os prompts e salve o token. + Execute `/newbot`, siga as instruções e salve o token. @@ -53,7 +53,7 @@ Status: pronto para produção para DMs de bot + grupos via grammY. Long polling } ``` - Fallback por ambiente: `TELEGRAM_BOT_TOKEN=...` (somente conta padrão). + Fallback por variável de ambiente: `TELEGRAM_BOT_TOKEN=...` (apenas conta padrão). O Telegram **não** usa `openclaw channels login telegram`; configure o token em config/env e depois inicie o gateway. @@ -66,31 +66,31 @@ openclaw pairing list telegram openclaw pairing approve telegram ``` - Códigos de pareamento expiram após 1 hora. + Os códigos de pareamento expiram após 1 hora. - Adicione o bot ao seu grupo e depois defina `channels.telegram.groups` e `groupPolicy` para corresponder ao seu modelo de acesso. + Adicione o bot ao seu grupo e depois ajuste `channels.telegram.groups` e `groupPolicy` para corresponder ao seu modelo de acesso. -A ordem de resolução do token reconhece contas. Na prática, valores em configuração vencem o fallback por ambiente, e `TELEGRAM_BOT_TOKEN` se aplica somente à conta padrão. +A ordem de resolução do token é sensível à conta. Na prática, os valores da config têm prioridade sobre o fallback por variável de ambiente, e `TELEGRAM_BOT_TOKEN` se aplica apenas à conta padrão. -## Configurações do lado do Telegram +## Configurações no lado do Telegram Bots do Telegram usam **Modo de Privacidade** por padrão, o que limita quais mensagens de grupo eles recebem. - Se o bot precisar ver todas as mensagens do grupo, faça um destes: + Se o bot precisar ver todas as mensagens do grupo, faça uma destas opções: - desative o modo de privacidade via `/setprivacy`, ou - - torne o bot um administrador do grupo. + - torne o bot administrador do grupo. - Ao alternar o modo de privacidade, remova + adicione novamente o bot em cada grupo para que o Telegram aplique a alteração. + Ao alternar o modo de privacidade, remova + readicione o bot em cada grupo para que o Telegram aplique a mudança. @@ -103,8 +103,8 @@ A ordem de resolução do token reconhece contas. Na prática, valores em config - - `/setjoingroups` para permitir/negar adições a grupos - - `/setprivacy` para comportamento de visibilidade em grupos + - `/setjoingroups` para permitir/negar adição a grupos + - `/setprivacy` para o comportamento de visibilidade em grupos @@ -113,24 +113,24 @@ A ordem de resolução do token reconhece contas. Na prática, valores em config - `channels.telegram.dmPolicy` controla o acesso a mensagens diretas: + `channels.telegram.dmPolicy` controla o acesso por mensagem direta: - `pairing` (padrão) - `allowlist` (exige pelo menos um ID de remetente em `allowFrom`) - `open` (exige que `allowFrom` inclua `"*"`) - `disabled` - `channels.telegram.allowFrom` aceita IDs numéricos de usuário do Telegram. Prefixos `telegram:` / `tg:` são aceitos e normalizados. + `channels.telegram.allowFrom` aceita IDs numéricos de usuários do Telegram. Prefixos `telegram:` / `tg:` são aceitos e normalizados. `dmPolicy: "allowlist"` com `allowFrom` vazio bloqueia todas as DMs e é rejeitado pela validação de configuração. - O onboarding aceita entrada `@username` e a resolve para IDs numéricos. - Se você atualizou e sua configuração contém entradas `@username` na allowlist, execute `openclaw doctor --fix` para resolvê-las (best-effort; requer um token de bot do Telegram). - Se você antes dependia de arquivos de allowlist do pairing store, `openclaw doctor --fix` pode recuperar entradas para `channels.telegram.allowFrom` em fluxos de allowlist (por exemplo quando `dmPolicy: "allowlist"` ainda não tem IDs explícitos). + A configuração solicita apenas IDs numéricos de usuário. + Se você atualizou e sua config contém entradas `@username` na allowlist, execute `openclaw doctor --fix` para resolvê-las (melhor esforço; exige um token de bot do Telegram). + Se você antes dependia de arquivos de allowlist do armazenamento de pareamento, `openclaw doctor --fix` pode recuperar entradas para `channels.telegram.allowFrom` em fluxos de allowlist (por exemplo, quando `dmPolicy: "allowlist"` ainda não tem IDs explícitos). - Para bots com um único dono, prefira `dmPolicy: "allowlist"` com IDs numéricos explícitos em `allowFrom` para manter a política de acesso durável na configuração (em vez de depender de aprovações de pareamento anteriores). + Para bots de um único proprietário, prefira `dmPolicy: "allowlist"` com IDs numéricos explícitos em `allowFrom` para manter a política de acesso persistente na config (em vez de depender de aprovações de pareamento anteriores). - Confusão comum: aprovação de pareamento por DM não significa "este remetente está autorizado em todo lugar". - O pareamento concede acesso por DM apenas. A autorização de remetente em grupos continua vindo de allowlists explícitas na configuração. - Se você quer "estou autorizado uma vez e tanto DMs quanto comandos em grupo funcionam", coloque seu ID numérico de usuário do Telegram em `channels.telegram.allowFrom`. + Confusão comum: a aprovação de pareamento de DM não significa “este remetente está autorizado em todos os lugares”. + O pareamento concede acesso apenas a DM. A autorização de remetente em grupos ainda vem de allowlists explícitas na config. + Se você quer “estou autorizado uma vez e tanto DMs quanto comandos em grupo funcionam”, coloque seu ID numérico de usuário do Telegram em `channels.telegram.allowFrom`. ### Encontrando seu ID de usuário do Telegram @@ -140,7 +140,7 @@ A ordem de resolução do token reconhece contas. Na prática, valores em config 2. Execute `openclaw logs --follow`. 3. Leia `from.id`. - Método oficial da Bot API: + Método oficial da API de Bot: ```bash curl "https://api.telegram.org/bot/getUpdates" @@ -151,28 +151,28 @@ curl "https://api.telegram.org/bot/getUpdates" - Dois controles se aplicam juntos: + Dois controles se aplicam em conjunto: 1. **Quais grupos são permitidos** (`channels.telegram.groups`) - sem configuração de `groups`: - com `groupPolicy: "open"`: qualquer grupo pode passar nas verificações de ID de grupo - - com `groupPolicy: "allowlist"` (padrão): grupos são bloqueados até você adicionar entradas em `groups` (ou `"*"`) - - `groups` configurado: funciona como allowlist (IDs explícitos ou `"*"`) + - com `groupPolicy: "allowlist"` (padrão): grupos são bloqueados até que você adicione entradas em `groups` (ou `"*"`) + - `groups` configurado: atua como allowlist (IDs explícitos ou `"*"`) 2. **Quais remetentes são permitidos em grupos** (`channels.telegram.groupPolicy`) - `open` - `allowlist` (padrão) - `disabled` - `groupAllowFrom` é usado para filtragem de remetentes em grupo. Se não estiver definido, o Telegram recai para `allowFrom`. - Entradas de `groupAllowFrom` devem ser IDs numéricos de usuário do Telegram (prefixos `telegram:` / `tg:` são normalizados). - Não coloque IDs de chat de grupo ou supergrupo do Telegram em `groupAllowFrom`. IDs de chat negativos pertencem a `channels.telegram.groups`. + `groupAllowFrom` é usado para filtragem de remetentes em grupos. Se não estiver definido, o Telegram usa `allowFrom` como fallback. + As entradas de `groupAllowFrom` devem ser IDs numéricos de usuários do Telegram (prefixos `telegram:` / `tg:` são normalizados). + Não coloque IDs de chat de grupo ou supergrupo do Telegram em `groupAllowFrom`. IDs negativos de chat pertencem a `channels.telegram.groups`. Entradas não numéricas são ignoradas para autorização de remetente. - Limite de segurança (`2026.2.25+`): autorização de remetente em grupo **não** herda aprovações do pairing store de DM. + Limite de segurança (`2026.2.25+`): a autenticação de remetente em grupo **não** herda aprovações do armazenamento de pareamento de DM. O pareamento continua sendo apenas para DM. Para grupos, defina `groupAllowFrom` ou `allowFrom` por grupo/por tópico. - Se `groupAllowFrom` não estiver definido, o Telegram recai para `allowFrom` da configuração, não para o pairing store. - Padrão prático para bots com um único dono: defina seu ID de usuário em `channels.telegram.allowFrom`, deixe `groupAllowFrom` indefinido e permita os grupos-alvo em `channels.telegram.groups`. - Observação de runtime: se `channels.telegram` estiver completamente ausente, o runtime assume por padrão `groupPolicy="allowlist"` em fail-closed, a menos que `channels.defaults.groupPolicy` esteja definido explicitamente. + Se `groupAllowFrom` não estiver definido, o Telegram usa `allowFrom` da config como fallback, não o armazenamento de pareamento. + Padrão prático para bots de um único proprietário: defina seu ID de usuário em `channels.telegram.allowFrom`, deixe `groupAllowFrom` sem definir e permita os grupos de destino em `channels.telegram.groups`. + Observação de runtime: se `channels.telegram` estiver completamente ausente, o runtime usa por padrão `groupPolicy="allowlist"` com fail-closed, a menos que `channels.defaults.groupPolicy` esteja definido explicitamente. Exemplo: permitir qualquer membro em um grupo específico: @@ -213,7 +213,7 @@ curl "https://api.telegram.org/bot/getUpdates" - Coloque IDs negativos de grupo ou supergrupo do Telegram como `-1001234567890` em `channels.telegram.groups`. - Coloque IDs de usuário do Telegram como `8734062810` em `groupAllowFrom` quando quiser limitar quais pessoas dentro de um grupo permitido podem acionar o bot. - - Use `groupAllowFrom: ["*"]` somente quando quiser que qualquer membro de um grupo permitido possa falar com o bot. + - Use `groupAllowFrom: ["*"]` apenas quando quiser que qualquer membro de um grupo permitido possa falar com o bot. @@ -228,12 +228,12 @@ curl "https://api.telegram.org/bot/getUpdates" - `agents.list[].groupChat.mentionPatterns` - `messages.groupChat.mentionPatterns` - Alternâncias por comando no nível da sessão: + Alternâncias de comando em nível de sessão: - `/activation always` - `/activation mention` - Elas atualizam apenas o estado da sessão. Use configuração para persistência. + Elas atualizam apenas o estado da sessão. Use a config para persistência. Exemplo de configuração persistente: @@ -249,24 +249,24 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Obtendo o ID do chat em grupo: + Obtendo o ID do chat de grupo: - - encaminhe uma mensagem de grupo para `@userinfobot` / `@getidsbot` + - encaminhe uma mensagem do grupo para `@userinfobot` / `@getidsbot` - ou leia `chat.id` em `openclaw logs --follow` - - ou inspecione `getUpdates` da Bot API + - ou inspecione `getUpdates` da API de Bot ## Comportamento em runtime -- O Telegram é gerenciado pelo processo do gateway. +- O Telegram é controlado pelo processo do gateway. - O roteamento é determinístico: respostas recebidas do Telegram voltam para o Telegram (o modelo não escolhe canais). -- Mensagens de entrada são normalizadas para o envelope compartilhado de canal com metadados de resposta e placeholders de mídia. -- Sessões de grupo são isoladas por ID do grupo. Tópicos de fórum acrescentam `:topic:` para manter os tópicos isolados. -- Mensagens de DM podem carregar `message_thread_id`; o OpenClaw as roteia com chaves de sessão cientes da thread e preserva o ID da thread nas respostas. -- O long polling usa grammY runner com sequenciamento por chat/por thread. A concorrência geral do runner sink usa `agents.defaults.maxConcurrent`. -- A Telegram Bot API não oferece suporte a confirmação de leitura (`sendReadReceipts` não se aplica). +- Mensagens recebidas são normalizadas no envelope compartilhado de canal com metadados de resposta e placeholders de mídia. +- Sessões de grupo são isoladas por ID de grupo. Tópicos de fórum adicionam `:topic:` para manter os tópicos isolados. +- Mensagens de DM podem carregar `message_thread_id`; o OpenClaw as roteia com chaves de sessão sensíveis a thread e preserva o ID da thread para as respostas. +- O long polling usa o runner do grammY com sequenciamento por chat/por thread. A concorrência geral do sink do runner usa `agents.defaults.maxConcurrent`. +- A API de Bot do Telegram não tem suporte a confirmação de leitura (`sendReadReceipts` não se aplica). ## Referência de recursos @@ -281,34 +281,34 @@ curl "https://api.telegram.org/bot/getUpdates" - `channels.telegram.streaming` é `off | partial | block | progress` (padrão: `partial`) - `progress` é mapeado para `partial` no Telegram (compatibilidade com nomenclatura entre canais) - - valores legados booleanos de `channels.telegram.streamMode` e `streaming` são mapeados automaticamente + - valores legados `channels.telegram.streamMode` e booleanos `streaming` são mapeados automaticamente - Para respostas somente de texto: + Para respostas apenas de texto: - DM: o OpenClaw mantém a mesma mensagem de prévia e faz uma edição final no lugar (sem segunda mensagem) - grupo/tópico: o OpenClaw mantém a mesma mensagem de prévia e faz uma edição final no lugar (sem segunda mensagem) - Para respostas complexas (por exemplo payloads de mídia), o OpenClaw recai para a entrega final normal e depois limpa a mensagem de prévia. + Para respostas complexas (por exemplo, payloads de mídia), o OpenClaw usa fallback para a entrega final normal e depois limpa a mensagem de prévia. O streaming de prévia é separado do block streaming. Quando o block streaming é ativado explicitamente para Telegram, o OpenClaw ignora o stream de prévia para evitar streaming duplo. - Se o transporte nativo de rascunho estiver indisponível/for rejeitado, o OpenClaw recai automaticamente para `sendMessage` + `editMessageText`. + Se o transporte nativo de rascunho não estiver disponível/for rejeitado, o OpenClaw usa automaticamente `sendMessage` + `editMessageText`. - Stream de raciocínio somente do Telegram: + Stream de raciocínio somente para Telegram: - - `/reasoning stream` envia o raciocínio para a prévia ao vivo durante a geração + - `/reasoning stream` envia o raciocínio para a prévia ao vivo enquanto gera - a resposta final é enviada sem o texto de raciocínio - O texto de saída usa `parse_mode: "HTML"` do Telegram. + O texto de saída usa Telegram `parse_mode: "HTML"`. - - Texto em estilo Markdown é renderizado em HTML seguro para Telegram. - - HTML bruto do modelo é escapado para reduzir falhas de parse do Telegram. - - Se o Telegram rejeitar o HTML parseado, o OpenClaw tenta novamente como texto simples. + - Texto no estilo Markdown é renderizado como HTML seguro para Telegram. + - HTML bruto do modelo é escapado para reduzir falhas de parsing no Telegram. + - Se o Telegram rejeitar o HTML processado, o OpenClaw tenta novamente como texto simples. - Prévias de link são ativadas por padrão e podem ser desativadas com `channels.telegram.linkPreview: false`. + As prévias de links ficam ativadas por padrão e podem ser desativadas com `channels.telegram.linkPreview: false`. @@ -317,17 +317,17 @@ curl "https://api.telegram.org/bot/getUpdates" Padrões de comandos nativos: - - `commands.native: "auto"` ativa comandos nativos para o Telegram + - `commands.native: "auto"` ativa comandos nativos para Telegram - Adicione entradas personalizadas ao menu de comandos: + Adicione entradas de menu de comando personalizado: ```json5 { channels: { telegram: { customCommands: [ - { command: "backup", description: "Git backup" }, - { command: "generate", description: "Create an image" }, + { command: "backup", description: "Backup do Git" }, + { command: "generate", description: "Criar uma imagem" }, ], }, }, @@ -336,40 +336,40 @@ curl "https://api.telegram.org/bot/getUpdates" Regras: - - nomes são normalizados (remove `/` inicial, minúsculas) + - os nomes são normalizados (remover `/` inicial, minúsculas) - padrão válido: `a-z`, `0-9`, `_`, comprimento `1..32` - - comandos personalizados não podem substituir comandos nativos + - comandos personalizados não podem sobrescrever comandos nativos - conflitos/duplicatas são ignorados e registrados em log Observações: - comandos personalizados são apenas entradas de menu; eles não implementam comportamento automaticamente - - comandos de plugin/Skills ainda podem funcionar quando digitados, mesmo que não apareçam no menu do Telegram + - comandos de Plugin/Skills ainda podem funcionar quando digitados, mesmo que não apareçam no menu do Telegram - Se os comandos nativos estiverem desativados, os comandos integrados serão removidos. Comandos personalizados/de plugin ainda podem ser registrados se configurados. + Se os comandos nativos estiverem desativados, os embutidos serão removidos. Comandos personalizados/de Plugin ainda podem ser registrados se configurados. Falhas comuns de configuração: - - `setMyCommands failed` com `BOT_COMMANDS_TOO_MUCH` significa que o menu do Telegram ainda excedeu o limite após o corte; reduza comandos personalizados/de plugin/Skills ou desative `channels.telegram.commands.native`. - - `setMyCommands failed` com erros de rede/fetch normalmente significa que o DNS/HTTPS de saída para `api.telegram.org` está bloqueado. + - `setMyCommands failed` com `BOT_COMMANDS_TOO_MUCH` significa que o menu do Telegram ainda excedeu o limite após o corte; reduza comandos de Plugin/Skills/personalizados ou desative `channels.telegram.commands.native`. + - `setMyCommands failed` com erros de rede/fetch normalmente significa que DNS/HTTPS de saída para `api.telegram.org` está bloqueado. - ### Comandos de pareamento de dispositivo (plugin `device-pair`) + ### Comandos de pareamento de dispositivo (Plugin `device-pair`) - Quando o plugin `device-pair` estiver instalado: + Quando o Plugin `device-pair` está instalado: 1. `/pair` gera um código de configuração 2. cole o código no app iOS - 3. `/pair pending` lista solicitações pendentes (incluindo papel/escopos) + 3. `/pair pending` lista solicitações pendentes (incluindo função/escopos) 4. aprove a solicitação: - `/pair approve ` para aprovação explícita - `/pair approve` quando houver apenas uma solicitação pendente - `/pair approve latest` para a mais recente - O código de configuração carrega um token bootstrap de curta duração. O handoff bootstrap integrado mantém o token principal do nó em `scopes: []`; qualquer token de operador transferido continua limitado a `operator.approvals`, `operator.read`, `operator.talk.secrets` e `operator.write`. As verificações de escopo do bootstrap têm prefixo de papel, então essa allowlist de operador só satisfaz solicitações de operador; papéis que não sejam de operador ainda precisam de escopos sob o prefixo do próprio papel. + O código de configuração carrega um token de bootstrap de curta duração. A transferência de bootstrap embutida mantém o token do Node primário em `scopes: []`; qualquer token de operador transferido permanece limitado a `operator.approvals`, `operator.read`, `operator.talk.secrets` e `operator.write`. As verificações de escopo de bootstrap usam prefixo de função, então essa allowlist de operador atende apenas solicitações de operador; funções que não sejam de operador ainda precisam de escopos sob seu próprio prefixo de função. - Se um dispositivo tentar novamente com detalhes de autenticação alterados (por exemplo papel/escopos/chave pública), a solicitação pendente anterior é substituída, e a nova solicitação usa um `requestId` diferente. Execute `/pair pending` novamente antes de aprovar. + Se um dispositivo tentar novamente com detalhes de autenticação alterados (por exemplo, função/escopos/chave pública), a solicitação pendente anterior será substituída e a nova solicitação usará um `requestId` diferente. Execute `/pair pending` novamente antes de aprovar. - Mais detalhes: [Pareamento](/channels/pairing#pair-via-telegram-recommended-for-ios). + Mais detalhes: [Pareamento](/pt-BR/channels/pairing#pair-via-telegram-recommended-for-ios). @@ -414,7 +414,7 @@ curl "https://api.telegram.org/bot/getUpdates" - `all` - `allowlist` (padrão) - Legado `capabilities: ["inlineButtons"]` é mapeado para `inlineButtons: "all"`. + O legado `capabilities: ["inlineButtons"]` é mapeado para `inlineButtons: "all"`. Exemplo de ação de mensagem: @@ -434,33 +434,33 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Cliques de callback são passados ao agente como texto: + Cliques em callback são passados ao agente como texto: `callback_data: ` - As ações da ferramenta do Telegram incluem: + As ações de ferramenta do Telegram incluem: - - `sendMessage` (`to`, `content`, `mediaUrl`, `replyToMessageId`, `messageThreadId` opcionais) + - `sendMessage` (`to`, `content`, opcional `mediaUrl`, `replyToMessageId`, `messageThreadId`) - `react` (`chatId`, `messageId`, `emoji`) - `deleteMessage` (`chatId`, `messageId`) - `editMessage` (`chatId`, `messageId`, `content`) - - `createForumTopic` (`chatId`, `name`, `iconColor`, `iconCustomEmojiId` opcionais) + - `createForumTopic` (`chatId`, `name`, opcional `iconColor`, `iconCustomEmojiId`) - Ações de mensagem de canal expõem aliases ergonômicos (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`). + As ações de mensagem do canal expõem aliases ergonômicos (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`). - Controles de bloqueio: + Controles de gate: - `channels.telegram.actions.sendMessage` - `channels.telegram.actions.deleteMessage` - `channels.telegram.actions.reactions` - `channels.telegram.actions.sticker` (padrão: desativado) - Observação: `edit` e `topic-create` estão atualmente ativados por padrão e não têm alternâncias `channels.telegram.actions.*` separadas. - Envios em runtime usam o snapshot ativo de config/secrets (inicialização/reload), então caminhos de ação não fazem uma nova resolução ad hoc de SecretRef por envio. + Observação: `edit` e `topic-create` estão atualmente ativados por padrão e não têm alternâncias separadas em `channels.telegram.actions.*`. + Os envios em runtime usam o snapshot ativo de config/segredos (inicialização/reload), então os caminhos de ação não fazem nova resolução ad hoc de SecretRef a cada envio. - Semântica de remoção de reação: [/tools/reactions](/tools/reactions) + Semântica de remoção de reação: [/tools/reactions](/pt-BR/tools/reactions) @@ -481,11 +481,11 @@ curl "https://api.telegram.org/bot/getUpdates" - Supergrupos com fórum: + Supergrupos de fórum: - - chaves de sessão de tópico acrescentam `:topic:` - - respostas e digitação têm como alvo a thread do tópico - - caminho de configuração do tópico: + - chaves de sessão de tópico adicionam `:topic:` + - respostas e indicadores de digitação têm como destino a thread do tópico + - caminho de config do tópico: `channels.telegram.groups..topics.` Caso especial do tópico geral (`threadId=1`): @@ -493,10 +493,10 @@ curl "https://api.telegram.org/bot/getUpdates" - envios de mensagem omitem `message_thread_id` (o Telegram rejeita `sendMessage(...thread_id=1)`) - ações de digitação ainda incluem `message_thread_id` - Herança de tópico: entradas de tópico herdam configurações do grupo, salvo substituição (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`). - `agentId` é somente de tópico e não é herdado dos padrões de grupo. + Herança de tópico: entradas de tópico herdam configurações do grupo, a menos que sejam substituídas (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`). + `agentId` é exclusivo de tópico e não herda dos padrões do grupo. - **Roteamento de agente por tópico**: cada tópico pode rotear para um agente diferente definindo `agentId` na configuração do tópico. Isso dá a cada tópico seu próprio workspace, memória e sessão isolados. Exemplo: + **Roteamento de agente por tópico**: cada tópico pode rotear para um agente diferente definindo `agentId` na config do tópico. Isso dá a cada tópico seu próprio workspace, memória e sessão isolados. Exemplo: ```json5 { @@ -505,8 +505,8 @@ curl "https://api.telegram.org/bot/getUpdates" groups: { "-1001234567890": { topics: { - "1": { agentId: "main" }, // Tópico Geral → agente main - "3": { agentId: "zu" }, // Tópico Dev → agente zu + "1": { agentId: "main" }, // Tópico geral → agente principal + "3": { agentId: "zu" }, // Tópico de desenvolvimento → agente zu "5": { agentId: "coder" } // Revisão de código → agente coder } } @@ -518,7 +518,7 @@ curl "https://api.telegram.org/bot/getUpdates" Cada tópico então tem sua própria chave de sessão: `agent:zu:telegram:group:-1001234567890:topic:3` - **Binding persistente de tópico ACP**: tópicos de fórum podem fixar sessões do harness ACP por meio de bindings ACP tipados de nível superior: + **Vinculação persistente de tópico ACP**: tópicos de fórum podem fixar sessões de harness ACP por meio de bindings ACP tipados de nível superior: - `bindings[]` com `type: "acp"` e `match.channel: "telegram"` @@ -569,13 +569,13 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Isso atualmente está limitado a tópicos de fórum em grupos e supergrupos. + Atualmente, isso está limitado a tópicos de fórum em grupos e supergrupos. - **Spawn ACP vinculado à thread a partir do chat**: + **Criação de ACP vinculado à thread a partir do chat**: - `/acp spawn --thread here|auto` pode vincular o tópico atual do Telegram a uma nova sessão ACP. - - Mensagens subsequentes do tópico são roteadas diretamente para a sessão ACP vinculada (sem necessidade de `/acp steer`). - - O OpenClaw fixa a mensagem de confirmação do spawn dentro do tópico após um vínculo bem-sucedido. + - Mensagens subsequentes no tópico são roteadas diretamente para a sessão ACP vinculada (sem necessidade de `/acp steer`). + - O OpenClaw fixa a mensagem de confirmação de criação dentro do tópico após uma vinculação bem-sucedida. - Requer `channels.telegram.threadBindings.spawnAcpSessions=true`. O contexto do template inclui: @@ -585,14 +585,14 @@ curl "https://api.telegram.org/bot/getUpdates" Comportamento de thread em DM: - - chats privados com `message_thread_id` mantêm o roteamento de DM, mas usam chaves de sessão/alvos de resposta cientes da thread. + - chats privados com `message_thread_id` mantêm o roteamento de DM, mas usam chaves de sessão e destinos de resposta sensíveis a thread. ### Mensagens de áudio - O Telegram distingue notas de voz de arquivos de áudio. + O Telegram diferencia notas de voz de arquivos de áudio. - padrão: comportamento de arquivo de áudio - tag `[[audio_as_voice]]` na resposta do agente para forçar envio como nota de voz @@ -611,7 +611,7 @@ curl "https://api.telegram.org/bot/getUpdates" ### Mensagens de vídeo - O Telegram distingue arquivos de vídeo de video notes. + O Telegram diferencia arquivos de vídeo de notas de vídeo. Exemplo de ação de mensagem: @@ -625,15 +625,15 @@ curl "https://api.telegram.org/bot/getUpdates" } ``` - Video notes não oferecem suporte a legendas; o texto de mensagem fornecido é enviado separadamente. + Notas de vídeo não suportam legendas; o texto de mensagem fornecido é enviado separadamente. ### Stickers - Tratamento de sticker de entrada: + Tratamento de stickers recebidos: - WEBP estático: baixado e processado (placeholder ``) - TGS animado: ignorado - - WEBM de vídeo: ignorado + - WEBM em vídeo: ignorado Campos de contexto de sticker: @@ -647,7 +647,7 @@ curl "https://api.telegram.org/bot/getUpdates" - `~/.openclaw/telegram/sticker-cache.json` - Stickers são descritos uma vez (quando possível) e armazenados em cache para reduzir chamadas repetidas de visão. + Os stickers são descritos uma vez (quando possível) e armazenados em cache para reduzir chamadas repetidas de visão. Ative ações de sticker: @@ -694,47 +694,47 @@ curl "https://api.telegram.org/bot/getUpdates" - `Telegram reaction added: 👍 by Alice (@alice) on msg 42` - Configuração: + Config: - `channels.telegram.reactionNotifications`: `off | own | all` (padrão: `own`) - `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` (padrão: `minimal`) Observações: - - `own` significa apenas reações de usuário a mensagens enviadas pelo bot (best-effort via cache de mensagens enviadas). + - `own` significa apenas reações de usuários a mensagens enviadas pelo bot (melhor esforço via cache de mensagens enviadas). - Eventos de reação ainda respeitam os controles de acesso do Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); remetentes não autorizados são descartados. - O Telegram não fornece IDs de thread em atualizações de reação. - - grupos sem fórum roteiam para a sessão do chat em grupo - - grupos com fórum roteiam para a sessão do tópico geral do grupo (`:topic:1`), não para o tópico exato de origem + - grupos sem fórum são roteados para a sessão de chat do grupo + - grupos com fórum são roteados para a sessão do tópico geral do grupo (`:topic:1`), não para o tópico de origem exato - `allowed_updates` para polling/webhook inclui `message_reaction` automaticamente. + `allowed_updates` para polling/Webhook inclui `message_reaction` automaticamente. - `ackReaction` envia um emoji de confirmação enquanto o OpenClaw processa uma mensagem de entrada. + `ackReaction` envia um emoji de confirmação enquanto o OpenClaw está processando uma mensagem recebida. Ordem de resolução: - `channels.telegram.accounts..ackReaction` - `channels.telegram.ackReaction` - `messages.ackReaction` - - fallback para emoji de identidade do agente (`agents.list[].identity.emoji`, senão "👀") + - fallback para emoji de identidade do agente (`agents.list[].identity.emoji`, caso contrário "👀") Observações: - O Telegram espera emoji unicode (por exemplo "👀"). - - Use `""` para desativar a reação para um canal ou conta. + - Use `""` para desativar a reação em um canal ou conta. - Gravações de configuração do canal são ativadas por padrão (`configWrites !== false`). + Gravações de config do canal ficam ativadas por padrão (`configWrites !== false`). - Gravações acionadas pelo Telegram incluem: + As gravações acionadas pelo Telegram incluem: - eventos de migração de grupo (`migrate_to_chat_id`) para atualizar `channels.telegram.groups` - - `/config set` e `/config unset` (requer ativação de comando) + - `/config set` e `/config unset` (exige ativação de comando) Desative: @@ -750,10 +750,10 @@ curl "https://api.telegram.org/bot/getUpdates" - + Padrão: long polling. - Modo webhook: + Modo Webhook: - defina `channels.telegram.webhookUrl` - defina `channels.telegram.webhookSecret` (obrigatório quando `webhookUrl` estiver definido) @@ -761,34 +761,34 @@ curl "https://api.telegram.org/bot/getUpdates" - `channels.telegram.webhookHost` opcional (padrão `127.0.0.1`) - `channels.telegram.webhookPort` opcional (padrão `8787`) - O listener local padrão para o modo webhook é vinculado a `127.0.0.1:8787`. + O listener local padrão para o modo Webhook faz bind em `127.0.0.1:8787`. Se seu endpoint público for diferente, coloque um proxy reverso na frente e aponte `webhookUrl` para a URL pública. Defina `webhookHost` (por exemplo `0.0.0.0`) quando você intencionalmente precisar de entrada externa. - + - o padrão de `channels.telegram.textChunkLimit` é 4000. - - `channels.telegram.chunkMode="newline"` prefere limites de parágrafo (linhas em branco) antes da divisão por comprimento. - - `channels.telegram.mediaMaxMb` (padrão 100) limita o tamanho de mídia de entrada e saída do Telegram. - - `channels.telegram.timeoutSeconds` substitui o timeout do cliente da API do Telegram (se não definido, o padrão do grammY se aplica). + - `channels.telegram.chunkMode="newline"` prefere limites de parágrafo (linhas em branco) antes da divisão por tamanho. + - `channels.telegram.mediaMaxMb` (padrão 100) limita o tamanho de mídia recebida e enviada no Telegram. + - `channels.telegram.timeoutSeconds` substitui o tempo limite do cliente da API do Telegram (se não definido, aplica-se o padrão do grammY). - o histórico de contexto de grupo usa `channels.telegram.historyLimit` ou `messages.groupChat.historyLimit` (padrão 50); `0` desativa. - - o contexto suplementar de resposta/citação/encaminhamento atualmente é repassado como recebido. + - o contexto suplementar de resposta/citação/encaminhamento atualmente é repassado conforme recebido. - as allowlists do Telegram controlam principalmente quem pode acionar o agente, não um limite completo de redação de contexto suplementar. - controles de histórico de DM: - `channels.telegram.dmHistoryLimit` - `channels.telegram.dms[""].historyLimit` - - a configuração `channels.telegram.retry` se aplica aos helpers de envio do Telegram (CLI/tools/actions) para erros recuperáveis de API de saída. + - a config `channels.telegram.retry` se aplica aos helpers de envio do Telegram (CLI/ferramentas/ações) para erros recuperáveis de saída da API. - O alvo de envio da CLI pode ser ID numérico de chat ou username: + O destino de envio da CLI pode ser um ID numérico de chat ou um nome de usuário: ```bash openclaw message send --channel telegram --target 123456789 --message "hi" openclaw message send --channel telegram --target @name --message "hi" ``` - Enquetes do Telegram usam `openclaw message poll` e oferecem suporte a tópicos de fórum: + As enquetes do Telegram usam `openclaw message poll` e oferecem suporte a tópicos de fórum: ```bash openclaw message poll --channel telegram --target 123456789 \ @@ -798,78 +798,79 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \ --poll-duration-seconds 300 --poll-public ``` - Flags de enquete somente do Telegram: + Flags de enquete exclusivas do Telegram: - `--poll-duration-seconds` (5-600) - `--poll-anonymous` - `--poll-public` - - `--thread-id` para tópicos de fórum (ou use um alvo `:topic:`) + - `--thread-id` para tópicos de fórum (ou use um destino `:topic:`) O envio no Telegram também oferece suporte a: - `--buttons` para teclados inline quando `channels.telegram.capabilities.inlineButtons` permitir - - `--force-document` para enviar imagens e GIFs de saída como documentos em vez de upload comprimido de foto ou mídia animada + - `--force-document` para enviar imagens e GIFs de saída como documentos em vez de uploads compactados de foto ou mídia animada - Bloqueio de ações: + Controle de ações: - `channels.telegram.actions.sendMessage=false` desativa mensagens de saída do Telegram, incluindo enquetes - - `channels.telegram.actions.poll=false` desativa a criação de enquete no Telegram enquanto mantém envios regulares ativados + - `channels.telegram.actions.poll=false` desativa a criação de enquetes no Telegram, mantendo os envios regulares ativados - O Telegram oferece suporte a aprovações de exec em DMs de aprovadores e pode opcionalmente publicar prompts de aprovação no chat ou tópico de origem. + O Telegram oferece suporte a aprovações de exec em DMs de aprovadores e pode, opcionalmente, publicar prompts de aprovação no chat ou tópico de origem. - Caminho de configuração: + Caminho de config: - `channels.telegram.execApprovals.enabled` - - `channels.telegram.execApprovals.approvers` (opcional; recai para IDs numéricos de dono inferidos de `allowFrom` e `defaultTo` direto quando possível) + - `channels.telegram.execApprovals.approvers` (opcional; usa como fallback IDs numéricos de proprietário inferidos de `allowFrom` e `defaultTo` direto quando possível) - `channels.telegram.execApprovals.target` (`dm` | `channel` | `both`, padrão: `dm`) - `agentFilter`, `sessionFilter` - Os aprovadores devem ser IDs numéricos de usuário do Telegram. O Telegram ativa automaticamente aprovações nativas de exec quando `enabled` não está definido ou é `"auto"` e pelo menos um aprovador pode ser resolvido, seja a partir de `execApprovals.approvers` ou da configuração numérica de dono da conta (`allowFrom` e `defaultTo` de mensagem direta). Defina `enabled: false` para desativar explicitamente o Telegram 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 fallback de aprovação de exec. + Os aprovadores devem ser IDs numéricos de usuários do Telegram. O Telegram ativa automaticamente aprovações nativas de exec quando `enabled` não está definido ou é `"auto"` e pelo menos um aprovador pode ser resolvido, seja a partir de `execApprovals.approvers` ou da config numérica de proprietário da conta (`allowFrom` e `defaultTo` de mensagem direta). Defina `enabled: false` para desativar explicitamente o Telegram como cliente nativo de aprovação. Caso contrário, as solicitações de aprovação usam fallback para outras rotas de aprovação configuradas ou para a política de fallback de aprovação de exec. - O Telegram também renderiza os botões compartilhados de aprovação usados por outros canais de chat. O adaptador nativo do Telegram adiciona principalmente roteamento de DM para aprovadores, fanout para canal/tópico e indicações de digitação antes da entrega. - Quando esses botões estiverem presentes, eles serão a UX principal de aprovação; o OpenClaw - só deve incluir um comando manual `/approve` quando o resultado da ferramenta disser - que aprovações por chat não estão disponíveis ou quando a aprovação manual for o único caminho. + O Telegram também renderiza os botões compartilhados de aprovação usados por outros canais de chat. O adaptador nativo do Telegram adiciona principalmente roteamento de DM de aprovador, fanout para canal/tópico e dicas de digitação antes da entrega. + Quando esses botões estão presentes, eles são a UX principal de aprovação; o OpenClaw + deve incluir um comando manual `/approve` apenas quando o resultado da ferramenta disser + que aprovações por chat não estão disponíveis ou que a aprovação manual é o único caminho. Regras de entrega: - - `target: "dm"` envia prompts de aprovação somente para DMs de aprovadores resolvidos + - `target: "dm"` envia prompts de aprovação apenas para DMs de aprovadores resolvidos - `target: "channel"` envia o prompt de volta para o chat/tópico de origem no Telegram - `target: "both"` envia para DMs de aprovadores e para o chat/tópico de origem - Somente aprovadores resolvidos podem aprovar ou negar. Não aprovadores não podem usar `/approve` e não podem usar botões de aprovação do Telegram. + Apenas aprovadores resolvidos podem aprovar ou negar. Não aprovadores não podem usar `/approve` nem usar botões de aprovação do Telegram. Comportamento de resolução de aprovação: - - IDs com prefixo `plugin:` sempre são resolvidos por aprovações de plugin. - - Outros IDs tentam `exec.approval.resolve` primeiro. - - Se o Telegram também estiver autorizado para aprovações de plugin e o gateway disser - que a aprovação de exec é desconhecida/expirada, o Telegram tenta novamente uma vez via + - IDs com prefixo `plugin:` sempre são resolvidos por aprovações de Plugin. + - Outros IDs de aprovação tentam primeiro `exec.approval.resolve`. + - Se o Telegram também estiver autorizado para aprovações de Plugin e o gateway disser + que a aprovação de exec é desconhecida/expirada, o Telegram tentará novamente uma vez por `plugin.approval.resolve`. - - Negativas/erros reais de aprovação de exec não recorrem silenciosamente à resolução de aprovação de plugin. + - Negativas/erros reais de aprovação de exec não passam silenciosamente para a resolução + de aprovação de Plugin. - A entrega no canal mostra o texto do comando no chat, então só ative `channel` ou `both` em grupos/tópicos confiáveis. Quando o prompt chega em um tópico de fórum, o OpenClaw preserva o tópico tanto para o prompt de aprovação quanto para o acompanhamento pós-aprovação. Aprovações de exec expiram após 30 minutos por padrão. + A entrega no canal mostra o texto do comando no chat, então ative `channel` ou `both` apenas em grupos/tópicos confiáveis. Quando o prompt chega em um tópico de fórum, o OpenClaw preserva o tópico tanto para o prompt de aprovação quanto para o acompanhamento pós-aprovação. As aprovações de exec expiram após 30 minutos por padrão. - Botões inline de aprovação também dependem de `channels.telegram.capabilities.inlineButtons` permitir a superfície alvo (`dm`, `group` ou `all`). + Botões inline de aprovação também dependem de `channels.telegram.capabilities.inlineButtons` permitir a superfície de destino (`dm`, `group` ou `all`). - Documentação relacionada: [Aprovações de exec](/tools/exec-approvals) + Documentação relacionada: [Aprovações de exec](/pt-BR/tools/exec-approvals) ## Controles de resposta de erro -Quando o agente encontra um erro de entrega ou de provedor, o Telegram pode responder com o texto do erro ou suprimi-lo. Duas chaves de configuração controlam esse comportamento: +Quando o agente encontra um erro de entrega ou do provedor, o Telegram pode responder com o texto do erro ou suprimi-lo. Duas chaves de config controlam esse comportamento: -| Chave | Valores | Padrão | Descrição | -| ----------------------------------- | ----------------- | ------- | ------------------------------------------------------------------------------------------------ | -| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` envia uma mensagem de erro amigável para o chat. `silent` suprime totalmente respostas de erro. | -| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | Tempo mínimo entre respostas de erro para o mesmo chat. Evita spam de erros durante indisponibilidades. | +| Key | Values | Default | Description | +| ----------------------------------- | ----------------- | ------- | ----------------------------------------------------------------------------------------------- | +| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` envia uma mensagem de erro amigável para o chat. `silent` suprime totalmente as respostas de erro. | +| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | Tempo mínimo entre respostas de erro para o mesmo chat. Evita spam de erros durante indisponibilidades. | -Substituições por conta, por grupo e por tópico são compatíveis (mesma herança das outras chaves de configuração do Telegram). +Substituições por conta, por grupo e por tópico são compatíveis (mesma herança das outras chaves de config do Telegram). ```json5 { @@ -879,7 +880,7 @@ Substituições por conta, por grupo e por tópico são compatíveis (mesma hera errorCooldownMs: 120000, groups: { "-1001234567890": { - errorPolicy: "silent", // suprimir erros neste grupo + errorPolicy: "silent", // suprime erros neste grupo }, }, }, @@ -892,19 +893,19 @@ Substituições por conta, por grupo e por tópico são compatíveis (mesma hera - - Se `requireMention=false`, o modo de privacidade do Telegram deve permitir visibilidade completa. + - Se `requireMention=false`, o modo de privacidade do Telegram deve permitir visibilidade total. - BotFather: `/setprivacy` -> Disable - - depois remova + adicione novamente o bot ao grupo - - `openclaw channels status` emite aviso quando a configuração espera mensagens de grupo sem menção. - - `openclaw channels status --probe` pode verificar IDs numéricos explícitos de grupo; o curinga `"*"` não pode ter associação verificada. + - depois remova + readicione o bot ao grupo + - `openclaw channels status` avisa quando a config espera mensagens de grupo sem menção. + - `openclaw channels status --probe` pode verificar IDs numéricos explícitos de grupo; o curinga `"*"` não pode ser verificado quanto à associação. - teste rápido de sessão: `/activation always`. - - quando `channels.telegram.groups` existe, o grupo precisa estar listado (ou incluir `"*"`) - - verifique se o bot é membro do grupo + - quando `channels.telegram.groups` existe, o grupo deve estar listado (ou incluir `"*"`) + - verifique a associação do bot ao grupo - revise os logs: `openclaw logs --follow` para motivos de ignorar @@ -912,18 +913,18 @@ Substituições por conta, por grupo e por tópico são compatíveis (mesma hera - autorize sua identidade de remetente (pareamento e/ou `allowFrom` numérico) - - a autorização de comandos ainda se aplica mesmo quando a política de grupo é `open` - - `setMyCommands failed` com `BOT_COMMANDS_TOO_MUCH` significa que o menu nativo tem entradas demais; reduza comandos personalizados/de plugin/Skills ou desative menus nativos - - `setMyCommands failed` com erros de rede/fetch normalmente indica problemas de alcance DNS/HTTPS para `api.telegram.org` + - a autorização de comando ainda se aplica mesmo quando a política de grupo é `open` + - `setMyCommands failed` com `BOT_COMMANDS_TOO_MUCH` significa que o menu nativo tem entradas demais; reduza comandos de Plugin/Skills/personalizados ou desative menus nativos + - `setMyCommands failed` com erros de rede/fetch normalmente indica problemas de alcance de DNS/HTTPS até `api.telegram.org` - - Node 22+ + fetch/proxy personalizado podem disparar comportamento de aborto imediato se os tipos de AbortSignal não forem compatíveis. - - Alguns hosts resolvem `api.telegram.org` para IPv6 primeiro; saída IPv6 quebrada pode causar falhas intermitentes na API do Telegram. + - Node 22+ + fetch/proxy personalizado pode disparar comportamento de aborto imediato se os tipos de AbortSignal não corresponderem. + - Alguns hosts resolvem `api.telegram.org` para IPv6 primeiro; saída IPv6 com problema pode causar falhas intermitentes da API do Telegram. - Se os logs incluírem `TypeError: fetch failed` ou `Network request for 'getUpdates' failed!`, o OpenClaw agora tenta novamente esses casos como erros de rede recuperáveis. - - Em hosts VPS com saída direta/TLS instável, encaminhe chamadas da API do Telegram por `channels.telegram.proxy`: + - Em hosts VPS com saída direta/TLS instável, roteie chamadas da API do Telegram por `channels.telegram.proxy`: ```yaml channels: @@ -931,7 +932,7 @@ channels: proxy: socks5://:@proxy-host:1080 ``` - - Node 22+ usa por padrão `autoSelectFamily=true` (exceto WSL2) e `dnsResultOrder=ipv4first`. + - Node 22+ usa por padrão `autoSelectFamily=true` (exceto no WSL2) e `dnsResultOrder=ipv4first`. - Se seu host for WSL2 ou funcionar explicitamente melhor com comportamento somente IPv4, force a seleção de família: ```yaml @@ -945,7 +946,7 @@ channels: por padrão para downloads de mídia do Telegram. Se um fake-IP confiável ou proxy transparente reescrever `api.telegram.org` para algum outro endereço privado/interno/de uso especial durante downloads de mídia, você pode - ativar o bypass somente do Telegram: + ativar o bypass exclusivo do Telegram: ```yaml channels: @@ -954,24 +955,25 @@ channels: dangerouslyAllowPrivateNetwork: true ``` - - A mesma ativação opcional também está disponível por conta em + - O mesmo opt-in está disponível por conta em `channels.telegram.accounts..network.dangerouslyAllowPrivateNetwork`. - - Se seu proxy resolver hosts de mídia do Telegram em `198.18.x.x`, deixe a - flag perigosa desativada primeiro. A mídia do Telegram já permite a faixa - de benchmark RFC 2544 por padrão. + - Se seu proxy resolver hosts de mídia do Telegram para `198.18.x.x`, deixe a + flag perigosa desativada primeiro. A mídia do Telegram já permite a faixa de + benchmark RFC 2544 por padrão. - `channels.telegram.network.dangerouslyAllowPrivateNetwork` enfraquece as - proteções SSRF de mídia do Telegram. Use isso apenas em ambientes de proxy - confiáveis e controlados pelo operador, como roteamento fake-IP do Clash, Mihomo ou Surge, quando eles sintetizarem respostas - privadas ou de uso especial fora da faixa de benchmark RFC 2544. Deixe isso desativado para acesso normal do Telegram pela internet pública. + `channels.telegram.network.dangerouslyAllowPrivateNetwork` enfraquece as proteções + SSRF de mídia do Telegram. Use isso apenas em ambientes de proxy confiáveis controlados pelo operador, + como roteamento fake-IP do Clash, Mihomo ou Surge, quando eles sintetizarem + respostas privadas ou de uso especial fora da faixa de benchmark RFC 2544. + Deixe isso desativado para acesso normal ao Telegram pela internet pública. - - Substituições por ambiente (temporárias): + - Substituições por variável de ambiente (temporárias): - `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1` - `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1` - `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first` - - Valide respostas DNS: + - Valide as respostas de DNS: ```bash dig +short api.telegram.org A @@ -981,97 +983,97 @@ dig +short api.telegram.org AAAA -Mais ajuda: [Solução de problemas de canais](/channels/troubleshooting). +Mais ajuda: [Solução de problemas do canal](/pt-BR/channels/troubleshooting). -## Ponteiros de referência da configuração do Telegram +## Ponteiros para a referência de config do Telegram Referência principal: - `channels.telegram.enabled`: ativa/desativa a inicialização do canal. - `channels.telegram.botToken`: token do bot (BotFather). -- `channels.telegram.tokenFile`: lê o token de um caminho de arquivo comum. Symlinks são rejeitados. +- `channels.telegram.tokenFile`: lê o token de um caminho de arquivo regular. Symlinks são rejeitados. - `channels.telegram.dmPolicy`: `pairing | allowlist | open | disabled` (padrão: pairing). -- `channels.telegram.allowFrom`: allowlist de DM (IDs numéricos de usuário do Telegram). `allowlist` exige pelo menos um ID de remetente. `open` exige `"*"`. `openclaw doctor --fix` pode resolver entradas legadas `@username` para IDs e pode recuperar entradas de allowlist de arquivos do pairing store em fluxos de migração de allowlist. +- `channels.telegram.allowFrom`: allowlist de DM (IDs numéricos de usuários do Telegram). `allowlist` exige pelo menos um ID de remetente. `open` exige `"*"`. `openclaw doctor --fix` pode resolver entradas legadas `@username` para IDs e pode recuperar entradas de allowlist de arquivos do armazenamento de pareamento em fluxos de migração de allowlist. - `channels.telegram.actions.poll`: ativa ou desativa a criação de enquetes no Telegram (padrão: ativado; ainda requer `sendMessage`). -- `channels.telegram.defaultTo`: alvo padrão do Telegram usado por `--deliver` da CLI quando nenhum `--reply-to` explícito é fornecido. +- `channels.telegram.defaultTo`: destino padrão do Telegram usado pelo `--deliver` da CLI quando nenhum `--reply-to` explícito é fornecido. - `channels.telegram.groupPolicy`: `open | allowlist | disabled` (padrão: allowlist). -- `channels.telegram.groupAllowFrom`: allowlist de remetente em grupo (IDs numéricos de usuário do Telegram). `openclaw doctor --fix` pode resolver entradas legadas `@username` para IDs. Entradas não numéricas são ignoradas no momento da autorização. A autorização em grupo não usa fallback do pairing store de DM (`2026.2.25+`). +- `channels.telegram.groupAllowFrom`: allowlist de remetentes em grupo (IDs numéricos de usuários do Telegram). `openclaw doctor --fix` pode resolver entradas legadas `@username` para IDs. Entradas não numéricas são ignoradas no momento da autenticação. A autenticação de grupo não usa fallback do armazenamento de pareamento de DM (`2026.2.25+`). - Precedência de múltiplas contas: - Quando dois ou mais IDs de conta estiverem configurados, defina `channels.telegram.defaultAccount` (ou inclua `channels.telegram.accounts.default`) para tornar o roteamento padrão explícito. - - Se nenhum dos dois estiver definido, o OpenClaw recai para o primeiro ID de conta normalizado e `openclaw doctor` emite aviso. - - `channels.telegram.accounts.default.allowFrom` e `channels.telegram.accounts.default.groupAllowFrom` se aplicam somente à conta `default`. + - Se nenhum dos dois estiver definido, o OpenClaw usa como fallback o primeiro ID de conta normalizado e `openclaw doctor` emite um aviso. + - `channels.telegram.accounts.default.allowFrom` e `channels.telegram.accounts.default.groupAllowFrom` se aplicam apenas à conta `default`. - Contas nomeadas herdam `channels.telegram.allowFrom` e `channels.telegram.groupAllowFrom` quando os valores no nível da conta não estão definidos. - Contas nomeadas não herdam `channels.telegram.accounts.default.allowFrom` / `groupAllowFrom`. - `channels.telegram.groups`: padrões por grupo + allowlist (use `"*"` para padrões globais). - - `channels.telegram.groups..groupPolicy`: substituição por grupo para `groupPolicy` (`open | allowlist | disabled`). - - `channels.telegram.groups..requireMention`: padrão de bloqueio por menção. + - `channels.telegram.groups..groupPolicy`: substituição por grupo para groupPolicy (`open | allowlist | disabled`). + - `channels.telegram.groups..requireMention`: gate padrão de menção. - `channels.telegram.groups..skills`: filtro de Skills (omitir = todas as Skills, vazio = nenhuma). - - `channels.telegram.groups..allowFrom`: substituição por grupo para allowlist de remetentes. + - `channels.telegram.groups..allowFrom`: substituição da allowlist de remetentes por grupo. - `channels.telegram.groups..systemPrompt`: prompt de sistema extra para o grupo. - `channels.telegram.groups..enabled`: desativa o grupo quando `false`. - - `channels.telegram.groups..topics..*`: substituições por tópico (campos de grupo + `agentId` exclusivo de tópico). - - `channels.telegram.groups..topics..agentId`: roteia este tópico para um agente específico (substitui o roteamento de nível de grupo e por binding). -- `channels.telegram.groups..topics..groupPolicy`: substituição por tópico para `groupPolicy` (`open | allowlist | disabled`). -- `channels.telegram.groups..topics..requireMention`: substituição por tópico para bloqueio por menção. -- `bindings[]` de nível superior com `type: "acp"` e ID canônico de tópico `chatId:topic:topicId` em `match.peer.id`: campos de binding persistente de tópico ACP (veja [Agentes ACP](/tools/acp-agents#channel-specific-settings)). + - `channels.telegram.groups..topics..*`: substituições por tópico (campos de grupo + `agentId` exclusivo do tópico). + - `channels.telegram.groups..topics..agentId`: roteia este tópico para um agente específico (substitui o roteamento no nível de grupo e por binding). +- `channels.telegram.groups..topics..groupPolicy`: substituição por tópico para groupPolicy (`open | allowlist | disabled`). +- `channels.telegram.groups..topics..requireMention`: substituição por tópico para o gate de menção. +- `bindings[]` no nível superior com `type: "acp"` e ID canônico de tópico `chatId:topic:topicId` em `match.peer.id`: campos persistentes de vinculação de tópico ACP (veja [Agentes ACP](/pt-BR/tools/acp-agents#channel-specific-settings)). - `channels.telegram.direct..topics..agentId`: roteia tópicos de DM para um agente específico (mesmo comportamento de tópicos de fórum). - `channels.telegram.execApprovals.enabled`: ativa o Telegram como cliente de aprovação de exec baseado em chat para esta conta. -- `channels.telegram.execApprovals.approvers`: IDs de usuário do Telegram autorizados a aprovar ou negar solicitações de exec. Opcional quando `channels.telegram.allowFrom` ou um `channels.telegram.defaultTo` direto já identifica o dono. +- `channels.telegram.execApprovals.approvers`: IDs de usuários do Telegram autorizados a aprovar ou negar solicitações de exec. Opcional quando `channels.telegram.allowFrom` ou um `channels.telegram.defaultTo` direto já identifica o proprietário. - `channels.telegram.execApprovals.target`: `dm | channel | both` (padrão: `dm`). `channel` e `both` preservam o tópico de origem do Telegram quando presente. -- `channels.telegram.execApprovals.agentFilter`: filtro opcional por ID de agente para prompts de aprovação encaminhados. -- `channels.telegram.execApprovals.sessionFilter`: filtro opcional por chave de sessão (substring ou regex) para prompts de aprovação encaminhados. -- `channels.telegram.accounts..execApprovals`: substituição por conta para roteamento de aprovação de exec no Telegram e autorização de aprovadores. +- `channels.telegram.execApprovals.agentFilter`: filtro opcional de ID de agente para prompts de aprovação encaminhados. +- `channels.telegram.execApprovals.sessionFilter`: filtro opcional de chave de sessão (substring ou regex) para prompts de aprovação encaminhados. +- `channels.telegram.accounts..execApprovals`: substituição por conta para roteamento de aprovação de exec no Telegram e autorização de aprovador. - `channels.telegram.capabilities.inlineButtons`: `off | dm | group | all | allowlist` (padrão: allowlist). - `channels.telegram.accounts..capabilities.inlineButtons`: substituição por conta. - `channels.telegram.commands.nativeSkills`: ativa/desativa comandos nativos de Skills no Telegram. - `channels.telegram.replyToMode`: `off | first | all` (padrão: `off`). - `channels.telegram.textChunkLimit`: tamanho do chunk de saída (caracteres). -- `channels.telegram.chunkMode`: `length` (padrão) ou `newline` para dividir em linhas em branco (limites de parágrafo) antes da divisão por comprimento. -- `channels.telegram.linkPreview`: alterna prévias de link para mensagens de saída (padrão: true). -- `channels.telegram.streaming`: `off | partial | block | progress` (prévia de stream ao vivo; padrão: `partial`; `progress` é mapeado para `partial`; `block` é compatibilidade legada com modo de prévia). O streaming de prévia do Telegram usa uma única mensagem de prévia editada no lugar. -- `channels.telegram.mediaMaxMb`: limite de mídia de entrada/saída do Telegram (MB, padrão: 100). -- `channels.telegram.retry`: política de nova tentativa para helpers de envio do Telegram (CLI/tools/actions) em erros recuperáveis de API de saída (tentativas, `minDelayMs`, `maxDelayMs`, jitter). +- `channels.telegram.chunkMode`: `length` (padrão) ou `newline` para dividir em linhas em branco (limites de parágrafo) antes do chunking por tamanho. +- `channels.telegram.linkPreview`: alterna prévias de links para mensagens de saída (padrão: true). +- `channels.telegram.streaming`: `off | partial | block | progress` (prévia de stream ao vivo; padrão: `partial`; `progress` é mapeado para `partial`; `block` é compatibilidade legada com o modo de prévia). O streaming de prévia do Telegram usa uma única mensagem de prévia que é editada no lugar. +- `channels.telegram.mediaMaxMb`: limite de mídia recebida/enviada do Telegram (MB, padrão: 100). +- `channels.telegram.retry`: política de tentativas para helpers de envio do Telegram (CLI/ferramentas/ações) em erros recuperáveis de saída da API (tentativas, minDelayMs, maxDelayMs, jitter). - `channels.telegram.network.autoSelectFamily`: substitui o autoSelectFamily do Node (true=ativar, false=desativar). O padrão é ativado no Node 22+, com WSL2 usando desativado por padrão. -- `channels.telegram.network.dnsResultOrder`: substitui a ordem de resultado do DNS (`ipv4first` ou `verbatim`). O padrão é `ipv4first` no Node 22+. -- `channels.telegram.network.dangerouslyAllowPrivateNetwork`: ativação perigosa para ambientes confiáveis com fake-IP ou proxy transparente em que downloads de mídia do Telegram resolvem `api.telegram.org` para endereços privados/internos/de uso especial fora da permissão padrão da faixa de benchmark RFC 2544. -- `channels.telegram.proxy`: URL de proxy para chamadas da Bot API (SOCKS/HTTP). -- `channels.telegram.webhookUrl`: ativa o modo webhook (requer `channels.telegram.webhookSecret`). -- `channels.telegram.webhookSecret`: segredo do webhook (obrigatório quando `webhookUrl` estiver definido). -- `channels.telegram.webhookPath`: caminho local do webhook (padrão `/telegram-webhook`). -- `channels.telegram.webhookHost`: host local de bind do webhook (padrão `127.0.0.1`). -- `channels.telegram.webhookPort`: porta local de bind do webhook (padrão `8787`). -- `channels.telegram.actions.reactions`: bloqueia reações da ferramenta do Telegram. -- `channels.telegram.actions.sendMessage`: bloqueia envios de mensagem da ferramenta do Telegram. -- `channels.telegram.actions.deleteMessage`: bloqueia exclusões de mensagem da ferramenta do Telegram. -- `channels.telegram.actions.sticker`: bloqueia ações de sticker do Telegram — envio e pesquisa (padrão: false). -- `channels.telegram.reactionNotifications`: `off | own | all` — controla quais reações acionam eventos de sistema (padrão: `own` quando não definido). +- `channels.telegram.network.dnsResultOrder`: substitui a ordem de resultados de DNS (`ipv4first` ou `verbatim`). O padrão é `ipv4first` no Node 22+. +- `channels.telegram.network.dangerouslyAllowPrivateNetwork`: opt-in perigoso para ambientes confiáveis de fake-IP ou proxy transparente nos quais downloads de mídia do Telegram resolvem `api.telegram.org` para endereços privados/internos/de uso especial fora da permissão padrão da faixa de benchmark RFC 2544. +- `channels.telegram.proxy`: URL de proxy para chamadas da API de Bot (SOCKS/HTTP). +- `channels.telegram.webhookUrl`: ativa o modo Webhook (requer `channels.telegram.webhookSecret`). +- `channels.telegram.webhookSecret`: segredo do Webhook (obrigatório quando `webhookUrl` estiver definido). +- `channels.telegram.webhookPath`: caminho local do Webhook (padrão `/telegram-webhook`). +- `channels.telegram.webhookHost`: host local de bind do Webhook (padrão `127.0.0.1`). +- `channels.telegram.webhookPort`: porta local de bind do Webhook (padrão `8787`). +- `channels.telegram.actions.reactions`: gate para reações de ferramenta do Telegram. +- `channels.telegram.actions.sendMessage`: gate para envios de mensagem de ferramenta do Telegram. +- `channels.telegram.actions.deleteMessage`: gate para exclusões de mensagem de ferramenta do Telegram. +- `channels.telegram.actions.sticker`: gate para ações de sticker do Telegram — enviar e pesquisar (padrão: false). +- `channels.telegram.reactionNotifications`: `off | own | all` — controla quais reações acionam eventos do sistema (padrão: `own` quando não definido). - `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` — controla a capacidade de reação do agente (padrão: `minimal` quando não definido). -- `channels.telegram.errorPolicy`: `reply | silent` — controla o comportamento de resposta de erro (padrão: `reply`). Substituições por conta/grupo/tópico são compatíveis. -- `channels.telegram.errorCooldownMs`: ms mínimos entre respostas de erro para o mesmo chat (padrão: `60000`). Evita spam de erros durante indisponibilidades. +- `channels.telegram.errorPolicy`: `reply | silent` — controla o comportamento de resposta de erro (padrão: `reply`). Compatível com substituições por conta/grupo/tópico. +- `channels.telegram.errorCooldownMs`: mínimo em ms entre respostas de erro para o mesmo chat (padrão: `60000`). Evita spam de erros durante indisponibilidades. -- [Referência de configuração - Telegram](/gateway/configuration-reference#telegram) +- [Referência de configuração - Telegram](/pt-BR/gateway/configuration-reference#telegram) -Campos de alto sinal específicos do Telegram: +Campos específicos do Telegram com maior sinal: -- inicialização/autenticação: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` deve apontar para um arquivo comum; symlinks são rejeitados) -- controle de acesso: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, `bindings[]` de nível superior (`type: "acp"`) +- inicialização/autenticação: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` deve apontar para um arquivo regular; symlinks são rejeitados) +- controle de acesso: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, `bindings[]` no nível superior (`type: "acp"`) - aprovações de exec: `execApprovals`, `accounts.*.execApprovals` - comando/menu: `commands.native`, `commands.nativeSkills`, `customCommands` - threading/respostas: `replyToMode` - streaming: `streaming` (prévia), `blockStreaming` - formatação/entrega: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix` - mídia/rede: `mediaMaxMb`, `timeoutSeconds`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy` -- webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost` -- ações/recursos: `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker` +- Webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost` +- ações/capacidades: `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker` - reações: `reactionNotifications`, `reactionLevel` - erros: `errorPolicy`, `errorCooldownMs` - gravações/histórico: `configWrites`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` ## Relacionado -- [Pareamento](/channels/pairing) -- [Grupos](/channels/groups) -- [Segurança](/gateway/security) -- [Roteamento de canal](/channels/channel-routing) -- [Roteamento multiagente](/concepts/multi-agent) -- [Solução de problemas](/channels/troubleshooting) +- [Pareamento](/pt-BR/channels/pairing) +- [Grupos](/pt-BR/channels/groups) +- [Segurança](/pt-BR/gateway/security) +- [Roteamento de canal](/pt-BR/channels/channel-routing) +- [Roteamento multiagente](/pt-BR/concepts/multi-agent) +- [Solução de problemas](/pt-BR/channels/troubleshooting) diff --git a/docs/pt-BR/concepts/qa-e2e-automation.md b/docs/pt-BR/concepts/qa-e2e-automation.md index 0c6f7c6dc..94fee6356 100644 --- a/docs/pt-BR/concepts/qa-e2e-automation.md +++ b/docs/pt-BR/concepts/qa-e2e-automation.md @@ -2,29 +2,33 @@ read_when: - Estendendo o qa-lab ou o qa-channel - Adicionando cenários de QA com suporte do repositório - - Criando automação de QA com maior realismo em torno do painel do Gateway -summary: Formato privado de automação de QA para qa-lab, qa-channel, cenários com seed e relatórios de protocolo + - Criando uma automação de QA com maior realismo em torno do painel do Gateway +summary: Formato da automação privada de QA para qa-lab, qa-channel, cenários com seed e relatórios de protocolo title: Automação E2E de QA x-i18n: - generated_at: "2026-04-18T05:24:45Z" + generated_at: "2026-04-20T05:41:39Z" model: gpt-5.4 provider: openai - source_hash: adf8c5f74e8fabdc8e9fd7ecd41afce8b60354c7dd24d92ac926d3c527927cd4 + source_hash: 34245ce871356caeab0d9e0eeeaa9fb4e408920a4a97ad27567fa365d8db17c7 source_path: concepts/qa-e2e-automation.md workflow: 15 --- # Automação E2E de QA -A pilha privada de QA foi projetada para exercitar o OpenClaw de uma forma mais realista e com formato de canal do que um único teste unitário consegue. +A stack privada de QA foi projetada para exercitar o OpenClaw de uma forma mais +realista e com formato de canal do que um único teste unitário consegue. Peças atuais: -- `extensions/qa-channel`: canal de mensagens sintético com superfícies de DM, canal, thread, reação, edição e exclusão. -- `extensions/qa-lab`: UI de depuração e barramento de QA para observar a transcrição, injetar mensagens de entrada e exportar um relatório em Markdown. -- `qa/`: recursos com seed mantidos no repositório para a tarefa inicial e cenários básicos de QA. +- `extensions/qa-channel`: canal de mensagens sintético com superfícies de DM, canal, thread, + reação, edição e exclusão. +- `extensions/qa-lab`: UI de depuração e barramento de QA para observar a transcrição, + injetar mensagens de entrada e exportar um relatório em Markdown. +- `qa/`: recursos com seed versionados no repositório para a tarefa inicial e + cenários de QA de linha de base. -O fluxo atual do operador de QA é um site de QA com dois painéis: +O fluxo atual do operador de QA é um site de QA em duas telas: - Esquerda: painel do Gateway (Control UI) com o agente. - Direita: QA Lab, mostrando a transcrição em estilo Slack e o plano do cenário. @@ -35,9 +39,13 @@ Execute com: pnpm qa:lab:up ``` -Isso compila o site de QA, inicia a lane do Gateway com Docker e expõe a página do QA Lab, onde um operador ou loop de automação pode dar ao agente uma missão de QA, observar o comportamento real do canal e registrar o que funcionou, falhou ou permaneceu bloqueado. +Isso compila o site de QA, inicia a lane do Gateway com Docker e expõe a +página do QA Lab, onde um operador ou loop de automação pode dar ao agente uma +missão de QA, observar o comportamento real do canal e registrar o que funcionou, falhou ou +permaneceu bloqueado. -Para uma iteração mais rápida da UI do QA Lab sem recompilar a imagem Docker a cada vez, inicie a pilha com um bundle do QA Lab montado por bind: +Para uma iteração mais rápida da UI do QA Lab sem reconstruir a imagem Docker a cada vez, +inicie a stack com um bundle do QA Lab montado por bind: ```bash pnpm openclaw qa docker-build-image @@ -46,56 +54,89 @@ pnpm qa:lab:up:fast pnpm qa:lab:watch ``` -`qa:lab:up:fast` mantém os serviços Docker em uma imagem pré-compilada e monta por bind `extensions/qa-lab/web/dist` no contêiner `qa-lab`. `qa:lab:watch` recompila esse bundle a cada alteração, e o navegador recarrega automaticamente quando o hash de recursos do QA Lab muda. +`qa:lab:up:fast` mantém os serviços Docker em uma imagem pré-compilada e faz bind-mount de +`extensions/qa-lab/web/dist` no contêiner `qa-lab`. `qa:lab:watch` +recompila esse bundle em caso de mudança, e o navegador recarrega automaticamente quando o hash +do recurso do QA Lab muda. -Para uma lane de smoke real de transporte com Matrix, execute: +Para uma lane de smoke do Matrix com transporte real, execute: ```bash pnpm openclaw qa matrix ``` -Essa lane provisiona um homeserver Tuwunel descartável no Docker, registra usuários temporários de driver, SUT e observador, cria uma sala privada e então executa o Plugin real do Matrix dentro de um processo filho de Gateway de QA. A lane de transporte ao vivo mantém a configuração filha restrita ao transporte em teste, para que o Matrix seja executado sem `qa-channel` na configuração filha. Ela grava os artefatos estruturados do relatório e um log combinado de stdout/stderr no diretório de saída de Matrix QA selecionado. Para capturar também a saída externa de compilação/inicialização de `scripts/run-node.mjs`, defina `OPENCLAW_RUN_NODE_OUTPUT_LOG=` para um arquivo de log local ao repositório. +Essa lane provisiona um homeserver Tuwunel descartável em Docker, registra +usuários temporários driver, SUT e observer, cria uma sala privada, e então executa +o Plugin real do Matrix dentro de um processo filho QA do Gateway. A lane de transporte ao vivo mantém +a configuração filha restrita ao transporte em teste, então o Matrix é executado sem +`qa-channel` na configuração filha. Ela grava os artefatos de relatório estruturado e +um log combinado de stdout/stderr no diretório de saída de QA do Matrix selecionado. Para +capturar também a saída externa de build/launcher de `scripts/run-node.mjs`, defina +`OPENCLAW_RUN_NODE_OUTPUT_LOG=` para um arquivo de log local ao repositório. -Para uma lane de smoke real de transporte com Telegram, execute: +Para uma lane de smoke do Telegram com transporte real, execute: ```bash pnpm openclaw qa telegram ``` -Essa lane mira em um grupo privado real do Telegram em vez de provisionar um servidor descartável. Ela requer `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` e `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`, além de dois bots distintos no mesmo grupo privado. O bot SUT precisa ter um nome de usuário no Telegram, e a observação entre bots funciona melhor quando ambos os bots têm o Bot-to-Bot Communication Mode habilitado em `@BotFather`. +Essa lane usa um grupo privado real do Telegram em vez de provisionar um +servidor descartável. Ela exige `OPENCLAW_QA_TELEGRAM_GROUP_ID`, +`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` e +`OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`, além de dois bots distintos no mesmo +grupo privado. O bot SUT deve ter um nome de usuário do Telegram, e a observação +bot-para-bot funciona melhor quando ambos os bots têm o modo Bot-to-Bot Communication +ativado no `@BotFather`. +O comando encerra com código diferente de zero quando qualquer cenário falha. Use `--allow-failures` quando +quiser artefatos sem um código de saída de falha. -As lanes de transporte ao vivo agora compartilham um contrato menor em vez de cada uma inventar seu próprio formato de lista de cenários: +As lanes de transporte ao vivo agora compartilham um contrato menor em vez de cada uma inventar +seu próprio formato de lista de cenários: -`qa-channel` continua sendo a suíte ampla de comportamento sintético do produto e não faz parte da matriz de cobertura de transporte ao vivo. +`qa-channel` continua sendo a suíte ampla de comportamento sintético do produto e não faz parte +da matriz de cobertura de transporte ao vivo. -| Lane | Canary | Bloqueio por menção | Bloqueio por allowlist | Resposta de nível superior | Retomada após reinício | Continuação em thread | Isolamento de thread | Observação de reação | Comando de ajuda | -| -------- | ------ | ------------------- | ---------------------- | -------------------------- | ---------------------- | -------------------- | -------------------- | -------------------- | ---------------- | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| Lane | Canary | Bloqueio por menção | Bloqueio por allowlist | Resposta de nível superior | Retomada após reinício | Acompanhamento em thread | Isolamento de thread | Observação de reação | Comando help | +| -------- | ------ | ------------------- | ---------------------- | -------------------------- | ---------------------- | ------------------------ | -------------------- | -------------------- | ------------ | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | -Isso mantém o `qa-channel` como a suíte ampla de comportamento do produto, enquanto Matrix, Telegram e futuros transportes ao vivo compartilham uma lista explícita de verificação do contrato de transporte. +Isso mantém `qa-channel` como a suíte ampla de comportamento do produto, enquanto Matrix, +Telegram e futuros transportes ao vivo compartilham uma checklist explícita de contrato de transporte. -Para uma lane com VM Linux descartável sem trazer Docker para o fluxo de QA, execute: +Para uma lane descartável de VM Linux sem colocar Docker no caminho do QA, execute: ```bash pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline ``` -Isso inicializa um guest novo do Multipass, instala dependências, compila o OpenClaw dentro do guest, executa `qa suite` e então copia o relatório e o resumo normais de QA de volta para `.artifacts/qa-e2e/...` no host. +Isso inicializa um guest novo do Multipass, instala dependências, compila o OpenClaw +dentro do guest, executa `qa suite` e então copia o relatório e o resumo normais de QA +de volta para `.artifacts/qa-e2e/...` no host. Ele reutiliza o mesmo comportamento de seleção de cenários de `qa suite` no host. -Execuções da suíte no host e no Multipass executam vários cenários selecionados em paralelo com workers isolados de Gateway por padrão, até 64 workers ou a contagem de cenários selecionada. Use `--concurrency ` para ajustar a quantidade de workers, ou `--concurrency 1` para execução serial. -Execuções ao vivo encaminham as entradas compatíveis de autenticação de QA que são práticas para o guest: chaves de provedor baseadas em env, o caminho de configuração do provedor ao vivo de QA e `CODEX_HOME` quando presente. Mantenha `--output-dir` sob a raiz do repositório para que o guest possa gravar de volta por meio do workspace montado. +Execuções da suíte no host e no Multipass executam múltiplos cenários selecionados em paralelo +com workers isolados do Gateway por padrão. `qa-channel` usa por padrão concorrência +4, limitada pela quantidade de cenários selecionados. Use `--concurrency ` para ajustar +a quantidade de workers, ou `--concurrency 1` para execução serial. +O comando encerra com código diferente de zero quando qualquer cenário falha. Use `--allow-failures` quando +quiser artefatos sem um código de saída de falha. +Execuções ao vivo encaminham as entradas de autenticação de QA compatíveis que são práticas para o +guest: chaves de provedor baseadas em env, o caminho de configuração do provedor ao vivo de QA e +`CODEX_HOME` quando presente. Mantenha `--output-dir` sob a raiz do repositório para que o guest +possa gravar de volta por meio do workspace montado. -## Seeds mantidos no repositório +## Seeds com suporte do repositório Os recursos com seed ficam em `qa/`: - `qa/scenarios/index.md` - `qa/scenarios//*.md` -Eles ficam intencionalmente no git para que o plano de QA seja visível tanto para humanos quanto para o agente. +Eles ficam intencionalmente no git para que o plano de QA seja visível tanto para humanos quanto para o +agente. -O `qa-lab` deve continuar sendo um executor genérico de Markdown. Cada arquivo Markdown de cenário é a fonte da verdade para uma execução de teste e deve definir: +`qa-lab` deve permanecer um executor genérico de Markdown. Cada arquivo Markdown de cenário é +a fonte da verdade para uma execução de teste e deve definir: - metadados do cenário - metadados opcionais de categoria, capacidade, lane e risco @@ -104,11 +145,16 @@ O `qa-lab` deve continuar sendo um executor genérico de Markdown. Cada arquivo - patch opcional de configuração do Gateway - o `qa-flow` executável -A superfície de runtime reutilizável que dá suporte ao `qa-flow` pode continuar genérica e transversal. Por exemplo, cenários em Markdown podem combinar helpers do lado do transporte com helpers do lado do navegador que dirigem a Control UI incorporada por meio da interface `browser.request` do Gateway sem adicionar um executor com caso especial. +A superfície de runtime reutilizável que sustenta `qa-flow` pode permanecer genérica +e transversal. Por exemplo, cenários em Markdown podem combinar helpers do lado do transporte +com helpers do lado do navegador que dirigem a Control UI incorporada pela +superfície `browser.request` do Gateway sem adicionar um executor com caso especial. -Os arquivos de cenário devem ser agrupados por capacidade do produto, e não pela pasta da árvore de código-fonte. Mantenha os IDs de cenário estáveis quando os arquivos forem movidos; use `docsRefs` e `codeRefs` para rastreabilidade de implementação. +Os arquivos de cenário devem ser agrupados por capacidade do produto, e não pela pasta da árvore +de código-fonte. Mantenha os IDs de cenário estáveis quando os arquivos forem movidos; use `docsRefs` e +`codeRefs` para rastreabilidade da implementação. -A lista básica deve permanecer ampla o suficiente para cobrir: +A lista de linha de base deve permanecer ampla o suficiente para cobrir: - chat em DM e canal - comportamento de thread @@ -117,37 +163,44 @@ A lista básica deve permanecer ampla o suficiente para cobrir: - recuperação de memória - troca de modelo - handoff para subagente -- leitura do repositório e da documentação -- uma pequena tarefa de compilação, como Lobster Invaders +- leitura de repositório e de documentação +- uma pequena tarefa de build, como Lobster Invaders ## Lanes de mock de provedor `qa suite` tem duas lanes locais de mock de provedor: -- `mock-openai` é o mock do OpenClaw sensível ao cenário. Ele continua sendo a lane de mock determinística padrão para QA com suporte do repositório e gates de paridade. -- `aimock` inicia um servidor de provedor baseado em AIMock para cobertura experimental de protocolo, fixture, gravação/reprodução e caos. Ele é aditivo e não substitui o despachante de cenários de `mock-openai`. +- `mock-openai` é o mock do OpenClaw orientado a cenários. Ele continua sendo a lane de mock + determinística padrão para QA com suporte do repositório e gates de paridade. +- `aimock` inicia um servidor de provedor com AIMock para cobertura experimental de protocolo, + fixture, record/replay e caos. Ele é complementar e não substitui o dispatcher + de cenários `mock-openai`. A implementação da lane de provedor fica em `extensions/qa-lab/src/providers/`. -Cada provedor é responsável por seus padrões, inicialização de servidor local, configuração de modelo do Gateway, necessidades de preparação de perfil de autenticação e flags de capacidade de live/mock. O código compartilhado de suíte e Gateway deve rotear pelo registro de provedores em vez de ramificar pelos nomes dos provedores. +Cada provedor é responsável por seus padrões, inicialização do servidor local, configuração do modelo do Gateway, +necessidades de preparação de perfil de autenticação e flags de capacidade live/mock. O código +compartilhado da suíte e do Gateway deve passar pelo registro de provedores em vez de ramificar +com base em nomes de provedores. ## Adaptadores de transporte -O `qa-lab` é responsável por uma interface genérica de transporte para cenários de QA em Markdown. -`qa-channel` é o primeiro adaptador nessa interface, mas o objetivo do design é mais amplo: -canais futuros, reais ou sintéticos, devem se conectar ao mesmo executor de suíte em vez de adicionar um executor de QA específico de transporte. +`qa-lab` é responsável por uma superfície de transporte genérica para cenários de QA em Markdown. +`qa-channel` é o primeiro adaptador nessa superfície, mas o objetivo do design é mais amplo: +futuros canais reais ou sintéticos devem se conectar ao mesmo executor da suíte +em vez de adicionar um executor de QA específico por transporte. No nível da arquitetura, a divisão é: - `qa-lab` é responsável pela execução genérica de cenários, concorrência de workers, gravação de artefatos e relatórios. - o adaptador de transporte é responsável pela configuração do Gateway, prontidão, observação de entrada e saída, ações de transporte e estado de transporte normalizado. -- os arquivos de cenário em Markdown sob `qa/scenarios/` definem a execução de teste; o `qa-lab` fornece a superfície de runtime reutilizável que os executa. +- os arquivos de cenário em Markdown em `qa/scenarios/` definem a execução do teste; `qa-lab` fornece a superfície de runtime reutilizável que os executa. -A orientação de adoção voltada a mantenedores para novos adaptadores de canal está em +A orientação de adoção voltada para mantenedores para novos adaptadores de canal fica em [Testing](/pt-BR/help/testing#adding-a-channel-to-qa). ## Relatórios -O `qa-lab` exporta um relatório de protocolo em Markdown a partir da linha do tempo observada no barramento. +`qa-lab` exporta um relatório de protocolo em Markdown a partir da linha do tempo observada no barramento. O relatório deve responder: - O que funcionou @@ -155,7 +208,8 @@ O relatório deve responder: - O que permaneceu bloqueado - Quais cenários de acompanhamento valem a pena adicionar -Para verificações de personalidade e estilo, execute o mesmo cenário em várias refs de modelo ao vivo e grave um relatório em Markdown avaliado: +Para verificações de caráter e estilo, execute o mesmo cenário em várias refs de modelo ao vivo +e escreva um relatório em Markdown avaliado: ```bash pnpm openclaw qa character-eval \ @@ -174,17 +228,36 @@ pnpm openclaw qa character-eval \ --judge-concurrency 16 ``` -O comando executa processos filhos locais de Gateway de QA, não Docker. Os cenários de avaliação de personalidade devem definir a persona por meio de `SOUL.md` e então executar turnos normais de usuário, como chat, ajuda com workspace e pequenas tarefas em arquivos. O modelo candidato não deve ser informado de que está sendo avaliado. O comando preserva cada transcrição completa, registra estatísticas básicas da execução e depois solicita aos modelos juízes, em modo fast, com raciocínio `xhigh`, que classifiquem as execuções por naturalidade, vibe e humor. -Use `--blind-judge-models` ao comparar provedores: o prompt do juiz ainda recebe cada transcrição e status de execução, mas as refs dos candidatos são substituídas por rótulos neutros como `candidate-01`; o relatório remapeia as classificações para as refs reais após o parsing. -As execuções candidatas usam `high` thinking por padrão, com `xhigh` para modelos OpenAI que oferecem suporte. Substitua um candidato específico inline com `--model provider/model,thinking=`. `--thinking ` ainda define um fallback global, e o formato mais antigo `--model-thinking ` é mantido por compatibilidade. -As refs candidatas de OpenAI usam modo fast por padrão para que o processamento prioritário seja usado quando o provedor oferecer suporte. Adicione `,fast`, `,no-fast` ou `,fast=false` inline quando um único candidato ou juiz precisar de substituição. Passe `--fast` apenas quando quiser forçar o modo fast para todos os modelos candidatos. As durações de candidatos e juízes são registradas no relatório para análise de benchmark, mas os prompts dos juízes dizem explicitamente para não classificar por velocidade. -As execuções de modelos candidatos e juízes usam concorrência 16 por padrão. Reduza `--concurrency` ou `--judge-concurrency` quando limites do provedor ou pressão no Gateway local tornarem uma execução muito ruidosa. -Quando nenhum `--model` candidato é informado, a avaliação de personalidade usa por padrão +O comando executa processos filhos locais do Gateway de QA, não Docker. Cenários de avaliação de caráter +devem definir a persona por meio de `SOUL.md` e então executar turnos normais de usuário, +como chat, ajuda de workspace e pequenas tarefas com arquivos. O modelo candidato +não deve ser informado de que está sendo avaliado. O comando preserva cada +transcrição completa, registra estatísticas básicas da execução e então solicita aos modelos julgadores, no modo fast com +raciocínio `xhigh`, que classifiquem as execuções por naturalidade, vibe e humor. +Use `--blind-judge-models` ao comparar provedores: o prompt do julgador ainda recebe +cada transcrição e status da execução, mas as refs candidatas são substituídas por rótulos neutros +como `candidate-01`; o relatório mapeia as classificações de volta para as refs reais após +o parsing. +As execuções candidatas usam por padrão pensamento `high`, com `xhigh` para modelos OpenAI que +o suportam. Substitua um candidato específico inline com +`--model provider/model,thinking=`. `--thinking ` ainda define um +fallback global, e o formato antigo `--model-thinking ` é +mantido por compatibilidade. +As refs candidatas da OpenAI usam por padrão o modo fast para que o processamento prioritário seja usado +onde o provedor der suporte. Adicione `,fast`, `,no-fast` ou `,fast=false` inline quando um +único candidato ou julgador precisar de uma substituição. Passe `--fast` apenas quando quiser +forçar o modo fast para todos os modelos candidatos. As durações de candidatos e julgadores são +registradas no relatório para análise de benchmark, mas os prompts dos julgadores dizem explicitamente +para não classificar por velocidade. +Execuções de modelos candidatos e julgadores usam por padrão concorrência 16. Reduza +`--concurrency` ou `--judge-concurrency` quando limites do provedor ou pressão no Gateway local +deixarem a execução muito ruidosa. +Quando nenhum `--model` candidato é passado, a avaliação de caráter usa por padrão `openai/gpt-5.4`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`, `anthropic/claude-sonnet-4-6`, `zai/glm-5.1`, `moonshot/kimi-k2.5` e -`google/gemini-3.1-pro-preview` quando nenhum `--model` é informado. -Quando nenhum `--judge-model` é informado, os juízes usam por padrão +`google/gemini-3.1-pro-preview` quando nenhum `--model` é passado. +Quando nenhum `--judge-model` é passado, os julgadores usam por padrão `openai/gpt-5.4,thinking=xhigh,fast` e `anthropic/claude-opus-4-6,thinking=high`. diff --git a/docs/pt-BR/gateway/configuration-reference.md b/docs/pt-BR/gateway/configuration-reference.md index 19244d4ef..9e4493a97 100644 --- a/docs/pt-BR/gateway/configuration-reference.md +++ b/docs/pt-BR/gateway/configuration-reference.md @@ -5,10 +5,10 @@ read_when: summary: Referência de configuração do Gateway para chaves principais do OpenClaw, valores padrão e links para referências dedicadas de subsistemas title: Referência de configuração x-i18n: - generated_at: "2026-04-18T05:24:44Z" + generated_at: "2026-04-20T05:41:41Z" model: gpt-5.4 provider: openai - source_hash: 4b504c9c6b47d7a327a0acf6934561c9b2606c01cc8ebe5526ccde73033d759f + source_hash: 22b10f1f133374cd29ef4a5ec4fb9c9938eb51184ad82e1aa2e5f6f7af58585e source_path: gateway/configuration-reference.md workflow: 15 --- @@ -17,19 +17,19 @@ 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 aponta para outras referências quando um subsistema tem sua própria documentação mais detalhada. Ela **não** tenta incluir em linha todos os catálogos de comandos pertencentes a canais/plugins nem todos os parâmetros profundos de memória/QMD em uma única página. +Esta página cobre as principais superfícies de configuração do OpenClaw e aponta para links externos quando um subsistema tem sua própria referência mais detalhada. Ela **não** tenta embutir, em uma única página, todos os catálogos de comandos pertencentes a canais/plugins nem todos os ajustes profundos de memória/QMD. -Fonte de verdade do código: +Fonte da verdade no código: -- `openclaw config schema` imprime o JSON Schema em tempo real usado para validação e para a Control UI, com metadados de plugins/canais/bundled mesclados quando disponíveis -- `config.schema.lookup` retorna um único nó do schema com escopo de caminho para ferramentas de exploração detalhada -- `pnpm config:docs:check` / `pnpm config:docs:gen` validam o hash da 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 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 inspeção detalhada +- `pnpm config:docs:check` / `pnpm config:docs:gen` validam o hash de baseline da documentação de configuração em relação à superfície atual do schema Referências detalhadas dedicadas: - [Referência de configuração de memória](/pt-BR/reference/memory-config) para `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` e configuração de Dreaming em `plugins.entries.memory-core.config.dreaming` - [Comandos de barra](/pt-BR/tools/slash-commands) para o catálogo atual de comandos internos + bundled -- páginas do canal/plugin responsável para superfícies de comando específicas de canal +- páginas do canal/plugin proprietário para superfícies de comando específicas de cada canal O formato de configuração é **JSON5** (comentários + vírgulas finais permitidos). Todos os campos são opcionais — o OpenClaw usa valores padrão seguros quando omitidos. @@ -37,34 +37,34 @@ O formato de configuração é **JSON5** (comentários + vírgulas finais permit ## Canais -Cada canal é iniciado automaticamente quando sua seção de configuração existe (a menos que `enabled: false`). +Cada canal inicia automaticamente quando sua seção de configuração existe (a menos que `enabled: false`). -### Acesso por DM e grupo +### Acesso a DM e grupos 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 no armazenamento de permissão pareado) | +| `allowlist` | Somente remetentes em `allowFrom` (ou armazenamento de permissões pareadas) | | `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 à allowlist configurada | -| `open` | Ignorar as allowlists de grupo (a exigência de menção ainda se aplica) | -| `disabled` | Bloquear todas as mensagens de grupo/sala | +| Política de grupo | Comportamento | +| --------------------- | ----------------------------------------------------- | +| `allowlist` (padrão) | Somente 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 | -`channels.defaults.groupPolicy` define o padrão quando o `groupPolicy` de um provedor não está definido. +`channels.defaults.groupPolicy` define o padrão quando `groupPolicy` de um provedor não está definido. Os códigos de pareamento expiram após 1 hora. As solicitações pendentes de pareamento por DM são limitadas a **3 por canal**. -Se um bloco de provedor estiver totalmente ausente (`channels.` ausente), a política de grupo em tempo de execução usa `allowlist` como fallback (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 recorre a `allowlist` (fail-closed), com um aviso na inicialização. -### Sobrescritas de modelo por canal +### Substituições de modelo por canal -Use `channels.modelByChannel` para fixar IDs de canal específicos a um modelo. Os valores aceitam `provider/model` ou aliases de modelo configurados. O mapeamento por canal é aplicado quando uma sessão ainda não tem uma sobrescrita de modelo (por exemplo, definida via `/model`). +Use `channels.modelByChannel` para fixar IDs de canais específicos a um modelo. Os valores aceitam `provider/model` ou aliases de modelo configurados. O mapeamento do canal é aplicado quando uma sessão ainda não tem uma substituição de modelo (por exemplo, definida por `/model`). ```json5 { @@ -105,15 +105,15 @@ Use `channels.defaults` para o comportamento compartilhado de política de grupo } ``` -- `channels.defaults.groupPolicy`: política de grupo de fallback quando um `groupPolicy` no nível do provedor não está definido. -- `channels.defaults.contextVisibility`: modo padrão de visibilidade de contexto suplementar para todos os canais. Valores: `all` (padrão, inclui todo o contexto citado/thread/histórico), `allowlist` (inclui apenas contexto de remetentes na allowlist), `allowlist_quote` (igual a allowlist, mas mantém contexto explícito de citação/resposta). Sobrescrita por canal: `channels..contextVisibility`. -- `channels.defaults.heartbeat.showOk`: inclui status saudáveis de canais na saída do Heartbeat. +- `channels.defaults.groupPolicy`: política de grupo de fallback quando `groupPolicy` no nível do provedor não está definido. +- `channels.defaults.contextVisibility`: modo padrão de visibilidade de contexto suplementar para todos os canais. Valores: `all` (padrão, inclui todo o contexto de citação/thread/histórico), `allowlist` (inclui contexto apenas 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 íntegros de canal na saída do Heartbeat. - `channels.defaults.heartbeat.showAlerts`: inclui status degradados/com erro na saída do Heartbeat. -- `channels.defaults.heartbeat.useIndicator`: renderiza uma saída de Heartbeat compacta em estilo de indicador. +- `channels.defaults.heartbeat.useIndicator`: renderiza uma saída de Heartbeat compacta no estilo indicador. ### WhatsApp -O WhatsApp funciona por meio do canal web do Gateway (Baileys Web). Ele inicia automaticamente quando existe uma sessão vinculada. +O WhatsApp é executado pelo canal web do gateway (Baileys Web). Ele inicia automaticamente quando existe uma sessão vinculada. ```json5 { @@ -124,7 +124,7 @@ O WhatsApp funciona por meio do canal web do Gateway (Baileys Web). Ele inicia a textChunkLimit: 4000, chunkMode: "length", // length | newline mediaMaxMb: 50, - sendReadReceipts: true, // confirmações azuis (false no modo de conversa consigo mesmo) + sendReadReceipts: true, // blue ticks (false in self-chat mode) groups: { "*": { requireMention: true }, }, @@ -165,9 +165,9 @@ O WhatsApp funciona por meio do canal web do Gateway (Baileys Web). Ele inicia a ``` - 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 sobrescreve essa seleção padrão de conta de fallback quando corresponde a um ID de conta configurado. -- O diretório legado de autenticação Baileys de conta única é migrado pelo `openclaw doctor` para `whatsapp/default`. -- Sobrescritas por conta: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. +- O opcional `channels.whatsapp.defaultAccount` substitui essa seleção de conta padrão de fallback quando corresponde a um ID de conta configurado. +- O diretório de autenticação legado de conta única do Baileys é migrado por `openclaw doctor` para `whatsapp/default`. +- Substituições por conta: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. @@ -202,7 +202,7 @@ O WhatsApp funciona por meio do canal web do Gateway (Baileys Web). Ele inicia a historyLimit: 50, replyToMode: "first", // off | first | all | batched linkPreview: true, - streaming: "partial", // off | partial | block | progress (padrão: off; ative explicitamente para evitar limites de taxa de edição de 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,12 +225,12 @@ O WhatsApp funciona por meio do canal web do Gateway (Baileys Web). Ele inicia a } ``` -- 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 sobrescreve 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. +- Token do bot: `channels.telegram.botToken` ou `channels.telegram.tokenFile` (somente arquivo regular; symlinks são rejeitados), com `TELEGRAM_BOT_TOKEN` como fallback para a conta padrão. +- O opcional `channels.telegram.defaultAccount` 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[]` no nível superior com `type: "acp"` configuram associações ACP persistentes para tópicos de fórum (use o formato canônico `chatId:topic:topicId` em `match.peer.id`). A semântica dos campos é compartilhada em [ACP Agents](/pt-BR/tools/acp-agents#channel-specific-settings). -- As prévias de streaming no Telegram usam `sendMessage` + `editMessageText` (funciona em conversas diretas e em grupo). +- Entradas de nível superior `bindings[]` 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 [ACP Agents](/pt-BR/tools/acp-agents#channel-specific-settings). +- As prévias de streaming do Telegram usam `sendMessage` + `editMessageText` (funciona em chats diretos e em grupo). - Política de retry: consulte [Política de retry](/pt-BR/concepts/retry). ### Discord @@ -286,7 +286,7 @@ O WhatsApp funciona por meio do canal web do Gateway (Baileys Web). Ele inicia a historyLimit: 20, textChunkLimit: 2000, chunkMode: "length", // length | newline - streaming: "off", // off | partial | block | progress (progress corresponde a 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 funciona por meio do canal web do Gateway (Baileys Web). Ele inicia a 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 funciona por meio do canal web do Gateway (Baileys Web). Ele inicia a ``` - Token: `channels.discord.token`, com `DISCORD_BOT_TOKEN` como fallback para a conta padrão. -- Chamadas diretas de saída que fornecem um `token` explícito do Discord usam esse token para a chamada; as configurações de retry/política da conta ainda vêm da conta selecionada no snapshot ativo do runtime. -- `channels.discord.defaultAccount` opcional sobrescreve a seleção de conta padrão quando corresponde a um ID de conta configurado. -- Use `user:` (DM) ou `channel:` (canal de guild) para destinos de entrega; IDs numéricos sem prefixo são rejeitados. -- Slugs de guild são em minúsculas com espaços substituídos por `-`; as 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 bots que mencionem o bot (as próprias mensagens ainda são filtradas). -- `channels.discord.guilds..ignoreOtherMentions` (e sobrescritas por canal) descarta mensagens que mencionam outro usuário ou cargo, mas não o bot (excluindo @everyone/@here). -- `maxLinesPerMessage` (padrão 17) divide mensagens altas mesmo quando têm menos de 2000 caracteres. +- Chamadas diretas de saída que fornecem um `token` explícito do Discord usam esse token para a chamada; as configurações de retry/política da conta ainda vêm da conta selecionada no snapshot ativo em tempo de execução. +- O opcional `channels.discord.defaultAccount` 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. +- Os slugs de guild são em minúsculas com espaços substituídos por `-`; as 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 bots que mencionem o bot (mensagens do próprio bot continuam filtradas). +- `channels.discord.guilds..ignoreOtherMentions` (e substituições no nível do canal) descarta mensagens que mencionam outro usuário ou cargo, mas não o bot (excluindo @everyone/@here). +- `maxLinesPerMessage` (padrão 17) divide mensagens altas mesmo quando estão abaixo de 2000 caracteres. - `channels.discord.threadBindings` controla o roteamento vinculado a threads do Discord: - - `enabled`: sobrescrita do Discord para recursos de sessão vinculados a thread (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` e entrega/roteamento vinculados) - - `idleHours`: sobrescrita do Discord para desfoco automático por inatividade em horas (`0` desabilita) - - `maxAgeHours`: sobrescrita do Discord para idade máxima rígida em horas (`0` desabilita) - - `spawnSubagentSessions`: chave de opt-in para criação/vinculação automática de thread em `sessions_spawn({ thread: true })` -- Entradas `bindings[]` no nível superior com `type: "acp"` configuram associações ACP persistentes para canais e threads (use o id do canal/thread em `match.peer.id`). A semântica dos campos é compartilhada em [ACP Agents](/pt-BR/tools/acp-agents#channel-specific-settings). + - `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` desativa) + - `maxAgeHours`: substituição do Discord para idade máxima rígida em horas (`0` desativa) + - `spawnSubagentSessions`: chave de ativação para criação/vinculação automática de thread em `sessions_spawn({ thread: true })` +- Entradas de nível superior `bindings[]` com `type: "acp"` configuram vínculos 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 sobrescritas opcionais de entrada automática + TTS. +- `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 reentrando 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 runtime para a presença do bot (saudável => online, degradado => idle, esgotado => dnd) e permite sobrescritas 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 nativa de aprovações 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 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 de 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 streaming. 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 mutável por nome/tag (modo de compatibilidade break-glass). +- `channels.discord.execApprovals`: entrega nativa do Discord para aprovações de execução e autorização de aprovadores. + - `enabled`: `true`, `false` ou `"auto"` (padrão). No modo automático, as aprovações de execução 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 execução. Usa `commands.ownerAllowFrom` como fallback quando omitido. + - `agentFilter`: lista de permissões opcional de IDs de agentes. Omita para encaminhar aprovações para todos os agentes. - `sessionFilter`: padrões opcionais de chave de sessão (substring ou regex). - - `target`: onde enviar os prompts de aprovação. `"dm"` (padrão) envia para as DMs do aprovador, `"channel"` envia para o canal de origem, `"both"` envia para ambos. Quando o destino inclui `"channel"`, os botões só podem ser usados por aprovadores resolvidos. - - `cleanupAfterResolve`: quando `true`, exclui DMs de aprovação após aprovação, negação ou timeout. + - `target`: onde enviar os prompts de aprovação. `"dm"` (padrão) envia para as 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 as 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). @@ -393,11 +393,11 @@ O WhatsApp funciona por meio do canal web do Gateway (Baileys Web). Ele inicia a } ``` -- JSON da conta de serviço: em linha (`serviceAccount`) ou baseado em arquivo (`serviceAccountFile`). -- 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 a correspondência por principal de email mutável (modo de compatibilidade break-glass). +- JSON da conta de serviço: embutido (`serviceAccount`) ou baseado em arquivo (`serviceAccountFile`). +- SecretRef da conta de serviço também é compatível (`serviceAccountRef`). +- Fallbacks por variável de ambiente: `GOOGLE_CHAT_SERVICE_ACCOUNT` ou `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. +- Use `spaces/` ou `users/` para alvos de entrega. +- `channels.googlechat.dangerouslyAllowNameMatching` reabilita a correspondência mutável de principal de e-mail (modo de compatibilidade break-glass). ### Slack @@ -449,7 +449,7 @@ O WhatsApp funciona por meio do canal web do Gateway (Baileys Web). Ele inicia a chunkMode: "length", streaming: { mode: "partial", // off | partial | block | progress - nativeTransport: true, // usa a API nativa de streaming do Slack quando mode=partial + nativeTransport: true, // use Slack native streaming API when mode=partial }, mediaMaxMb: 20, execApprovals: { @@ -464,30 +464,30 @@ O WhatsApp funciona por meio do canal web do Gateway (Baileys Web). Ele inicia a } ``` -- **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). +- **Socket mode** requer `botToken` e `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` para fallback por variável de ambiente da conta padrão). +- **HTTP mode** requer `botToken` mais `signingSecret` (na raiz ou por conta). - `botToken`, `appToken`, `signingSecret` e `userToken` aceitam strings em texto simples ou objetos SecretRef. -- Snapshots de conta do Slack expõem campos por credencial de origem/status, como `botTokenSource`, `botTokenStatus`, `appTokenStatus` e, no modo HTTP, `signingSecretStatus`. `configured_unavailable` significa que a conta está configurada via SecretRef, mas o caminho atual de comando/runtime não conseguiu resolver o valor do segredo. +- Snapshots de conta do Slack expõem campos por credencial de origem/status, como `botTokenSource`, `botTokenStatus`, `appTokenStatus` e, em **HTTP mode**, `signingSecretStatus`. `configured_unavailable` significa que a conta está configurada por SecretRef, mas o caminho atual de comando/runtime não conseguiu resolver o valor do segredo. - `configWrites: false` bloqueia gravações de configuração iniciadas pelo Slack. -- `channels.slack.defaultAccount` opcional sobrescreve 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 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. +- O opcional `channels.slack.defaultAccount` 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 streaming do Slack. `channels.slack.streaming.nativeTransport` controla o transporte nativo de streaming do Slack. Os valores legados `streamMode`, booleanos `streaming` e `nativeStreaming` são migrados automaticamente. +- Use `user:` (DM) ou `channel:` para alvos de entrega. **Modos de notificação de reação:** `off`, `own` (padrão), `all`, `allowlist` (de `reactionAllowlist`). -**Isolamento de sessão por thread:** `thread.historyScope` é por thread (padrão) ou compartilhado no 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. -- Streaming nativo do Slack, junto com o status em thread no estilo “is typing...” do assistente do Slack, requer um destino 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 em estilo thread. -- `typingReaction` adiciona uma reação temporária à mensagem recebida do Slack enquanto uma resposta está em execução e depois a remove na conclusão. Use um shortcode de emoji do Slack, como `"hourglass_flowing_sand"`. -- `channels.slack.execApprovals`: entrega nativa de aprovações 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 requerem 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évia no estilo thread. +- `typingReaction` adiciona uma reação temporária à mensagem recebida no Slack enquanto uma resposta está em execução e a remove quando termina. Use um shortcode de emoji do Slack como `"hourglass_flowing_sand"`. +- `channels.slack.execApprovals`: entrega nativa do Slack para aprovações de execução 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 | 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 | +| Grupo de ações | 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 | ### Mattermost @@ -511,7 +511,7 @@ O Mattermost é distribuído como Plugin: `openclaw plugins install @openclaw/ma 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, @@ -521,18 +521,19 @@ O Mattermost é distribuído como Plugin: `openclaw plugins install @openclaw/ma } ``` -Modos de chat: `oncall` (responde em @-mention, padrão), `onmessage` (toda mensagem), `onchar` (mensagens que começam com prefixo de gatilho). +Modos de chat: `oncall` (responde em @mention, padrão), `onmessage` (toda mensagem), `onchar` (mensagens que começam com 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 deve 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 `Unauthorized: invalid command token.` -- Para hosts de callback privados/tailnet/internos, o Mattermost pode exigir que `ServiceSettings.AllowedUntrustedInternalConnections` inclua o host/domínio de callback. Use valores de host/domínio, não URLs completas. -- `channels.mattermost.configWrites`: 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`: sobrescrita por canal para exigência de menção (`"*"` como padrão). -- `channels.mattermost.defaultAccount` opcional sobrescreve a seleção de conta padrão quando corresponde a um ID de conta configurado. +- `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 comando de barra. Se o registro falhar ou nenhum comando for ativado, o OpenClaw rejeitará callbacks com `Unauthorized: invalid command token.` +- Para hosts de callback privados/tailnet/internos, o Mattermost pode exigir que `ServiceSettings.AllowedUntrustedInternalConnections` inclua o host/domínio do callback. + Use valores de host/domínio, não URLs completas. +- `channels.mattermost.configWrites`: permite ou nega gravações de configuração iniciadas pelo Mattermost. +- `channels.mattermost.requireMention`: exige `@mention` antes de responder em canais. +- `channels.mattermost.groups..requireMention`: substituição de bloqueio por menção por canal (`"*"` para padrão). +- O opcional `channels.mattermost.defaultAccount` substitui a seleção de conta padrão quando corresponde a um ID de conta configurado. ### Signal @@ -541,7 +542,7 @@ Quando os comandos nativos do Mattermost estão habilitados: channels: { signal: { enabled: true, - account: "+15555550123", // vínculo de conta opcional + account: "+15555550123", // optional account binding dmPolicy: "pairing", allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"], configWrites: true, @@ -555,13 +556,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 em uma identidade de conta específica do Signal. +- `channels.signal.account`: fixa a inicialização do canal a uma identidade específica de conta Signal. - `channels.signal.configWrites`: permite ou nega gravações de configuração iniciadas pelo Signal. -- `channels.signal.defaultAccount` opcional sobrescreve a seleção de conta padrão quando corresponde a um ID de conta configurado. +- O opcional `channels.signal.defaultAccount` 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 por Plugin, configurado em `channels.bluebubbles`). +BlueBubbles é o caminho recomendado para iMessage (baseado em Plugin, configurado em `channels.bluebubbles`). ```json5 { @@ -569,21 +570,21 @@ BlueBubbles é o caminho recomendado para iMessage (com suporte por Plugin, conf bluebubbles: { enabled: true, dmPolicy: "pairing", - // serverUrl, password, webhookPath, controles de grupo e ações avançadas: - // consulte /channels/bluebubbles + // serverUrl, password, webhookPath, group controls, and advanced actions: + // see /channels/bluebubbles }, }, } ``` -- Caminhos de chave principal cobertos aqui: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. -- `channels.bluebubbles.defaultAccount` opcional sobrescreve a seleção de conta padrão quando corresponde a um ID de conta configurado. -- Entradas `bindings[]` no nível superior com `type: "acp"` podem vincular conversas do BlueBubbles a sessões ACP persistentes. 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). +- Caminhos de chave principais cobertos aqui: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. +- O opcional `channels.bluebubbles.defaultAccount` substitui a seleção de conta padrão quando corresponde a um ID de conta configurado. +- Entradas de nível superior `bindings[]` com `type: "acp"` podem vincular conversas do BlueBubbles a sessões persistentes de ACP. Use um identificador ou string de alvo 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 -O OpenClaw inicia `imsg rpc` (JSON-RPC sobre stdio). Nenhum daemon ou porta é necessário. +O OpenClaw inicia `imsg rpc` (JSON-RPC por stdio). Nenhum daemon ou porta é necessário. ```json5 { @@ -607,17 +608,17 @@ O OpenClaw inicia `imsg rpc` (JSON-RPC sobre stdio). Nenhum daemon ou porta é n } ``` -- `channels.imessage.defaultAccount` opcional sobrescreve a seleção de conta padrão quando corresponde a um ID de conta configurado. +- O opcional `channels.imessage.defaultAccount` substitui a seleção de conta padrão quando corresponde a um ID de conta configurado. -- Requer Full Disk Access ao banco de dados do Messages. -- Prefira destinos `chat_id:`. Use `imsg chats --limit 20` para listar chats. +- Requer Acesso Total ao Disco ao banco de dados do Messages. +- Prefira alvos `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. - `attachmentRoots` e `remoteAttachmentRoots` restringem caminhos de anexos recebidos (padrão: `/Users/*/Library/Messages/Attachments`). -- O SCP usa verificação estrita de chave de host, então garanta que a chave do host de relay já exista em `~/.ssh/known_hosts`. +- O SCP usa verificação estrita de chave do host, então garanta que a chave do host 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[]` no nível superior com `type: "acp"` podem vincular conversas do iMessage a sessões ACP persistentes. Use um identificador normalizado ou um destino de chat explícito (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) em `match.peer.id`. Semântica compartilhada dos campos: [ACP Agents](/pt-BR/tools/acp-agents#channel-specific-settings). +- Entradas de nível superior `bindings[]` com `type: "acp"` podem vincular conversas do iMessage a sessões persistentes de ACP. Use um identificador normalizado ou alvo explícito de conversa (`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). - + ```bash #!/usr/bin/env bash @@ -628,7 +629,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -O Matrix tem suporte por extensão e é configurado em `channels.matrix`. +O Matrix é baseado em extensão e configurado em `channels.matrix`. ```json5 { @@ -659,24 +660,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 sobrescrevê-lo com `channels.matrix.accounts..proxy`. -- `channels.matrix.network.dangerouslyAllowPrivateNetwork` permite homeservers privados/internos. `proxy` e esse opt-in 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 substituí-lo com `channels.matrix.accounts..proxy`. +- `channels.matrix.network.dangerouslyAllowPrivateNetwork` permite homeservers privados/internos. `proxy` e essa ativação de rede são controles independentes. - `channels.matrix.defaultAccount` seleciona a conta preferida em configurações com várias contas. -- `channels.matrix.autoJoin` tem como padrão `off`, então salas convidadas e convites novos no estilo DM são ignorados até você definir `autoJoin: "allowlist"` com `autoJoinAllowlist` ou `autoJoin: "always"`. -- `channels.matrix.execApprovals`: entrega nativa de aprovações 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 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 de todos os agentes. +- `channels.matrix.autoJoin` usa `off` por padrão, então salas convidadas e novos convites em estilo DM são ignorados até que você defina `autoJoin: "allowlist"` com `autoJoinAllowlist` ou `autoJoin: "always"`. +- `channels.matrix.execApprovals`: entrega nativa do Matrix para aprovações de execução e autorização de aprovadores. + - `enabled`: `true`, `false` ou `"auto"` (padrão). No modo automático, as aprovações de execução são ativadas quando os aprovadores podem ser resolvidos a partir de `approvers` ou `commands.ownerAllowFrom`. + - `approvers`: IDs de usuário Matrix (por exemplo `@owner:example.org`) autorizados a aprovar solicitações de execução. + - `agentFilter`: lista de permissões opcional de IDs de agentes. Omita para encaminhar aprovações para todos os agentes. - `sessionFilter`: padrões opcionais de chave de sessão (substring ou regex). - `target`: onde enviar os prompts de aprovação. `"dm"` (padrão), `"channel"` (sala de origem) ou `"both"`. - - Sobrescritas por conta: `channels.matrix.accounts..execApprovals`. + - 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 pesquisas em diretório ao vivo usam a mesma política de proxy do tráfego em runtime. -- A configuração completa do Matrix, regras de destino e exemplos de configuração estão documentados em [Matrix](/pt-BR/channels/matrix). +- Sondas de status do Matrix e pesquisas de diretório ao vivo usam a mesma política de proxy do tráfego de runtime. +- 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`. +O Microsoft Teams é baseado em extensão e configurado em `channels.msteams`. ```json5 { @@ -684,19 +685,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: - // consulte /channels/msteams + // appId, appPassword, tenantId, webhook, team/channel policies: + // see /channels/msteams }, }, } ``` -- Caminhos de chave principal cobertos aqui: `channels.msteams`, `channels.msteams.configWrites`. -- A configuração completa do Teams (credenciais, webhook, política de DM/grupo, sobrescritas por equipe/canal) está documentada em [Microsoft Teams](/pt-BR/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). ### IRC -O IRC tem suporte por extensão e é configurado em `channels.irc`. +O IRC é baseado em extensão e configurado em `channels.irc`. ```json5 { @@ -717,9 +718,9 @@ O IRC tem suporte por extensão e é configurado em `channels.irc`. } ``` -- Caminhos de chave principal cobertos aqui: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. -- `channels.irc.defaultAccount` opcional sobrescreve a seleção de conta padrão quando corresponde a um ID de conta configurado. -- A configuração completa do canal IRC (host/porta/TLS/canais/allowlists/exigência de menção) está documentada em [IRC](/pt-BR/channels/irc). +- Caminhos de chave principais cobertos aqui: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. +- O opcional `channels.irc.defaultAccount` substitui a seleção de conta padrão quando corresponde a um ID de conta configurado. +- A configuração completa do canal IRC (host/porta/TLS/canais/listas de permissões/bloqueio por menção) está documentada em [IRC](/pt-BR/channels/irc). ### Várias contas (todos os canais) @@ -731,11 +732,11 @@ Execute várias contas por canal (cada uma com seu próprio `accountId`): telegram: { accounts: { default: { - name: "Bot principal", + name: "Primary bot", botToken: "123456:ABC...", }, alerts: { - name: "Bot de alertas", + name: "Alerts bot", botToken: "987654:XYZ...", }, }, @@ -746,26 +747,26 @@ Execute várias contas por canal (cada uma com seu próprio `accountId`): - `default` é usado quando `accountId` é omitido (CLI + roteamento). - Tokens de ambiente se aplicam apenas à conta **default**. -- As configurações base do canal se aplicam a todas as contas, a menos que sejam sobrescritas por conta. +- As configurações básicas do canal se aplicam a todas as contas, a menos que sejam substituídas por conta. - Use `bindings[].match.accountId` para rotear cada conta para um agente diferente. -- Se você adicionar uma conta não padrão via `openclaw channels add` (ou onboarding de canal) enquanto ainda estiver em uma configuração de canal de conta única no nível superior, o OpenClaw primeiro promove os valores de conta única no nível superior com escopo de conta para o mapa de contas do canal, para que a conta original continue funcionando. A maioria dos canais move esses valores para `channels..accounts.default`; o Matrix pode preservar um destino nomeado/default correspondente já existente. -- Associações existentes apenas de canal (sem `accountId`) continuam correspondendo à conta padrão; associações 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 destino nomeado/default correspondente já existente. +- Se você adicionar uma conta não padrão via `openclaw channels add` (ou onboarding de canal) enquanto ainda estiver em uma configuração de canal de conta única no 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. +- Os 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 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 de canal dedicadas (por exemplo Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat e Twitch). +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). -### Exigência de menção em conversas em grupo +### Bloqueio por menção em conversas de grupo -As mensagens de grupo, por padrão, **exigem menção** (menção em metadados ou padrões regex seguros). Aplica-se a conversas em grupo de WhatsApp, Telegram, Discord, Google Chat e iMessage. +Mensagens de grupo usam **exigir menção** por padrão (menção por metadados ou padrões regex seguros). Aplica-se a conversas em grupo de WhatsApp, Telegram, Discord, Google Chat e iMessage. **Tipos de menção:** -- **Menções em metadados**: @-mentions nativas da plataforma. Ignoradas no modo de conversa consigo mesmo do WhatsApp. +- **Menções por metadados**: @-mentions nativas 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. -- A exigência de menção só é aplicada quando a detecção é possível (menções nativas ou pelo menos um padrão). +- O bloqueio por menção é aplicado apenas quando a detecção é possível (menções nativas ou pelo menos um padrão). ```json5 { @@ -778,7 +779,7 @@ As mensagens de grupo, por padrão, **exigem menção** (menção em metadados o } ``` -`messages.groupChat.historyLimit` define o padrão global. Os canais podem sobrescrever com `channels..historyLimit` (ou por conta). Defina `0` para desabilitar. +`messages.groupChat.historyLimit` define o padrão global. Os canais podem substituir com `channels..historyLimit` (ou por conta). Defina `0` para desativar. #### Limites de histórico de DM @@ -795,7 +796,7 @@ As mensagens de grupo, por padrão, **exigem menção** (menção em metadados o } ``` -Resolução: sobrescrita por DM → padrão do provedor → sem limite (tudo retido). +Resolução: substituição por DM → padrão do provedor → sem limite (tudo é mantido). Compatível com: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`. @@ -827,16 +828,16 @@ Inclua seu próprio número em `allowFrom` para habilitar o modo de conversa con ```json5 { commands: { - native: "auto", // registra comandos nativos quando compatível - nativeSkills: "auto", // registra comandos nativos de Skills quando compatível - text: true, // analisa /commands em mensagens de chat - bash: false, // permite ! (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, // permite /config - mcp: false, // permite /mcp - plugins: false, // permite /plugins - debug: false, // permite /debug - restart: true, // permite /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}", @@ -851,27 +852,27 @@ Inclua seu próprio número em `allowFrom` para habilitar o modo de conversa con -- Este bloco configura superfícies de comando. Para o catálogo atual de comandos internos + bundled, 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 também em [Slash Commands](/pt-BR/tools/slash-commands). +- Este bloco configura superfícies de comando. Para o catálogo atual de comandos internos + bundled, consulte [Comandos de barra](/pt-BR/tools/slash-commands). +- Esta página é uma **referência de chaves de configuração**, não o catálogo completo de comandos. Comandos pertencentes a canais/plugins como QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone` e Talk `/voice` estão documentados em suas páginas de canal/plugin, além de [Comandos de barra](/pt-BR/tools/slash-commands). - Comandos de texto devem ser mensagens **independentes** com `/` no início. -- `native: "auto"` ativa comandos nativos para Discord/Telegram e mantém o Slack desativado. -- `nativeSkills: "auto"` ativa comandos nativos de Skills para Discord/Telegram e mantém o Slack desativado. -- Sobrescrita por canal: `channels.discord.commands.native` (bool ou `"auto"`). `false` limpa comandos registrados anteriormente. -- Sobrescreva o registro nativo de Skills por canal com `channels..commands.nativeSkills`. +- `native: "auto"` ativa comandos nativos para Discord/Telegram e deixa o Slack desativado. +- `nativeSkills: "auto"` ativa comandos nativos de Skills para Discord/Telegram e deixa o 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 de `/config set|unset` também exigem `operator.admin`; `/config show` somente leitura continua disponível para clientes operadores normais com escopo de gravação. -- `mcp: true` habilita `/mcp` para a configuração de servidores MCP gerenciados pelo OpenClaw em `mcp.servers`. -- `plugins: true` habilita `/plugins` para descoberta, instalação e controles de habilitar/desabilitar plugins. +- `config: true` habilita `/config` (lê/grava `openclaw.json`). Para clientes `chat.send` do gateway, gravações persistentes de `/config set|unset` também exigem `operator.admin`; `/config show` somente leitura continua disponível para clientes normais de operador com escopo de gravação. +- `mcp: true` habilita `/mcp` para a configuração de servidor MCP gerenciada pelo OpenClaw em `mcp.servers`. +- `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 àquela 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 allowlist explícita de proprietários para comandos/ferramentas exclusivos do proprietário. Ela é separada de `allowFrom`. -- `ownerDisplay: "hash"` aplica hash aos IDs do proprietário no prompt do sistema. Defina `ownerDisplaySecret` para controlar o hashing. -- `allowFrom` é por provedor. Quando definido, é a **única** fonte de autorização (allowlists/pareamento de 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` desativa `/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 aos 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 comandos ignorem políticas de grupos de acesso quando `allowFrom` não está definido. - Mapa da documentação de comandos: - - catálogo interno + bundled: [Slash Commands](/pt-BR/tools/slash-commands) + - catálogo interno + bundled: [Comandos de barra](/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) @@ -882,7 +883,7 @@ Inclua seu próprio número em `allowFrom` para habilitar o modo de conversa con --- -## Padrões de agente +## Padrões do agente ### `agents.defaults.workspace` @@ -896,7 +897,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 mostrada na linha Runtime do prompt do sistema. Se não estiver definida, o OpenClaw detecta automaticamente subindo a partir do workspace. ```json5 { @@ -906,7 +907,7 @@ Raiz opcional do repositório exibida na linha Runtime do prompt do sistema. Se ### `agents.defaults.skills` -Allowlist padrão opcional de Skills para agentes que não definem +Lista opcional padrão de permissões de Skills para agentes que não definem `agents.list[].skills`. ```json5 @@ -924,12 +925,13 @@ Allowlist 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 aquele agente; ela não é mesclada com os padrões. +- Defina `agents.list[].skills: []` para nenhuma Skills. +- Uma lista não vazia em `agents.list[].skills` é o conjunto final para aquele agente; ela + não é mesclada com os padrões. ### `agents.defaults.skipBootstrap` -Desabilita a criação automática de arquivos bootstrap do workspace (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`). +Desativa a criação automática de arquivos bootstrap do workspace (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`). ```json5 { @@ -941,7 +943,7 @@ Desabilita a criação automática de arquivos bootstrap do workspace (`AGENTS.m Controla quando os arquivos bootstrap do workspace são injetados no prompt do sistema. Padrão: `"always"`. -- `"continuation-skip"`: turnos de continuação seguros (após uma resposta concluída do assistente) pulam a reinjeção do bootstrap do workspace, reduzindo o tamanho do prompt. Execuções de Heartbeat e retries após Compaction ainda recompõem o contexto. +- `"continuation-skip"`: turnos seguros de continuação (após uma resposta concluída do assistente) ignoram a reinjeção do bootstrap do workspace, reduzindo o tamanho do prompt. Execuções de Heartbeat e novas tentativas após Compaction ainda recriam o contexto. ```json5 { @@ -951,7 +953,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 de truncamento. Padrão: `12000`. +Máximo de caracteres por arquivo bootstrap do workspace antes do truncamento. Padrão: `12000`. ```json5 { @@ -988,30 +990,31 @@ Padrão: `"once"`. O OpenClaw tem vários orçamentos de prompt/contexto de alto volume, e eles são intencionalmente divididos por subsistema em vez de passarem todos por um único -parâmetro genérico. +ajuste genérico. - `agents.defaults.bootstrapMaxChars` / `agents.defaults.bootstrapTotalMaxChars`: injeção normal de bootstrap do workspace. - `agents.defaults.startupContext.*`: - prelúdio inicial de uso único para `/new` e `/reset`, incluindo arquivos - recentes `memory/*.md` do dia. + prelúdio de inicialização único de `/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 runtime e blocos injetados pertencentes ao runtime. - `memory.qmd.limits.*`: - dimensionamento de trechos e injeções de busca de memória indexada. + dimensionamento de snippets e injeção de busca de memória indexada. -Use a sobrescrita correspondente por agente apenas quando um agente precisar de -um orçamento diferente: +Use a substituição correspondente por agente somente quando um agente precisar de um +orçamento diferente: - `agents.list[].skillsLimits.maxSkillsPromptChars` - `agents.list[].contextLimits.*` #### `agents.defaults.startupContext` -Controla o prelúdio inicial de primeira interação injetado em execuções simples de `/new` e `/reset`. +Controla o prelúdio de inicialização do primeiro turno injetado em execuções +simples de `/new` e `/reset`. ```json5 { @@ -1049,14 +1052,19 @@ Padrões compartilhados para superfícies de contexto limitadas em runtime. } ``` -- `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 em tempo real do resultado de ferramenta usado para resultados persistidos e recuperação de overflow. -- `postCompactionMaxChars`: limite de trecho de AGENTS.md usado durante a injeção de atualização após Compaction. +- `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 em tempo real de resultado de ferramenta usado para resultados + persistidos e recuperação de overflow. +- `postCompactionMaxChars`: limite de trecho de AGENTS.md usado durante a injeção + de atualização pós-Compaction. #### `agents.list[].contextLimits` -Sobrescrita por agente para os parâmetros compartilhados de `contextLimits`. Campos omitidos herdam de `agents.defaults.contextLimits`. +Substituição por agente para os ajustes compartilhados de `contextLimits`. Campos omitidos herdam +de `agents.defaults.contextLimits`. ```json5 { @@ -1097,7 +1105,7 @@ não afeta a leitura de arquivos `SKILL.md` sob demanda. #### `agents.list[].skillsLimits.maxSkillsPromptChars` -Sobrescrita por agente para o orçamento de prompt de Skills. +Substituição por agente para o orçamento de prompt de Skills. ```json5 { @@ -1116,10 +1124,10 @@ Sobrescrita por agente para o orçamento de prompt de Skills. ### `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 lado mais longo da imagem em blocos de imagem de transcript/ferramenta antes de chamadas ao provedor. Padrão: `1200`. -Valores menores geralmente reduzem o uso de tokens de visão e o tamanho do payload da requisição em execuções com muitas capturas de tela. +Valores menores geralmente reduzem o uso de tokens de visão e o tamanho da carga da solicitação em execuções com muitas capturas de tela. Valores maiores preservam mais detalhes visuais. ```json5 @@ -1130,7 +1138,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 os timestamps das mensagens). Usa o fuso horário do host como fallback. ```json5 { @@ -1180,7 +1188,7 @@ Formato de hora no prompt do sistema. Padrão: `auto` (preferência do SO). }, params: { cacheRetention: "long" }, // parâmetros globais padrão do provedor embeddedHarness: { - runtime: "auto", // auto | pi | id registrado do harness, por exemplo codex + runtime: "auto", // auto | pi | registered harness id, e.g. codex fallback: "pi", // pi | none }, pdfMaxBytesMb: 10, @@ -1198,48 +1206,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 de string define apenas o modelo principal. - - A forma de objeto define o principal mais modelos ordenados de failover. + - A forma string define apenas o modelo principal. + - A forma objeto define o principal mais modelos ordenados de failover. - `imageModel`: aceita uma string (`"provider/model"`) ou um objeto (`{ primary, fallbacks }`). - Usado pelo caminho da ferramenta `image` como sua configuração de modelo de visão. - - Também usado como roteamento de fallback quando o modelo selecionado/padrão não pode aceitar entrada de imagem. + - Também usado como roteamento de fallback quando o modelo selecionado/padrão não aceita entrada de imagem. - `imageGenerationModel`: aceita uma string (`"provider/model"`) ou um objeto (`{ primary, fallbacks }`). - - Usado pela capacidade compartilhada de geração de imagens 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 imagens do Gemini, `fal/fal-ai/flux/dev` para fal, ou `openai/gpt-image-1` para OpenAI Images. - - Se você selecionar um provider/model 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. Ele tenta primeiro o provedor padrão atual e depois os demais provedores registrados de geração de imagem em ordem de 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 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, depois os provedores restantes 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 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 provedor padrão com autenticação. Ele tenta primeiro o provedor padrão atual e depois os demais provedores registrados de geração de música em ordem de ID do provedor. - - Se você selecionar um provider/model diretamente, configure também a autenticação/chave de API correspondente do provedor. + - Se omitido, `music_generate` ainda pode inferir um padrão de provedor com autenticação. Ele tenta primeiro o provedor padrão atual, depois os provedores restantes 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. - `videoGenerationModel`: aceita uma string (`"provider/model"`) ou um objeto (`{ primary, fallbacks }`). - 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 provedor padrão com autenticação. Ele tenta primeiro o provedor padrão atual e depois os demais provedores registrados de geração de vídeo em ordem de ID do provedor. - - Se você selecionar um provider/model diretamente, configure também a autenticação/chave de API correspondente do provedor. - - O provedor bundled 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 no nível do provedor `size`, `aspectRatio`, `resolution`, `audio` e `watermark`. + - Se omitido, `video_generate` ainda pode inferir um padrão de provedor com autenticação. Ele tenta primeiro o provedor padrão atual, depois os provedores restantes 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 oferece suporte a até 1 vídeo de saída, 1 imagem de entrada, 4 vídeos de entrada, duração de 10 segundos e opções no nível do 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 usa `imageModel` como fallback e depois o modelo resolvido da sessão/padrão. + - Se omitido, a ferramenta PDF recorre a `imageModel` e depois ao modelo padrão/de sessão resolvido. - `pdfMaxBytesMb`: limite padrão de tamanho de PDF para a ferramenta `pdf` quando `maxBytesMb` não é passado no momento da chamada. - `pdfMaxPages`: máximo padrão de páginas consideradas pelo modo de fallback de extração na ferramenta `pdf`. -- `verboseDefault`: nível detalhado padrão para agentes. Valores: `"off"`, `"on"`, `"full"`. Padrão: `"off"`. +- `verboseDefault`: nível 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` (ex.: `openai/gpt-5.4`). Se você omitir o provedor, o OpenClaw tenta primeiro um alias, depois uma correspondência única de provedor configurado para aquele ID exato de modelo e só então usa o provedor padrão configurado como fallback (comportamento legado de compatibilidade, portanto prefira `provider/model` explícito). Se esse provedor não expuser mais o modelo padrão configurado, o OpenClaw usa como fallback o primeiro provider/model configurado em vez de expor um padrão obsoleto de provedor removido. -- `models`: o catálogo de modelos configurado e a allowlist para `/model`. Cada entrada pode incluir `alias` (atalho) e `params` (específicos do provedor, por exemplo `temperature`, `maxTokens`, `cacheRetention`, `context1m`). -- `params`: parâmetros globais padrão do provedor aplicados a todos os modelos. Definidos em `agents.defaults.params` (ex.: `{ cacheRetention: "long" }`). -- 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 incorporado de baixo nível. Use `runtime: "auto"` para permitir que harnesses de plugins registrados reivindiquem 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 add/remove de fallback) salvam a forma canônica de objeto e preservam listas de fallback existentes quando possível. +- `model.primary`: formato `provider/model` (por exemplo `openai/gpt-5.4`). Se você omitir o provedor, o OpenClaw primeiro tenta um alias, depois uma correspondência exclusiva de provedor configurado para esse ID de modelo exato 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`). +- `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` (configuração): `agents.defaults.params` (base global) é substituído por `agents.defaults.models["provider/model"].params` (por modelo), então `agents.list[].params` (ID do agente correspondente) substitui por chave. Consulte [Prompt Caching](/pt-BR/reference/prompt-caching) para detalhes. +- `embeddedHarness`: política padrão do runtime incorporado de baixo nível do agente. 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 desativar 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 interações de agentes incorporados. +`embeddedHarness` controla qual executor de baixo nível executa turnos de agentes incorporados. 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 aplicativos Codex. +Use isso quando um Plugin confiável fornecer um harness nativo, como o harness bundled +Codex app-server. ```json5 { @@ -1255,13 +1263,13 @@ do servidor de aplicativos 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 interno como fallback de compatibilidade. `"none"` faz com que a seleção de harness de plugin ausente ou incompatível falhe em vez de usar PI silenciosamente. -- Sobrescritas 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"`. +- `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 interno como fallback de compatibilidade. `"none"` faz com que a seleção ausente ou não compatível de harness de Plugin falhe em vez de usar PI silenciosamente. +- Substituições por ambiente: `OPENCLAW_AGENT_RUNTIME=` substitui `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=none` desativa o fallback para PI nesse processo. +- Para implantações somente Codex, defina `model: "codex/gpt-5.4"`, `embeddedHarness.runtime: "codex"` e `embeddedHarness.fallback: "none"`. - Isso controla apenas o harness de chat incorporado. Geração de mídia, visão, PDF, música, vídeo e TTS ainda usam suas configurações de provider/model. -**Atalhos de alias internos** (aplicam-se apenas quando o modelo está em `agents.defaults.models`): +**Atalhos internos de alias** (aplicam-se apenas quando o modelo está em `agents.defaults.models`): | Alias | Modelo | | ------------------- | -------------------------------------- | @@ -1276,13 +1284,13 @@ do servidor de aplicativos Codex. Seus aliases configurados sempre prevalecem sobre os padrões. -Os modelos Z.AI GLM-4.x ativam automaticamente o modo thinking, a menos que você defina `--thinking off` ou configure `agents.defaults.models["zai/"].params.thinking` manualmente. -Os modelos Z.AI ativam `tool_stream` por padrão para streaming de chamadas de ferramenta. Defina `agents.defaults.models["zai/"].params.tool_stream` como `false` para desabilitá-lo. -Os modelos Anthropic Claude 4.6 usam por padrão thinking `adaptive` quando nenhum nível explícito de thinking é definido. +Modelos GLM-4.x da Z.AI ativam automaticamente o modo thinking, a menos que você defina `--thinking off` ou configure `agents.defaults.models["zai/"].params.thinking` por conta própria. +Modelos Z.AI ativam `tool_stream` por padrão para streaming de chamadas de ferramenta. Defina `agents.defaults.models["zai/"].params.tool_stream` como `false` para desativá-lo. +Modelos Claude 4.6 da Anthropic usam `adaptive` como padrão para thinking quando nenhum nível explícito é definido. ### `agents.defaults.cliBackends` -Backends CLI opcionais para execuções de fallback somente texto (sem chamadas de ferramenta). Útil como backup quando provedores de API falham. +Backends CLI opcionais para execuções de fallback somente texto (sem chamadas de ferramenta). Úteis como backup quando provedores de API falham. ```json5 { @@ -1310,13 +1318,13 @@ Backends CLI opcionais para execuções de fallback somente texto (sem chamadas } ``` -- Backends CLI são voltados primeiro para texto; ferramentas são sempre desabilitadas. +- Backends CLI são voltados principalmente para texto; ferramentas sempre ficam desativadas. - Sessões são compatíveis quando `sessionArg` está definido. -- Passagem de imagens é compatível quando `imageArg` aceita caminhos de arquivo. +- Pass-through de imagem é compatível quando `imageArg` aceita caminhos de arquivo. ### `agents.defaults.systemPromptOverride` -Substitui todo o prompt de sistema montado pelo OpenClaw por uma string fixa. Defina no nível padrão (`agents.defaults.systemPromptOverride`) ou por agente (`agents.list[].systemPromptOverride`). Valores por agente têm precedência; um valor vazio ou apenas 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 { @@ -1337,17 +1345,17 @@ 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 | ... - prompt: "Leia HEARTBEAT.md se ele existir...", + 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, timeoutSeconds: 45, @@ -1357,15 +1365,15 @@ 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 payloads de aviso de erro de ferramenta durante execuções de Heartbeat. -- `timeoutSeconds`: tempo máximo em segundos permitido para uma interação de agente de Heartbeat antes de ela ser abortada. Deixe sem definir para usar `agents.defaults.timeoutSeconds`. -- `directPolicy`: política de entrega direta/DM. `allow` (padrão) permite entrega para destino direto. `block` suprime entrega para destino direto e emite `reason=dm-blocked`. +- `every`: string de duração (ms/s/m/h). Padrão: `30m` (autenticação por chave de API) ou `1h` (autenticação OAuth). Defina `0m` para desativar. +- `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 a alvo direto. `block` suprime entrega a alvo direto e emite `reason=dm-blocked`. - `lightContext`: quando true, execuções de Heartbeat usam contexto bootstrap leve e mantêm apenas `HEARTBEAT.md` dos 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`, **somente esses agentes** executam Heartbeats. -- Heartbeats executam interações completas de agente — intervalos menores consomem mais tokens. +- `isolatedSession`: quando true, cada Heartbeat é executado em uma sessão nova sem histórico prévio 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`, **somente esses agentes** executam Heartbeat. +- Heartbeats executam turnos completos de agente — intervalos mais curtos consomem mais tokens. ### `agents.defaults.compaction` @@ -1375,19 +1383,19 @@ Execuções periódicas de Heartbeat. defaults: { compaction: { mode: "safeguard", // default | safeguard - provider: "my-provider", // id de um Plugin 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 exatamente IDs de implantação, IDs de tickets e pares host:porta.", // usado quando identifierPolicy=custom - postCompactionSections: ["Session Startup", "Red Lines"], // [] desabilita reinjeção - model: "openrouter/anthropic/claude-sonnet-4-6", // sobrescrita 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, - systemPrompt: "Sessão próxima de Compaction. Armazene memórias duráveis agora.", - prompt: "Escreva quaisquer notas duradouras em memory/YYYY-MM-DD.md; responda com o token silencioso exato NO_REPLY se não houver nada para armazenar.", + systemPrompt: "Session nearing compaction. Store durable memories now.", + prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with the exact silent token NO_REPLY if nothing to store.", }, }, }, @@ -1395,19 +1403,19 @@ 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 provedor de Compaction registrado. Quando definido, `summarize()` do provedor é chamado em vez da sumarização LLM interna. Em caso de falha, usa a implementação interna 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 que o OpenClaw a aborte. Padrão: `900`. -- `identifierPolicy`: `strict` (padrão), `off` ou `custom`. `strict` adiciona orientação interna de retenção de identificadores opacos durante a sumarização de Compaction. +- `mode`: `default` ou `safeguard` (resumo em partes para históricos longos). Consulte [Compaction](/pt-BR/concepts/compaction). +- `provider`: ID de um Plugin de provedor de Compaction registrado. Quando definido, `summarize()` do provedor é chamado em vez do resumo LLM interno. Em caso de falha, recorre ao interno. 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 que o OpenClaw a interrompa. Padrão: `900`. +- `identifierPolicy`: `strict` (padrão), `off` ou `custom`. `strict` adiciona instruções internas de preservação de identificadores opacos durante o resumo 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 com esse par padrão, os cabeçalhos antigos `Every Session`/`Safety` também são aceitos como fallback legado. -- `model`: sobrescrita 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 executar em 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, "Compactando contexto..."). Desabilitado por padrão para manter a Compaction silenciosa. -- `memoryFlush`: turno agentivo silencioso antes da Compaction automática para armazenar memórias duráveis. Ignorado quando o workspace é somente leitura. +- `postCompactionSections`: nomes opcionais de seções H2/H3 de AGENTS.md para reinjetar após Compaction. O padrão é `["Session Startup", "Red Lines"]`; defina `[]` para desativar a reinjeção. Quando não definido ou explicitamente definido para esse par padrão, cabeçalhos antigos `Every Session`/`Safety` também são aceitos como fallback legado. +- `model`: substituição opcional de `provider/model-id` apenas para resumo de Compaction. Use isso quando a sessão principal deve manter um modelo, mas os resumos de Compaction devem executar em outro; quando não definido, a Compaction usa o modelo principal da sessão. +- `notifyUser`: quando `true`, envia um breve aviso ao usuário quando a Compaction começa (por exemplo, "Compactando contexto..."). Desativado por padrão para manter a Compaction silenciosa. +- `memoryFlush`: turno agentic silencioso antes da auto-Compaction 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 de enviar ao LLM. **Não** modifica o histórico da sessão em disco. ```json5 { @@ -1415,13 +1423,13 @@ 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, minPrunableToolChars: 50000, softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 }, - hardClear: { enabled: true, placeholder: "[Conteúdo antigo de resultado de ferramenta removido]" }, + hardClear: { enabled: true, placeholder: "[Old tool result content cleared]" }, tools: { deny: ["browser", "canvas"] }, }, }, @@ -1433,15 +1441,15 @@ Remove **resultados antigos de ferramentas** do contexto em memória antes de en - `mode: "cache-ttl"` habilita passagens de poda. - `ttl` controla com que frequência a poda pode ser executada novamente (após o último toque no cache). -- A poda primeiro faz soft-trim de resultados de ferramentas superdimensionados e depois faz hard-clear de resultados mais antigos, se necessário. +- A poda primeiro faz um corte suave em resultados de ferramentas superdimensionados e depois limpa completamente resultados mais antigos, se necessário. -**Soft-trim** mantém o início + o fim e insere `...` no meio. +**Corte suave** mantém o início + o fim e insere `...` no meio. -**Hard-clear** substitui todo o resultado da ferramenta pelo placeholder. +**Limpeza completa** substitui todo o resultado da ferramenta pelo placeholder. Observações: -- Blocos de imagem nunca são reduzidos/removidos. +- Blocos de imagem nunca são cortados/limpos. - As proporções são baseadas em caracteres (aproximadas), não em contagens exatas de tokens. - Se existirem menos de `keepLastAssistants` mensagens do assistente, a poda é ignorada. @@ -1449,7 +1457,7 @@ Observações: Consulte [Session Pruning](/pt-BR/concepts/session-pruning) para detalhes de comportamento. -### Streaming em bloco +### Streaming em blocos ```json5 { @@ -1466,10 +1474,10 @@ Consulte [Session Pruning](/pt-BR/concepts/session-pruning) para detalhes de com ``` - Canais que não sejam Telegram exigem `*.blockStreaming: true` explícito para habilitar respostas em bloco. -- Sobrescritas por canal: `channels..blockStreamingCoalesce` (e variantes por conta). Signal/Slack/Discord/Google Chat usam por padrão `minChars: 1500`. -- `humanDelay`: pausa aleatória entre respostas em bloco. `natural` = 800–2500ms. Sobrescrita por agente: `agents.list[].humanDelay`. +- Substituições por canal: `channels..blockStreamingCoalesce` (e variantes por conta). Signal/Slack/Discord/Google Chat usam por padrão `minChars: 1500`. +- `humanDelay`: pausa aleatória entre respostas em bloco. `natural` = 800–2500ms. Substituição por agente: `agents.list[].humanDelay`. -Consulte [Streaming](/pt-BR/concepts/streaming) para comportamento e detalhes de fragmentação. +Consulte [Streaming](/pt-BR/concepts/streaming) para detalhes de comportamento + fragmentação. ### Indicadores de digitação @@ -1484,8 +1492,8 @@ Consulte [Streaming](/pt-BR/concepts/streaming) para comportamento e detalhes de } ``` -- Padrões: `instant` para chats diretos/menções, `message` para chats em grupo sem menção. -- Sobrescritas por sessão: `session.typingMode`, `session.typingIntervalSeconds`. +- Padrões: `instant` para conversas diretas/menções, `message` para conversas em grupo sem menção. +- Substituições por sessão: `session.typingMode`, `session.typingIntervalSeconds`. Consulte [Typing Indicators](/pt-BR/concepts/typing-indicators). @@ -1539,7 +1547,7 @@ Sandbox opcional para o agente incorporado. Consulte [Sandboxing](/pt-BR/gateway identityFile: "~/.ssh/id_ed25519", certificateFile: "~/.ssh/id_ed25519-cert.pub", knownHostsFile: "~/.ssh/known_hosts", - // SecretRefs / conteúdos inline 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" }, @@ -1592,11 +1600,11 @@ Sandbox opcional para o agente incorporado. Consulte [Sandboxing](/pt-BR/gateway **Backend:** -- `docker`: runtime local do Docker (padrão) -- `ssh`: runtime remoto genérico com suporte por SSH +- `docker`: runtime Docker local (padrão) +- `ssh`: runtime remoto genérico baseado em SSH - `openshell`: runtime OpenShell -Quando `backend: "openshell"` é selecionado, as configurações específicas de runtime passam para +Quando `backend: "openshell"` é selecionado, as configurações específicas do runtime vão para `plugins.entries.openshell.config`. **Configuração do backend SSH:** @@ -1605,29 +1613,29 @@ Quando `backend: "openshell"` é selecionado, as configurações específicas de - `command`: comando do cliente SSH (padrão: `ssh`) - `workspaceRoot`: raiz remota absoluta usada para workspaces por escopo - `identityFile` / `certificateFile` / `knownHostsFile`: arquivos locais existentes passados ao OpenSSH -- `identityData` / `certificateData` / `knownHostsData`: conteúdos inline ou SecretRefs que o OpenClaw materializa em arquivos temporários em runtime -- `strictHostKeyChecking` / `updateHostKeys`: parâmetros de política de chave de host do OpenSSH +- `identityData` / `certificateData` / `knownHostsData`: conteúdo embutido ou SecretRefs que o OpenClaw materializa em arquivos temporários em runtime +- `strictHostKeyChecking` / `updateHostKeys`: ajustes de política de chave de host do OpenSSH **Precedência de autenticação SSH:** - `identityData` prevalece sobre `identityFile` - `certificateData` prevalece sobre `certificateFile` - `knownHostsData` prevalece sobre `knownHostsFile` -- Valores `*Data` com suporte por SecretRef são resolvidos a partir do snapshot ativo do runtime de segredos antes do início da sessão sandbox +- Valores `*Data` baseados em 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 +- inicializa o workspace remoto uma vez após criar ou recriar - depois mantém o workspace SSH remoto como canônico -- roteia `exec`, ferramentas de arquivo e caminhos de mídia via SSH +- roteia `exec`, ferramentas de arquivo e caminhos de mídia por SSH - não sincroniza automaticamente mudanças remotas de volta para o host -- não oferece suporte a contêineres de navegador sandbox +- não oferece suporte a contêineres de navegador no 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` -- `rw`: workspace do agente montado em `/workspace` com leitura/gravação +- `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 em leitura/gravação em `/workspace` **Escopo:** @@ -1648,10 +1656,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, }, @@ -1663,30 +1671,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 e depois mantém o workspace remoto como canônico +- `mirror`: inicializa o remoto a partir do local antes de `exec`, sincroniza de volta após `exec`; o workspace local continua sendo o canônico +- `remote`: inicializa o remoto uma vez quando o sandbox é criado e depois mantém o workspace remoto como canônico -No modo `remote`, edições locais do host feitas fora do OpenClaw não são sincronizadas automaticamente para o sandbox após a etapa inicial. -O transporte é SSH para o sandbox OpenShell, mas o Plugin controla o ciclo de vida do sandbox e a sincronização espelho opcional. +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 inicialização. +O transporte é SSH para dentro do sandbox OpenShell, mas o Plugin controla o ciclo de vida do sandbox e a sincronização opcional de espelho. -**`setupCommand`** executa uma vez após a criação do contêiner (via `sh -lc`). Requer saída de rede, raiz gravável e usuário root. +**`setupCommand`** é 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. -**Por padrão, os contêineres usam `network: "none"`** — defina `"bridge"` (ou uma rede bridge personalizada) se o agente precisar de acesso de saída. +**Os contêineres usam `network: "none"` por padrão** — defina como `"bridge"` (ou uma rede bridge personalizada) se o agente precisar de acesso de saída. `"host"` é bloqueado. `"container:"` é bloqueado por padrão, a menos que você defina explicitamente `sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (break-glass). -**Anexos de entrada** são preparados em `media/inbound/*` no workspace ativo. +**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. +**`docker.binds`** monta diretórios adicionais do host; montagens globais e por agente são mescladas. -**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). +**Navegador em sandbox** (`sandbox.browser.enabled`): Chromium + CDP em um contêiner. URL do noVNC injetada no prompt do sistema. Não requer `browser.enabled` em `openclaw.json`. +O acesso de observador no 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 segmentarem o navegador do host. -- `network` usa por padrão `openclaw-sandbox-browser` (rede bridge dedicada). Defina `bridge` apenas quando você quiser explicitamente conectividade global de bridge. -- `cdpSourceRange` restringe opcionalmente a entrada CDP na borda do contêiner a um intervalo CIDR (por exemplo `172.21.0.1/32`). -- `sandbox.browser.binds` monta diretórios adicionais do host apenas no contêiner do navegador em sandbox. Quando definido (inclusive `[]`), substitui `docker.binds` para o contêiner do navegador. -- Os padrões de inicialização são definidos em `scripts/sandbox-browser-entrypoint.sh` e ajustados para hosts de contêiner: +- `allowHostControl: false` (padrão) bloqueia sessões em sandbox de terem como alvo o navegador do host. +- `network` usa `openclaw-sandbox-browser` por padrão (rede bridge dedicada). Defina como `bridge` apenas quando você quiser explicitamente conectividade global de bridge. +- `cdpSourceRange` restringe opcionalmente 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 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êiner: - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` @@ -1703,31 +1711,30 @@ O acesso de observador via noVNC usa autenticação VNC por padrão e o OpenClaw - `--renderer-process-limit=2` - `--no-zygote` - `--metrics-recording-only` - - `--disable-extensions` (habilitado por padrão) + - `--disable-extensions` (ativado por padrão) - `--disable-3d-apis`, `--disable-software-rasterizer` e `--disable-gpu` são - habilitados por padrão e podem ser desabilitados com + ativados por padrão e podem ser desativados com `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` se o uso de WebGL/3D exigir isso. - - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` reabilita extensões se o seu fluxo de trabalho + - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` reabilita extensões se seu fluxo de trabalho depender delas. - `--renderer-process-limit=2` pode ser alterado com `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; defina `0` para usar o - limite padrão de processos do Chromium. - - mais `--no-sandbox` e `--disable-setuid-sandbox` quando `noSandbox` 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. + limite de processos padrão do Chromium. + - mais `--no-sandbox` e `--disable-setuid-sandbox` quando `noSandbox` estiver ativado. + - 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 exclusivos do Docker. +O sandbox de navegador e `sandbox.docker.binds` são compatíveis apenas com Docker. -Crie as imagens: +Criar imagens: ```bash scripts/sandbox-setup.sh # imagem principal do sandbox scripts/sandbox-browser-setup.sh # imagem opcional do navegador ``` -### `agents.list` (sobrescritas por agente) +### `agents.list` (substituições por agente) ```json5 { @@ -1739,13 +1746,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", // sobrescrita por agente do nível de thinking - reasoningDefault: "on", // sobrescrita por agente da visibilidade de reasoning - fastModeDefault: false, // sobrescrita por agente do modo rápido + 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" }, // sobrescreve agents.defaults.models params correspondentes por chave - 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", @@ -1777,19 +1784,19 @@ scripts/sandbox-browser-setup.sh # imagem opcional do navegador ``` - `id`: ID estável do agente (obrigatório). -- `default`: quando vários estão definidos, o primeiro prevalece (um aviso é registrado). Se nenhum estiver definido, a primeira entrada da lista é o padrão. -- `model`: a forma de string sobrescreve apenas `primary`; a forma de objeto `{ primary, fallbacks }` sobrescreve ambos (`[]` desabilita fallbacks globais). Tarefas de Cron que sobrescrevem apenas `primary` ainda herdam fallbacks padrão, a menos que você defina `fallbacks: []`. -- `params`: parâmetros de stream por agente mesclados sobre a entrada de modelo selecionada em `agents.defaults.models`. Use isto para sobrescritas 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`: sobrescrita opcional por agente do nível padrão de thinking (`off | minimal | low | medium | high | xhigh | adaptive`). Sobrescreve `agents.defaults.thinkingDefault` para esse agente quando nenhuma sobrescrita por mensagem ou sessão estiver definida. -- `reasoningDefault`: sobrescrita opcional por agente da visibilidade padrão de reasoning (`on | off | stream`). Aplica-se quando nenhuma sobrescrita de reasoning por mensagem ou sessão estiver definida. -- `fastModeDefault`: padrão opcional por agente para o modo rápido (`true | false`). Aplica-se quando nenhuma sobrescrita de modo rápido por mensagem ou sessão estiver definida. -- `embeddedHarness`: sobrescrita opcional por agente da política de harness de baixo nível. Use `{ runtime: "codex", fallback: "none" }` para tornar um agente exclusivo de 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 `runtime.acp` (`agent`, `backend`, `mode`, `cwd`) quando o agente deve usar por padrão sessões de harness ACP. +- `default`: quando vários são definidos, o primeiro prevalece (aviso registrado). Se nenhum for definido, a primeira entrada da lista é o padrão. +- `model`: a forma string substitui apenas `primary`; a forma objeto `{ primary, fallbacks }` substitui ambos (`[]` desativa fallbacks globais). Jobs Cron que substituem apenas `primary` ainda herdam os fallbacks padrão, a menos que você defina `fallbacks: []`. +- `params`: parâmetros de stream por agente mesclados sobre a entrada de modelo selecionada em `agents.defaults.models`. Use isto para substituições específicas do agente, como `cacheRetention`, `temperature` ou `maxTokens`, sem duplicar todo o catálogo de modelos. +- `skills`: lista opcional de permissões de Skills por agente. Se omitida, o agente herda `agents.defaults.skills` quando definido; uma lista explícita substitui os padrões em vez de mesclar, e `[]` significa nenhuma Skills. +- `thinkingDefault`: nível thinking padrão opcional por agente (`off | minimal | low | medium | high | xhigh | adaptive`). Substitui `agents.defaults.thinkingDefault` para este agente quando nenhuma substituição por mensagem ou sessão estiver definida. +- `reasoningDefault`: visibilidade reasoning padrão opcional por agente (`on | off | stream`). Aplica-se quando nenhuma substituição de reasoning por mensagem ou sessão estiver definida. +- `fastModeDefault`: padrão opcional por agente para modo rápido (`true | false`). Aplica-se quando nenhuma substituição de modo rápido por mensagem ou sessão estiver definida. +- `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 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 de `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` a partir de `emoji`, `mentionPatterns` a partir de `name`/`emoji`. -- `subagents.allowAgents`: allowlist de IDs de agente para `sessions_spawn` (`["*"]` = qualquer; padrão: apenas o mesmo agente). -- Proteção de herança de sandbox: se a sessão solicitante estiver em sandbox, `sessions_spawn` rejeita destinos que executariam sem sandbox. +- `identity` deriva padrões: `ackReaction` de `emoji`, `mentionPatterns` de `name`/`emoji`. +- `subagents.allowAgents`: lista de permissões de IDs de agentes para `sessions_spawn` (`["*"]` = qualquer; 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 `sessions_spawn` que omitem `agentId` (força seleção explícita de perfil; padrão: false). --- @@ -1815,11 +1822,11 @@ 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 (tipo ausente usa `route` por padrão), `acp` para bindings persistentes de conversa ACP. +- `type` (opcional): `route` para roteamento normal (tipo ausente assume route), `acp` para vínculos persistentes de conversa ACP. - `match.channel` (obrigatório) - `match.accountId` (opcional; `*` = qualquer conta; omitido = conta padrão) - `match.peer` (opcional; `{ kind: direct|group|channel, id }`) -- `match.guildId` / `match.teamId` (opcional; específicos do canal) +- `match.guildId` / `match.teamId` (opcional; específico do canal) - `acp` (opcional; apenas para entradas `type: "acp"`): `{ mode, label, cwd, backend }` **Ordem determinística de correspondência:** @@ -1828,12 +1835,12 @@ Execute vários agentes isolados dentro de um Gateway. Consulte [Multi-Agent](/p 2. `match.guildId` 3. `match.teamId` 4. `match.accountId` (exato, sem peer/guild/team) -5. `match.accountId: "*"` (para o canal inteiro) +5. `match.accountId: "*"` (em todo o canal) 6. Agente padrão Dentro de cada nível, a primeira entrada correspondente em `bindings` prevalece. -Para entradas `type: "acp"`, o OpenClaw resolve pela identidade exata da conversa (`match.channel` + conta + `match.peer.id`) e não usa a ordem de níveis de binding de rota acima. +Para entradas `type: "acp"`, o OpenClaw resolve por identidade exata da conversa (`match.channel` + conta + `match.peer.id`) e não usa a ordem de níveis de binding de rota acima. ### Perfis de acesso por agente @@ -1956,22 +1963,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 da thread pai acima dessa 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" } }], @@ -1983,35 +1990,35 @@ Consulte [Multi-Agent Sandbox & Tools](/pt-BR/tools/multi-agent-sandbox-tools) p -- **`scope`**: estratégia base de agrupamento de sessão para contextos de conversa em grupo. +- **`scope`**: estratégia base de agrupamento de sessões para contextos de conversa 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-channel-peer`: isola por canal + remetente (recomendado para caixas de entrada multiusuário). + - `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ô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 que expirar primeiro prevalece. -- **`resetByType`**: sobrescritas por tipo (`direct`, `group`, `thread`). O valor legado `dm` é aceito como alias para `direct`. -- **`parentForkMaxTokens`**: máximo de `totalTokens` da sessão pai permitido ao criar uma sessão de thread bifurcada (padrão `100000`). - - Se o `totalTokens` da sessão pai estiver acima desse valor, o OpenClaw inicia uma sessão de thread nova em vez de herdar o histórico de transcrição da sessão pai. - - Defina `0` para desabilitar essa proteção e sempre permitir bifurcação da sessão pai. +- **`reset`**: política principal de redefinição. `daily` redefine em `atHour` no horário local; `idle` redefine após `idleMinutes`. Quando ambos estão configurados, o que expirar primeiro prevalece. +- **`resetByType`**: substituições por tipo (`direct`, `group`, `thread`). O legado `dm` é aceito como alias para `direct`. +- **`parentForkMaxTokens`**: `totalTokens` máximo permitido na sessão pai ao criar uma sessão de thread bifurcada (padrão `100000`). + - Se `totalTokens` da sessão pai estiver acima desse valor, o OpenClaw inicia uma nova sessão de thread em vez de herdar o histórico da transcrição da sessão pai. + - Defina `0` para desativar essa proteção e sempre permitir bifurcação da sessão pai. - **`mainKey`**: campo legado. O runtime sempre usa `"main"` para o bucket principal de chat direto. -- **`agentToAgent.maxPingPongTurns`**: número máximo de turnos de resposta de volta entre agentes durante trocas agent-to-agent (inteiro, intervalo: `0`–`5`). `0` desabilita encadeamento ping-pong. +- **`agentToAgent.maxPingPongTurns`**: número máximo de turnos de resposta entre agentes durante trocas entre agentes (inteiro, intervalo: `0`–`5`). `0` desativa o encadeamento ping-pong. - **`sendPolicy`**: 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. +- **`maintenance`**: controles de limpeza + retenção do armazenamento de sessões. - `mode`: `warn` emite apenas avisos; `enforce` aplica a limpeza. - `pruneAfter`: limite de idade para entradas obsoletas (padrão `30d`). - `maxEntries`: número máximo de entradas em `sessions.json` (padrão `500`). - `rotateBytes`: rotaciona `sessions.json` quando ele excede esse tamanho (padrão `10mb`). - - `resetArchiveRetention`: retenção para arquivos de transcrição `*.reset.`. Usa `pruneAfter` por padrão; defina `false` para desabilitar. + - `resetArchiveRetention`: retenção para arquivos de transcrição `*.reset.`. Usa `pruneAfter` por padrão; defina `false` para desativar. - `maxDiskBytes`: orçamento opcional de disco para o diretório de sessões. No modo `warn`, registra avisos; no modo `enforce`, remove primeiro os artefatos/sessões mais antigos. - - `highWaterBytes`: alvo opcional após limpeza do orçamento. O padrão é `80%` de `maxDiskBytes`. + - `highWaterBytes`: alvo opcional após a limpeza do orçamento. O padrão é `80%` de `maxDiskBytes`. - **`threadBindings`**: padrões globais para recursos de sessão vinculados a thread. - - `enabled`: chave mestra padrão (os provedores podem sobrescrever; o Discord usa `channels.discord.threadBindings.enabled`) - - `idleHours`: padrão de desfoco automático por inatividade em horas (`0` desabilita; os provedores podem sobrescrever) - - `maxAgeHours`: padrão de idade máxima rígida em horas (`0` desabilita; os provedores podem sobrescrever) + - `enabled`: chave mestre padrão (provedores podem substituir; o Discord usa `channels.discord.threadBindings.enabled`) + - `idleHours`: desfoco automático padrão por inatividade em horas (`0` desativa; provedores podem substituir) + - `maxAgeHours`: idade máxima rígida padrão em horas (`0` desativa; provedores podem substituir) @@ -2022,7 +2029,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, @@ -2037,7 +2044,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, @@ -2049,9 +2056,9 @@ Consulte [Multi-Agent Sandbox & Tools](/pt-BR/tools/multi-agent-sandbox-tools) p ### Prefixo de resposta -Sobrescritas por canal/conta: `channels..responsePrefix`, `channels..accounts..responsePrefix`. +Substituições por canal/conta: `channels..responsePrefix`, `channels..accounts..responsePrefix`. -Resolução (a mais específica prevalece): conta → canal → global. `""` desabilita e interrompe a cascata. `"auto"` deriva `[{identity.name}]`. +Resolução (a mais específica prevalece): conta → canal → global. `""` desativa e interrompe a cascata. `"auto"` deriva `[{identity.name}]`. **Variáveis de template:** @@ -2061,24 +2068,24 @@ Resolução (a mais específica prevalece): conta → canal → global. `""` des | `{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"`) | +| `{identity.name}` | Nome de identidade do agente | (igual a `"auto"`) | -As variáveis não diferenciam maiúsculas de minúsculas. `{think}` é um alias para `{thinkingLevel}`. +As variáveis não diferenciam maiúsculas de minúsculas. `{think}` é um alias de `{thinkingLevel}`. -### Reação de ack +### Reação de confirmação -- Usa por padrão `identity.emoji` do agente ativo ou `"👀"` caso contrário. Defina `""` para desabilitar. -- Sobrescritas por canal: `channels..ackReaction`, `channels..accounts..ackReaction`. -- Ordem de resolução: conta → canal → `messages.ackReaction` → fallback da identidade. +- Usa por padrão `identity.emoji` do agente ativo; caso contrário, `"👀"`. Defina `""` para desativar. +- Substituições por canal: `channels..ackReaction`, `channels..accounts..ackReaction`. +- Ordem de resolução: conta → canal → `messages.ackReaction` → fallback de identidade. - Escopo: `group-mentions` (padrão), `group-all`, `direct`, `all`. -- `removeAckAfterReply`: remove o ack após a resposta no Slack, Discord e Telegram. -- `messages.statusReactions.enabled`: habilita reações de status de ciclo de vida no Slack, Discord e Telegram. - No Slack e no Discord, quando não definido, mantém as reações de status habilitadas quando reações de ack estão ativas. - No Telegram, defina explicitamente como `true` para habilitar reações de status de ciclo de vida. +- `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, se não estiver 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 do 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 são descarregados imediatamente. Comandos de controle ignoram o debounce. +Agrupa mensagens rápidas somente de texto do mesmo remetente em um único turno do agente. Mídia/anexos são descarregados imediatamente. Comandos de controle ignoram o debounce. ### TTS (texto para fala) @@ -2121,11 +2128,11 @@ Agrupa mensagens rápidas somente de texto do mesmo remetente em um único turno } ``` -- `auto` controla o modo padrão de auto-TTS: `off`, `always`, `inbound` ou `tagged`. `/tts on|off` pode sobrescrever preferências locais, e `/tts status` mostra o estado efetivo. -- `summaryModel` sobrescreve `agents.defaults.model.primary` para resumo automático. -- `modelOverrides` é habilitado por padrão; `modelOverrides.allowProvider` usa `false` como padrão (opt-in). -- As chaves de API usam como fallback `ELEVENLABS_API_KEY`/`XI_API_KEY` e `OPENAI_API_KEY`. -- `openai.baseUrl` sobrescreve o endpoint TTS da OpenAI. A ordem de resolução é config, depois `OPENAI_TTS_BASE_URL`, depois `https://api.openai.com/v1`. +- `auto` controla o modo padrão de auto-TTS: `off`, `always`, `inbound` ou `tagged`. `/tts on|off` pode substituir preferências locais, e `/tts status` mostra o estado efetivo. +- `summaryModel` substitui `agents.defaults.model.primary` para resumo automático. +- `modelOverrides` é habilitado por padrão; `modelOverrides.allowProvider` usa `false` por padrão (opt-in). +- As chaves de API usam `ELEVENLABS_API_KEY`/`XI_API_KEY` e `OPENAI_API_KEY` como fallback. +- `openai.baseUrl` substitui o endpoint TTS do 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 flexibiliza a validação de modelo/voz. --- @@ -2158,45 +2165,45 @@ 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 legadas planas 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 como fallback `ELEVENLABS_VOICE_ID` ou `SAG_VOICE_ID`. +- IDs de voz usam `ELEVENLABS_VOICE_ID` ou `SAG_VOICE_ID` como fallback. - `providers.*.apiKey` aceita strings em texto simples ou objetos SecretRef. -- O fallback `ELEVENLABS_API_KEY` se aplica apenas quando nenhuma chave de API de Talk estiver configurada. +- O fallback `ELEVENLABS_API_KEY` se aplica apenas quando nenhuma chave de API de Talk está configurada. - `providers.*.voiceAliases` permite que diretivas de Talk usem nomes amigáveis. -- `silenceTimeoutMs` controla quanto tempo o modo Talk espera após o silêncio do usuário antes de enviar a transcrição. Quando não definido, mantém a janela de pausa padrão da plataforma (`700 ms no macOS e Android, 900 ms no iOS`). +- `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 estiver definido, mantém a janela de pausa padrão da plataforma (`700 ms no macOS e Android, 900 ms no iOS`). --- ## Ferramentas -### Perfis de ferramenta +### Perfis de ferramentas -`tools.profile` define uma allowlist base antes de `tools.allow`/`tools.deny`: +`tools.profile` define uma lista base de permissões antes de `tools.allow`/`tools.deny`: O onboarding local define novas configurações locais por padrão como `tools.profile: "coding"` quando não definido (perfis explícitos existentes são preservados). -| Perfil | Inclui | -| ----------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `minimal` | apenas `session_status` | +| Perfil | Inclui | +| ----------- | ------------------------------------------------------------------------------------------------------------------------------- | +| `minimal` | somente `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 definido) | ### Grupos de ferramentas -| Grupo | Ferramentas | -| ------------------ | ----------------------------------------------------------------------------------------------------------------------- | -| `group:runtime` | `exec`, `process`, `code_execution` (`bash` é aceito como alias para `exec`) | -| `group:fs` | `read`, `write`, `edit`, `apply_patch` | +| Grupo | Ferramentas | +| ------------------ | -------------------------------------------------------------------------------------------------------------------- | +| `group:runtime` | `exec`, `process`, `code_execution` (`bash` é aceito como alias 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 internas (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` @@ -2210,7 +2217,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 → allow/deny. +Restringe ainda mais ferramentas para provedores ou modelos específicos. Ordem: perfil base → perfil do provedor → permitir/negar. ```json5 { @@ -2226,7 +2233,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 { @@ -2242,9 +2249,9 @@ Controla acesso elevado de exec fora do sandbox: } ``` -- A sobrescrita por agente (`agents.list[].tools.elevated`) só pode restringir ainda mais. -- `/elevated on|off|ask|full` armazena estado por sessão; diretivas inline se aplicam a uma única mensagem. -- `exec` elevado ignora o sandbox e usa o caminho de escape configurado (`gateway` por padrão, ou `node` quando o destino de exec é `node`). +- A substituição por agente (`agents.list[].tools.elevated`) só pode restringir ainda mais. +- `/elevated on|off|ask|full` armazena o estado por sessão; diretivas inline se aplicam a uma única mensagem. +- `exec` elevado ignora o sandbox e usa o caminho de escape configurado (`gateway` por padrão ou `node` quando o alvo de execução é `node`). ### `tools.exec` @@ -2268,8 +2275,8 @@ Controla acesso elevado de exec fora do sandbox: ### `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`. +As verificações de segurança de loop de ferramenta são **desativadas por padrão**. Defina `enabled: true` para ativar a detecção. +As configurações podem ser definidas globalmente em `tools.loopDetection` e substituídas por agente em `agents.list[].tools.loopDetection`. ```json5 { @@ -2290,13 +2297,13 @@ As configurações podem ser definidas globalmente em `tools.loopDetection` e so } ``` -- `historySize`: máximo de histórico de chamadas de ferramenta retido para análise de loop. +- `historySize`: máximo de histórico de chamadas de ferramenta mantido para análise de loop. - `warningThreshold`: limite de padrão repetitivo sem progresso para avisos. - `criticalThreshold`: limite repetitivo mais alto para bloquear loops críticos. -- `globalCircuitBreakerThreshold`: limite de parada rígida para qualquer execução sem progresso. +- `globalCircuitBreakerThreshold`: limite de interrupção rígida para qualquer execução sem progresso. - `detectors.genericRepeat`: avisa sobre chamadas repetidas da mesma ferramenta/com os mesmos argumentos. -- `detectors.knownPollNoProgress`: avisa/bloqueia ferramentas conhecidas de polling (`process.poll`, `command_status` etc.). -- `detectors.pingPong`: avisa/bloqueia padrões alternados de par sem progresso. +- `detectors.knownPollNoProgress`: avisa/bloqueia ferramentas de polling conhecidas (`process.poll`, `command_status` etc.). +- `detectors.pingPong`: avisa/bloqueia padrões alternados em par sem progresso. - Se `warningThreshold >= criticalThreshold` ou `criticalThreshold >= globalCircuitBreakerThreshold`, a validação falha. ### `tools.web` @@ -2307,14 +2314,14 @@ As configurações podem ser definidas globalmente em `tools.loopDetection` e so web: { search: { enabled: true, - apiKey: "brave_api_key", // ou variável de ambiente 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, @@ -2331,7 +2338,7 @@ As configurações podem ser definidas globalmente em `tools.loopDetection` e so ### `tools.media` -Configura compreensão de mídia de entrada (imagem/áudio/vídeo): +Configura o entendimento de mídia recebida (imagem/áudio/vídeo): ```json5 { @@ -2339,7 +2346,7 @@ Configura compreensão de mídia de entrada (imagem/áudio/vídeo): media: { concurrency: 2, asyncCompletion: { - directSend: false, // opt-in: 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, @@ -2363,32 +2370,32 @@ Configura compreensão de mídia de entrada (imagem/áudio/vídeo): } ``` - + **Entrada de provedor** (`type: "provider"` ou omitido): - `provider`: ID do provedor de API (`openai`, `anthropic`, `google`/`gemini`, `groq` etc.) -- `model`: sobrescrita do ID do modelo +- `model`: substituição de ID de modelo - `profile` / `preferredProfile`: seleção de perfil em `auth-profiles.json` **Entrada CLI** (`type: "cli"`): - `command`: executável a ser executado -- `args`: argumentos com template (suporta `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` etc.) +- `args`: argumentos com template (compatível com `{{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`: sobrescritas por entrada. -- Falhas usam a próxima entrada como fallback. +- `capabilities`: lista opcional (`image`, `audio`, `video`). Padrões: `openai`/`anthropic`/`minimax` → imagem, `google` → imagem+áudio+vídeo, `groq` → áudio. +- `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: substituições por entrada. +- Falhas recorrem à próxima entrada. A autenticação do provedor segue a ordem padrão: `auth-profiles.json` → variáveis de ambiente → `models.providers.*.apiKey`. **Campos de conclusão assíncrona:** -- `asyncCompletion.directSend`: quando `true`, tarefas concluídas de `music_generate` - e `video_generate` tentam primeiro entrega direta ao canal. Padrão: `false` - (caminho legado de ativação de sessão solicitante/entrega por modelo). +- `asyncCompletion.directSend`: quando `true`, tarefas assíncronas concluídas de `music_generate` + e `video_generate` tentam primeiro entrega direta no canal. Padrão: `false` + (caminho legado de despertar da sessão solicitante/entrega pelo modelo). @@ -2407,9 +2414,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 iniciadas por ela, como subagentes). +Padrão: `tree` (sessão atual + sessões geradas por ela, como subagentes). ```json5 { @@ -2425,25 +2432,25 @@ Padrão: `tree` (sessão atual + sessões iniciadas por ela, como subagentes). Observações: - `self`: apenas a chave da sessão atual. -- `tree`: sessão atual + sessões iniciadas pela sessão atual (subagentes). +- `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). -- `all`: qualquer sessão. O direcionamento entre agentes ainda requer `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 se `tools.sessions.visibility="all"`. +- `all`: qualquer sessão. O direcionamento entre agentes ainda exige `tools.agentToAgent`. +- Limitação por sandbox: quando a sessão atual está em sandbox e `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, a visibilidade é forçada para `tree` mesmo se `tools.sessions.visibility="all"`. ### `tools.sessions_spawn` -Controla suporte a anexos inline para `sessions_spawn`. +Controla o suporte a anexos inline para `sessions_spawn`. ```json5 { tools: { sessions_spawn: { attachments: { - enabled: false, // opt-in: 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" }, }, }, @@ -2454,20 +2461,20 @@ 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`. -- O conteúdo dos anexos é automaticamente redigido da persistência da transcrição. -- Entradas em Base64 são validadas com verificações rígidas de alfabeto/padding e uma proteção de tamanho antes da decodificação. +- O conteúdo do anexo é automaticamente redigido da persistência da transcrição. +- Entradas Base64 são validadas com verificações estritas de alfabeto/preenchimento e uma 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 retém apenas quando `retainOnSessionKeep: true`. +- A limpeza segue a política `cleanup`: `delete` sempre remove anexos; `keep` os mantém somente quando `retainOnSessionKeep: true`. ### `tools.experimental` -Flags experimentais de ferramentas internas. Padrão desativado, a menos que uma regra de autoativação estrita agentic GPT-5 se aplique. +Sinalizadores experimentais de ferramentas internas. Padrão desativado, a menos que uma regra de ativação automática rígida agentic do GPT-5 se aplique. ```json5 { tools: { experimental: { - planTool: true, // habilita o experimental update_plan + planTool: true, // enable experimental update_plan }, }, } @@ -2475,9 +2482,9 @@ Flags experimentais de ferramentas internas. Padrão desativado, a menos que uma Observações: -- `planTool`: habilita a ferramenta estruturada `update_plan` para acompanhamento de trabalho não trivial em várias etapas. -- Padrão: `false`, a menos que `agents.defaults.embeddedPi.executionContract` (ou uma sobrescrita 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 ativação da ferramenta fora desse escopo, ou `false` para mantê-la desativada mesmo em execuções GPT-5 strict-agentic. -- Quando habilitado, o prompt do sistema também adiciona orientação de uso para que o modelo a utilize apenas em trabalho substancial e mantenha no máximo uma etapa `in_progress`. +- `planTool`: habilita a ferramenta estruturada experimental `update_plan` para acompanhamento 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 ativação da ferramenta fora desse escopo, ou `false` para mantê-la desativada mesmo para execuções GPT-5 strict-agentic. +- Quando habilitado, o prompt do sistema também adiciona orientação de uso para que o modelo só a use em trabalho substancial e mantenha no máximo uma etapa `in_progress`. ### `agents.defaults.subagents` @@ -2497,8 +2504,8 @@ Observações: } ``` -- `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; padrão: apenas o mesmo agente). +- `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 agentes de destino para `sessions_spawn` quando o agente solicitante não define seu próprio `subagents.allowAgents` (`["*"]` = qualquer; 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 ferramenta por subagente: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. @@ -2511,7 +2518,7 @@ O OpenClaw usa o catálogo interno de modelos. Adicione provedores personalizado ```json5 { models: { - mode: "merge", // merge (padrão) | replace + mode: "merge", // merge (default) | replace providers: { "custom-proxy": { baseUrl: "http://localhost:4000/v1", @@ -2536,22 +2543,22 @@ O OpenClaw usa o catálogo interno de modelos. Adicione provedores personalizado ``` - Use `authHeader: true` + `headers` para necessidades de autenticação personalizadas. -- Sobrescreva a raiz de configuração do agente com `OPENCLAW_AGENT_DIR` (ou `PI_CODING_AGENT_DIR`, um alias legado de variável de ambiente). +- 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 em `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 configuração/perfil de autenticação. - - Valores `apiKey` de provedor gerenciados por SecretRef são atualizados a partir de marcadores de origem (`ENV_VAR_NAME` para refs de ambiente, `secretref-managed` para refs de arquivo/exec) em vez de persistir segredos resolvidos. - - Valores de 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` do agente vazios ou ausentes usam `models.providers` da configuração como fallback. - - `contextWindow`/`maxTokens` de modelo correspondente usam o maior valor entre a configuração explícita e os 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. + - Valores não vazios de `baseUrl` em `models.json` do agente prevalecem. + - Valores não vazios de `apiKey` do agente prevalecem apenas quando esse provedor não é gerenciado por SecretRef no contexto atual de configuração/perfil de autenticação. + - Valores `apiKey` de provedores 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 provedores 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 correspondentes usam o valor mais alto entre a configuração explícita e os valores implícitos do catálogo. + - `contextTokens` de modelo correspondente preserva um limite explícito de runtime quando presente; use-o para limitar o contexto efetivo sem alterar os metadados nativos do modelo. - Use `models.mode: "replace"` quando quiser que a configuração reescreva totalmente `models.json`. - - A persistência de marcadores é autoritativa em relação à 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. + - A persistência de marcadores é autoritativa à origem: os marcadores são gravados a partir do snapshot ativo da configuração de origem (pré-resolução), não a partir de valores secretos resolvidos em runtime. ### Detalhes dos campos do provedor - `models.mode`: comportamento do catálogo de provedores (`merge` ou `replace`). -- `models.providers`: mapa de provedores personalizados indexado por ID do provedor. +- `models.providers`: mapa de provedores personalizados indexado por ID de 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`). @@ -2559,26 +2566,26 @@ O OpenClaw usa o catálogo interno de modelos. Adicione provedores personalizado - `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 de proxy/tenant. -- `models.providers.*.request`: sobrescritas de transporte para requisições HTTP do model-provider. +- `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`: sobrescrita da estratégia de autenticação. Modos: `"provider-default"` (usa a autenticação interna do provedor), `"authorization-bearer"` (com `token`), `"header"` (com `headerName`, `value` e `prefix` opcional). - - `request.proxy`: sobrescrita 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`: sobrescrita 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 similares, por meio da proteção de fetch HTTP do provedor (opt-in do operador para endpoints compatíveis com OpenAI self-hosted confiáveis). O WebSocket usa o mesmo `request` para cabeçalhos/TLS, mas não essa proteção SSRF de fetch. Padrão `false`. + - `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 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 faixas privadas, CGNAT ou similares, por meio da proteção SSRF de fetch HTTP do provedor (opt-in do operador para endpoints OpenAI-compatíveis auto-hospedados confiáveis). O WebSocket usa o mesmo `request` para cabeçalhos/TLS, mas não essa proteção 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 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 puramente textuais de `messages[].content` em strings simples antes de enviar a requisição. -- `plugins.entries.amazon-bedrock.config.discovery`: raiz de configurações de autodescoberta do Bedrock. -- `plugins.entries.amazon-bedrock.config.discovery.enabled`: ativa/desativa descoberta implícita. +- `models.providers.*.models.*.contextTokens`: limite opcional de contexto em runtime. Use isso quando quiser um orçamento efetivo de contexto menor que `contextWindow` nativo do modelo. +- `models.providers.*.models.*.compat.supportsDeveloperRole`: dica opcional de compatibilidade. Para `api: "openai-completions"` com `baseUrl` não nativo não vazio (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 OpenAI-compatíveis que aceitam somente string. Quando `true`, o OpenClaw transforma arrays `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`: liga/desliga a 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.providerFilter`: filtro opcional por ID de provedor para descoberta direcionada. - `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: intervalo de polling para atualização da descoberta. - `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 @@ -2631,7 +2638,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 referências `opencode-go/...` para o catálogo Go. Atalho: `openclaw onboard --auth-choice opencode-zen` ou `openclaw onboard --auth-choice opencode-go`. @@ -2651,8 +2658,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 coding (padrão): `https://api.z.ai/api/coding/paas/v4` -- Para o endpoint geral, defina um provedor personalizado com a sobrescrita de URL base. +- Endpoint de código (padrão): `https://api.z.ai/api/coding/paas/v4` +- Para o endpoint geral, defina um provedor personalizado com substituição de URL base. @@ -2693,9 +2700,9 @@ 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`. -Os endpoints nativos do Moonshot anunciam compatibilidade de uso de streaming no transporte compartilhado +Os endpoints nativos da Moonshot anunciam compatibilidade de uso de streaming no transporte compartilhado `openai-completions`, e o OpenClaw baseia isso nas capacidades do endpoint -em vez de apenas no ID do provedor interno. +em vez de apenas no ID interno do provedor. @@ -2752,7 +2759,7 @@ Compatível com Anthropic, provedor interno. Atalho: `openclaw onboard --auth-ch } ``` -A URL base deve omitir `/v1` (o cliente Anthropic o acrescenta). Atalho: `openclaw onboard --auth-choice synthetic-api-key`. +A URL base deve omitir `/v1` (o cliente Anthropic a acrescenta). Atalho: `openclaw onboard --auth-choice synthetic-api-key`. @@ -2796,7 +2803,7 @@ 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. -No caminho de streaming compatível com Anthropic, o OpenClaw desabilita o thinking do MiniMax +No caminho de streaming compatível com Anthropic, o OpenClaw desativa o thinking do MiniMax por padrão, a menos que você defina `thinking` explicitamente. `/fast on` ou `params.fastMode: true` reescreve `MiniMax-M2.7` para `MiniMax-M2.7-highspeed`. @@ -2805,7 +2812,7 @@ por padrão, a menos que você defina `thinking` explicitamente. `/fast on` ou -Consulte [Local Models](/pt-BR/gateway/local-models). Resumindo: execute um grande modelo local via API Responses do LM Studio em hardware robusto; mantenha modelos hospedados mesclados para fallback. +Consulte [Modelos locais](/pt-BR/gateway/local-models). Resumindo: execute um modelo local grande via API Responses do LM Studio em hardware robusto; mantenha modelos hospedados mesclados para fallback. @@ -2826,7 +2833,7 @@ Consulte [Local Models](/pt-BR/gateway/local-models). Resumindo: execute um gran }, 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 }, @@ -2836,14 +2843,14 @@ Consulte [Local Models](/pt-BR/gateway/local-models). Resumindo: execute um gran } ``` -- `allowBundled`: allowlist opcional apenas para Skills bundled (Skills gerenciadas/do workspace não são afetadas). +- `allowBundled`: lista opcional de permissões apenas para Skills bundled (Skills gerenciadas/do workspace não são afetadas). - `load.extraDirs`: raízes extras compartilhadas de Skills (menor precedência). - `install.preferBrew`: quando true, prefere instaladores Homebrew quando `brew` está disponível antes de recorrer a outros tipos de instalador. -- `install.nodeManager`: preferência de instalador Node para especificações `metadata.openclaw.install` +- `install.nodeManager`: preferência de gerenciador Node para specs `metadata.openclaw.install` (`npm` | `pnpm` | `yarn` | `bun`). -- `entries..enabled: false` desabilita uma Skill mesmo que esteja 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` desativa uma Skill mesmo se estiver bundled/instalada. +- `entries..apiKey`: conveniência para Skills que declaram uma variável de ambiente primária (string em texto simples ou objeto SecretRef). --- @@ -2871,38 +2878,38 @@ Consulte [Local Models](/pt-BR/gateway/local-models). Resumindo: execute um gran } ``` -- Carregado de `~/.openclaw/extensions`, `/.openclaw/extensions` e `plugins.load.paths`. -- A descoberta aceita plugins nativos do OpenClaw e também bundles compatíveis do Codex e bundles do Claude, incluindo bundles do Claude sem manifesto no layout padrão. -- **Alterações de configuração exigem reinicialização do gateway.** -- `allow`: allowlist opcional (somente os plugins listados são carregados). `deny` prevalece. +- Carregado de `~/.openclaw/extensions`, `/.openclaw/extensions`, além de `plugins.load.paths`. +- A descoberta aceita plugins nativos do OpenClaw, além de bundles compatíveis do Codex e bundles do Claude, incluindo bundles do Claude sem manifesto no layout padrão. +- **Mudanças de configuração exigem reinicialização do gateway.** +- `allow`: lista opcional de permissões (somente os 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 do plugin. -- `plugins.entries..hooks.allowPromptInjection`: quando `false`, o core bloqueia `before_prompt_build` e ignora campos que alteram prompt de `before_agent_start` legado, preservando `modelOverride` e `providerOverride` legados. Aplica-se a hooks nativos de plugin e diretórios de hook fornecidos por bundle compatíveis. -- `plugins.entries..subagent.allowModelOverride`: confia explicitamente neste plugin para solicitar sobrescritas por execução de `provider` e `model` para execuções em segundo plano de subagente. -- `plugins.entries..subagent.allowedModels`: allowlist opcional de destinos canônicos `provider/model` para sobrescritas confiáveis de subagente. Use `"*"` apenas quando você quiser intencionalmente permitir qualquer modelo. -- `plugins.entries..config`: objeto de configuração definido pelo plugin (validado pelo schema do plugin nativo do OpenClaw quando disponível). -- `plugins.entries.firecrawl.config.webFetch`: configurações do provedor de web-fetch Firecrawl. +- `plugins.entries..hooks.allowPromptInjection`: quando `false`, o core bloqueia `before_prompt_build` e ignora campos de mutação de prompt do legado `before_agent_start`, enquanto preserva `modelOverride` e `providerOverride` legados. Aplica-se a hooks de plugins nativos e diretórios de hook fornecidos por bundle compatíveis. +- `plugins.entries..subagent.allowModelOverride`: confia explicitamente neste plugin para solicitar substituições por execução de `provider` e `model` para execuções em segundo plano de subagentes. +- `plugins.entries..subagent.allowedModels`: lista opcional de permissões de alvos canônicos `provider/model` para substituições confiáveis de subagentes. 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 de busca web Firecrawl. - `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 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). + - `onlyMainContent`: extrai somente o conteúdo principal das páginas (padrão: `true`). + - `maxAgeMs`: idade máxima do cache em milissegundos (padrão: `172800000` / 2 dias). - `timeoutSeconds`: timeout da requisição de scraping em segundos (padrão: `60`). -- `plugins.entries.xai.config.xSearch`: configurações de X Search do xAI (busca web do Grok). +- `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 ser usado para busca (ex.: `"grok-4-1-fast"`). -- `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 do Cron para cada varredura completa de Dreaming (padrão `"0 3 * * *"`). - - política de fases e limites são detalhes de implementação (não são chaves de configuração voltadas ao usuário). + - `model`: modelo Grok a usar para busca (por exemplo `"grok-4-1-fast"`). +- `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 mestre 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): - `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 incorporados 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 de mecanismo de contexto ativo; usa por padrão `"legacy"` a menos que você instale e selecione outro mecanismo. +- Plugins de bundle do Claude habilitados também podem contribuir com padrões embutidos de Pi a partir de `settings.json`; o OpenClaw os aplica como configurações de agente sanitizadas, não como patches brutos da configuração do OpenClaw. +- `plugins.slots.memory`: escolhe o ID do plugin de memória ativo ou `"none"` para desativar plugins de memória. +- `plugins.slots.contextEngine`: escolhe o ID do plugin ativo de engine de contexto; usa `"legacy"` por padrão, a menos que você instale e selecione outro engine. - `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. @@ -2911,7 +2918,7 @@ Consulte [Plugins](/pt-BR/tools/plugin). --- -## Browser +## Navegador ```json5 { @@ -2920,8 +2927,8 @@ Consulte [Plugins](/pt-BR/tools/plugin). evaluateEnabled: true, defaultProfile: "user", ssrfPolicy: { - // dangerouslyAllowPrivateNetwork: true, // faça opt-in apenas para acesso confiável à 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"], }, @@ -2947,27 +2954,28 @@ 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 browser permanece estrita por padrão. -- Defina `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` apenas quando você confiar intencionalmente na navegação de browser em rede privada. +- `evaluateEnabled: false` desativa `act:evaluate` e `wait --fn`. +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` fica desativado quando não definido, então a navegação do navegador permanece estrita por padrão. +- Defina `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` apenas quando você confiar intencionalmente na navegação do navegador em rede privada. - No modo estrito, endpoints remotos de perfil CDP (`profiles.*.cdpUrl`) estão sujeitos ao mesmo bloqueio de rede privada durante verificações de alcance/descoberta. - `ssrfPolicy.allowPrivateNetwork` continua compatível como alias legado. - No modo estrito, use `ssrfPolicy.hostnameAllowlist` e `ssrfPolicy.allowedHostnames` para exceções explícitas. -- Perfis remotos são apenas de anexação (iniciar/parar/redefinir desabilitados). +- Perfis remotos são somente de anexação (iniciar/parar/redefinir desativado). - `profiles.*.cdpUrl` aceita `http://`, `https://`, `ws://` e `wss://`. Use HTTP(S) quando quiser que o OpenClaw descubra `/json/version`; use WS(S) quando seu provedor fornecer uma URL WebSocket direta do DevTools. -- Perfis `existing-session` são apenas para host e usam Chrome MCP em vez de CDP. -- Perfis `existing-session` podem definir `userDataDir` para segmentar um perfil específico de navegador - baseado em Chromium, como Brave ou Edge. +- Perfis `existing-session` usam Chrome MCP em vez de CDP e podem se anexar no + host selecionado ou por meio de um Node de navegador conectado. +- Perfis `existing-session` podem definir `userDataDir` para ter como alvo um perfil + específico de navegador baseado em Chromium, como Brave ou Edge. - Perfis `existing-session` mantêm os limites atuais de rota do Chrome MCP: - ações guiadas por snapshot/ref em vez de segmentação por seletor CSS, hooks de upload - de um único arquivo, sem sobrescritas de timeout de diálogo, sem `wait --load networkidle`, + ações dirigidas por 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 download ou ações em lote. - Perfis locais gerenciados `openclaw` atribuem automaticamente `cdpPort` e `cdpUrl`; defina `cdpUrl` explicitamente apenas 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`). +- Ordem de detecção automática: navegador padrão se for baseado em Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. +- Serviço de controle: somente loopback (porta derivada de `gateway.port`, padrão `18791`). - `extraArgs` acrescenta flags extras de inicialização ao Chromium local (por exemplo `--disable-gpu`, dimensionamento de janela ou flags de depuração). @@ -2981,14 +2989,14 @@ Consulte [Plugins](/pt-BR/tools/plugin). seamColor: "#FF4500", assistant: { name: "OpenClaw", - avatar: "CB", // emoji, texto curto, URL de imagem ou URI data + 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`: sobrescrita de identidade da Control UI. Usa a identidade do agente ativo como fallback. +- `seamColor`: cor de destaque para o chrome da UI do app nativo (tom da bolha do Modo Talk etc.). +- `assistant`: substituição de identidade da Control UI. Usa a identidade do agente ativo como fallback. --- @@ -3003,8 +3011,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; consulte /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, @@ -3022,9 +3030,9 @@ Consulte [Plugins](/pt-BR/tools/plugin). basePath: "/openclaw", // root: "dist/control-ui", // embedSandbox: "scripts", // strict | scripts | trusted - // allowExternalEmbedUrls: false, // perigoso: permite URLs absolutas externas http(s) de embed - // 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, }, @@ -3035,12 +3043,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 em /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: { @@ -3057,62 +3065,62 @@ 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 esteja em `local`. -- `port`: porta multiplexada única para WS + HTTP. Precedência: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. +- `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 única multiplexada 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`. - **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. -- **Autenticação**: obrigatória por padrão. Binds fora de loopback exigem autenticação 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. -- `gateway.auth.mode: "none"`: modo explícito sem autenticação. Use apenas para configurações locais confiáveis de local loopback; isso intencionalmente não é oferecido pelos prompts de onboarding. -- `gateway.auth.mode: "trusted-proxy"`: delega autenticação a um proxy reverso com reconhecimento de identidade e confia em cabeçalhos de identidade vindos 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 em loopback no mesmo host não satisfazem a autenticação trusted-proxy. -- `gateway.auth.allowTailscale`: quando `true`, cabeçalhos de identidade do Tailscale Serve podem satisfazer autenticação da Control UI/WebSocket (verificados via `tailscale whois`). Endpoints da API HTTP **não** usam essa autenticação por cabeçalho do Tailscale; eles seguem o modo normal de autenticação HTTP do gateway. Esse fluxo sem token presume que o host do gateway é confiável. Usa `true` por padrão quando `tailscale.mode = "serve"`. -- `gateway.auth.rateLimit`: limitador opcional para falhas de autenticação. Aplica-se por IP do cliente e por escopo de autenticação (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 simultâneas inválidas do mesmo cliente podem acionar o limitador na segunda requisição em vez de ambas passarem como simples incompatibilidades. - - `gateway.auth.rateLimit.exemptLoopback` usa `true` por padrão; defina `false` quando você quiser intencionalmente que o tráfego localhost também seja limitado (para ambientes de teste ou implantações estritas com proxy). -- Tentativas de autenticação WS originadas do browser são sempre limitadas com a isenção de loopback desabilitada (defesa em profundidade contra força bruta localhost via navegador). -- Em loopback, esses bloqueios para origens de browser são isolados por valor +- **Auth**: exigida por padrão. Binds fora de loopback exigem autenticação 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 configurados ao mesmo tempo (incluindo SecretRefs), defina `gateway.auth.mode` explicitamente como `token` ou `password`. 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. +- `gateway.auth.mode: "none"`: modo explícito sem autenticação. Use apenas em configurações confiáveis de loopback local; isso intencionalmente não é oferecido nos prompts de onboarding. +- `gateway.auth.mode: "trusted-proxy"`: delega a autenticação a um proxy reverso com reconhecimento de identidade e confia em cabeçalhos de identidade de `gateway.trustedProxies` (consulte [Trusted Proxy Auth](/pt-BR/gateway/trusted-proxy-auth)). Esse modo espera uma origem de proxy **fora de loopback**; proxies reversos de loopback no mesmo host não satisfazem a autenticação trusted-proxy. +- `gateway.auth.allowTailscale`: quando `true`, cabeçalhos de identidade do Tailscale Serve podem satisfazer a autenticação da Control UI/WebSocket (verificados via `tailscale whois`). Endpoints da API HTTP **não** usam essa autenticação por cabeçalho do Tailscale; eles seguem o modo normal de autenticação HTTP do gateway. Esse fluxo sem token assume que o host do gateway é confiável. Usa `true` por padrão quando `tailscale.mode = "serve"`. +- `gateway.auth.rateLimit`: limitador opcional de falhas de autenticação. Aplica-se por IP de cliente e por escopo de autenticação (segredo compartilhado e token de dispositivo são rastreados independentemente). Tentativas bloqueadas retornam `429` + `Retry-After`. + - No caminho assíncrono da Control UI do Tailscale Serve, tentativas falhas para o mesmo `{scope, clientIp}` são serializadas antes do registro da falha. Assim, tentativas ruins concorrentes do mesmo cliente podem disparar o limitador na segunda requisição em vez de ambas passarem em corrida como simples incompatibilidades. + - `gateway.auth.rateLimit.exemptLoopback` usa `true` por 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 autenticação WS originadas do navegador são sempre limitadas com a isenção de loopback desativada (defesa em profundidade contra força bruta em localhost a partir do navegador). +- Em loopback, esses bloqueios de origem do 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 em loopback) ou `funnel` (público, requer autenticação). -- `controlUi.allowedOrigins`: allowlist explícita de origem do browser para conexões WebSocket do Gateway. Obrigatória quando se espera clientes de browser vindos 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. +- `tailscale.mode`: `serve` (somente tailnet, bind loopback) ou `funnel` (público, requer auth). +- `controlUi.allowedOrigins`: lista explícita de permissões de origem do navegador para conexões WebSocket do Gateway. Obrigatória quando clientes do navegador são esperados 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 Host. - `remote.transport`: `ssh` (padrão) ou `direct` (ws/wss). Para `direct`, `remote.url` deve ser `ws://` ou `wss://`. -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: sobrescrita break-glass do lado do cliente que permite `ws://` em texto claro para IPs confiáveis de rede privada; o padrão continua sendo apenas loopback para texto claro. -- `gateway.remote.token` / `.password` são campos de credencial do cliente remoto. Eles não configuram autenticação 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 por relay para o gateway. Essa URL deve corresponder à URL do relay compilada no build iOS. -- `gateway.push.apns.relay.timeoutMs`: timeout em milissegundos para envio do gateway ao relay. O padrão é `10000`. -- Registros com suporte por 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 do registro ao gateway. Outro gateway não pode reutilizar esse registro armazenado. -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: sobrescritas 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 de canais em minutos. Defina `0` para desabilitar globalmente reinicializações do monitor de saúde. Padrão: `5`. +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: substituição break-glass no lado do cliente que permite `ws://` em texto simples para IPs confiáveis de rede privada; o padrão continua sendo somente loopback para texto simples. +- `gateway.remote.token` / `.password` são campos de credenciais do cliente remoto. Eles não configuram a autenticação do gateway por si só. +- `gateway.push.apns.relay.baseUrl`: URL base HTTPS para o relay APNs externo usado por builds oficiais/TestFlight do iOS depois que publicam registros baseados em relay no gateway. Essa URL deve corresponder à URL do relay compilada no build do iOS. +- `gateway.push.apns.relay.timeoutMs`: timeout em milissegundos para envio do gateway ao relay. Padrão: `10000`. +- Registros baseados em 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 ao gateway uma concessão de envio com escopo do registro. Outro gateway não pode reutilizar esse registro armazenado. +- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: substituições temporárias por ambiente para a configuração de relay acima. +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: escape hatch somente para desenvolvimento para URLs HTTP de relay em loopback. URLs de relay de produção devem permanecer em HTTPS. +- `gateway.channelHealthCheckMinutes`: intervalo do monitor de saúde de canais em minutos. Defina `0` para desativar 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 por monitor de saúde por canal/conta em uma hora móvel. Padrão: `10`. +- `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`: opt-out por canal para reinicializações do monitor de saúde, mantendo o monitor global habilitado. -- `channels..accounts..healthMonitor.enabled`: sobrescrita por conta para canais com várias contas. Quando definido, tem precedência sobre a sobrescrita no nível do canal. -- Caminhos locais de chamada do gateway 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 sob seu controle. Entradas de loopback ainda são válidas para configurações de proxy no mesmo host/detecção local (por exemplo Tailscale Serve ou um proxy reverso local), mas **não** tornam requisições de loopback elegíveis para `gateway.auth.mode: "trusted-proxy"`. +- `channels..accounts..healthMonitor.enabled`: substituição por conta para canais com várias contas. Quando definido, tem precedência sobre a substituição no nível do canal. +- Caminhos locais de chamada do gateway podem usar `gateway.remote.*` como fallback somente quando `gateway.auth.*` não está definido. +- Se `gateway.auth.token` / `gateway.auth.password` estiver configurado explicitamente via SecretRef e não for resolvido, a resolução falha em modo fechado (sem fallback remoto mascarando). +- `trustedProxies`: IPs de proxies reversos que encerram TLS ou injetam cabeçalhos do cliente encaminhado. Liste apenas proxies sob seu controle. Entradas de loopback ainda são válidas para configurações de proxy local/detecção local no mesmo host (por exemplo Tailscale Serve ou um proxy reverso local), mas **não** tornam requisições de 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 bloqueadas para HTTP `POST /tools/invoke` (estende a lista padrão de negação). -- `gateway.tools.allow`: remove nomes de ferramenta da lista padrão de negação HTTP. +- `gateway.tools.deny`: nomes extras de ferramentas bloqueados 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. ### Endpoints compatíveis com OpenAI -- Chat Completions: desabilitado por padrão. Habilite com `gateway.http.endpoints.chatCompletions.enabled: true`. +- Chat Completions: desativado por padrão. Habilite com `gateway.http.endpoints.chatCompletions.enabled: true`. - API Responses: `gateway.http.endpoints.responses.enabled`. -- Endurecimento de entrada por URL da Responses: +- Endurecimento de entrada de URL em Responses: - `gateway.http.endpoints.responses.maxUrlParts` - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` - 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 busca por URL. + Listas de permissões 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 desativar busca por URL. - Cabeçalho opcional de endurecimento de resposta: - `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 entre várias instâncias +### Isolamento de várias instâncias Execute vários gateways em um host com portas e diretórios de estado exclusivos: @@ -3143,10 +3151,10 @@ Consulte [Multiple Gateways](/pt-BR/gateway/multiple-gateways). ``` - `enabled`: habilita encerramento TLS no listener do gateway (HTTPS/WSS) (padrão: `false`). -- `autoGenerate`: gera automaticamente um par local certificado/chave autoassinado quando arquivos explícitos não estão configurados; apenas para uso local/dev. +- `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 com permissões restritas. -- `caPath`: caminho opcional do bundle CA para verificação de cliente ou cadeias de confiança personalizadas. +- `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. ### `gateway.reload` @@ -3163,11 +3171,11 @@ Consulte [Multiple 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; alterações exigem reinicialização explícita. - - `"restart"`: sempre reinicia o processo do gateway em mudança de configuração. + - `"off"`: ignora edições em tempo real; mudanças exigem reinicialização explícita. + - `"restart"`: sempre reinicia o processo do gateway ao mudar a configuração. - `"hot"`: aplica mudanças no processo sem reiniciar. - - `"hybrid"` (padrão): tenta hot reload primeiro; usa reinicialização como fallback se necessário. -- `debounceMs`: janela de debounce em ms antes que alterações de configuração sejam aplicadas (inteiro não negativo). + - `"hybrid"` (padrão): tenta hot reload primeiro; recorre à reinicialização 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). --- @@ -3210,32 +3218,32 @@ Tokens de hook em query string são rejeitados. Observações de validação e segurança: -- `hooks.enabled=true` requer `hooks.token` não vazio. +- `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` do payload 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 do payload para caminhos genéricos. -- Templates como `{{messages[0].subject}}` leem do payload. +- `match.source` corresponde a um campo da carga para caminhos genéricos. +- Templates como `{{messages[0].subject}}` leem 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 são rejeitados). -- `agentId` roteia para um agente específico; IDs desconhecidos usam o padrão como fallback. +- `agentId` roteia para um agente específico; IDs desconhecidos recorrem ao padrão. - `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`: allowlist opcional de prefixos para valores explícitos de `sessionKey` (requisição + mapeamento), por exemplo `["hook:"]`. +- `allowedSessionKeyPrefixes`: lista opcional de permissões de prefixo 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` sobrescreve o LLM para essa execução de hook (deve ser permitido se o catálogo de modelos estiver definido). +- `model` substitui o LLM para esta execução de hook (deve ser permitido se o catálogo de modelos estiver definido). @@ -3262,7 +3270,7 @@ Observações de validação e segurança: } ``` -- O Gateway inicia automaticamente `gog gmail watch serve` na inicialização quando configurado. Defina `OPENCLAW_SKIP_GMAIL_WATCHER=1` para desabilitar. +- O Gateway inicia automaticamente `gog gmail watch serve` na inicialização quando configurado. Defina `OPENCLAW_SKIP_GMAIL_WATCHER=1` para desativar. - Não execute um `gog gmail watch serve` separado junto com o Gateway. --- @@ -3274,7 +3282,7 @@ 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 }, } ``` @@ -3283,18 +3291,18 @@ Observações de validação e segurança: - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` - Somente local: mantenha `gateway.bind: "loopback"` (padrão). -- Binds fora de loopback: rotas de canvas exigem autenticação do Gateway (token/senha/trusted-proxy), igual às outras superfícies HTTP do Gateway. -- Node WebViews normalmente não enviam cabeçalhos de autenticação; depois que um node é pareado e conectado, o Gateway anuncia URLs de capability com escopo de node para acesso a canvas/A2UI. -- URLs de capability ficam vinculadas à sessão WS ativa do node e expiram rapidamente. Fallback baseado em IP não é usado. +- Binds fora de loopback: rotas do canvas exigem autenticação do Gateway (token/senha/trusted-proxy), igual a outras superfícies HTTP do Gateway. +- Node WebViews normalmente não enviam cabeçalhos de autenticação; 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. - Injeta cliente de live reload no HTML servido. -- Cria automaticamente um `index.html` inicial quando estiver vazio. +- Cria automaticamente um `index.html` inicial quando vazio. - Também serve A2UI em `/__openclaw__/a2ui/`. - Alterações exigem reinicialização do gateway. -- Desabilite live reload para diretórios grandes ou erros `EMFILE`. +- Desative live reload para diretórios grandes ou erros `EMFILE`. --- -## Discovery +## Descoberta ### mDNS (Bonjour) @@ -3310,7 +3318,7 @@ 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. Sobrescreva com `OPENCLAW_MDNS_HOSTNAME`. +- O hostname usa `openclaw` por padrão. Substitua com `OPENCLAW_MDNS_HOSTNAME`. ### Wide-area (DNS-SD) @@ -3322,7 +3330,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) + split DNS do Tailscale. +Grava uma zona DNS-SD unicast em `~/.openclaw/dns/`. Para descoberta entre redes, combine com um servidor DNS (CoreDNS recomendado) + DNS dividido do Tailscale. Configuração: `openclaw dns setup --apply`. @@ -3348,13 +3356,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 CWD + `~/.openclaw/.env` (nenhum sobrescreve variáveis existentes). +- Arquivos `.env`: `.env` do CWD + `~/.openclaw/.env` (nenhum substitui variáveis existentes). - `shellEnv`: importa chaves esperadas ausentes do perfil do seu shell de login. - Consulte [Environment](/pt-BR/help/environment) para a precedência completa. -### Substituição de variáveis de ambiente +### 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 { @@ -3364,20 +3372,20 @@ 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_]*`. +- Apenas nomes em maiúsculas são reconhecidos: `[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`. --- -## Secrets +## Segredos -Refs de segredo são aditivas: valores em texto simples continuam funcionando. +Referências de segredos são aditivas: valores em texto simples ainda funcionam. ### `SecretRef` -Use um formato de objeto: +Use um formato único de objeto: ```json5 { source: "env" | "file" | "exec", provider: "default", id: "..." } @@ -3387,23 +3395,23 @@ Validação: - padrão de `provider`: `^[a-z][a-z0-9_-]{0,63}$` - 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"`) +- id para `source: "file"`: 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 de `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 credencial compatível +### Superfície de credenciais compatível -- Matriz canônica: [SecretRef Credential Surface](/pt-BR/reference/secretref-credential-surface) -- `secrets apply` segmenta caminhos de credencial compatíveis em `openclaw.json`. -- Refs em `auth-profiles.json` estão incluídas na resolução em runtime e na cobertura de auditoria. +- Matriz canônica: [Superfície de credenciais SecretRef](/pt-BR/reference/secretref-credential-surface) +- `secrets apply` tem como alvo caminhos de credenciais compatíveis em `openclaw.json`. +- Referências de `auth-profiles.json` estão incluídas na resolução de runtime e na cobertura de auditoria. -### Configuração de provedores de segredo +### Configuração de provedores de segredos ```json5 { secrets: { providers: { - default: { source: "env" }, // provedor explícito opcional de ambiente + default: { source: "env" }, // optional explicit env provider filemain: { source: "file", path: "~/.openclaw/secrets.json", @@ -3427,13 +3435,13 @@ Validação: Observações: -- O provedor `file` suporta `mode: "json"` e `mode: "singleValue"` (`id` deve ser `"value"` no modo singleValue). -- O provedor `exec` requer um caminho `command` absoluto e usa payloads de protocolo em stdin/stdout. -- Por padrão, caminhos de comando symlink são rejeitados. Defina `allowSymlinkCommand: true` para permitir caminhos symlink enquanto valida o caminho resolvido do destino. -- Se `trustedDirs` estiver configurado, a verificação de diretório confiável se aplica ao caminho resolvido do destino. -- O ambiente filho de `exec` é mínimo por padrão; passe explicitamente as variáveis necessárias com `passEnv`. -- Refs de segredo são resolvidas no momento da ativação em um snapshot em memória, e os caminhos de requisição depois 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. +- 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 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 do destino resolvido. +- Se `trustedDirs` estiver configurado, a verificação de diretório confiável se aplica ao caminho do destino resolvido. +- O ambiente do processo filho de `exec` é mínimo por padrão; passe explicitamente as variáveis necessárias com `passEnv`. +- Referências de segredos são resolvidas no momento da ativação em um snapshot em memória, depois os caminhos de requisição leem apenas esse snapshot. +- A filtragem de superfície ativa se aplica durante a ativação: referências não resolvidas em superfícies habilitadas falham a inicialização/reload, enquanto superfícies inativas são ignoradas com diagnósticos. --- @@ -3456,12 +3464,12 @@ Observações: ``` - Perfis por agente são armazenados em `/auth-profiles.json`. -- `auth-profiles.json` suporta refs no 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 suportam credenciais de auth-profile com suporte por SecretRef. -- Credenciais estáticas de runtime vêm de snapshots resolvidos em memória; entradas estáticas legadas de `auth.json` são removidas quando encontradas. -- Importações legadas de OAuth vêm de `~/.openclaw/credentials/oauth.json`. +- `auth-profiles.json` é compatível com referências em nível de valor (`keyRef` para `api_key`, `tokenRef` para `token`) para modos estáticos de credencial. +- Perfis em modo OAuth (`auth.profiles..mode = "oauth"`) não oferecem suporte a credenciais de perfil de autenticação baseadas em SecretRef. +- Credenciais estáticas de runtime vêm de snapshots em memória já resolvidos; entradas estáticas legadas de `auth.json` são removidas quando descobertas. +- Importações legadas de OAuth de `~/.openclaw/credentials/oauth.json`. - Consulte [OAuth](/pt-BR/concepts/oauth). -- Comportamento do runtime de Secrets e tooling `audit/configure/apply`: [Secrets Management](/pt-BR/gateway/secrets). +- Comportamento do runtime de segredos e ferramentas `audit/configure/apply`: [Gerenciamento de segredos](/pt-BR/gateway/secrets). ### `auth.cooldowns` @@ -3483,15 +3491,20 @@ Observações: } ``` -- `billingBackoffHours`: backoff base em horas quando um perfil falha devido a 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 do provedor permanecem limitados ao provedor que os possui (por exemplo OpenRouter `Key limit exceeded`). Mensagens de `402` retryable de janela de uso ou limite de gasto de organização/workspace permanecem no caminho `rate_limit`. -- `billingBackoffHoursByProvider`: sobrescritas opcionais por provedor para horas de backoff de cobrança. -- `billingMaxHours`: limite em horas para crescimento exponencial do backoff de cobrança (padrão: `24`). +- `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 + do provedor continuam limitadas ao provedor ao qual pertencem (por exemplo OpenRouter + `Key limit exceeded`). Mensagens `402` de janela de uso + ou de limite de gasto de organização/workspace que são passíveis de nova tentativa 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`). - `authPermanentBackoffMinutes`: backoff base em minutos para falhas `auth_permanent` de alta confiança (padrão: `10`). -- `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`: número máximo de rotações de auth-profile do mesmo provedor para erros de sobrecarga antes de alternar para fallback de modelo (padrão: `1`). Formatos de provedor ocupado, como `ModelNotReadyException`, entram aqui. +- `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. - `overloadedBackoffMs`: atraso fixo antes de tentar novamente uma rotação de provedor/perfil sobrecarregado (padrão: `0`). -- `rateLimitedProfileRotations`: número máximo de rotações de auth-profile do mesmo provedor para erros de limite de taxa antes de alternar para fallback de modelo (padrão: `1`). Esse bucket de limite de taxa inclui texto moldado pelo 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 auth-profile do mesmo provedor para erros de limite de taxa antes de mudar para fallback de modelo (padrão: `1`). Esse grupo de limite de taxa inclui textos típicos de provedores como `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` e `resource exhausted`. --- @@ -3513,11 +3526,11 @@ 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`. -- `maxFileBytes`: tamanho máximo do arquivo de log em bytes antes de as gravações serem suprimidas (inteiro positivo; padrão: `524288000` = 500 MB). Use rotação externa de logs para implantações de produção. +- `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. --- -## Diagnostics +## Diagnósticos ```json5 { @@ -3550,20 +3563,20 @@ Observações: } ``` -- `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 (suporta curingas como `"telegram.*"` ou `"*"`). +- `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 (compatível com 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`). -- `otel.endpoint`: URL do collector para exportação OTel. +- `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 as requisições de exportação OTel. +- `otel.headers`: cabeçalhos extras de metadados HTTP/gRPC enviados com requisições de exportação OTel. - `otel.serviceName`: nome do serviço para atributos de recurso. -- `otel.traces` / `otel.metrics` / `otel.logs`: habilita exportação de trace, métricas ou logs. -- `otel.sampleRate`: taxa de amostragem de trace `0`–`1`. -- `otel.flushIntervalMs`: intervalo periódico de flush de telemetria em ms. +- `otel.traces` / `otel.metrics` / `otel.logs`: habilitam exportação de traces, métricas ou logs. +- `otel.sampleRate`: taxa de amostragem de traces `0`–`1`. +- `otel.flushIntervalMs`: intervalo periódico em ms para flush de telemetria. - `cacheTrace.enabled`: registra snapshots de rastreamento de cache para execuções incorporadas (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`: controla o que é incluído na saída de rastreamento de cache (todos usam `true` por padrão). +- `cacheTrace.filePath`: caminho de saída para o 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). --- @@ -3585,12 +3598,12 @@ Observações: } ``` -- `channel`: canal de lançamento para instalações npm/git — `"stable"`, `"beta"` ou `"dev"`. +- `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`: com que frequência verificações do canal beta são executadas em horas (padrão: `1`; máximo: `24`). +- `auto.stableJitterHours`: janela extra em horas para distribuir o rollout do canal estável (padrão: `12`; máximo: `168`). +- `auto.betaCheckIntervalHours`: frequência em horas das verificações do canal beta (padrão: `1`; máximo: `24`). --- @@ -3625,20 +3638,20 @@ Observações: - `enabled`: feature gate global do ACP (padrão: `false`). - `dispatch.enabled`: gate independente para despacho de turnos 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 de agente ACP de fallback quando spawns não especificam um destino explícito. -- `allowedAgents`: allowlist de IDs de agente permitidos para sessões de runtime ACP; vazio significa nenhuma restrição adicional. +- `backend`: ID padrão de backend de runtime ACP (deve corresponder a um Plugin de runtime ACP registrado). +- `defaultAgent`: ID de agente ACP de fallback quando spawns não especificam um alvo explícito. +- `allowedAgents`: lista de permissões de IDs de agentes permitidos para sessões de runtime ACP; vazio significa sem restrição adicional. - `maxConcurrentSessions`: máximo de sessões ACP ativas simultaneamente. -- `stream.coalesceIdleMs`: janela de flush por ociosidade em ms para texto em streaming. -- `stream.maxChunkChars`: tamanho máximo do chunk antes de dividir a projeção de bloco transmitido. +- `stream.coalesceIdleMs`: janela de flush ocioso em ms para texto em streaming. +- `stream.maxChunkChars`: tamanho máximo do chunk antes de dividir a projeção do bloco em streaming. - `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.deliveryMode`: `"live"` transmite incrementalmente; `"final_only"` mantém em buffer até eventos terminais do turno. - `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 sobrescritas booleanas de visibilidade em eventos transmitidos. -- `runtime.ttlMinutes`: TTL ocioso em minutos para workers de sessão ACP antes de ficarem elegíveis para limpeza. -- `runtime.installCommand`: comando de instalação opcional para executar ao inicializar um ambiente de runtime ACP. +- `stream.tagVisibility`: registro de nomes de tags para substituições booleanas de visibilidade em eventos transmitidos. +- `runtime.ttlMinutes`: TTL ocioso em minutos para workers de sessão ACP antes de elegibilidade para limpeza. +- `runtime.installCommand`: comando de instalação opcional a ser executado ao inicializar um ambiente de runtime ACP. --- @@ -3655,16 +3668,16 @@ Observações: ``` - `cli.banner.taglineMode` controla o estilo da tagline do banner: - - `"random"` (padrão): taglines engraçadas/sazonais rotativas. + - `"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 taglines), defina a variável de ambiente `OPENCLAW_HIDE_BANNER=1`. + - `"off"`: sem texto de tagline (o título/versão do banner ainda é exibido). +- Para ocultar o banner inteiro (não apenas as taglines), defina a variável de ambiente `OPENCLAW_HIDE_BANNER=1`. --- ## Wizard -Metadados gravados por fluxos guiados de configuração da CLI (`onboard`, `configure`, `doctor`): +Metadados gravados por fluxos de configuração guiada da CLI (`onboard`, `configure`, `doctor`): ```json5 { @@ -3682,13 +3695,13 @@ Metadados gravados por fluxos guiados de configuração da CLI (`onboard`, `conf ## Identidade -Consulte os campos de identidade em `agents.list` em [Padrões de agente](#agent-defaults). +Consulte os campos de identidade de `agents.list` em [Padrões do agente](#agent-defaults). --- ## Bridge (legado, removido) -As versões atuais não incluem mais a bridge TCP. Nodes se conectam pelo WebSocket do Gateway. As chaves `bridge.*` não fazem mais parte do schema de configuração (a validação falha até que sejam removidas; `openclaw doctor --fix` pode remover chaves desconhecidas). +As compilações atuais não incluem mais a bridge TCP. Nodes se conectam pelo WebSocket do Gateway. Chaves `bridge.*` não fazem mais parte do schema de configuração (a validação falha até serem removidas; `openclaw doctor --fix` pode remover chaves desconhecidas). @@ -3717,22 +3730,22 @@ As versões atuais não incluem mais a bridge TCP. Nodes se conectam pelo WebSoc cron: { enabled: true, maxConcurrentRuns: 2, - webhook: "https://example.invalid/legacy", // fallback legado obsoleto para trabalhos armazenados com notify:true - webhookToken: "replace-with-dedicated-token", // token bearer opcional para autenticação 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 de Cron antes de removê-las de `sessions.json`. Também controla a limpeza de transcrições arquivadas deletadas de Cron. Padrão: `24h`; defina `false` para desabilitar. +- `sessionRetention`: por quanto tempo manter sessões concluídas de execuções Cron isoladas 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 desativar. - `runLog.maxBytes`: tamanho máximo por arquivo de log de execução (`cron/runs/.jsonl`) antes da poda. Padrão: `2_000_000` bytes. -- `runLog.keepLines`: linhas mais recentes retidas quando a poda 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 autenticação é enviado. -- `webhook`: URL de webhook de fallback legado obsoleta (http/https) usada apenas para trabalhos armazenados que ainda tenham `notify: true`. +- `runLog.keepLines`: linhas mais recentes mantidas quando a poda 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 autenticação é enviado. +- `webhook`: URL de Webhook legada obsoleta (http/https) usada apenas para jobs armazenados que ainda têm `notify: true`. ### `cron.retry` @@ -3748,11 +3761,11 @@ As versões atuais não incluem mais a bridge TCP. Nodes se conectam pelo WebSoc } ``` -- `maxAttempts`: máximo de retries para trabalhos pontuais 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]`; de 1 a 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. +- `maxAttempts`: máximo de tentativas para jobs únicos em erros transitórios (padrão: `3`; intervalo: `0`–`10`). +- `backoffMs`: array de atrasos de backoff em ms para cada tentativa (padrão: `[30000, 60000, 300000]`; 1–10 entradas). +- `retryOn`: tipos de erro que disparam nova tentativa — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Omita para tentar novamente todos os tipos transitórios. -Aplica-se apenas a trabalhos pontuais de Cron. Trabalhos recorrentes usam tratamento de falha separado. +Aplica-se apenas a jobs Cron únicos. Jobs recorrentes usam tratamento separado de falhas. ### `cron.failureAlert` @@ -3770,11 +3783,11 @@ Aplica-se apenas a trabalhos pontuais de Cron. Trabalhos recorrentes usam tratam } ``` -- `enabled`: habilita alertas de falha para trabalhos de Cron (padrão: `false`). -- `after`: falhas consecutivas antes que um alerta seja disparado (inteiro positivo, mín: `1`). -- `cooldownMs`: milissegundos mínimos entre alertas repetidos para o mesmo trabalho (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 definir o escopo da entrega do alerta. +- `enabled`: habilita alertas de falha para jobs Cron (padrão: `false`). +- `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"` faz POST para o Webhook configurado. +- `accountId`: ID opcional de conta ou canal para delimitar a entrega do alerta. ### `cron.failureDestination` @@ -3791,49 +3804,49 @@ Aplica-se apenas a trabalhos pontuais de Cron. Trabalhos recorrentes usam tratam } ``` -- Destino padrão para notificações de falha de Cron em todos os trabalhos. +- Destino padrão para notificações de falha de Cron em todos os jobs. - `mode`: `"announce"` ou `"webhook"`; usa `"announce"` por padrão quando existem dados de destino suficientes. -- `channel`: sobrescrita de canal para entrega por anúncio. `"last"` reutiliza o último canal de entrega conhecido. -- `to`: destino explícito de anúncio ou URL de webhook. Obrigatório para modo webhook. -- `accountId`: sobrescrita opcional de conta para entrega. -- `delivery.failureDestination` por trabalho sobrescreve esse padrão global. -- Quando nem o destino global nem o por trabalho está definido, trabalhos que já entregam via `announce` usam esse destino principal de anúncio como fallback em caso de falha. -- `delivery.failureDestination` só é compatível com trabalhos `sessionTarget="isolated"`, a menos que o `delivery.mode` principal do trabalho seja `"webhook"`. +- `channel`: substituição de canal para entrega `announce`. `"last"` reutiliza o último canal de entrega conhecido. +- `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 não há destino de falha global nem por job, jobs que já entregam via `announce` recorrem a esse alvo principal de `announce` em caso de falha. +- `delivery.failureDestination` é compatível apenas com jobs `sessionTarget="isolated"`, a menos que `delivery.mode` principal do job seja `"webhook"`. -Consulte [Cron Jobs](/pt-BR/automation/cron-jobs). Execuções isoladas de Cron são rastreadas como [background tasks](/pt-BR/automation/tasks). +Consulte [Jobs Cron](/pt-BR/automation/cron-jobs). Execuções Cron isoladas são rastreadas como [tarefas em segundo plano](/pt-BR/automation/tasks). --- -## Variáveis de template de modelo de mídia +## Variáveis de template do modelo de mídia 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 do 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 da mídia (image/audio/document/…) | -| `{{Transcript}}` | transcrição de áudio | -| `{{Prompt}}` | prompt de mídia resolvido para entradas CLI | +| `{{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 dos membros do grupo (best effort) | -| `{{SenderName}}` | nome de exibição do remetente (best effort) | -| `{{SenderE164}}` | número de telefone do remetente (best effort) | -| `{{Provider}}` | dica do provedor (whatsapp, telegram, discord etc.) | +| `{{ChatType}}` | `"direct"` ou `"group"` | +| `{{GroupSubject}}` | assunto do grupo (melhor esforço) | +| `{{GroupMembers}}` | prévia de 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.) | --- -## Includes de configuração (`$include`) +## Inclusões de configuração (`$include`) Divida a configuração em vários arquivos: @@ -3850,13 +3863,13 @@ Divida a configuração em vários arquivos: **Comportamento de mesclagem:** -- Arquivo único: substitui o objeto contêiner. -- Array de arquivos: mesclado profundamente em ordem (os posteriores sobrescrevem os anteriores). -- Chaves irmãs: mescladas após os includes (sobrescrevem 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 resolvem dentro desse limite. -- Erros: mensagens claras para arquivos ausentes, erros de parsing e includes circulares. +- Arquivo único: substitui o objeto que o contém. +- Array de arquivos: mesclado profundamente em ordem (os posteriores substituem os anteriores). +- Chaves irmãs: mescladas após as inclusões (substituem valores incluídos). +- Inclusões aninhadas: 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 são resolvidas dentro desse limite. +- Erros: mensagens claras para arquivos ausentes, erros de parse e inclusões circulares. --- -_Relacionado: [Configuration](/pt-BR/gateway/configuration) · [Configuration Examples](/pt-BR/gateway/configuration-examples) · [Doctor](/pt-BR/gateway/doctor)_ +_Relacionado: [Configuration](/pt-BR/gateway/configuration) · [Exemplos de configuração](/pt-BR/gateway/configuration-examples) · [Doctor](/pt-BR/gateway/doctor)_ diff --git a/docs/pt-BR/help/faq.md b/docs/pt-BR/help/faq.md index dc1ae2d50..e185c0ba6 100644 --- a/docs/pt-BR/help/faq.md +++ b/docs/pt-BR/help/faq.md @@ -1,21 +1,21 @@ --- read_when: - - Respondendo a dúvidas comuns sobre configuração, instalação, onboarding ou uso em tempo de execução - - Fazendo a triagem de problemas relatados por usuários antes de uma depuração mais aprofundada + - Respondendo a perguntas comuns sobre configuração, instalação, onboarding ou suporte em tempo de execução + - Triando problemas relatados por usuários antes de uma depuração mais aprofundada summary: Perguntas frequentes sobre a configuração, a instalação e o uso do OpenClaw title: Perguntas frequentes x-i18n: - generated_at: "2026-04-12T23:28:29Z" + generated_at: "2026-04-20T05:41:39Z" model: gpt-5.4 provider: openai - source_hash: d2a78d0fea9596625cc2753e6dc8cc42c2379a3a0c91729265eee0261fe53eaa + source_hash: 6bdb17fc4d8c61a36f3a9fc3ca4a20f723cfa6c9bbbc92f963d6e313181f3451 source_path: help/faq.md workflow: 15 --- # Perguntas frequentes -Respostas rápidas, além de uma solução de problemas mais aprofundada para configurações do mundo real (desenvolvimento local, VPS, multi-agent, OAuth/chaves de API, failover de modelos). Para diagnósticos em tempo de execução, consulte [Solução de problemas](/pt-BR/gateway/troubleshooting). Para a referência completa de configuração, consulte [Configuração](/pt-BR/gateway/configuration). +Respostas rápidas mais solução de problemas aprofundada para configurações do mundo real (desenvolvimento local, VPS, multi-agent, chaves OAuth/API, failover de modelo). Para diagnósticos de tempo de execução, consulte [Solução de problemas](/pt-BR/gateway/troubleshooting). Para a referência completa de configuração, consulte [Configuração](/pt-BR/gateway/configuration). ## Primeiros 60 segundos se algo estiver quebrado @@ -25,7 +25,7 @@ Respostas rápidas, além de uma solução de problemas mais aprofundada para co openclaw status ``` - Resumo local rápido: SO + atualização, acessibilidade do gateway/serviço, agents/sessions, configuração do provedor + problemas em tempo de execução (quando o gateway está acessível). + Resumo local rápido: SO + atualização, disponibilidade do gateway/serviço, agents/sessions, configuração do provedor + problemas de tempo de execução (quando o gateway está acessível). 2. **Relatório copiável (seguro para compartilhar)** @@ -41,15 +41,15 @@ Respostas rápidas, além de uma solução de problemas mais aprofundada para co openclaw gateway status ``` - Mostra o tempo de execução do supervisor em comparação com a acessibilidade do RPC, a URL de destino da sondagem e qual configuração o serviço provavelmente usou. + Mostra o tempo de execução do supervisor vs acessibilidade RPC, a URL de destino da sonda e qual configuração o serviço provavelmente usou. -4. **Sondagens profundas** +4. **Sondas profundas** ```bash openclaw status --deep ``` - Executa uma sondagem ativa de integridade do gateway, incluindo sondagens de canal quando compatível + Executa uma sonda de integridade ativa do gateway, incluindo sondas de canal quando compatível (requer um gateway acessível). Consulte [Health](/pt-BR/gateway/health). 5. **Acompanhe o log mais recente** @@ -78,7 +78,7 @@ Respostas rápidas, além de uma solução de problemas mais aprofundada para co ```bash openclaw health --json - openclaw health --verbose # mostra a URL de destino + o caminho da configuração em erros + openclaw health --verbose # mostra a URL de destino + o caminho da configuração em caso de erros ``` Solicita ao gateway em execução um snapshot completo (somente WS). Consulte [Health](/pt-BR/gateway/health). @@ -87,24 +87,24 @@ Respostas rápidas, além de uma solução de problemas mais aprofundada para co - Use um agente de IA local que consiga **ver sua máquina**. Isso é muito mais eficaz do que perguntar - no Discord, porque a maioria dos casos de "estou travado" são **problemas locais de configuração ou ambiente** que + Use um agente de IA local que consiga **ver sua máquina**. Isso é muito mais eficaz do que pedir ajuda + no Discord, porque a maioria dos casos de "estou travado" é causada por **problemas locais de configuração ou ambiente** que ajudantes remotos não conseguem inspecionar. - **Claude Code**: [https://www.anthropic.com/claude-code/](https://www.anthropic.com/claude-code/) - **OpenAI Codex**: [https://openai.com/codex/](https://openai.com/codex/) Essas ferramentas podem ler o repositório, executar comandos, inspecionar logs e ajudar a corrigir sua configuração - no nível da máquina (PATH, serviços, permissões, arquivos de autenticação). Dê a elas o **checkout completo do código-fonte** via - instalação hackable (git): + no nível da máquina (PATH, serviços, permissões, arquivos de autenticação). Dê a elas o **checkout completo do código-fonte** por meio + da instalação hackable (git): ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` Isso instala o OpenClaw **a partir de um checkout git**, para que o agente possa ler o código + a documentação e - raciocinar sobre a versão exata que você está executando. Você sempre pode voltar para a versão estável depois - executando novamente o instalador sem `--install-method git`. + raciocinar sobre a versão exata que você está executando. Você sempre pode voltar para a versão estável mais tarde + executando o instalador novamente sem `--install-method git`. Dica: peça ao agente para **planejar e supervisionar** a correção (passo a passo) e depois executar apenas os comandos necessários. Isso mantém as mudanças pequenas e mais fáceis de auditar. @@ -131,22 +131,22 @@ Respostas rápidas, além de uma solução de problemas mais aprofundada para co `openclaw gateway status`, `openclaw health --verbose`. Loop rápido de depuração: [Primeiros 60 segundos se algo estiver quebrado](#primeiros-60-segundos-se-algo-estiver-quebrado). - Documentação de instalação: [Instalar](/pt-BR/install), [Flags do instalador](/pt-BR/install/installer), [Atualizando](/pt-BR/install/updating). + Documentação de instalação: [Install](/pt-BR/install), [Flags do instalador](/pt-BR/install/installer), [Atualização](/pt-BR/install/updating). - Motivos comuns para ignorar o heartbeat: + Motivos comuns para ignorar Heartbeat: - `quiet-hours`: fora da janela configurada de active-hours - - `empty-heartbeat-file`: `HEARTBEAT.md` existe, mas contém apenas estrutura em branco ou somente cabeçalhos - - `no-tasks-due`: o modo de tarefas de `HEARTBEAT.md` está ativo, mas nenhum dos intervalos das tarefas venceu ainda - - `alerts-disabled`: toda a visibilidade do heartbeat está desativada (`showOk`, `showAlerts` e `useIndicator` estão todos desativados) + - `empty-heartbeat-file`: `HEARTBEAT.md` existe, mas contém apenas estrutura em branco/somente cabeçalho + - `no-tasks-due`: o modo de tarefa de `HEARTBEAT.md` está ativo, mas nenhum dos intervalos de tarefa ainda venceu + - `alerts-disabled`: toda a visibilidade do heartbeat está desativada (`showOk`, `showAlerts` e `useIndicator` estão todos desligados) - No modo de tarefas, os timestamps de vencimento só são avançados depois que uma execução real de heartbeat + No modo de tarefa, os carimbos de data/hora de vencimento só são avançados depois que uma execução real do heartbeat é concluída. Execuções ignoradas não marcam tarefas como concluídas. - Documentação: [Heartbeat](/pt-BR/gateway/heartbeat), [Automação e Tarefas](/pt-BR/automation). + Documentação: [Heartbeat](/pt-BR/gateway/heartbeat), [Automação & Tarefas](/pt-BR/automation). @@ -158,16 +158,16 @@ Respostas rápidas, além de uma solução de problemas mais aprofundada para co openclaw onboard --install-daemon ``` - O assistente também pode compilar ativos de UI automaticamente. Após o onboarding, normalmente você executa o Gateway na porta **18789**. + O assistente também pode compilar automaticamente os assets da UI. Após o onboarding, você normalmente executa o Gateway na porta **18789**. - A partir do código-fonte (colaboradores/dev): + A partir do código-fonte (contribuidores/dev): ```bash git clone https://github.com/openclaw/openclaw.git cd openclaw pnpm install pnpm build - pnpm ui:build # instala automaticamente as dependências da UI na primeira execução + pnpm ui:build openclaw onboard ``` @@ -176,50 +176,50 @@ Respostas rápidas, além de uma solução de problemas mais aprofundada para co - O assistente abre o navegador com uma URL limpa (sem token) do dashboard logo após o onboarding e também imprime o link no resumo. Mantenha essa aba aberta; se ela não tiver sido iniciada, copie/cole a URL impressa na mesma máquina. + O assistente abre seu navegador com uma URL limpa do dashboard (sem token) logo após o onboarding e também imprime o link no resumo. Mantenha essa aba aberta; se ela não tiver sido iniciada, copie/cole a URL impressa na mesma máquina. - + **Localhost (mesma máquina):** - Abra `http://127.0.0.1:18789/`. - - Se ele solicitar autenticação por segredo compartilhado, cole o token ou a senha configurados nas configurações da Control UI. + - Se pedir autenticação por segredo compartilhado, cole o token ou a senha configurados nas configurações da Control UI. - Origem do token: `gateway.auth.token` (ou `OPENCLAW_GATEWAY_TOKEN`). - Origem da senha: `gateway.auth.password` (ou `OPENCLAW_GATEWAY_PASSWORD`). - Se nenhum segredo compartilhado estiver configurado ainda, gere um token com `openclaw doctor --generate-gateway-token`. - **Fora de localhost:** + **Fora do localhost:** - - **Tailscale Serve** (recomendado): mantenha o bind loopback, execute `openclaw gateway --tailscale serve`, abra `https:///`. Se `gateway.auth.allowTailscale` for `true`, os cabeçalhos de identidade atendem à autenticação da Control UI/WebSocket (sem colar segredo compartilhado, assumindo host do gateway confiável); as APIs HTTP ainda exigem autenticação por segredo compartilhado, a menos que você use deliberadamente `none` em private-ingress ou autenticação HTTP por trusted-proxy. - Tentativas ruins concorrentes de autenticação do Serve feitas pelo mesmo cliente são serializadas antes de o limitador de autenticação com falha registrá-las, então a segunda tentativa ruim já pode mostrar `retry later`. - - **Bind na tailnet**: execute `openclaw gateway --bind tailnet --token ""` (ou configure autenticação por senha), abra `http://:18789/` e então cole o segredo compartilhado correspondente nas configurações do dashboard. - - **Proxy reverso com reconhecimento de identidade**: mantenha o Gateway atrás de um trusted proxy sem loopback, configure `gateway.auth.mode: "trusted-proxy"` e então abra a URL do proxy. - - **Túnel SSH**: `ssh -N -L 18789:127.0.0.1:18789 user@host` e então abra `http://127.0.0.1:18789/`. A autenticação por segredo compartilhado ainda se aplica pelo túnel; cole o token ou a senha configurados se solicitado. + - **Tailscale Serve** (recomendado): mantenha o bind em loopback, execute `openclaw gateway --tailscale serve`, abra `https:///`. Se `gateway.auth.allowTailscale` for `true`, os cabeçalhos de identidade satisfazem a autenticação da Control UI/WebSocket (sem colar segredo compartilhado, assumindo um host de gateway confiável); as APIs HTTP ainda exigem autenticação por segredo compartilhado, a menos que você use deliberadamente `none` em private-ingress ou autenticação HTTP de proxy confiável. + Más tentativas simultâneas de autenticação do Serve a partir do mesmo cliente são serializadas antes que o limitador de falhas de autenticação as registre, portanto a segunda tentativa inválida já pode mostrar `retry later`. + - **Bind na tailnet**: execute `openclaw gateway --bind tailnet --token ""` (ou configure autenticação por senha), abra `http://:18789/` e depois cole o segredo compartilhado correspondente nas configurações do dashboard. + - **Proxy reverso com reconhecimento de identidade**: mantenha o Gateway atrás de um proxy confiável sem loopback, configure `gateway.auth.mode: "trusted-proxy"` e então abra a URL do proxy. + - **Túnel SSH**: `ssh -N -L 18789:127.0.0.1:18789 user@host` e depois abra `http://127.0.0.1:18789/`. A autenticação por segredo compartilhado ainda se aplica pelo túnel; cole o token ou a senha configurados se solicitado. - Consulte [Dashboard](/web/dashboard) e [Superfícies web](/web) para detalhes sobre modos de bind e autenticação. + Consulte [Dashboard](/web/dashboard) e [Superfícies web](/web) para detalhes de modos de bind e autenticação. - + Elas controlam camadas diferentes: - `approvals.exec`: encaminha prompts de aprovação para destinos de chat - - `channels..execApprovals`: faz esse canal atuar como um cliente nativo de aprovação para aprovações de exec + - `channels..execApprovals`: faz com que esse canal atue como um cliente nativo de aprovação para aprovações exec - A política de exec do host continua sendo o verdadeiro gate de aprovação. A configuração do chat controla apenas onde os - prompts de aprovação aparecem e como as pessoas podem respondê-los. + A política exec do host continua sendo o verdadeiro controle de aprovação. A configuração do chat controla apenas onde os prompts de aprovação + aparecem e como as pessoas podem respondê-los. - Na maioria das configurações você **não** precisa das duas: + Na maioria das configurações, você **não** precisa de ambas: - - Se o chat já oferecer suporte a comandos e respostas, `/approve` no mesmo chat funciona pelo caminho compartilhado. - - Se um canal nativo compatível puder inferir aprovadores com segurança, o OpenClaw agora ativa automaticamente aprovações nativas com prioridade para DM quando `channels..execApprovals.enabled` não estiver definido ou estiver como `"auto"`. - - Quando cartões/botões nativos de aprovação estiverem disponíveis, essa UI nativa será o caminho principal; o agent só deve incluir um comando manual `/approve` se 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. - - Use `approvals.exec` somente quando os prompts também precisarem ser encaminhados para outros chats ou salas explícitas de operações. - - Use `channels..execApprovals.target: "channel"` ou `"both"` somente quando você quiser explicitamente que os prompts de aprovação sejam postados de volta na sala/tópico de origem. - - As aprovações de Plugin são separadas novamente: por padrão elas usam `/approve` no mesmo chat, encaminhamento opcional em `approvals.plugin`, e somente alguns canais nativos mantêm o tratamento nativo de aprovação de plugin por cima disso. + - Se o chat já oferece suporte a comandos e respostas, `/approve` no mesmo chat funciona pelo caminho compartilhado. + - Se um canal nativo compatível puder inferir aprovadores com segurança, o OpenClaw agora ativa automaticamente aprovações nativas DM-first quando `channels..execApprovals.enabled` estiver indefinido ou for `"auto"`. + - Quando cartões/botões nativos de aprovação estiverem disponíveis, essa UI nativa será o caminho principal; o agent só deve incluir um comando manual `/approve` se o resultado da ferramenta disser que aprovações por chat não estão disponíveis ou que a aprovação manual é o único caminho. + - Use `approvals.exec` apenas quando os prompts também precisarem ser encaminhados para outros chats ou salas operacionais explícitas. + - Use `channels..execApprovals.target: "channel"` ou `"both"` apenas quando quiser explicitamente que os prompts de aprovação sejam postados de volta na sala/tópico de origem. + - As aprovações de Plugin são separadas novamente: elas usam `/approve` no mesmo chat por padrão, encaminhamento opcional `approvals.plugin` e apenas alguns canais nativos mantêm o tratamento nativo de aprovação de plugin por cima disso. - Resumindo: encaminhamento é para roteamento, configuração do cliente nativo é para uma UX mais rica e específica de canal. - Consulte [Aprovações de Exec](/pt-BR/tools/exec-approvals). + Em resumo: encaminhamento é para roteamento, configuração de cliente nativo é para uma UX mais rica e específica do canal. + Consulte [Aprovações exec](/pt-BR/tools/exec-approvals). @@ -229,31 +229,31 @@ Respostas rápidas, além de uma solução de problemas mais aprofundada para co Sim. O Gateway é leve — a documentação lista **512MB-1GB de RAM**, **1 núcleo** e cerca de **500MB** - de disco como suficientes para uso pessoal, e observa que um **Raspberry Pi 4 pode executá-lo**. + de disco como suficientes para uso pessoal, e observa que um **Raspberry Pi 4 consegue executá-lo**. - Se você quiser mais folga (logs, mídia, outros serviços), **2GB são recomendados**, mas isso + Se você quiser uma folga extra (logs, mídia, outros serviços), **2GB são recomendados**, mas isso não é um mínimo rígido. - Dica: um Pi/VPS pequeno pode hospedar o Gateway, e você pode parear **Nodes** no laptop/celular para + Dica: um Pi/VPS pequeno pode hospedar o Gateway, e você pode emparelhar **nodes** no seu laptop/telefone para tela/câmera/canvas locais ou execução de comandos. Consulte [Nodes](/pt-BR/nodes). - Resumindo: funciona, mas espere algumas arestas. + Em resumo: funciona, mas espere algumas arestas. - - Use um SO de **64 bits** e mantenha Node >= 22. - - Prefira a **instalação hackable (git)** para poder ver logs e atualizar rapidamente. + - Use um SO **64 bits** e mantenha Node >= 22. + - Prefira a **instalação hackable (git)** para que você possa ver logs e atualizar rapidamente. - Comece sem canais/Skills e depois adicione-os um por um. - - Se você encontrar problemas binários estranhos, normalmente é um problema de **compatibilidade com ARM**. + - Se você encontrar problemas estranhos com binários, geralmente é um problema de **compatibilidade ARM**. - Documentação: [Linux](/pt-BR/platforms/linux), [Instalar](/pt-BR/install). + Documentação: [Linux](/pt-BR/platforms/linux), [Install](/pt-BR/install). - + Essa tela depende de o Gateway estar acessível e autenticado. A TUI também envia - "Wake up, my friend!" automaticamente na primeira inicialização. Se você vir essa linha **sem resposta** + "Wake up, my friend!" automaticamente na primeira hatch. Se você vir essa linha sem **nenhuma resposta** e os tokens permanecerem em 0, o agent nunca foi executado. 1. Reinicie o Gateway: @@ -276,27 +276,27 @@ Respostas rápidas, além de uma solução de problemas mais aprofundada para co openclaw doctor ``` - Se o Gateway for remoto, garanta que a conexão de túnel/Tailscale esteja ativa e que a UI + Se o Gateway for remoto, certifique-se de que a conexão do túnel/Tailscale esteja ativa e que a UI esteja apontando para o Gateway correto. Consulte [Acesso remoto](/pt-BR/gateway/remote). Sim. Copie o **diretório de estado** e o **workspace**, depois execute o Doctor uma vez. Isso - mantém seu bot "exatamente igual" (memória, histórico de sessão, autenticação e estado do canal) - desde que você copie **ambos** os locais: + mantém seu bot "exatamente igual" (memória, histórico de sessão, autenticação e + estado do canal), contanto que você copie **ambos** os locais: 1. Instale o OpenClaw na nova máquina. 2. Copie `$OPENCLAW_STATE_DIR` (padrão: `~/.openclaw`) da máquina antiga. 3. Copie seu workspace (padrão: `~/.openclaw/workspace`). 4. Execute `openclaw doctor` e reinicie o serviço do Gateway. - Isso preserva a configuração, perfis de autenticação, credenciais do WhatsApp, sessions e memória. Se você estiver no - modo remoto, lembre-se de que o host do gateway é o responsável pelo armazenamento de sessions e pelo workspace. + Isso preserva a configuração, perfis de autenticação, credenciais do WhatsApp, sessões e memória. Se você estiver em + modo remoto, lembre-se de que o host do gateway é o proprietário do armazenamento de sessões e do workspace. - **Importante:** se você apenas fizer commit/push do seu workspace para o GitHub, estará fazendo backup - de **memória + arquivos de bootstrap**, mas **não** do histórico de sessions nem da autenticação. Eles ficam - em `~/.openclaw/` (por exemplo `~/.openclaw/agents//sessions/`). + **Importante:** se você apenas fizer commit/push do seu workspace para o GitHub, estará fazendo + backup de **memória + arquivos bootstrap**, mas **não** do histórico de sessões nem da autenticação. Eles ficam + em `~/.openclaw/` (por exemplo, `~/.openclaw/agents//sessions/`). Relacionado: [Migração](/pt-BR/install/migrating), [Onde as coisas ficam no disco](#where-things-live-on-disk), [Workspace do agent](/pt-BR/concepts/agent-workspace), [Doctor](/pt-BR/gateway/doctor), @@ -304,22 +304,22 @@ Respostas rápidas, além de uma solução de problemas mais aprofundada para co - + Consulte o changelog no GitHub: [https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md) - As entradas mais recentes ficam no topo. Se a seção do topo estiver marcada como **Unreleased**, a próxima - seção datada será a versão mais recente publicada. As entradas são agrupadas em **Highlights**, **Changes** e + As entradas mais recentes ficam no topo. Se a seção superior estiver marcada como **Unreleased**, a próxima + seção com data será a versão lançada mais recente. As entradas são agrupadas em **Highlights**, **Changes** e **Fixes** (além de seções de documentação/outras, quando necessário). Algumas conexões da Comcast/Xfinity bloqueiam incorretamente `docs.openclaw.ai` por meio do Xfinity - Advanced Security. Desative isso ou adicione `docs.openclaw.ai` à allowlist e tente novamente. - Ajude-nos a desbloqueá-lo reportando aqui: [https://spa.xfinity.com/check_url_status](https://spa.xfinity.com/check_url_status). + Advanced Security. Desative-o ou adicione `docs.openclaw.ai` à allowlist e tente novamente. + Ajude-nos a desbloqueá-lo informando aqui: [https://spa.xfinity.com/check_url_status](https://spa.xfinity.com/check_url_status). - Se você ainda não conseguir acessar o site, a documentação está espelhada no GitHub: + Se você ainda não conseguir acessar o site, a documentação é espelhada no GitHub: [https://github.com/openclaw/openclaw/tree/main/docs](https://github.com/openclaw/openclaw/tree/main/docs) @@ -327,12 +327,12 @@ Respostas rápidas, além de uma solução de problemas mais aprofundada para co **Stable** e **beta** são **npm dist-tags**, não linhas de código separadas: - - `latest` = stable - - `beta` = build antecipada para testes + - `latest` = estável + - `beta` = build antecipado para testes - Normalmente, uma versão stable chega primeiro em **beta** e, em seguida, uma etapa explícita - de promoção move essa mesma versão para `latest`. Os maintainers também podem - publicar direto em `latest` quando necessário. É por isso que beta e stable podem + Normalmente, uma versão estável chega primeiro em **beta** e depois uma etapa explícita + de promoção move essa mesma versão para `latest`. Os mantenedores também podem + publicar diretamente em `latest` quando necessário. É por isso que beta e stable podem apontar para a **mesma versão** após a promoção. Veja o que mudou: @@ -343,8 +343,8 @@ Respostas rápidas, além de uma solução de problemas mais aprofundada para co - **Beta** é a npm dist-tag `beta` (pode coincidir com `latest` após a promoção). - **Dev** é o head móvel de `main` (git); quando publicado, usa a npm dist-tag `dev`. + **Beta** é a npm dist-tag `beta` (pode corresponder a `latest` após a promoção). + **Dev** é a ponta móvel de `main` (git); quando publicado, usa a npm dist-tag `dev`. One-liners (macOS/Linux): @@ -380,7 +380,7 @@ Respostas rápidas, além de uma solução de problemas mais aprofundada para co curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - Isso fornece um repositório local que você pode editar e depois atualizar via git. + Isso lhe dá um repositório local que você pode editar e depois atualizar via git. Se você preferir fazer manualmente um clone limpo, use: @@ -391,8 +391,8 @@ Respostas rápidas, além de uma solução de problemas mais aprofundada para co pnpm build ``` - Documentação: [Atualizar](/cli/update), [Canais de desenvolvimento](/pt-BR/install/development-channels), - [Instalar](/pt-BR/install). + Documentação: [Update](/cli/update), [Canais de desenvolvimento](/pt-BR/install/development-channels), + [Install](/pt-BR/install). @@ -408,13 +408,13 @@ Respostas rápidas, além de uma solução de problemas mais aprofundada para co - Execute novamente o instalador com **saída detalhada**: + Execute o instalador novamente com **saída detalhada**: ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --verbose ``` - Instalação beta com verbose: + Instalação beta com modo detalhado: ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --beta --verbose @@ -442,14 +442,14 @@ Respostas rápidas, além de uma solução de problemas mais aprofundada para co Dois problemas comuns no Windows: - **1) erro do npm spawn git / git not found** + **1) erro npm spawn git / git not found** - - Instale o **Git for Windows** e garanta que `git` esteja no seu PATH. - - Feche e reabra o PowerShell, depois execute novamente o instalador. + - Instale o **Git for Windows** e certifique-se de que `git` esteja no seu PATH. + - Feche e reabra o PowerShell e, em seguida, execute o instalador novamente. **2) openclaw is not recognized após a instalação** - - A pasta global bin do npm não está no PATH. + - Sua pasta global bin do npm não está no PATH. - Verifique o caminho: ```powershell @@ -457,22 +457,22 @@ Respostas rápidas, além de uma solução de problemas mais aprofundada para co ``` - Adicione esse diretório ao PATH do usuário (nenhum sufixo `\bin` é necessário no Windows; na maioria dos sistemas ele é `%AppData%\npm`). - - Feche e reabra o PowerShell depois de atualizar o PATH. + - Feche e reabra o PowerShell após atualizar o PATH. - Se você quiser a configuração mais tranquila no Windows, use **WSL2** em vez do Windows nativo. + Se quiser a configuração mais tranquila no Windows, use **WSL2** em vez de Windows nativo. Documentação: [Windows](/pt-BR/platforms/windows). - - Isso normalmente é uma incompatibilidade de code page do console em shells nativos do Windows. + + Isso geralmente é uma incompatibilidade de code page do console em shells nativos do Windows. Sintomas: - - A saída de `system.run`/`exec` renderiza chinês como mojibake - - O mesmo comando parece correto em outro perfil de terminal + - a saída de `system.run`/`exec` renderiza texto em chinês como mojibake + - o mesmo comando parece correto em outro perfil de terminal - Solução rápida no PowerShell: + Solução alternativa rápida no PowerShell: ```powershell chcp 65001 @@ -481,32 +481,32 @@ Respostas rápidas, além de uma solução de problemas mais aprofundada para co $OutputEncoding = [System.Text.UTF8Encoding]::new($false) ``` - Depois reinicie o Gateway e tente novamente o comando: + Em seguida, reinicie o Gateway e tente novamente o comando: ```powershell openclaw gateway restart ``` - Se você ainda conseguir reproduzir isso na versão mais recente do OpenClaw, acompanhe/reporte em: + Se você ainda reproduzir isso na versão mais recente do OpenClaw, acompanhe/informe em: - [Issue #30640](https://github.com/openclaw/openclaw/issues/30640) - - Use a **instalação hackable (git)** para ter todo o código-fonte e a documentação localmente, depois pergunte - ao seu bot (ou Claude/Codex) _a partir dessa pasta_ para que ele possa ler o repositório e responder com precisão. + + Use a **instalação hackable (git)** para ter o código-fonte completo e a documentação localmente e depois pergunte + ao seu bot (ou Claude/Codex) _a partir dessa pasta_, para que ele possa ler o repositório e responder com precisão. ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - Mais detalhes: [Instalar](/pt-BR/install) e [Flags do instalador](/pt-BR/install/installer). + Mais detalhes: [Install](/pt-BR/install) e [Flags do instalador](/pt-BR/install/installer). - Resposta curta: siga o guia do Linux e depois execute o onboarding. + Resposta curta: siga o guia de Linux e depois execute o onboarding. - Caminho rápido no Linux + instalação do serviço: [Linux](/pt-BR/platforms/linux). - Passo a passo completo: [Primeiros passos](/pt-BR/start/getting-started). @@ -522,7 +522,7 @@ Respostas rápidas, além de uma solução de problemas mais aprofundada para co - + Mantemos um **hub de hospedagem** com os provedores mais comuns. Escolha um e siga o guia: - [Hospedagem VPS](/pt-BR/vps) (todos os provedores em um só lugar) @@ -530,23 +530,23 @@ Respostas rápidas, além de uma solução de problemas mais aprofundada para co - [Hetzner](/pt-BR/install/hetzner) - [exe.dev](/pt-BR/install/exe-dev) - Como funciona na nuvem: o **Gateway roda no servidor**, e você o acessa - pelo laptop/celular via Control UI (ou Tailscale/SSH). Seu estado + workspace - ficam no servidor, então trate o host como a fonte da verdade e faça backup dele. + Como funciona na nuvem: o **Gateway é executado no servidor**, e você o acessa + do seu laptop/telefone via Control UI (ou Tailscale/SSH). Seu estado + workspace + ficam no servidor, portanto trate o host como a fonte da verdade e faça backup dele. - Você pode parear **Nodes** (Mac/iOS/Android/headless) com esse Gateway na nuvem para acessar - tela/câmera/canvas locais ou executar comandos no laptop mantendo o + Você pode emparelhar **nodes** (Mac/iOS/Android/headless) com esse Gateway na nuvem para acessar + tela/câmera/canvas locais ou executar comandos no seu laptop, mantendo o Gateway na nuvem. - Hub: [Plataformas](/pt-BR/platforms). Acesso remoto: [Gateway remoto](/pt-BR/gateway/remote). - Nodes: [Nodes](/pt-BR/nodes), [CLI de Nodes](/cli/nodes). + Hub: [Platforms](/pt-BR/platforms). Acesso remoto: [Gateway remoto](/pt-BR/gateway/remote). + Nodes: [Nodes](/pt-BR/nodes), [Nodes CLI](/cli/nodes). Resposta curta: **é possível, mas não é recomendado**. O fluxo de atualização pode reiniciar o - Gateway (o que derruba a session ativa), pode exigir um checkout git limpo e - pode solicitar confirmação. Mais seguro: execute as atualizações em um shell como operador. + Gateway (o que derruba a sessão ativa), pode exigir um checkout git limpo e + pode pedir confirmação. Mais seguro: execute as atualizações de um shell como operador. Use a CLI: @@ -565,7 +565,7 @@ Respostas rápidas, além de uma solução de problemas mais aprofundada para co openclaw gateway restart ``` - Documentação: [Atualizar](/cli/update), [Atualizando](/pt-BR/install/updating). + Documentação: [Update](/cli/update), [Atualização](/pt-BR/install/updating). @@ -573,32 +573,32 @@ Respostas rápidas, além de uma solução de problemas mais aprofundada para co `openclaw onboard` é o caminho de configuração recomendado. No **modo local**, ele orienta você por: - **Configuração de modelo/autenticação** (OAuth do provedor, chaves de API, setup-token da Anthropic, além de opções de modelo local como LM Studio) - - Localização do **workspace** + arquivos de bootstrap + - Local do **workspace** + arquivos bootstrap - **Configurações do Gateway** (bind/porta/autenticação/tailscale) - - **Canais** (WhatsApp, Telegram, Discord, Mattermost, Signal, iMessage, além de plugins de canal empacotados como QQ Bot) + - **Canais** (WhatsApp, Telegram, Discord, Mattermost, Signal, iMessage, além de plugins de canal incluídos, como QQ Bot) - **Instalação do daemon** (LaunchAgent no macOS; unidade de usuário systemd no Linux/WSL2) - **Verificações de integridade** e seleção de **Skills** - Ele também avisa se o modelo configurado for desconhecido ou se faltar autenticação. + Ele também avisa se o modelo configurado for desconhecido ou estiver sem autenticação. Não. Você pode executar o OpenClaw com **chaves de API** (Anthropic/OpenAI/outras) ou com - **modelos somente locais** para que seus dados permaneçam no seu dispositivo. Assinaturas (Claude - Pro/Max ou OpenAI Codex) são maneiras opcionais de autenticar esses provedores. + **modelos somente locais**, para que seus dados permaneçam no seu dispositivo. Assinaturas (Claude + Pro/Max ou OpenAI Codex) são formas opcionais de autenticar esses provedores. - Para a Anthropic no OpenClaw, a divisão prática é: + Para Anthropic no OpenClaw, a divisão prática é: - - **Chave de API da Anthropic**: cobrança normal da API da Anthropic + - **Chave de API Anthropic**: cobrança normal da API da Anthropic - **Autenticação do Claude CLI / assinatura Claude no OpenClaw**: a equipe da Anthropic - nos informou que esse uso voltou a ser permitido, e o OpenClaw está tratando o uso de `claude -p` + nos disse que esse uso voltou a ser permitido, e o OpenClaw está tratando o uso de `claude -p` como autorizado para essa integração, a menos que a Anthropic publique uma nova política - Para hosts de gateway de longa duração, as chaves de API da Anthropic ainda são a configuração - mais previsível. O OAuth do OpenAI Codex é explicitamente compatível com ferramentas - externas como o OpenClaw. + Para hosts de gateway de longa duração, as chaves de API da Anthropic ainda são a + configuração mais previsível. O OAuth do OpenAI Codex é explicitamente compatível com + ferramentas externas como o OpenClaw. O OpenClaw também oferece suporte a outras opções hospedadas no estilo assinatura, incluindo **Qwen Cloud Coding Plan**, **MiniMax Coding Plan** e @@ -607,7 +607,7 @@ Respostas rápidas, além de uma solução de problemas mais aprofundada para co Documentação: [Anthropic](/pt-BR/providers/anthropic), [OpenAI](/pt-BR/providers/openai), [Qwen Cloud](/pt-BR/providers/qwen), [MiniMax](/pt-BR/providers/minimax), [Modelos GLM](/pt-BR/providers/glm), - [Modelos locais](/pt-BR/gateway/local-models), [Modelos](/pt-BR/concepts/models). + [Modelos locais](/pt-BR/gateway/local-models), [Models](/pt-BR/concepts/models). @@ -615,21 +615,21 @@ Respostas rápidas, além de uma solução de problemas mais aprofundada para co Sim. A equipe da Anthropic nos informou que o uso do Claude CLI no estilo OpenClaw voltou a ser permitido, então - o OpenClaw trata a autenticação por assinatura do Claude e o uso de `claude -p` como autorizados + o OpenClaw trata a autenticação por assinatura Claude e o uso de `claude -p` como autorizados para essa integração, a menos que a Anthropic publique uma nova política. Se você quiser - a configuração mais previsível no servidor, use uma chave de API da Anthropic. + a configuração no lado do servidor mais previsível, use uma chave de API da Anthropic. - + Sim. A equipe da Anthropic nos informou que esse uso voltou a ser permitido, então o OpenClaw trata - a reutilização do Claude CLI e o uso de `claude -p` como autorizados para essa integração, + a reutilização do Claude CLI e o uso de `claude -p` como autorizados para esta integração, a menos que a Anthropic publique uma nova política. - O setup-token da Anthropic continua disponível como um caminho de token compatível no OpenClaw, mas o OpenClaw agora prefere a reutilização do Claude CLI e `claude -p` quando disponíveis. - Para cargas de trabalho de produção ou multiusuário, a autenticação por chave de API da Anthropic ainda é a + O setup-token da Anthropic ainda está disponível como um caminho de token compatível no OpenClaw, mas o OpenClaw agora prefere a reutilização do Claude CLI e `claude -p` quando disponíveis. + Para cargas de trabalho de produção ou multiusuário, a autenticação com chave de API da Anthropic ainda é a opção mais segura e previsível. Se você quiser outras opções hospedadas no estilo assinatura no OpenClaw, consulte [OpenAI](/pt-BR/providers/openai), [Qwen / Model Cloud](/pt-BR/providers/qwen), [MiniMax](/pt-BR/providers/minimax) e [Modelos @@ -641,67 +641,67 @@ Respostas rápidas, além de uma solução de problemas mais aprofundada para co Isso significa que sua **cota/limite de taxa da Anthropic** foi esgotada na janela atual. Se você usar **Claude CLI**, aguarde a janela ser redefinida ou faça upgrade do seu plano. Se você -usar uma **chave de API da Anthropic**, verifique o Anthropic Console +usar uma **chave de API da Anthropic**, verifique o Console da Anthropic quanto a uso/faturamento e aumente os limites conforme necessário. Se a mensagem for especificamente: `Extra usage is required for long context requests`, a solicitação está tentando usar o beta de contexto de 1M da Anthropic (`context1m: true`). Isso só funciona quando sua - credencial é elegível para cobrança de contexto longo (faturamento por chave de API ou o - caminho de login Claude do OpenClaw com Extra Usage habilitado). + credencial é elegível para faturamento de contexto longo (faturamento por chave de API ou o + caminho de login Claude do OpenClaw com Extra Usage ativado). - Dica: defina um **modelo de fallback** para que o OpenClaw possa continuar respondendo enquanto um provedor estiver com rate limit. - Consulte [Modelos](/cli/models), [OAuth](/pt-BR/concepts/oauth) e + Dica: defina um **modelo de fallback** para que o OpenClaw possa continuar respondendo enquanto um provedor estiver limitado por taxa. + Consulte [Models](/cli/models), [OAuth](/pt-BR/concepts/oauth) e [/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/pt-BR/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context). - Sim. O OpenClaw tem um provedor empacotado **Amazon Bedrock (Converse)**. Com marcadores de ambiente da AWS presentes, o OpenClaw pode descobrir automaticamente o catálogo Bedrock de streaming/texto e mesclá-lo como um provedor implícito `amazon-bedrock`; caso contrário, você pode ativar explicitamente `plugins.entries.amazon-bedrock.config.discovery.enabled` ou adicionar uma entrada manual de provedor. Consulte [Amazon Bedrock](/pt-BR/providers/bedrock) e [Provedores de modelos](/pt-BR/providers/models). Se você preferir um fluxo gerenciado de chave, um proxy compatível com OpenAI na frente do Bedrock também continua sendo uma opção válida. + Sim. O OpenClaw tem um provedor incluído **Amazon Bedrock (Converse)**. Com marcadores de ambiente AWS presentes, o OpenClaw pode descobrir automaticamente o catálogo Bedrock de streaming/texto e mesclá-lo como um provedor implícito `amazon-bedrock`; caso contrário, você pode ativar explicitamente `plugins.entries.amazon-bedrock.config.discovery.enabled` ou adicionar uma entrada de provedor manual. Consulte [Amazon Bedrock](/pt-BR/providers/bedrock) e [Provedores de modelo](/pt-BR/providers/models). Se preferir um fluxo de chave gerenciado, um proxy compatível com OpenAI na frente do Bedrock continua sendo uma opção válida. - - O OpenClaw oferece suporte ao **OpenAI Code (Codex)** via OAuth (login do ChatGPT). O onboarding pode executar o fluxo OAuth e definirá o modelo padrão como `openai-codex/gpt-5.4` quando apropriado. Consulte [Provedores de modelos](/pt-BR/concepts/model-providers) e [Onboarding (CLI)](/pt-BR/start/wizard). + + O OpenClaw oferece suporte a **OpenAI Code (Codex)** via OAuth (login do ChatGPT). O onboarding pode executar o fluxo OAuth e definirá o modelo padrão como `openai-codex/gpt-5.4` quando apropriado. Consulte [Provedores de modelo](/pt-BR/concepts/model-providers) e [Onboarding (CLI)](/pt-BR/start/wizard). - - O OpenClaw trata os dois caminhos separadamente: + + O OpenClaw trata as duas rotas separadamente: - `openai-codex/gpt-5.4` = OAuth do ChatGPT/Codex - - `openai/gpt-5.4` = API direta da plataforma OpenAI + - `openai/gpt-5.4` = API direta da OpenAI Platform - No OpenClaw, o login do ChatGPT/Codex está conectado à rota `openai-codex/*`, - e não à rota direta `openai/*`. Se você quiser o caminho da API direta no + No OpenClaw, o login do ChatGPT/Codex é ligado à rota `openai-codex/*`, + não à rota direta `openai/*`. Se você quiser o caminho da API direta no OpenClaw, defina `OPENAI_API_KEY` (ou a configuração equivalente do provedor OpenAI). Se você quiser login do ChatGPT/Codex no OpenClaw, use `openai-codex/*`. - - `openai-codex/*` usa a rota OAuth do Codex, e suas janelas de cota utilizável são + + `openai-codex/*` usa a rota OAuth do Codex, e suas janelas de cota utilizáveis são gerenciadas pela OpenAI e dependem do plano. Na prática, esses limites podem ser diferentes da experiência no site/app do ChatGPT, mesmo quando ambos estão vinculados à mesma conta. - O OpenClaw pode mostrar as janelas de uso/cota do provedor atualmente visíveis em - `openclaw models status`, mas não inventa nem normaliza direitos do ChatGPT web - em acesso direto à API. Se você quiser o caminho direto de cobrança/limite da OpenAI Platform, + O OpenClaw pode mostrar as janelas de uso/cota atualmente visíveis do provedor em + `openclaw models status`, mas ele não inventa nem normaliza permissões do ChatGPT web + para acesso direto à API. Se você quiser o caminho direto de faturamento/limite da OpenAI Platform, use `openai/*` com uma chave de API. - - Sim. O OpenClaw oferece suporte completo ao **OAuth por assinatura do OpenAI Code (Codex)**. + + Sim. O OpenClaw oferece suporte completo a **OAuth por assinatura do OpenAI Code (Codex)**. A OpenAI permite explicitamente o uso de OAuth por assinatura em ferramentas/fluxos de trabalho externos como o OpenClaw. O onboarding pode executar o fluxo OAuth para você. - Consulte [OAuth](/pt-BR/concepts/oauth), [Provedores de modelos](/pt-BR/concepts/model-providers) e [Onboarding (CLI)](/pt-BR/start/wizard). + Consulte [OAuth](/pt-BR/concepts/oauth), [Provedores de modelo](/pt-BR/concepts/model-providers) e [Onboarding (CLI)](/pt-BR/start/wizard). - O Gemini CLI usa um **fluxo de autenticação de Plugin**, não um client id ou secret em `openclaw.json`. + O Gemini CLI usa um **fluxo de autenticação de plugin**, não um client id ou secret em `openclaw.json`. - Passos: + Etapas: 1. Instale o Gemini CLI localmente para que `gemini` esteja no `PATH` - Homebrew: `brew install gemini-cli` @@ -711,36 +711,36 @@ quanto a uso/faturamento e aumente os limites conforme necessário. 4. Modelo padrão após o login: `google-gemini-cli/gemini-3-flash-preview` 5. Se as solicitações falharem, defina `GOOGLE_CLOUD_PROJECT` ou `GOOGLE_CLOUD_PROJECT_ID` no host do gateway - Isso armazena tokens OAuth em perfis de autenticação no host do gateway. Detalhes: [Provedores de modelos](/pt-BR/concepts/model-providers). + Isso armazena tokens OAuth em perfis de autenticação no host do gateway. Detalhes: [Provedores de modelo](/pt-BR/concepts/model-providers). - - Normalmente não. O OpenClaw precisa de contexto grande + segurança robusta; placas pequenas truncam e vazam. Se for indispensável, execute localmente a **maior** build de modelo que você puder (LM Studio) e consulte [/gateway/local-models](/pt-BR/gateway/local-models). Modelos menores/quantizados aumentam o risco de prompt injection — consulte [Segurança](/pt-BR/gateway/security). + + Normalmente não. O OpenClaw precisa de contexto grande + segurança forte; modelos pequenos truncam e vazam. Se for realmente necessário, execute localmente a **maior** build de modelo que conseguir (LM Studio) e consulte [/gateway/local-models](/pt-BR/gateway/local-models). Modelos menores/quantizados aumentam o risco de prompt injection — consulte [Segurança](/pt-BR/gateway/security). - - Escolha endpoints fixados por região. O OpenRouter expõe opções hospedadas nos EUA para MiniMax, Kimi e GLM; escolha a variante hospedada nos EUA para manter os dados na região. Você ainda pode listar Anthropic/OpenAI ao lado deles usando `models.mode: "merge"` para que os fallbacks continuem disponíveis enquanto respeitam o provedor regional que você selecionar. + + Escolha endpoints fixados por região. O OpenRouter expõe opções hospedadas nos EUA para MiniMax, Kimi e GLM; escolha a variante hospedada nos EUA para manter os dados na região. Você ainda pode listar Anthropic/OpenAI junto com esses usando `models.mode: "merge"` para que os fallbacks continuem disponíveis enquanto respeitam o provedor regional que você selecionar. - Não. O OpenClaw roda em macOS ou Linux (Windows via WSL2). Um Mac mini é opcional — algumas pessoas - compram um como host sempre ativo, mas uma VPS pequena, servidor doméstico ou máquina do tipo Raspberry Pi também funciona. + Não. O OpenClaw é executado em macOS ou Linux (Windows via WSL2). Um Mac mini é opcional — algumas pessoas + compram um como host sempre ativo, mas uma VPS pequena, servidor doméstico ou máquina da classe Raspberry Pi também funciona. - Você só precisa de um Mac **para ferramentas exclusivas do macOS**. Para iMessage, use [BlueBubbles](/pt-BR/channels/bluebubbles) (recomendado) — o servidor BlueBubbles roda em qualquer Mac, e o Gateway pode rodar em Linux ou em outro lugar. Se você quiser outras ferramentas exclusivas do macOS, execute o Gateway em um Mac ou pareie um Node macOS. + Você só precisa de um Mac **para ferramentas exclusivas do macOS**. Para iMessage, use [BlueBubbles](/pt-BR/channels/bluebubbles) (recomendado) — o servidor BlueBubbles roda em qualquer Mac, e o Gateway pode rodar em Linux ou em outro lugar. Se você quiser outras ferramentas exclusivas do macOS, execute o Gateway em um Mac ou emparelhe um node macOS. Documentação: [BlueBubbles](/pt-BR/channels/bluebubbles), [Nodes](/pt-BR/nodes), [Modo remoto no Mac](/pt-BR/platforms/mac/remote). - - Você precisa de **algum dispositivo macOS** conectado ao Messages. **Não** precisa ser um Mac mini — - qualquer Mac funciona. **Use [BlueBubbles](/pt-BR/channels/bluebubbles)** (recomendado) para iMessage — o servidor BlueBubbles roda no macOS, enquanto o Gateway pode rodar em Linux ou em outro lugar. + + Você precisa de **algum dispositivo macOS** conectado ao Mensagens. **Não** precisa ser um Mac mini — + qualquer Mac serve. **Use [BlueBubbles](/pt-BR/channels/bluebubbles)** (recomendado) para iMessage — o servidor BlueBubbles roda no macOS, enquanto o Gateway pode rodar em Linux ou em outro lugar. Configurações comuns: - - Execute o Gateway em Linux/VPS e o servidor BlueBubbles em qualquer Mac conectado ao Messages. - - Execute tudo no Mac se quiser a configuração de máquina única mais simples. + - Execute o Gateway em Linux/VPS e o servidor BlueBubbles em qualquer Mac conectado ao Mensagens. + - Execute tudo no Mac se quiser a configuração mais simples em uma única máquina. Documentação: [BlueBubbles](/pt-BR/channels/bluebubbles), [Nodes](/pt-BR/nodes), [Modo remoto no Mac](/pt-BR/platforms/mac/remote). @@ -748,56 +748,56 @@ quanto a uso/faturamento e aumente os limites conforme necessário. - Sim. O **Mac mini pode executar o Gateway**, e o seu MacBook Pro pode se conectar como um - **Node** (dispositivo complementar). Nodes não executam o Gateway — eles fornecem capacidades extras - como tela/câmera/canvas e `system.run` nesse dispositivo. + Sim. O **Mac mini pode executar o Gateway**, e seu MacBook Pro pode se conectar como um + **node** (dispositivo complementar). Nodes não executam o Gateway — eles fornecem capacidades extras + como tela/câmera/canvas e `system.run` naquele dispositivo. Padrão comum: - Gateway no Mac mini (sempre ativo). - - MacBook Pro executa o app do macOS ou um host de node e faz pareamento com o Gateway. + - O MacBook Pro executa o app macOS ou um host de node e se emparelha com o Gateway. - Use `openclaw nodes status` / `openclaw nodes list` para vê-lo. - Documentação: [Nodes](/pt-BR/nodes), [CLI de Nodes](/cli/nodes). + Documentação: [Nodes](/pt-BR/nodes), [Nodes CLI](/cli/nodes). - Bun **não é recomendado**. Vemos bugs em tempo de execução, especialmente com WhatsApp e Telegram. + Bun **não é recomendado**. Vemos bugs de tempo de execução, especialmente com WhatsApp e Telegram. Use **Node** para gateways estáveis. - Se você ainda quiser experimentar o Bun, faça isso em um gateway não voltado para produção + Se você ainda quiser experimentar Bun, faça isso em um gateway não produtivo sem WhatsApp/Telegram. - + `channels.telegram.allowFrom` é **o ID de usuário do Telegram do remetente humano** (numérico). Não é o nome de usuário do bot. - O onboarding aceita entrada `@username` e a resolve para um ID numérico, mas a autorização do OpenClaw usa apenas IDs numéricos. + A configuração solicita apenas IDs de usuário numéricos. Se você já tiver entradas legadas `@username` na configuração, `openclaw doctor --fix` pode tentar resolvê-las. Mais seguro (sem bot de terceiros): - - Envie DM para seu bot e depois execute `openclaw logs --follow` para ler `from.id`. + - Envie uma DM para seu bot e depois execute `openclaw logs --follow` e leia `from.id`. API oficial do Bot: - - Envie DM para seu bot e depois chame `https://api.telegram.org/bot/getUpdates` para ler `message.from.id`. + - Envie uma DM para seu bot e depois chame `https://api.telegram.org/bot/getUpdates` e leia `message.from.id`. Terceiros (menos privado): - - Envie DM para `@userinfobot` ou `@getidsbot`. + - Envie uma DM para `@userinfobot` ou `@getidsbot`. Consulte [/channels/telegram](/pt-BR/channels/telegram#access-control-and-activation). - Sim, via **roteamento multi-agent**. Vincule o **DM** do WhatsApp de cada remetente (peer `kind: "direct"`, remetente E.164 como `+15551234567`) a um `agentId` diferente, para que cada pessoa tenha seu próprio workspace e armazenamento de sessions. As respostas ainda virão da **mesma conta de WhatsApp**, e o controle de acesso a DMs (`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`) é global por conta de WhatsApp. Consulte [Roteamento multi-agent](/pt-BR/concepts/multi-agent) e [WhatsApp](/pt-BR/channels/whatsapp). + Sim, via **roteamento multi-agent**. Vincule a **DM** do WhatsApp de cada remetente (peer `kind: "direct"`, remetente E.164 como `+15551234567`) a um `agentId` diferente, para que cada pessoa tenha seu próprio workspace e armazenamento de sessões. As respostas ainda virão da **mesma conta do WhatsApp**, e o controle de acesso a DM (`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`) é global por conta de WhatsApp. Consulte [Roteamento multi-agent](/pt-BR/concepts/multi-agent) e [WhatsApp](/pt-BR/channels/whatsapp). - - Sim. Use roteamento multi-agent: dê a cada agent seu próprio modelo padrão e depois vincule rotas de entrada (conta do provedor ou peers específicos) a cada agent. Um exemplo de configuração está em [Roteamento multi-agent](/pt-BR/concepts/multi-agent). Consulte também [Modelos](/pt-BR/concepts/models) e [Configuração](/pt-BR/gateway/configuration). + + Sim. Use roteamento multi-agent: dê a cada agent seu próprio modelo padrão e depois vincule as rotas de entrada (conta do provedor ou peers específicos) a cada agent. Um exemplo de configuração está em [Roteamento multi-agent](/pt-BR/concepts/multi-agent). Consulte também [Models](/pt-BR/concepts/models) e [Configuração](/pt-BR/gateway/configuration). @@ -810,18 +810,18 @@ quanto a uso/faturamento e aumente os limites conforme necessário. brew install ``` - Se você executar o OpenClaw via systemd, garanta que o PATH do serviço inclua `/home/linuxbrew/.linuxbrew/bin` (ou seu prefixo brew) para que ferramentas instaladas via `brew` sejam resolvidas em shells sem login. - Builds recentes também adicionam no início diretórios bin comuns de usuário em serviços Linux systemd (por exemplo `~/.local/bin`, `~/.npm-global/bin`, `~/.local/share/pnpm`, `~/.bun/bin`) e respeitam `PNPM_HOME`, `NPM_CONFIG_PREFIX`, `BUN_INSTALL`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `NVM_DIR` e `FNM_DIR` quando definidos. + Se você executar o OpenClaw via systemd, certifique-se de que o PATH do serviço inclua `/home/linuxbrew/.linuxbrew/bin` (ou seu prefixo brew) para que as ferramentas instaladas com `brew` sejam resolvidas em shells sem login. + Builds recentes também prefixam diretórios bin comuns de usuário em serviços Linux systemd (por exemplo `~/.local/bin`, `~/.npm-global/bin`, `~/.local/share/pnpm`, `~/.bun/bin`) e respeitam `PNPM_HOME`, `NPM_CONFIG_PREFIX`, `BUN_INSTALL`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `NVM_DIR` e `FNM_DIR` quando definidos. - - - **Instalação hackable (git):** checkout completo do código-fonte, editável, melhor para colaboradores. - Você executa os builds localmente e pode corrigir código/documentação. - - **npm install:** instalação global da CLI, sem repositório, melhor para “apenas executar”. + + - **Instalação hackable (git):** checkout completo do código-fonte, editável, melhor para contribuidores. + Você executa builds localmente e pode corrigir código/documentação. + - **npm install:** instalação global da CLI, sem repositório, melhor para "só executar". As atualizações vêm das npm dist-tags. - Documentação: [Primeiros passos](/pt-BR/start/getting-started), [Atualizando](/pt-BR/install/updating). + Documentação: [Primeiros passos](/pt-BR/start/getting-started), [Atualização](/pt-BR/install/updating). @@ -849,27 +849,27 @@ quanto a uso/faturamento e aumente os limites conforme necessário. openclaw gateway restart ``` - O Doctor detecta uma incompatibilidade no entrypoint do serviço do gateway e oferece reescrever a configuração do serviço para corresponder à instalação atual (use `--repair` em automação). + O Doctor detecta uma incompatibilidade no entrypoint do serviço do gateway e oferece reescrever a configuração do serviço para corresponder à instalação atual (use `--repair` em automações). Dicas de backup: consulte [Estratégia de backup](#where-things-live-on-disk). - Resposta curta: **se você quer confiabilidade 24/7, use uma VPS**. Se você quer a - menor fricção e aceita suspensão/reinicializações, execute localmente. + Resposta curta: **se você quer confiabilidade 24/7, use uma VPS**. Se você quer o + menor atrito e não se importa com suspensão/reinicializações, execute localmente. **Laptop (Gateway local)** - - **Prós:** sem custo de servidor, acesso direto a arquivos locais, janela do navegador visível. + - **Prós:** sem custo de servidor, acesso direto a arquivos locais, janela do navegador visível em tempo real. - **Contras:** suspensão/quedas de rede = desconexões, atualizações/reinicializações do SO interrompem, a máquina precisa permanecer ativa. **VPS / nuvem** - **Prós:** sempre ativo, rede estável, sem problemas com suspensão do laptop, mais fácil de manter em execução. - - **Contras:** geralmente roda em modo headless (use capturas de tela), acesso apenas remoto a arquivos, você precisa usar SSH para atualizar. + - **Contras:** geralmente roda headless (use capturas de tela), acesso apenas a arquivos remotos, você precisa usar SSH para atualizações. - **Observação específica do OpenClaw:** WhatsApp/Telegram/Slack/Mattermost/Discord funcionam bem em uma VPS. A única troca real é **navegador headless** versus uma janela visível. Consulte [Browser](/pt-BR/tools/browser). + **Observação específica do OpenClaw:** WhatsApp/Telegram/Slack/Mattermost/Discord funcionam bem em uma VPS. A única troca real é **navegador headless** vs uma janela visível. Consulte [Browser](/pt-BR/tools/browser). **Padrão recomendado:** VPS se você já teve desconexões do gateway antes. Local é ótimo quando você está usando ativamente o Mac e quer acesso a arquivos locais ou automação de UI com um navegador visível. @@ -879,20 +879,20 @@ quanto a uso/faturamento e aumente os limites conforme necessário. Não é obrigatório, mas **é recomendado para confiabilidade e isolamento**. - **Host dedicado (VPS/Mac mini/Pi):** sempre ativo, menos interrupções por suspensão/reinicialização, permissões mais limpas, mais fácil de manter em execução. - - **Laptop/desktop compartilhado:** totalmente aceitável para testes e uso ativo, mas espere pausas quando a máquina entrar em suspensão ou for atualizada. + - **Laptop/desktop compartilhado:** totalmente aceitável para testes e uso ativo, mas espere pausas quando a máquina suspender ou atualizar. - Se você quiser o melhor dos dois mundos, mantenha o Gateway em um host dedicado e pareie seu laptop como um **Node** para ferramentas locais de tela/câmera/exec. Consulte [Nodes](/pt-BR/nodes). + Se você quiser o melhor dos dois mundos, mantenha o Gateway em um host dedicado e emparelhe seu laptop como um **node** para ferramentas locais de tela/câmera/exec. Consulte [Nodes](/pt-BR/nodes). Para orientações de segurança, leia [Segurança](/pt-BR/gateway/security). - + O OpenClaw é leve. Para um Gateway básico + um canal de chat: - **Mínimo absoluto:** 1 vCPU, 1GB de RAM, ~500MB de disco. - - **Recomendado:** 1-2 vCPU, 2GB de RAM ou mais para ter folga (logs, mídia, vários canais). Ferramentas de Node e automação de navegador podem consumir muitos recursos. + - **Recomendado:** 1–2 vCPU, 2GB de RAM ou mais para folga (logs, mídia, múltiplos canais). Ferramentas de Node e automação de navegador podem exigir muitos recursos. - SO: use **Ubuntu LTS** (ou qualquer Debian/Ubuntu moderno). O caminho de instalação no Linux é o mais testado nele. + SO: use **Ubuntu LTS** (ou qualquer Debian/Ubuntu moderno). O caminho de instalação no Linux é mais bem testado nele. Documentação: [Linux](/pt-BR/platforms/linux), [Hospedagem VPS](/pt-BR/vps). @@ -905,12 +905,12 @@ quanto a uso/faturamento e aumente os limites conforme necessário. Orientação básica: - **Mínimo absoluto:** 1 vCPU, 1GB de RAM. - - **Recomendado:** 2GB de RAM ou mais se você executar vários canais, automação de navegador ou ferramentas de mídia. + - **Recomendado:** 2GB de RAM ou mais se você executar múltiplos canais, automação de navegador ou ferramentas de mídia. - **SO:** Ubuntu LTS ou outro Debian/Ubuntu moderno. - Se você estiver no Windows, o **WSL2 é a configuração estilo VM mais fácil** e tem a melhor - compatibilidade com ferramentas. Consulte [Windows](/pt-BR/platforms/windows), [Hospedagem VPS](/pt-BR/vps). - Se você estiver executando macOS em uma VM, consulte [VM de macOS](/pt-BR/install/macos-vm). + Se você estiver no Windows, **WSL2 é a configuração no estilo VM mais fácil** e tem a melhor + compatibilidade de ferramentas. Consulte [Windows](/pt-BR/platforms/windows), [Hospedagem VPS](/pt-BR/vps). + Se você estiver executando macOS em uma VM, consulte [VM macOS](/pt-BR/install/macos-vm). @@ -919,63 +919,63 @@ quanto a uso/faturamento e aumente os limites conforme necessário. - OpenClaw é um assistente pessoal de IA que você executa nos seus próprios dispositivos. Ele responde nas superfícies de mensagens que você já usa (WhatsApp, Telegram, Slack, Mattermost, Discord, Google Chat, Signal, iMessage, WebChat e plugins de canal empacotados, como QQ Bot) e também pode fazer voz + um Canvas ao vivo em plataformas compatíveis. O **Gateway** é o plano de controle sempre ativo; o assistente é o produto. + OpenClaw é um assistente pessoal de IA que você executa em seus próprios dispositivos. Ele responde nas superfícies de mensagens que você já usa (WhatsApp, Telegram, Slack, Mattermost, Discord, Google Chat, Signal, iMessage, WebChat e plugins de canal incluídos, como QQ Bot) e também pode fazer voz + um Canvas ao vivo em plataformas compatíveis. O **Gateway** é o plano de controle sempre ativo; o assistente é o produto. - OpenClaw não é “apenas um wrapper do Claude”. É um **plano de controle local-first** que permite executar um - assistente capaz no **seu próprio hardware**, acessível pelos apps de chat que você já usa, com - sessions com estado, memória e ferramentas — sem entregar o controle dos seus fluxos de trabalho a um + O OpenClaw não é "apenas um wrapper do Claude". É um **plano de controle local-first** que permite executar um + assistente capaz em **seu próprio hardware**, acessível pelos aplicativos de chat que você já usa, com + sessões com estado, memória e ferramentas — sem entregar o controle dos seus fluxos de trabalho a um SaaS hospedado. Destaques: - **Seus dispositivos, seus dados:** execute o Gateway onde quiser (Mac, Linux, VPS) e mantenha o - workspace + histórico de sessions locais. - - **Canais reais, não um sandbox web:** WhatsApp/Telegram/Slack/Discord/Signal/iMessage/etc., + workspace + histórico de sessão locais. + - **Canais reais, não uma sandbox web:** WhatsApp/Telegram/Slack/Discord/Signal/iMessage/etc., além de voz móvel e Canvas em plataformas compatíveis. - - **Independente de modelo:** use Anthropic, OpenAI, MiniMax, OpenRouter etc., com roteamento - por agent e failover. - - **Opção somente local:** execute modelos locais para que **todos os dados possam permanecer no seu dispositivo** se você quiser. + - **Agnóstico a modelo:** use Anthropic, OpenAI, MiniMax, OpenRouter etc., com roteamento por agent + e failover. + - **Opção somente local:** execute modelos locais para que **todos os dados possam permanecer no seu dispositivo** se quiser. - **Roteamento multi-agent:** agents separados por canal, conta ou tarefa, cada um com seu próprio workspace e padrões. - - **Código aberto e hackable:** inspecione, estenda e faça self-host sem lock-in de fornecedor. + - **Open source e hackable:** inspecione, estenda e faça self-host sem lock-in de fornecedor. - Documentação: [Gateway](/pt-BR/gateway), [Canais](/pt-BR/channels), [Multi-agent](/pt-BR/concepts/multi-agent), - [Memória](/pt-BR/concepts/memory). + Documentação: [Gateway](/pt-BR/gateway), [Channels](/pt-BR/channels), [Multi-agent](/pt-BR/concepts/multi-agent), + [Memory](/pt-BR/concepts/memory). - + Bons primeiros projetos: - Criar um site (WordPress, Shopify ou um site estático simples). - - Prototipar um app móvel (estrutura, telas, plano de API). - - Organizar arquivos e pastas (limpeza, nomenclatura, tags). + - Prototipar um app mobile (estrutura, telas, plano de API). + - Organizar arquivos e pastas (limpeza, nomenclatura, etiquetagem). - Conectar o Gmail e automatizar resumos ou acompanhamentos. - Ele pode lidar com tarefas grandes, mas funciona melhor quando você as divide em fases e + Ele consegue lidar com tarefas grandes, mas funciona melhor quando você as divide em fases e usa sub-agents para trabalho em paralelo. - Ganhos do dia a dia geralmente se parecem com isto: + Ganhos cotidianos geralmente se parecem com isto: - **Briefings pessoais:** resumos da caixa de entrada, calendário e notícias que importam para você. - - **Pesquisa e redação:** pesquisa rápida, resumos e primeiros rascunhos para e-mails ou documentos. - - **Lembretes e acompanhamentos:** alertas e checklists orientados por Cron ou Heartbeat. - - **Automação de navegador:** preenchimento de formulários, coleta de dados e repetição de tarefas web. - - **Coordenação entre dispositivos:** envie uma tarefa do celular, deixe o Gateway executá-la em um servidor e receba o resultado de volta no chat. + - **Pesquisa e redação:** pesquisa rápida, resumos e primeiros rascunhos de e-mails ou documentos. + - **Lembretes e acompanhamentos:** nudges e checklists orientados por cron ou Heartbeat. + - **Automação de navegador:** preencher formulários, coletar dados e repetir tarefas na web. + - **Coordenação entre dispositivos:** envie uma tarefa do seu telefone, deixe o Gateway executá-la em um servidor e receba o resultado de volta no chat. - - Sim, para **pesquisa, qualificação e redação**. Ele pode analisar sites, montar listas curtas, - resumir prospects e escrever rascunhos de outreach ou de textos de anúncio. + + Sim para **pesquisa, qualificação e redação**. Ele pode examinar sites, montar shortlists, + resumir prospects e escrever rascunhos de outreach ou de textos de anúncios. Para **outreach ou execução de anúncios**, mantenha um humano no circuito. Evite spam, siga as leis locais e - as políticas da plataforma e revise qualquer coisa antes de enviá-la. O padrão mais seguro é deixar o + as políticas da plataforma e revise tudo antes de enviar. O padrão mais seguro é deixar o OpenClaw redigir e você aprovar. Documentação: [Segurança](/pt-BR/gateway/security). @@ -983,13 +983,13 @@ quanto a uso/faturamento e aumente os limites conforme necessário. - OpenClaw é um **assistente pessoal** e uma camada de coordenação, não um substituto de IDE. Use - Claude Code ou Codex para o loop de programação direta mais rápido dentro de um repositório. Use OpenClaw quando - quiser memória durável, acesso entre dispositivos e orquestração de ferramentas. + O OpenClaw é um **assistente pessoal** e uma camada de coordenação, não um substituto de IDE. Use + Claude Code ou Codex para o loop de programação direta mais rápido dentro de um repositório. Use OpenClaw quando quiser + memória durável, acesso entre dispositivos e orquestração de ferramentas. Vantagens: - - **Memória + workspace persistentes** entre sessions + - **Memória + workspace persistentes** entre sessões - **Acesso multiplataforma** (WhatsApp, Telegram, TUI, WebChat) - **Orquestração de ferramentas** (navegador, arquivos, agendamento, hooks) - **Gateway sempre ativo** (execute em uma VPS, interaja de qualquer lugar) @@ -1003,69 +1003,69 @@ quanto a uso/faturamento e aumente os limites conforme necessário. ## Skills e automação - - Use substituições gerenciadas em vez de editar a cópia no repositório. Coloque suas alterações em `~/.openclaw/skills//SKILL.md` (ou adicione uma pasta via `skills.load.extraDirs` em `~/.openclaw/openclaw.json`). A precedência é `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → empacotado → `skills.load.extraDirs`, então as substituições gerenciadas ainda têm precedência sobre Skills empacotadas sem tocar no git. Se você precisar da Skill instalada globalmente, mas visível apenas para alguns agents, mantenha a cópia compartilhada em `~/.openclaw/skills` e controle a visibilidade com `agents.defaults.skills` e `agents.list[].skills`. Apenas alterações que valham a pena enviar upstream devem ficar no repositório e sair como PRs. + + Use substituições gerenciadas em vez de editar a cópia do repositório. Coloque suas alterações em `~/.openclaw/skills//SKILL.md` (ou adicione uma pasta via `skills.load.extraDirs` em `~/.openclaw/openclaw.json`). A precedência é `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → incluídos → `skills.load.extraDirs`, então as substituições gerenciadas ainda têm prioridade sobre as Skills incluídas sem tocar no git. Se você precisar que a Skill seja instalada globalmente, mas visível apenas para alguns agents, mantenha a cópia compartilhada em `~/.openclaw/skills` e controle a visibilidade com `agents.defaults.skills` e `agents.list[].skills`. Apenas edições dignas de upstream devem ficar no repositório e sair como PRs. - Sim. Adicione diretórios extras via `skills.load.extraDirs` em `~/.openclaw/openclaw.json` (menor precedência). A precedência padrão é `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → empacotado → `skills.load.extraDirs`. `clawhub` instala em `./skills` por padrão, que o OpenClaw trata como `/skills` na próxima session. Se a Skill só deve ficar visível para determinados agents, combine isso com `agents.defaults.skills` ou `agents.list[].skills`. + Sim. Adicione diretórios extras por meio de `skills.load.extraDirs` em `~/.openclaw/openclaw.json` (menor precedência). A precedência padrão é `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → incluídos → `skills.load.extraDirs`. O `clawhub` instala em `./skills` por padrão, que o OpenClaw trata como `/skills` na próxima sessão. Se a Skill só deve ser visível para determinados agents, combine isso com `agents.defaults.skills` ou `agents.list[].skills`. Hoje, os padrões compatíveis são: - - **Jobs de Cron**: jobs isolados podem definir uma substituição `model` por job. - - **Sub-agents**: encaminhe tarefas para agents separados com modelos padrão diferentes. - - **Troca sob demanda**: use `/model` para trocar o modelo da session atual a qualquer momento. + - **Jobs Cron**: jobs isolados podem definir uma substituição `model` por job. + - **Sub-agents**: roteie tarefas para agents separados com modelos padrão diferentes. + - **Troca sob demanda**: use `/model` para trocar o modelo da sessão atual a qualquer momento. - Consulte [Jobs de Cron](/pt-BR/automation/cron-jobs), [Roteamento multi-agent](/pt-BR/concepts/multi-agent) e [Comandos slash](/pt-BR/tools/slash-commands). + Consulte [Jobs Cron](/pt-BR/automation/cron-jobs), [Roteamento multi-agent](/pt-BR/concepts/multi-agent) e [Comandos slash](/pt-BR/tools/slash-commands). - - Use **sub-agents** para tarefas longas ou paralelas. Sub-agents são executados em sua própria session, - retornam um resumo e mantêm o chat principal responsivo. + + Use **sub-agents** para tarefas longas ou paralelas. Os sub-agents são executados em sua própria sessão, + retornam um resumo e mantêm seu chat principal responsivo. - Peça ao seu bot para “criar um sub-agent para esta tarefa” ou use `/subagents`. - Use `/status` no chat para ver o que o Gateway está fazendo agora (e se ele está ocupado). + Peça ao seu bot para "iniciar um sub-agent para esta tarefa" ou use `/subagents`. + Use `/status` no chat para ver o que o Gateway está fazendo neste momento (e se está ocupado). - Dica sobre tokens: tarefas longas e sub-agents consomem tokens. Se custo for uma preocupação, defina um + Dica sobre tokens: tarefas longas e sub-agents consomem tokens. Se o custo for uma preocupação, defina um modelo mais barato para sub-agents via `agents.defaults.subagents.model`. Documentação: [Sub-agents](/pt-BR/tools/subagents), [Tarefas em segundo plano](/pt-BR/automation/tasks). - - Use vinculações de thread. Você pode vincular uma thread do Discord a um subagent ou alvo de session para que mensagens de acompanhamento nessa thread permaneçam nessa session vinculada. + + Use vinculações de thread. Você pode vincular uma thread do Discord a um subagent ou alvo de sessão para que as mensagens de acompanhamento nessa thread permaneçam nessa sessão vinculada. Fluxo básico: - - Crie com `sessions_spawn` usando `thread: true` (e opcionalmente `mode: "session"` para acompanhamento persistente). + - Inicie com `sessions_spawn` usando `thread: true` (e opcionalmente `mode: "session"` para acompanhamento persistente). - Ou vincule manualmente com `/focus `. - Use `/agents` para inspecionar o estado da vinculação. - Use `/session idle ` e `/session max-age ` para controlar o desfoco automático. - Use `/unfocus` para desvincular a thread. - Configuração necessária: + Configuração obrigatória: - Padrões globais: `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`. - Substituições do Discord: `channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours`. - - Vinculação automática ao criar: defina `channels.discord.threadBindings.spawnSubagentSessions: true`. + - Vinculação automática ao iniciar: defina `channels.discord.threadBindings.spawnSubagentSessions: true`. Documentação: [Sub-agents](/pt-BR/tools/subagents), [Discord](/pt-BR/channels/discord), [Referência de configuração](/pt-BR/gateway/configuration-reference), [Comandos slash](/pt-BR/tools/slash-commands). - - Verifique primeiro a rota resolvida do solicitante: + + Verifique primeiro a rota do solicitante resolvida: - - A entrega de subagent em modo de conclusão dá preferência a qualquer thread vinculada ou rota de conversa quando uma existir. - - Se a origem da conclusão carregar apenas um canal, o OpenClaw recorre à rota armazenada da session solicitante (`lastChannel` / `lastTo` / `lastAccountId`) para que a entrega direta ainda possa funcionar. - - Se não existir nem uma rota vinculada nem uma rota armazenada utilizável, a entrega direta pode falhar e o resultado recai para entrega enfileirada da session em vez de ser postado imediatamente no chat. - - Alvos inválidos ou obsoletos ainda podem forçar fallback para fila ou falha final de entrega. - - Se a última resposta visível do assistente filho for exatamente o token silencioso `NO_REPLY` / `no_reply`, ou exatamente `ANNOUNCE_SKIP`, o OpenClaw suprime intencionalmente o anúncio em vez de postar progresso anterior obsoleto. - - Se o filho tiver expirado após apenas chamadas de ferramentas, o anúncio pode condensar isso em um breve resumo de progresso parcial em vez de reproduzir a saída bruta das ferramentas. + - A entrega de subagent no modo de conclusão prefere qualquer thread vinculada ou rota de conversa quando existir. + - Se a origem da conclusão trouxer apenas um canal, o OpenClaw recorre à rota armazenada da sessão do solicitante (`lastChannel` / `lastTo` / `lastAccountId`) para que a entrega direta ainda possa funcionar. + - Se não existir nem uma rota vinculada nem uma rota armazenada utilizável, a entrega direta pode falhar e o resultado recorre à entrega enfileirada da sessão em vez de ser publicado imediatamente no chat. + - Alvos inválidos ou obsoletos ainda podem forçar o fallback para fila ou a falha da entrega final. + - Se a última resposta visível do assistente filho for exatamente o token silencioso `NO_REPLY` / `no_reply`, ou exatamente `ANNOUNCE_SKIP`, o OpenClaw suprime intencionalmente o anúncio em vez de publicar um progresso anterior obsoleto. + - Se o filho expirar após apenas chamadas de ferramenta, o anúncio pode condensar isso em um breve resumo de progresso parcial em vez de reproduzir a saída bruta das ferramentas. Depuração: @@ -1073,7 +1073,7 @@ quanto a uso/faturamento e aumente os limites conforme necessário. openclaw tasks show ``` - Documentação: [Sub-agents](/pt-BR/tools/subagents), [Tarefas em segundo plano](/pt-BR/automation/tasks), [Ferramentas de session](/pt-BR/concepts/session-tool). + Documentação: [Sub-agents](/pt-BR/tools/subagents), [Tarefas em segundo plano](/pt-BR/automation/tasks), [Ferramentas de sessão](/pt-BR/concepts/session-tool). @@ -1083,9 +1083,9 @@ quanto a uso/faturamento e aumente os limites conforme necessário. Checklist: - - Confirme que o Cron está habilitado (`cron.enabled`) e que `OPENCLAW_SKIP_CRON` não está definido. + - Confirme que o Cron está ativado (`cron.enabled`) e que `OPENCLAW_SKIP_CRON` não está definido. - Verifique se o Gateway está em execução 24/7 (sem suspensão/reinicializações). - - Verifique as configurações de fuso horário do job (`--tz` versus o fuso horário do host). + - Verifique as configurações de fuso horário para o job (`--tz` vs fuso horário do host). Depuração: @@ -1094,7 +1094,7 @@ quanto a uso/faturamento e aumente os limites conforme necessário. openclaw cron runs --id --limit 50 ``` - Documentação: [Jobs de Cron](/pt-BR/automation/cron-jobs), [Automação e Tarefas](/pt-BR/automation). + Documentação: [Jobs Cron](/pt-BR/automation/cron-jobs), [Automação & Tarefas](/pt-BR/automation). @@ -1106,7 +1106,7 @@ quanto a uso/faturamento e aumente os limites conforme necessário. - Falhas de autenticação do canal (`unauthorized`, `Forbidden`) significam que o executor tentou entregar, mas as credenciais bloquearam. - Um resultado isolado silencioso (`NO_REPLY` / `no_reply` apenas) é tratado como intencionalmente não entregável, então o executor também suprime a entrega de fallback enfileirada. - Para jobs de Cron isolados, o executor é responsável pela entrega final. Espera-se + Para jobs Cron isolados, o executor é o responsável pela entrega final. Espera-se que o agent retorne um resumo em texto simples para o executor enviar. `--no-deliver` mantém esse resultado interno; ele não permite que o agent envie diretamente com a ferramenta de mensagem. @@ -1118,27 +1118,27 @@ quanto a uso/faturamento e aumente os limites conforme necessário. openclaw tasks show ``` - Documentação: [Jobs de Cron](/pt-BR/automation/cron-jobs), [Tarefas em segundo plano](/pt-BR/automation/tasks). + Documentação: [Jobs Cron](/pt-BR/automation/cron-jobs), [Tarefas em segundo plano](/pt-BR/automation/tasks). - - Isso geralmente é o caminho ativo de troca de modelo, não agendamento duplicado. + + Isso geralmente é o caminho de troca de modelo ao vivo, não um agendamento duplicado. O Cron isolado pode persistir uma transferência de modelo em tempo de execução e tentar novamente quando a - execução ativa gera `LiveSessionModelSwitchError`. A nova tentativa mantém o - provedor/modelo alterado e, se a troca trouxe uma nova substituição de perfil de autenticação, o Cron + execução ativa lançar `LiveSessionModelSwitchError`. A nova tentativa mantém o + provedor/modelo trocado e, se a troca trouxe uma nova substituição de perfil de autenticação, o Cron também a persiste antes de tentar novamente. - Regras relacionadas de seleção: + Regras de seleção relacionadas: - A substituição de modelo do hook do Gmail vence primeiro, quando aplicável. - - Depois vem `model` por job. - - Depois qualquer substituição de modelo de cron-session armazenada. - - Depois a seleção normal de modelo padrão/do agent. + - Depois, `model` por job. + - Depois, qualquer substituição de modelo armazenada da sessão cron. + - Depois, a seleção normal de modelo padrão/do agent. - O loop de nova tentativa é limitado. Após a tentativa inicial mais 2 novas tentativas por troca, - o Cron aborta em vez de entrar em loop infinito. + O loop de nova tentativa é limitado. Após a tentativa inicial mais 2 novas tentativas de troca, + o Cron aborta em vez de entrar em loop para sempre. Depuração: @@ -1147,7 +1147,7 @@ quanto a uso/faturamento e aumente os limites conforme necessário. openclaw tasks show ``` - Documentação: [Jobs de Cron](/pt-BR/automation/cron-jobs), [CLI do cron](/cli/cron). + Documentação: [Jobs Cron](/pt-BR/automation/cron-jobs), [CLI do cron](/cli/cron). @@ -1167,38 +1167,38 @@ quanto a uso/faturamento e aumente os limites conforme necessário. ``` A instalação nativa com `openclaw skills install` grava no diretório `skills/` - do workspace ativo. Instale a CLI separada `clawhub` apenas se quiser publicar ou + do workspace ativo. Instale a CLI `clawhub` separada apenas se quiser publicar ou sincronizar suas próprias Skills. Para instalações compartilhadas entre agents, coloque a Skill em `~/.openclaw/skills` e use `agents.defaults.skills` ou `agents.list[].skills` se quiser restringir quais agents podem vê-la. - + Sim. Use o agendador do Gateway: - - **Jobs de Cron** para tarefas agendadas ou recorrentes (persistem entre reinicializações). - - **Heartbeat** para verificações periódicas da "session principal". - - **Jobs isolados** para agents autônomos que postam resumos ou entregam em chats. + - **Jobs Cron** para tarefas agendadas ou recorrentes (persistem após reinicializações). + - **Heartbeat** para verificações periódicas da "sessão principal". + - **Jobs isolados** para agents autônomos que publicam resumos ou entregam em chats. - Documentação: [Jobs de Cron](/pt-BR/automation/cron-jobs), [Automação e Tarefas](/pt-BR/automation), + Documentação: [Jobs Cron](/pt-BR/automation/cron-jobs), [Automação & Tarefas](/pt-BR/automation), [Heartbeat](/pt-BR/gateway/heartbeat). - - Não diretamente. Skills do macOS são controladas por `metadata.openclaw.os` mais os binários necessários, e as Skills só aparecem no prompt do sistema quando são elegíveis no **host do Gateway**. No Linux, Skills exclusivas de `darwin` (como `apple-notes`, `apple-reminders`, `things-mac`) não serão carregadas a menos que você substitua esse controle. + + Não diretamente. As Skills do macOS são controladas por `metadata.openclaw.os` mais binários obrigatórios, e as Skills só aparecem no prompt do sistema quando são elegíveis no **host do Gateway**. No Linux, Skills exclusivas de `darwin` (como `apple-notes`, `apple-reminders`, `things-mac`) não serão carregadas a menos que você substitua esse controle. Você tem três padrões compatíveis: **Opção A - executar o Gateway em um Mac (mais simples).** - Execute o Gateway onde os binários do macOS existam e depois conecte-se a partir do Linux em [modo remoto](#gateway-ports-already-running-and-remote-mode) ou via Tailscale. As Skills são carregadas normalmente porque o host do Gateway é macOS. + Execute o Gateway onde os binários do macOS existirem e depois conecte-se a partir do Linux em [modo remoto](#gateway-ports-already-running-and-remote-mode) ou via Tailscale. As Skills são carregadas normalmente porque o host do Gateway é macOS. **Opção B - usar um node macOS (sem SSH).** - Execute o Gateway no Linux, pareie um node macOS (app de barra de menu) e defina **Node Run Commands** como "Always Ask" ou "Always Allow" no Mac. O OpenClaw pode tratar Skills exclusivas do macOS como elegíveis quando os binários necessários existirem no node. O agent executa essas Skills por meio da ferramenta `nodes`. Se você escolher "Always Ask", aprovar "Always Allow" no prompt adiciona esse comando à allowlist. + Execute o Gateway no Linux, emparelhe um node macOS (app de barra de menu) e defina **Node Run Commands** como "Always Ask" ou "Always Allow" no Mac. O OpenClaw pode tratar Skills exclusivas do macOS como elegíveis quando os binários exigidos existirem no node. O agent executa essas Skills por meio da ferramenta `nodes`. Se você escolher "Always Ask", aprovar "Always Allow" no prompt adiciona esse comando à allowlist. - **Opção C - fazer proxy de binários do macOS via SSH (avançado).** - Mantenha o Gateway no Linux, mas faça com que os binários CLI necessários resolvam para wrappers SSH que são executados em um Mac. Depois substitua a Skill para permitir Linux, para que ela continue elegível. + **Opção C - fazer proxy de binários do macOS por SSH (avançado).** + Mantenha o Gateway no Linux, mas faça com que os binários CLI exigidos sejam resolvidos para wrappers SSH executados em um Mac. Depois substitua a Skill para permitir Linux, para que ela permaneça elegível. 1. Crie um wrapper SSH para o binário (exemplo: `memo` para Apple Notes): @@ -1208,45 +1208,45 @@ quanto a uso/faturamento e aumente os limites conforme necessário. exec ssh -T user@mac-host /opt/homebrew/bin/memo "$@" ``` - 2. Coloque o wrapper no `PATH` do host Linux (por exemplo `~/bin/memo`). + 2. Coloque o wrapper no `PATH` no host Linux (por exemplo `~/bin/memo`). 3. Substitua os metadados da Skill (workspace ou `~/.openclaw/skills`) para permitir Linux: ```markdown --- name: apple-notes - description: Manage Apple Notes via the memo CLI on macOS. + description: Gerencie Apple Notes por meio da CLI memo no macOS. metadata: { "openclaw": { "os": ["darwin", "linux"], "requires": { "bins": ["memo"] } } } --- ``` - 4. Inicie uma nova session para atualizar o snapshot de Skills. + 4. Inicie uma nova sessão para que o snapshot de Skills seja atualizado. - Hoje não há integração nativa. + Não integrada nativamente no momento. Opções: - - **Skill / Plugin personalizado:** melhor para acesso confiável à API (Notion e HeyGen têm APIs). + - **Skill / Plugin personalizado:** melhor para acesso confiável à API (Notion/HeyGen têm APIs). - **Automação de navegador:** funciona sem código, mas é mais lenta e mais frágil. Se você quiser manter contexto por cliente (fluxos de trabalho de agência), um padrão simples é: - Uma página do Notion por cliente (contexto + preferências + trabalho ativo). - - Pedir ao agent para buscar essa página no início de uma session. + - Pedir ao agent para buscar essa página no início de uma sessão. - Se você quiser uma integração nativa, abra uma solicitação de recurso ou crie uma Skill + Se você quiser uma integração nativa, abra uma solicitação de funcionalidade ou crie uma Skill voltada para essas APIs. - Instalar Skills: + Instale Skills: ```bash openclaw skills install openclaw skills update --all ``` - Instalações nativas vão para o diretório `skills/` do workspace ativo. Para Skills compartilhadas entre agents, coloque-as em `~/.openclaw/skills//SKILL.md`. Se apenas alguns agents devem ver uma instalação compartilhada, configure `agents.defaults.skills` ou `agents.list[].skills`. Algumas Skills esperam binários instalados via Homebrew; no Linux isso significa Linuxbrew (consulte a entrada da FAQ sobre Homebrew no Linux acima). Consulte [Skills](/pt-BR/tools/skills), [Configuração de Skills](/pt-BR/tools/skills-config) e [ClawHub](/pt-BR/tools/clawhub). + Instalações nativas chegam ao diretório `skills/` do workspace ativo. Para Skills compartilhadas entre agents, coloque-as em `~/.openclaw/skills//SKILL.md`. Se apenas alguns agents devem ver uma instalação compartilhada, configure `agents.defaults.skills` ou `agents.list[].skills`. Algumas Skills esperam binários instalados via Homebrew; no Linux isso significa Linuxbrew (consulte a entrada de FAQ do Homebrew no Linux acima). Consulte [Skills](/pt-BR/tools/skills), [Configuração de Skills](/pt-BR/tools/skills-config) e [ClawHub](/pt-BR/tools/clawhub). @@ -1265,31 +1265,31 @@ quanto a uso/faturamento e aumente os limites conforme necessário. openclaw browser --browser-profile chrome-live tabs ``` - Esse caminho é local ao host. Se o Gateway estiver em outro lugar, execute um host de node na máquina do navegador ou use CDP remoto. + Esse caminho pode usar o navegador do host local ou um node de navegador conectado. Se o Gateway estiver em outro lugar, execute um host de node na máquina do navegador ou use CDP remoto. - Limitações atuais em `existing-session` / `user`: + Limites atuais em `existing-session` / `user`: - - as ações são orientadas por ref, não por seletor CSS - - uploads exigem `ref` / `inputRef` e atualmente oferecem suporte a um arquivo por vez - - `responsebody`, exportação em PDF, interceptação de downloads e ações em lote ainda exigem um navegador gerenciado ou um perfil CDP bruto + - as ações são guiadas por ref, não por seletor CSS + - uploads exigem `ref` / `inputRef` e atualmente aceitam um arquivo por vez + - `responsebody`, exportação de PDF, interceptação de download e ações em lote ainda exigem um navegador gerenciado ou um perfil CDP bruto -## Sandboxing e memória +## Sandbox e memória - + Sim. Consulte [Sandboxing](/pt-BR/gateway/sandboxing). Para configuração específica de Docker (gateway completo em Docker ou imagens de sandbox), consulte [Docker](/pt-BR/install/docker). - - A imagem padrão prioriza segurança e é executada como usuário `node`, então ela não - inclui pacotes de sistema, Homebrew nem navegadores empacotados. Para uma configuração mais completa: + + A imagem padrão prioriza segurança e é executada como o usuário `node`, então ela não + inclui pacotes de sistema, Homebrew nem navegadores incluídos. Para uma configuração mais completa: - Persista `/home/node` com `OPENCLAW_HOME_VOLUME` para que os caches sobrevivam. - Incorpore dependências de sistema na imagem com `OPENCLAW_DOCKER_APT_PACKAGES`. - - Instale navegadores do Playwright via a CLI empacotada: + - Instale navegadores Playwright pela CLI incluída: `node /app/node_modules/playwright-core/cli.js install chromium` - Defina `PLAYWRIGHT_BROWSERS_PATH` e garanta que o caminho seja persistido. @@ -1298,20 +1298,20 @@ quanto a uso/faturamento e aumente os limites conforme necessário. - Sim — se o seu tráfego privado for em **DMs** e o tráfego público em **grupos**. + Sim — se seu tráfego privado for **DMs** e seu tráfego público for **grupos**. - Use `agents.defaults.sandbox.mode: "non-main"` para que sessions de grupo/canal (chaves não principais) sejam executadas no Docker, enquanto a session principal de DM permanece no host. Depois restrinja quais ferramentas ficam disponíveis nas sessions em sandbox via `tools.sandbox.tools`. + Use `agents.defaults.sandbox.mode: "non-main"` para que sessões de grupo/canal (chaves não principais) sejam executadas em Docker, enquanto a sessão principal de DM permanece no host. Depois restrinja quais ferramentas ficam disponíveis nas sessões em sandbox via `tools.sandbox.tools`. Passo a passo de configuração + exemplo: [Grupos: DMs pessoais + grupos públicos](/pt-BR/channels/groups#pattern-personal-dms-public-groups-single-agent) - Referência principal de configuração: [Configuração do Gateway](/pt-BR/gateway/configuration-reference#agentsdefaultssandbox) + Referência de configuração principal: [Configuração do Gateway](/pt-BR/gateway/configuration-reference#agentsdefaultssandbox) - Defina `agents.defaults.sandbox.docker.binds` como `["host:path:mode"]` (por exemplo, `"/home/user/src:/src:ro"`). Vinculações globais + por agent são mescladas; vinculações por agent são ignoradas quando `scope: "shared"`. Use `:ro` para qualquer coisa sensível e lembre-se de que as vinculações contornam as barreiras do sistema de arquivos do sandbox. + Defina `agents.defaults.sandbox.docker.binds` como `["host:path:mode"]` (ex.: `"/home/user/src:/src:ro"`). Vinculações globais + por agent são mescladas; vinculações por agent são ignoradas quando `scope: "shared"`. Use `:ro` para qualquer coisa sensível e lembre-se de que as vinculações contornam as barreiras do sistema de arquivos do sandbox. - O OpenClaw valida origens de bind usando tanto o caminho normalizado quanto o caminho canônico resolvido por meio do ancestral existente mais profundo. Isso significa que escapes por symlink em diretório pai ainda falham de forma segura, mesmo quando o último segmento do caminho ainda não existe, e as verificações de allowed-root continuam sendo aplicadas após a resolução do symlink. + O OpenClaw valida origens de bind tanto em relação ao caminho normalizado quanto ao caminho canônico resolvido por meio do ancestral existente mais profundo. Isso significa que escapes por symlink-parent ainda falham de forma segura mesmo quando o último segmento do caminho ainda não existe, e as verificações de raiz permitida continuam se aplicando após a resolução de symlink. Consulte [Sandboxing](/pt-BR/gateway/sandboxing#custom-bind-mounts) e [Sandbox vs Tool Policy vs Elevated](/pt-BR/gateway/sandbox-vs-tool-policy-vs-elevated#bind-mounts-security-quick-check) para exemplos e observações de segurança. @@ -1321,56 +1321,56 @@ quanto a uso/faturamento e aumente os limites conforme necessário. A memória do OpenClaw são apenas arquivos Markdown no workspace do agent: - Notas diárias em `memory/YYYY-MM-DD.md` - - Notas curadas de longo prazo em `MEMORY.md` (apenas sessions principais/privadas) + - Notas curadas de longo prazo em `MEMORY.md` (somente sessões principais/privadas) - O OpenClaw também executa um **flush silencioso de memória antes da Compaction** para lembrar o modelo - de gravar notas duráveis antes da Compaction automática. Isso só é executado quando o workspace - pode ser gravado (sandboxes somente leitura ignoram isso). Consulte [Memória](/pt-BR/concepts/memory). + O OpenClaw também executa uma **gravação silenciosa de memória antes da Compaction** para lembrar o modelo + de escrever notas duráveis antes da Compaction automática. Isso só é executado quando o workspace + pode ser gravado (sandboxes somente leitura pulam isso). Consulte [Memory](/pt-BR/concepts/memory). - Peça ao bot para **gravar o fato na memória**. Notas de longo prazo devem ficar em `MEMORY.md`, - e contexto de curto prazo vai para `memory/YYYY-MM-DD.md`. + Peça ao bot para **gravar o fato na memória**. Notas de longo prazo pertencem a `MEMORY.md`, + contexto de curto prazo vai em `memory/YYYY-MM-DD.md`. - Esta ainda é uma área que estamos aprimorando. Ajuda lembrar o modelo de armazenar memórias; + Esta ainda é uma área que estamos melhorando. Ajuda lembrar o modelo para armazenar memórias; ele saberá o que fazer. Se ele continuar esquecendo, verifique se o Gateway está usando o mesmo workspace em todas as execuções. - Documentação: [Memória](/pt-BR/concepts/memory), [Workspace do agent](/pt-BR/concepts/agent-workspace). + Documentação: [Memory](/pt-BR/concepts/memory), [Workspace do agent](/pt-BR/concepts/agent-workspace). - Os arquivos de memória ficam no disco e persistem até que você os exclua. O limite é seu - armazenamento, não o modelo. O **contexto da session** ainda é limitado pela janela de - contexto do modelo, então conversas longas podem sofrer Compaction ou truncamento. É por isso - que a busca de memória existe — ela traz apenas as partes relevantes de volta para o contexto. + Os arquivos de memória ficam no disco e persistem até você excluí-los. O limite é o seu + armazenamento, não o modelo. O **contexto da sessão** ainda é limitado pela janela de contexto do modelo, + então conversas longas podem sofrer Compaction ou truncamento. É por isso que + a busca de memória existe — ela traz de volta ao contexto apenas as partes relevantes. - Documentação: [Memória](/pt-BR/concepts/memory), [Contexto](/pt-BR/concepts/context). + Documentação: [Memory](/pt-BR/concepts/memory), [Context](/pt-BR/concepts/context). Apenas se você usar **embeddings da OpenAI**. O OAuth do Codex cobre chat/completions e - **não** concede acesso a embeddings, portanto **fazer login com Codex (OAuth ou pelo - login do Codex CLI)** não ajuda na busca semântica de memória. Embeddings da OpenAI - ainda exigem uma chave de API real (`OPENAI_API_KEY` ou `models.providers.openai.apiKey`). + **não** concede acesso a embeddings, então **fazer login com Codex (OAuth ou o + login da CLI do Codex)** não ajuda para busca semântica de memória. Embeddings da OpenAI + ainda precisam de uma chave de API real (`OPENAI_API_KEY` ou `models.providers.openai.apiKey`). Se você não definir um provedor explicitamente, o OpenClaw seleciona automaticamente um provedor quando - consegue resolver uma chave de API (perfis de autenticação, `models.providers.*.apiKey` ou variáveis de ambiente). - Ele prefere OpenAI se uma chave da OpenAI for resolvida, senão Gemini se uma chave do Gemini - for resolvida, depois Voyage e depois Mistral. Se nenhuma chave remota estiver disponível, a busca de - memória permanece desativada até que você a configure. Se você tiver um caminho de modelo local + consegue resolver uma chave de API (perfis de autenticação, `models.providers.*.apiKey` ou vars de ambiente). + Ele prefere OpenAI se resolver uma chave OpenAI, caso contrário Gemini se resolver uma chave Gemini, + depois Voyage e depois Mistral. Se nenhuma chave remota estiver disponível, a busca de memória + permanece desativada até você configurá-la. Se você tiver um caminho de modelo local configurado e presente, o OpenClaw prefere `local`. Ollama é compatível quando você define explicitamente `memorySearch.provider = "ollama"`. Se você preferir permanecer local, defina `memorySearch.provider = "local"` (e opcionalmente - `memorySearch.fallback = "none"`). Se você quiser embeddings do Gemini, defina + `memorySearch.fallback = "none"`). Se quiser embeddings do Gemini, defina `memorySearch.provider = "gemini"` e forneça `GEMINI_API_KEY` (ou - `memorySearch.remote.apiKey`). Oferecemos suporte a modelos de embedding **OpenAI, Gemini, Voyage, Mistral, Ollama ou local** — - consulte [Memória](/pt-BR/concepts/memory) para detalhes de configuração. + `memorySearch.remote.apiKey`). Oferecemos suporte a modelos de embedding **OpenAI, Gemini, Voyage, Mistral, Ollama ou local** + — consulte [Memory](/pt-BR/concepts/memory) para os detalhes de configuração. @@ -1379,17 +1379,17 @@ quanto a uso/faturamento e aumente os limites conforme necessário. - Não — **o estado do OpenClaw é local**, mas **serviços externos ainda veem o que você envia para eles**. + Não — **o estado do OpenClaw é local**, mas **serviços externos ainda veem o que você envia a eles**. - - **Local por padrão:** sessions, arquivos de memória, configuração e workspace ficam no host do Gateway - (`~/.openclaw` + o diretório do seu workspace). + - **Local por padrão:** sessões, arquivos de memória, configuração e workspace ficam no host do Gateway + (`~/.openclaw` + seu diretório de workspace). - **Remoto por necessidade:** mensagens que você envia a provedores de modelo (Anthropic/OpenAI/etc.) vão para - as APIs deles, e plataformas de chat (WhatsApp/Telegram/Slack/etc.) armazenam dados de mensagem em seus + as APIs deles, e plataformas de chat (WhatsApp/Telegram/Slack/etc.) armazenam dados de mensagens em seus servidores. - - **Você controla a pegada:** usar modelos locais mantém os prompts na sua máquina, mas o - tráfego do canal ainda passa pelos servidores do canal. + - **Você controla a superfície:** usar modelos locais mantém os prompts na sua máquina, mas o tráfego + do canal ainda passa pelos servidores do canal. - Relacionado: [Workspace do agent](/pt-BR/concepts/agent-workspace), [Memória](/pt-BR/concepts/memory). + Relacionado: [Workspace do agent](/pt-BR/concepts/agent-workspace), [Memory](/pt-BR/concepts/memory). @@ -1400,17 +1400,17 @@ quanto a uso/faturamento e aumente os limites conforme necessário. | --------------------------------------------------------------- | ------------------------------------------------------------------ | | `$OPENCLAW_STATE_DIR/openclaw.json` | Configuração principal (JSON5) | | `$OPENCLAW_STATE_DIR/credentials/oauth.json` | Importação legada de OAuth (copiada para perfis de autenticação no primeiro uso) | - | `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | Perfis de autenticação (OAuth, chaves de API e opcionais `keyRef`/`tokenRef`) | - | `$OPENCLAW_STATE_DIR/secrets.json` | Payload de segredo opcional baseado em arquivo para provedores `file` de SecretRef | - | `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | Arquivo legado de compatibilidade (entradas estáticas `api_key` removidas) | - | `$OPENCLAW_STATE_DIR/credentials/` | Estado do provedor (por exemplo `whatsapp//creds.json`) | - | `$OPENCLAW_STATE_DIR/agents/` | Estado por agent (agentDir + sessions) | + | `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | Perfis de autenticação (OAuth, chaves de API e `keyRef`/`tokenRef` opcionais) | + | `$OPENCLAW_STATE_DIR/secrets.json` | Payload opcional de segredo baseado em arquivo para provedores `file` de SecretRef | + | `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | Arquivo legado de compatibilidade (entradas estáticas `api_key` limpas) | + | `$OPENCLAW_STATE_DIR/credentials/` | Estado do provedor (ex.: `whatsapp//creds.json`) | + | `$OPENCLAW_STATE_DIR/agents/` | Estado por agent (agentDir + sessões) | | `$OPENCLAW_STATE_DIR/agents//sessions/` | Histórico e estado da conversa (por agent) | - | `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | Metadados da session (por agent) | + | `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | Metadados de sessão (por agent) | Caminho legado de agent único: `~/.openclaw/agent/*` (migrado por `openclaw doctor`). - Seu **workspace** (`AGENTS.md`, arquivos de memória, Skills etc.) é separado e configurado via `agents.defaults.workspace` (padrão: `~/.openclaw/workspace`). + Seu **workspace** (`AGENTS.md`, arquivos de memória, Skills etc.) é separado e configurado por `agents.defaults.workspace` (padrão: `~/.openclaw/workspace`). @@ -1420,10 +1420,10 @@ quanto a uso/faturamento e aumente os limites conforme necessário. - **Workspace (por agent)**: `AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`, `MEMORY.md` (ou o fallback legado `memory.md` quando `MEMORY.md` estiver ausente), `memory/YYYY-MM-DD.md`, `HEARTBEAT.md` opcional. - - **Diretório de estado (`~/.openclaw`)**: configuração, estado de canal/provedor, perfis de autenticação, sessions, logs + - **Diretório de estado (`~/.openclaw`)**: configuração, estado de canal/provedor, perfis de autenticação, sessões, logs e Skills compartilhadas (`~/.openclaw/skills`). - O workspace padrão é `~/.openclaw/workspace`, configurável via: + O workspace padrão é `~/.openclaw/workspace`, configurável por: ```json5 { @@ -1431,25 +1431,25 @@ quanto a uso/faturamento e aumente os limites conforme necessário. } ``` - Se o bot “esquecer” após uma reinicialização, confirme que o Gateway está usando o mesmo + Se o bot "esquece" após uma reinicialização, confirme que o Gateway está usando o mesmo workspace em todas as inicializações (e lembre-se: o modo remoto usa o workspace do **host do gateway**, não o do seu laptop local). - Dica: se você quiser um comportamento ou preferência durável, peça ao bot para **escrever isso em + Dica: se você quiser um comportamento ou preferência durável, peça ao bot para **gravar isso em AGENTS.md ou MEMORY.md** em vez de depender do histórico do chat. - Consulte [Workspace do agent](/pt-BR/concepts/agent-workspace) e [Memória](/pt-BR/concepts/memory). + Consulte [Workspace do agent](/pt-BR/concepts/agent-workspace) e [Memory](/pt-BR/concepts/memory). - Coloque seu **workspace do agent** em um repositório git **privado** e faça backup dele em algum - lugar privado (por exemplo, GitHub privado). Isso captura memória + arquivos AGENTS/SOUL/USER - e permite restaurar a “mente” do assistente depois. + Coloque seu **workspace do agent** em um repositório git **privado** e faça backup dele em algum lugar + privado (por exemplo, GitHub privado). Isso captura memória + arquivos AGENTS/SOUL/USER + e permite restaurar a "mente" do assistente depois. - **Não** faça commit de nada em `~/.openclaw` (credenciais, sessions, tokens ou payloads de segredos criptografados). - Se você precisar de uma restauração completa, faça backup separadamente do workspace e do diretório - de estado (veja a pergunta sobre migração acima). + **Não** faça commit de nada dentro de `~/.openclaw` (credenciais, sessões, tokens ou payloads de segredos criptografados). + Se você precisar de uma restauração completa, faça backup tanto do workspace quanto do diretório de estado + separadamente (consulte a pergunta de migração acima). Documentação: [Workspace do agent](/pt-BR/concepts/agent-workspace). @@ -1459,13 +1459,13 @@ quanto a uso/faturamento e aumente os limites conforme necessário. Consulte o guia dedicado: [Desinstalar](/pt-BR/install/uninstall). - - Sim. O workspace é o **cwd padrão** e a âncora de memória, não um sandbox rígido. + + Sim. O workspace é o **cwd padrão** e âncora de memória, não um sandbox rígido. Caminhos relativos são resolvidos dentro do workspace, mas caminhos absolutos podem acessar outros - locais do host, a menos que o sandboxing esteja habilitado. Se você precisar de isolamento, use + locais do host, a menos que o sandboxing esteja ativado. Se você precisar de isolamento, use [`agents.defaults.sandbox`](/pt-BR/gateway/sandboxing) ou configurações de sandbox por agent. Se você - quiser que um repositório seja o diretório de trabalho padrão, aponte o - `workspace` desse agent para a raiz do repositório. O repositório do OpenClaw é apenas código-fonte; mantenha o + quiser que um repositório seja o diretório de trabalho padrão, aponte o `workspace` + desse agent para a raiz do repositório. O repositório do OpenClaw é apenas código-fonte; mantenha o workspace separado, a menos que você queira intencionalmente que o agent trabalhe dentro dele. Exemplo (repositório como cwd padrão): @@ -1482,12 +1482,12 @@ quanto a uso/faturamento e aumente os limites conforme necessário. - - O estado da session pertence ao **host do gateway**. Se você estiver em modo remoto, o armazenamento de sessions que importa está na máquina remota, não no seu laptop local. Consulte [Gerenciamento de session](/pt-BR/concepts/session). + + O estado da sessão pertence ao **host do gateway**. Se você estiver em modo remoto, o armazenamento de sessões que importa está na máquina remota, não no seu laptop local. Consulte [Gerenciamento de sessão](/pt-BR/concepts/session). -## Conceitos básicos de configuração +## Noções básicas de configuração @@ -1497,15 +1497,15 @@ quanto a uso/faturamento e aumente os limites conforme necessário. $OPENCLAW_CONFIG_PATH ``` - Se o arquivo estiver ausente, ele usará padrões razoavelmente seguros (incluindo um workspace padrão em `~/.openclaw/workspace`). + Se o arquivo estiver ausente, ele usa padrões razoavelmente seguros (incluindo um workspace padrão em `~/.openclaw/workspace`). - - Bindings sem loopback **exigem um caminho válido de autenticação do gateway**. Na prática, isso significa: + + Binds sem loopback **exigem um caminho de autenticação válido do gateway**. Na prática, isso significa: - autenticação por segredo compartilhado: token ou senha - - `gateway.auth.mode: "trusted-proxy"` atrás de um proxy reverso com reconhecimento de identidade, corretamente configurado e sem loopback + - `gateway.auth.mode: "trusted-proxy"` atrás de um proxy reverso com reconhecimento de identidade sem loopback e configurado corretamente ```json5 { @@ -1521,31 +1521,31 @@ quanto a uso/faturamento e aumente os limites conforme necessário. Observações: - - `gateway.remote.token` / `.password` por si só **não** habilitam autenticação local do gateway. - - Caminhos de chamada locais podem usar `gateway.remote.*` como fallback somente quando `gateway.auth.*` não estiver definido. + - `gateway.remote.token` / `.password` **não** ativam a autenticação local do gateway por si só. + - Caminhos de chamada locais podem usar `gateway.remote.*` como fallback apenas quando `gateway.auth.*` não estiver definido. - Para autenticação por senha, defina `gateway.auth.mode: "password"` mais `gateway.auth.password` (ou `OPENCLAW_GATEWAY_PASSWORD`). - - Se `gateway.auth.token` / `gateway.auth.password` estiver explicitamente configurado via SecretRef e não puder ser resolvido, a resolução falha de forma segura (sem mascaramento por fallback remoto). - - Configurações da Control UI com segredo compartilhado autenticam via `connect.params.auth.token` ou `connect.params.auth.password` (armazenados nas configurações do app/UI). Modos com identidade, como Tailscale Serve ou `trusted-proxy`, usam cabeçalhos da requisição. Evite colocar segredos compartilhados em URLs. - - Com `gateway.auth.mode: "trusted-proxy"`, proxies reversos de loopback no mesmo host ainda **não** satisfazem a autenticação por trusted-proxy. O trusted proxy precisa ser uma origem configurada sem loopback. + - Se `gateway.auth.token` / `gateway.auth.password` estiver explicitamente configurado via SecretRef e não for resolvido, a resolução falha de forma segura (sem mascaramento por fallback remoto). + - Configurações da Control UI com segredo compartilhado autenticam via `connect.params.auth.token` ou `connect.params.auth.password` (armazenados nas configurações do app/UI). Modos com identidade, como Tailscale Serve ou `trusted-proxy`, usam cabeçalhos da solicitação em vez disso. Evite colocar segredos compartilhados em URLs. + - Com `gateway.auth.mode: "trusted-proxy"`, proxies reversos em loopback no mesmo host ainda **não** satisfazem a autenticação trusted-proxy. O proxy confiável deve ser uma origem sem loopback configurada. - O OpenClaw aplica autenticação do gateway por padrão, inclusive em loopback. No caminho padrão normal, isso significa autenticação por token: se nenhum caminho explícito de autenticação estiver configurado, a inicialização do gateway resolve para o modo token e gera um automaticamente, salvando-o em `gateway.auth.token`, então **clientes WS locais precisam se autenticar**. Isso bloqueia que outros processos locais chamem o Gateway. + O OpenClaw aplica autenticação do gateway por padrão, inclusive no loopback. No caminho padrão normal, isso significa autenticação por token: se nenhum caminho de autenticação explícito estiver configurado, a inicialização do gateway resolve para o modo token e gera um automaticamente, salvando-o em `gateway.auth.token`, então **clientes WS locais precisam se autenticar**. Isso impede que outros processos locais chamem o Gateway. - Se você preferir um caminho diferente de autenticação, pode escolher explicitamente o modo senha (ou, para proxies reversos sem loopback com reconhecimento de identidade, `trusted-proxy`). Se você **realmente** quiser loopback aberto, defina explicitamente `gateway.auth.mode: "none"` na sua configuração. O Doctor pode gerar um token para você a qualquer momento: `openclaw doctor --generate-gateway-token`. + Se você preferir um caminho de autenticação diferente, pode escolher explicitamente o modo senha (ou, para proxies reversos sem loopback e com reconhecimento de identidade, `trusted-proxy`). Se você **realmente** quiser loopback aberto, defina `gateway.auth.mode: "none"` explicitamente em sua configuração. O Doctor pode gerar um token para você a qualquer momento: `openclaw doctor --generate-gateway-token`. - + O Gateway observa a configuração e oferece suporte a hot-reload: - - `gateway.reload.mode: "hybrid"` (padrão): aplica a quente mudanças seguras, reinicia para mudanças críticas + - `gateway.reload.mode: "hybrid"` (padrão): aplica a quente alterações seguras, reinicia para as críticas - `hot`, `restart`, `off` também são compatíveis - + Defina `cli.banner.taglineMode` na configuração: ```json5 @@ -1558,24 +1558,24 @@ quanto a uso/faturamento e aumente os limites conforme necessário. } ``` - - `off`: oculta o texto do slogan, mas mantém a linha do título/versão do banner. - - `default`: usa `All your chats, one OpenClaw.` sempre. + - `off`: oculta o texto do slogan, mas mantém a linha de título/versão do banner. + - `default`: usa `All your chats, one OpenClaw.` todas as vezes. - `random`: slogans engraçados/sazonais rotativos (comportamento padrão). - - Se você não quiser banner nenhum, defina a variável de ambiente `OPENCLAW_HIDE_BANNER=1`. + - Se você quiser nenhum banner, defina a env `OPENCLAW_HIDE_BANNER=1`. - - `web_fetch` funciona sem chave de API. `web_search` depende do provedor - selecionado: + + `web_fetch` funciona sem chave de API. `web_search` depende do + provedor selecionado: - Provedores com API, como Brave, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Perplexity e Tavily, exigem sua configuração normal de chave de API. - - Ollama Web Search não exige chave, mas usa o host Ollama configurado e requer `ollama signin`. - - DuckDuckGo não exige chave, mas é uma integração não oficial baseada em HTML. - - SearXNG não exige chave/é self-hosted; configure `SEARXNG_BASE_URL` ou `plugins.entries.searxng.config.webSearch.baseUrl`. + - Ollama Web Search não usa chave, mas usa o host Ollama configurado e exige `ollama signin`. + - DuckDuckGo não usa chave, mas é uma integração não oficial baseada em HTML. + - SearXNG não usa chave/é self-hosted; configure `SEARXNG_BASE_URL` ou `plugins.entries.searxng.config.webSearch.baseUrl`. **Recomendado:** execute `openclaw configure --section web` e escolha um provedor. - Alternativas por variável de ambiente: + Alternativas por ambiente: - Brave: `BRAVE_API_KEY` - Exa: `EXA_API_KEY` @@ -1617,58 +1617,58 @@ quanto a uso/faturamento e aumente os limites conforme necessário. } ``` - A configuração específica do provedor para busca na web agora fica em `plugins.entries..config.webSearch.*`. - Caminhos legados de provedor em `tools.web.search.*` ainda são carregados temporariamente por compatibilidade, mas não devem ser usados em novas configurações. - A configuração de fallback do Firecrawl para busca de conteúdo web fica em `plugins.entries.firecrawl.config.webFetch.*`. + A configuração específica de provedor para pesquisa web agora fica em `plugins.entries..config.webSearch.*`. + Os caminhos legados de provedor `tools.web.search.*` ainda carregam temporariamente por compatibilidade, mas não devem ser usados em novas configurações. + A configuração de fallback de web-fetch do Firecrawl fica em `plugins.entries.firecrawl.config.webFetch.*`. Observações: - Se você usa allowlists, adicione `web_search`/`web_fetch`/`x_search` ou `group:web`. - - `web_fetch` vem habilitado por padrão (a menos que seja explicitamente desabilitado). - - Se `tools.web.fetch.provider` for omitido, o OpenClaw detecta automaticamente o primeiro provedor de fallback para fetch pronto com base nas credenciais disponíveis. Hoje o provedor empacotado é o Firecrawl. + - `web_fetch` vem ativado por padrão (a menos que seja explicitamente desativado). + - Se `tools.web.fetch.provider` for omitido, o OpenClaw detecta automaticamente o primeiro provedor de fallback de fetch pronto a partir das credenciais disponíveis. Hoje o provedor incluído é o Firecrawl. - Daemons leem variáveis de ambiente de `~/.openclaw/.env` (ou do ambiente do serviço). Documentação: [Ferramentas web](/pt-BR/tools/web). - + `config.apply` substitui a **configuração inteira**. Se você enviar um objeto parcial, todo o - resto será removido. + restante será removido. Recuperação: - - Restaure a partir de um backup (git ou uma cópia de `~/.openclaw/openclaw.json`). - - Se você não tiver backup, execute novamente `openclaw doctor` e reconfigure canais/modelos. + - Restaure de um backup (git ou uma cópia de `~/.openclaw/openclaw.json`). + - Se você não tiver backup, execute `openclaw doctor` novamente e reconfigure canais/modelos. - Se isso foi inesperado, abra um bug e inclua sua última configuração conhecida ou qualquer backup. - - Um agent de programação local muitas vezes consegue reconstruir uma configuração funcional a partir de logs ou histórico. + - Um agente de programação local muitas vezes consegue reconstruir uma configuração funcional a partir de logs ou histórico. Como evitar: - - Use `openclaw config set` para mudanças pequenas. + - Use `openclaw config set` para pequenas alterações. - Use `openclaw configure` para edições interativas. - - Use `config.schema.lookup` primeiro quando você não tiver certeza sobre um caminho exato ou o formato de um campo; ele retorna um nó raso do schema mais resumos imediatos dos filhos para aprofundamento. - - Use `config.patch` para edições parciais via RPC; deixe `config.apply` apenas para substituição completa da configuração. - - Se você estiver usando a ferramenta `gateway`, exclusiva para owners, em uma execução de agent, ela ainda rejeitará gravações em `tools.exec.ask` / `tools.exec.security` (incluindo aliases legados `tools.bash.*` que são normalizados para os mesmos caminhos protegidos de exec). + - Use `config.schema.lookup` primeiro quando você não tiver certeza sobre um caminho exato ou o formato de um campo; ele retorna um nó superficial de schema mais resumos imediatos dos filhos para aprofundamento. + - Use `config.patch` para edições RPC parciais; mantenha `config.apply` apenas para substituição completa da configuração. + - Se você estiver usando a ferramenta `gateway` exclusiva do proprietário em uma execução de agent, ela ainda rejeitará gravações em `tools.exec.ask` / `tools.exec.security` (incluindo aliases legados `tools.bash.*` que se normalizam para os mesmos caminhos exec protegidos). Documentação: [Configuração](/cli/config), [Configure](/cli/configure), [Doctor](/pt-BR/gateway/doctor). - O padrão mais comum é **um Gateway** (por exemplo, Raspberry Pi) mais **nodes** e **agents**: + O padrão comum é **um Gateway** (por exemplo, Raspberry Pi) mais **nodes** e **agents**: - - **Gateway (central):** controla canais (Signal/WhatsApp), roteamento e sessions. + - **Gateway (central):** é o dono dos canais (Signal/WhatsApp), roteamento e sessões. - **Nodes (dispositivos):** Macs/iOS/Android se conectam como periféricos e expõem ferramentas locais (`system.run`, `canvas`, `camera`). - - **Agents (workers):** cérebros/workspaces separados para funções específicas (por exemplo, "Hetzner ops", "Personal data"). - - **Sub-agents:** criam trabalho em segundo plano a partir de um agent principal quando você quer paralelismo. - - **TUI:** conecta-se ao Gateway e alterna agents/sessions. + - **Agents (workers):** cérebros/workspaces separados para funções especializadas (por exemplo, "operações Hetzner", "dados pessoais"). + - **Sub-agents:** iniciam trabalho em segundo plano a partir de um agent principal quando você quer paralelismo. + - **TUI:** conecta ao Gateway e alterna entre agents/sessions. Documentação: [Nodes](/pt-BR/nodes), [Acesso remoto](/pt-BR/gateway/remote), [Roteamento multi-agent](/pt-BR/concepts/multi-agent), [Sub-agents](/pt-BR/tools/subagents), [TUI](/web/tui). - + Sim. É uma opção de configuração: ```json5 @@ -1686,9 +1686,9 @@ quanto a uso/faturamento e aumente os limites conforme necessário. O modo headless usa o **mesmo mecanismo Chromium** e funciona para a maior parte da automação (formulários, cliques, scraping, logins). As principais diferenças: - - Sem janela visível do navegador (use capturas de tela se precisar de elementos visuais). - - Alguns sites são mais rígidos com automação em modo headless (CAPTCHAs, anti-bot). - Por exemplo, X/Twitter frequentemente bloqueia sessions headless. + - Nenhuma janela de navegador visível (use capturas de tela se precisar de recursos visuais). + - Alguns sites são mais rigorosos com automação em modo headless (CAPTCHAs, anti-bot). + Por exemplo, X/Twitter frequentemente bloqueia sessões headless. @@ -1701,26 +1701,26 @@ quanto a uso/faturamento e aumente os limites conforme necessário. ## Gateways remotos e nodes - + As mensagens do Telegram são tratadas pelo **gateway**. O gateway executa o agent e - só então chama nodes pelo **Gateway WebSocket** quando uma ferramenta de node é necessária: + só então chama os nodes pelo **Gateway WebSocket** quando uma ferramenta de node é necessária: Telegram → Gateway → Agent → `node.*` → Node → Gateway → Telegram - Nodes não veem tráfego de provedor de entrada; eles recebem apenas chamadas RPC de node. + Nodes não veem o tráfego de entrada do provedor; eles recebem apenas chamadas RPC de node. - - Resposta curta: **pareie seu computador como um node**. O Gateway roda em outro lugar, mas pode + + Resposta curta: **emparelhe seu computador como um node**. O Gateway é executado em outro lugar, mas pode chamar ferramentas `node.*` (tela, câmera, sistema) na sua máquina local pelo Gateway WebSocket. Configuração típica: 1. Execute o Gateway no host sempre ativo (VPS/servidor doméstico). - 2. Coloque o host do Gateway e seu computador na mesma tailnet. - 3. Garanta que o WS do Gateway esteja acessível (bind em tailnet ou túnel SSH). - 4. Abra o app do macOS localmente e conecte-se em modo **Remote over SSH** (ou tailnet direta) + 2. Coloque o host do Gateway + seu computador na mesma tailnet. + 3. Garanta que o WS do Gateway esteja acessível (bind da tailnet ou túnel SSH). + 4. Abra o app macOS localmente e conecte em modo **Remote over SSH** (ou tailnet direta) para que ele possa se registrar como um node. 5. Aprove o node no Gateway: @@ -1729,107 +1729,107 @@ quanto a uso/faturamento e aumente os limites conforme necessário. openclaw devices approve ``` - Nenhuma bridge TCP separada é necessária; nodes se conectam pelo Gateway WebSocket. + Nenhuma bridge TCP separada é necessária; os nodes se conectam pelo Gateway WebSocket. - Lembrete de segurança: parear um node macOS permite `system.run` nessa máquina. Só - pareie dispositivos em que você confia e revise [Segurança](/pt-BR/gateway/security). + Lembrete de segurança: emparelhar um node macOS permite `system.run` nessa máquina. Emparelhe + apenas dispositivos confiáveis e revise [Segurança](/pt-BR/gateway/security). - Documentação: [Nodes](/pt-BR/nodes), [Protocolo do Gateway](/pt-BR/gateway/protocol), [modo remoto no macOS](/pt-BR/platforms/mac/remote), [Segurança](/pt-BR/gateway/security). + Documentação: [Nodes](/pt-BR/nodes), [Protocolo do gateway](/pt-BR/gateway/protocol), [Modo remoto no macOS](/pt-BR/platforms/mac/remote), [Segurança](/pt-BR/gateway/security). Verifique o básico: - - Gateway em execução: `openclaw gateway status` + - O Gateway está em execução: `openclaw gateway status` - Integridade do Gateway: `openclaw status` - Integridade do canal: `openclaw channels status` Depois verifique autenticação e roteamento: - - Se você usa Tailscale Serve, confira se `gateway.auth.allowTailscale` está definido corretamente. - - Se você se conecta por túnel SSH, confirme que o túnel local está ativo e aponta para a porta correta. - - Confirme se suas allowlists (DM ou grupo) incluem sua conta. + - Se você usa Tailscale Serve, certifique-se de que `gateway.auth.allowTailscale` esteja definido corretamente. + - Se você se conecta por túnel SSH, confirme que o túnel local está ativo e aponta para a porta certa. + - Confirme que suas allowlists (DM ou grupo) incluem sua conta. - Documentação: [Tailscale](/pt-BR/gateway/tailscale), [Acesso remoto](/pt-BR/gateway/remote), [Canais](/pt-BR/channels). + Documentação: [Tailscale](/pt-BR/gateway/tailscale), [Acesso remoto](/pt-BR/gateway/remote), [Channels](/pt-BR/channels). - Sim. Não há uma bridge "bot-to-bot" integrada, mas você pode montar isso de algumas - formas confiáveis: + Sim. Não existe uma bridge "bot para bot" integrada, mas você pode conectá-las de algumas + maneiras confiáveis: - **Mais simples:** use um canal de chat normal ao qual ambos os bots tenham acesso (Telegram/Slack/WhatsApp). - Faça o Bot A enviar uma mensagem para o Bot B e depois deixe o Bot B responder normalmente. + **Mais simples:** use um canal de chat normal ao qual ambos os bots possam acessar (Telegram/Slack/WhatsApp). + Faça o Bot A enviar uma mensagem ao Bot B e depois deixe o Bot B responder normalmente. **Bridge por CLI (genérica):** execute um script que chame o outro Gateway com `openclaw agent --message ... --deliver`, apontando para um chat em que o outro bot - esteja escutando. Se um bot estiver em uma VPS remota, aponte sua CLI para esse Gateway remoto + escuta. Se um dos bots estiver em uma VPS remota, aponte sua CLI para esse Gateway remoto via SSH/Tailscale (consulte [Acesso remoto](/pt-BR/gateway/remote)). - Padrão de exemplo (execute a partir de uma máquina que consiga acessar o Gateway de destino): + Padrão de exemplo (execute em uma máquina que consiga alcançar o Gateway de destino): ```bash openclaw agent --message "Hello from local bot" --deliver --channel telegram --reply-to ``` Dica: adicione uma proteção para que os dois bots não entrem em loop infinito (somente menções, allowlists - de canal ou uma regra de “não responder a mensagens de bot”). + do canal ou uma regra de "não responder a mensagens de bot"). - Documentação: [Acesso remoto](/pt-BR/gateway/remote), [CLI do Agent](/cli/agent), [Envio pelo agent](/pt-BR/tools/agent-send). + Documentação: [Acesso remoto](/pt-BR/gateway/remote), [CLI do agent](/cli/agent), [Envio do agent](/pt-BR/tools/agent-send). - Não. Um Gateway pode hospedar vários agents, cada um com seu próprio workspace, modelos padrão - e roteamento. Essa é a configuração normal e é muito mais barata e mais simples do que executar + Não. Um Gateway pode hospedar vários agents, cada um com seu próprio workspace, padrões de modelo + e roteamento. Essa é a configuração normal e é muito mais barata e simples do que executar uma VPS por agent. - Use VPSs separadas apenas quando você precisar de isolamento rígido (limites de segurança) ou de configurações muito - diferentes que não queira compartilhar. Caso contrário, mantenha um Gateway e - use vários agents ou sub-agents. + Use VPSs separadas apenas quando precisar de isolamento rígido (limites de segurança) ou de + configurações muito diferentes que você não queira compartilhar. Caso contrário, mantenha um Gateway + e use vários agents ou sub-agents. - - Sim — nodes são a maneira principal de alcançar seu laptop a partir de um Gateway remoto, e eles - oferecem mais do que acesso a shell. O Gateway roda em macOS/Linux (Windows via WSL2) e é - leve (uma VPS pequena ou máquina do tipo Raspberry Pi é suficiente; 4 GB de RAM é mais que o bastante), então uma configuração + + Sim — os nodes são a forma de primeira classe de alcançar seu laptop a partir de um Gateway remoto, e eles + liberam mais do que acesso ao shell. O Gateway é executado em macOS/Linux (Windows via WSL2) e é + leve (uma VPS pequena ou máquina da classe Raspberry Pi já serve; 4 GB de RAM é mais do que suficiente), então uma configuração comum é um host sempre ativo mais seu laptop como node. - - **Sem SSH de entrada obrigatório.** Nodes se conectam para fora ao Gateway WebSocket e usam pareamento de dispositivo. - - **Controles de execução mais seguros.** `system.run` é controlado por allowlists/aprovações de node nesse laptop. - - **Mais ferramentas do dispositivo.** Nodes expõem `canvas`, `camera` e `screen`, além de `system.run`. - - **Automação de navegador local.** Mantenha o Gateway em uma VPS, mas execute o Chrome localmente por meio de um host de node no laptop, ou conecte-se ao Chrome local no host via Chrome MCP. + - **Não exige SSH de entrada.** Os nodes se conectam para fora ao Gateway WebSocket e usam emparelhamento de dispositivo. + - **Controles de execução mais seguros.** `system.run` é controlado por allowlists/aprovações do node nesse laptop. + - **Mais ferramentas de dispositivo.** Os nodes expõem `canvas`, `camera` e `screen`, além de `system.run`. + - **Automação local de navegador.** Mantenha o Gateway em uma VPS, mas execute o Chrome localmente por meio de um host de node no laptop, ou conecte-se ao Chrome local no host via Chrome MCP. - SSH é aceitável para acesso ocasional ao shell, mas nodes são mais simples para fluxos de trabalho contínuos de agents e + SSH é aceitável para acesso eventual ao shell, mas nodes são mais simples para fluxos de trabalho contínuos de agent e automação de dispositivos. - Documentação: [Nodes](/pt-BR/nodes), [CLI de Nodes](/cli/nodes), [Browser](/pt-BR/tools/browser). + Documentação: [Nodes](/pt-BR/nodes), [Nodes CLI](/cli/nodes), [Browser](/pt-BR/tools/browser). - - Não. Apenas **um gateway** deve ser executado por host, a menos que você execute intencionalmente perfis isolados (consulte [Múltiplos gateways](/pt-BR/gateway/multiple-gateways)). Nodes são periféricos que se conectam + + Não. Apenas **um gateway** deve ser executado por host, a menos que você intencionalmente execute perfis isolados (consulte [Múltiplos gateways](/pt-BR/gateway/multiple-gateways)). Nodes são periféricos que se conectam ao gateway (nodes iOS/Android ou o "modo node" do macOS no app da barra de menu). Para hosts de node headless - e controle por CLI, consulte [CLI de host de node](/cli/node). + e controle por CLI, consulte [CLI do host de node](/cli/node). - É necessário um reinício completo para mudanças em `gateway`, `discovery` e `canvasHost`. + É necessário um reinício completo para alterações em `gateway`, `discovery` e `canvasHost`. - + Sim. - - `config.schema.lookup`: inspeciona uma subárvore de configuração com seu nó raso do schema, dica de UI correspondente e resumos imediatos dos filhos antes de gravar + - `config.schema.lookup`: inspeciona uma subárvore da configuração com seu nó superficial de schema, dica de UI correspondente e resumos imediatos dos filhos antes de gravar - `config.get`: busca o snapshot atual + hash - `config.patch`: atualização parcial segura (preferida para a maioria das edições por RPC); faz hot-reload quando possível e reinicia quando necessário - `config.apply`: valida + substitui a configuração completa; faz hot-reload quando possível e reinicia quando necessário - - A ferramenta de runtime `gateway`, exclusiva para owners, ainda se recusa a regravar `tools.exec.ask` / `tools.exec.security`; aliases legados `tools.bash.*` são normalizados para os mesmos caminhos protegidos de exec + - A ferramenta de runtime `gateway`, exclusiva do proprietário, ainda se recusa a regravar `tools.exec.ask` / `tools.exec.security`; aliases legados `tools.bash.*` se normalizam para os mesmos caminhos exec protegidos - + ```json5 { agents: { defaults: { workspace: "~/.openclaw/workspace" } }, @@ -1842,7 +1842,7 @@ quanto a uso/faturamento e aumente os limites conforme necessário. - Passos mínimos: + Etapas mínimas: 1. **Instale + faça login na VPS** @@ -1854,7 +1854,7 @@ quanto a uso/faturamento e aumente os limites conforme necessário. 2. **Instale + faça login no seu Mac** - Use o app do Tailscale e entre na mesma tailnet. 3. **Ative o MagicDNS (recomendado)** - - No console de administração do Tailscale, ative o MagicDNS para que a VPS tenha um nome estável. + - No console administrativo do Tailscale, ative o MagicDNS para que a VPS tenha um nome estável. 4. **Use o hostname da tailnet** - SSH: `ssh user@your-vps.tailnet-xxxx.ts.net` - Gateway WS: `ws://your-vps.tailnet-xxxx.ts.net:18789` @@ -1875,8 +1875,8 @@ quanto a uso/faturamento e aumente os limites conforme necessário. Configuração recomendada: 1. **Certifique-se de que a VPS + o Mac estejam na mesma tailnet**. - 2. **Use o app do macOS em modo Remote** (o alvo SSH pode ser o hostname da tailnet). - O app vai tunelar a porta do Gateway e se conectar como node. + 2. **Use o app macOS no modo Remote** (o destino SSH pode ser o hostname da tailnet). + O app fará túnel da porta do Gateway e se conectará como um node. 3. **Aprove o node** no gateway: ```bash @@ -1884,18 +1884,18 @@ quanto a uso/faturamento e aumente os limites conforme necessário. openclaw devices approve ``` - Documentação: [Protocolo do Gateway](/pt-BR/gateway/protocol), [Discovery](/pt-BR/gateway/discovery), [modo remoto no macOS](/pt-BR/platforms/mac/remote). + Documentação: [Protocolo do gateway](/pt-BR/gateway/protocol), [Discovery](/pt-BR/gateway/discovery), [Modo remoto no macOS](/pt-BR/platforms/mac/remote). - Se você só precisa de **ferramentas locais** (tela/câmera/exec) no segundo laptop, adicione-o como - **node**. Isso mantém um único Gateway e evita configuração duplicada. Ferramentas locais de node - atualmente são exclusivas do macOS, mas planejamos estendê-las a outros sistemas operacionais. + Se você só precisa de **ferramentas locais** (tela/câmera/exec) no segundo laptop, adicione-o como um + **node**. Isso mantém um único Gateway e evita configuração duplicada. As ferramentas locais de node são + atualmente exclusivas do macOS, mas planejamos estendê-las para outros SOs. Instale um segundo Gateway apenas quando precisar de **isolamento rígido** ou de dois bots totalmente separados. - Documentação: [Nodes](/pt-BR/nodes), [CLI de Nodes](/cli/nodes), [Múltiplos gateways](/pt-BR/gateway/multiple-gateways). + Documentação: [Nodes](/pt-BR/nodes), [Nodes CLI](/cli/nodes), [Múltiplos gateways](/pt-BR/gateway/multiple-gateways). @@ -1904,14 +1904,14 @@ quanto a uso/faturamento e aumente os limites conforme necessário. - O OpenClaw lê variáveis de ambiente do processo pai (shell, launchd/systemd, CI etc.) e também carrega adicionalmente: + O OpenClaw lê vars de ambiente do processo pai (shell, launchd/systemd, CI etc.) e adicionalmente carrega: - `.env` do diretório de trabalho atual - um `.env` global de fallback em `~/.openclaw/.env` (também conhecido como `$OPENCLAW_STATE_DIR/.env`) - Nenhum dos arquivos `.env` substitui variáveis de ambiente existentes. + Nenhum dos arquivos `.env` substitui vars de ambiente existentes. - Você também pode definir variáveis de ambiente inline na configuração (aplicadas apenas se estiverem ausentes do ambiente do processo): + Você também pode definir vars de ambiente inline na configuração (aplicadas apenas se estiverem ausentes do env do processo): ```json5 { @@ -1922,15 +1922,15 @@ quanto a uso/faturamento e aumente os limites conforme necessário. } ``` - Consulte [/environment](/pt-BR/help/environment) para a precedência completa e as origens. + Consulte [/environment](/pt-BR/help/environment) para a precedência completa e as fontes. - + Duas correções comuns: - 1. Coloque as chaves ausentes em `~/.openclaw/.env` para que sejam carregadas mesmo quando o serviço não herdar o ambiente do seu shell. - 2. Ative a importação do shell (conveniência opcional): + 1. Coloque as chaves ausentes em `~/.openclaw/.env` para que sejam captadas mesmo quando o serviço não herda o env do seu shell. + 2. Ative a importação do shell (conveniência opt-in): ```json5 { @@ -1943,18 +1943,18 @@ quanto a uso/faturamento e aumente os limites conforme necessário. } ``` - Isso executa seu shell de login e importa apenas as chaves esperadas que estiverem ausentes (nunca substitui). Equivalentes em variável de ambiente: + Isso executa seu shell de login e importa apenas chaves esperadas ausentes (nunca substitui). Equivalentes em var de ambiente: `OPENCLAW_LOAD_SHELL_ENV=1`, `OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000`. - - `openclaw models status` informa se a **importação do ambiente do shell** está habilitada. "Shell env: off" - **não** significa que suas variáveis de ambiente estão ausentes — significa apenas que o OpenClaw não carregará + + `openclaw models status` informa se a **importação do env do shell** está ativada. "Shell env: off" + **não** significa que suas vars de ambiente estão ausentes — apenas significa que o OpenClaw não carregará automaticamente seu shell de login. - Se o Gateway estiver em execução como serviço (launchd/systemd), ele não herdará o - ambiente do seu shell. Corrija isso fazendo um destes: + Se o Gateway for executado como serviço (launchd/systemd), ele não herdará o + ambiente do seu shell. Corrija de uma destas maneiras: 1. Coloque o token em `~/.openclaw/.env`: @@ -1963,7 +1963,7 @@ quanto a uso/faturamento e aumente os limites conforme necessário. ``` 2. Ou ative a importação do shell (`env.shellEnv.enabled: true`). - 3. Ou adicione-o ao bloco `env` da sua configuração (aplica-se apenas se estiver ausente). + 3. Ou adicione-o ao bloco `env` da sua configuração (aplicado apenas se estiver ausente). Depois reinicie o gateway e verifique novamente: @@ -1977,18 +1977,18 @@ quanto a uso/faturamento e aumente os limites conforme necessário. -## Sessions e múltiplos chats +## Sessões e múltiplos chats - Envie `/new` ou `/reset` como uma mensagem isolada. Consulte [Gerenciamento de session](/pt-BR/concepts/session). + Envie `/new` ou `/reset` como uma mensagem independente. Consulte [Gerenciamento de sessão](/pt-BR/concepts/session). - - Sessions podem expirar após `session.idleMinutes`, mas isso vem **desativado por padrão** (valor padrão **0**). + + As sessões podem expirar após `session.idleMinutes`, mas isso vem **desativado por padrão** (padrão **0**). Defina um valor positivo para ativar a expiração por inatividade. Quando ativada, a **próxima** - mensagem após o período de inatividade inicia um novo ID de session para essa chave de chat. - Isso não exclui as transcrições — apenas inicia uma nova session. + mensagem após o período de inatividade inicia um novo ID de sessão para aquela chave de chat. + Isso não exclui transcrições — apenas inicia uma nova sessão. ```json5 { @@ -2000,34 +2000,34 @@ quanto a uso/faturamento e aumente os limites conforme necessário. - - Sim, via **roteamento multi-agent** e **sub-agents**. Você pode criar um agent coordenador - e vários agents workers com seus próprios workspaces e modelos. + + Sim, via **roteamento multi-agent** e **sub-agents**. Você pode criar um agent + coordenador e vários agents workers com seus próprios workspaces e modelos. - Dito isso, isso é melhor visto como um **experimento divertido**. Consome muitos tokens e muitas vezes - é menos eficiente do que usar um bot com sessions separadas. O modelo típico que - imaginamos é um bot com o qual você conversa, com diferentes sessions para trabalho em paralelo. Esse - bot também pode criar sub-agents quando necessário. + Dito isso, é melhor ver isso como um **experimento divertido**. Consome muitos tokens e frequentemente + é menos eficiente do que usar um bot com sessões separadas. O modelo típico que + imaginamos é um bot com o qual você conversa, com diferentes sessões para trabalho em paralelo. Esse + bot também pode iniciar sub-agents quando necessário. Documentação: [Roteamento multi-agent](/pt-BR/concepts/multi-agent), [Sub-agents](/pt-BR/tools/subagents), [CLI de Agents](/cli/agents). - O contexto da session é limitado pela janela do modelo. Chats longos, saídas grandes de ferramentas ou muitos + O contexto da sessão é limitado pela janela do modelo. Chats longos, saídas grandes de ferramentas ou muitos arquivos podem disparar Compaction ou truncamento. O que ajuda: - Peça ao bot para resumir o estado atual e gravá-lo em um arquivo. - - Use `/compact` antes de tarefas longas e `/new` ao trocar de assunto. - - Mantenha o contexto importante no workspace e peça ao bot para lê-lo novamente. - - Use sub-agents para trabalhos longos ou paralelos, assim o chat principal permanece menor. - - Escolha um modelo com uma janela de contexto maior se isso acontecer com frequência. + - Use `/compact` antes de tarefas longas e `/new` ao mudar de assunto. + - Mantenha contexto importante no workspace e peça ao bot para lê-lo de volta. + - Use sub-agents para trabalho longo ou paralelo, para que o chat principal permaneça menor. + - Escolha um modelo com janela de contexto maior se isso acontecer com frequência. - + Use o comando de redefinição: ```bash @@ -2040,7 +2040,7 @@ quanto a uso/faturamento e aumente os limites conforme necessário. openclaw reset --scope full --yes --non-interactive ``` - Depois execute novamente a configuração: + Depois execute a configuração novamente: ```bash openclaw onboard --install-daemon @@ -2050,14 +2050,14 @@ quanto a uso/faturamento e aumente os limites conforme necessário. - O onboarding também oferece **Reset** se detectar uma configuração existente. Consulte [Onboarding (CLI)](/pt-BR/start/wizard). - Se você usou perfis (`--profile` / `OPENCLAW_PROFILE`), redefina cada diretório de estado (os padrões são `~/.openclaw-`). - - Redefinição de desenvolvimento: `openclaw gateway --dev --reset` (somente desenvolvimento; limpa configuração de dev + credenciais + sessions + workspace). + - Redefinição de dev: `openclaw gateway --dev --reset` (somente dev; apaga configuração + credenciais + sessões + workspace de dev). - + Use uma destas opções: - - **Compactar** (mantém a conversa, mas resume turnos anteriores): + - **Compactar** (mantém a conversa, mas resume turnos antigos): ``` /compact @@ -2065,7 +2065,7 @@ quanto a uso/faturamento e aumente os limites conforme necessário. ou `/compact ` para orientar o resumo. - - **Redefinir** (novo ID de session para a mesma chave de chat): + - **Redefinir** (novo ID de sessão para a mesma chave de chat): ``` /new @@ -2074,24 +2074,24 @@ quanto a uso/faturamento e aumente os limites conforme necessário. Se isso continuar acontecendo: - - Ative ou ajuste a **poda de session** (`agents.defaults.contextPruning`) para reduzir saídas antigas de ferramentas. - - Use um modelo com uma janela de contexto maior. + - Ative ou ajuste a **poda de sessão** (`agents.defaults.contextPruning`) para reduzir saídas antigas de ferramentas. + - Use um modelo com janela de contexto maior. - Documentação: [Compaction](/pt-BR/concepts/compaction), [Poda de session](/pt-BR/concepts/session-pruning), [Gerenciamento de session](/pt-BR/concepts/session). + Documentação: [Compaction](/pt-BR/concepts/compaction), [Poda de sessão](/pt-BR/concepts/session-pruning), [Gerenciamento de sessão](/pt-BR/concepts/session). - Esse é um erro de validação do provedor: o modelo emitiu um bloco `tool_use` sem o - `input` obrigatório. Isso normalmente significa que o histórico da session está obsoleto ou corrompido (muitas vezes após threads longas - ou uma mudança em ferramenta/schema). + Isso é um erro de validação do provedor: o modelo emitiu um bloco `tool_use` sem o + `input` obrigatório. Normalmente significa que o histórico da sessão está obsoleto ou corrompido (muitas vezes após threads longas + ou uma alteração de ferramenta/schema). - Correção: inicie uma nova session com `/new` (mensagem isolada). + Correção: inicie uma sessão nova com `/new` (mensagem independente). - - Heartbeats são executados a cada **30 min** por padrão (**1 h** ao usar autenticação por OAuth). Ajuste ou desative: + + Heartbeats são executados a cada **30m** por padrão (**1h** ao usar autenticação OAuth). Ajuste ou desative: ```json5 { @@ -2114,10 +2114,10 @@ quanto a uso/faturamento e aumente os limites conforme necessário. - Não. O OpenClaw roda na **sua própria conta**, então, se você estiver no grupo, o OpenClaw poderá vê-lo. - Por padrão, respostas em grupos são bloqueadas até que você permita remetentes (`groupPolicy: "allowlist"`). + Não. O OpenClaw é executado na **sua própria conta**, então, se você estiver no grupo, o OpenClaw poderá vê-lo. + Por padrão, respostas em grupo são bloqueadas até você permitir remetentes (`groupPolicy: "allowlist"`). - Se você quiser que apenas **você** consiga acionar respostas no grupo: + Se você quiser que apenas **você** possa acionar respostas no grupo: ```json5 { @@ -2142,7 +2142,7 @@ quanto a uso/faturamento e aumente os limites conforme necessário. Procure `chatId` (ou `from`) terminando em `@g.us`, como: `1234567890-1234567890@g.us`. - Opção 2 (se já estiver configurado/na allowlist): liste grupos a partir da configuração: + Opção 2 (se já estiver configurado/na allowlist): liste grupos da configuração: ```bash openclaw directory groups list --channel whatsapp @@ -2155,45 +2155,45 @@ quanto a uso/faturamento e aumente os limites conforme necessário. Duas causas comuns: - - O controle por menção está ativado (padrão). Você precisa @mencionar o bot (ou corresponder a `mentionPatterns`). + - O bloqueio por menção está ativado (padrão). Você precisa @mencionar o bot (ou corresponder a `mentionPatterns`). - Você configurou `channels.whatsapp.groups` sem `"*"` e o grupo não está na allowlist. - Consulte [Grupos](/pt-BR/channels/groups) e [Mensagens em grupo](/pt-BR/channels/group-messages). + Consulte [Groups](/pt-BR/channels/groups) e [Mensagens em grupo](/pt-BR/channels/group-messages). - Chats diretos são recolhidos para a session principal por padrão. Grupos/canais têm suas próprias chaves de session, e tópicos do Telegram / threads do Discord são sessions separadas. Consulte [Grupos](/pt-BR/channels/groups) e [Mensagens em grupo](/pt-BR/channels/group-messages). + Chats diretos entram em colapso para a sessão principal por padrão. Grupos/canais têm suas próprias chaves de sessão, e tópicos do Telegram / threads do Discord são sessões separadas. Consulte [Groups](/pt-BR/channels/groups) e [Mensagens em grupo](/pt-BR/channels/group-messages). Não há limites rígidos. Dezenas (até centenas) funcionam bem, mas fique atento a: - - **Crescimento de disco:** sessions + transcrições ficam em `~/.openclaw/agents//sessions/`. + - **Crescimento em disco:** sessões + transcrições ficam em `~/.openclaw/agents//sessions/`. - **Custo de tokens:** mais agents significam mais uso simultâneo de modelos. - - **Sobrecarga operacional:** perfis de autenticação, workspaces e roteamento de canal por agent. + - **Sobrecarga operacional:** perfis de autenticação, workspaces e roteamento de canais por agent. Dicas: - Mantenha um workspace **ativo** por agent (`agents.defaults.workspace`). - - Pode sessions antigas (apague entradas JSONL ou do armazenamento) se o disco crescer. - - Use `openclaw doctor` para identificar workspaces soltos e incompatibilidades de perfil. + - Faça poda de sessões antigas (exclua JSONL ou entradas de armazenamento) se o disco crescer. + - Use `openclaw doctor` para identificar workspaces perdidos e incompatibilidades de perfis. - + Sim. Use **Roteamento multi-agent** para executar vários agents isolados e rotear mensagens de entrada por canal/conta/peer. Slack é compatível como canal e pode ser vinculado a agents específicos. - O acesso ao navegador é poderoso, mas não significa “fazer qualquer coisa que um humano faz” — anti-bot, CAPTCHAs e MFA ainda podem - bloquear automação. Para o controle mais confiável do navegador, use Chrome MCP local no host - ou CDP na máquina que realmente executa o navegador. + O acesso ao navegador é poderoso, mas não significa "fazer qualquer coisa que um humano pode" — anti-bot, CAPTCHAs e MFA + ainda podem bloquear a automação. Para o controle de navegador mais confiável, use Chrome MCP local no host + ou use CDP na máquina que realmente executa o navegador. - Configuração recomendada: + Configuração de melhores práticas: - - Host do Gateway sempre ativo (VPS/Mac mini). + - Host de Gateway sempre ativo (VPS/Mac mini). - Um agent por função (bindings). - - Canal/canais do Slack vinculados a esses agents. + - Canal(is) do Slack vinculados a esses agents. - Navegador local via Chrome MCP ou um node quando necessário. Documentação: [Roteamento multi-agent](/pt-BR/concepts/multi-agent), [Slack](/pt-BR/channels/slack), @@ -2202,56 +2202,56 @@ quanto a uso/faturamento e aumente os limites conforme necessário. -## Modelos: padrões, seleção, aliases, troca +## Models: padrões, seleção, aliases, troca - O modelo padrão do OpenClaw é aquele que você definir em: + O modelo padrão do OpenClaw é o que você definir como: ``` agents.defaults.model.primary ``` - Os modelos são referenciados como `provider/model` (exemplo: `openai/gpt-5.4`). Se você omitir o provedor, o OpenClaw primeiro tenta um alias, depois uma correspondência única de provedor configurado para aquele ID de modelo exato e só então recorre ao provedor padrão configurado como um caminho de compatibilidade legado e obsoleto. Se esse provedor não expuser mais o modelo padrão configurado, o OpenClaw recorrerá ao primeiro provedor/modelo configurado, em vez de exibir um padrão obsoleto de provedor removido. Ainda assim, você deve definir **explicitamente** `provider/model`. + Os modelos são referenciados como `provider/model` (exemplo: `openai/gpt-5.4`). Se você omitir o provedor, o OpenClaw primeiro tenta um alias, depois uma correspondência exclusiva de provedor configurado para esse ID exato de modelo e só então recorre ao provedor padrão configurado como um caminho legado e obsoleto de compatibilidade. Se esse provedor não expuser mais o modelo padrão configurado, o OpenClaw recorre ao primeiro provedor/modelo configurado em vez de exibir um padrão obsoleto de provedor removido. Ainda assim, você deve definir **explicitamente** `provider/model`. - **Padrão recomendado:** use o modelo mais forte e de geração mais recente disponível na sua pilha de provedores. - **Para agents com ferramentas habilitadas ou entrada não confiável:** priorize força do modelo acima do custo. - **Para chat rotineiro/de baixo risco:** use modelos de fallback mais baratos e faça roteamento por função do agent. + **Padrão recomendado:** use o modelo mais forte e de última geração disponível na sua pilha de provedores. + **Para agents com ferramentas habilitadas ou entrada não confiável:** priorize força do modelo em vez de custo. + **Para chats rotineiros/de baixo risco:** use modelos de fallback mais baratos e faça roteamento por função do agent. O MiniMax tem sua própria documentação: [MiniMax](/pt-BR/providers/minimax) e [Modelos locais](/pt-BR/gateway/local-models). - Regra prática: use o **melhor modelo que você puder pagar** para trabalhos de alto risco e um modelo - mais barato para chat rotineiro ou resumos. Você pode rotear modelos por agent e usar sub-agents para - paralelizar tarefas longas (cada sub-agent consome tokens). Consulte [Modelos](/pt-BR/concepts/models) e + Regra prática: use o **melhor modelo que puder pagar** para trabalho de alto risco e um modelo mais barato + para chat rotineiro ou resumos. Você pode rotear modelos por agent e usar sub-agents para + paralelizar tarefas longas (cada sub-agent consome tokens). Consulte [Models](/pt-BR/concepts/models) e [Sub-agents](/pt-BR/tools/subagents). Aviso importante: modelos mais fracos ou excessivamente quantizados são mais vulneráveis a prompt injection e comportamento inseguro. Consulte [Segurança](/pt-BR/gateway/security). - Mais contexto: [Modelos](/pt-BR/concepts/models). + Mais contexto: [Models](/pt-BR/concepts/models). - Use **comandos de modelo** ou edite apenas os campos de **modelo**. Evite substituições completas da configuração. + Use **comandos de modelo** ou edite apenas os campos de **modelo**. Evite substituir a configuração inteira. Opções seguras: - - `/model` no chat (rápido, por session) + - `/model` no chat (rápido, por sessão) - `openclaw models set ...` (atualiza apenas a configuração do modelo) - `openclaw configure --section model` (interativo) - edite `agents.defaults.model` em `~/.openclaw/openclaw.json` Evite `config.apply` com um objeto parcial, a menos que você pretenda substituir a configuração inteira. - Para edições via RPC, inspecione primeiro com `config.schema.lookup` e prefira `config.patch`. O payload de lookup fornece o caminho normalizado, documentação/restrições rasas do schema e resumos imediatos dos filhos. + Para edições por RPC, inspecione primeiro com `config.schema.lookup` e prefira `config.patch`. O payload do lookup fornece o caminho normalizado, documentação/restrições superficiais do schema e resumos imediatos dos filhos. para atualizações parciais. - Se você sobrescreveu a configuração, restaure a partir de um backup ou execute novamente `openclaw doctor` para reparar. + Se você sobrescreveu a configuração, restaure de um backup ou execute `openclaw doctor` novamente para reparar. - Documentação: [Modelos](/pt-BR/concepts/models), [Configure](/cli/configure), [Configuração](/cli/config), [Doctor](/pt-BR/gateway/doctor). + Documentação: [Models](/pt-BR/concepts/models), [Configure](/cli/configure), [Configuração](/cli/config), [Doctor](/pt-BR/gateway/doctor). @@ -2261,7 +2261,7 @@ quanto a uso/faturamento e aumente os limites conforme necessário. Configuração mais rápida: 1. Instale o Ollama em `https://ollama.com/download` - 2. Baixe um modelo local, como `ollama pull gemma4` + 2. Faça pull de um modelo local, como `ollama pull gemma4` 3. Se você também quiser modelos em nuvem, execute `ollama signin` 4. Execute `openclaw onboard` e escolha `Ollama` 5. Escolha `Local` ou `Cloud + Local` @@ -2269,27 +2269,27 @@ quanto a uso/faturamento e aumente os limites conforme necessário. Observações: - `Cloud + Local` oferece modelos em nuvem mais seus modelos locais do Ollama - - modelos em nuvem como `kimi-k2.5:cloud` não precisam de download local + - modelos em nuvem como `kimi-k2.5:cloud` não precisam de pull local - para troca manual, use `openclaw models list` e `openclaw models set ollama/` - Observação de segurança: modelos menores ou muito quantizados são mais vulneráveis a prompt + Observação de segurança: modelos menores ou fortemente quantizados são mais vulneráveis a prompt injection. Recomendamos fortemente **modelos grandes** para qualquer bot que possa usar ferramentas. - Se você ainda quiser modelos pequenos, ative sandboxing e allowlists estritas de ferramentas. + Se você ainda quiser modelos pequenos, ative sandboxing e allowlists rígidas de ferramentas. Documentação: [Ollama](/pt-BR/providers/ollama), [Modelos locais](/pt-BR/gateway/local-models), - [Provedores de modelos](/pt-BR/concepts/model-providers), [Segurança](/pt-BR/gateway/security), + [Provedores de modelo](/pt-BR/concepts/model-providers), [Segurança](/pt-BR/gateway/security), [Sandboxing](/pt-BR/gateway/sandboxing). - - - Essas implantações podem variar e mudar ao longo do tempo; não há uma recomendação fixa de provedor. - - Verifique a configuração de runtime atual em cada gateway com `openclaw models status`. - - Para agents sensíveis à segurança/com ferramentas habilitadas, use o modelo mais forte e de geração mais recente disponível. + + - Esses deployments podem ser diferentes e mudar com o tempo; não há uma recomendação fixa de provedor. + - Verifique a configuração atual de tempo de execução em cada gateway com `openclaw models status`. + - Para agents sensíveis à segurança/com ferramentas habilitadas, use o modelo mais forte e de última geração disponível. - Use o comando `/model` como mensagem isolada: + Use o comando `/model` como uma mensagem independente: ``` /model sonnet @@ -2301,7 +2301,7 @@ quanto a uso/faturamento e aumente os limites conforme necessário. /model gemini-flash-lite ``` - Estes são os aliases integrados. Aliases personalizados podem ser adicionados via `agents.defaults.models`. + Esses são os aliases incluídos. Aliases personalizados podem ser adicionados via `agents.defaults.models`. Você pode listar os modelos disponíveis com `/model`, `/model list` ou `/model status`. @@ -2311,7 +2311,7 @@ quanto a uso/faturamento e aumente os limites conforme necessário. /model 3 ``` - Você também pode forçar um perfil de autenticação específico para o provedor (por session): + Você também pode forçar um perfil de autenticação específico para o provedor (por sessão): ``` /model opus@anthropic:default @@ -2319,38 +2319,38 @@ quanto a uso/faturamento e aumente os limites conforme necessário. ``` Dica: `/model status` mostra qual agent está ativo, qual arquivo `auth-profiles.json` está sendo usado e qual perfil de autenticação será tentado em seguida. - Ele também mostra o endpoint configurado do provedor (`baseUrl`) e o modo de API (`api`) quando disponíveis. + Ele também mostra o endpoint do provedor configurado (`baseUrl`) e o modo de API (`api`) quando disponíveis. - **Como removo a fixação de um perfil definido com @profile?** + **Como removo a fixação de um perfil que defini com @profile?** - Execute novamente `/model` **sem** o sufixo `@profile`: + Execute `/model` novamente **sem** o sufixo `@profile`: ``` /model anthropic/claude-opus-4-6 ``` - Se quiser voltar ao padrão, escolha-o em `/model` (ou envie `/model `). + Se você quiser voltar ao padrão, escolha-o em `/model` (ou envie `/model `). Use `/model status` para confirmar qual perfil de autenticação está ativo. - Sim. Defina um como padrão e troque conforme necessário: + Sim. Defina um como padrão e troque quando necessário: - - **Troca rápida (por session):** `/model gpt-5.4` para tarefas diárias, `/model openai-codex/gpt-5.4` para programação com OAuth do Codex. - - **Padrão + troca:** defina `agents.defaults.model.primary` como `openai/gpt-5.4` e depois troque para `openai-codex/gpt-5.4` ao programar (ou o inverso). - - **Sub-agents:** encaminhe tarefas de programação para sub-agents com um modelo padrão diferente. + - **Troca rápida (por sessão):** `/model gpt-5.4` para tarefas diárias, `/model openai-codex/gpt-5.4` para programação com OAuth do Codex. + - **Padrão + troca:** defina `agents.defaults.model.primary` como `openai/gpt-5.4` e depois troque para `openai-codex/gpt-5.4` ao programar (ou o contrário). + - **Sub-agents:** roteie tarefas de programação para sub-agents com um modelo padrão diferente. - Consulte [Modelos](/pt-BR/concepts/models) e [Comandos slash](/pt-BR/tools/slash-commands). + Consulte [Models](/pt-BR/concepts/models) e [Comandos slash](/pt-BR/tools/slash-commands). - Use um toggle por session ou um padrão de configuração: + Use um toggle por sessão ou um padrão de configuração: - - **Por session:** envie `/fast on` enquanto a session estiver usando `openai/gpt-5.4` ou `openai-codex/gpt-5.4`. + - **Por sessão:** envie `/fast on` enquanto a sessão estiver usando `openai/gpt-5.4` ou `openai-codex/gpt-5.4`. - **Padrão por modelo:** defina `agents.defaults.models["openai/gpt-5.4"].params.fastMode` como `true`. - - **Também para OAuth do Codex:** se você também usar `openai-codex/gpt-5.4`, defina a mesma flag nele. + - **OAuth do Codex também:** se você também usar `openai-codex/gpt-5.4`, defina o mesmo sinalizador ali. Exemplo: @@ -2375,15 +2375,15 @@ quanto a uso/faturamento e aumente os limites conforme necessário. } ``` - Para a OpenAI, o modo rápido mapeia para `service_tier = "priority"` em requisições nativas de Responses compatíveis. As substituições por session com `/fast` têm precedência sobre os padrões de configuração. + Para OpenAI, o modo rápido mapeia para `service_tier = "priority"` em solicitações nativas de Responses compatíveis. As substituições de sessão `/fast` prevalecem sobre os padrões de configuração. - Consulte [Pensamento e modo rápido](/pt-BR/tools/thinking) e [Modo rápido da OpenAI](/pt-BR/providers/openai#openai-fast-mode). + Consulte [Thinking e modo rápido](/pt-BR/tools/thinking) e [Modo rápido da OpenAI](/pt-BR/providers/openai#openai-fast-mode). Se `agents.defaults.models` estiver definido, ele se torna a **allowlist** para `/model` e quaisquer - substituições de session. Escolher um modelo que não está nessa lista retorna: + substituições de sessão. Escolher um modelo que não esteja nessa lista retorna: ``` Model "provider/model" is not allowed. Use /model to list available models. @@ -2395,19 +2395,19 @@ quanto a uso/faturamento e aumente os limites conforme necessário. - Isso significa que o **provedor não está configurado** (nenhuma configuração de provedor MiniMax ou perfil - de autenticação foi encontrada), então o modelo não pode ser resolvido. + Isso significa que o **provedor não está configurado** (nenhuma configuração de provedor MiniMax ou perfil de + autenticação foi encontrado), então o modelo não pode ser resolvido. Checklist de correção: - 1. Atualize para uma versão atual do OpenClaw (ou execute a partir do código-fonte `main`) e depois reinicie o gateway. - 2. Certifique-se de que o MiniMax está configurado (assistente ou JSON) ou de que a autenticação do MiniMax - existe no ambiente/perfis de autenticação para que o provedor correspondente possa ser injetado + 1. Atualize para uma versão atual do OpenClaw (ou execute a partir do código-fonte em `main`) e depois reinicie o gateway. + 2. Certifique-se de que o MiniMax esteja configurado (assistente ou JSON) ou de que a autenticação MiniMax + exista no env/perfis de autenticação para que o provedor correspondente possa ser injetado (`MINIMAX_API_KEY` para `minimax`, `MINIMAX_OAUTH_TOKEN` ou OAuth MiniMax armazenado para `minimax-portal`). - 3. Use o ID de modelo exato (sensível a maiúsculas e minúsculas) para seu caminho de autenticação: - `minimax/MiniMax-M2.7` ou `minimax/MiniMax-M2.7-highspeed` para configuração com chave de API, - ou `minimax-portal/MiniMax-M2.7` / + 3. Use o ID exato do modelo (sensível a maiúsculas/minúsculas) para o seu caminho de autenticação: + `minimax/MiniMax-M2.7` ou `minimax/MiniMax-M2.7-highspeed` para configuração + com chave de API, ou `minimax-portal/MiniMax-M2.7` / `minimax-portal/MiniMax-M2.7-highspeed` para configuração com OAuth. 4. Execute: @@ -2415,17 +2415,17 @@ quanto a uso/faturamento e aumente os limites conforme necessário. openclaw models list ``` - e escolha da lista (ou `/model list` no chat). + e escolha na lista (ou `/model list` no chat). - Consulte [MiniMax](/pt-BR/providers/minimax) e [Modelos](/pt-BR/concepts/models). + Consulte [MiniMax](/pt-BR/providers/minimax) e [Models](/pt-BR/concepts/models). - - Sim. Use **MiniMax como padrão** e troque de modelo **por session** quando necessário. - Fallbacks são para **erros**, não para “tarefas difíceis”, então use `/model` ou um agent separado. + + Sim. Use **MiniMax como padrão** e troque de modelo **por sessão** quando necessário. + Fallbacks servem para **erros**, não para "tarefas difíceis", então use `/model` ou um agent separado. - **Opção A: trocar por session** + **Opção A: trocar por sessão** ```json5 { @@ -2452,14 +2452,14 @@ quanto a uso/faturamento e aumente os limites conforme necessário. - Agent A padrão: MiniMax - Agent B padrão: OpenAI - - Faça o roteamento por agent ou use `/agent` para trocar + - Faça roteamento por agent ou use `/agent` para trocar - Documentação: [Modelos](/pt-BR/concepts/models), [Roteamento multi-agent](/pt-BR/concepts/multi-agent), [MiniMax](/pt-BR/providers/minimax), [OpenAI](/pt-BR/providers/openai). + Documentação: [Models](/pt-BR/concepts/models), [Roteamento multi-agent](/pt-BR/concepts/multi-agent), [MiniMax](/pt-BR/providers/minimax), [OpenAI](/pt-BR/providers/openai). - - Sim. O OpenClaw vem com alguns atalhos padrão (aplicados apenas quando o modelo existe em `agents.defaults.models`): + + Sim. O OpenClaw inclui alguns atalhos padrão (aplicados apenas quando o modelo existe em `agents.defaults.models`): - `opus` → `anthropic/claude-opus-4-6` - `sonnet` → `anthropic/claude-sonnet-4-6` @@ -2492,7 +2492,7 @@ quanto a uso/faturamento e aumente os limites conforme necessário. } ``` - Depois, `/model sonnet` (ou `/` quando compatível) é resolvido para esse ID de modelo. + Depois, `/model sonnet` (ou `/`, quando compatível) resolve para esse ID de modelo. @@ -2525,23 +2525,23 @@ quanto a uso/faturamento e aumente os limites conforme necessário. } ``` - Se você referenciar um provedor/modelo, mas a chave obrigatória do provedor estiver ausente, receberá um erro de autenticação em tempo de execução (por exemplo, `No API key found for provider "zai"`). + Se você referenciar um provedor/modelo, mas a chave necessária do provedor estiver ausente, receberá um erro de autenticação em tempo de execução (por exemplo, `No API key found for provider "zai"`). - **No API key found for provider após adicionar um novo agent** + **Nenhuma chave de API encontrada para o provedor após adicionar um novo agent** Isso geralmente significa que o **novo agent** tem um armazenamento de autenticação vazio. A autenticação é por agent e - fica em: + fica armazenada em: ``` ~/.openclaw/agents//agent/auth-profiles.json ``` - Opções de correção: + Opções para corrigir: - Execute `openclaw agents add ` e configure a autenticação durante o assistente. - Ou copie `auth-profiles.json` do `agentDir` do agent principal para o `agentDir` do novo agent. - **Não** reutilize `agentDir` entre agents; isso causa colisões de autenticação/session. + **Não** reutilize `agentDir` entre agents; isso causa colisões de autenticação/sessão. @@ -2555,69 +2555,69 @@ quanto a uso/faturamento e aumente os limites conforme necessário. 1. **Rotação de perfil de autenticação** dentro do mesmo provedor. 2. **Fallback de modelo** para o próximo modelo em `agents.defaults.model.fallbacks`. - Cooldowns se aplicam a perfis com falha (backoff exponencial), para que o OpenClaw possa continuar respondendo mesmo quando um provedor está com rate limit ou falhando temporariamente. + Cooldowns se aplicam a perfis com falha (backoff exponencial), então o OpenClaw pode continuar respondendo mesmo quando um provedor está com limite de taxa ou falhando temporariamente. - O bucket de rate limit inclui mais do que respostas `429` simples. O OpenClaw + O bucket de limite de taxa inclui mais do que respostas `429` simples. O OpenClaw também trata mensagens como `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded`, `resource exhausted` e limites - periódicos de janela de uso (`weekly/monthly limit reached`) como - rate limits que justificam failover. + periódicos de janela de uso (`weekly/monthly limit reached`) como dignos de + failover por limite de taxa. - Algumas respostas que parecem de faturamento não são `402`, e algumas respostas HTTP `402` - também continuam nesse bucket transitório. Se um provedor retornar + Algumas respostas que parecem ser de faturamento não são `402`, e algumas respostas HTTP `402` + também permanecem nesse bucket transitório. Se um provedor retornar texto explícito de faturamento em `401` ou `403`, o OpenClaw ainda pode manter isso - na faixa de faturamento, mas correspondências de texto específicas do provedor continuam limitadas ao + na faixa de faturamento, mas os correspondentes de texto específicos do provedor permanecem limitados ao provedor a que pertencem (por exemplo, OpenRouter `Key limit exceeded`). Se uma mensagem `402` - em vez disso se parecer com um limite de janela de uso passível de nova tentativa ou - um limite de gasto da organização/workspace (`daily limit reached, resets tomorrow`, - `organization spending limit exceeded`), o OpenClaw trata isso como + em vez disso parecer uma janela de uso que pode ser repetida ou um + limite de gastos da organização/workspace (`daily limit reached, resets tomorrow`, + `organization spending limit exceeded`), o OpenClaw a trata como `rate_limit`, não como uma desativação longa por faturamento. - Erros de estouro de contexto são diferentes: assinaturas como + Erros de excesso de contexto são diferentes: assinaturas como `request_too_large`, `input exceeds the maximum number of tokens`, `input token count exceeds the maximum number of input tokens`, `input is too long for the model` ou `ollama error: context length exceeded` permanecem no caminho de Compaction/nova tentativa em vez de avançar o fallback de modelo. - O texto genérico de erro do servidor é intencionalmente mais restrito do que “qualquer coisa com - unknown/error”. O OpenClaw trata formas transitórias limitadas ao provedor - como Anthropic bare `An unknown error occurred`, OpenRouter bare - `Provider returned error`, erros de stop reason como `Unhandled stop reason: + O texto genérico de erro do servidor é intencionalmente mais restrito do que "qualquer coisa com + unknown/error nele". O OpenClaw trata formatos transitórios com escopo de provedor + como Anthropic simples `An unknown error occurred`, OpenRouter simples + `Provider returned error`, erros de motivo de parada como `Unhandled stop reason: error`, payloads JSON `api_error` com texto transitório de servidor (`internal server error`, `unknown error, 520`, `upstream error`, `backend error`) e erros de provedor ocupado como `ModelNotReadyException` como - sinais de timeout/sobrecarga que justificam failover quando o contexto do - provedor corresponde. - Texto genérico interno de fallback como `LLM request failed with an unknown + sinais de timeout/sobrecarga dignos de failover quando o contexto do provedor + corresponde. + Texto interno genérico de fallback como `LLM request failed with an unknown error.` permanece conservador e não dispara fallback de modelo por si só. - Isso significa que o sistema tentou usar o ID de perfil de autenticação `anthropic:default`, mas não encontrou credenciais para ele no armazenamento de autenticação esperado. + Isso significa que o sistema tentou usar o ID de perfil de autenticação `anthropic:default`, mas não conseguiu encontrar credenciais para ele no armazenamento de autenticação esperado. **Checklist de correção:** - - **Confirme onde os perfis de autenticação ficam** (caminhos novos vs. legados) + - **Confirme onde os perfis de autenticação ficam** (caminhos novos vs legados) - Atual: `~/.openclaw/agents//agent/auth-profiles.json` - Legado: `~/.openclaw/agent/*` (migrado por `openclaw doctor`) - - **Confirme que sua variável de ambiente foi carregada pelo Gateway** + - **Confirme que sua var de ambiente está carregada pelo Gateway** - Se você definiu `ANTHROPIC_API_KEY` no shell, mas executa o Gateway via systemd/launchd, ele pode não herdá-la. Coloque-a em `~/.openclaw/.env` ou ative `env.shellEnv`. - - **Certifique-se de estar editando o agent correto** + - **Certifique-se de que está editando o agent correto** - Configurações multi-agent significam que pode haver vários arquivos `auth-profiles.json`. - - **Faça uma verificação básica do status do modelo/autenticação** + - **Faça uma verificação básica do status de modelo/autenticação** - Use `openclaw models status` para ver os modelos configurados e se os provedores estão autenticados. **Checklist de correção para "No credentials found for profile anthropic"** - Isso significa que a execução está fixada a um perfil de autenticação da Anthropic, mas o Gateway - não consegue encontrá-lo no seu armazenamento de autenticação. + Isso significa que a execução está fixada em um perfil de autenticação da Anthropic, mas o Gateway + não consegue encontrá-lo em seu armazenamento de autenticação. - **Use Claude CLI** - Execute `openclaw models auth login --provider anthropic --method cli --set-default` no host do gateway. - - **Se quiser usar uma chave de API** + - **Se você quiser usar uma chave de API** - Coloque `ANTHROPIC_API_KEY` em `~/.openclaw/.env` no **host do gateway**. - Limpe qualquer ordem fixada que force um perfil ausente: @@ -2625,29 +2625,29 @@ quanto a uso/faturamento e aumente os limites conforme necessário. openclaw models auth order clear --provider anthropic ``` - - **Confirme que você está executando comandos no host do gateway** - - Em modo remoto, os perfis de autenticação ficam na máquina do gateway, não no seu laptop. + - **Confirme que está executando comandos no host do gateway** + - No modo remoto, os perfis de autenticação ficam na máquina do gateway, não no seu laptop. - Se sua configuração de modelo incluir Google Gemini como fallback (ou se você trocou para um atalho do Gemini), o OpenClaw tentará usá-lo durante o fallback de modelo. Se você não configurou credenciais do Google, verá `No API key found for provider "google"`. + Se sua configuração de modelo incluir Google Gemini como fallback (ou se você trocou para um atalho Gemini), o OpenClaw tentará usá-lo durante o fallback de modelo. Se você não tiver configurado credenciais do Google, verá `No API key found for provider "google"`. - Correção: forneça autenticação do Google ou remova/evite modelos do Google em `agents.defaults.model.fallbacks` / aliases para que o fallback não seja roteado para lá. + Correção: forneça autenticação do Google ou remova/evite modelos Google em `agents.defaults.model.fallbacks` / aliases para que o fallback não roteie para lá. **LLM request rejected: thinking signature required (Google Antigravity)** - Causa: o histórico da session contém **blocos de thinking sem assinaturas** (frequentemente de - um stream abortado/parcial). O Google Antigravity exige assinaturas para blocos de thinking. + Causa: o histórico da sessão contém **blocos thinking sem assinaturas** (muitas vezes de + um stream abortado/parcial). O Google Antigravity exige assinaturas para blocos thinking. - Correção: o OpenClaw agora remove blocos de thinking sem assinatura para Claude no Google Antigravity. Se isso ainda aparecer, inicie uma **nova session** ou defina `/thinking off` para esse agent. + Correção: o OpenClaw agora remove blocos thinking sem assinatura para o Claude do Google Antigravity. Se isso ainda aparecer, inicie uma **nova sessão** ou defina `/thinking off` para esse agent. ## Perfis de autenticação: o que são e como gerenciá-los -Relacionado: [/concepts/oauth](/pt-BR/concepts/oauth) (fluxos OAuth, armazenamento de tokens, padrões de múltiplas contas) +Relacionado: [/concepts/oauth](/pt-BR/concepts/oauth) (fluxos OAuth, armazenamento de tokens, padrões multi-conta) @@ -2660,30 +2660,30 @@ Relacionado: [/concepts/oauth](/pt-BR/concepts/oauth) (fluxos OAuth, armazenamen - O OpenClaw usa IDs com prefixo do provedor, como: + O OpenClaw usa IDs prefixados pelo provedor, como: - `anthropic:default` (comum quando não existe identidade de e-mail) - `anthropic:` para identidades OAuth - - IDs personalizados que você escolher (por exemplo `anthropic:work`) + - IDs personalizados que você escolher (por exemplo, `anthropic:work`) - Sim. A configuração oferece suporte a metadados opcionais para perfis e uma ordenação por provedor (`auth.order.`). Isso **não** armazena segredos; apenas mapeia IDs para provedor/modo e define a ordem de rotação. + Sim. A configuração oferece suporte a metadados opcionais para perfis e uma ordenação por provedor (`auth.order.`). Isso **não** armazena segredos; mapeia IDs para provedor/modo e define a ordem de rotação. - O OpenClaw pode ignorar temporariamente um perfil se ele estiver em um **cooldown** curto (rate limits/timeouts/falhas de autenticação) ou em um estado **desativado** mais longo (faturamento/créditos insuficientes). Para inspecionar isso, execute `openclaw models status --json` e verifique `auth.unusableProfiles`. Ajuste: `auth.cooldowns.billingBackoffHours*`. + O OpenClaw pode pular temporariamente um perfil se ele estiver em um **cooldown** curto (limites de taxa/timeouts/falhas de autenticação) ou em um estado mais longo de **desativado** (faturamento/créditos insuficientes). Para inspecionar isso, execute `openclaw models status --json` e verifique `auth.unusableProfiles`. Ajuste: `auth.cooldowns.billingBackoffHours*`. - Cooldowns de rate limit podem ser específicos por modelo. Um perfil que esteja em cooldown + Cooldowns por limite de taxa podem ter escopo por modelo. Um perfil que está em cooldown para um modelo ainda pode ser utilizável para um modelo irmão no mesmo provedor, - enquanto janelas de faturamento/desativação continuam bloqueando o perfil inteiro. + enquanto janelas de faturamento/desativação ainda bloqueiam o perfil inteiro. Você também pode definir uma substituição de ordem **por agent** (armazenada em `auth-state.json` desse agent) via CLI: ```bash - # Usa o agent padrão configurado por padrão (omita --agent) + # O padrão é o agent padrão configurado (omita --agent) openclaw models auth order get --provider anthropic - # Fixa a rotação em um único perfil (tenta apenas este) + # Trava a rotação em um único perfil (tenta só este) openclaw models auth order set --provider anthropic anthropic:default # Ou define uma ordem explícita (fallback dentro do provedor) @@ -2693,7 +2693,7 @@ Relacionado: [/concepts/oauth](/pt-BR/concepts/oauth) (fluxos OAuth, armazenamen openclaw models auth order clear --provider anthropic ``` - Para direcionar a um agent específico: + Para apontar para um agent específico: ```bash openclaw models auth order set --provider anthropic --agent main anthropic:default @@ -2705,18 +2705,18 @@ Relacionado: [/concepts/oauth](/pt-BR/concepts/oauth) (fluxos OAuth, armazenamen openclaw models status --probe ``` - Se um perfil armazenado for omitido da ordem explícita, a sondagem informa + Se um perfil armazenado for omitido da ordem explícita, a sonda informa `excluded_by_auth_order` para esse perfil em vez de tentá-lo silenciosamente. - + O OpenClaw oferece suporte a ambos: - - **OAuth** geralmente aproveita acesso por assinatura (quando aplicável). + - **OAuth** frequentemente aproveita acesso por assinatura (quando aplicável). - **Chaves de API** usam cobrança por token. - O assistente oferece suporte explícito a Anthropic Claude CLI, OAuth do OpenAI Codex e chaves de API. + O assistente oferece suporte explícito a Anthropic Claude CLI, OpenAI Codex OAuth e chaves de API. @@ -2725,29 +2725,29 @@ Relacionado: [/concepts/oauth](/pt-BR/concepts/oauth) (fluxos OAuth, armazenamen - `gateway.port` controla a única porta multiplexada para WebSocket + HTTP (Control UI, hooks etc.). + `gateway.port` controla a porta multiplexada única para WebSocket + HTTP (Control UI, hooks etc.). Precedência: ``` - --port > OPENCLAW_GATEWAY_PORT > gateway.port > default 18789 + --port > OPENCLAW_GATEWAY_PORT > gateway.port > padrão 18789 ``` - - Porque "running" é a visão do **supervisor** (launchd/systemd/schtasks). A sondagem RPC é a CLI realmente se conectando ao WebSocket do gateway e chamando `status`. + + Porque "running" é a visão do **supervisor** (launchd/systemd/schtasks). A sonda RPC é a CLI realmente se conectando ao gateway WebSocket e chamando `status`. Use `openclaw gateway status` e confie nestas linhas: - - `Probe target:` (a URL que a sondagem realmente usou) + - `Probe target:` (a URL que a sonda realmente usou) - `Listening:` (o que realmente está vinculado à porta) - - `Last gateway error:` (causa-raiz comum quando o processo está vivo, mas a porta não está escutando) + - `Last gateway error:` (causa raiz comum quando o processo está vivo, mas a porta não está escutando) - - Você está editando um arquivo de configuração enquanto o serviço está executando outro (geralmente uma incompatibilidade de `--profile` / `OPENCLAW_STATE_DIR`). + + Você está editando um arquivo de configuração enquanto o serviço está executando outro (frequentemente uma incompatibilidade de `--profile` / `OPENCLAW_STATE_DIR`). Correção: @@ -2760,13 +2760,13 @@ Relacionado: [/concepts/oauth](/pt-BR/concepts/oauth) (fluxos OAuth, armazenamen - O OpenClaw aplica um lock de runtime vinculando imediatamente o listener WebSocket na inicialização (padrão `ws://127.0.0.1:18789`). Se o bind falhar com `EADDRINUSE`, ele gera `GatewayLockError`, indicando que outra instância já está escutando. + O OpenClaw impõe um bloqueio de tempo de execução vinculando imediatamente o listener WebSocket na inicialização (padrão `ws://127.0.0.1:18789`). Se o bind falhar com `EADDRINUSE`, ele gera `GatewayLockError`, indicando que outra instância já está escutando. - Correção: pare a outra instância, libere a porta ou execute com `openclaw gateway --port `. + Correção: interrompa a outra instância, libere a porta ou execute com `openclaw gateway --port `. - + Defina `gateway.mode: "remote"` e aponte para uma URL WebSocket remota, opcionalmente com credenciais remotas de segredo compartilhado: ```json5 @@ -2785,54 +2785,54 @@ Relacionado: [/concepts/oauth](/pt-BR/concepts/oauth) (fluxos OAuth, armazenamen Observações: - `openclaw gateway` só inicia quando `gateway.mode` é `local` (ou quando você passa a flag de substituição). - - O app do macOS observa o arquivo de configuração e troca de modo em tempo real quando esses valores mudam. - - `gateway.remote.token` / `.password` são apenas credenciais remotas do lado do cliente; elas não habilitam autenticação do gateway local por si só. + - O app macOS observa o arquivo de configuração e alterna os modos em tempo real quando esses valores mudam. + - `gateway.remote.token` / `.password` são apenas credenciais remotas do lado do cliente; elas não ativam a autenticação local do gateway por si só. - + Seu caminho de autenticação do gateway e o método de autenticação da UI não correspondem. - Fatos (a partir do código): + Fatos (do código): - - A Control UI mantém o token em `sessionStorage` para a session atual da aba do navegador e a URL do gateway selecionada, então atualizações na mesma aba continuam funcionando sem restaurar persistência de token de longa duração em `localStorage`. + - A Control UI mantém o token em `sessionStorage` para a sessão atual da aba do navegador e a URL do gateway selecionado, então atualizações na mesma aba continuam funcionando sem restaurar persistência de token em `localStorage` de longa duração. - Em `AUTH_TOKEN_MISMATCH`, clientes confiáveis podem tentar uma nova tentativa limitada com um token de dispositivo em cache quando o gateway retorna dicas de nova tentativa (`canRetryWithDeviceToken=true`, `recommendedNextStep=retry_with_device_token`). - - Essa nova tentativa com token em cache agora reutiliza os escopos aprovados em cache armazenados com o token do dispositivo. Chamadores com `deviceToken` explícito / `scopes` explícitos ainda mantêm o conjunto de escopos solicitado em vez de herdar escopos em cache. - - Fora desse caminho de nova tentativa, a precedência de autenticação da conexão é segredo compartilhado explícito token/senha primeiro, depois `deviceToken` explícito, depois token de dispositivo armazenado e então token de bootstrap. - - As verificações de escopo do token de bootstrap têm prefixo por função. A allowlist integrada de operador de bootstrap atende apenas solicitações de operador; node ou outras funções não operador ainda precisam de escopos sob o prefixo da própria função. + - Essa nova tentativa com token em cache agora reutiliza os escopos aprovados em cache armazenados com o token do dispositivo. Chamadores com `deviceToken` explícito / `scopes` explícitos ainda mantêm o conjunto de escopos solicitado em vez de herdarem escopos em cache. + - Fora desse caminho de nova tentativa, a precedência da autenticação de conexão é: token/senha compartilhados explícitos primeiro, depois `deviceToken` explícito, depois token de dispositivo armazenado, depois token bootstrap. + - As verificações de escopo do token bootstrap têm prefixo de função. A allowlist incorporada do operador bootstrap satisfaz apenas solicitações de operador; roles de node ou outras roles não operadoras ainda precisam de escopos sob o prefixo da própria role. Correção: - Mais rápido: `openclaw dashboard` (imprime + copia a URL do dashboard, tenta abrir; mostra dica de SSH se estiver headless). - Se você ainda não tiver um token: `openclaw doctor --generate-gateway-token`. - - Se for remoto, primeiro crie um túnel: `ssh -N -L 18789:127.0.0.1:18789 user@host` e depois abra `http://127.0.0.1:18789/`. - - Modo de segredo compartilhado: defina `gateway.auth.token` / `OPENCLAW_GATEWAY_TOKEN` ou `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD` e então cole o segredo correspondente nas configurações da Control UI. - - Modo Tailscale Serve: verifique se `gateway.auth.allowTailscale` está habilitado e se você está abrindo a URL do Serve, não uma URL bruta de loopback/tailnet que ignora os cabeçalhos de identidade do Tailscale. - - Modo trusted-proxy: verifique se você está passando pelo proxy com reconhecimento de identidade sem loopback configurado, não por um proxy de loopback no mesmo host nem pela URL bruta do gateway. - - Se a incompatibilidade persistir após a nova tentativa única, faça rotação/reaprovação do token do dispositivo pareado: + - Se for remoto, faça o túnel primeiro: `ssh -N -L 18789:127.0.0.1:18789 user@host` e depois abra `http://127.0.0.1:18789/`. + - Modo de segredo compartilhado: defina `gateway.auth.token` / `OPENCLAW_GATEWAY_TOKEN` ou `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD`, depois cole o segredo correspondente nas configurações da Control UI. + - Modo Tailscale Serve: verifique se `gateway.auth.allowTailscale` está ativado e se você está abrindo a URL do Serve, não uma URL bruta de loopback/tailnet que contorna os cabeçalhos de identidade do Tailscale. + - Modo trusted-proxy: verifique se você está passando pelo proxy com reconhecimento de identidade sem loopback configurado, não por um proxy de loopback no mesmo host nem por uma URL bruta do gateway. + - Se a incompatibilidade persistir após a única nova tentativa, rotacione/reaprove o token de dispositivo pareado: - `openclaw devices list` - `openclaw devices rotate --device --role operator` - Se esse comando de rotação disser que foi negado, verifique duas coisas: - - sessions de dispositivo pareado só podem girar **o próprio** dispositivo, a menos que também tenham `operator.admin` + - sessões de dispositivo pareado só podem rotacionar o **próprio** dispositivo, a menos que também tenham `operator.admin` - valores explícitos de `--scope` não podem exceder os escopos atuais de operador do chamador - Ainda travado? Execute `openclaw status --all` e siga [Solução de problemas](/pt-BR/gateway/troubleshooting). Consulte [Dashboard](/web/dashboard) para detalhes de autenticação. - - O bind `tailnet` escolhe um IP do Tailscale nas interfaces de rede (100.64.0.0/10). Se a máquina não estiver no Tailscale (ou a interface estiver inativa), não há nada em que fazer bind. + + O bind `tailnet` escolhe um IP do Tailscale nas interfaces de rede (100.64.0.0/10). Se a máquina não estiver no Tailscale (ou se a interface estiver inativa), não haverá nada em que fazer bind. Correção: - Inicie o Tailscale nesse host (para que ele tenha um endereço 100.x), ou - Troque para `gateway.bind: "loopback"` / `"lan"`. - Observação: `tailnet` é explícito. `auto` prefere loopback; use `gateway.bind: "tailnet"` quando quiser um bind apenas na tailnet. + Observação: `tailnet` é explícito. `auto` prefere loopback; use `gateway.bind: "tailnet"` quando quiser um bind somente de tailnet. - Normalmente não — um Gateway pode executar vários canais de mensagens e agents. Use vários Gateways apenas quando precisar de redundância (ex.: bot de resgate) ou isolamento rígido. + Normalmente não — um Gateway pode executar vários canais de mensagem e agents. Use vários Gateways apenas quando precisar de redundância (ex.: bot de resgate) ou isolamento rígido. Sim, mas você precisa isolar: @@ -2844,24 +2844,24 @@ Relacionado: [/concepts/oauth](/pt-BR/concepts/oauth) (fluxos OAuth, armazenamen Configuração rápida (recomendada): - Use `openclaw --profile ...` por instância (cria automaticamente `~/.openclaw-`). - - Defina um `gateway.port` exclusivo em cada configuração de perfil (ou passe `--port` em execuções manuais). + - Defina um `gateway.port` exclusivo na configuração de cada perfil (ou passe `--port` em execuções manuais). - Instale um serviço por perfil: `openclaw --profile gateway install`. - Perfis também adicionam sufixo aos nomes dos serviços (`ai.openclaw.`; legado `com.openclaw.*`, `openclaw-gateway-.service`, `OpenClaw Gateway ()`). + Os perfis também acrescentam sufixo aos nomes de serviço (`ai.openclaw.`; legados `com.openclaw.*`, `openclaw-gateway-.service`, `OpenClaw Gateway ()`). Guia completo: [Múltiplos gateways](/pt-BR/gateway/multiple-gateways). O Gateway é um **servidor WebSocket** e espera que a primeira mensagem seja - um frame `connect`. Se ele receber qualquer outra coisa, fecha a conexão + um frame `connect`. Se receber qualquer outra coisa, fecha a conexão com **código 1008** (violação de política). Causas comuns: - Você abriu a URL **HTTP** em um navegador (`http://...`) em vez de um cliente WS. - - Você usou a porta ou caminho errados. - - Um proxy ou túnel removeu cabeçalhos de autenticação ou enviou uma requisição que não era do Gateway. + - Você usou a porta ou o caminho errados. + - Um proxy ou túnel removeu cabeçalhos de autenticação ou enviou uma solicitação que não era do Gateway. Correções rápidas: @@ -2869,13 +2869,13 @@ Relacionado: [/concepts/oauth](/pt-BR/concepts/oauth) (fluxos OAuth, armazenamen 2. Não abra a porta WS em uma aba normal do navegador. 3. Se a autenticação estiver ativada, inclua o token/senha no frame `connect`. - Se você estiver usando a CLI ou a TUI, a URL deve ser assim: + Se você estiver usando a CLI ou a TUI, a URL deve parecer com: ``` openclaw tui --url ws://:18789 --token ``` - Detalhes do protocolo: [Protocolo do Gateway](/pt-BR/gateway/protocol). + Detalhes do protocolo: [Protocolo do gateway](/pt-BR/gateway/protocol). @@ -2883,7 +2883,7 @@ Relacionado: [/concepts/oauth](/pt-BR/concepts/oauth) (fluxos OAuth, armazenamen ## Logging e depuração - + Logs em arquivo (estruturados): ``` @@ -2898,18 +2898,18 @@ Relacionado: [/concepts/oauth](/pt-BR/concepts/oauth) (fluxos OAuth, armazenamen openclaw logs --follow ``` - Logs de serviço/supervisor (quando o gateway roda via launchd/systemd): + Logs do serviço/supervisor (quando o gateway é executado via launchd/systemd): - macOS: `$OPENCLAW_STATE_DIR/logs/gateway.log` e `gateway.err.log` (padrão: `~/.openclaw/logs/...`; perfis usam `~/.openclaw-/logs/...`) - Linux: `journalctl --user -u openclaw-gateway[-].service -n 200 --no-pager` - Windows: `schtasks /Query /TN "OpenClaw Gateway ()" /V /FO LIST` - Consulte [Solução de problemas](/pt-BR/gateway/troubleshooting) para mais informações. + Consulte [Solução de problemas](/pt-BR/gateway/troubleshooting) para mais detalhes. - - Use os helpers do gateway: + + Use os auxiliares do gateway: ```bash openclaw gateway status @@ -2920,10 +2920,10 @@ Relacionado: [/concepts/oauth](/pt-BR/concepts/oauth) (fluxos OAuth, armazenamen - + Existem **dois modos de instalação no Windows**: - **1) WSL2 (recomendado):** o Gateway roda dentro do Linux. + **1) WSL2 (recomendado):** o Gateway é executado dentro do Linux. Abra o PowerShell, entre no WSL e depois reinicie: @@ -2939,7 +2939,7 @@ Relacionado: [/concepts/oauth](/pt-BR/concepts/oauth) (fluxos OAuth, armazenamen openclaw gateway run ``` - **2) Windows nativo (não recomendado):** o Gateway roda diretamente no Windows. + **2) Windows nativo (não recomendado):** o Gateway é executado diretamente no Windows. Abra o PowerShell e execute: @@ -2948,13 +2948,13 @@ Relacionado: [/concepts/oauth](/pt-BR/concepts/oauth) (fluxos OAuth, armazenamen openclaw gateway restart ``` - Se você o executa manualmente (sem serviço), use: + Se você o executar manualmente (sem serviço), use: ```powershell openclaw gateway run ``` - Documentação: [Windows (WSL2)](/pt-BR/platforms/windows), [Runbook do serviço Gateway](/pt-BR/gateway). + Documentação: [Windows (WSL2)](/pt-BR/platforms/windows), [Runbook do serviço do Gateway](/pt-BR/gateway). @@ -2970,24 +2970,24 @@ Relacionado: [/concepts/oauth](/pt-BR/concepts/oauth) (fluxos OAuth, armazenamen Causas comuns: - - A autenticação do modelo não foi carregada no **host do gateway** (verifique `models status`). - - Pareamento/allowlist do canal bloqueando respostas (verifique a configuração do canal + logs). + - Autenticação do modelo não carregada no **host do gateway** (verifique `models status`). + - Emparelhamento/allowlist do canal bloqueando respostas (verifique a configuração do canal + logs). - WebChat/Dashboard aberto sem o token correto. - Se você estiver remoto, confirme que a conexão de túnel/Tailscale está ativa e que o + Se você estiver remoto, confirme que a conexão por túnel/Tailscale está ativa e que o Gateway WebSocket está acessível. - Documentação: [Canais](/pt-BR/channels), [Solução de problemas](/pt-BR/gateway/troubleshooting), [Acesso remoto](/pt-BR/gateway/remote). + Documentação: [Channels](/pt-BR/channels), [Solução de problemas](/pt-BR/gateway/troubleshooting), [Acesso remoto](/pt-BR/gateway/remote). - - Isso normalmente significa que a UI perdeu a conexão WebSocket. Verifique: + + Isso geralmente significa que a UI perdeu a conexão WebSocket. Verifique: 1. O Gateway está em execução? `openclaw gateway status` 2. O Gateway está íntegro? `openclaw status` 3. A UI tem o token correto? `openclaw dashboard` - 4. Se for remoto, o túnel/link Tailscale está ativo? + 4. Se for remoto, o link de túnel/Tailscale está ativo? Depois acompanhe os logs: @@ -2999,7 +2999,7 @@ Relacionado: [/concepts/oauth](/pt-BR/concepts/oauth) (fluxos OAuth, armazenamen - + Comece com logs e status do canal: ```bash @@ -3007,14 +3007,14 @@ Relacionado: [/concepts/oauth](/pt-BR/concepts/oauth) (fluxos OAuth, armazenamen openclaw channels logs --channel telegram ``` - Depois compare o erro: + Depois relacione o erro: - - `BOT_COMMANDS_TOO_MUCH`: o menu do Telegram tem entradas demais. O OpenClaw já reduz até o limite do Telegram e tenta novamente com menos comandos, mas algumas entradas do menu ainda precisam ser removidas. Reduza comandos de plugin/Skill/personalizados ou desative `channels.telegram.commands.native` se não precisar do menu. - - `TypeError: fetch failed`, `Network request for 'setMyCommands' failed!` ou erros de rede semelhantes: se você estiver em uma VPS ou atrás de um proxy, confirme que HTTPS de saída é permitido e que o DNS funciona para `api.telegram.org`. + - `BOT_COMMANDS_TOO_MUCH`: o menu do Telegram tem entradas demais. O OpenClaw já reduz até o limite do Telegram e tenta novamente com menos comandos, mas algumas entradas do menu ainda precisam ser removidas. Reduza comandos de plugin/skill/personalizados ou desative `channels.telegram.commands.native` se não precisar do menu. + - `TypeError: fetch failed`, `Network request for 'setMyCommands' failed!` ou erros de rede semelhantes: se você estiver em uma VPS ou atrás de um proxy, confirme que HTTPS de saída está permitido e que o DNS funciona para `api.telegram.org`. - Se o Gateway for remoto, certifique-se de estar olhando os logs no host do Gateway. + Se o Gateway for remoto, verifique se você está olhando os logs no host do Gateway. - Documentação: [Telegram](/pt-BR/channels/telegram), [Solução de problemas de canais](/pt-BR/channels/troubleshooting). + Documentação: [Telegram](/pt-BR/channels/telegram), [Solução de problemas de canal](/pt-BR/channels/troubleshooting). @@ -3027,8 +3027,8 @@ Relacionado: [/concepts/oauth](/pt-BR/concepts/oauth) (fluxos OAuth, armazenamen openclaw logs --follow ``` - Na TUI, use `/status` para ver o estado atual. Se você espera respostas em um canal de chat, - garanta que a entrega esteja habilitada (`/deliver on`). + Na TUI, use `/status` para ver o estado atual. Se você espera respostas em um + canal de chat, certifique-se de que a entrega esteja ativada (`/deliver on`). Documentação: [TUI](/web/tui), [Comandos slash](/pt-BR/tools/slash-commands). @@ -3042,24 +3042,24 @@ Relacionado: [/concepts/oauth](/pt-BR/concepts/oauth) (fluxos OAuth, armazenamen openclaw gateway start ``` - Isso para/inicia o **serviço supervisionado** (launchd no macOS, systemd no Linux). + Isso interrompe/inicia o **serviço supervisionado** (launchd no macOS, systemd no Linux). Use isso quando o Gateway estiver sendo executado em segundo plano como daemon. - Se você estiver executando em primeiro plano, pare com Ctrl-C e depois: + Se você estiver executando em primeiro plano, interrompa com Ctrl-C e depois: ```bash openclaw gateway run ``` - Documentação: [Runbook do serviço Gateway](/pt-BR/gateway). + Documentação: [Runbook do serviço do Gateway](/pt-BR/gateway). - + - `openclaw gateway restart`: reinicia o **serviço em segundo plano** (launchd/systemd). - - `openclaw gateway`: executa o gateway **em primeiro plano** nesta sessão de terminal. + - `openclaw gateway`: executa o gateway **em primeiro plano** para esta sessão do terminal. - Se você instalou o serviço, use os comandos de gateway. Use `openclaw gateway` quando + Se você instalou o serviço, use os comandos do gateway. Use `openclaw gateway` quando quiser uma execução única em primeiro plano. @@ -3073,20 +3073,20 @@ Relacionado: [/concepts/oauth](/pt-BR/concepts/oauth) (fluxos OAuth, armazenamen - Anexos de saída do agent precisam incluir uma linha `MEDIA:` (em sua própria linha). Consulte [Configuração do assistente OpenClaw](/pt-BR/start/openclaw) e [Envio pelo agent](/pt-BR/tools/agent-send). + Anexos de saída do agent devem incluir uma linha `MEDIA:` (em sua própria linha). Consulte [Configuração do assistente OpenClaw](/pt-BR/start/openclaw) e [Envio do agent](/pt-BR/tools/agent-send). - Envio via CLI: + Envio pela CLI: ```bash - openclaw message send --target +15555550123 --message "Aqui está" --media /path/to/file.png + openclaw message send --target +15555550123 --message "Here you go" --media /path/to/file.png ``` Verifique também: - - O canal de destino oferece suporte a mídia de saída e não está bloqueado por allowlists. - - O arquivo está dentro dos limites de tamanho do provedor (imagens são redimensionadas para no máximo 2048 px). - - `tools.fs.workspaceOnly=true` mantém envios de caminho local limitados ao workspace, temp/media-store e arquivos validados pelo sandbox. - - `tools.fs.workspaceOnly=false` permite que `MEDIA:` envie arquivos locais do host que o agent já consiga ler, mas apenas para mídia mais tipos de documento seguros (imagens, áudio, vídeo, PDF e documentos do Office). Texto simples e arquivos parecidos com segredos continuam bloqueados. + - O canal de destino é compatível com mídia de saída e não está bloqueado por allowlists. + - O arquivo está dentro dos limites de tamanho do provedor (imagens são redimensionadas para no máximo 2048px). + - `tools.fs.workspaceOnly=true` mantém envios por caminho local limitados ao workspace, temp/media-store e arquivos validados pelo sandbox. + - `tools.fs.workspaceOnly=false` permite que `MEDIA:` envie arquivos locais do host que o agent já consegue ler, mas apenas para mídia e tipos de documento seguros (imagens, áudio, vídeo, PDF e documentos do Office). Arquivos de texto simples e com aparência de segredo continuam bloqueados. Consulte [Imagens](/pt-BR/nodes/images). @@ -3097,10 +3097,10 @@ Relacionado: [/concepts/oauth](/pt-BR/concepts/oauth) (fluxos OAuth, armazenamen - Trate DMs de entrada como entrada não confiável. Os padrões foram projetados para reduzir riscos: + Trate DMs de entrada como entrada não confiável. Os padrões são projetados para reduzir riscos: - O comportamento padrão em canais compatíveis com DM é **pairing**: - - Remetentes desconhecidos recebem um código de pareamento; o bot não processa a mensagem deles. + - Remetentes desconhecidos recebem um código de pairing; o bot não processa a mensagem deles. - Aprove com: `openclaw pairing approve --channel [--account ] ` - As solicitações pendentes são limitadas a **3 por canal**; verifique `openclaw pairing list --channel [--account ]` se um código não chegou. - Abrir DMs publicamente exige opt-in explícito (`dmPolicy: "open"` e allowlist `"*"`). @@ -3110,28 +3110,28 @@ Relacionado: [/concepts/oauth](/pt-BR/concepts/oauth) (fluxos OAuth, armazenamen - Não. Prompt injection trata de **conteúdo não confiável**, não apenas de quem pode mandar DM para o bot. - Se o seu assistente lê conteúdo externo (busca/fetch web, páginas do navegador, e-mails, - documentos, anexos, logs colados), esse conteúdo pode incluir instruções que tentam - sequestrar o modelo. Isso pode acontecer mesmo se **você for o único remetente**. + Não. Prompt injection diz respeito a **conteúdo não confiável**, não apenas a quem pode enviar DM ao bot. + Se seu assistente lê conteúdo externo (pesquisa/fetch na web, páginas do navegador, e-mails, + documentos, anexos, logs colados), esse conteúdo pode incluir instruções que tentem + sequestrar o modelo. Isso pode acontecer mesmo que **você seja o único remetente**. - O maior risco ocorre quando ferramentas estão habilitadas: o modelo pode ser induzido a + O maior risco ocorre quando ferramentas estão ativadas: o modelo pode ser enganado para exfiltrar contexto ou chamar ferramentas em seu nome. Reduza o raio de impacto: - - usando um agent "leitor" somente leitura ou com ferramentas desativadas para resumir conteúdo não confiável + - usando um agent "leitor", somente leitura ou sem ferramentas, para resumir conteúdo não confiável - mantendo `web_search` / `web_fetch` / `browser` desativados para agents com ferramentas habilitadas - - tratando texto decodificado de arquivos/documentos também como não confiável: OpenResponses - `input_file` e a extração de anexos de mídia envolvem o texto extraído em - marcadores explícitos de limite de conteúdo externo em vez de passar o texto bruto do arquivo - - sandboxing e allowlists estritas de ferramentas + - tratando também como não confiável o texto decodificado de arquivos/documentos: `input_file` do + OpenResponses e a extração de anexos de mídia envolvem o texto extraído em + marcadores explícitos de limite de conteúdo externo, em vez de passar o texto bruto do arquivo + - com sandboxing e allowlists rígidas de ferramentas Detalhes: [Segurança](/pt-BR/gateway/security). - Sim, para a maioria das configurações. Isolar o bot com contas e números de telefone separados - reduz o raio de impacto se algo der errado. Isso também facilita girar + Sim, na maioria das configurações. Isolar o bot com contas e números de telefone separados + reduz o raio de impacto se algo der errado. Isso também facilita rotacionar credenciais ou revogar acesso sem impactar suas contas pessoais. Comece pequeno. Dê acesso apenas às ferramentas e contas de que você realmente precisa e expanda @@ -3145,52 +3145,52 @@ Relacionado: [/concepts/oauth](/pt-BR/concepts/oauth) (fluxos OAuth, armazenamen **Não** recomendamos autonomia total sobre suas mensagens pessoais. O padrão mais seguro é: - Manter DMs em **modo pairing** ou em uma allowlist restrita. - - Usar um **número ou conta separados** se você quiser que ele envie mensagens em seu nome. + - Usar um **número ou conta separados** se quiser que ele envie mensagens em seu nome. - Deixar que ele redija e depois **aprovar antes de enviar**. - Se você quiser experimentar, faça isso em uma conta dedicada e mantenha-a isolada. Consulte + Se você quiser experimentar, faça isso em uma conta dedicada e mantenha tudo isolado. Consulte [Segurança](/pt-BR/gateway/security). - Sim, **se** o agent for somente chat e a entrada for confiável. Níveis menores são - mais suscetíveis a sequestro por instruções, portanto evite-os para agents com ferramentas habilitadas - ou ao ler conteúdo não confiável. Se você realmente precisar usar um modelo menor, restrinja + Sim, **desde que** o agent seja apenas de chat e a entrada seja confiável. Camadas menores são + mais suscetíveis a sequestro de instruções, então evite-as para agents com ferramentas habilitadas + ou ao ler conteúdo não confiável. Se você precisar usar um modelo menor, restrinja as ferramentas e execute dentro de um sandbox. Consulte [Segurança](/pt-BR/gateway/security). - - Códigos de pareamento são enviados **apenas** quando um remetente desconhecido envia mensagem ao bot e - `dmPolicy: "pairing"` está habilitado. `/start` por si só não gera um código. + + Códigos de pairing são enviados **apenas** quando um remetente desconhecido envia mensagem ao bot e + `dmPolicy: "pairing"` está ativado. `/start` por si só não gera um código. - Verifique solicitações pendentes: + Verifique as solicitações pendentes: ```bash openclaw pairing list telegram ``` - Se você quiser acesso imediato, coloque seu ID de remetente na allowlist ou defina `dmPolicy: "open"` + Se você quiser acesso imediato, adicione seu ID de remetente à allowlist ou defina `dmPolicy: "open"` para essa conta. - - Não. A política padrão de DM no WhatsApp é **pairing**. Remetentes desconhecidos recebem apenas um código de pareamento e a mensagem deles **não é processada**. O OpenClaw só responde a chats que recebe ou a envios explícitos que você aciona. + + Não. A política padrão de DM no WhatsApp é **pairing**. Remetentes desconhecidos recebem apenas um código de pairing e a mensagem deles **não é processada**. O OpenClaw só responde a chats que recebe ou a envios explícitos que você aciona. - Aprove o pareamento com: + Aprove o pairing com: ```bash openclaw pairing approve whatsapp ``` - Liste solicitações pendentes: + Liste as solicitações pendentes: ```bash openclaw pairing list whatsapp ``` - O prompt do assistente para número de telefone é usado para definir sua **allowlist/owner** para que seus próprios DMs sejam permitidos. Ele não é usado para envio automático. Se você executa no seu número pessoal do WhatsApp, use esse número e ative `channels.whatsapp.selfChatMode`. + Prompt do assistente para número de telefone: ele é usado para definir sua **allowlist/proprietário** para que suas próprias DMs sejam permitidas. Não é usado para envio automático. Se você executar no seu número pessoal do WhatsApp, use esse número e ative `channels.whatsapp.selfChatMode`. @@ -3198,11 +3198,11 @@ Relacionado: [/concepts/oauth](/pt-BR/concepts/oauth) (fluxos OAuth, armazenamen ## Comandos de chat, interrupção de tarefas e "ele não para" - - A maioria das mensagens internas ou de ferramentas só aparece quando **verbose**, **trace** ou **reasoning** está habilitado - para essa session. + + A maioria das mensagens internas ou de ferramentas só aparece quando **verbose**, **trace** ou **reasoning** está ativado + para aquela sessão. - Corrija no chat em que você vê isso: + Corrija no chat em que você está vendo isso: ``` /verbose off @@ -3210,7 +3210,7 @@ Relacionado: [/concepts/oauth](/pt-BR/concepts/oauth) (fluxos OAuth, armazenamen /reasoning off ``` - Se ainda estiver barulhento, verifique as configurações da session na Control UI e defina verbose + Se ainda estiver barulhento, verifique as configurações da sessão na Control UI e defina verbose como **inherit**. Confirme também que você não está usando um perfil de bot com `verboseDefault` definido como `on` na configuração. @@ -3219,7 +3219,7 @@ Relacionado: [/concepts/oauth](/pt-BR/concepts/oauth) (fluxos OAuth, armazenamen - Envie qualquer um destes **como uma mensagem isolada** (sem barra): + Envie qualquer um destes **como uma mensagem independente** (sem slash): ``` stop @@ -3243,7 +3243,7 @@ Relacionado: [/concepts/oauth](/pt-BR/concepts/oauth) (fluxos OAuth, armazenamen interrupt ``` - Esses são gatilhos de interrupção (não comandos slash). + Esses são gatilhos de interrupção (não são comandos slash). Para processos em segundo plano (da ferramenta exec), você pode pedir ao agent para executar: @@ -3253,15 +3253,15 @@ Relacionado: [/concepts/oauth](/pt-BR/concepts/oauth) (fluxos OAuth, armazenamen Visão geral dos comandos slash: consulte [Comandos slash](/pt-BR/tools/slash-commands). - A maioria dos comandos deve ser enviada como uma **mensagem isolada** que começa com `/`, mas alguns atalhos (como `/status`) também funcionam inline para remetentes na allowlist. + A maioria dos comandos deve ser enviada como uma mensagem **independente** que comece com `/`, mas alguns atalhos (como `/status`) também funcionam inline para remetentes na allowlist. O OpenClaw bloqueia mensagens **entre provedores** por padrão. Se uma chamada de ferramenta estiver vinculada - ao Telegram, ela não enviará para o Discord, a menos que você permita explicitamente. + ao Telegram, ela não enviará ao Discord a menos que você permita explicitamente. - Habilite mensagens entre provedores para o agent: + Ative mensagens entre provedores para o agent: ```json5 { @@ -3276,18 +3276,18 @@ Relacionado: [/concepts/oauth](/pt-BR/concepts/oauth) (fluxos OAuth, armazenamen } ``` - Reinicie o gateway depois de editar a configuração. + Reinicie o gateway após editar a configuração. - + O modo de fila controla como novas mensagens interagem com uma execução em andamento. Use `/queue` para mudar os modos: - `steer` - novas mensagens redirecionam a tarefa atual - - `followup` - executa mensagens uma de cada vez + - `followup` - executa mensagens uma por vez - `collect` - agrupa mensagens e responde uma vez (padrão) - `steer-backlog` - redireciona agora e depois processa o backlog - - `interrupt` - interrompe a execução atual e inicia uma nova + - `interrupt` - interrompe a execução atual e começa do zero Você pode adicionar opções como `debounce:2s cap:25 drop:summarize` para modos de followup. @@ -3298,10 +3298,10 @@ Relacionado: [/concepts/oauth](/pt-BR/concepts/oauth) (fluxos OAuth, armazenamen - No OpenClaw, credenciais e seleção de modelo são separadas. Definir `ANTHROPIC_API_KEY` (ou armazenar uma chave de API da Anthropic em perfis de autenticação) habilita a autenticação, mas o modelo padrão real é aquele que você configurar em `agents.defaults.model.primary` (por exemplo, `anthropic/claude-sonnet-4-6` ou `anthropic/claude-opus-4-6`). Se você vir `No credentials found for profile "anthropic:default"`, isso significa que o Gateway não conseguiu encontrar credenciais da Anthropic no `auth-profiles.json` esperado para o agent em execução. + No OpenClaw, credenciais e seleção de modelo são coisas separadas. Definir `ANTHROPIC_API_KEY` (ou armazenar uma chave de API da Anthropic em perfis de autenticação) ativa a autenticação, mas o modelo padrão real é aquele que você configurar em `agents.defaults.model.primary` (por exemplo, `anthropic/claude-sonnet-4-6` ou `anthropic/claude-opus-4-6`). Se você vir `No credentials found for profile "anthropic:default"`, isso significa que o Gateway não conseguiu encontrar credenciais da Anthropic no `auth-profiles.json` esperado para o agent em execução. --- -Ainda travado? Pergunte no [Discord](https://discord.com/invite/clawd) ou abra uma [discussão no GitHub](https://github.com/openclaw/openclaw/discussions). +Ainda está travado? Pergunte no [Discord](https://discord.com/invite/clawd) ou abra uma [discussão no GitHub](https://github.com/openclaw/openclaw/discussions). diff --git a/docs/pt-BR/help/testing.md b/docs/pt-BR/help/testing.md index 63d29ff2f..0db6b3a4d 100644 --- a/docs/pt-BR/help/testing.md +++ b/docs/pt-BR/help/testing.md @@ -1,15 +1,15 @@ --- read_when: - - Executando testes localmente ou no CI - - Adicionando regressões para bugs de modelo/provedor + - Executando testes localmente ou na CI + - Adicionando testes de regressão para bugs de modelo/provedor - Depurando o comportamento do Gateway + agente summary: 'Kit de testes: suítes unit/e2e/live, executores Docker e o que cada teste cobre' title: Testes x-i18n: - generated_at: "2026-04-18T05:24:45Z" + generated_at: "2026-04-20T05:41:43Z" model: gpt-5.4 provider: openai - source_hash: 7cdd2048ba58e606fd68703977c2b33000abdb1826b6589ce25a35c53468726a + source_hash: 88457038e2e2c7940d0348762d0ece187111a8c61fa9bad54b39eade4217ddbc source_path: help/testing.md workflow: 15 --- @@ -31,91 +31,91 @@ Na maioria dos dias: - Gate completo (esperado antes do push): `pnpm build && pnpm check && pnpm test` - Execução local mais rápida da suíte completa em uma máquina com bastante recurso: `pnpm test:max` -- Loop direto de watch do Vitest: `pnpm test:watch` -- O direcionamento direto de arquivos agora também roteia caminhos de extensão/canal: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- Prefira execuções direcionadas primeiro quando estiver iterando sobre uma única falha. +- Loop direto do Vitest em watch: `pnpm test:watch` +- O direcionamento direto por arquivo agora também roteia caminhos de extensões/canais: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` +- Prefira primeiro execuções direcionadas quando estiver iterando em uma única falha. - Site de QA com suporte de Docker: `pnpm qa:lab:up` -- Faixa de QA com suporte de VM Linux: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` +- Lane de QA com suporte de VM Linux: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -Quando você altera testes ou quer confiança extra: +Quando você mexe em testes ou quer confiança extra: - Gate de cobertura: `pnpm test:coverage` - Suíte E2E: `pnpm test:e2e` Ao depurar provedores/modelos reais (requer credenciais reais): -- Suíte live (sondagens de modelos + ferramentas/imagens do Gateway): `pnpm test:live` -- Direcione um arquivo live em modo silencioso: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Suíte live (modelos + sondas de ferramenta/imagem do Gateway): `pnpm test:live` +- Direcionar um arquivo live silenciosamente: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -Dica: quando você só precisa de um caso com falha, prefira restringir os testes live por meio das variáveis de ambiente de allowlist descritas abaixo. +Dica: quando você precisa apenas de um caso com falha, prefira restringir os testes live por meio das variáveis de ambiente de allowlist descritas abaixo. ## Executores específicos de QA -Esses comandos ficam ao lado das suítes de teste principais quando você precisa do realismo do QA-lab: +Estes comandos ficam ao lado das suítes principais de teste quando você precisa do realismo do qa-lab: - `pnpm openclaw qa suite` - Executa cenários de QA com suporte do repositório diretamente no host. - - Executa vários cenários selecionados em paralelo por padrão com workers isolados do Gateway, até 64 workers ou a contagem de cenários selecionados. Use `--concurrency ` para ajustar a contagem de workers, ou `--concurrency 1` para a faixa serial mais antiga. + - Executa vários cenários selecionados em paralelo por padrão com workers isolados do gateway. `qa-channel` usa concorrência 4 por padrão (limitada pela quantidade de cenários selecionados). Use `--concurrency ` para ajustar a quantidade de workers, ou `--concurrency 1` para a lane serial antiga. + - Sai com código diferente de zero quando qualquer cenário falha. Use `--allow-failures` quando quiser artefatos sem um código de saída com falha. - Suporta os modos de provedor `live-frontier`, `mock-openai` e `aimock`. - `aimock` inicia um servidor local de provedor com suporte do AIMock para cobertura experimental de fixture e simulação de protocolo sem substituir a faixa `mock-openai` sensível ao cenário. + `aimock` inicia um servidor local de provedor com suporte de AIMock para cobertura experimental de fixtures e mocks de protocolo sem substituir a lane `mock-openai`, que é orientada a cenários. - `pnpm openclaw qa suite --runner multipass` - Executa a mesma suíte de QA dentro de uma VM Linux Multipass descartável. - - Mantém o mesmo comportamento de seleção de cenários que `qa suite` no host. - - Reutiliza as mesmas flags de seleção de provedor/modelo que `qa suite`. + - Mantém o mesmo comportamento de seleção de cenários de `qa suite` no host. + - Reutiliza as mesmas flags de seleção de provedor/modelo de `qa suite`. - Execuções live encaminham as entradas de autenticação de QA suportadas que são práticas para o guest: chaves de provedor baseadas em env, o caminho de configuração do provedor live de QA e `CODEX_HOME` quando presente. - - Os diretórios de saída devem permanecer sob a raiz do repositório para que o guest possa gravar de volta pelo workspace montado. - - Grava o relatório + resumo normais de QA, além dos logs do Multipass, em + - Os diretórios de saída devem permanecer sob a raiz do repositório para que o guest possa gravar de volta por meio do workspace montado. + - Grava o relatório e resumo normais de QA, além dos logs do Multipass, em `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - - Inicia o site de QA com suporte de Docker para trabalho de QA no estilo de operador. + - Inicia o site de QA com suporte de Docker para trabalho de QA no estilo operador. - `pnpm openclaw qa aimock` - - Inicia apenas o servidor local de provedor AIMock para testes de fumaça diretos de protocolo. + - Inicia apenas o servidor local de provedor AIMock para smoke tests diretos de protocolo. - `pnpm openclaw qa matrix` - - Executa a faixa de QA live do Matrix contra um homeserver Tuwunel descartável com suporte de Docker. - - Esse host de QA é apenas para repositório/dev hoje. Instalações empacotadas do OpenClaw não incluem - `qa-lab`, portanto não expõem `openclaw qa`. - - Checkouts do repositório carregam o executor empacotado diretamente; nenhuma etapa separada de instalação de Plugin é necessária. - - Provisiona três usuários Matrix temporários (`driver`, `sut`, `observer`) mais uma sala privada, depois inicia um processo filho do Gateway de QA com o Plugin Matrix real como transporte do SUT. - - Usa a imagem estável fixada do Tuwunel `ghcr.io/matrix-construct/tuwunel:v1.5.1` por padrão. Substitua com `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` quando precisar testar uma imagem diferente. - - O Matrix não expõe flags compartilhadas de origem de credenciais porque a faixa provisiona usuários descartáveis localmente. + - Executa a lane live de QA do Matrix contra um homeserver Tuwunel descartável com suporte de Docker. + - Este host de QA é apenas para repositório/desenvolvimento hoje. Instalações empacotadas do OpenClaw não incluem `qa-lab`, então não expõem `openclaw qa`. + - Checkouts do repositório carregam o runner empacotado diretamente; nenhuma etapa separada de instalação de plugin é necessária. + - Provisiona três usuários temporários do Matrix (`driver`, `sut`, `observer`) mais uma sala privada, depois inicia um processo filho do gateway de QA com o plugin real do Matrix como transporte do SUT. + - Usa a imagem estável fixada do Tuwunel `ghcr.io/matrix-construct/tuwunel:v1.5.1` por padrão. Substitua com `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE` quando precisar testar outra imagem. + - O Matrix não expõe flags compartilhadas de origem de credenciais porque a lane provisiona usuários descartáveis localmente. - Grava um relatório de QA do Matrix, resumo, artefato de eventos observados e log combinado de stdout/stderr em `.artifacts/qa-e2e/...`. - `pnpm openclaw qa telegram` - - Executa a faixa de QA live do Telegram contra um grupo privado real usando os tokens de bot do driver e do SUT vindos do env. + - Executa a lane live de QA do Telegram contra um grupo privado real usando os tokens de bot do driver e do SUT vindos do env. - Requer `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` e `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. O id do grupo deve ser o id numérico do chat do Telegram. - - Suporta `--credential-source convex` para credenciais compartilhadas em pool. Use o modo env por padrão, ou defina `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` para optar por leases em pool. - - Requer dois bots distintos no mesmo grupo privado, com o bot SUT expondo um nome de usuário do Telegram. - - Para observação estável de bot para bot, habilite o Modo de Comunicação Bot-to-Bot no `@BotFather` para ambos os bots e garanta que o bot driver possa observar o tráfego de bots no grupo. + - Suporta `--credential-source convex` para credenciais compartilhadas em pool. Use o modo env por padrão, ou defina `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` para optar por leases compartilhados. + - Sai com código diferente de zero quando qualquer cenário falha. Use `--allow-failures` quando quiser artefatos sem um código de saída com falha. + - Requer dois bots distintos no mesmo grupo privado, com o bot do SUT expondo um nome de usuário do Telegram. + - Para observação estável de bot para bot, ative o Bot-to-Bot Communication Mode em `@BotFather` para ambos os bots e garanta que o bot driver possa observar o tráfego de bots no grupo. - Grava um relatório de QA do Telegram, resumo e artefato de mensagens observadas em `.artifacts/qa-e2e/...`. -As faixas de transporte live compartilham um contrato padrão para que novos transportes não sofram desvios: +As lanes de transporte live compartilham um contrato padrão para que novos transportes não se desviem: -`qa-channel` continua sendo a suíte ampla de QA sintético e não faz parte da matriz de cobertura de transporte live. +`qa-channel` continua sendo a suíte ampla de QA sintética e não faz parte da matriz de cobertura de transporte live. -| Faixa | Canary | Gating de menção | Bloco de allowlist | Resposta de nível superior | Retomada após reinício | Acompanhamento em thread | Isolamento de thread | Observação de reação | Comando de ajuda | -| -------- | ------ | ---------------- | ------------------ | -------------------------- | ---------------------- | ------------------------ | -------------------- | -------------------- | ---------------- | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| Lane | Canary | Gating por menção | Bloco de allowlist | Resposta de nível superior | Retomada após reinício | Follow-up em thread | Isolamento de thread | Observação de reação | Comando de ajuda | +| -------- | ------ | ----------------- | ------------------ | -------------------------- | ---------------------- | ------------------- | -------------------- | -------------------- | ---------------- | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | ### Credenciais compartilhadas do Telegram via Convex (v1) -Quando `--credential-source convex` (ou `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`) está habilitado para -`openclaw qa telegram`, o QA lab adquire um lease exclusivo de um pool com suporte do Convex, envia Heartbeat -desse lease enquanto a faixa está em execução e libera o lease no desligamento. +Quando `--credential-source convex` (ou `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`) estiver ativado para +`openclaw qa telegram`, o QA lab adquire um lease exclusivo de um pool com suporte de Convex, envia Heartbeat desse lease enquanto a lane está em execução e libera o lease ao encerrar. -Estrutura de referência do projeto Convex: +Scaffold de projeto de referência do Convex: - `qa/convex-credential-broker/` Variáveis de ambiente obrigatórias: - `OPENCLAW_QA_CONVEX_SITE_URL` (por exemplo `https://your-deployment.convex.site`) -- Um segredo para a função selecionada: +- Um segredo para o papel selecionado: - `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` para `maintainer` - `OPENCLAW_QA_CONVEX_SECRET_CI` para `ci` -- Seleção da função de credencial: +- Seleção do papel de credencial: - CLI: `--credential-role maintainer|ci` - - Padrão no env: `OPENCLAW_QA_CREDENTIAL_ROLE` (o padrão é `maintainer`) + - Padrão do env: `OPENCLAW_QA_CREDENTIAL_ROLE` (o padrão é `ci` na CI, `maintainer` caso contrário) Variáveis de ambiente opcionais: @@ -125,14 +125,14 @@ Variáveis de ambiente opcionais: - `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (padrão `15000`) - `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (padrão `/qa-credentials/v1`) - `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (id de rastreamento opcional) -- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` permite URLs Convex `http://` de loopback apenas para desenvolvimento local. +- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` permite URLs Convex `http://` em loopback para desenvolvimento apenas local. `OPENCLAW_QA_CONVEX_SITE_URL` deve usar `https://` em operação normal. -Comandos administrativos do mantenedor (adicionar/remover/listar no pool) requerem +Comandos administrativos de mantenedor (adicionar/remover/listar pool) requerem `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` especificamente. -Helpers de CLI para mantenedores: +Auxiliares de CLI para mantenedores: ```bash pnpm openclaw qa credentials add --kind telegram --payload-file qa/telegram-credential.json @@ -142,7 +142,7 @@ pnpm openclaw qa credentials remove --credential-id Use `--json` para saída legível por máquina em scripts e utilitários de CI. -Contrato padrão de endpoint (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): +Contrato padrão do endpoint (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): - `POST /acquire` - Requisição: `{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }` @@ -160,7 +160,7 @@ Contrato padrão de endpoint (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v - `POST /admin/remove` (apenas segredo de mantenedor) - Requisição: `{ credentialId, actorId }` - Sucesso: `{ status: "ok", changed, credential }` - - Proteção de lease ativo: `{ status: "error", code: "LEASE_ACTIVE", ... }` + - Proteção contra lease ativo: `{ status: "error", code: "LEASE_ACTIVE", ... }` - `POST /admin/list` (apenas segredo de mantenedor) - Requisição: `{ kind?, status?, includePayload?, limit? }` - Sucesso: `{ status: "ok", credentials, count }` @@ -168,60 +168,59 @@ Contrato padrão de endpoint (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v Formato do payload para o tipo Telegram: - `{ groupId: string, driverToken: string, sutToken: string }` -- `groupId` deve ser uma string numérica de id de chat do Telegram. +- `groupId` deve ser uma string com o id numérico do chat do Telegram. - `admin/add` valida esse formato para `kind: "telegram"` e rejeita payloads malformados. ### Adicionando um canal ao QA -Adicionar um canal ao sistema de QA em Markdown requer exatamente duas coisas: +Adicionar um canal ao sistema de QA em markdown requer exatamente duas coisas: 1. Um adaptador de transporte para o canal. 2. Um pacote de cenários que exercite o contrato do canal. -Não adicione uma nova raiz de comando de QA de nível superior quando o host compartilhado `qa-lab` puder -ser dono do fluxo. +Não adicione uma nova raiz de comando de QA de nível superior quando o host compartilhado `qa-lab` puder ser o dono do fluxo. `qa-lab` é dono da mecânica compartilhada do host: - a raiz de comando `openclaw qa` -- inicialização e desligamento da suíte +- inicialização e encerramento da suíte - concorrência de workers - gravação de artefatos - geração de relatórios - execução de cenários - aliases de compatibilidade para cenários antigos de `qa-channel` -Plugins de executor são donos do contrato de transporte: +Plugins de runner são donos do contrato de transporte: - como `openclaw qa ` é montado sob a raiz compartilhada `qa` -- como o Gateway é configurado para esse transporte +- como o gateway é configurado para esse transporte - como a prontidão é verificada - como eventos de entrada são injetados - como mensagens de saída são observadas - como transcrições e estado normalizado do transporte são expostos -- como ações com suporte do transporte são executadas -- como redefinição ou limpeza específica do transporte é tratada +- como ações com suporte de transporte são executadas +- como reset ou limpeza específicos do transporte são tratados A barra mínima de adoção para um novo canal é: 1. Manter `qa-lab` como dono da raiz compartilhada `qa`. -2. Implementar o executor de transporte na costura de host compartilhada `qa-lab`. -3. Manter a mecânica específica do transporte dentro do Plugin de executor ou do harness do Plugin. -4. Montar o executor como `openclaw qa ` em vez de registrar uma raiz de comando concorrente. - Plugins de executor devem declarar `qaRunners` em `openclaw.plugin.json` e exportar um array `qaRunnerCliRegistrations` correspondente de `runtime-api.ts`. - Mantenha `runtime-api.ts` leve; a execução lazy de CLI e de executor deve permanecer atrás de entrypoints separados. -5. Criar ou adaptar cenários Markdown nos diretórios temáticos `qa/scenarios/`. -6. Usar os helpers genéricos de cenário para novos cenários. -7. Manter funcionando os aliases de compatibilidade existentes, a menos que o repositório esteja fazendo uma migração intencional. +2. Implementar o runner de transporte no seam compartilhado do host `qa-lab`. +3. Manter mecânicas específicas de transporte dentro do plugin de runner ou do harness do canal. +4. Montar o runner como `openclaw qa ` em vez de registrar uma raiz de comando concorrente. + Plugins de runner devem declarar `qaRunners` em `openclaw.plugin.json` e exportar um array correspondente `qaRunnerCliRegistrations` de `runtime-api.ts`. + Mantenha `runtime-api.ts` leve; a execução lazy de CLI e runner deve permanecer atrás de entrypoints separados. +5. Criar ou adaptar cenários markdown nos diretórios temáticos `qa/scenarios/`. +6. Usar os auxiliares genéricos de cenário para novos cenários. +7. Manter os aliases de compatibilidade existentes funcionando, a menos que o repositório esteja fazendo uma migração intencional. A regra de decisão é estrita: -- Se o comportamento puder ser expresso uma vez em `qa-lab`, coloque-o em `qa-lab`. -- Se o comportamento depender de um transporte de canal, mantenha-o nesse Plugin de executor ou harness do Plugin. -- Se um cenário precisar de uma nova capacidade que mais de um canal possa usar, adicione um helper genérico em vez de um branch específico de canal em `suite.ts`. -- Se um comportamento só fizer sentido para um transporte, mantenha o cenário específico do transporte e deixe isso explícito no contrato do cenário. +- Se um comportamento puder ser expresso uma vez no `qa-lab`, coloque-o no `qa-lab`. +- Se um comportamento depender de um transporte de canal, mantenha-o naquele plugin de runner ou harness de plugin. +- Se um cenário precisar de uma nova capacidade que mais de um canal possa usar, adicione um auxiliar genérico em vez de um branch específico de canal em `suite.ts`. +- Se um comportamento só fizer sentido para um transporte, mantenha o cenário específico daquele transporte e deixe isso explícito no contrato do cenário. -Os nomes preferidos de helper genérico para novos cenários são: +Os nomes preferidos de auxiliares genéricos para novos cenários são: - `waitForTransportReady` - `waitForChannelReady` @@ -244,9 +243,8 @@ Aliases de compatibilidade continuam disponíveis para cenários existentes, inc - `formatConversationTranscript` - `resetBus` -Novos trabalhos de canal devem usar os nomes genéricos de helper. -Os aliases de compatibilidade existem para evitar uma migração em “flag day”, não como modelo para -a criação de novos cenários. +Novos trabalhos de canal devem usar os nomes genéricos de auxiliares. +Aliases de compatibilidade existem para evitar uma migração de uma só vez, não como modelo para criação de novos cenários. ## Suítes de teste (o que roda onde) @@ -255,147 +253,145 @@ Pense nas suítes como “realismo crescente” (e aumento de instabilidade/cust ### Unit / integration (padrão) - Comando: `pnpm test` -- Configuração: dez execuções sequenciais de shards (`vitest.full-*.config.ts`) sobre os projetos Vitest com escopo já existentes -- Arquivos: inventários core/unit em `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` e os testes node permitidos de `ui` cobertos por `vitest.unit.config.ts` +- Configuração: dez execuções sequenciais de shard (`vitest.full-*.config.ts`) sobre os projetos Vitest com escopo já existentes +- Arquivos: inventários core/unit em `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` e os testes `ui` de node permitidos cobertos por `vitest.unit.config.ts` - Escopo: - - Testes unitários puros - - Testes de integração em processo (autenticação do gateway, roteamento, ferramentas, parsing, config) + - Testes puramente unitários + - Testes de integração in-process (autenticação do gateway, roteamento, ferramentas, parsing, config) - Regressões determinísticas para bugs conhecidos - Expectativas: - - Roda no CI + - Roda na CI - Não requer chaves reais - Deve ser rápido e estável - Observação sobre projetos: - - `pnpm test` sem alvo agora executa onze configurações de shard menores (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) em vez de um único processo gigante do projeto raiz nativo. Isso reduz o pico de RSS em máquinas carregadas e evita que o trabalho de auto-reply/extensão sufoque suítes não relacionadas. - - `pnpm test --watch` ainda usa o grafo de projetos nativo da raiz em `vitest.config.ts`, porque um loop watch com múltiplos shards não é prático. - - `pnpm test`, `pnpm test:watch` e `pnpm test:perf:imports` encaminham primeiro alvos explícitos de arquivo/diretório por faixas com escopo, então `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` evita pagar o custo completo de inicialização do projeto raiz. - - `pnpm test:changed` expande caminhos alterados no git para as mesmas faixas com escopo quando o diff toca apenas arquivos de código/teste roteáveis; edições de config/setup ainda recorrem à reexecução ampla do projeto raiz. - - Testes unitários leves de importação de agents, commands, plugins, helpers de auto-reply, `plugin-sdk` e áreas utilitárias puras semelhantes passam pela faixa `unit-fast`, que ignora `test/setup-openclaw-runtime.ts`; arquivos com estado pesado/runtime permanecem nas faixas existentes. - - Alguns arquivos-fonte helper de `plugin-sdk` e `commands` também mapeiam execuções no modo changed para testes irmãos explícitos nessas faixas leves, para que edições de helpers evitem reexecutar a suíte pesada completa desse diretório. - - `auto-reply` agora tem três buckets dedicados: helpers core de nível superior, testes de integração `reply.*` de nível superior e a subárvore `src/auto-reply/reply/**`. Isso mantém o trabalho mais pesado do harness de reply fora dos testes baratos de status/chunk/token. -- Observação sobre o executor embutido: + - `pnpm test` sem alvo agora executa onze configurações menores de shard (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) em vez de um único processo root-project nativo gigante. Isso reduz o pico de RSS em máquinas carregadas e evita que o trabalho de auto-reply/extensões prejudique suítes não relacionadas. + - `pnpm test --watch` ainda usa o grafo de projeto nativo do root `vitest.config.ts`, porque um loop de watch com múltiplos shards não é prático. + - `pnpm test`, `pnpm test:watch` e `pnpm test:perf:imports` roteiam primeiro alvos explícitos de arquivo/diretório por lanes com escopo, então `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` evita o custo de inicialização do projeto root completo. + - `pnpm test:changed` expande caminhos git alterados nas mesmas lanes com escopo quando o diff toca apenas arquivos de origem/teste roteáveis; edições em config/setup ainda recorrem à reexecução ampla do projeto root. + - Testes unitários leves de importação de agents, commands, plugins, auxiliares de auto-reply, `plugin-sdk` e áreas utilitárias puras semelhantes passam pela lane `unit-fast`, que ignora `test/setup-openclaw-runtime.ts`; arquivos stateful/com runtime pesado permanecem nas lanes existentes. + - Alguns arquivos auxiliares de origem de `plugin-sdk` e `commands` também mapeiam execuções em modo changed para testes irmãos explícitos nessas lanes leves, de modo que edições em auxiliares evitam reexecutar a suíte pesada completa desse diretório. + - `auto-reply` agora tem três buckets dedicados: auxiliares core de nível superior, testes de integração `reply.*` de nível superior e a subárvore `src/auto-reply/reply/**`. Isso mantém o trabalho mais pesado do harness de reply fora dos testes baratos de status/chunk/token. +- Observação sobre embedded runner: - Quando você altera entradas de descoberta de ferramentas de mensagem ou o contexto de runtime de Compaction, mantenha ambos os níveis de cobertura. - - Adicione regressões focadas em helpers para limites puros de roteamento/normalização. - - Também mantenha saudáveis as suítes de integração do executor embutido: + - Adicione regressões focadas em auxiliares para limites puros de roteamento/normalização. + - Também mantenha saudáveis as suítes de integração do embedded runner: `src/agents/pi-embedded-runner/compact.hooks.test.ts`, `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` e `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - - Essas suítes verificam que ids com escopo e o comportamento de Compaction ainda fluem - pelos caminhos reais `run.ts` / `compact.ts`; testes apenas de helper não são um - substituto suficiente para esses caminhos de integração. + - Essas suítes verificam que ids com escopo e o comportamento de Compaction continuam fluindo pelos caminhos reais de `run.ts` / `compact.ts`; testes só de auxiliares não são um substituto suficiente para esses caminhos de integração. - Observação sobre pool: - A configuração base do Vitest agora usa `threads` por padrão. - - A configuração compartilhada do Vitest também fixa `isolate: false` e usa o executor não isolado nos projetos raiz, e2e e live. - - A faixa UI da raiz mantém sua configuração e otimizador `jsdom`, mas agora também roda no executor compartilhado não isolado. + - A configuração compartilhada do Vitest também fixa `isolate: false` e usa o runner não isolado nos projetos root, configs e2e e live. + - A lane root de UI mantém sua configuração `jsdom` e o otimizador, mas agora também roda no runner compartilhado não isolado. - Cada shard de `pnpm test` herda os mesmos padrões `threads` + `isolate: false` da configuração compartilhada do Vitest. - - O launcher compartilhado `scripts/run-vitest.mjs` agora também adiciona `--no-maglev` por padrão para processos Node filhos do Vitest, para reduzir churn de compilação do V8 durante grandes execuções locais. Defina `OPENCLAW_VITEST_ENABLE_MAGLEV=1` se precisar comparar com o comportamento padrão do V8. + - O launcher compartilhado `scripts/run-vitest.mjs` agora também adiciona `--no-maglev` por padrão aos processos Node filhos do Vitest para reduzir a agitação de compilação do V8 durante grandes execuções locais. Defina `OPENCLAW_VITEST_ENABLE_MAGLEV=1` se precisar comparar com o comportamento padrão do V8. - Observação sobre iteração local rápida: - - `pnpm test:changed` passa por faixas com escopo quando os caminhos alterados mapeiam de forma limpa para uma suíte menor. + - `pnpm test:changed` roteia por lanes com escopo quando os caminhos alterados mapeiam claramente para uma suíte menor. - `pnpm test:max` e `pnpm test:changed:max` mantêm o mesmo comportamento de roteamento, apenas com um limite maior de workers. - - O autoescalonamento local de workers agora é intencionalmente mais conservador e também recua quando a média de carga do host já está alta, para que várias execuções concorrentes do Vitest causem menos impacto por padrão. - - A configuração base do Vitest marca os arquivos de projetos/configuração como `forceRerunTriggers` para que reexecuções no modo changed permaneçam corretas quando o wiring dos testes muda. - - A configuração mantém `OPENCLAW_VITEST_FS_MODULE_CACHE` habilitado em hosts compatíveis; defina `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` se quiser um local de cache explícito para profiling direto. -- Observação de depuração de performance: - - `pnpm test:perf:imports` habilita o relatório de duração de importação do Vitest mais a saída de detalhamento de importações. + - O autoescalonamento local de workers agora é intencionalmente conservador e também reduz quando a média de carga do host já está alta, para que múltiplas execuções simultâneas do Vitest causem menos impacto por padrão. + - A configuração base do Vitest marca os arquivos de projetos/config como `forceRerunTriggers` para que reexecuções em modo changed continuem corretas quando a fiação de testes mudar. + - A configuração mantém `OPENCLAW_VITEST_FS_MODULE_CACHE` ativado em hosts compatíveis; defina `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path` se quiser um local de cache explícito para profiling direto. +- Observação sobre depuração de performance: + - `pnpm test:perf:imports` ativa relatórios de duração de importação do Vitest mais a saída de detalhamento de importações. - `pnpm test:perf:imports:changed` aplica a mesma visão de profiling aos arquivos alterados desde `origin/main`. -- `pnpm test:perf:changed:bench -- --ref ` compara `test:changed` roteado com o caminho nativo do projeto raiz para esse diff commitado e imprime tempo total mais RSS máximo no macOS. -- `pnpm test:perf:changed:bench -- --worktree` faz benchmark da árvore suja atual roteando a lista de arquivos alterados por `scripts/test-projects.mjs` e pela configuração raiz do Vitest. - - `pnpm test:perf:profile:main` grava um perfil de CPU da thread principal para overhead de inicialização e transformação do Vitest/Vite. - - `pnpm test:perf:profile:runner` grava perfis de CPU+heap do executor para a suíte unit com paralelismo de arquivos desabilitado. +- `pnpm test:perf:changed:bench -- --ref ` compara `test:changed` roteado com o caminho nativo do projeto root para esse diff commitado e imprime tempo total mais RSS máximo no macOS. +- `pnpm test:perf:changed:bench -- --worktree` faz benchmark da árvore suja atual roteando a lista de arquivos alterados por `scripts/test-projects.mjs` e a configuração root do Vitest. + - `pnpm test:perf:profile:main` grava um perfil de CPU da thread principal para overhead de startup e transformação do Vitest/Vite. + - `pnpm test:perf:profile:runner` grava perfis de CPU+heap do runner para a suíte unit com paralelismo de arquivos desativado. -### E2E (teste de fumaça do gateway) +### E2E (smoke do gateway) - Comando: `pnpm test:e2e` - Configuração: `vitest.e2e.config.ts` - Arquivos: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` - Padrões de runtime: - - Usa `threads` do Vitest com `isolate: false`, em linha com o restante do repositório. + - Usa `threads` do Vitest com `isolate: false`, alinhado com o restante do repositório. - Usa workers adaptativos (CI: até 2, local: 1 por padrão). - - Roda em modo silencioso por padrão para reduzir o overhead de I/O no console. + - Roda em modo silencioso por padrão para reduzir o overhead de E/S do console. - Substituições úteis: - - `OPENCLAW_E2E_WORKERS=` para forçar a contagem de workers (limitada a 16). - - `OPENCLAW_E2E_VERBOSE=1` para reabilitar a saída verbosa no console. + - `OPENCLAW_E2E_WORKERS=` para forçar a quantidade de workers (limitada a 16). + - `OPENCLAW_E2E_VERBOSE=1` para reativar a saída detalhada do console. - Escopo: - - Comportamento end-to-end do gateway com múltiplas instâncias - - Superfícies WebSocket/HTTP, pareamento de nós e networking mais pesado + - Comportamento end-to-end de gateway com múltiplas instâncias + - Superfícies WebSocket/HTTP, emparelhamento de Node e rede mais pesada - Expectativas: - - Roda no CI (quando habilitado no pipeline) + - Roda na CI (quando ativado no pipeline) - Não requer chaves reais - - Tem mais partes móveis que testes unitários (pode ser mais lento) + - Tem mais partes móveis do que testes unitários (pode ser mais lento) -### E2E: teste de fumaça do backend OpenShell +### E2E: smoke do backend OpenShell - Comando: `pnpm test:e2e:openshell` - Arquivo: `test/openshell-sandbox.e2e.test.ts` - Escopo: - Inicia um gateway OpenShell isolado no host via Docker - Cria um sandbox a partir de um Dockerfile local temporário - - Exercita o backend OpenShell do OpenClaw sobre `sandbox ssh-config` real + execução por SSH - - Verifica o comportamento canônico remoto do sistema de arquivos por meio da ponte fs do sandbox + - Exercita o backend OpenShell do OpenClaw por `sandbox ssh-config` + execução SSH reais + - Verifica o comportamento canônico remoto do sistema de arquivos por meio da bridge fs do sandbox - Expectativas: - Opt-in apenas; não faz parte da execução padrão de `pnpm test:e2e` - Requer um CLI `openshell` local mais um daemon Docker funcional - - Usa `HOME` / `XDG_CONFIG_HOME` isolados, depois destrói o gateway e o sandbox de teste + - Usa `HOME` / `XDG_CONFIG_HOME` isolados e depois destrói o gateway e sandbox de teste - Substituições úteis: - - `OPENCLAW_E2E_OPENSHELL=1` para habilitar o teste ao executar manualmente a suíte e2e mais ampla - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` para apontar para um binário CLI ou script wrapper fora do padrão + - `OPENCLAW_E2E_OPENSHELL=1` para ativar o teste ao executar manualmente a suíte e2e mais ampla + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` para apontar para um binário CLI não padrão ou script wrapper ### Live (provedores reais + modelos reais) - Comando: `pnpm test:live` - Configuração: `vitest.live.config.ts` - Arquivos: `src/**/*.live.test.ts` -- Padrão: **habilitado** por `pnpm test:live` (define `OPENCLAW_LIVE_TEST=1`) +- Padrão: **ativado** por `pnpm test:live` (define `OPENCLAW_LIVE_TEST=1`) - Escopo: - - “Esse provedor/modelo realmente funciona _hoje_ com credenciais reais?” - - Capturar mudanças de formato do provedor, peculiaridades de chamada de ferramentas, problemas de autenticação e comportamento de rate limit + - “Este provedor/modelo realmente funciona _hoje_ com credenciais reais?” + - Capturar mudanças de formato de provedor, peculiaridades de tool calling, problemas de autenticação e comportamento de limite de taxa - Expectativas: - - Não é estável em CI por definição (redes reais, políticas reais de provedor, cotas, indisponibilidades) - - Custa dinheiro / consome rate limits + - Não é estável em CI por design (redes reais, políticas reais de provedor, cotas, indisponibilidades) + - Custa dinheiro / usa limites de taxa - Prefira executar subconjuntos reduzidos em vez de “tudo” -- Execuções live leem `~/.profile` para obter chaves de API ausentes. -- Por padrão, execuções live ainda isolam `HOME` e copiam material de config/auth para uma home temporária de teste, para que fixtures unitárias não possam alterar seu `~/.openclaw` real. -- Defina `OPENCLAW_LIVE_USE_REAL_HOME=1` apenas quando quiser intencionalmente que os testes live usem seu diretório home real. -- `pnpm test:live` agora usa por padrão um modo mais silencioso: mantém a saída de progresso `[live] ...`, mas suprime o aviso extra de `~/.profile` e silencia logs de bootstrap do gateway/chatter do Bonjour. Defina `OPENCLAW_LIVE_TEST_QUIET=0` se quiser recuperar os logs completos de inicialização. -- Rotação de chave de API (específica por provedor): defina `*_API_KEYS` com formato separado por vírgula/ponto e vírgula ou `*_API_KEY_1`, `*_API_KEY_2` (por exemplo `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) ou use a substituição por live `OPENCLAW_LIVE_*_KEY`; os testes tentam novamente em respostas de rate limit. +- Execuções live carregam `~/.profile` para obter chaves de API ausentes. +- Por padrão, execuções live ainda isolam `HOME` e copiam material de config/auth para um home temporário de teste, para que fixtures unitárias não possam alterar seu `~/.openclaw` real. +- Defina `OPENCLAW_LIVE_USE_REAL_HOME=1` apenas quando quiser intencionalmente que testes live usem seu diretório home real. +- `pnpm test:live` agora usa por padrão um modo mais silencioso: mantém a saída de progresso `[live] ...`, mas oculta o aviso extra de `~/.profile` e silencia logs de bootstrap do gateway/chatter Bonjour. Defina `OPENCLAW_LIVE_TEST_QUIET=0` se quiser de volta os logs completos de inicialização. +- Rotação de chaves de API (específica por provedor): defina `*_API_KEYS` com formato separado por vírgula/ponto e vírgula ou `*_API_KEY_1`, `*_API_KEY_2` (por exemplo `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) ou substituição por live via `OPENCLAW_LIVE_*_KEY`; os testes tentam novamente em respostas de limite de taxa. - Saída de progresso/Heartbeat: - - Suítes live agora emitem linhas de progresso em stderr para que chamadas longas de provedor permaneçam visivelmente ativas mesmo quando a captura de console do Vitest está silenciosa. - - `vitest.live.config.ts` desabilita a interceptação de console do Vitest para que linhas de progresso de provedor/gateway sejam transmitidas imediatamente durante execuções live. + - As suítes live agora emitem linhas de progresso em stderr para que chamadas longas ao provedor mostrem atividade visível mesmo quando a captura de console do Vitest está silenciosa. + - `vitest.live.config.ts` desativa a interceptação de console do Vitest para que linhas de progresso do provedor/gateway sejam transmitidas imediatamente durante execuções live. - Ajuste Heartbeats de modelo direto com `OPENCLAW_LIVE_HEARTBEAT_MS`. - Ajuste Heartbeats de gateway/sonda com `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. -## Qual suíte eu devo executar? +## Qual suíte devo executar? Use esta tabela de decisão: -- Editando lógica/testes: execute `pnpm test` (e `pnpm test:coverage` se você mudou bastante coisa) -- Alterando networking do gateway / protocolo WS / pareamento: adicione `pnpm test:e2e` -- Depurando “meu bot caiu” / falhas específicas de provedor / chamada de ferramentas: execute um `pnpm test:live` reduzido +- Editando lógica/testes: execute `pnpm test` (e `pnpm test:coverage` se mudou muita coisa) +- Alterando rede do gateway / protocolo WS / emparelhamento: adicione `pnpm test:e2e` +- Depurando “meu bot caiu” / falhas específicas de provedor / tool calling: execute um `pnpm test:live` reduzido ## Live: varredura de capacidades de Node Android - Teste: `src/gateway/android-node.capabilities.live.test.ts` - Script: `pnpm android:test:integration` -- Objetivo: invocar **todos os comandos atualmente anunciados** por um Node Android conectado e verificar o comportamento contratual dos comandos. +- Objetivo: invocar **todo comando atualmente anunciado** por um Node Android conectado e validar o comportamento do contrato de comando. - Escopo: - - Pré-condicionado/configuração manual (a suíte não instala/executa/pareia o app). - - Validação `node.invoke` do gateway comando por comando para o Node Android selecionado. -- Pré-configuração obrigatória: - - App Android já conectado + pareado ao gateway. + - Setup manual/com pré-condições (a suíte não instala/executa/emparelha o app). + - Validação `node.invoke` do gateway, comando por comando, para o Node Android selecionado. +- Pré-setup obrigatório: + - App Android já conectado e emparelhado ao gateway. - App mantido em primeiro plano. - Permissões/consentimento de captura concedidos para as capacidades que você espera que passem. - Substituições opcionais de alvo: - `OPENCLAW_ANDROID_NODE_ID` ou `OPENCLAW_ANDROID_NODE_NAME`. - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`. -- Detalhes completos de configuração do Android: [App Android](/pt-BR/platforms/android) +- Detalhes completos de setup do Android: [App Android](/pt-BR/platforms/android) -## Live: teste de fumaça de modelo (chaves de perfil) +## Live: smoke de modelo (chaves de perfil) -Os testes live são divididos em duas camadas para que possamos isolar falhas: +Os testes live são divididos em duas camadas para podermos isolar falhas: -- “Modelo direto” nos informa se o provedor/modelo consegue responder com a chave informada. -- “Teste de fumaça do gateway” nos informa se o pipeline completo gateway+agente funciona para esse modelo (sessões, histórico, ferramentas, política de sandbox etc.). +- “Modelo direto” nos diz se o provedor/modelo consegue responder com aquela chave. +- “Smoke do gateway” nos diz se o pipeline completo de gateway+agente funciona para aquele modelo (sessões, histórico, ferramentas, política de sandbox etc.). ### Camada 1: conclusão direta do modelo (sem gateway) @@ -404,57 +400,57 @@ Os testes live são divididos em duas camadas para que possamos isolar falhas: - Enumerar modelos descobertos - Usar `getApiKeyForModel` para selecionar modelos para os quais você tem credenciais - Executar uma pequena conclusão por modelo (e regressões direcionadas quando necessário) -- Como habilitar: +- Como ativar: - `pnpm test:live` (ou `OPENCLAW_LIVE_TEST=1` se estiver invocando o Vitest diretamente) -- Defina `OPENCLAW_LIVE_MODELS=modern` (ou `all`, alias para modern) para realmente executar esta suíte; caso contrário, ela é ignorada para manter `pnpm test:live` focado no teste de fumaça do gateway +- Defina `OPENCLAW_LIVE_MODELS=modern` (ou `all`, alias para modern) para realmente executar esta suíte; caso contrário, ela é ignorada para manter `pnpm test:live` focado no smoke do gateway - Como selecionar modelos: - `OPENCLAW_LIVE_MODELS=modern` para executar a allowlist moderna (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - `OPENCLAW_LIVE_MODELS=all` é um alias para a allowlist moderna - ou `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (allowlist separada por vírgulas) - - Varreduras modern/all usam por padrão um limite curado de alto sinal; defina `OPENCLAW_LIVE_MAX_MODELS=0` para uma varredura moderna exaustiva ou um número positivo para um limite menor. + - As varreduras modern/all usam por padrão um limite selecionado de alto sinal; defina `OPENCLAW_LIVE_MAX_MODELS=0` para uma varredura moderna exaustiva ou um número positivo para um limite menor. - Como selecionar provedores: - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist separada por vírgulas) - De onde vêm as chaves: - - Por padrão: armazenamento de perfil e fallbacks de env - - Defina `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para exigir **apenas** o armazenamento de perfil + - Por padrão: armazenamento de perfis e fallbacks de env + - Defina `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para exigir **somente armazenamento de perfis** - Por que isso existe: - Separa “a API do provedor está quebrada / a chave é inválida” de “o pipeline do agente do gateway está quebrado” - - Contém regressões pequenas e isoladas (exemplo: replay de reasoning do OpenAI Responses/Codex Responses + fluxos de chamada de ferramenta) + - Contém regressões pequenas e isoladas (exemplo: fluxos de replay de reasoning + tool-call do OpenAI Responses/Codex Responses) -### Camada 2: teste de fumaça do Gateway + agente dev (o que `@openclaw` realmente faz) +### Camada 2: smoke do Gateway + agente dev (o que o "@openclaw" realmente faz) - Teste: `src/gateway/gateway-models.profiles.live.test.ts` - Objetivo: - - Subir um gateway em processo - - Criar/atualizar uma sessão `agent:dev:*` (substituição de modelo por execução) - - Iterar por modelos com chaves e verificar: + - Subir um gateway in-process + - Criar/aplicar patch em uma sessão `agent:dev:*` (substituição de modelo por execução) + - Iterar modelos-com-chaves e validar: - resposta “significativa” (sem ferramentas) - uma invocação real de ferramenta funciona (sonda de leitura) - sondas opcionais extras de ferramenta (sonda exec+read) - - caminhos de regressão do OpenAI (somente chamada de ferramenta → continuação) continuam funcionando + - caminhos de regressão do OpenAI (somente tool-call → follow-up) continuam funcionando - Detalhes das sondas (para que você possa explicar falhas rapidamente): - sonda `read`: o teste grava um arquivo nonce no workspace e pede ao agente para `read` esse arquivo e retornar o nonce. - - sonda `exec+read`: o teste pede ao agente para gravar um nonce em um arquivo temporário com `exec` e depois lê-lo de volta com `read`. + - sonda `exec+read`: o teste pede ao agente para gravar um nonce em um arquivo temporário com `exec` e depois fazer `read` dele. - sonda de imagem: o teste anexa um PNG gerado (gato + código aleatório) e espera que o modelo retorne `cat `. - Referência de implementação: `src/gateway/gateway-models.profiles.live.test.ts` e `src/gateway/live-image-probe.ts`. -- Como habilitar: +- Como ativar: - `pnpm test:live` (ou `OPENCLAW_LIVE_TEST=1` se estiver invocando o Vitest diretamente) - Como selecionar modelos: - Padrão: allowlist moderna (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - `OPENCLAW_LIVE_GATEWAY_MODELS=all` é um alias para a allowlist moderna - Ou defina `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (ou lista separada por vírgulas) para restringir - - Varreduras modern/all do gateway usam por padrão um limite curado de alto sinal; defina `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` para uma varredura moderna exaustiva ou um número positivo para um limite menor. -- Como selecionar provedores (evite “tudo do OpenRouter”): + - As varreduras de gateway modern/all usam por padrão um limite selecionado de alto sinal; defina `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` para uma varredura moderna exaustiva ou um número positivo para um limite menor. +- Como selecionar provedores (evite “OpenRouter tudo”): - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist separada por vírgulas) -- As sondas de ferramenta + imagem estão sempre ativas neste teste live: - - sonda `read` + sonda `exec+read` (estresse de ferramenta) - - a sonda de imagem roda quando o modelo anuncia suporte a entrada de imagem +- Sondas de ferramenta + imagem estão sempre ativadas neste teste live: + - sonda `read` + sonda `exec+read` (stress de ferramenta) + - a sonda de imagem é executada quando o modelo anuncia suporte a entrada de imagem - Fluxo (alto nível): - O teste gera um pequeno PNG com “CAT” + código aleatório (`src/gateway/live-image-probe.ts`) - Envia via `agent` `attachments: [{ mimeType: "image/png", content: "" }]` - - O Gateway faz o parse dos anexos em `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) - - O agente embutido encaminha uma mensagem de usuário multimodal ao modelo - - Verificação: a resposta contém `cat` + o código (tolerância de OCR: pequenos erros são permitidos) + - O Gateway analisa anexos em `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) + - O agente embarcado encaminha uma mensagem multimodal do usuário para o modelo + - Validação: a resposta contém `cat` + o código (tolerância de OCR: pequenos erros são permitidos) Dica: para ver o que você pode testar na sua máquina (e os ids exatos `provider/model`), execute: @@ -463,26 +459,26 @@ openclaw models list openclaw models list --json ``` -## Live: teste de fumaça do backend CLI (Claude, Codex, Gemini ou outros CLIs locais) +## Live: smoke de backend CLI (Claude, Codex, Gemini ou outros CLIs locais) - Teste: `src/gateway/gateway-cli-backend.live.test.ts` - Objetivo: validar o pipeline Gateway + agente usando um backend CLI local, sem tocar na sua config padrão. -- Os padrões de teste de fumaça específicos do backend ficam na definição `cli-backend.ts` da extensão proprietária. -- Habilitar: +- Os padrões de smoke específicos de backend ficam na definição `cli-backend.ts` da extensão proprietária. +- Ativar: - `pnpm test:live` (ou `OPENCLAW_LIVE_TEST=1` se estiver invocando o Vitest diretamente) - `OPENCLAW_LIVE_CLI_BACKEND=1` - Padrões: - Provedor/modelo padrão: `claude-cli/claude-sonnet-4-6` - - O comportamento de comando/args/imagem vem dos metadados do Plugin de backend CLI proprietário. -- Substituições (opcionais): + - O comportamento de comando/args/imagem vem dos metadados do plugin proprietário do backend CLI. +- Substituições opcionais: - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"` - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"` - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'` - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` para enviar um anexo de imagem real (os caminhos são injetados no prompt). - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` para passar caminhos de arquivo de imagem como args da CLI em vez de injeção no prompt. - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (ou `"list"`) para controlar como args de imagem são passados quando `IMAGE_ARG` está definido. - - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` para enviar uma segunda rodada e validar o fluxo de retomada. - - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` para desabilitar a sonda padrão de continuidade na mesma sessão Claude Sonnet -> Opus (defina `1` para forçá-la quando o modelo selecionado suportar um alvo de troca). + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` para passar caminhos de arquivos de imagem como args de CLI em vez de injeção no prompt. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (ou `"list"`) para controlar como os args de imagem são passados quando `IMAGE_ARG` está definido. + - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` para enviar um segundo turno e validar o fluxo de retomada. + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` para desativar a sonda padrão de continuidade na mesma sessão de Claude Sonnet -> Opus (defina `1` para forçar a ativação quando o modelo selecionado suportar um alvo de troca). Exemplo: @@ -509,22 +505,22 @@ pnpm test:docker:live-cli-backend:gemini Observações: -- O executor Docker fica em `scripts/test-live-cli-backend-docker.sh`. -- Ele executa o teste de fumaça live do backend CLI dentro da imagem Docker do repositório como o usuário não root `node`. -- Ele resolve os metadados do teste de fumaça da CLI a partir da extensão proprietária e então instala o pacote Linux CLI correspondente (`@anthropic-ai/claude-code`, `@openai/codex` ou `@google/gemini-cli`) em um prefixo gravável em cache em `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (padrão: `~/.cache/openclaw/docker-cli-tools`). -- `pnpm test:docker:live-cli-backend:claude-subscription` requer OAuth portátil de assinatura do Claude Code por meio de `~/.claude/.credentials.json` com `claudeAiOauth.subscriptionType` ou `CLAUDE_CODE_OAUTH_TOKEN` de `claude setup-token`. Primeiro ele prova `claude -p` direto no Docker, depois executa duas rodadas do backend CLI do Gateway sem preservar variáveis de ambiente de chave de API da Anthropic. Essa faixa de assinatura desabilita por padrão as sondas de ferramenta MCP e imagem do Claude porque o Claude atualmente roteia o uso de aplicativos de terceiros por cobrança de uso extra em vez dos limites normais do plano de assinatura. -- O teste de fumaça live do backend CLI agora exercita o mesmo fluxo end-to-end para Claude, Codex e Gemini: rodada de texto, rodada de classificação de imagem e depois chamada da ferramenta MCP `cron`, verificada pela CLI do gateway. -- O teste de fumaça padrão do Claude também atualiza a sessão de Sonnet para Opus e verifica que a sessão retomada ainda se lembra de uma observação anterior. +- O executor Docker está em `scripts/test-live-cli-backend-docker.sh`. +- Ele executa o smoke live de backend CLI dentro da imagem Docker do repositório como o usuário não root `node`. +- Ele resolve os metadados de smoke da CLI a partir da extensão proprietária e então instala o pacote CLI Linux correspondente (`@anthropic-ai/claude-code`, `@openai/codex` ou `@google/gemini-cli`) em um prefixo gravável em cache em `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (padrão: `~/.cache/openclaw/docker-cli-tools`). +- `pnpm test:docker:live-cli-backend:claude-subscription` requer OAuth portátil de assinatura do Claude Code por meio de `~/.claude/.credentials.json` com `claudeAiOauth.subscriptionType` ou `CLAUDE_CODE_OAUTH_TOKEN` de `claude setup-token`. Primeiro ele comprova `claude -p` direto no Docker, depois executa dois turnos do Gateway CLI-backend sem preservar variáveis de ambiente de chave de API da Anthropic. Esta lane de assinatura desativa por padrão as sondas MCP/ferramenta e imagem do Claude porque o Claude atualmente roteia o uso de apps de terceiros por cobrança de uso extra em vez dos limites normais do plano de assinatura. +- O smoke live de backend CLI agora exercita o mesmo fluxo end-to-end para Claude, Codex e Gemini: turno de texto, turno de classificação de imagem e depois chamada da ferramenta MCP `cron` verificada pelo gateway CLI. +- O smoke padrão do Claude também aplica patch na sessão de Sonnet para Opus e verifica que a sessão retomada ainda se lembra de uma anotação anterior. -## Live: teste de fumaça de bind ACP (`/acp spawn ... --bind here`) +## Live: smoke de bind ACP (`/acp spawn ... --bind here`) - Teste: `src/gateway/gateway-acp-bind.live.test.ts` - Objetivo: validar o fluxo real de bind de conversa ACP com um agente ACP live: - enviar `/acp spawn --bind here` - - vincular in-place uma conversa sintética de canal de mensagem - - enviar uma continuação normal nessa mesma conversa - - verificar que a continuação chega na transcrição da sessão ACP vinculada -- Habilitar: + - vincular uma conversa sintética de canal de mensagens no lugar + - enviar um follow-up normal nessa mesma conversa + - verificar que o follow-up chega na transcrição da sessão ACP vinculada +- Ativar: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` - Padrões: @@ -539,8 +535,8 @@ Observações: - `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude,codex,gemini` - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'` - Observações: - - Essa faixa usa a superfície `chat.send` do gateway com campos sintéticos de rota de origem apenas para admin, para que os testes possam anexar contexto de canal de mensagem sem fingir entrega externa. - - Quando `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` não está definido, o teste usa o registro embutido de agentes do Plugin `acpx` embutido para o agente de harness ACP selecionado. + - Esta lane usa a superfície `chat.send` do gateway com campos admin-only sintéticos de originating-route para que os testes possam anexar contexto de canal de mensagens sem fingir entrega externa. + - Quando `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` não está definido, o teste usa o registro de agentes embutido do plugin `acpx` incorporado para o agente de harness ACP selecionado. Exemplo: @@ -566,31 +562,31 @@ pnpm test:docker:live-acp-bind:gemini Observações sobre Docker: -- O executor Docker fica em `scripts/test-live-acp-bind-docker.sh`. -- Por padrão, ele executa o teste de fumaça de bind ACP contra todos os agentes CLI live suportados em sequência: `claude`, `codex` e depois `gemini`. +- O executor Docker está em `scripts/test-live-acp-bind-docker.sh`. +- Por padrão, ele executa o smoke de bind ACP contra todos os agentes CLI live suportados em sequência: `claude`, `codex`, depois `gemini`. - Use `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` ou `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` para restringir a matriz. -- Ele lê `~/.profile`, prepara o material de autenticação CLI correspondente dentro do contêiner, instala `acpx` em um prefixo npm gravável e então instala a CLI live solicitada (`@anthropic-ai/claude-code`, `@openai/codex` ou `@google/gemini-cli`) se ela estiver ausente. +- Ele carrega `~/.profile`, prepara o material de autenticação da CLI correspondente dentro do contêiner, instala `acpx` em um prefixo npm gravável e então instala a CLI live solicitada (`@anthropic-ai/claude-code`, `@openai/codex` ou `@google/gemini-cli`) se estiver ausente. - Dentro do Docker, o executor define `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx` para que o acpx mantenha disponíveis para a CLI filha do harness as variáveis de ambiente do provedor vindas do profile carregado. -## Live: teste de fumaça do harness app-server do Codex +## Live: smoke do harness app-server do Codex -- Objetivo: validar o harness do Codex pertencente ao Plugin por meio do método +- Objetivo: validar o harness do Codex pertencente ao plugin por meio do método `agent` normal do gateway: - - carregar o Plugin `codex` empacotado + - carregar o plugin `codex` empacotado - selecionar `OPENCLAW_AGENT_RUNTIME=codex` - - enviar uma primeira rodada do agente do gateway para `codex/gpt-5.4` - - enviar uma segunda rodada para a mesma sessão OpenClaw e verificar se a thread do app-server - pode ser retomada - - executar `/codex status` e `/codex models` pelo mesmo caminho de - comando do gateway + - enviar um primeiro turno do agente do gateway para `codex/gpt-5.4` + - enviar um segundo turno para a mesma sessão do OpenClaw e verificar se a thread + do app-server consegue ser retomada + - executar `/codex status` e `/codex models` pelo mesmo caminho de comando + do gateway - Teste: `src/gateway/gateway-codex-harness.live.test.ts` -- Habilitar: `OPENCLAW_LIVE_CODEX_HARNESS=1` +- Ativar: `OPENCLAW_LIVE_CODEX_HARNESS=1` - Modelo padrão: `codex/gpt-5.4` -- Sonda de imagem opcional: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` -- Sonda MCP/ferramenta opcional: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` -- O teste de fumaça define `OPENCLAW_AGENT_HARNESS_FALLBACK=none` para que um harness Codex - quebrado não possa passar silenciosamente ao fazer fallback para PI. -- Autenticação: `OPENAI_API_KEY` do shell/profile, mais opcionais copiados +- Sonda opcional de imagem: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` +- Sonda opcional de MCP/ferramenta: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` +- O smoke define `OPENCLAW_AGENT_HARNESS_FALLBACK=none` para que um harness + Codex quebrado não passe ao recorrer silenciosamente ao PI. +- Auth: `OPENAI_API_KEY` do shell/profile, além de cópias opcionais de `~/.codex/auth.json` e `~/.codex/config.toml` Receita local: @@ -614,15 +610,14 @@ pnpm test:docker:live-codex-harness Observações sobre Docker: - O executor Docker fica em `scripts/test-live-codex-harness-docker.sh`. -- Ele lê o `~/.profile` montado, passa `OPENAI_API_KEY`, copia arquivos de autenticação da CLI do Codex - quando presentes, instala `@openai/codex` em um prefixo npm montado e gravável, - prepara a árvore de código-fonte e então executa apenas o teste live do harness do Codex. -- O Docker habilita por padrão as sondas de imagem e MCP/ferramenta. Defina +- Ele carrega o `~/.profile` montado, passa `OPENAI_API_KEY`, copia arquivos de + auth da CLI Codex quando presentes, instala `@openai/codex` em um prefixo npm + gravável montado, prepara a árvore de código-fonte e então executa apenas o teste live do harness Codex. +- O Docker ativa por padrão as sondas de imagem e MCP/ferramenta. Defina `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` ou `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` quando precisar de uma execução de depuração mais restrita. -- O Docker também exporta `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, em linha com a configuração do - teste live, para que o fallback `openai-codex/*` ou PI não possa ocultar uma regressão do - harness do Codex. +- O Docker também exporta `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, alinhado com a configuração + do teste live para que o fallback para `openai-codex/*` ou PI não possa ocultar uma regressão no harness Codex. ### Receitas live recomendadas @@ -631,13 +626,13 @@ Allowlists estreitas e explícitas são mais rápidas e menos instáveis: - Modelo único, direto (sem gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` -- Modelo único, teste de fumaça do gateway: +- Modelo único, smoke do gateway: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Chamada de ferramentas em vários provedores: +- Tool calling em vários provedores: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Foco em Google (chave da API Gemini + Antigravity): +- Foco em Google (chave de API do Gemini + Antigravity): - Gemini (chave de API): `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Antigravity (OAuth): `OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` @@ -645,16 +640,16 @@ Observações: - `google/...` usa a API Gemini (chave de API). - `google-antigravity/...` usa a ponte OAuth Antigravity (endpoint de agente no estilo Cloud Code Assist). -- `google-gemini-cli/...` usa a CLI Gemini local na sua máquina (autenticação separada + peculiaridades de ferramentas). +- `google-gemini-cli/...` usa a CLI local do Gemini na sua máquina (auth separado + peculiaridades de ferramentas). - API Gemini vs CLI Gemini: - - API: o OpenClaw chama a API Gemini hospedada do Google via HTTP (autenticação por chave de API / perfil); é isso que a maioria dos usuários quer dizer com “Gemini”. - - CLI: o OpenClaw executa um binário local `gemini`; ele tem sua própria autenticação e pode se comportar de maneira diferente (streaming/suporte a ferramentas/desalinhamento de versão). + - API: o OpenClaw chama a API Gemini hospedada pelo Google via HTTP (auth por chave de API / perfil); é isso que a maioria dos usuários quer dizer com “Gemini”. + - CLI: o OpenClaw executa um binário local `gemini`; ele tem sua própria auth e pode se comportar de forma diferente (streaming/suporte a ferramentas/diferenças de versão). ## Live: matriz de modelos (o que cobrimos) -Não há uma “lista fixa de modelos do CI” (live é opt-in), mas estes são os modelos **recomendados** para cobrir regularmente em uma máquina de desenvolvimento com chaves. +Não existe uma “lista de modelos de CI” fixa (live é opt-in), mas estes são os modelos **recomendados** para cobrir regularmente em uma máquina de desenvolvimento com chaves. -### Conjunto moderno de smoke (chamada de ferramentas + imagem) +### Conjunto de smoke moderno (tool calling + imagem) Esta é a execução de “modelos comuns” que esperamos manter funcionando: @@ -666,10 +661,10 @@ Esta é a execução de “modelos comuns” que esperamos manter funcionando: - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Execute o teste de fumaça do gateway com ferramentas + imagem: +Execute o smoke do gateway com ferramentas + imagem: `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -### Baseline: chamada de ferramentas (Read + Exec opcional) +### Base: tool calling (Read + Exec opcional) Escolha pelo menos um por família de provedor: @@ -681,28 +676,28 @@ Escolha pelo menos um por família de provedor: Cobertura adicional opcional (bom ter): -- xAI: `xai/grok-4` (ou a mais recente disponível) -- Mistral: `mistral/`… (escolha um modelo com capacidade de `tools` que você tenha habilitado) +- xAI: `xai/grok-4` (ou a versão mais recente disponível) +- Mistral: `mistral/`… (escolha um modelo com capacidade de ferramentas que você tenha habilitado) - Cerebras: `cerebras/`… (se você tiver acesso) -- LM Studio: `lmstudio/`… (local; a chamada de ferramentas depende do modo da API) +- LM Studio: `lmstudio/`… (local; o tool calling depende do modo da API) -### Vision: envio de imagem (anexo → mensagem multimodal) +### Visão: envio de imagem (anexo → mensagem multimodal) -Inclua pelo menos um modelo com capacidade de imagem em `OPENCLAW_LIVE_GATEWAY_MODELS` (variantes com suporte a visão do Claude/Gemini/OpenAI etc.) para exercitar a sonda de imagem. +Inclua pelo menos um modelo com capacidade de imagem em `OPENCLAW_LIVE_GATEWAY_MODELS` (variantes com visão de Claude/Gemini/OpenAI etc.) para exercitar a sonda de imagem. ### Agregadores / gateways alternativos Se você tiver chaves habilitadas, também oferecemos suporte a testes via: -- OpenRouter: `openrouter/...` (centenas de modelos; use `openclaw models scan` para encontrar candidatos com suporte a ferramenta+imagem) -- OpenCode: `opencode/...` para Zen e `opencode-go/...` para Go (autenticação via `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) +- OpenRouter: `openrouter/...` (centenas de modelos; use `openclaw models scan` para encontrar candidatos com capacidade de ferramenta+imagem) +- OpenCode: `opencode/...` para Zen e `opencode-go/...` para Go (auth via `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) Mais provedores que você pode incluir na matriz live (se tiver credenciais/config): -- Embutidos: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot` +- Integrados: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot` - Via `models.providers` (endpoints personalizados): `minimax` (cloud/API), além de qualquer proxy compatível com OpenAI/Anthropic (LM Studio, vLLM, LiteLLM etc.) -Dica: não tente codificar “todos os modelos” na documentação. A lista autoritativa é tudo o que `discoverModels(...)` retornar na sua máquina + quaisquer chaves disponíveis. +Dica: não tente fixar “todos os modelos” na documentação. A lista autoritativa é o que `discoverModels(...)` retorna na sua máquina + quaisquer chaves disponíveis. ## Credenciais (nunca faça commit) @@ -711,32 +706,32 @@ Os testes live descobrem credenciais da mesma forma que a CLI. Implicações pr - Se a CLI funciona, os testes live devem encontrar as mesmas chaves. - Se um teste live disser “sem credenciais”, depure da mesma forma que você depuraria `openclaw models list` / seleção de modelo. -- Perfis de autenticação por agente: `~/.openclaw/agents//agent/auth-profiles.json` (é isso que “chaves de perfil” significa nos testes live) +- Perfis de auth por agente: `~/.openclaw/agents//agent/auth-profiles.json` (é isso que “chaves de perfil” significa nos testes live) - Config: `~/.openclaw/openclaw.json` (ou `OPENCLAW_CONFIG_PATH`) -- Diretório de estado legado: `~/.openclaw/credentials/` (copiado para a home live preparada quando presente, mas não é o armazenamento principal de chaves de perfil) -- Execuções live locais copiam por padrão a configuração ativa, arquivos `auth-profiles.json` por agente, `credentials/` legados e diretórios de autenticação de CLI externa suportados para uma home temporária de teste; as homes live preparadas ignoram `workspace/` e `sandboxes/`, e substituições de caminho `agents.*.workspace` / `agentDir` são removidas para que as sondas fiquem fora do seu workspace real do host. +- Diretório de estado legado: `~/.openclaw/credentials/` (copiado para o home live preparado quando presente, mas não é o armazenamento principal de chaves de perfil) +- Execuções locais live copiam por padrão a config ativa, arquivos `auth-profiles.json` por agente, `credentials/` legado e diretórios externos de auth de CLI suportados para um home temporário de teste; homes live preparados ignoram `workspace/` e `sandboxes/`, e substituições de caminho `agents.*.workspace` / `agentDir` são removidas para que as sondas não atinjam seu workspace real do host. -Se quiser depender de chaves em env (por exemplo, exportadas no seu `~/.profile`), execute os testes locais após `source ~/.profile`, ou use os executores Docker abaixo (eles podem montar `~/.profile` no contêiner). +Se quiser depender de chaves do env (por exemplo exportadas no seu `~/.profile`), execute testes locais após `source ~/.profile`, ou use os executores Docker abaixo (eles podem montar `~/.profile` no contêiner). ## Live do Deepgram (transcrição de áudio) - Teste: `src/media-understanding/providers/deepgram/audio.live.test.ts` -- Habilitar: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts` +- Ativar: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts` -## Live do plano de codificação do BytePlus +## Live do plano de codificação BytePlus - Teste: `src/agents/byteplus.live.test.ts` -- Habilitar: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts` +- Ativar: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts` - Substituição opcional de modelo: `BYTEPLUS_CODING_MODEL=ark-code-latest` ## Live de mídia de workflow do ComfyUI - Teste: `extensions/comfy/comfy.live.test.ts` -- Habilitar: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` +- Ativar: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` - Escopo: - Exercita os caminhos empacotados de imagem, vídeo e `music_generate` do comfy - - Ignora cada capacidade, a menos que `models.providers.comfy.` esteja configurado - - Útil após alterar envio de workflow do comfy, polling, downloads ou registro do Plugin + - Ignora cada capacidade a menos que `models.providers.comfy.` esteja configurado + - Útil depois de alterar envio de workflow do comfy, polling, downloads ou registro de plugin ## Live de geração de imagem @@ -744,114 +739,114 @@ Se quiser depender de chaves em env (por exemplo, exportadas no seu `~/.profile` - Comando: `pnpm test:live src/image-generation/runtime.live.test.ts` - Harness: `pnpm test:live:media image` - Escopo: - - Enumera todos os Plugins de provedor de geração de imagem registrados - - Carrega variáveis de ambiente ausentes de provedores a partir do seu shell de login (`~/.profile`) antes de sondar - - Usa por padrão chaves de API live/env antes dos perfis de autenticação armazenados, para que chaves de teste antigas em `auth-profiles.json` não ocultem credenciais reais do shell - - Ignora provedores sem autenticação/perfil/modelo utilizável + - Enumera todos os plugins de provedor de geração de imagem registrados + - Carrega variáveis de ambiente de provedor ausentes do seu shell de login (`~/.profile`) antes das sondas + - Usa chaves de API live/env antes dos perfis de auth armazenados por padrão, para que chaves de teste obsoletas em `auth-profiles.json` não ocultem credenciais reais do shell + - Ignora provedores sem auth/perfil/modelo utilizável - Executa as variantes padrão de geração de imagem pela capacidade compartilhada de runtime: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` - `openai:default-generate` -- Provedores empacotados atuais cobertos: +- Provedores empacotados atualmente cobertos: - `openai` - `google` - Restrição opcional: - `OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS="openai,google"` - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-1,google/gemini-3.1-flash-image-preview"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit"` -- Comportamento opcional de autenticação: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forçar autenticação do armazenamento de perfil e ignorar substituições apenas de env +- Comportamento opcional de auth: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forçar auth via armazenamento de perfis e ignorar substituições somente por env ## Live de geração de música - Teste: `extensions/music-generation-providers.live.test.ts` -- Habilitar: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` +- Ativar: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` - Harness: `pnpm test:live:media music` - Escopo: - Exercita o caminho compartilhado empacotado de provedor de geração de música - Atualmente cobre Google e MiniMax - - Carrega variáveis de ambiente de provedores do seu shell de login (`~/.profile`) antes de sondar - - Usa por padrão chaves de API live/env antes dos perfis de autenticação armazenados, para que chaves de teste antigas em `auth-profiles.json` não ocultem credenciais reais do shell - - Ignora provedores sem autenticação/perfil/modelo utilizável + - Carrega variáveis de ambiente de provedor do seu shell de login (`~/.profile`) antes das sondas + - Usa chaves de API live/env antes dos perfis de auth armazenados por padrão, para que chaves de teste obsoletas em `auth-profiles.json` não ocultem credenciais reais do shell + - Ignora provedores sem auth/perfil/modelo utilizável - Executa ambos os modos de runtime declarados quando disponíveis: - `generate` com entrada apenas de prompt - `edit` quando o provedor declara `capabilities.edit.enabled` - - Cobertura atual da faixa compartilhada: + - Cobertura atual da lane compartilhada: - `google`: `generate`, `edit` - `minimax`: `generate` - `comfy`: arquivo live separado do Comfy, não esta varredura compartilhada - Restrição opcional: - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` -- Comportamento opcional de autenticação: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forçar autenticação do armazenamento de perfil e ignorar substituições apenas de env +- Comportamento opcional de auth: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forçar auth via armazenamento de perfis e ignorar substituições somente por env ## Live de geração de vídeo - Teste: `extensions/video-generation-providers.live.test.ts` -- Habilitar: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` +- Ativar: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` - Harness: `pnpm test:live:media video` - Escopo: - Exercita o caminho compartilhado empacotado de provedor de geração de vídeo - - Usa por padrão o caminho de smoke seguro para release: provedores sem FAL, uma solicitação de texto para vídeo por provedor, prompt de lagosta de um segundo e um limite de operação por provedor a partir de `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` por padrão) - - Ignora FAL por padrão porque a latência da fila no lado do provedor pode dominar o tempo da release; passe `--video-providers fal` ou `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` para executá-lo explicitamente - - Carrega variáveis de ambiente de provedores do seu shell de login (`~/.profile`) antes de sondar - - Usa por padrão chaves de API live/env antes dos perfis de autenticação armazenados, para que chaves de teste antigas em `auth-profiles.json` não ocultem credenciais reais do shell - - Ignora provedores sem autenticação/perfil/modelo utilizável + - Usa por padrão o caminho de smoke seguro para release: provedores que não são FAL, uma solicitação de texto para vídeo por provedor, prompt lobster de um segundo e um limite de operação por provedor a partir de `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` por padrão) + - Ignora FAL por padrão porque a latência de fila do lado do provedor pode dominar o tempo de release; passe `--video-providers fal` ou `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` para executá-lo explicitamente + - Carrega variáveis de ambiente do provedor do seu shell de login (`~/.profile`) antes das sondas + - Usa chaves de API live/env antes dos perfis de auth armazenados por padrão, para que chaves de teste obsoletas em `auth-profiles.json` não ocultem credenciais reais do shell + - Ignora provedores sem auth/perfil/modelo utilizável - Executa apenas `generate` por padrão - Defina `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` para também executar modos de transformação declarados quando disponíveis: - `imageToVideo` quando o provedor declara `capabilities.imageToVideo.enabled` e o provedor/modelo selecionado aceita entrada de imagem local com suporte de buffer na varredura compartilhada - `videoToVideo` quando o provedor declara `capabilities.videoToVideo.enabled` e o provedor/modelo selecionado aceita entrada de vídeo local com suporte de buffer na varredura compartilhada - Provedores `imageToVideo` atualmente declarados, mas ignorados, na varredura compartilhada: - `vydra` porque o `veo3` empacotado é somente texto e o `kling` empacotado exige uma URL de imagem remota - - Cobertura Vydra específica do provedor: + - Cobertura específica de provedor Vydra: - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - esse arquivo executa `veo3` de texto para vídeo, mais uma faixa `kling` que usa por padrão uma fixture de URL de imagem remota + - esse arquivo executa `veo3` de texto para vídeo mais uma lane `kling` que usa por padrão uma fixture com URL de imagem remota - Cobertura live atual de `videoToVideo`: - - `runway` apenas quando o modelo selecionado é `runway/gen4_aleph` + - apenas `runway` quando o modelo selecionado é `runway/gen4_aleph` - Provedores `videoToVideo` atualmente declarados, mas ignorados, na varredura compartilhada: - `alibaba`, `qwen`, `xai` porque esses caminhos atualmente exigem URLs de referência remotas `http(s)` / MP4 - - `google` porque a faixa compartilhada atual Gemini/Veo usa entrada local com suporte de buffer e esse caminho não é aceito na varredura compartilhada - - `openai` porque a faixa compartilhada atual não garante acesso específico da organização a inpaint/remix de vídeo + - `google` porque a lane compartilhada atual de Gemini/Veo usa entrada local com suporte de buffer e esse caminho não é aceito na varredura compartilhada + - `openai` porque a lane compartilhada atual não tem garantias de acesso específicas da organização para inpaint/remix de vídeo - Restrição opcional: - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"` - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"` - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""` para incluir todos os provedores na varredura padrão, incluindo FAL - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` para reduzir o limite de operação de cada provedor em uma execução de smoke agressiva -- Comportamento opcional de autenticação: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forçar autenticação do armazenamento de perfil e ignorar substituições apenas de env +- Comportamento opcional de auth: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para forçar auth via armazenamento de perfis e ignorar substituições somente por env ## Harness live de mídia - Comando: `pnpm test:live:media` - Finalidade: - Executa as suítes live compartilhadas de imagem, música e vídeo por um único entrypoint nativo do repositório - - Carrega automaticamente variáveis de ambiente ausentes de provedores a partir de `~/.profile` - - Restringe automaticamente cada suíte aos provedores que atualmente têm autenticação utilizável por padrão - - Reutiliza `scripts/test-live.mjs`, então o comportamento de Heartbeat e modo silencioso permanece consistente + - Carrega automaticamente variáveis de ambiente de provedor ausentes de `~/.profile` + - Restringe automaticamente cada suíte por padrão aos provedores que atualmente têm auth utilizável + - Reutiliza `scripts/test-live.mjs`, para que o comportamento de Heartbeat e modo silencioso permaneça consistente - Exemplos: - `pnpm test:live:media` - `pnpm test:live:media image video --providers openai,google,minimax` - `pnpm test:live:media video --video-providers openai,runway --all-providers` - `pnpm test:live:media music --quiet` -## Executores Docker (verificações opcionais de “funciona no Linux”) +## Executores Docker (verificações opcionais de "funciona no Linux") Esses executores Docker se dividem em dois grupos: -- Executores live de modelos: `test:docker:live-models` e `test:docker:live-gateway` executam apenas o arquivo live de chave de perfil correspondente dentro da imagem Docker do repositório (`src/agents/models.profiles.live.test.ts` e `src/gateway/gateway-models.profiles.live.test.ts`), montando seu diretório local de config e workspace (e carregando `~/.profile` se montado). Os entrypoints locais correspondentes são `test:live:models-profiles` e `test:live:gateway-profiles`. -- Os executores Docker live usam por padrão um limite de smoke menor para que uma varredura Docker completa permaneça prática: +- Executores live de modelo: `test:docker:live-models` e `test:docker:live-gateway` executam apenas o arquivo live correspondente de chaves de perfil dentro da imagem Docker do repositório (`src/agents/models.profiles.live.test.ts` e `src/gateway/gateway-models.profiles.live.test.ts`), montando seu diretório local de config e workspace (e carregando `~/.profile` se montado). Os entrypoints locais correspondentes são `test:live:models-profiles` e `test:live:gateway-profiles`. +- Os executores Docker live usam por padrão um limite menor de smoke para que uma varredura Docker completa continue prática: `test:docker:live-models` usa por padrão `OPENCLAW_LIVE_MAX_MODELS=12`, e `test:docker:live-gateway` usa por padrão `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` e `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Substitua essas variáveis de ambiente quando quiser explicitamente a varredura exaustiva maior. -- `test:docker:all` constrói a imagem Docker live uma vez via `test:docker:live-build` e depois a reutiliza para as duas faixas Docker live. +- `test:docker:all` compila a imagem Docker live uma vez por `test:docker:live-build`, depois a reutiliza para as duas lanes Docker live. - Executores de smoke em contêiner: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` e `test:docker:plugins` inicializam um ou mais contêineres reais e verificam caminhos de integração de nível mais alto. -Os executores Docker live de modelos também fazem bind-mount apenas dos homes de autenticação CLI necessários (ou de todos os suportados quando a execução não está restrita), e então os copiam para o home do contêiner antes da execução para que OAuth de CLI externa possa atualizar tokens sem alterar o armazenamento de autenticação do host: +Os executores Docker live de modelo também fazem bind-mount apenas dos homes de auth de CLI necessários (ou de todos os suportados quando a execução não está restrita), depois os copiam para o home do contêiner antes da execução para que o OAuth da CLI externa possa renovar tokens sem alterar o armazenamento de auth do host: - Modelos diretos: `pnpm test:docker:live-models` (script: `scripts/test-live-models-docker.sh`) - Smoke de bind ACP: `pnpm test:docker:live-acp-bind` (script: `scripts/test-live-acp-bind-docker.sh`) @@ -860,104 +855,103 @@ Os executores Docker live de modelos também fazem bind-mount apenas dos homes d - Gateway + agente dev: `pnpm test:docker:live-gateway` (script: `scripts/test-live-gateway-models-docker.sh`) - Smoke live do Open WebUI: `pnpm test:docker:openwebui` (script: `scripts/e2e/openwebui-docker.sh`) - Assistente de onboarding (TTY, scaffolding completo): `pnpm test:docker:onboard` (script: `scripts/e2e/onboard-docker.sh`) -- Networking do Gateway (dois contêineres, autenticação WS + health): `pnpm test:docker:gateway-network` (script: `scripts/e2e/gateway-network-docker.sh`) -- Ponte de canal MCP (Gateway inicializado com seed + ponte stdio + smoke bruto de quadro de notificação do Claude): `pnpm test:docker:mcp-channels` (script: `scripts/e2e/mcp-channels-docker.sh`) +- Rede do gateway (dois contêineres, auth WS + health): `pnpm test:docker:gateway-network` (script: `scripts/e2e/gateway-network-docker.sh`) +- Bridge de canal MCP (Gateway semeado + bridge stdio + smoke bruto de notification-frame do Claude): `pnpm test:docker:mcp-channels` (script: `scripts/e2e/mcp-channels-docker.sh`) - Plugins (smoke de instalação + alias `/plugin` + semântica de reinício do bundle Claude): `pnpm test:docker:plugins` (script: `scripts/e2e/plugins-docker.sh`) -Os executores Docker live de modelos também fazem bind-mount do checkout atual somente leitura e -o preparam em um diretório de trabalho temporário dentro do contêiner. Isso mantém a imagem de runtime -leve e ainda assim executa o Vitest exatamente sobre seu código-fonte/config local. -A etapa de preparação ignora caches locais grandes e saídas de build de app, como -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` e diretórios locais do app `.build` ou -saídas do Gradle, para que execuções live no Docker não passem minutos copiando +Os executores Docker live de modelo também fazem bind-mount do checkout atual como somente leitura e +o preparam em um workdir temporário dentro do contêiner. Isso mantém a imagem de runtime +enxuta, ao mesmo tempo em que executa o Vitest exatamente com seu código-fonte/config locais. +A etapa de preparação ignora caches locais grandes e saídas de build do app, como +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` e diretórios de saída locais de `.build` do app ou +Gradle, para que execuções live em Docker não gastem minutos copiando artefatos específicos da máquina. -Eles também definem `OPENCLAW_SKIP_CHANNELS=1` para que sondas live do gateway não iniciem -workers reais de canais como Telegram/Discord/etc. dentro do contêiner. +Eles também definem `OPENCLAW_SKIP_CHANNELS=1` para que as sondas live do gateway não iniciem +workers reais de canais do Telegram/Discord/etc. dentro do contêiner. `test:docker:live-models` ainda executa `pnpm test:live`, então também passe -`OPENCLAW_LIVE_GATEWAY_*` quando precisar restringir ou excluir a cobertura live -do gateway nessa faixa Docker. +`OPENCLAW_LIVE_GATEWAY_*` quando precisar restringir ou excluir a cobertura live do gateway dessa lane Docker. `test:docker:openwebui` é um smoke de compatibilidade de nível mais alto: ele inicia um -contêiner do Gateway do OpenClaw com endpoints HTTP compatíveis com OpenAI habilitados, -inicia um contêiner do Open WebUI fixado apontando para esse gateway, faz login por -meio do Open WebUI, verifica se `/api/models` expõe `openclaw/default` e então envia uma +contêiner de gateway OpenClaw com endpoints HTTP compatíveis com OpenAI ativados, +inicia um contêiner fixado do Open WebUI contra esse gateway, faz login pelo +Open WebUI, verifica se `/api/models` expõe `openclaw/default` e então envia uma requisição real de chat pelo proxy `/api/chat/completions` do Open WebUI. -A primeira execução pode ser visivelmente mais lenta porque o Docker pode precisar baixar a -imagem do Open WebUI e o próprio Open WebUI pode precisar concluir sua configuração inicial. -Essa faixa espera uma chave live de modelo utilizável, e `OPENCLAW_PROFILE_FILE` -(`~/.profile` por padrão) é a forma principal de fornecê-la em execuções Dockerizadas. +A primeira execução pode ser visivelmente mais lenta porque o Docker talvez precise baixar a +imagem do Open WebUI e o Open WebUI talvez precise terminar sua própria configuração de cold start. +Essa lane espera uma chave de modelo live utilizável, e `OPENCLAW_PROFILE_FILE` +(`~/.profile` por padrão) é a forma principal de fornecê-la em execuções com Docker. Execuções bem-sucedidas imprimem um pequeno payload JSON como `{ "ok": true, "model": "openclaw/default", ... }`. `test:docker:mcp-channels` é intencionalmente determinístico e não precisa de uma conta real de Telegram, Discord ou iMessage. Ele inicializa um contêiner de Gateway -com seed, inicia um segundo contêiner que executa `openclaw mcp serve` e então +semeado, inicia um segundo contêiner que executa `openclaw mcp serve` e então verifica descoberta de conversa roteada, leituras de transcrição, metadados de anexo, -comportamento da fila de eventos live, roteamento de envio de saída e notificações de canal + -permissão no estilo Claude pela ponte stdio MCP real. A verificação de notificação -inspeciona diretamente os quadros MCP brutos do stdio para que o smoke valide o que a -ponte realmente emite, não apenas o que um SDK cliente específico por acaso expõe. +comportamento de fila de eventos live, roteamento de envio de saída e notificações de canal + +permissão no estilo Claude pela bridge MCP stdio real. A verificação de notificação +inspeciona diretamente os frames MCP stdio brutos, assim o smoke valida o que a +bridge realmente emite, não apenas o que um SDK cliente específico por acaso expõe. -Smoke manual de thread ACP em linguagem natural (não CI): +Smoke manual de thread em linguagem natural ACP (não CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Mantenha este script para fluxos de regressão/depuração. Ele pode ser necessário novamente para validação de roteamento de thread ACP, portanto não o exclua. +- Mantenha este script para fluxos de regressão/depuração. Ele pode ser necessário novamente para validação de roteamento de thread ACP, então não o exclua. Variáveis de ambiente úteis: - `OPENCLAW_CONFIG_DIR=...` (padrão: `~/.openclaw`) montado em `/home/node/.openclaw` - `OPENCLAW_WORKSPACE_DIR=...` (padrão: `~/.openclaw/workspace`) montado em `/home/node/.openclaw/workspace` - `OPENCLAW_PROFILE_FILE=...` (padrão: `~/.profile`) montado em `/home/node/.profile` e carregado antes de executar os testes -- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` para verificar apenas variáveis de ambiente carregadas de `OPENCLAW_PROFILE_FILE`, usando diretórios temporários de config/workspace e sem montagens de autenticação CLI externa -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (padrão: `~/.cache/openclaw/docker-cli-tools`) montado em `/home/node/.npm-global` para instalações CLI em cache dentro do Docker -- Diretórios/arquivos de autenticação CLI externa sob `$HOME` são montados somente leitura em `/host-auth...` e então copiados para `/home/node/...` antes do início dos testes +- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` para verificar apenas variáveis de ambiente carregadas de `OPENCLAW_PROFILE_FILE`, usando diretórios temporários de config/workspace e sem mounts de auth de CLI externa +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (padrão: `~/.cache/openclaw/docker-cli-tools`) montado em `/home/node/.npm-global` para instalações de CLI em cache dentro do Docker +- Diretórios/arquivos externos de auth de CLI sob `$HOME` são montados como somente leitura sob `/host-auth...` e depois copiados para `/home/node/...` antes de os testes começarem - Diretórios padrão: `.minimax` - Arquivos padrão: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - Execuções com provedor restrito montam apenas os diretórios/arquivos necessários inferidos de `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - Substitua manualmente com `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` ou uma lista separada por vírgulas como `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` - `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` para restringir a execução - `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` para filtrar provedores dentro do contêiner -- `OPENCLAW_SKIP_DOCKER_BUILD=1` para reutilizar uma imagem `openclaw:local-live` existente em reexecuções que não precisam de rebuild -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para garantir que as credenciais venham do armazenamento de perfil (não do env) +- `OPENCLAW_SKIP_DOCKER_BUILD=1` para reutilizar uma imagem `openclaw:local-live` existente em reexecuções que não precisam de recompilação +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` para garantir que as credenciais venham do armazenamento de perfis (não do env) - `OPENCLAW_OPENWEBUI_MODEL=...` para escolher o modelo exposto pelo gateway para o smoke do Open WebUI - `OPENCLAW_OPENWEBUI_PROMPT=...` para substituir o prompt de verificação de nonce usado pelo smoke do Open WebUI - `OPENWEBUI_IMAGE=...` para substituir a tag de imagem fixada do Open WebUI -## Verificação da documentação +## Sanidade da documentação -Execute verificações da documentação após editar docs: `pnpm check:docs`. +Execute verificações de docs após edições na documentação: `pnpm check:docs`. Execute a validação completa de âncoras do Mintlify quando também precisar verificar títulos na página: `pnpm docs:check-links:anchors`. ## Regressão offline (segura para CI) Estas são regressões de “pipeline real” sem provedores reais: -- Chamada de ferramentas do Gateway (mock OpenAI, gateway real + loop de agente): `src/gateway/gateway.test.ts` (caso: "runs a mock OpenAI tool call end-to-end via gateway agent loop") -- Assistente do Gateway (WS `wizard.start`/`wizard.next`, grava config + autenticação exigida): `src/gateway/gateway.test.ts` (caso: "runs wizard over ws and writes auth token config") +- Tool calling do gateway (mock OpenAI, gateway real + loop de agente): `src/gateway/gateway.test.ts` (caso: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Assistente do gateway (WS `wizard.start`/`wizard.next`, grava config + auth aplicado): `src/gateway/gateway.test.ts` (caso: "runs wizard over ws and writes auth token config") -## Evals de confiabilidade do agente (Skills) +## Avaliações de confiabilidade de agente (Skills) -Já temos alguns testes seguros para CI que se comportam como “evals de confiabilidade do agente”: +Já temos alguns testes seguros para CI que se comportam como “avaliações de confiabilidade de agente”: -- Chamada simulada de ferramentas pelo loop real do gateway + agente (`src/gateway/gateway.test.ts`). -- Fluxos end-to-end do assistente que validam wiring de sessão e efeitos de configuração (`src/gateway/gateway.test.ts`). +- Mock de tool-calling pelo gateway real + loop de agente (`src/gateway/gateway.test.ts`). +- Fluxos end-to-end do assistente que validam a fiação da sessão e os efeitos na config (`src/gateway/gateway.test.ts`). O que ainda falta para Skills (veja [Skills](/pt-BR/tools/skills)): -- **Tomada de decisão:** quando Skills são listadas no prompt, o agente escolhe a Skill correta (ou evita as irrelevantes)? -- **Conformidade:** o agente lê `SKILL.md` antes do uso e segue as etapas/args obrigatórios? -- **Contratos de fluxo de trabalho:** cenários de múltiplas rodadas que verificam ordem de ferramentas, continuidade do histórico da sessão e limites de sandbox. +- **Tomada de decisão:** quando Skills são listadas no prompt, o agente escolhe a Skill certa (ou evita as irrelevantes)? +- **Conformidade:** o agente lê `SKILL.md` antes do uso e segue as etapas/args exigidos? +- **Contratos de fluxo de trabalho:** cenários multi-turno que validam ordem de ferramentas, continuidade do histórico da sessão e limites de sandbox. -Evals futuros devem permanecer determinísticos primeiro: +Avaliações futuras devem permanecer determinísticas primeiro: -- Um executor de cenários usando provedores simulados para verificar chamadas de ferramentas + ordem, leituras de arquivos de Skill e wiring de sessão. +- Um executor de cenários usando provedores mock para validar chamadas de ferramenta + ordem, leituras de arquivos de Skill e fiação de sessão. - Uma pequena suíte de cenários focados em Skills (usar vs evitar, gating, prompt injection). -- Evals live opcionais (opt-in, controlados por env) somente depois que a suíte segura para CI estiver pronta. +- Avaliações live opcionais (opt-in, protegidas por env) somente depois que a suíte segura para CI estiver implementada. -## Testes de contrato (formato de Plugin e canal) +## Testes de contrato (formato de plugin e canal) -Testes de contrato verificam que todo Plugin e canal registrado está em conformidade com seu -contrato de interface. Eles iteram sobre todos os Plugins descobertos e executam uma suíte de -verificações de formato e comportamento. A faixa unit padrão de `pnpm test` intencionalmente -ignora esses arquivos compartilhados de seam e smoke; execute os comandos de contrato explicitamente +Os testes de contrato verificam se todo plugin e canal registrado está em conformidade com seu +contrato de interface. Eles iteram sobre todos os plugins descobertos e executam uma suíte de +validações de formato e comportamento. A lane unit padrão de `pnpm test` +ignora intencionalmente esses arquivos compartilhados de seam e smoke; execute os comandos de contrato explicitamente quando alterar superfícies compartilhadas de canal ou provedor. ### Comandos @@ -970,53 +964,53 @@ quando alterar superfícies compartilhadas de canal ou provedor. Localizados em `src/channels/plugins/contracts/*.contract.test.ts`: -- **plugin** - Formato básico do Plugin (id, nome, capacidades) +- **plugin** - Formato básico do plugin (id, nome, capacidades) - **setup** - Contrato do assistente de configuração -- **session-binding** - Comportamento de vinculação de sessão -- **outbound-payload** - Estrutura do payload de mensagem -- **inbound** - Tratamento de mensagens de entrada -- **actions** - Handlers de ação de canal +- **session-binding** - Comportamento de vínculo de sessão +- **outbound-payload** - Estrutura da carga útil da mensagem +- **inbound** - Tratamento de mensagem de entrada +- **actions** - Handlers de ação do canal - **threading** - Tratamento de ID de thread - **directory** - API de diretório/lista -- **group-policy** - Aplicação de política de grupo +- **group-policy** - Aplicação da política de grupo ### Contratos de status do provedor Localizados em `src/plugins/contracts/*.contract.test.ts`. -- **status** - Sondas de status de canal -- **registry** - Formato do registro de Plugins +- **status** - Sondas de status do canal +- **registry** - Formato do registro de plugins ### Contratos de provedor Localizados em `src/plugins/contracts/*.contract.test.ts`: -- **auth** - Contrato de fluxo de autenticação -- **auth-choice** - Escolha/seleção de autenticação +- **auth** - Contrato do fluxo de auth +- **auth-choice** - Escolha/seleção de auth - **catalog** - API de catálogo de modelos -- **discovery** - Descoberta de Plugins -- **loader** - Carregamento de Plugins +- **discovery** - Descoberta de plugins +- **loader** - Carregamento de plugin - **runtime** - Runtime do provedor -- **shape** - Formato/interface do Plugin +- **shape** - Formato/interface do plugin - **wizard** - Assistente de configuração ### Quando executar -- Depois de alterar exports ou subpaths do plugin-sdk -- Depois de adicionar ou modificar um Plugin de canal ou provedor -- Depois de refatorar registro ou descoberta de Plugins +- Depois de alterar exports ou subpaths de plugin-sdk +- Depois de adicionar ou modificar um plugin de canal ou provedor +- Depois de refatorar o registro ou a descoberta de plugins -Os testes de contrato rodam no CI e não exigem chaves reais de API. +Os testes de contrato rodam na CI e não exigem chaves de API reais. ## Adicionando regressões (orientação) -Quando você corrige um problema de provedor/modelo descoberto em live: +Quando você corrigir um problema de provedor/modelo descoberto em live: -- Adicione uma regressão segura para CI, se possível (provedor simulado/stub, ou capture a transformação exata do formato da requisição) -- Se for inerentemente apenas live (rate limits, políticas de autenticação), mantenha o teste live restrito e opt-in via variáveis de ambiente -- Prefira atingir a menor camada que detecta o bug: - - bug de conversão/replay de requisição do provedor → teste direto de modelos +- Adicione uma regressão segura para CI, se possível (provedor mock/stub, ou capture a transformação exata do formato da requisição) +- Se for inerentemente apenas live (limites de taxa, políticas de auth), mantenha o teste live restrito e opt-in via variáveis de ambiente +- Prefira mirar na menor camada que capture o bug: + - bug de conversão/replay de requisição do provedor → teste de modelos diretos - bug no pipeline de sessão/histórico/ferramenta do gateway → smoke live do gateway ou teste mock do gateway seguro para CI -- Guardrail de travessia de SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` deriva um alvo de amostra por classe SecretRef a partir dos metadados do registro (`listSecretTargetRegistryEntries()`), depois verifica que ids exec de segmento de travessia são rejeitados. - - Se você adicionar uma nova família de alvo SecretRef `includeInPlan` em `src/secrets/target-registry-data.ts`, atualize `classifyTargetClass` nesse teste. O teste falha intencionalmente em ids de alvo não classificados para que novas classes não possam ser ignoradas silenciosamente. +- Proteção para travessia de SecretRef: + - `src/secrets/exec-secret-ref-id-parity.test.ts` deriva um alvo amostrado por classe de SecretRef a partir dos metadados do registro (`listSecretTargetRegistryEntries()`), então valida que ids de exec com segmento de travessia são rejeitados. + - Se você adicionar uma nova família de alvos SecretRef `includeInPlan` em `src/secrets/target-registry-data.ts`, atualize `classifyTargetClass` nesse teste. O teste falha intencionalmente em ids de alvo não classificados para que novas classes não possam ser ignoradas silenciosamente. diff --git a/docs/pt-BR/install/index.md b/docs/pt-BR/install/index.md index 000195e99..72024d974 100644 --- a/docs/pt-BR/install/index.md +++ b/docs/pt-BR/install/index.md @@ -3,22 +3,22 @@ read_when: - Você precisa de um método de instalação diferente do início rápido de Primeiros passos - Você quer implantar em uma plataforma de nuvem - Você precisa atualizar, migrar ou desinstalar -summary: Instale o OpenClaw — script de instalação, npm/pnpm/bun, a partir do código-fonte, Docker e mais +summary: Instale o OpenClaw — script do instalador, npm/pnpm/bun, a partir do código-fonte, Docker e mais title: Instalar x-i18n: - generated_at: "2026-04-05T12:45:12Z" + generated_at: "2026-04-20T05:41:43Z" model: gpt-5.4 provider: openai - source_hash: eca17c76a2a66166b3d8cda9dc3144ab920d30ad0ed2a220eb9389d7a383ba5d + source_hash: ad0a5fdbbf13dcaf2fed6840f35aa22b2e9e458509509f98303c8d87c2556a6f source_path: install/index.md workflow: 15 --- -# Instalar +# Instalação -## Recomendado: script de instalação +## Recomendado: script do instalador -A forma mais rápida de instalar. Ele detecta seu sistema operacional, instala o Node se necessário, instala o OpenClaw e inicia o onboarding. +A forma mais rápida de instalar. Ele detecta seu SO, instala o Node se necessário, instala o OpenClaw e inicia a integração inicial. @@ -33,7 +33,7 @@ A forma mais rápida de instalar. Ele detecta seu sistema operacional, instala o -Para instalar sem executar o onboarding: +Para instalar sem executar a integração inicial: @@ -48,27 +48,27 @@ Para instalar sem executar o onboarding: -Para ver todas as flags e opções de CI/automação, consulte [Internos do instalador](/install/installer). +Para todos os sinalizadores e opções de CI/automação, consulte [Detalhes internos do instalador](/pt-BR/install/installer). ## Requisitos do sistema -- **Node 24** (recomendado) ou Node 22.14+ — o script de instalação cuida disso automaticamente -- **macOS, Linux ou Windows** — tanto Windows nativo quanto WSL2 são compatíveis; WSL2 é mais estável. Consulte [Windows](/platforms/windows). -- `pnpm` é necessário apenas se você compilar a partir do código-fonte +- **Node 24** (recomendado) ou Node 22.14+ — o script do instalador cuida disso automaticamente +- **macOS, Linux ou Windows** — tanto o Windows nativo quanto o WSL2 são compatíveis; o WSL2 é mais estável. Consulte [Windows](/pt-BR/platforms/windows). +- `pnpm` só é necessário se você compilar a partir do código-fonte ## Métodos alternativos de instalação ### Instalador com prefixo local (`install-cli.sh`) -Use este método quando quiser manter o OpenClaw e o Node sob um prefixo local, como -`~/.openclaw`, sem depender de uma instalação de Node em todo o sistema: +Use isto quando quiser manter o OpenClaw e o Node em um prefixo local como +`~/.openclaw`, sem depender de uma instalação do Node em todo o sistema: ```bash curl -fsSL https://openclaw.ai/install-cli.sh | bash ``` -Ele oferece suporte a instalações via npm por padrão, além de instalações a partir de checkout git no mesmo -fluxo de prefixo. Referência completa: [Internos do instalador](/install/installer#install-clish). +Ele oferece suporte a instalações via npm por padrão, além de instalações a partir de checkout do git dentro do mesmo +fluxo com prefixo. Referência completa: [Detalhes internos do instalador](/pt-BR/install/installer#install-clish). ### npm, pnpm ou bun @@ -100,7 +100,7 @@ Se você já gerencia o Node por conta própria: ``` - O Bun é compatível com o caminho de instalação global da CLI. Para o runtime do Gateway, o Node continua sendo o runtime de daemon recomendado. + Bun é compatível com o caminho de instalação global da CLI. Para o runtime do Gateway, o Node continua sendo o runtime de daemon recomendado. @@ -122,14 +122,14 @@ Para contribuidores ou qualquer pessoa que queira executar a partir de um checko ```bash git clone https://github.com/openclaw/openclaw.git cd openclaw -pnpm install && pnpm ui:build && pnpm build +pnpm install && pnpm build && pnpm ui:build pnpm link --global openclaw onboard --install-daemon ``` -Ou ignore o link e use `pnpm openclaw ...` de dentro do repositório. Consulte [Setup](/start/setup) para ver fluxos completos de desenvolvimento. +Ou ignore o link e use `pnpm openclaw ...` dentro do repositório. Consulte [Configuração](/pt-BR/start/setup) para ver os fluxos completos de desenvolvimento. -### Instalar do GitHub main +### Instalar a partir da branch `main` do GitHub ```bash npm install -g github:openclaw/openclaw#main @@ -138,76 +138,76 @@ npm install -g github:openclaw/openclaw#main ### Contêineres e gerenciadores de pacotes - - Implantações conteinerizadas ou headless. + + Implantações em contêiner ou sem interface. - - Alternativa de contêiner rootless ao Docker. + + Alternativa de contêiner sem root ao Docker. - + Instalação declarativa via flake do Nix. - + Provisionamento automatizado de frota. - - Uso somente da CLI via runtime Bun. + + Uso somente da CLI com o runtime Bun. ## Verifique a instalação ```bash -openclaw --version # confirm the CLI is available -openclaw doctor # check for config issues -openclaw gateway status # verify the Gateway is running +openclaw --version # confirma se a CLI está disponível +openclaw doctor # verifica se há problemas de configuração +openclaw gateway status # verifica se o Gateway está em execução ``` Se você quiser inicialização gerenciada após a instalação: - macOS: LaunchAgent via `openclaw onboard --install-daemon` ou `openclaw gateway install` -- Linux/WSL2: serviço de usuário systemd pelos mesmos comandos -- Windows nativo: Scheduled Task primeiro, com fallback para um item de login por usuário na pasta Startup se a criação da tarefa for negada +- Linux/WSL2: serviço de usuário do systemd pelos mesmos comandos +- Windows nativo: Scheduled Task primeiro, com fallback para um item de login na pasta Startup por usuário se a criação da tarefa for negada ## Hospedagem e implantação -Implante o OpenClaw em um servidor de nuvem ou VPS: +Implante o OpenClaw em um servidor em nuvem ou VPS: - Qualquer VPS Linux - Etapas compartilhadas do Docker - K8s - Fly.io - Hetzner - Google Cloud - Azure - Railway - Render - Northflank + Qualquer VPS Linux + Etapas compartilhadas do Docker + K8s + Fly.io + Hetzner + Google Cloud + Azure + Railway + Render + Northflank ## Atualizar, migrar ou desinstalar - + Mantenha o OpenClaw atualizado. - - Mude para uma nova máquina. + + Mova para uma nova máquina. - + Remova o OpenClaw completamente. ## Solução de problemas: `openclaw` não encontrado -Se a instalação foi bem-sucedida, mas `openclaw` não é encontrado no terminal: +Se a instalação foi concluída com sucesso, mas `openclaw` não é encontrado no terminal: ```bash -node -v # Node installed? -npm prefix -g # Where are global packages? -echo "$PATH" # Is the global bin dir in PATH? +node -v # Node instalado? +npm prefix -g # Onde estão os pacotes globais? +echo "$PATH" # O diretório global de bin está no PATH? ``` Se `$(npm prefix -g)/bin` não estiver no seu `$PATH`, adicione-o ao arquivo de inicialização do shell (`~/.zshrc` ou `~/.bashrc`): @@ -216,4 +216,4 @@ Se `$(npm prefix -g)/bin` não estiver no seu `$PATH`, adicione-o ao arquivo de export PATH="$(npm prefix -g)/bin:$PATH" ``` -Depois abra um novo terminal. Consulte [Configuração do Node](/install/node) para mais detalhes. +Depois, abra um novo terminal. Consulte [Configuração do Node](/pt-BR/install/node) para mais detalhes. diff --git a/docs/pt-BR/platforms/windows.md b/docs/pt-BR/platforms/windows.md index 21ecc32b4..82e0cdcd7 100644 --- a/docs/pt-BR/platforms/windows.md +++ b/docs/pt-BR/platforms/windows.md @@ -1,24 +1,27 @@ --- read_when: - Instalando o OpenClaw no Windows - - Escolhendo entre Windows nativo e WSL2 - - Buscando o status do app complementar para Windows -summary: 'Suporte ao Windows: caminhos de instalação nativo e WSL2, daemon e limitações atuais' + - Escolhendo entre o Windows nativo e o WSL2 + - Procurando o status do aplicativo complementar para Windows +summary: 'Suporte ao Windows: caminhos de instalação nativos e via WSL2, daemon e limitações atuais' title: Windows x-i18n: - generated_at: "2026-04-05T12:48:32Z" + generated_at: "2026-04-20T05:41:42Z" model: gpt-5.4 provider: openai - source_hash: 7d9819206bdd65cf03519c1bc73ed0c7889b0ab842215ea94343262300adfd14 + source_hash: 1e7451c785a1d75c809522ad93e2c44a00b211f77f14c5c489fd0b01840d3fe2 source_path: platforms/windows.md workflow: 15 --- # Windows -O OpenClaw oferece suporte tanto a **Windows nativo** quanto a **WSL2**. O WSL2 é o caminho mais estável e recomendado para a experiência completa — a CLI, o Gateway e as ferramentas são executados dentro do Linux com compatibilidade total. O Windows nativo funciona para o uso principal da CLI e do Gateway, com algumas limitações observadas abaixo. +O OpenClaw oferece suporte tanto a **Windows nativo** quanto a **WSL2**. O WSL2 é o caminho mais +estável e recomendado para a experiência completa — a CLI, o Gateway e as +ferramentas são executados dentro do Linux com compatibilidade total. O Windows nativo funciona para +uso básico da CLI e do Gateway, com algumas limitações observadas abaixo. -Apps complementares nativos para Windows estão planejados. +Aplicativos complementares nativos para Windows estão planejados. ## WSL2 (recomendado) @@ -28,13 +31,13 @@ Apps complementares nativos para Windows estão planejados. ## Status do Windows nativo -Os fluxos da CLI no Windows nativo estão melhorando, mas o WSL2 ainda é o caminho recomendado. +Os fluxos da CLI nativa no Windows estão melhorando, mas o WSL2 ainda é o caminho recomendado. O que funciona bem no Windows nativo hoje: - instalador do site via `install.ps1` - uso local da CLI, como `openclaw --version`, `openclaw doctor` e `openclaw plugins list --json` -- smoke de agent/provider local incorporado, como: +- teste básico incorporado de agente/provedor local, como: ```powershell openclaw agent --local --agent main --thinking low -m "Reply with exactly WINDOWS-HATCH-OK." @@ -44,11 +47,11 @@ Limitações atuais: - `openclaw onboard --non-interactive` ainda espera um gateway local acessível, a menos que você passe `--skip-health` - `openclaw onboard --non-interactive --install-daemon` e `openclaw gateway install` tentam primeiro usar Tarefas Agendadas do Windows -- se a criação da Tarefa Agendada for negada, o OpenClaw recorre a um item de login por usuário na pasta Startup e inicia o gateway imediatamente -- se o próprio `schtasks` travar ou parar de responder, o OpenClaw agora aborta esse caminho rapidamente e recorre ao fallback em vez de ficar travado para sempre -- as Tarefas Agendadas ainda são preferidas quando disponíveis porque oferecem melhor status de supervisor +- se a criação da Tarefa Agendada for negada, o OpenClaw recorre a um item de inicialização por usuário na pasta Inicializar e inicia o gateway imediatamente +- se o próprio `schtasks` travar ou parar de responder, o OpenClaw agora interrompe esse caminho rapidamente e usa o fallback em vez de ficar travado indefinidamente +- Tarefas Agendadas ainda são preferidas quando disponíveis porque fornecem um melhor status de supervisão -Se você quiser apenas a CLI nativa, sem instalar o serviço do gateway, use um destes: +Se você quiser apenas a CLI nativa, sem instalar o serviço do gateway, use uma destas opções: ```powershell openclaw onboard --non-interactive --skip-health @@ -62,14 +65,14 @@ openclaw gateway install openclaw gateway status --json ``` -Se a criação da Tarefa Agendada estiver bloqueada, o modo de serviço de fallback ainda inicia automaticamente após o login por meio da pasta Startup do usuário atual. +Se a criação de Tarefa Agendada estiver bloqueada, o modo de serviço de fallback ainda inicia automaticamente após o login por meio da pasta Inicializar do usuário atual. ## Gateway -- [Runbook do Gateway](/pt-BR/gateway) +- [Guia operacional do Gateway](/pt-BR/gateway) - [Configuração](/pt-BR/gateway/configuration) -## Instalação do serviço Gateway (CLI) +## Instalação do serviço do Gateway (CLI) Dentro do WSL2: @@ -99,9 +102,10 @@ openclaw doctor ## Inicialização automática do Gateway antes do login no Windows -Para configurações headless, garanta que toda a cadeia de inicialização seja executada mesmo quando ninguém fizer login no Windows. +Para configurações headless, garanta que toda a cadeia de inicialização seja executada mesmo quando ninguém fizer login no +Windows. -### 1) Mantenha os serviços do usuário em execução sem login +### 1) Manter serviços de usuário em execução sem login Dentro do WSL: @@ -109,7 +113,7 @@ Dentro do WSL: sudo loginctl enable-linger "$(whoami)" ``` -### 2) Instale o serviço de usuário do gateway OpenClaw +### 2) Instalar o serviço de usuário do gateway do OpenClaw Dentro do WSL: @@ -117,7 +121,7 @@ Dentro do WSL: openclaw gateway install ``` -### 3) Inicie o WSL automaticamente na inicialização do Windows +### 3) Iniciar o WSL automaticamente na inicialização do Windows No PowerShell como Administrador: @@ -125,7 +129,7 @@ No PowerShell como Administrador: schtasks /create /tn "WSL Boot" /tr "wsl.exe -d Ubuntu --exec /bin/true" /sc onstart /ru SYSTEM ``` -Substitua `Ubuntu` pelo nome da sua distro em: +Substitua `Ubuntu` pelo nome da sua distribuição em: ```powershell wsl --list --verbose @@ -133,16 +137,19 @@ wsl --list --verbose ### Verificar a cadeia de inicialização -Após uma reinicialização (antes do login no Windows), verifique no WSL: +Após uma reinicialização (antes do login no Windows), verifique a partir do WSL: ```bash systemctl --user is-enabled openclaw-gateway.service systemctl --user status openclaw-gateway.service --no-pager ``` -## Avançado: expor serviços do WSL pela LAN (portproxy) +## Avançado: expor serviços do WSL na LAN (portproxy) -O WSL tem sua própria rede virtual. Se outra máquina precisar acessar um serviço em execução **dentro do WSL** (SSH, um servidor TTS local ou o Gateway), você precisará encaminhar uma porta do Windows para o IP atual do WSL. O IP do WSL muda após reinicializações, então talvez seja necessário atualizar a regra de encaminhamento. +O WSL tem sua própria rede virtual. Se outra máquina precisar acessar um serviço +em execução **dentro do WSL** (SSH, um servidor TTS local ou o Gateway), você deve +encaminhar uma porta do Windows para o IP atual do WSL. O IP do WSL muda após reinicializações, +então talvez seja necessário atualizar a regra de encaminhamento. Exemplo (PowerShell **como Administrador**): @@ -158,7 +165,7 @@ netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=$ListenPor connectaddress=$WslIp connectport=$TargetPort ``` -Permita a porta no Firewall do Windows (uma única vez): +Permita a porta no Firewall do Windows (uma vez): ```powershell New-NetFirewallRule -DisplayName "WSL SSH $ListenPort" -Direction Inbound ` @@ -175,12 +182,12 @@ netsh interface portproxy add v4tov4 listenport=$ListenPort listenaddress=0.0.0. Observações: -- O SSH a partir de outra máquina deve apontar para o **IP do host Windows** (exemplo: `ssh user@windows-host -p 2222`). -- Nós remotos precisam apontar para uma URL do Gateway **acessível** (não `127.0.0.1`); use +- O SSH de outra máquina aponta para o **IP do host Windows** (exemplo: `ssh user@windows-host -p 2222`). +- Nós remotos devem apontar para uma URL de Gateway **acessível** (não `127.0.0.1`); use `openclaw status --all` para confirmar. -- Use `listenaddress=0.0.0.0` para acesso pela LAN; `127.0.0.1` mantém o acesso apenas local. -- Se quiser isso automático, registre uma Tarefa Agendada para executar a etapa de atualização - no login. +- Use `listenaddress=0.0.0.0` para acesso pela LAN; `127.0.0.1` o mantém apenas local. +- Se quiser automatizar isso, registre uma Tarefa Agendada para executar a etapa de + atualização no login. ## Instalação passo a passo do WSL2 @@ -190,16 +197,16 @@ Abra o PowerShell (Admin): ```powershell wsl --install -# Ou escolha uma distro explicitamente: +# Ou escolha uma distribuição explicitamente: wsl --list --online wsl --install -d Ubuntu-24.04 ``` Reinicie se o Windows solicitar. -### 2) Ative o systemd (necessário para instalar o gateway) +### 2) Habilite o systemd (obrigatório para instalar o gateway) -No seu terminal WSL: +No terminal do WSL: ```bash sudo tee /etc/wsl.conf >/dev/null <<'EOF' @@ -214,7 +221,7 @@ Depois, no PowerShell: wsl --shutdown ``` -Abra o Ubuntu novamente e então verifique: +Abra o Ubuntu novamente e verifique: ```bash systemctl --user status @@ -222,20 +229,30 @@ systemctl --user status ### 3) Instale o OpenClaw (dentro do WSL) -Siga o fluxo Linux de Primeiros passos dentro do WSL: +Para uma configuração inicial normal dentro do WSL, siga o fluxo de Primeiros passos para Linux: ```bash git clone https://github.com/openclaw/openclaw.git cd openclaw pnpm install -pnpm ui:build # instala automaticamente as dependências da UI na primeira execução pnpm build -openclaw onboard +pnpm ui:build +pnpm openclaw onboard --install-daemon +``` + +Se você estiver desenvolvendo a partir do código-fonte em vez de fazer a configuração inicial, use o +fluxo de desenvolvimento a partir do código-fonte em [Configuração](/pt-BR/start/setup): + +```bash +pnpm install +# Apenas na primeira execução (ou após redefinir a configuração/workspace local do OpenClaw) +pnpm openclaw setup +pnpm gateway:watch ``` Guia completo: [Primeiros passos](/pt-BR/start/getting-started) -## App complementar para Windows +## Aplicativo complementar para Windows -Ainda não temos um app complementar para Windows. Contribuições são bem-vindas se você quiser +Ainda não temos um aplicativo complementar para Windows. Contribuições são bem-vindas se você quiser ajudar a tornar isso realidade. diff --git a/docs/pt-BR/start/setup.md b/docs/pt-BR/start/setup.md index 890d73521..7bea3e495 100644 --- a/docs/pt-BR/start/setup.md +++ b/docs/pt-BR/start/setup.md @@ -1,14 +1,14 @@ --- read_when: - Configurando uma nova máquina - - Você quer o “mais recente e melhor” sem quebrar sua configuração pessoal -summary: Fluxos avançados de configuração e desenvolvimento para o OpenClaw + - Você quer a “última e melhor” versão sem quebrar sua configuração pessoal +summary: Fluxos de trabalho avançados de configuração e desenvolvimento para OpenClaw title: Configuração x-i18n: - generated_at: "2026-04-05T12:53:40Z" + generated_at: "2026-04-20T05:41:41Z" model: gpt-5.4 provider: openai - source_hash: be4e280dde7f3a224345ca557ef2fb35a9c9db8520454ff63794ac6f8d4e71e7 + source_hash: 773cdbef5f38b069303b5e13fca5fcdc28f082746869f17b8b92aab1610b95a8 source_path: start/setup.md workflow: 15 --- @@ -16,28 +16,28 @@ x-i18n: # Configuração -Se você está configurando pela primeira vez, comece com [Primeiros passos](/pt-BR/start/getting-started). -Para detalhes de onboarding, consulte [Onboarding (CLI)](/pt-BR/start/wizard). +Se você estiver configurando pela primeira vez, comece com [Primeiros passos](/pt-BR/start/getting-started). +Para detalhes de onboarding, veja [Onboarding (CLI)](/pt-BR/start/wizard). -## Resumo +## Resumo rápido -- **As personalizações ficam fora do repositório:** `~/.openclaw/workspace` (workspace) + `~/.openclaw/openclaw.json` (configuração). -- **Fluxo estável:** instale o app macOS; deixe-o executar o Gateway empacotado. -- **Fluxo de ponta:** execute você mesmo o Gateway via `pnpm gateway:watch` e depois deixe o app macOS se conectar no modo Local. +- **A personalização fica fora do repositório:** `~/.openclaw/workspace` (workspace) + `~/.openclaw/openclaw.json` (configuração). +- **Fluxo de trabalho estável:** instale o app do macOS; deixe-o executar o Gateway incluído. +- **Fluxo de trabalho de ponta:** execute o Gateway você mesmo via `pnpm gateway:watch`, depois deixe o app do macOS se conectar no modo Local. ## Pré-requisitos (a partir do código-fonte) - Node 24 recomendado (Node 22 LTS, atualmente `22.14+`, ainda compatível) -- `pnpm` preferido (ou Bun, se você intencionalmente usar o [fluxo Bun](/pt-BR/install/bun)) -- Docker (opcional; apenas para configuração/e2e em contêiner — consulte [Docker](/pt-BR/install/docker)) +- `pnpm` preferencial (ou Bun, se você estiver usando intencionalmente o [fluxo de trabalho com Bun](/pt-BR/install/bun)) +- Docker (opcional; apenas para configuração em contêiner/e2e — veja [Docker](/pt-BR/install/docker)) -## Estratégia de personalização (para que atualizações não prejudiquem) +## Estratégia de personalização (para que as atualizações não prejudiquem) -Se você quiser “100% personalizado para mim” _e_ atualizações fáceis, mantenha sua personalização em: +Se você quer algo “100% personalizado para mim” _e_ atualizações fáceis, mantenha sua personalização em: -- **Configuração:** `~/.openclaw/openclaw.json` (JSON/estilo JSON5) -- **Workspace:** `~/.openclaw/workspace` (Skills, prompts, memórias; torne-o um repositório git privado) +- **Configuração:** `~/.openclaw/openclaw.json` (estilo JSON/JSON5) +- **Workspace:** `~/.openclaw/workspace` (Skills, prompts, memórias; transforme-o em um repositório git privado) Inicialize uma vez: @@ -51,22 +51,22 @@ De dentro deste repositório, use a entrada local da CLI: openclaw setup ``` -Se você ainda não tiver uma instalação global, execute por meio de `pnpm openclaw setup` (ou `bun run openclaw setup` se estiver usando o fluxo Bun). +Se você ainda não tiver uma instalação global, execute via `pnpm openclaw setup` (ou `bun run openclaw setup` se estiver usando o fluxo de trabalho com Bun). ## Execute o Gateway a partir deste repositório -Após `pnpm build`, você pode executar a CLI empacotada diretamente: +Depois de `pnpm build`, você pode executar a CLI empacotada diretamente: ```bash node openclaw.mjs gateway --port 18789 --verbose ``` -## Fluxo estável (app macOS primeiro) +## Fluxo de trabalho estável (app do macOS primeiro) -1. Instale e inicie o **OpenClaw.app** (barra de menu). -2. Conclua a checklist de onboarding/permissões (prompts TCC). -3. Verifique se o Gateway está em **Local** e em execução (o app o gerencia). -4. Vincule superfícies (exemplo: WhatsApp): +1. Instale e abra o **OpenClaw.app** (barra de menus). +2. Conclua a lista de verificação de onboarding/permissões (prompts do TCC). +3. Garanta que o Gateway esteja em **Local** e em execução (o app o gerencia). +4. Vincule as superfícies (exemplo: WhatsApp): ```bash openclaw channels login @@ -78,17 +78,17 @@ openclaw channels login openclaw health ``` -Se o onboarding não estiver disponível no seu build: +Se o onboarding não estiver disponível na sua build: -- Execute `openclaw setup`, depois `openclaw channels login` e então inicie o Gateway manualmente (`openclaw gateway`). +- Execute `openclaw setup`, depois `openclaw channels login`, e então inicie o Gateway manualmente (`openclaw gateway`). -## Fluxo de ponta (Gateway em um terminal) +## Fluxo de trabalho de ponta (Gateway em um terminal) -Objetivo: trabalhar no Gateway TypeScript, obter hot reload e manter a UI do app macOS conectada. +Objetivo: trabalhar no Gateway em TypeScript, obter hot reload e manter a interface do app do macOS conectada. -### 0) (Opcional) Execute também o app macOS a partir do código-fonte +### 0) (Opcional) Execute também o app do macOS a partir do código-fonte -Se você também quiser o app macOS na ponta: +Se você também quiser o app do macOS na versão de ponta: ```bash ./scripts/restart-mac.sh @@ -98,20 +98,25 @@ Se você também quiser o app macOS na ponta: ```bash pnpm install +# Apenas na primeira execução (ou após redefinir a configuração/workspace local do OpenClaw) +pnpm openclaw setup pnpm gateway:watch ``` -`gateway:watch` executa o gateway em modo watch e recarrega em mudanças relevantes de código-fonte, -configuração e metadados de plugins empacotados. +`gateway:watch` executa o gateway em modo watch e recarrega em mudanças relevantes no código-fonte, na configuração e nos metadados de plugins incluídos. +`pnpm openclaw setup` é a etapa única de inicialização da configuração/workspace local para um checkout novo. +`pnpm gateway:watch` não recompila `dist/control-ui`, então execute `pnpm ui:build` novamente após mudanças em `ui/` ou use `pnpm ui:dev` enquanto desenvolve a Control UI. -Se você estiver usando intencionalmente o fluxo Bun, os comandos equivalentes são: +Se você estiver usando intencionalmente o fluxo de trabalho com Bun, os comandos equivalentes são: ```bash bun install +# Apenas na primeira execução (ou após redefinir a configuração/workspace local do OpenClaw) +bun run openclaw setup bun run gateway:watch ``` -### 2) Aponte o app macOS para o Gateway em execução +### 2) Aponte o app do macOS para o Gateway em execução No **OpenClaw.app**: @@ -130,8 +135,8 @@ openclaw health ### Armadilhas comuns - **Porta errada:** o WS do Gateway usa por padrão `ws://127.0.0.1:18789`; mantenha app + CLI na mesma porta. -- **Onde o estado fica:** - - Estado de canal/provider: `~/.openclaw/credentials/` +- **Onde o estado fica armazenado:** + - Estado de canal/provedor: `~/.openclaw/credentials/` - Perfis de autenticação de modelo: `~/.openclaw/agents//agent/auth-profiles.json` - Sessões: `~/.openclaw/agents//sessions/` - Logs: `/tmp/openclaw/` @@ -141,39 +146,36 @@ openclaw health Use isto ao depurar autenticação ou decidir o que fazer backup: - **WhatsApp**: `~/.openclaw/credentials/whatsapp//creds.json` -- **Token do bot do Telegram**: config/env ou `channels.telegram.tokenFile` (apenas arquivo normal; symlinks rejeitados) -- **Token do bot do Discord**: config/env ou SecretRef (providers env/file/exec) -- **Tokens do Slack**: config/env (`channels.slack.*`) -- **Allowlists de pareamento**: +- **Token de bot do Telegram**: configuração/env ou `channels.telegram.tokenFile` (apenas arquivo comum; symlinks são rejeitados) +- **Token de bot do Discord**: configuração/env ou SecretRef (provedores env/file/exec) +- **Tokens do Slack**: configuração/env (`channels.slack.*`) +- **Listas de permissão de pareamento**: - `~/.openclaw/credentials/-allowFrom.json` (conta padrão) - `~/.openclaw/credentials/--allowFrom.json` (contas não padrão) - **Perfis de autenticação de modelo**: `~/.openclaw/agents//agent/auth-profiles.json` -- **Payload de segredos com suporte a arquivo (opcional)**: `~/.openclaw/secrets.json` +- **Payload de segredos com base em arquivo (opcional)**: `~/.openclaw/secrets.json` - **Importação legada de OAuth**: `~/.openclaw/credentials/oauth.json` - Mais detalhes: [Security](/pt-BR/gateway/security#credential-storage-map). + Mais detalhes: [Segurança](/pt-BR/gateway/security#credential-storage-map). ## Atualização (sem destruir sua configuração) - Mantenha `~/.openclaw/workspace` e `~/.openclaw/` como “suas coisas”; não coloque prompts/configurações pessoais no repositório `openclaw`. -- Atualizando o código-fonte: `git pull` + a etapa de instalação do gerenciador de pacotes escolhido (`pnpm install` por padrão; `bun install` para o fluxo Bun) + continue usando o comando `gateway:watch` correspondente. +- Atualizando o código-fonte: `git pull` + a etapa de instalação do gerenciador de pacotes escolhido (`pnpm install` por padrão; `bun install` para o fluxo de trabalho com Bun) + continue usando o comando `gateway:watch` correspondente. ## Linux (serviço de usuário systemd) -Instalações Linux usam um serviço de **usuário** do systemd. Por padrão, o systemd interrompe -serviços de usuário em logout/inatividade, o que derruba o Gateway. O onboarding tenta ativar -o lingering para você (pode solicitar sudo). Se ainda estiver desativado, execute: +As instalações no Linux usam um serviço **de usuário** do systemd. Por padrão, o systemd interrompe serviços de usuário em logout/inatividade, o que encerra o Gateway. O onboarding tenta ativar o lingering para você (pode solicitar sudo). Se ainda estiver desativado, execute: ```bash sudo loginctl enable-linger $USER ``` -Para servidores sempre ativos ou multiusuário, considere um serviço de **sistema** em vez de um -serviço de usuário (sem necessidade de lingering). Consulte [Runbook do Gateway](/pt-BR/gateway) para observações sobre systemd. +Para servidores sempre ativos ou com múltiplos usuários, considere usar um serviço **de sistema** em vez de um serviço de usuário (sem necessidade de lingering). Veja o [guia operacional do Gateway](/pt-BR/gateway) para as observações sobre systemd. ## Documentação relacionada -- [Runbook do Gateway](/pt-BR/gateway) (flags, supervisão, portas) +- [Guia operacional do Gateway](/pt-BR/gateway) (flags, supervisão, portas) - [Configuração do Gateway](/pt-BR/gateway/configuration) (schema de configuração + exemplos) -- [Discord](/pt-BR/channels/discord) e [Telegram](/pt-BR/channels/telegram) (tags de resposta + configurações `replyToMode`) -- [Configuração do assistente OpenClaw](/start/openclaw) -- [app macOS](/platforms/macos) (ciclo de vida do gateway) +- [Discord](/pt-BR/channels/discord) e [Telegram](/pt-BR/channels/telegram) (tags de resposta + configurações de replyToMode) +- [Configuração do assistente OpenClaw](/pt-BR/start/openclaw) +- [app do macOS](/pt-BR/platforms/macos) (ciclo de vida do gateway) diff --git a/docs/pt-BR/tools/browser.md b/docs/pt-BR/tools/browser.md index c42ea8c3d..42dd4c939 100644 --- a/docs/pt-BR/tools/browser.md +++ b/docs/pt-BR/tools/browser.md @@ -1,15 +1,15 @@ --- read_when: - - Adicionando automação de navegador controlada por agente + - Adicionando automação de navegador controlada pelo agente - Depurando por que o openclaw está interferindo no seu próprio Chrome - - Implementando configurações do navegador + ciclo de vida no app para macOS + - Implementando configurações e ciclo de vida do navegador no app do macOS summary: Serviço integrado de controle do navegador + comandos de ação title: Navegador (gerenciado pelo OpenClaw) x-i18n: - generated_at: "2026-04-14T13:04:31Z" + generated_at: "2026-04-20T05:42:07Z" model: gpt-5.4 provider: openai - source_hash: ae9ef725f544d4236d229f498c7187871c69bd18d31069b30a7e67fac53166a2 + source_hash: 3f7d37b34ba48dc7c38f8c2e77f8bb97af987eac6a874ebfc921f950fb59de4b source_path: tools/browser.md workflow: 15 --- @@ -18,24 +18,24 @@ x-i18n: O OpenClaw pode executar um **perfil dedicado do Chrome/Brave/Edge/Chromium** que o agente controla. Ele é isolado do seu navegador pessoal e é gerenciado por meio de um pequeno -serviço local de controle dentro do Gateway (somente loopback). +serviço de controle local dentro do Gateway (apenas loopback). Visão para iniciantes: - Pense nele como um **navegador separado, apenas para o agente**. -- O perfil `openclaw` **não** interfere no perfil do seu navegador pessoal. +- O perfil `openclaw` **não** toca no perfil do seu navegador pessoal. - O agente pode **abrir abas, ler páginas, clicar e digitar** em uma área segura. -- O perfil `user` integrado se conecta à sua sessão real do Chrome autenticada via Chrome MCP. +- O perfil integrado `user` se conecta à sua sessão real do Chrome com login feito via Chrome MCP. -## O que você obtém +## O que você recebe - Um perfil de navegador separado chamado **openclaw** (com destaque laranja por padrão). - Controle determinístico de abas (listar/abrir/focar/fechar). - Ações do agente (clicar/digitar/arrastar/selecionar), snapshots, capturas de tela, PDFs. -- Suporte opcional a vários perfis (`openclaw`, `work`, `remote`, ...). +- Suporte opcional a múltiplos perfis (`openclaw`, `work`, `remote`, ...). -Este navegador **não** é o seu navegador principal do dia a dia. Ele é uma superfície segura e isolada para -automação e verificação pelo agente. +Este navegador **não** é o seu navegador do dia a dia. Ele é uma superfície +segura e isolada para automação e verificação por agentes. ## Início rápido @@ -46,16 +46,16 @@ openclaw browser --browser-profile openclaw open https://example.com openclaw browser --browser-profile openclaw snapshot ``` -Se você receber “Browser disabled”, ative-o na configuração (veja abaixo) e reinicie o +Se você receber “Navegador desativado”, ative-o na configuração (veja abaixo) e reinicie o Gateway. -Se `openclaw browser` estiver ausente por completo, ou se o agente disser que a ferramenta de navegador +Se `openclaw browser` estiver totalmente ausente, ou se o agente disser que a ferramenta de navegador não está disponível, vá para [Comando ou ferramenta de navegador ausente](/pt-BR/tools/browser#missing-browser-command-or-tool). ## Controle por Plugin A ferramenta `browser` padrão agora é um Plugin incluído que vem habilitado por -padrão. Isso significa que você pode desativá-lo ou substituí-lo sem remover o restante do +padrão. Isso significa que você pode desativá-la ou substituí-la sem remover o restante do sistema de plugins do OpenClaw: ```json5 @@ -70,25 +70,25 @@ sistema de plugins do OpenClaw: } ``` -Desative o Plugin incluído antes de instalar outro Plugin que forneça o -mesmo nome de ferramenta `browser`. A experiência padrão do navegador precisa de ambos: +Desative o Plugin incluído antes de instalar outro plugin que forneça o +mesmo nome de ferramenta `browser`. A experiência padrão de navegador precisa de ambos: - `plugins.entries.browser.enabled` não desativado - `browser.enabled=true` -Se você desligar apenas o Plugin, a CLI de navegador incluída (`openclaw browser`), +Se você desativar apenas o plugin, a CLI de navegador incluída (`openclaw browser`), o método do gateway (`browser.request`), a ferramenta do agente e o serviço padrão de controle do navegador -desaparecem juntos. Sua configuração `browser.*` permanece intacta para ser reutilizada por um -Plugin substituto. +desaparecem juntos. Sua configuração `browser.*` permanece intacta para que um +plugin substituto a reutilize. -O Plugin de navegador incluído agora também é responsável pela implementação do runtime do navegador. -O core mantém apenas helpers compartilhados do Plugin SDK, além de reexports de compatibilidade para -caminhos internos de importação mais antigos. Na prática, remover ou substituir o pacote do Plugin de navegador -remove o conjunto de recursos do navegador em vez de deixar um segundo runtime controlado pelo -core para trás. +O Plugin de navegador incluído agora também é responsável pela implementação de runtime do navegador. +O núcleo mantém apenas helpers compartilhados do Plugin SDK, além de reexports de compatibilidade para +caminhos de importação internos mais antigos. Na prática, remover ou substituir o pacote do plugin de navegador +remove o conjunto de recursos do navegador, em vez de deixar para trás um segundo runtime controlado pelo +núcleo. -Alterações na configuração do navegador ainda exigem um reinício do Gateway para que o Plugin incluído -possa registrar novamente seu serviço de navegador com as novas configurações. +Alterações na configuração do navegador ainda exigem uma reinicialização do Gateway para que o Plugin incluído +registre novamente seu serviço de navegador com as novas configurações. ## Comando ou ferramenta de navegador ausente @@ -106,7 +106,7 @@ Exemplo de configuração com problema: } ``` -Corrija isso adicionando `browser` à allowlist de plugins: +Corrija adicionando `browser` à allowlist de plugins: ```json5 { @@ -118,9 +118,9 @@ Corrija isso adicionando `browser` à allowlist de plugins: Observações importantes: -- `browser.enabled=true` por si só não é suficiente quando `plugins.allow` está definido. -- `plugins.entries.browser.enabled=true` por si só também não é suficiente quando `plugins.allow` está definido. -- `tools.alsoAllow: ["browser"]` **não** carrega o Plugin de navegador incluído. Ele apenas ajusta a política da ferramenta depois que o Plugin já foi carregado. +- `browser.enabled=true` não é suficiente por si só quando `plugins.allow` está definido. +- `plugins.entries.browser.enabled=true` também não é suficiente por si só quando `plugins.allow` está definido. +- `tools.alsoAllow: ["browser"]` **não** carrega o Plugin de navegador incluído. Ele apenas ajusta a política da ferramenta depois que o plugin já foi carregado. - Se você não precisa de uma allowlist restritiva de plugins, remover `plugins.allow` também restaura o comportamento padrão do navegador incluído. Sintomas típicos: @@ -131,15 +131,16 @@ Sintomas típicos: ## Perfis: `openclaw` vs `user` -- `openclaw`: navegador gerenciado e isolado (nenhuma extensão necessária). -- `user`: perfil integrado de conexão ao Chrome MCP para sua **sessão real do Chrome autenticada**. +- `openclaw`: navegador gerenciado e isolado (não requer extensão). +- `user`: perfil integrado de conexão do Chrome MCP para sua **sessão real do Chrome** + com login feito. Para chamadas da ferramenta de navegador do agente: - Padrão: use o navegador isolado `openclaw`. -- Prefira `profile="user"` quando sessões autenticadas já existentes forem importantes e o usuário - estiver no computador para clicar/aprovar qualquer solicitação de conexão. -- `profile` é a substituição explícita quando você quiser um modo específico de navegador. +- Prefira `profile="user"` quando sessões com login já existentes forem importantes e o usuário + estiver no computador para clicar/aprovar qualquer prompt de conexão. +- `profile` é a substituição explícita quando você quer um modo específico de navegador. Defina `browser.defaultProfile: "openclaw"` se quiser o modo gerenciado por padrão. @@ -152,13 +153,13 @@ As configurações do navegador ficam em `~/.openclaw/openclaw.json`. browser: { enabled: true, // padrão: true ssrfPolicy: { - // dangerouslyAllowPrivateNetwork: true, // opte por isso apenas para acesso confiável à rede privada + // dangerouslyAllowPrivateNetwork: true, // opte por isso apenas para acesso confiável a redes privadas // allowPrivateNetwork: true, // alias legado // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], }, // cdpUrl: "http://127.0.0.1:18792", // substituição legada de perfil único - remoteCdpTimeoutMs: 1500, // tempo limite de HTTP do CDP remoto (ms) + remoteCdpTimeoutMs: 1500, // tempo limite HTTP do CDP remoto (ms) remoteCdpHandshakeTimeoutMs: 3000, // tempo limite do handshake WebSocket do CDP remoto (ms) defaultProfile: "openclaw", color: "#FF4500", @@ -188,32 +189,32 @@ As configurações do navegador ficam em `~/.openclaw/openclaw.json`. Observações: -- O serviço de controle do navegador se vincula ao loopback em uma porta derivada de `gateway.port` - (padrão: `18791`, que é a porta do gateway + 2). +- O serviço de controle do navegador faz bind em loopback em uma porta derivada de `gateway.port` + (padrão: `18791`, que é gateway + 2). - Se você substituir a porta do Gateway (`gateway.port` ou `OPENCLAW_GATEWAY_PORT`), as portas derivadas do navegador mudam para permanecer na mesma “família”. -- `cdpUrl` assume por padrão a porta CDP local gerenciada quando não está definido. -- `remoteCdpTimeoutMs` se aplica a verificações de alcance do CDP remoto (não loopback). -- `remoteCdpHandshakeTimeoutMs` se aplica a verificações de alcance do WebSocket do CDP remoto. -- A navegação/abertura de aba do navegador é protegida contra SSRF antes da navegação e verificada novamente, na medida do possível, na URL final `http(s)` após a navegação. -- No modo SSRF estrito, a descoberta/sondas de endpoint CDP remoto (`cdpUrl`, incluindo buscas em `/json/version`) também são verificadas. -- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` fica desativado por padrão. Defina-o como `true` apenas quando você confiar intencionalmente no acesso do navegador à rede privada. -- `browser.ssrfPolicy.allowPrivateNetwork` continua com suporte como alias legado para compatibilidade. -- `attachOnly: true` significa “nunca iniciar um navegador local; apenas conectar se ele já estiver em execução”. +- `cdpUrl` usa por padrão a porta CDP local gerenciada quando não definido. +- `remoteCdpTimeoutMs` se aplica a verificações de alcançabilidade do CDP remoto (não loopback). +- `remoteCdpHandshakeTimeoutMs` se aplica a verificações de alcançabilidade do WebSocket do CDP remoto. +- A navegação/abertura de aba do navegador é protegida contra SSRF antes da navegação e é verificada novamente, na medida do possível, na URL final `http(s)` após a navegação. +- No modo estrito de SSRF, a descoberta/verificação do endpoint CDP remoto (`cdpUrl`, incluindo buscas em `/json/version`) também é verificada. +- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` vem desativado por padrão. Defina-o como `true` apenas quando você confiar intencionalmente no acesso do navegador à rede privada. +- `browser.ssrfPolicy.allowPrivateNetwork` continua compatível como alias legado para compatibilidade. +- `attachOnly: true` significa “nunca iniciar um navegador local; apenas conectar se ele já estiver em execução.” - `color` + `color` por perfil tingem a interface do navegador para que você possa ver qual perfil está ativo. -- O perfil padrão é `openclaw` (navegador independente gerenciado pelo OpenClaw). Use `defaultProfile: "user"` para optar pelo navegador do usuário autenticado. -- Ordem de autodetecção: navegador padrão do sistema se for baseado em Chromium; caso contrário Chrome → Brave → Edge → Chromium → Chrome Canary. -- Perfis `openclaw` locais atribuem automaticamente `cdpPort`/`cdpUrl` — defina esses valores apenas para CDP remoto. +- O perfil padrão é `openclaw` (navegador autônomo gerenciado pelo OpenClaw). Use `defaultProfile: "user"` para optar pelo navegador do usuário com login feito. +- Ordem de detecção automática: navegador padrão do sistema, se for baseado em Chromium; caso contrário Chrome → Brave → Edge → Chromium → Chrome Canary. +- Perfis locais `openclaw` atribuem automaticamente `cdpPort`/`cdpUrl` — defina-os apenas para CDP remoto. - `driver: "existing-session"` usa Chrome DevTools MCP em vez de CDP bruto. Não defina `cdpUrl` para esse driver. - Defina `browser.profiles..userDataDir` quando um perfil existing-session precisar se conectar a um perfil de usuário Chromium não padrão, como Brave ou Edge. -## Usar Brave (ou outro navegador baseado em Chromium) +## Use Brave (ou outro navegador baseado em Chromium) Se o navegador **padrão do sistema** for baseado em Chromium (Chrome/Brave/Edge/etc), -o OpenClaw o usa automaticamente. Defina `browser.executablePath` para substituir a -autodetecção: +o OpenClaw o usará automaticamente. Defina `browser.executablePath` para substituir a +detecção automática: Exemplo de CLI: @@ -246,41 +247,41 @@ openclaw config set browser.executablePath "/usr/bin/google-chrome" ## Controle local vs remoto -- **Controle local (padrão):** o Gateway inicia o serviço de controle em loopback e pode iniciar um navegador local. -- **Controle remoto (host do node):** execute um host do node na máquina que tem o navegador; o Gateway encaminha as ações do navegador para ele. +- **Controle local (padrão):** o Gateway inicia o serviço de controle em loopback e pode abrir um navegador local. +- **Controle remoto (host Node):** execute um host Node na máquina que tem o navegador; o Gateway faz proxy das ações do navegador para ele. - **CDP remoto:** defina `browser.profiles..cdpUrl` (ou `browser.cdpUrl`) para se conectar a um navegador remoto baseado em Chromium. Nesse caso, o OpenClaw não iniciará um navegador local. -O comportamento de parada difere por modo de perfil: +O comportamento ao parar difere por modo de perfil: - perfis locais gerenciados: `openclaw browser stop` interrompe o processo do navegador que o OpenClaw iniciou -- perfis somente conexão e perfis CDP remotos: `openclaw browser stop` fecha a sessão de - controle ativa e libera as substituições de emulação do Playwright/CDP (viewport, - esquema de cores, localidade, fuso horário, modo offline e estados semelhantes), mesmo +- perfis attach-only e de CDP remoto: `openclaw browser stop` fecha a sessão de controle ativa + e libera as substituições de emulação do Playwright/CDP (viewport, + esquema de cores, localidade, fuso horário, modo offline e estado semelhante), mesmo que nenhum processo de navegador tenha sido iniciado pelo OpenClaw -As URLs de CDP remoto podem incluir autenticação: +URLs CDP remotas podem incluir autenticação: -- Tokens de query (por exemplo, `https://provider.example?token=`) +- Tokens na query (por exemplo, `https://provider.example?token=`) - Autenticação HTTP Basic (por exemplo, `https://user:pass@provider.example`) O OpenClaw preserva a autenticação ao chamar endpoints `/json/*` e ao se conectar -ao WebSocket CDP. Prefira variáveis de ambiente ou gerenciadores de segredos para -tokens em vez de registrá-los em arquivos de configuração. +ao WebSocket do CDP. Prefira variáveis de ambiente ou gerenciadores de segredos para +tokens em vez de confirmá-los em arquivos de configuração. ## Proxy de navegador do Node (padrão sem configuração) -Se você executar um **host do node** na máquina que tem o seu navegador, o OpenClaw pode -encaminhar automaticamente as chamadas da ferramenta de navegador para esse node sem nenhuma configuração adicional de navegador. -Este é o caminho padrão para gateways remotos. +Se você executar um **host Node** na máquina que tem seu navegador, o OpenClaw pode +rotear automaticamente chamadas da ferramenta de navegador para esse node sem nenhuma configuração extra do navegador. +Esse é o caminho padrão para gateways remotos. Observações: -- O host do node expõe seu servidor local de controle do navegador por meio de um **comando proxy**. -- Os perfis vêm da configuração `browser.profiles` do próprio node (igual ao local). -- `nodeHost.browserProxy.allowProfiles` é opcional. Deixe-o vazio para o comportamento legado/padrão: todos os perfis configurados continuam acessíveis por meio do proxy, incluindo rotas de criação/exclusão de perfil. -- Se você definir `nodeHost.browserProxy.allowProfiles`, o OpenClaw o trata como um limite de menor privilégio: apenas perfis na allowlist podem ser direcionados, e rotas persistentes de criação/exclusão de perfil são bloqueadas na superfície do proxy. +- O host Node expõe seu servidor local de controle do navegador por meio de um **comando proxy**. +- Os perfis vêm da própria configuração `browser.profiles` do node (igual ao local). +- `nodeHost.browserProxy.allowProfiles` é opcional. Deixe vazio para o comportamento legado/padrão: todos os perfis configurados continuam acessíveis pelo proxy, incluindo rotas de criar/excluir perfil. +- Se você definir `nodeHost.browserProxy.allowProfiles`, o OpenClaw o trata como um limite de menor privilégio: apenas perfis na allowlist podem ser usados como alvo, e rotas persistentes de criar/excluir perfil são bloqueadas na superfície do proxy. - Desative se não quiser isso: - No node: `nodeHost.browserProxy.enabled=false` - No gateway: `gateway.nodes.browser.mode="off"` @@ -314,28 +315,42 @@ Exemplo: Observações: - Substitua `` pelo seu token real do Browserless. -- Escolha o endpoint regional que corresponde à sua conta do Browserless (consulte a documentação deles). +- Escolha o endpoint de região que corresponda à sua conta Browserless (veja a documentação deles). - Se o Browserless fornecer uma URL base HTTPS, você pode convertê-la para `wss://` para uma conexão CDP direta ou manter a URL HTTPS e deixar o OpenClaw descobrir `/json/version`. -## Provedores CDP WebSocket diretos +## Provedores CDP de WebSocket direto -Alguns serviços hospedados de navegador expõem um endpoint **WebSocket direto** em vez -da descoberta CDP padrão baseada em HTTP (`/json/version`). O OpenClaw oferece suporte a ambos: +Alguns serviços de navegador hospedados expõem um endpoint **WebSocket direto** em vez +da descoberta padrão de CDP baseada em HTTP (`/json/version`). O OpenClaw aceita três +formatos de URL CDP e escolhe automaticamente a estratégia de conexão correta: -- **Endpoints HTTP(S)** — o OpenClaw chama `/json/version` para descobrir a - URL do depurador WebSocket e então se conecta. -- **Endpoints WebSocket** (`ws://` / `wss://`) — o OpenClaw se conecta diretamente, - ignorando `/json/version`. Use isso para serviços como - [Browserless](https://browserless.io), - [Browserbase](https://www.browserbase.com) ou qualquer provedor que forneça uma - URL WebSocket. +- **Descoberta por HTTP(S)** — `http://host[:port]` ou `https://host[:port]`. + O OpenClaw chama `/json/version` para descobrir a URL do depurador WebSocket e então + se conecta. Sem fallback para WebSocket. +- **Endpoints WebSocket diretos** — `ws://host[:port]/devtools//` ou + `wss://...` com um caminho `/devtools/browser|page|worker|shared_worker|service_worker/`. + O OpenClaw se conecta diretamente por um handshake WebSocket e ignora + `/json/version` por completo. +- **Raízes WebSocket simples** — `ws://host[:port]` ou `wss://host[:port]` sem + caminho `/devtools/...` (por exemplo, [Browserless](https://browserless.io), + [Browserbase](https://www.browserbase.com)). O OpenClaw tenta primeiro a descoberta HTTP + em `/json/version` (normalizando o esquema para `http`/`https`); + se a descoberta retornar um `webSocketDebuggerUrl`, ele será usado; caso contrário, o OpenClaw + recorre a um handshake WebSocket direto na raiz simples. Isso cobre + tanto portas de depuração remota no estilo Chrome quanto provedores somente WebSocket. + +`ws://host:port` / `wss://host:port` simples, sem um caminho `/devtools/...`, +apontando para uma instância local do Chrome, são compatíveis por meio do +fallback com descoberta primeiro — o Chrome só aceita upgrades WebSocket no caminho específico por navegador +ou por alvo retornado por `/json/version`, então um handshake apenas na raiz +falharia. ### Browserbase [Browserbase](https://www.browserbase.com) é uma plataforma em nuvem para executar -navegadores headless com resolução de CAPTCHA integrada, modo furtivo e +navegadores headless com resolução integrada de CAPTCHA, modo furtivo e proxies residenciais. ```json5 @@ -359,78 +374,78 @@ Observações: - [Cadastre-se](https://www.browserbase.com/sign-up) e copie sua **API Key** no [painel Overview](https://www.browserbase.com/overview). -- Substitua `` pela sua chave de API real do Browserbase. -- O Browserbase cria automaticamente uma sessão de navegador ao conectar por WebSocket, então - não é necessária nenhuma etapa manual de criação de sessão. +- Substitua `` pela sua API key real do Browserbase. +- O Browserbase cria automaticamente uma sessão de navegador na conexão WebSocket, então + não é necessária uma etapa manual de criação de sessão. - O plano gratuito permite uma sessão simultânea e uma hora de navegador por mês. - Consulte os [preços](https://www.browserbase.com/pricing) para os limites dos planos pagos. -- Consulte a [documentação do Browserbase](https://docs.browserbase.com) para a + Veja os [preços](https://www.browserbase.com/pricing) para os limites dos planos pagos. +- Veja a [documentação do Browserbase](https://docs.browserbase.com) para a referência completa da API, guias de SDK e exemplos de integração. ## Segurança Ideias principais: -- O controle do navegador é somente loopback; o acesso flui pela autenticação do Gateway ou pelo pareamento de node. -- A API HTTP de navegador em loopback independente usa **somente autenticação por segredo compartilhado**: - autenticação bearer por token do gateway, `x-openclaw-password` ou autenticação HTTP Basic com a +- O controle do navegador é apenas loopback; o acesso passa pela autenticação do Gateway ou pelo pareamento do node. +- A API HTTP autônoma do navegador em loopback usa **apenas autenticação por segredo compartilhado**: + auth bearer com token do gateway, `x-openclaw-password` ou HTTP Basic auth com a senha configurada do gateway. - Cabeçalhos de identidade do Tailscale Serve e `gateway.auth.mode: "trusted-proxy"` **não** - autenticam esta API de navegador em loopback independente. -- Se o controle do navegador estiver ativado e nenhuma autenticação por segredo compartilhado estiver configurada, o OpenClaw + autenticam esta API autônoma do navegador em loopback. +- Se o controle do navegador estiver habilitado e nenhuma autenticação por segredo compartilhado estiver configurada, o OpenClaw gera automaticamente `gateway.auth.token` na inicialização e o persiste na configuração. -- O OpenClaw **não** gera esse token automaticamente quando `gateway.auth.mode` já está em +- O OpenClaw **não** gera esse token automaticamente quando `gateway.auth.mode` já é `password`, `none` ou `trusted-proxy`. - Mantenha o Gateway e quaisquer hosts de node em uma rede privada (Tailscale); evite exposição pública. -- Trate URLs/tokens de CDP remotos como segredos; prefira variáveis de ambiente ou um gerenciador de segredos. +- Trate URLs/tokens de CDP remoto como segredos; prefira variáveis de ambiente ou um gerenciador de segredos. -Dicas de CDP remoto: +Dicas para CDP remoto: - Prefira endpoints criptografados (HTTPS ou WSS) e tokens de curta duração quando possível. - Evite incorporar tokens de longa duração diretamente em arquivos de configuração. -## Perfis (vários navegadores) +## Perfis (multi-browser) -O OpenClaw oferece suporte a vários perfis nomeados (configurações de roteamento). Os perfis podem ser: +O OpenClaw oferece suporte a múltiplos perfis nomeados (configurações de roteamento). Os perfis podem ser: -- **gerenciados pelo openclaw**: uma instância dedicada de navegador baseado em Chromium com seu próprio diretório de dados do usuário + porta CDP -- **remotos**: uma URL CDP explícita (navegador baseado em Chromium em execução em outro lugar) -- **sessão existente**: seu perfil existente do Chrome via autoconexão do Chrome DevTools MCP +- **gerenciados pelo openclaw**: uma instância dedicada de navegador baseado em Chromium com seu próprio diretório de dados de usuário + porta CDP +- **remoto**: uma URL CDP explícita (navegador baseado em Chromium em execução em outro lugar) +- **sessão existente**: seu perfil atual do Chrome via conexão automática do Chrome DevTools MCP Padrões: - O perfil `openclaw` é criado automaticamente se estiver ausente. -- O perfil `user` é integrado para conexão existing-session do Chrome MCP. -- Perfis existing-session são opt-in além de `user`; crie-os com `--driver existing-session`. -- Portas CDP locais são alocadas em **18800–18899** por padrão. +- O perfil `user` é integrado para conexão a sessão existente do Chrome MCP. +- Perfis de sessão existente são opt-in além de `user`; crie-os com `--driver existing-session`. +- As portas CDP locais são alocadas de **18800–18899** por padrão. - Excluir um perfil move seu diretório de dados local para a Lixeira. Todos os endpoints de controle aceitam `?profile=`; a CLI usa `--browser-profile`. -## Existing-session via Chrome DevTools MCP +## Sessão existente via Chrome DevTools MCP -O OpenClaw também pode se conectar a um perfil de navegador baseado em Chromium já em execução por meio do +O OpenClaw também pode se conectar a um perfil em execução de navegador baseado em Chromium por meio do servidor oficial Chrome DevTools MCP. Isso reutiliza as abas e o estado de login -já abertos nesse perfil do navegador. +já abertos nesse perfil de navegador. Referências oficiais de contexto e configuração: - [Chrome for Developers: Use Chrome DevTools MCP with your browser session](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session) -- [README do Chrome DevTools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp) +- [Chrome DevTools MCP README](https://github.com/ChromeDevTools/chrome-devtools-mcp) Perfil integrado: - `user` -Opcional: crie seu próprio perfil existing-session personalizado se quiser um +Opcional: crie seu próprio perfil personalizado de sessão existente se quiser um nome, cor ou diretório de dados do navegador diferentes. Comportamento padrão: -- O perfil integrado `user` usa autoconexão do Chrome MCP, que tem como alvo o +- O perfil integrado `user` usa conexão automática do Chrome MCP, que tem como alvo o perfil local padrão do Google Chrome. -Use `userDataDir` para Brave, Edge, Chromium ou um perfil do Chrome que não seja o padrão: +Use `userDataDir` para Brave, Edge, Chromium ou um perfil não padrão do Chrome: ```json5 { @@ -447,13 +462,13 @@ Use `userDataDir` para Brave, Edge, Chromium ou um perfil do Chrome que não sej } ``` -Então, no navegador correspondente: +Depois, no navegador correspondente: 1. Abra a página de inspeção desse navegador para depuração remota. 2. Ative a depuração remota. -3. Mantenha o navegador em execução e aprove a solicitação de conexão quando o OpenClaw se conectar. +3. Mantenha o navegador em execução e aprove o prompt de conexão quando o OpenClaw se conectar. -Páginas de inspeção comuns: +Páginas comuns de inspeção: - Chrome: `chrome://inspect/#remote-debugging` - Brave: `brave://inspect/#remote-debugging` @@ -474,62 +489,63 @@ Como é o sucesso: - `status` mostra `transport: chrome-mcp` - `status` mostra `running: true` - `tabs` lista as abas do navegador que já estão abertas -- `snapshot` retorna refs da aba ativa selecionada +- `snapshot` retorna refs da aba ao vivo selecionada O que verificar se a conexão não funcionar: - o navegador baseado em Chromium de destino está na versão `144+` -- a depuração remota está ativada na página de inspeção desse navegador +- a depuração remota está habilitada na página de inspeção desse navegador - o navegador exibiu e você aceitou o prompt de consentimento de conexão - `openclaw doctor` migra a configuração antiga de navegador baseada em extensão e verifica se - o Chrome está instalado localmente para perfis padrão de autoconexão, mas ele não pode - ativar a depuração remota do lado do navegador para você + o Chrome está instalado localmente para perfis padrão de conexão automática, mas ele não pode + habilitar a depuração remota no lado do navegador para você Uso pelo agente: -- Use `profile="user"` quando precisar do estado do navegador autenticado do usuário. -- Se você usar um perfil existing-session personalizado, passe esse nome de perfil explícito. -- Escolha esse modo apenas quando o usuário estiver no computador para aprovar o +- Use `profile="user"` quando precisar do estado do navegador do usuário com login feito. +- Se você usa um perfil personalizado de sessão existente, passe esse nome de perfil explícito. +- Escolha esse modo somente quando o usuário estiver no computador para aprovar o prompt de conexão. - o Gateway ou host de node pode iniciar `npx chrome-devtools-mcp@latest --autoConnect` Observações: -- Esse caminho tem risco maior que o perfil isolado `openclaw`, porque ele pode - agir dentro da sua sessão de navegador autenticada. +- Esse caminho apresenta risco mais alto do que o perfil isolado `openclaw`, pois pode + agir dentro da sua sessão de navegador com login feito. - O OpenClaw não inicia o navegador para esse driver; ele se conecta apenas a uma sessão existente. - O OpenClaw usa aqui o fluxo oficial `--autoConnect` do Chrome DevTools MCP. Se - `userDataDir` estiver definido, o OpenClaw o repassa para direcionar aquele diretório - explícito de dados do usuário do Chromium. -- Capturas de tela em existing-session oferecem suporte a capturas de página e capturas - de elemento com `--ref` a partir de snapshots, mas não a seletores CSS `--element`. -- Capturas de tela de página em existing-session funcionam sem Playwright via Chrome MCP. + `userDataDir` estiver definido, o OpenClaw o repassa para ter como alvo esse diretório explícito + de dados de usuário Chromium. +- Capturas de tela em sessão existente oferecem suporte a capturas de página e capturas de elemento com `--ref` + a partir de snapshots, mas não a seletores CSS `--element`. +- Capturas de tela de página em sessão existente funcionam sem Playwright via Chrome MCP. Capturas de elemento baseadas em ref (`--ref`) também funcionam ali, mas `--full-page` não pode ser combinado com `--ref` ou `--element`. -- As ações de existing-session ainda são mais limitadas que o caminho do navegador +- As ações em sessão existente ainda são mais limitadas do que no caminho de navegador gerenciado: - `click`, `type`, `hover`, `scrollIntoView`, `drag` e `select` exigem refs de snapshot em vez de seletores CSS - - `click` é apenas com botão esquerdo (sem substituições de botão ou modificadores) + - `click` é apenas com o botão esquerdo (sem substituições de botão ou modificadores) - `type` não oferece suporte a `slowly=true`; use `fill` ou `press` - `press` não oferece suporte a `delayMs` - `hover`, `scrollIntoView`, `drag`, `select`, `fill` e `evaluate` não oferecem suporte a substituições de timeout por chamada - - `select` atualmente oferece suporte a apenas um único valor -- `wait --url` em existing-session oferece suporte a padrões exatos, por substring e glob + - `select` atualmente aceita apenas um valor +- `wait --url` em sessão existente oferece suporte a padrões exatos, de substring e glob como outros drivers de navegador. `wait --load networkidle` ainda não é compatível. -- Hooks de upload em existing-session exigem `ref` ou `inputRef`, oferecem suporte a um arquivo - por vez e não oferecem suporte a direcionamento CSS `element`. -- Hooks de diálogo em existing-session não oferecem suporte a substituições de timeout. -- Alguns recursos ainda exigem o caminho do navegador gerenciado, incluindo ações - em lote, exportação em PDF, interceptação de download e `responsebody`. -- Existing-session é local ao host. Se o Chrome estiver em outra máquina ou em um - namespace de rede diferente, use CDP remoto ou um host de node. +- Hooks de upload em sessão existente exigem `ref` ou `inputRef`, aceitam um arquivo + por vez e não oferecem suporte a direcionamento de CSS `element`. +- Hooks de diálogo em sessão existente não oferecem suporte a substituições de timeout. +- Alguns recursos ainda exigem o caminho de navegador gerenciado, incluindo ações em lote, + exportação para PDF, interceptação de download e `responsebody`. +- Sessão existente pode se conectar no host selecionado ou por meio de um node de navegador conectado. Se + o Chrome estiver em outro lugar e nenhum node de navegador estiver conectado, use + CDP remoto ou um host de node. ## Garantias de isolamento -- **Diretório de dados do usuário dedicado**: nunca toca o perfil do seu navegador pessoal. +- **Diretório dedicado de dados do usuário**: nunca toca no perfil do seu navegador pessoal. - **Portas dedicadas**: evita `9222` para prevenir colisões com fluxos de trabalho de desenvolvimento. - **Controle determinístico de abas**: direciona abas por `targetId`, não pela “última aba”. @@ -549,11 +565,11 @@ Plataformas: - macOS: verifica `/Applications` e `~/Applications`. - Linux: procura `google-chrome`, `brave`, `microsoft-edge`, `chromium` etc. -- Windows: verifica locais de instalação comuns. +- Windows: verifica locais comuns de instalação. ## API de controle (opcional) -Somente para integrações locais, o Gateway expõe uma pequena API HTTP em loopback: +Apenas para integrações locais, o Gateway expõe uma pequena API HTTP em loopback: - Status/iniciar/parar: `GET /`, `POST /start`, `POST /stop` - Abas: `GET /tabs`, `POST /tabs/open`, `POST /tabs/focus`, `DELETE /tabs/:targetId` @@ -573,19 +589,19 @@ Todos os endpoints aceitam `?profile=`. Se a autenticação do gateway por segredo compartilhado estiver configurada, as rotas HTTP do navegador também exigirão autenticação: - `Authorization: Bearer ` -- `x-openclaw-password: ` ou autenticação HTTP Basic com essa senha +- `x-openclaw-password: ` ou HTTP Basic auth com essa senha Observações: -- Esta API de navegador em loopback independente **não** consome `trusted-proxy` nem - cabeçalhos de identidade do Tailscale Serve. +- Esta API autônoma do navegador em loopback **não** consome cabeçalhos de identidade de trusted-proxy ou + Tailscale Serve. - Se `gateway.auth.mode` for `none` ou `trusted-proxy`, essas rotas de navegador em loopback - não herdam esses modos baseados em identidade; mantenha-as somente em loopback. + não herdam esses modos com identidade; mantenha-as apenas em loopback. ### Contrato de erro de `/act` -`POST /act` usa uma resposta de erro estruturada para falhas de validação e -política no nível da rota: +`POST /act` usa uma resposta de erro estruturada para validação em nível de rota e +falhas de política: ```json { "error": "", "code": "ACT_*" } @@ -596,45 +612,45 @@ Valores atuais de `code`: - `ACT_KIND_REQUIRED` (HTTP 400): `kind` está ausente ou não é reconhecido. - `ACT_INVALID_REQUEST` (HTTP 400): o payload da ação falhou na normalização ou validação. - `ACT_SELECTOR_UNSUPPORTED` (HTTP 400): `selector` foi usado com um tipo de ação não compatível. -- `ACT_EVALUATE_DISABLED` (HTTP 403): `evaluate` (ou `wait --fn`) está desativado pela configuração. -- `ACT_TARGET_ID_MISMATCH` (HTTP 403): `targetId` no nível superior ou em lote entra em conflito com o alvo da solicitação. -- `ACT_EXISTING_SESSION_UNSUPPORTED` (HTTP 501): a ação não é compatível com perfis existing-session. +- `ACT_EVALUATE_DISABLED` (HTTP 403): `evaluate` (ou `wait --fn`) está desabilitado por configuração. +- `ACT_TARGET_ID_MISMATCH` (HTTP 403): `targetId` de nível superior ou em lote entra em conflito com o alvo da solicitação. +- `ACT_EXISTING_SESSION_UNSUPPORTED` (HTTP 501): a ação não é compatível com perfis de sessão existente. -Outras falhas em runtime ainda podem retornar `{ "error": "" }` sem um +Outras falhas de runtime ainda podem retornar `{ "error": "" }` sem um campo `code`. ### Requisito do Playwright Alguns recursos (navigate/act/AI snapshot/role snapshot, capturas de tela de elementos, -PDF) exigem Playwright. Se o Playwright não estiver instalado, esses endpoints retornarão +PDF) exigem Playwright. Se o Playwright não estiver instalado, esses endpoints retornam um erro 501 claro. O que ainda funciona sem Playwright: - Snapshots ARIA - Capturas de tela de página para o navegador `openclaw` gerenciado quando um WebSocket - CDP por aba estiver disponível + CDP por aba está disponível - Capturas de tela de página para perfis `existing-session` / Chrome MCP -- Capturas de tela baseadas em `--ref` em `existing-session` a partir da saída de snapshot +- Capturas de tela baseadas em ref (`--ref`) em `existing-session` a partir da saída de snapshot -O que ainda precisa de Playwright: +O que ainda exige Playwright: - `navigate` - `act` - AI snapshots / role snapshots -- Capturas de tela de elemento por seletor CSS (`--element`) +- Capturas de tela de elementos por seletor CSS (`--element`) - Exportação completa de PDF do navegador -Capturas de tela de elemento também rejeitam `--full-page`; a rota retorna `fullPage is +Capturas de tela de elementos também rejeitam `--full-page`; a rota retorna `fullPage is not supported for element screenshots`. -Se você vir `Playwright is not available in this gateway build`, instale o pacote completo do -Playwright (não `playwright-core`) e reinicie o gateway, ou reinstale o +Se você vir `Playwright is not available in this gateway build`, instale o pacote completo +do Playwright (não `playwright-core`) e reinicie o gateway, ou reinstale o OpenClaw com suporte a navegador. #### Instalação do Playwright no Docker -Se o seu Gateway estiver em execução no Docker, evite `npx playwright` (conflitos de override do npm). +Se o seu Gateway for executado no Docker, evite `npx playwright` (conflitos com overrides do npm). Use a CLI incluída: ```bash @@ -642,26 +658,26 @@ docker compose run --rm openclaw-cli \ node /app/node_modules/playwright-core/cli.js install chromium ``` -Para persistir os downloads do navegador, defina `PLAYWRIGHT_BROWSERS_PATH` (por exemplo, +Para persistir downloads de navegador, defina `PLAYWRIGHT_BROWSERS_PATH` (por exemplo, `/home/node/.cache/ms-playwright`) e garanta que `/home/node` seja persistido via `OPENCLAW_HOME_VOLUME` ou um bind mount. Veja [Docker](/pt-BR/install/docker). -## Como funciona (internamente) +## Como funciona (interno) -Fluxo de alto nível: +Fluxo em alto nível: -- Um pequeno **servidor de controle** aceita requisições HTTP. +- Um pequeno **servidor de controle** aceita solicitações HTTP. - Ele se conecta a navegadores baseados em Chromium (Chrome/Brave/Edge/Chromium) via **CDP**. -- Para ações avançadas (clicar/digitar/snapshot/PDF), ele usa **Playwright** sobre +- Para ações avançadas (click/type/snapshot/PDF), ele usa **Playwright** sobre o CDP. -- Quando o Playwright está ausente, apenas operações que não usam Playwright ficam disponíveis. +- Quando o Playwright está ausente, apenas operações sem Playwright ficam disponíveis. Esse design mantém o agente em uma interface estável e determinística, ao mesmo tempo em que permite trocar navegadores e perfis locais/remotos. ## Referência rápida da CLI -Todos os comandos aceitam `--browser-profile ` para direcionar um perfil específico. +Todos os comandos aceitam `--browser-profile ` para direcionar a um perfil específico. Todos os comandos também aceitam `--json` para saída legível por máquina (payloads estáveis). Básico: @@ -695,8 +711,8 @@ Inspeção: Observação sobre ciclo de vida: -- Para perfis somente conexão e perfis CDP remotos, `openclaw browser stop` ainda é o - comando correto de limpeza após testes. Ele fecha a sessão de controle ativa e +- Para perfis attach-only e de CDP remoto, `openclaw browser stop` ainda é o + comando de limpeza correto após testes. Ele fecha a sessão de controle ativa e limpa substituições temporárias de emulação em vez de encerrar o navegador subjacente. - `openclaw browser errors --clear` @@ -749,47 +765,47 @@ Estado: Observações: -- `upload` e `dialog` são chamadas de **preparação**; execute-as antes do clique/pressionamento +- `upload` e `dialog` são chamadas de **preparação**; execute-as antes do click/press que aciona o seletor/diálogo. -- Os caminhos de saída de download e trace são restritos às raízes temporárias do OpenClaw: +- Os caminhos de saída de download e trace são limitados às raízes temporárias do OpenClaw: - traces: `/tmp/openclaw` (fallback: `${os.tmpdir()}/openclaw`) - downloads: `/tmp/openclaw/downloads` (fallback: `${os.tmpdir()}/openclaw/downloads`) -- Os caminhos de upload são restritos a uma raiz temporária de uploads do OpenClaw: +- Os caminhos de upload são limitados a uma raiz temporária de uploads do OpenClaw: - uploads: `/tmp/openclaw/uploads` (fallback: `${os.tmpdir()}/openclaw/uploads`) -- `upload` também pode definir diretamente entradas de arquivo via `--input-ref` ou `--element`. +- `upload` também pode definir inputs de arquivo diretamente por `--input-ref` ou `--element`. - `snapshot`: - - `--format ai` (padrão quando o Playwright está instalado): retorna um snapshot de IA com refs numéricos (`aria-ref=""`). + - `--format ai` (padrão quando o Playwright está instalado): retorna um AI snapshot com refs numéricos (`aria-ref=""`). - `--format aria`: retorna a árvore de acessibilidade (sem refs; apenas inspeção). - - `--efficient` (ou `--mode efficient`): preset compacto de snapshot por role (interactive + compact + depth + maxChars menor). + - `--efficient` (ou `--mode efficient`): preset compacto de role snapshot (interactive + compact + depth + maxChars menor). - Padrão de configuração (somente ferramenta/CLI): defina `browser.snapshotDefaults.mode: "efficient"` para usar snapshots eficientes quando o chamador não passar um modo (veja [Configuração do Gateway](/pt-BR/gateway/configuration-reference#browser)). - - Opções de snapshot por role (`--interactive`, `--compact`, `--depth`, `--selector`) forçam um snapshot baseado em role com refs como `ref=e12`. - - `--frame "