chore(i18n): refresh pt-BR translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
2ea29d1a46
commit
741e5b4089
@ -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.
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Pareamento" icon="link" href="/channels/pairing">
|
||||
A política padrão de DM para Telegram é `pairing`.
|
||||
<Card title="Pareamento" icon="link" href="/pt-BR/channels/pairing">
|
||||
A política padrão de DM para Telegram é pareamento.
|
||||
</Card>
|
||||
<Card title="Solução de problemas de canais" icon="wrench" href="/channels/troubleshooting">
|
||||
<Card title="Solução de problemas do canal" icon="wrench" href="/pt-BR/channels/troubleshooting">
|
||||
Diagnósticos entre canais e playbooks de reparo.
|
||||
</Card>
|
||||
<Card title="Configuração do Gateway" icon="settings" href="/gateway/configuration">
|
||||
Padrões completos de configuração de canal e exemplos.
|
||||
<Card title="Configuração do Gateway" icon="settings" href="/pt-BR/gateway/configuration">
|
||||
Padrões e exemplos completos de configuração de canal.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -34,7 +34,7 @@ Status: pronto para produção para DMs de bot + grupos via grammY. Long polling
|
||||
<Step title="Crie o token do bot no BotFather">
|
||||
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.
|
||||
|
||||
</Step>
|
||||
|
||||
@ -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.
|
||||
|
||||
</Step>
|
||||
@ -66,31 +66,31 @@ openclaw pairing list telegram
|
||||
openclaw pairing approve telegram <CODE>
|
||||
```
|
||||
|
||||
Códigos de pareamento expiram após 1 hora.
|
||||
Os códigos de pareamento expiram após 1 hora.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Adicione o bot a um grupo">
|
||||
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.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
## Configurações do lado do Telegram
|
||||
## Configurações no lado do Telegram
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Modo de privacidade e visibilidade em grupos">
|
||||
Bots do Telegram usam **Modo de Privacidade** por padrão, o que limita quais mensagens de grupo eles recebem.
|
||||
|
||||
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.
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -103,8 +103,8 @@ A ordem de resolução do token reconhece contas. Na prática, valores em config
|
||||
|
||||
<Accordion title="Alternâncias úteis do BotFather">
|
||||
|
||||
- `/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
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -113,24 +113,24 @@ A ordem de resolução do token reconhece contas. Na prática, valores em config
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Política de DM">
|
||||
`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<bot_token>/getUpdates"
|
||||
@ -151,28 +151,28 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
</Tab>
|
||||
|
||||
<Tab title="Política de grupo e allowlists">
|
||||
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<bot_token>/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.
|
||||
</Warning>
|
||||
|
||||
</Tab>
|
||||
@ -228,12 +228,12 @@ curl "https://api.telegram.org/bot<bot_token>/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<bot_token>/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
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## 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:<threadId>` 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:<threadId>` 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<bot_token>/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
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Formatação e fallback para HTML">
|
||||
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`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -317,17 +317,17 @@ curl "https://api.telegram.org/bot<bot_token>/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<bot_token>/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 <requestId>` para aprovação explícita
|
||||
- `/pair approve` quando houver apenas uma solicitação pendente
|
||||
- `/pair approve latest` para a mais recente
|
||||
|
||||
O código de configuração carrega um token 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).
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -414,7 +414,7 @@ curl "https://api.telegram.org/bot<bot_token>/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<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Cliques de callback são passados ao agente como texto:
|
||||
Cliques em callback são passados ao agente como texto:
|
||||
`callback_data: <value>`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Ações de mensagem do Telegram para agentes e automação">
|
||||
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)
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -481,11 +481,11 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Tópicos de fórum e comportamento de thread">
|
||||
Supergrupos com fórum:
|
||||
Supergrupos de fórum:
|
||||
|
||||
- chaves de sessão de tópico acrescentam `:topic:<threadId>`
|
||||
- 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:<threadId>`
|
||||
- respostas e indicadores de digitação têm como destino a thread do tópico
|
||||
- caminho de config do tópico:
|
||||
`channels.telegram.groups.<chatId>.topics.<threadId>`
|
||||
|
||||
Caso especial do tópico geral (`threadId=1`):
|
||||
@ -493,10 +493,10 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- envios de mensagem omitem `message_thread_id` (o Telegram rejeita `sendMessage(...thread_id=1)`)
|
||||
- ações de digitação ainda incluem `message_thread_id`
|
||||
|
||||
Herança de tó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<bot_token>/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<bot_token>/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<bot_token>/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 <agent> --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<bot_token>/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.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Áudio, vídeo e stickers">
|
||||
### 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<bot_token>/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<bot_token>/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 `<media:sticker>`)
|
||||
- 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<bot_token>/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<bot_token>/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.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Reações de confirmação">
|
||||
`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.<accountId>.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.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Gravações de config a partir de eventos e comandos do Telegram">
|
||||
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<bot_token>/getUpdates"
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Long polling vs webhook">
|
||||
<Accordion title="Long polling vs Webhook">
|
||||
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<bot_token>/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.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Limites, nova tentativa e alvos da CLI">
|
||||
<Accordion title="Limites, tentativas e destinos da CLI">
|
||||
- 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["<user_id>"].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
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Aprovações de exec no Telegram">
|
||||
O Telegram oferece suporte a aprovações de exec em DMs de aprovadores e pode opcionalmente publicar prompts 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)
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 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
|
||||
<AccordionGroup>
|
||||
<Accordion title="O bot não responde a mensagens de grupo sem menção">
|
||||
|
||||
- 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`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="O bot não está vendo mensagens de grupo de forma alguma">
|
||||
|
||||
- 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
|
||||
|
||||
</Accordion>
|
||||
@ -912,18 +913,18 @@ Substituições por conta, por grupo e por tópico são compatíveis (mesma hera
|
||||
<Accordion title="Os comandos funcionam parcialmente ou não funcionam">
|
||||
|
||||
- autorize sua identidade de remetente (pareamento e/ou `allowFrom` numérico)
|
||||
- a autorização de comandos ainda se aplica mesmo quando a política de grupo é `open`
|
||||
- `setMyCommands failed` com `BOT_COMMANDS_TOO_MUCH` significa que o menu nativo tem entradas demais; reduza comandos 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`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Instabilidade de polling ou de rede">
|
||||
|
||||
- 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://<user>:<password>@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.<accountId>.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.
|
||||
|
||||
<Warning>
|
||||
`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.
|
||||
</Warning>
|
||||
|
||||
- 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
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
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.<id>.groupPolicy`: substituição por grupo para `groupPolicy` (`open | allowlist | disabled`).
|
||||
- `channels.telegram.groups.<id>.requireMention`: padrão de bloqueio por menção.
|
||||
- `channels.telegram.groups.<id>.groupPolicy`: substituição por grupo para groupPolicy (`open | allowlist | disabled`).
|
||||
- `channels.telegram.groups.<id>.requireMention`: gate padrão de menção.
|
||||
- `channels.telegram.groups.<id>.skills`: filtro de Skills (omitir = todas as Skills, vazio = nenhuma).
|
||||
- `channels.telegram.groups.<id>.allowFrom`: substituição por grupo para allowlist de remetentes.
|
||||
- `channels.telegram.groups.<id>.allowFrom`: substituição da allowlist de remetentes por grupo.
|
||||
- `channels.telegram.groups.<id>.systemPrompt`: prompt de sistema extra para o grupo.
|
||||
- `channels.telegram.groups.<id>.enabled`: desativa o grupo quando `false`.
|
||||
- `channels.telegram.groups.<id>.topics.<threadId>.*`: substituições por tópico (campos de grupo + `agentId` exclusivo de tópico).
|
||||
- `channels.telegram.groups.<id>.topics.<threadId>.agentId`: roteia este tópico para um agente específico (substitui o roteamento de nível de grupo e por binding).
|
||||
- `channels.telegram.groups.<id>.topics.<threadId>.groupPolicy`: substituição por tópico para `groupPolicy` (`open | allowlist | disabled`).
|
||||
- `channels.telegram.groups.<id>.topics.<threadId>.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.<id>.topics.<threadId>.*`: substituições por tópico (campos de grupo + `agentId` exclusivo do tópico).
|
||||
- `channels.telegram.groups.<id>.topics.<threadId>.agentId`: roteia este tópico para um agente específico (substitui o roteamento no nível de grupo e por binding).
|
||||
- `channels.telegram.groups.<id>.topics.<threadId>.groupPolicy`: substituição por tópico para groupPolicy (`open | allowlist | disabled`).
|
||||
- `channels.telegram.groups.<id>.topics.<threadId>.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.<id>.topics.<threadId>.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.<account>.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.<account>.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.<account>.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)
|
||||
|
||||
@ -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=<path>` 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=<path>` 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 <count>` 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 <count>` 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/<theme>/*.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=<level>`. `--thinking <level>` ainda define um fallback global, e o formato mais antigo `--model-thinking <provider/model=level>` é 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=<level>`. `--thinking <level>` ainda define um
|
||||
fallback global, e o formato antigo `--model-thinking <provider/model=level>` é
|
||||
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`.
|
||||
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@ -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.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="macOS / Linux / WSL2">
|
||||
@ -33,7 +33,7 @@ A forma mais rápida de instalar. Ele detecta seu sistema operacional, instala o
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
Para instalar sem executar o onboarding:
|
||||
Para instalar sem executar a integração inicial:
|
||||
|
||||
<Tabs>
|
||||
<Tab title="macOS / Linux / WSL2">
|
||||
@ -48,27 +48,27 @@ Para instalar sem executar o onboarding:
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
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:
|
||||
```
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
</Tab>
|
||||
@ -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
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Docker" href="/install/docker" icon="container">
|
||||
Implantações conteinerizadas ou headless.
|
||||
<Card title="Docker" href="/pt-BR/install/docker" icon="container">
|
||||
Implantações em contêiner ou sem interface.
|
||||
</Card>
|
||||
<Card title="Podman" href="/install/podman" icon="container">
|
||||
Alternativa de contêiner rootless ao Docker.
|
||||
<Card title="Podman" href="/pt-BR/install/podman" icon="container">
|
||||
Alternativa de contêiner sem root ao Docker.
|
||||
</Card>
|
||||
<Card title="Nix" href="/install/nix" icon="snowflake">
|
||||
<Card title="Nix" href="/pt-BR/install/nix" icon="snowflake">
|
||||
Instalação declarativa via flake do Nix.
|
||||
</Card>
|
||||
<Card title="Ansible" href="/install/ansible" icon="server">
|
||||
<Card title="Ansible" href="/pt-BR/install/ansible" icon="server">
|
||||
Provisionamento automatizado de frota.
|
||||
</Card>
|
||||
<Card title="Bun" href="/install/bun" icon="zap">
|
||||
Uso somente da CLI via runtime Bun.
|
||||
<Card title="Bun" href="/pt-BR/install/bun" icon="zap">
|
||||
Uso somente da CLI com o runtime Bun.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## 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:
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="VPS" href="/vps">Qualquer VPS Linux</Card>
|
||||
<Card title="Docker VM" href="/install/docker-vm-runtime">Etapas compartilhadas do Docker</Card>
|
||||
<Card title="Kubernetes" href="/install/kubernetes">K8s</Card>
|
||||
<Card title="Fly.io" href="/install/fly">Fly.io</Card>
|
||||
<Card title="Hetzner" href="/install/hetzner">Hetzner</Card>
|
||||
<Card title="GCP" href="/install/gcp">Google Cloud</Card>
|
||||
<Card title="Azure" href="/install/azure">Azure</Card>
|
||||
<Card title="Railway" href="/install/railway">Railway</Card>
|
||||
<Card title="Render" href="/install/render">Render</Card>
|
||||
<Card title="Northflank" href="/install/northflank">Northflank</Card>
|
||||
<Card title="VPS" href="/pt-BR/vps">Qualquer VPS Linux</Card>
|
||||
<Card title="Docker VM" href="/pt-BR/install/docker-vm-runtime">Etapas compartilhadas do Docker</Card>
|
||||
<Card title="Kubernetes" href="/pt-BR/install/kubernetes">K8s</Card>
|
||||
<Card title="Fly.io" href="/pt-BR/install/fly">Fly.io</Card>
|
||||
<Card title="Hetzner" href="/pt-BR/install/hetzner">Hetzner</Card>
|
||||
<Card title="GCP" href="/pt-BR/install/gcp">Google Cloud</Card>
|
||||
<Card title="Azure" href="/pt-BR/install/azure">Azure</Card>
|
||||
<Card title="Railway" href="/pt-BR/install/railway">Railway</Card>
|
||||
<Card title="Render" href="/pt-BR/install/render">Render</Card>
|
||||
<Card title="Northflank" href="/pt-BR/install/northflank">Northflank</Card>
|
||||
</CardGroup>
|
||||
|
||||
## Atualizar, migrar ou desinstalar
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Atualização" href="/install/updating" icon="refresh-cw">
|
||||
<Card title="Atualização" href="/pt-BR/install/updating" icon="refresh-cw">
|
||||
Mantenha o OpenClaw atualizado.
|
||||
</Card>
|
||||
<Card title="Migração" href="/install/migrating" icon="arrow-right">
|
||||
Mude para uma nova máquina.
|
||||
<Card title="Migração" href="/pt-BR/install/migrating" icon="arrow-right">
|
||||
Mova para uma nova máquina.
|
||||
</Card>
|
||||
<Card title="Desinstalar" href="/install/uninstall" icon="trash-2">
|
||||
<Card title="Desinstalar" href="/pt-BR/install/uninstall" icon="trash-2">
|
||||
Remova o OpenClaw completamente.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## 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.
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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
|
||||
|
||||
<Note>
|
||||
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).
|
||||
</Note>
|
||||
|
||||
## 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/<agentId>/agent/auth-profiles.json`
|
||||
- Sessões: `~/.openclaw/agents/<agentId>/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/<accountId>/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/<channel>-allowFrom.json` (conta padrão)
|
||||
- `~/.openclaw/credentials/<channel>-<accountId>-allowFrom.json` (contas não padrão)
|
||||
- **Perfis de autenticação de modelo**: `~/.openclaw/agents/<agentId>/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)
|
||||
|
||||
@ -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.<name>.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.<name>.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=<token>`)
|
||||
- Tokens na query (por exemplo, `https://provider.example?token=<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 `<BROWSERLESS_API_KEY>` 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/<kind>/<id>` ou
|
||||
`wss://...` com um caminho `/devtools/browser|page|worker|shared_worker|service_worker/<id>`.
|
||||
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 `<BROWSERBASE_API_KEY>` 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 `<BROWSERBASE_API_KEY>` 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=<name>`; 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=<name>`.
|
||||
Se a autenticação do gateway por segredo compartilhado estiver configurada, as rotas HTTP do navegador também exigirão autenticação:
|
||||
|
||||
- `Authorization: Bearer <gateway token>`
|
||||
- `x-openclaw-password: <gateway password>` ou autenticação HTTP Basic com essa senha
|
||||
- `x-openclaw-password: <gateway 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": "<message>", "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": "<message>" }` sem um
|
||||
Outras falhas de runtime ainda podem retornar `{ "error": "<message>" }` 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 <name>` para direcionar um perfil específico.
|
||||
Todos os comandos aceitam `--browser-profile <name>` 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="<n>"`).
|
||||
- `--format ai` (padrão quando o Playwright está instalado): retorna um AI snapshot com refs numéricos (`aria-ref="<n>"`).
|
||||
- `--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 "<iframe selector>"` limita snapshots por role a um iframe (em conjunto com refs por role como `e12`).
|
||||
- `--interactive` produz uma lista plana e fácil de escolher de elementos interativos (melhor para executar ações).
|
||||
- `--labels` adiciona uma captura de tela somente da viewport com labels de ref sobrepostos (imprime `MEDIA:<path>`).
|
||||
- `click`/`type`/etc exigem um `ref` de `snapshot` (seja numérico `12` ou ref por role `e12`).
|
||||
- Opções de role snapshot (`--interactive`, `--compact`, `--depth`, `--selector`) forçam um snapshot baseado em função com refs como `ref=e12`.
|
||||
- `--frame "<iframe selector>"` limita role snapshots a um iframe (pareado com refs de função como `e12`).
|
||||
- `--interactive` produz uma lista plana e fácil de escolher de elementos interativos (melhor para conduzir ações).
|
||||
- `--labels` adiciona uma captura de tela somente da viewport com rótulos de ref sobrepostos (imprime `MEDIA:<path>`).
|
||||
- `click`/`type`/etc exigem um `ref` de `snapshot` (numérico `12` ou ref de função `e12`).
|
||||
Seletores CSS intencionalmente não são compatíveis para ações.
|
||||
|
||||
## Snapshots e refs
|
||||
|
||||
O OpenClaw oferece suporte a dois estilos de “snapshot”:
|
||||
|
||||
- **Snapshot de IA (refs numéricos)**: `openclaw browser snapshot` (padrão; `--format ai`)
|
||||
- Saída: um snapshot de texto que inclui refs numéricos.
|
||||
- **AI snapshot (refs numéricos)**: `openclaw browser snapshot` (padrão; `--format ai`)
|
||||
- Saída: um snapshot em texto que inclui refs numéricos.
|
||||
- Ações: `openclaw browser click 12`, `openclaw browser type 23 "hello"`.
|
||||
- Internamente, o ref é resolvido via `aria-ref` do Playwright.
|
||||
|
||||
- **Snapshot por role (refs por role como `e12`)**: `openclaw browser snapshot --interactive` (ou `--compact`, `--depth`, `--selector`, `--frame`)
|
||||
- Saída: uma lista/árvore baseada em role com `[ref=e12]` (e opcionalmente `[nth=1]`).
|
||||
- **Role snapshot (refs de função como `e12`)**: `openclaw browser snapshot --interactive` (ou `--compact`, `--depth`, `--selector`, `--frame`)
|
||||
- Saída: uma lista/árvore baseada em função com `[ref=e12]` (e opcionalmente `[nth=1]`).
|
||||
- Ações: `openclaw browser click e12`, `openclaw browser highlight e12`.
|
||||
- Internamente, o ref é resolvido via `getByRole(...)` (mais `nth()` para duplicatas).
|
||||
- Adicione `--labels` para incluir uma captura de tela da viewport com labels `e12` sobrepostos.
|
||||
- Adicione `--labels` para incluir uma captura de tela da viewport com rótulos `e12` sobrepostos.
|
||||
|
||||
Comportamento dos refs:
|
||||
|
||||
- Refs **não são estáveis entre navegações**; se algo falhar, execute `snapshot` novamente e use um ref novo.
|
||||
- Se o snapshot por role foi feito com `--frame`, os refs por role ficam limitados àquele iframe até o próximo snapshot por role.
|
||||
- Se o role snapshot foi feito com `--frame`, os refs de função ficam limitados a esse iframe até o próximo role snapshot.
|
||||
|
||||
## Recursos avançados de espera
|
||||
## Recursos avançados de wait
|
||||
|
||||
Você pode esperar por mais do que apenas tempo/texto:
|
||||
|
||||
@ -799,10 +815,10 @@ Você pode esperar por mais do que apenas tempo/texto:
|
||||
- `openclaw browser wait --load networkidle`
|
||||
- Esperar por um predicado JS:
|
||||
- `openclaw browser wait --fn "window.ready===true"`
|
||||
- Esperar por um seletor ficar visível:
|
||||
- Esperar um seletor ficar visível:
|
||||
- `openclaw browser wait "#main"`
|
||||
|
||||
Eles podem ser combinados:
|
||||
Esses podem ser combinados:
|
||||
|
||||
```bash
|
||||
openclaw browser wait "#main" \
|
||||
@ -814,15 +830,15 @@ openclaw browser wait "#main" \
|
||||
|
||||
## Fluxos de depuração
|
||||
|
||||
Quando uma ação falhar (por exemplo, “not visible”, “strict mode violation”, “covered”):
|
||||
Quando uma ação falha (por exemplo, “not visible”, “strict mode violation”, “covered”):
|
||||
|
||||
1. `openclaw browser snapshot --interactive`
|
||||
2. Use `click <ref>` / `type <ref>` (prefira refs por role no modo interativo)
|
||||
2. Use `click <ref>` / `type <ref>` (prefira refs de função no modo interativo)
|
||||
3. Se ainda falhar: `openclaw browser highlight <ref>` para ver o que o Playwright está direcionando
|
||||
4. Se a página se comportar de forma estranha:
|
||||
- `openclaw browser errors --clear`
|
||||
- `openclaw browser requests --filter api --clear`
|
||||
5. Para depuração profunda: grave um trace:
|
||||
5. Para depuração aprofundada: grave um trace:
|
||||
- `openclaw browser trace start`
|
||||
- reproduza o problema
|
||||
- `openclaw browser trace stop` (imprime `TRACE:<path>`)
|
||||
@ -840,7 +856,7 @@ openclaw browser requests --filter api --json
|
||||
openclaw browser cookies --json
|
||||
```
|
||||
|
||||
Snapshots por role em JSON incluem `refs` mais um pequeno bloco `stats` (lines/chars/refs/interactive) para que ferramentas possam raciocinar sobre tamanho e densidade do payload.
|
||||
Role snapshots em JSON incluem `refs` mais um pequeno bloco `stats` (lines/chars/refs/interactive) para que ferramentas possam raciocinar sobre tamanho e densidade do payload.
|
||||
|
||||
## Controles de estado e ambiente
|
||||
|
||||
@ -850,7 +866,7 @@ Eles são úteis para fluxos de trabalho do tipo “faça o site se comportar co
|
||||
- Storage: `storage local|session get|set|clear`
|
||||
- Offline: `set offline on|off`
|
||||
- Headers: `set headers --headers-json '{"X-Debug":"1"}'` (o legado `set headers --json '{"X-Debug":"1"}'` continua compatível)
|
||||
- Autenticação HTTP Basic: `set credentials user pass` (ou `--clear`)
|
||||
- HTTP basic auth: `set credentials user pass` (ou `--clear`)
|
||||
- Geolocalização: `set geo <lat> <lon> --origin "https://example.com"` (ou `--clear`)
|
||||
- Mídia: `set media dark|light|no-preference|none`
|
||||
- Fuso horário / localidade: `set timezone ...`, `set locale ...`
|
||||
@ -860,15 +876,15 @@ Eles são úteis para fluxos de trabalho do tipo “faça o site se comportar co
|
||||
|
||||
## Segurança e privacidade
|
||||
|
||||
- O perfil de navegador openclaw pode conter sessões autenticadas; trate-o como sensível.
|
||||
- O perfil de navegador openclaw pode conter sessões com login feito; trate-o como sensível.
|
||||
- `browser act kind=evaluate` / `openclaw browser evaluate` e `wait --fn`
|
||||
executam JavaScript arbitrário no contexto da página. Injeção de prompt pode direcionar
|
||||
executam JavaScript arbitrário no contexto da página. Injeção de prompt pode influenciar
|
||||
isso. Desative com `browser.evaluateEnabled=false` se você não precisar disso.
|
||||
- Para logins e observações sobre anti-bot (X/Twitter etc.), veja [Login no navegador + postagem no X/Twitter](/pt-BR/tools/browser-login).
|
||||
- Para logins e observações anti-bot (X/Twitter etc.), veja [Login no navegador + postagem no X/Twitter](/pt-BR/tools/browser-login).
|
||||
- Mantenha o Gateway/host de node privado (somente loopback ou tailnet).
|
||||
- Endpoints CDP remotos são poderosos; faça tunnel e proteja-os.
|
||||
- Endpoints CDP remotos são poderosos; faça túnel e proteja-os.
|
||||
|
||||
Exemplo de modo estrito (bloquear destinos privados/internos por padrão):
|
||||
Exemplo de modo estrito (bloqueia destinos privados/internos por padrão):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -876,7 +892,7 @@ Exemplo de modo estrito (bloquear destinos privados/internos por padrão):
|
||||
ssrfPolicy: {
|
||||
dangerouslyAllowPrivateNetwork: false,
|
||||
hostnameAllowlist: ["*.example.com", "example.com"],
|
||||
allowedHostnames: ["localhost"], // allow exato opcional
|
||||
allowedHostnames: ["localhost"], // permissão exata opcional
|
||||
},
|
||||
},
|
||||
}
|
||||
@ -887,23 +903,23 @@ Exemplo de modo estrito (bloquear destinos privados/internos por padrão):
|
||||
Para problemas específicos do Linux (especialmente snap Chromium), veja
|
||||
[Solução de problemas do navegador](/pt-BR/tools/browser-linux-troubleshooting).
|
||||
|
||||
Para configurações divididas entre Gateway no WSL2 + Chrome no Windows em hosts separados, veja
|
||||
Para configurações divididas entre Gateway no WSL2 + Chrome no Windows, veja
|
||||
[Solução de problemas de WSL2 + Windows + CDP remoto do Chrome](/pt-BR/tools/browser-wsl2-windows-remote-cdp-troubleshooting).
|
||||
|
||||
### Falha de inicialização do CDP vs bloqueio SSRF de navegação
|
||||
### Falha na inicialização do CDP vs bloqueio SSRF de navegação
|
||||
|
||||
Essas são classes de falha diferentes e apontam para caminhos de código diferentes.
|
||||
Essas são classes diferentes de falha e apontam para caminhos de código diferentes.
|
||||
|
||||
- **Falha de inicialização ou prontidão do CDP** significa que o OpenClaw não consegue confirmar que o plano de controle do navegador está íntegro.
|
||||
- **Bloqueio SSRF de navegação** significa que o plano de controle do navegador está íntegro, mas um destino de navegação de página é rejeitado pela política.
|
||||
- **Bloqueio SSRF de navegação** significa que o plano de controle do navegador está íntegro, mas um alvo de navegação de página é rejeitado pela política.
|
||||
|
||||
Exemplos comuns:
|
||||
|
||||
- Falha de inicialização ou prontidão do CDP:
|
||||
- Falha na inicialização ou prontidão do CDP:
|
||||
- `Chrome CDP websocket for profile "openclaw" is not reachable after start`
|
||||
- `Remote CDP for profile "<name>" is not reachable at <cdpUrl>`
|
||||
- Bloqueio SSRF de navegação:
|
||||
- fluxos `open`, `navigate`, snapshot ou de abertura de aba falham com um erro de política de navegador/rede, enquanto `start` e `tabs` continuam funcionando
|
||||
- fluxos de `open`, `navigate`, snapshot ou abertura de aba falham com um erro de política de navegador/rede enquanto `start` e `tabs` ainda funcionam
|
||||
|
||||
Use esta sequência mínima para separar os dois:
|
||||
|
||||
@ -915,41 +931,41 @@ openclaw browser --browser-profile openclaw open https://example.com
|
||||
|
||||
Como interpretar os resultados:
|
||||
|
||||
- Se `start` falhar com `not reachable after start`, primeiro resolva o problema de prontidão do CDP.
|
||||
- Se `start` tiver êxito, mas `tabs` falhar, o plano de controle ainda não está íntegro. Trate isso como um problema de alcance do CDP, não como um problema de navegação de página.
|
||||
- Se `start` e `tabs` tiverem êxito, mas `open` ou `navigate` falhar, o plano de controle do navegador está ativo e a falha está na política de navegação ou na página de destino.
|
||||
- Se `start`, `tabs` e `open` tiverem êxito, o caminho básico de controle do navegador gerenciado está íntegro.
|
||||
- Se `start` falhar com `not reachable after start`, primeiro solucione a prontidão do CDP.
|
||||
- Se `start` tiver sucesso, mas `tabs` falhar, o plano de controle ainda não está íntegro. Trate isso como um problema de alcançabilidade do CDP, não como um problema de navegação de página.
|
||||
- Se `start` e `tabs` tiverem sucesso, mas `open` ou `navigate` falhar, o plano de controle do navegador está ativo e a falha está na política de navegação ou na página de destino.
|
||||
- Se `start`, `tabs` e `open` tiverem sucesso, o caminho básico de controle do navegador gerenciado está íntegro.
|
||||
|
||||
Detalhes importantes de comportamento:
|
||||
|
||||
- A configuração do navegador usa por padrão um objeto de política SSRF fail-closed mesmo quando você não configura `browser.ssrfPolicy`.
|
||||
- Para o perfil gerenciado local em loopback `openclaw`, as verificações de integridade do CDP intencionalmente ignoram a imposição de alcance SSRF do navegador para o próprio plano de controle local do OpenClaw.
|
||||
- Para o perfil gerenciado local `openclaw` em loopback, as verificações de integridade do CDP ignoram intencionalmente a aplicação de alcançabilidade SSRF do navegador para o próprio plano de controle local do OpenClaw.
|
||||
- A proteção de navegação é separada. Um resultado bem-sucedido em `start` ou `tabs` não significa que um alvo posterior de `open` ou `navigate` seja permitido.
|
||||
|
||||
Orientação de segurança:
|
||||
Orientações de segurança:
|
||||
|
||||
- **Não** relaxe a política SSRF do navegador por padrão.
|
||||
- Prefira exceções restritas de host, como `hostnameAllowlist` ou `allowedHostnames`, em vez de acesso amplo à rede privada.
|
||||
- Use `dangerouslyAllowPrivateNetwork: true` apenas em ambientes intencionalmente confiáveis em que o acesso do navegador à rede privada seja necessário e revisado.
|
||||
- **Não** flexibilize a política SSRF do navegador por padrão.
|
||||
- Prefira exceções estreitas de host, como `hostnameAllowlist` ou `allowedHostnames`, em vez de acesso amplo à rede privada.
|
||||
- Use `dangerouslyAllowPrivateNetwork: true` apenas em ambientes intencionalmente confiáveis nos quais o acesso do navegador à rede privada seja necessário e revisado.
|
||||
|
||||
Exemplo: navegação bloqueada, plano de controle íntegro
|
||||
|
||||
- `start` tem êxito
|
||||
- `tabs` tem êxito
|
||||
- `start` tem sucesso
|
||||
- `tabs` tem sucesso
|
||||
- `open http://internal.example` falha
|
||||
|
||||
Isso normalmente significa que a inicialização do navegador está correta e o destino de navegação precisa de revisão da política.
|
||||
Isso normalmente significa que a inicialização do navegador está correta e o alvo de navegação precisa de revisão de política.
|
||||
|
||||
Exemplo: inicialização bloqueada antes que a navegação importe
|
||||
Exemplo: inicialização bloqueada antes de a navegação importar
|
||||
|
||||
- `start` falha com `not reachable after start`
|
||||
- `tabs` também falha ou não pode ser executado
|
||||
|
||||
Isso aponta para inicialização do navegador ou alcance do CDP, não para um problema de allowlist de URL de página.
|
||||
Isso aponta para inicialização do navegador ou alcançabilidade do CDP, não para um problema de allowlist de URL de página.
|
||||
|
||||
## Ferramentas do agente + como o controle funciona
|
||||
|
||||
O agente recebe **uma ferramenta** para automação do navegador:
|
||||
O agente recebe **uma ferramenta** para automação de navegador:
|
||||
|
||||
- `browser` — status/start/stop/tabs/open/focus/close/snapshot/screenshot/navigate/act
|
||||
|
||||
@ -962,13 +978,13 @@ Como isso se mapeia:
|
||||
- `profile` para escolher um perfil de navegador nomeado (openclaw, chrome ou CDP remoto).
|
||||
- `target` (`sandbox` | `host` | `node`) para selecionar onde o navegador está.
|
||||
- Em sessões em sandbox, `target: "host"` exige `agents.defaults.sandbox.browser.allowHostControl=true`.
|
||||
- Se `target` for omitido: sessões em sandbox usam `sandbox` por padrão; sessões sem sandbox usam `host` por padrão.
|
||||
- Se um node com capacidade de navegador estiver conectado, a ferramenta poderá encaminhar automaticamente para ele, a menos que você fixe `target="host"` ou `target="node"`.
|
||||
- Se `target` for omitido: sessões em sandbox usam `sandbox` por padrão, sessões fora de sandbox usam `host` por padrão.
|
||||
- Se um node com capacidade de navegador estiver conectado, a ferramenta poderá rotear automaticamente para ele, a menos que você fixe `target="host"` ou `target="node"`.
|
||||
|
||||
Isso mantém o agente determinístico e evita seletores frágeis.
|
||||
|
||||
## Relacionados
|
||||
## Relacionado
|
||||
|
||||
- [Visão geral das ferramentas](/pt-BR/tools) — todas as ferramentas de agente disponíveis
|
||||
- [Sandboxing](/pt-BR/gateway/sandboxing) — controle do navegador em ambientes com sandbox
|
||||
- [Sandboxing](/pt-BR/gateway/sandboxing) — controle do navegador em ambientes em sandbox
|
||||
- [Segurança](/pt-BR/gateway/security) — riscos e reforço de segurança do controle do navegador
|
||||
|
||||
Loading…
Reference in New Issue
Block a user