chore(i18n): refresh pt-BR translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
d353a0e3db
commit
73c46f03c7
@ -1,43 +1,43 @@
|
||||
---
|
||||
read_when:
|
||||
- Configurando o controle de acesso a DMs
|
||||
- Emparelhamento de um novo Node iOS/Android
|
||||
- Revisando a postura de segurança do OpenClaw
|
||||
summary: 'Visão geral do pareamento: aprove quem pode enviar mensagens diretas para você + quais nós podem participar'
|
||||
title: Pareamento
|
||||
- Emparelhando um novo Node iOS/Android
|
||||
- Analisando a postura de segurança do OpenClaw
|
||||
summary: 'Visão geral do pareamento: aprove quem pode enviar mensagens diretas para você + quais nodes podem ingressar'
|
||||
title: Emparelhamento
|
||||
x-i18n:
|
||||
generated_at: "2026-05-04T02:21:31Z"
|
||||
generated_at: "2026-05-04T09:37:11Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 4fb27840f7c9ef55e7270cc29f813e6db90b240aa2180f30952eb9485f0f8874
|
||||
source_hash: f2bce4cfba7708b0003f2ffeacada8bc1849cc301f28178b499a9a67bddcf36d
|
||||
source_path: channels/pairing.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
“Pareamento” é a etapa explícita de aprovação de acesso do OpenClaw.
|
||||
Ela é usada em dois lugares:
|
||||
“Emparelhamento” é a etapa explícita de aprovação de acesso do OpenClaw.
|
||||
Ele é usado em dois lugares:
|
||||
|
||||
1. **Pareamento de DM** (quem tem permissão para falar com o bot)
|
||||
2. **Pareamento de Node** (quais dispositivos/nós têm permissão para entrar na rede do Gateway)
|
||||
1. **Emparelhamento por DM** (quem tem permissão para falar com o bot)
|
||||
2. **Emparelhamento de Node** (quais dispositivos/Nodes têm permissão para ingressar na rede do Gateway)
|
||||
|
||||
Contexto de segurança: [Segurança](/pt-BR/gateway/security)
|
||||
|
||||
## 1) Pareamento de DM (acesso de chat de entrada)
|
||||
## 1) Emparelhamento por DM (acesso de chat de entrada)
|
||||
|
||||
Quando um canal é configurado com a política de DM `pairing`, remetentes desconhecidos recebem um código curto e a mensagem deles **não é processada** até você aprovar.
|
||||
|
||||
As políticas padrão de DM estão documentadas em: [Segurança](/pt-BR/gateway/security)
|
||||
As políticas de DM padrão estão documentadas em: [Segurança](/pt-BR/gateway/security)
|
||||
|
||||
`dmPolicy: "open"` é público somente quando a lista de permissões efetiva de DM inclui `"*"`.
|
||||
A configuração e a validação exigem esse curinga para configurações público-abertas. Se o estado existente
|
||||
contiver `open` com entradas concretas em `allowFrom`, o runtime ainda admite
|
||||
somente esses remetentes, e aprovações no armazenamento de pareamento não ampliam o acesso `open`.
|
||||
`dmPolicy: "open"` é público somente quando a lista de permissões de DM efetiva inclui `"*"`.
|
||||
A configuração e a validação exigem esse curinga para configurações públicas abertas. Se o estado existente
|
||||
contiver `open` com entradas `allowFrom` concretas, em tempo de execução ainda serão admitidos
|
||||
somente esses remetentes, e as aprovações do armazenamento de emparelhamento não ampliam o acesso `open`.
|
||||
|
||||
Códigos de pareamento:
|
||||
Códigos de emparelhamento:
|
||||
|
||||
- 8 caracteres, maiúsculos, sem caracteres ambíguos (`0O1I`).
|
||||
- **Expiram após 1 hora**. O bot só envia a mensagem de pareamento quando uma nova solicitação é criada (aproximadamente uma vez por hora por remetente).
|
||||
- Solicitações pendentes de pareamento de DM são limitadas a **3 por canal** por padrão; solicitações adicionais são ignoradas até que uma expire ou seja aprovada.
|
||||
- 8 caracteres, maiúsculas, sem caracteres ambíguos (`0O1I`).
|
||||
- **Expiram após 1 hora**. O bot só envia a mensagem de emparelhamento quando uma nova solicitação é criada (aproximadamente uma vez por hora por remetente).
|
||||
- Solicitações pendentes de emparelhamento por DM são limitadas a **3 por canal** por padrão; solicitações adicionais são ignoradas até que uma expire ou seja aprovada.
|
||||
|
||||
### Aprovar um remetente
|
||||
|
||||
@ -46,21 +46,21 @@ openclaw pairing list telegram
|
||||
openclaw pairing approve telegram <CODE>
|
||||
```
|
||||
|
||||
Se nenhum proprietário de comando estiver configurado ainda, aprovar um código de pareamento de DM também inicializa
|
||||
`commands.ownerAllowFrom` para o remetente aprovado, como `telegram:123456789`.
|
||||
Isso dá às configurações de primeira execução um proprietário explícito para comandos privilegiados e prompts de aprovação de exec.
|
||||
Depois que um proprietário existe, aprovações de pareamento posteriores concedem apenas acesso de DM;
|
||||
Se nenhum proprietário de comandos ainda estiver configurado, aprovar um código de emparelhamento por DM também inicializa
|
||||
`commands.ownerAllowFrom` com o remetente aprovado, como `telegram:123456789`.
|
||||
Isso dá às configurações iniciais um proprietário explícito para comandos privilegiados e prompts de aprovação de exec.
|
||||
Depois que um proprietário existe, aprovações de emparelhamento posteriores concedem apenas acesso por DM;
|
||||
elas não adicionam mais proprietários.
|
||||
|
||||
Canais compatíveis: `bluebubbles`, `discord`, `feishu`, `googlechat`, `imessage`, `irc`, `line`, `matrix`, `mattermost`, `msteams`, `nextcloud-talk`, `nostr`, `openclaw-weixin`, `signal`, `slack`, `synology-chat`, `telegram`, `twitch`, `whatsapp`, `zalo`, `zalouser`.
|
||||
|
||||
### Grupos de remetentes reutilizáveis
|
||||
|
||||
Use `accessGroups` de nível superior quando o mesmo conjunto de remetentes confiáveis deve ser aplicado a
|
||||
vários canais de mensagem ou tanto a listas de permissões de DM quanto de grupo.
|
||||
Use `accessGroups` no nível superior quando o mesmo conjunto de remetentes confiáveis deve se aplicar a
|
||||
vários canais de mensagens ou tanto a listas de permissões de DM quanto de grupos.
|
||||
|
||||
Grupos estáticos usam `type: "message.senders"` e são referenciados com
|
||||
`accessGroup:<name>` nas listas de permissões de canais:
|
||||
`accessGroup:<name>` a partir das listas de permissões do canal:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -81,9 +81,9 @@ Grupos estáticos usam `type: "message.senders"` e são referenciados com
|
||||
}
|
||||
```
|
||||
|
||||
Grupos de acesso estão documentados em detalhes aqui: [Grupos de acesso](/pt-BR/channels/access-groups)
|
||||
Os grupos de acesso estão documentados em detalhes aqui: [Grupos de acesso](/pt-BR/channels/access-groups)
|
||||
|
||||
### Onde o estado fica armazenado
|
||||
### Onde o estado fica
|
||||
|
||||
Armazenado em `~/.openclaw/credentials/`:
|
||||
|
||||
@ -94,53 +94,59 @@ Armazenado em `~/.openclaw/credentials/`:
|
||||
|
||||
Comportamento de escopo por conta:
|
||||
|
||||
- Contas não padrão leem/gravam somente o arquivo de lista de permissões com escopo delas.
|
||||
- A conta padrão usa o arquivo de lista de permissões sem escopo, com escopo do canal.
|
||||
- Contas não padrão leem/gravam apenas seu arquivo de lista de permissões com escopo.
|
||||
- A conta padrão usa o arquivo de lista de permissões sem escopo do canal.
|
||||
|
||||
Trate esses arquivos como sensíveis (eles controlam o acesso ao seu assistente).
|
||||
|
||||
<Note>
|
||||
O armazenamento da lista de permissões de pareamento é para acesso de DM. A autorização de grupo é separada.
|
||||
Aprovar um código de pareamento de DM não permite automaticamente que esse remetente execute comandos de grupo
|
||||
O armazenamento da lista de permissões de emparelhamento é para acesso por DM. A autorização de grupos é separada.
|
||||
Aprovar um código de emparelhamento por DM não permite automaticamente que esse remetente execute comandos de grupo
|
||||
ou controle o bot em grupos. A inicialização do primeiro proprietário é um estado de configuração separado
|
||||
em `commands.ownerAllowFrom`, e a entrega em chats de grupo ainda segue as listas de permissões de grupo
|
||||
do canal (por exemplo, `groupAllowFrom`, `groups` ou substituições por grupo
|
||||
do canal (por exemplo `groupAllowFrom`, `groups` ou substituições por grupo
|
||||
ou por tópico, dependendo do canal).
|
||||
</Note>
|
||||
|
||||
## 2) Pareamento de dispositivo Node (nós iOS/Android/macOS/headless)
|
||||
## 2) Emparelhamento de dispositivo Node (Nodes iOS/Android/macOS/headless)
|
||||
|
||||
Nós se conectam ao Gateway como **dispositivos** com `role: node`. O Gateway
|
||||
cria uma solicitação de pareamento de dispositivo que precisa ser aprovada.
|
||||
Nodes se conectam ao Gateway como **dispositivos** com `role: node`. O Gateway
|
||||
cria uma solicitação de emparelhamento de dispositivo que deve ser aprovada.
|
||||
|
||||
### Parear via Telegram (recomendado para iOS)
|
||||
### Emparelhar via Telegram (recomendado para iOS)
|
||||
|
||||
Se você usa o Plugin `device-pair`, pode fazer o pareamento inicial do dispositivo inteiramente pelo Telegram:
|
||||
Se você usa o Plugin `device-pair`, pode fazer o primeiro emparelhamento de dispositivo inteiramente pelo Telegram:
|
||||
|
||||
1. No Telegram, envie uma mensagem para seu bot: `/pair`
|
||||
2. O bot responde com duas mensagens: uma mensagem de instruções e uma mensagem separada com o **código de configuração** (fácil de copiar/colar no Telegram).
|
||||
3. No telefone, abra o app iOS do OpenClaw → Settings → Gateway.
|
||||
4. Cole o código de configuração e conecte.
|
||||
5. De volta ao Telegram: `/pair pending` (revise IDs de solicitação, função e escopos) e então aprove.
|
||||
1. No Telegram, envie uma mensagem ao seu bot: `/pair`
|
||||
2. O bot responde com duas mensagens: uma mensagem de instruções e uma mensagem separada de **código de configuração** (fácil de copiar/colar no Telegram).
|
||||
3. No seu telefone, abra o app iOS do OpenClaw → Configurações → Gateway.
|
||||
4. Escaneie o código QR ou cole o código de configuração e conecte.
|
||||
5. De volta ao Telegram: `/pair pending` (revise IDs de solicitação, função e escopos), depois aprove.
|
||||
|
||||
O código de configuração é uma carga JSON codificada em base64 que contém:
|
||||
|
||||
- `url`: a URL WebSocket do Gateway (`ws://...` ou `wss://...`)
|
||||
- `bootstrapToken`: um token de bootstrap de curta duração para um único dispositivo, usado no handshake inicial de pareamento
|
||||
- `bootstrapToken`: um token bootstrap de curta duração para um único dispositivo, usado no handshake inicial de emparelhamento
|
||||
|
||||
Esse token de bootstrap carrega o perfil integrado de bootstrap de pareamento:
|
||||
Esse token bootstrap carrega o perfil bootstrap de emparelhamento integrado:
|
||||
|
||||
- o token `node` principal transferido permanece com `scopes: []`
|
||||
- qualquer token `operator` transferido permanece limitado à lista de permissões de bootstrap:
|
||||
- o token `node` entregue primário permanece com `scopes: []`
|
||||
- qualquer token `operator` entregue permanece limitado à lista de permissões bootstrap:
|
||||
`operator.approvals`, `operator.read`, `operator.talk.secrets`, `operator.write`
|
||||
- verificações de escopo de bootstrap são prefixadas por função, não um único conjunto plano de escopos:
|
||||
entradas de escopo de operador só satisfazem solicitações de operador, e funções não operadoras
|
||||
ainda devem solicitar escopos sob o próprio prefixo de função
|
||||
- rotação/revogação posterior de token permanece limitada tanto pelo contrato de função aprovado
|
||||
do dispositivo quanto pelos escopos de operador da sessão chamadora
|
||||
- verificações de escopo bootstrap são prefixadas por função, não um único conjunto plano de escopos:
|
||||
entradas de escopo operator só satisfazem solicitações de operator, e funções que não são operator
|
||||
ainda devem solicitar escopos sob seu próprio prefixo de função
|
||||
- rotação/revogação posterior de tokens permanece limitada tanto pelo contrato de função aprovado
|
||||
do dispositivo quanto pelos escopos de operator da sessão chamadora
|
||||
|
||||
Trate o código de configuração como uma senha enquanto ele estiver válido.
|
||||
|
||||
Para Tailscale, público ou outro emparelhamento móvel que não seja loopback, use Tailscale
|
||||
Serve/Funnel ou outra URL `wss://` do Gateway. URLs de configuração `ws://` diretas que não sejam loopback
|
||||
são rejeitadas antes da emissão do QR/código de configuração. Códigos de configuração `ws://` em texto puro
|
||||
são limitados a URLs de loopback; clientes `ws://` em rede privada ainda exigem o escape explícito
|
||||
`OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` descrito no guia de Gateway remoto.
|
||||
|
||||
### Aprovar um dispositivo Node
|
||||
|
||||
```bash
|
||||
@ -149,24 +155,25 @@ openclaw devices approve <requestId>
|
||||
openclaw devices reject <requestId>
|
||||
```
|
||||
|
||||
Quando uma aprovação explícita é negada porque a sessão de dispositivo pareado aprovadora
|
||||
foi aberta com escopo apenas de pareamento, a CLI tenta novamente a mesma solicitação com
|
||||
`operator.admin`. Isso permite que um dispositivo pareado existente com capacidade de administrador recupere um novo
|
||||
pareamento da Control UI/navegador sem editar `devices/paired.json` manualmente. O
|
||||
Gateway ainda valida a conexão repetida; tokens que não conseguem se autenticar
|
||||
Quando uma aprovação explícita é negada porque a sessão de dispositivo emparelhado aprovadora
|
||||
foi aberta apenas com escopo de emparelhamento, a CLI tenta novamente a mesma solicitação com
|
||||
`operator.admin`. Isso permite que um dispositivo emparelhado existente com capacidade de admin recupere um novo
|
||||
emparelhamento da UI de Controle/navegador sem editar `devices/paired.json` manualmente. O
|
||||
Gateway ainda valida a conexão repetida; tokens que não conseguem autenticar
|
||||
com `operator.admin` permanecem bloqueados.
|
||||
|
||||
Se o mesmo dispositivo tentar novamente com detalhes de autenticação diferentes (por exemplo, função/escopos/chave pública diferentes),
|
||||
a solicitação pendente anterior é substituída e um novo `requestId` é criado.
|
||||
Se o mesmo dispositivo tentar novamente com detalhes de autenticação diferentes (por exemplo, função/escopos/chave pública
|
||||
diferentes), a solicitação pendente anterior é substituída e um novo
|
||||
`requestId` é criado.
|
||||
|
||||
<Note>
|
||||
Um dispositivo já pareado não recebe acesso mais amplo silenciosamente. Se ele reconectar solicitando mais escopos ou uma função mais ampla, o OpenClaw mantém a aprovação existente como está e cria uma nova solicitação pendente de upgrade. Use `openclaw devices list` para comparar o acesso aprovado atualmente com o novo acesso solicitado antes de aprovar.
|
||||
Um dispositivo já emparelhado não recebe acesso mais amplo silenciosamente. Se ele se reconectar pedindo mais escopos ou uma função mais ampla, o OpenClaw mantém a aprovação existente como está e cria uma nova solicitação pendente de upgrade. Use `openclaw devices list` para comparar o acesso atualmente aprovado com o acesso recém-solicitado antes de aprovar.
|
||||
</Note>
|
||||
|
||||
### Aprovação automática opcional de Node por CIDR confiável
|
||||
|
||||
O pareamento de dispositivo permanece manual por padrão. Para redes de Node estritamente controladas,
|
||||
você pode optar pela aprovação automática de Node na primeira execução com CIDRs explícitos ou IPs exatos:
|
||||
O emparelhamento de dispositivos permanece manual por padrão. Para redes de Node rigidamente controladas,
|
||||
você pode optar pela aprovação automática inicial de Node com CIDRs explícitos ou IPs exatos:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -180,26 +187,27 @@ você pode optar pela aprovação automática de Node na primeira execução com
|
||||
}
|
||||
```
|
||||
|
||||
Isso se aplica somente a novas solicitações de pareamento com `role: node` sem escopos solicitados.
|
||||
Clientes de operador, navegador, Control UI e WebChat ainda exigem aprovação manual.
|
||||
Alterações de função, escopo, metadados e chave pública ainda exigem aprovação manual.
|
||||
Isso se aplica somente a novas solicitações de emparelhamento `role: node` sem escopos
|
||||
solicitados. Clientes operator, navegador, UI de Controle e WebChat ainda exigem aprovação
|
||||
manual. Alterações de função, escopo, metadados e chave pública ainda exigem aprovação
|
||||
manual.
|
||||
|
||||
### Armazenamento do estado de pareamento de Node
|
||||
### Armazenamento do estado de emparelhamento de Node
|
||||
|
||||
Armazenado em `~/.openclaw/devices/`:
|
||||
|
||||
- `pending.json` (curta duração; solicitações pendentes expiram)
|
||||
- `paired.json` (dispositivos pareados + tokens)
|
||||
- `paired.json` (dispositivos emparelhados + tokens)
|
||||
|
||||
### Observações
|
||||
|
||||
- A API legada `node.pair.*` (CLI: `openclaw nodes pending|approve|reject|remove|rename`) é um
|
||||
armazenamento de pareamento separado, de propriedade do gateway. Nós WS ainda exigem pareamento de dispositivo.
|
||||
- O registro de pareamento é a fonte durável da verdade para funções aprovadas. Tokens de dispositivo ativos
|
||||
permanecem limitados a esse conjunto de funções aprovado; uma entrada de token avulsa
|
||||
armazenamento de emparelhamento separado de propriedade do Gateway. Nodes WS ainda exigem emparelhamento de dispositivo.
|
||||
- O registro de emparelhamento é a fonte durável da verdade para funções aprovadas. Tokens de
|
||||
dispositivo ativos permanecem limitados a esse conjunto de funções aprovado; uma entrada de token isolada
|
||||
fora das funções aprovadas não cria novo acesso.
|
||||
|
||||
## Documentação relacionada
|
||||
## Documentos relacionados
|
||||
|
||||
- Modelo de segurança + injeção de prompt: [Segurança](/pt-BR/gateway/security)
|
||||
- Atualizar com segurança (executar doctor): [Atualização](/pt-BR/install/updating)
|
||||
|
||||
@ -4,25 +4,25 @@ read_when:
|
||||
summary: Status de suporte, recursos e configuração do bot do Telegram
|
||||
title: Telegram
|
||||
x-i18n:
|
||||
generated_at: "2026-05-04T07:02:43Z"
|
||||
generated_at: "2026-05-04T09:36:48Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 6ef1b019a6a0e261b33972b5edffaedd29310b1333d112bade2e79e9d56887c6
|
||||
source_hash: 5711d53cf908a14024bc5a94f7d590bb4bcb6963a1d78049d7782871f4eae932
|
||||
source_path: channels/telegram.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Pronto para produção para DMs e grupos de bots via grammY. O long polling é o modo padrão; o modo Webhook é opcional.
|
||||
Pronto para produção para DMs de bot e grupos via grammY. A sondagem longa é o modo padrão; o modo Webhook é opcional.
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Emparelhamento" icon="link" href="/pt-BR/channels/pairing">
|
||||
A política padrão de DM para Telegram é emparelhamento.
|
||||
<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="/pt-BR/channels/troubleshooting">
|
||||
Diagnósticos entre canais e playbooks de reparo.
|
||||
Diagnósticos entre canais e manuais de reparo.
|
||||
</Card>
|
||||
<Card title="Configuração do Gateway" icon="settings" href="/pt-BR/gateway/configuration">
|
||||
Padrões e exemplos completos de configuração de canal.
|
||||
Padrões e exemplos completos de configuração de canais.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -51,8 +51,8 @@ Pronto para produção para DMs e grupos de bots via grammY. O long polling é o
|
||||
}
|
||||
```
|
||||
|
||||
Fallback de env: `TELEGRAM_BOT_TOKEN=...` (somente conta padrão).
|
||||
Telegram **não** usa `openclaw channels login telegram`; configure o token na configuração/env e depois inicie o Gateway.
|
||||
Alternativa por ambiente: `TELEGRAM_BOT_TOKEN=...` (somente conta padrão).
|
||||
O Telegram **não** usa `openclaw channels login telegram`; configure o token na configuração/ambiente e depois inicie o Gateway.
|
||||
|
||||
</Step>
|
||||
|
||||
@ -64,17 +64,17 @@ openclaw pairing list telegram
|
||||
openclaw pairing approve telegram <CODE>
|
||||
```
|
||||
|
||||
Os códigos de emparelhamento expiram após 1 hora.
|
||||
Códigos de pareamento expiram depois de 1 hora.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Adicione o bot a um grupo">
|
||||
Adicione o bot ao seu grupo e, em seguida, defina `channels.telegram.groups` e `groupPolicy` para corresponder ao seu modelo de acesso.
|
||||
Adicione o bot ao seu grupo e depois defina `channels.telegram.groups` e `groupPolicy` para corresponder ao seu modelo de acesso.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
A ordem de resolução de token considera a conta. Na prática, valores de configuração têm precedência sobre o fallback de env, e `TELEGRAM_BOT_TOKEN` se aplica somente à conta padrão.
|
||||
A ordem de resolução de token leva a conta em consideração. Na prática, valores de configuração prevalecem sobre a alternativa por ambiente, e `TELEGRAM_BOT_TOKEN` se aplica somente à conta padrão.
|
||||
</Note>
|
||||
|
||||
## Configurações do lado do Telegram
|
||||
@ -83,7 +83,7 @@ A ordem de resolução de token considera a conta. Na prática, valores de confi
|
||||
<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 de grupo, faça uma destas opções:
|
||||
Se o bot precisar ver todas as mensagens do grupo:
|
||||
|
||||
- desative o modo de privacidade via `/setprivacy`, ou
|
||||
- torne o bot administrador do grupo.
|
||||
@ -93,9 +93,9 @@ A ordem de resolução de token considera a conta. Na prática, valores de confi
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Permissões de grupo">
|
||||
O status de administrador é controlado nas configurações de grupo do Telegram.
|
||||
O status de administrador é controlado nas configurações do grupo do Telegram.
|
||||
|
||||
Bots administradores recebem todas as mensagens de grupo, o que é útil para comportamento de grupo sempre ativo.
|
||||
Bots administradores recebem todas as mensagens do grupo, o que é útil para comportamento sempre ativo em grupos.
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -121,24 +121,24 @@ A ordem de resolução de token considera a conta. Na prática, valores de confi
|
||||
`dmPolicy: "open"` com `allowFrom: ["*"]` permite que qualquer conta do Telegram que encontre ou adivinhe o nome de usuário do bot comande o bot. Use isso somente para bots intencionalmente públicos com ferramentas rigidamente restritas; bots de um único proprietário devem usar `allowlist` com IDs numéricos de usuário.
|
||||
|
||||
`channels.telegram.allowFrom` aceita IDs numéricos de usuário do Telegram. Prefixos `telegram:` / `tg:` são aceitos e normalizados.
|
||||
Em configurações de várias contas, um `channels.telegram.allowFrom` restritivo no nível superior é tratado como um limite de segurança: entradas `allowFrom: ["*"]` no nível da conta não tornam essa conta pública, a menos que a lista de permissões efetiva da conta ainda contenha um curinga explícito após a mesclagem.
|
||||
`dmPolicy: "allowlist"` com `allowFrom` vazio bloqueia todas as DMs e é rejeitado pela validação de configuração.
|
||||
A configuração inicial pede somente IDs numéricos de usuário.
|
||||
Se você atualizou e sua configuração contém entradas de lista de permissões `@username`, execute `openclaw doctor --fix` para resolvê-las (melhor esforço; exige um token de bot do Telegram).
|
||||
Se você anteriormente dependia de arquivos de lista de permissões do armazenamento de emparelhamento, `openclaw doctor --fix` pode recuperar entradas para `channels.telegram.allowFrom` em fluxos de lista de permissões (por exemplo, quando `dmPolicy: "allowlist"` ainda não tem IDs explícitos).
|
||||
Em configurações com várias contas, um `channels.telegram.allowFrom` restritivo no nível superior é tratado como um limite de segurança: entradas `allowFrom: ["*"]` no nível da conta não tornam essa conta pública, a menos que a lista de permissão efetiva da conta ainda contenha um curinga explícito após a mesclagem.
|
||||
`dmPolicy: "allowlist"` com `allowFrom` vazio bloqueia todas as DMs e é rejeitado pela validação da configuração.
|
||||
A configuração inicial solicita somente IDs numéricos de usuário.
|
||||
Se você atualizou e sua configuração contém entradas `@username` na lista de permissão, execute `openclaw doctor --fix` para resolvê-las (melhor esforço; exige um token de bot do Telegram).
|
||||
Se antes você dependia de arquivos de lista de permissão do armazenamento de pareamento, `openclaw doctor --fix` pode recuperar entradas para `channels.telegram.allowFrom` em fluxos de lista de permissão (por exemplo, quando `dmPolicy: "allowlist"` ainda não tem IDs explícitos).
|
||||
|
||||
Para bots de um único proprietário, prefira `dmPolicy: "allowlist"` com IDs numéricos explícitos em `allowFrom` para manter a política de acesso durável na configuração (em vez de depender de aprovações de emparelhamento anteriores).
|
||||
Para bots de um único proprietário, prefira `dmPolicy: "allowlist"` com IDs numéricos explícitos em `allowFrom` para manter a política de acesso durável na configuração (em vez de depender de aprovações de pareamento anteriores).
|
||||
|
||||
Confusão comum: aprovação de emparelhamento por DM não significa "este remetente está autorizado em todos os lugares".
|
||||
O emparelhamento concede acesso por DM. Se ainda não houver proprietário de comandos, o primeiro emparelhamento aprovado também define `commands.ownerAllowFrom` para que comandos exclusivos do proprietário e aprovações de execução tenham uma conta de operador explícita.
|
||||
A autorização de remetentes em grupo ainda vem de listas de permissões explícitas na configuração.
|
||||
Se você quer "estou autorizado uma vez e tanto DMs quanto comandos de grupo funcionam", coloque seu ID numérico de usuário do Telegram em `channels.telegram.allowFrom`; para comandos exclusivos do proprietário, garanta que `commands.ownerAllowFrom` contenha `telegram:<your user id>`.
|
||||
Confusão comum: aprovação de pareamento por DM não significa "este remetente está autorizado em todos os lugares".
|
||||
O pareamento concede acesso por DM. Se ainda não existir um proprietário de comandos, o primeiro pareamento aprovado também define `commands.ownerAllowFrom` para que comandos exclusivos do proprietário e aprovações de execução tenham uma conta de operador explícita.
|
||||
A autorização de remetente em grupos ainda vem de listas de permissão explícitas na configuração.
|
||||
Se você quer "sou autorizado uma vez e tanto DMs quanto comandos de grupo funcionam", coloque seu ID numérico de usuário do Telegram em `channels.telegram.allowFrom`; para comandos exclusivos do proprietário, verifique se `commands.ownerAllowFrom` contém `telegram:<your user id>`.
|
||||
|
||||
### Encontrando seu ID de usuário do Telegram
|
||||
|
||||
Mais seguro (sem bot de terceiros):
|
||||
|
||||
1. Envie uma DM para seu bot.
|
||||
1. Envie uma DM ao seu bot.
|
||||
2. Execute `openclaw logs --follow`.
|
||||
3. Leia `from.id`.
|
||||
|
||||
@ -152,29 +152,29 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Política de grupo e listas de permissões">
|
||||
Dois controles se aplicam em conjunto:
|
||||
<Tab title="Política de grupo e listas de permissão">
|
||||
Dois controles se aplicam juntos:
|
||||
|
||||
1. **Quais grupos são permitidos** (`channels.telegram.groups`)
|
||||
- sem configuração `groups`:
|
||||
- sem configuração de `groups`:
|
||||
- com `groupPolicy: "open"`: qualquer grupo pode passar nas verificações de ID de grupo
|
||||
- com `groupPolicy: "allowlist"` (padrão): grupos ficam bloqueados até você adicionar entradas em `groups` (ou `"*"`)
|
||||
- `groups` configurado: atua como lista de permissões (IDs explícitos ou `"*"`)
|
||||
- `groups` configurado: atua como lista de permissão (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 definido, Telegram recorre a `allowFrom`.
|
||||
`groupAllowFrom` é usado para filtragem de remetentes em grupos. Se não for definido, o Telegram recorre a `allowFrom`.
|
||||
Entradas `groupAllowFrom` devem ser IDs numéricos de usuário do Telegram (prefixos `telegram:` / `tg:` são normalizados).
|
||||
Não coloque IDs de chat de grupos ou supergrupos do Telegram em `groupAllowFrom`. IDs de chat negativos pertencem a `channels.telegram.groups`.
|
||||
Não coloque IDs de chat de grupo ou supergrupo do Telegram em `groupAllowFrom`. IDs de chat negativos pertencem a `channels.telegram.groups`.
|
||||
Entradas não numéricas são ignoradas para autorização de remetente.
|
||||
Limite de segurança (`2026.2.25+`): autenticação de remetente em grupo **não** herda aprovações de armazenamento de emparelhamento por DM.
|
||||
O emparelhamento permanece somente para DM. Para grupos, defina `groupAllowFrom` ou `allowFrom` por grupo/por tópico.
|
||||
Se `groupAllowFrom` não estiver definido, Telegram recorre a `allowFrom` da configuração, não ao armazenamento de emparelhamento.
|
||||
Padrão prático para bots de um único proprietário: defina seu ID de usuário em `channels.telegram.allowFrom`, deixe `groupAllowFrom` indefinido e permita os grupos-alvo em `channels.telegram.groups`.
|
||||
Nota de runtime: se `channels.telegram` estiver completamente ausente, o runtime usa por padrão `groupPolicy="allowlist"` com falha fechada, a menos que `channels.defaults.groupPolicy` esteja explicitamente definido.
|
||||
Limite de segurança (`2026.2.25+`): autenticação de remetente em grupo **não** herda aprovações do armazenamento de pareamento de DM.
|
||||
O pareamento continua sendo somente para DM. Para grupos, defina `groupAllowFrom` ou `allowFrom` por grupo/por tópico.
|
||||
Se `groupAllowFrom` não estiver definido, o Telegram recorre ao `allowFrom` da configuração, não ao armazenamento de pareamento.
|
||||
Padrão prático para bots de um único proprietário: defina seu ID de usuário em `channels.telegram.allowFrom`, deixe `groupAllowFrom` indefinido e permita os grupos de destino em `channels.telegram.groups`.
|
||||
Observação de runtime: se `channels.telegram` estiver completamente ausente, o runtime usa por padrão `groupPolicy="allowlist"` fechado por segurança, a menos que `channels.defaults.groupPolicy` seja definido explicitamente.
|
||||
|
||||
Exemplo: permitir qualquer membro em um grupo específico:
|
||||
|
||||
@ -193,7 +193,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Exemplo: permitir apenas usuários específicos dentro de um grupo específico:
|
||||
Exemplo: permitir somente usuários específicos dentro de um grupo específico:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -211,18 +211,18 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Erro comum: `groupAllowFrom` não é uma lista de permissões de grupos do Telegram.
|
||||
Erro comum: `groupAllowFrom` não é uma lista de permissão de grupos do Telegram.
|
||||
|
||||
- Coloque IDs de chat negativos de grupos ou supergrupos do Telegram, como `-1001234567890`, em `channels.telegram.groups`.
|
||||
- Coloque IDs negativos de chat de grupo ou supergrupo do Telegram, como `-1001234567890`, em `channels.telegram.groups`.
|
||||
- Coloque IDs de usuário do Telegram, como `8734062810`, em `groupAllowFrom` quando quiser limitar quais pessoas dentro de um grupo permitido podem acionar o bot.
|
||||
- Use `groupAllowFrom: ["*"]` somente quando quiser que qualquer membro de um grupo permitido consiga falar com o bot.
|
||||
- Use `groupAllowFrom: ["*"]` somente quando quiser que qualquer membro de um grupo permitido possa falar com o bot.
|
||||
|
||||
</Warning>
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Comportamento de menção">
|
||||
Respostas em grupo exigem menção por padrão.
|
||||
Respostas em grupos exigem menção por padrão.
|
||||
|
||||
A menção pode vir de:
|
||||
|
||||
@ -254,30 +254,30 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Obtendo o ID do chat do grupo:
|
||||
|
||||
- encaminhe uma mensagem do grupo para `@userinfobot` / `@getidsbot`
|
||||
- encaminhe uma mensagem de grupo para `@userinfobot` / `@getidsbot`
|
||||
- ou leia `chat.id` em `openclaw logs --follow`
|
||||
- ou inspecione `getUpdates` da Bot API
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Comportamento de runtime
|
||||
## Comportamento em runtime
|
||||
|
||||
- Telegram é de propriedade do processo do Gateway.
|
||||
- O roteamento é determinístico: entradas do Telegram respondem de volta no Telegram (o modelo não escolhe canais).
|
||||
- Mensagens de entrada são normalizadas no envelope de canal compartilhado com metadados de resposta e placeholders de mídia.
|
||||
- O Telegram é controlado pelo processo do Gateway.
|
||||
- O roteamento é determinístico: entradas do Telegram respondem de volta ao Telegram (o modelo não escolhe canais).
|
||||
- Mensagens recebidas são normalizadas no envelope de canal compartilhado com metadados de resposta e placeholders de mídia.
|
||||
- Sessões de grupo são isoladas por ID de grupo. Tópicos de fórum acrescentam `:topic:<threadId>` para manter os tópicos isolados.
|
||||
- Mensagens de DM podem carregar `message_thread_id`; OpenClaw preserva o ID da conversa para respostas, mas mantém DMs na sessão plana por padrão. Configure `channels.telegram.dm.threadReplies: "inbound"`, `channels.telegram.direct.<chatId>.threadReplies: "inbound"`, `requireTopic: true` ou uma configuração de tópico correspondente quando você intencionalmente quiser isolamento de sessão por tópico de DM.
|
||||
- Long polling usa o runner do grammY com sequenciamento por chat/por conversa. A concorrência geral do coletor do runner usa `agents.defaults.maxConcurrent`.
|
||||
- Long polling é protegido dentro de cada processo do Gateway para que apenas um poller ativo possa usar um token de bot por vez. Se você ainda vir conflitos `getUpdates` 409, outro Gateway do OpenClaw, script ou poller externo provavelmente está usando o mesmo token.
|
||||
- Reinicializações do watchdog de long polling são acionadas após 120 segundos sem vivacidade de `getUpdates` concluída por padrão. Aumente `channels.telegram.pollingStallThresholdMs` somente se sua implantação ainda vir reinicializações falsas por travamento de polling durante trabalhos de longa duração. O valor está em milissegundos e é permitido de `30000` a `600000`; substituições por conta são compatíveis.
|
||||
- A Telegram Bot API não oferece suporte a recibos de leitura (`sendReadReceipts` não se aplica).
|
||||
- Mensagens de DM podem carregar `message_thread_id`; o OpenClaw preserva o ID da thread para respostas, mas mantém DMs na sessão plana por padrão. Configure `channels.telegram.dm.threadReplies: "inbound"`, `channels.telegram.direct.<chatId>.threadReplies: "inbound"`, `requireTopic: true` ou uma configuração de tópico correspondente quando você quiser intencionalmente isolamento de sessão por tópico em DM.
|
||||
- A sondagem longa usa o executor do grammY com sequenciamento por chat/por thread. A concorrência geral do coletor do executor usa `agents.defaults.maxConcurrent`.
|
||||
- A sondagem longa é protegida dentro de cada processo de Gateway, de modo que apenas um sondador ativo possa usar um token de bot por vez. Se você ainda vir conflitos `getUpdates` 409, outro Gateway do OpenClaw, script ou sondador externo provavelmente está usando o mesmo token.
|
||||
- Reinicializações do mecanismo de vigilância de sondagem longa são acionadas por padrão após 120 segundos sem liveness concluído de `getUpdates`. Aumente `channels.telegram.pollingStallThresholdMs` somente se sua implantação ainda apresentar reinicializações falsas por paralisação de sondagem durante trabalho de longa duração. O valor é em milissegundos e é permitido de `30000` a `600000`; substituições por conta são compatíveis.
|
||||
- A Bot API do Telegram não tem suporte a recibos de leitura (`sendReadReceipts` não se aplica).
|
||||
|
||||
## Referência de recursos
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Prévia de transmissão ao vivo (edições de mensagem)">
|
||||
OpenClaw pode transmitir respostas parciais em tempo real:
|
||||
O OpenClaw pode transmitir respostas parciais em tempo real:
|
||||
|
||||
- chats diretos: mensagem de prévia + `editMessageText`
|
||||
- grupos/tópicos: mensagem de prévia + `editMessageText`
|
||||
@ -285,12 +285,12 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
Requisito:
|
||||
|
||||
- `channels.telegram.streaming` é `off | partial | block | progress` (padrão: `partial`)
|
||||
- `progress` mantém um rascunho de status editável e o atualiza com progresso de ferramentas até a entrega final
|
||||
- `progress` mantém um rascunho de status editável e o atualiza com o progresso da ferramenta até a entrega final
|
||||
- `streaming.preview.toolProgress` controla se atualizações de ferramenta/progresso reutilizam a mesma mensagem de prévia editada (padrão: `true` quando a transmissão de prévia está ativa)
|
||||
- `streaming.preview.commandText` controla detalhes de comando/execução dentro dessas linhas de progresso de ferramenta: `raw` (padrão, preserva o comportamento lançado) ou `status` (somente rótulo da ferramenta)
|
||||
- `channels.telegram.streamMode` legado e valores booleanos de `streaming` são detectados; execute `openclaw doctor --fix` para migrá-los para `channels.telegram.streaming.mode`
|
||||
- valores legados `channels.telegram.streamMode` e booleanos de `streaming` são detectados; execute `openclaw doctor --fix` para migrá-los para `channels.telegram.streaming.mode`
|
||||
|
||||
Atualizações de prévia de progresso de ferramenta são as linhas curtas de status mostradas enquanto ferramentas são executadas, por exemplo execução de comandos, leituras de arquivos, atualizações de planejamento ou resumos de patch. Telegram as mantém ativadas por padrão para corresponder ao comportamento lançado do OpenClaw a partir de `v2026.4.22`. Para manter a prévia editada para o texto da resposta, mas ocultar linhas de progresso de ferramenta, defina:
|
||||
Atualizações de prévia de progresso de ferramenta são as linhas curtas de status exibidas enquanto ferramentas são executadas, por exemplo execução de comandos, leituras de arquivos, atualizações de planejamento ou resumos de patches. O Telegram mantém isso habilitado por padrão para corresponder ao comportamento lançado do OpenClaw desde `v2026.4.22`. Para manter a prévia editada para o texto da resposta, mas ocultar linhas de progresso de ferramenta, defina:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -307,7 +307,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Para manter o progresso de ferramenta visível, mas ocultar texto de comando/execução, defina:
|
||||
Para manter o progresso de ferramenta visível, mas ocultar o texto de comando/execução, defina:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -342,47 +342,47 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Use `streaming.mode: "off"` somente quando quiser entrega apenas final: as edições de pré-visualização do Telegram são desativadas e conversas genéricas de ferramenta/progresso são suprimidas em vez de serem enviadas como mensagens de status independentes. Prompts de aprovação, cargas de mídia e erros ainda passam pela entrega final normal. Use `streaming.preview.toolProgress: false` quando quiser manter apenas as edições de pré-visualização da resposta enquanto oculta as linhas de status de progresso da ferramenta.
|
||||
Use `streaming.mode: "off"` somente quando quiser entrega apenas final: as edições de prévia do Telegram são desativadas e conversas genéricas de ferramenta/progresso são suprimidas em vez de serem enviadas como mensagens de status independentes. Solicitações de aprovação, cargas de mídia e erros ainda passam pela entrega final normal. Use `streaming.preview.toolProgress: false` quando quiser manter apenas as edições de prévia da resposta enquanto oculta as linhas de status de progresso da ferramenta.
|
||||
|
||||
<Note>
|
||||
As respostas a citações selecionadas do Telegram são a exceção. Quando `replyToMode` é `"first"`, `"all"` ou `"batched"` e a mensagem recebida inclui texto de citação selecionado, o OpenClaw envia a resposta final pelo caminho nativo de resposta com citação do Telegram em vez de editar a pré-visualização da resposta, portanto `streaming.preview.toolProgress` não pode mostrar as linhas curtas de status para essa interação. Respostas à mensagem atual sem texto de citação selecionado ainda mantêm o streaming de pré-visualização. Defina `replyToMode: "off"` quando a visibilidade do progresso da ferramenta for mais importante do que respostas nativas com citação, ou defina `streaming.preview.toolProgress: false` para reconhecer essa troca.
|
||||
As respostas do Telegram com citação selecionada são a exceção. Quando `replyToMode` é `"first"`, `"all"` ou `"batched"` e a mensagem recebida inclui texto de citação selecionado, o OpenClaw envia a resposta final pelo caminho nativo de resposta com citação do Telegram em vez de editar a prévia da resposta, portanto `streaming.preview.toolProgress` não consegue mostrar as linhas curtas de status para essa vez. Respostas à mensagem atual sem texto de citação selecionado ainda mantêm o streaming de prévia. Defina `replyToMode: "off"` quando a visibilidade do progresso da ferramenta importar mais do que respostas nativas com citação, ou defina `streaming.preview.toolProgress: false` para reconhecer a troca.
|
||||
</Note>
|
||||
|
||||
Para respostas somente em texto:
|
||||
Para respostas somente de texto:
|
||||
|
||||
- pré-visualizações curtas em DM/grupo/tópico: o OpenClaw mantém a mesma mensagem de pré-visualização e faz uma edição final no mesmo lugar, a menos que uma mensagem visível que não seja de pré-visualização tenha sido enviada depois que a pré-visualização apareceu
|
||||
- pré-visualizações seguidas por saída visível que não seja de pré-visualização: o OpenClaw envia a resposta concluída como uma nova mensagem final e limpa a pré-visualização antiga, para que a resposta final apareça depois da saída intermediária
|
||||
- pré-visualizações com mais de cerca de um minuto: o OpenClaw envia a resposta concluída como uma nova mensagem final e depois limpa a pré-visualização, para que o carimbo de data/hora visível do Telegram reflita o horário de conclusão em vez do horário de criação da pré-visualização
|
||||
- prévias curtas em DM/grupo/tópico: o OpenClaw mantém a mesma mensagem de prévia e faz uma edição final no lugar, a menos que uma mensagem visível que não seja prévia tenha sido enviada depois que a prévia apareceu
|
||||
- prévias seguidas por saída visível que não é prévia: o OpenClaw envia a resposta concluída como uma nova mensagem final e limpa a prévia mais antiga, de modo que a resposta final apareça depois da saída intermediária
|
||||
- prévias com mais de cerca de um minuto: o OpenClaw envia a resposta concluída como uma nova mensagem final e depois limpa a prévia, de modo que o carimbo de data/hora visível do Telegram reflita o horário de conclusão em vez do horário de criação da prévia
|
||||
|
||||
Para respostas complexas (por exemplo, cargas de mídia), o OpenClaw recorre à entrega final normal e depois limpa a mensagem de pré-visualização.
|
||||
Para respostas complexas (por exemplo, cargas de mídia), o OpenClaw retorna à entrega final normal e depois limpa a mensagem de prévia.
|
||||
|
||||
O streaming de pré-visualização é separado do streaming de blocos. Quando o streaming de blocos é explicitamente ativado para o Telegram, o OpenClaw ignora o stream de pré-visualização para evitar streaming duplicado.
|
||||
O streaming de prévia é separado do streaming em bloco. Quando o streaming em bloco está explicitamente ativado para Telegram, o OpenClaw ignora o stream de prévia para evitar streaming duplicado.
|
||||
|
||||
Stream de raciocínio somente no Telegram:
|
||||
Stream de raciocínio somente do Telegram:
|
||||
|
||||
- `/reasoning stream` envia o raciocínio para a pré-visualização ao vivo durante a geração
|
||||
- a pré-visualização do raciocínio é excluída após a entrega final; use `/reasoning on` quando o raciocínio deve permanecer visível
|
||||
- `/reasoning stream` envia o raciocínio para a prévia ao vivo durante a geração
|
||||
- a prévia do raciocínio é excluída após a entrega final; use `/reasoning on` quando o raciocínio deve permanecer visível
|
||||
- a resposta final é enviada sem texto de raciocínio
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Formatação e fallback de HTML">
|
||||
O texto de saída usa `parse_mode: "HTML"` do Telegram.
|
||||
O texto de saída usa Telegram `parse_mode: "HTML"`.
|
||||
|
||||
- Texto no estilo Markdown é renderizado como HTML seguro para o Telegram.
|
||||
- Texto no estilo Markdown é renderizado como HTML seguro para Telegram.
|
||||
- HTML bruto do modelo é escapado para reduzir falhas de análise do Telegram.
|
||||
- Se o Telegram rejeitar o HTML analisado, o OpenClaw tenta novamente como texto simples.
|
||||
- Se o Telegram rejeitar HTML analisado, o OpenClaw tenta novamente como texto simples.
|
||||
|
||||
Pré-visualizações de links são ativadas por padrão e podem ser desativadas com `channels.telegram.linkPreview: false`.
|
||||
Prévias de link são ativadas por padrão e podem ser desativadas com `channels.telegram.linkPreview: false`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Comandos nativos e comandos personalizados">
|
||||
O registro do menu de comandos do Telegram é tratado na inicialização com `setMyCommands`.
|
||||
|
||||
Padrões de comando nativo:
|
||||
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:
|
||||
|
||||
@ -403,28 +403,28 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
- nomes são normalizados (remove `/` inicial, minúsculas)
|
||||
- padrão válido: `a-z`, `0-9`, `_`, comprimento `1..32`
|
||||
- comandos personalizados não podem substituir comandos nativos
|
||||
- conflitos/duplicatas são ignorados e registrados em log
|
||||
- comandos personalizados não podem sobrescrever comandos nativos
|
||||
- conflitos/duplicados são ignorados e registrados
|
||||
|
||||
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/skill ainda podem funcionar quando digitados, mesmo que não apareçam no menu do Telegram
|
||||
|
||||
Se comandos nativos estiverem desativados, os integrados serão removidos. Comandos personalizados/de Plugin ainda podem ser registrados se configurados.
|
||||
Se comandos nativos estiverem desativados, os integrados 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 a redução; reduza comandos de Plugin/Skills/personalizados ou desative `channels.telegram.commands.native`.
|
||||
- Falha em `deleteWebhook`, `deleteMyCommands` ou `setMyCommands` com `404: Not Found` enquanto comandos curl diretos da Bot API funcionam pode significar que `channels.telegram.apiRoot` foi definido como o endpoint completo `/bot<TOKEN>`. `apiRoot` deve ser apenas a raiz da Bot API, e `openclaw doctor --fix` remove um `/bot<TOKEN>` final acidental.
|
||||
- `getMe returned 401` significa que o Telegram rejeitou o token do bot configurado. Atualize `botToken`, `tokenFile` ou `TELEGRAM_BOT_TOKEN` com o token atual do BotFather; o OpenClaw para antes do polling, então isso não é relatado como uma falha de limpeza de Webhook.
|
||||
- `setMyCommands failed` com `BOT_COMMANDS_TOO_MUCH` significa que o menu do Telegram ainda excedeu o limite após a redução; reduza comandos de plugin/skill/personalizados ou desative `channels.telegram.commands.native`.
|
||||
- Falha de `deleteWebhook`, `deleteMyCommands` ou `setMyCommands` com `404: Not Found` enquanto comandos diretos `curl` da Bot API funcionam pode significar que `channels.telegram.apiRoot` foi definido como o endpoint completo `/bot<TOKEN>`. `apiRoot` deve ser apenas a raiz da Bot API, e `openclaw doctor --fix` remove um `/bot<TOKEN>` acidental no final.
|
||||
- `getMe returned 401` significa que o Telegram rejeitou o token de bot configurado. Atualize `botToken`, `tokenFile` ou `TELEGRAM_BOT_TOKEN` com o token atual do BotFather; o OpenClaw para antes do polling, então isso não é relatado como falha de limpeza de Webhook.
|
||||
- `setMyCommands failed` com erros de rede/fetch geralmente significa que DNS/HTTPS de saída para `api.telegram.org` está bloqueado.
|
||||
|
||||
### Comandos de pareamento de dispositivo (Plugin `device-pair`)
|
||||
|
||||
Quando o Plugin `device-pair` está instalado:
|
||||
|
||||
1. `/pair` gera o código de configuração
|
||||
1. `/pair` gera código de configuração
|
||||
2. cole o código no app iOS
|
||||
3. `/pair pending` lista solicitações pendentes (incluindo função/escopos)
|
||||
4. aprove a solicitação:
|
||||
@ -432,9 +432,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `/pair approve` quando há apenas uma solicitação pendente
|
||||
- `/pair approve latest` para a mais recente
|
||||
|
||||
O código de configuração carrega um token de bootstrap de curta duração. A transferência de bootstrap integrada mantém o token do nó principal em `scopes: []`; qualquer token de operador transferido permanece limitado a `operator.approvals`, `operator.read`, `operator.talk.secrets` e `operator.write`. As verificações de escopo de bootstrap são prefixadas por função, portanto essa allowlist de operador só satisfaz solicitações de operador; funções que não sejam de operador ainda precisam de escopos sob seu próprio prefixo de função.
|
||||
O código de configuração carrega um token de bootstrap de curta duração. A transferência de bootstrap integrada mantém o token do nó principal 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 têm prefixo de função, então essa lista de permissões de operador satisfaz apenas solicitações de operador; funções não operadoras ainda precisam de escopos sob seu próprio prefixo de função.
|
||||
|
||||
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.
|
||||
Se um dispositivo tentar novamente com detalhes de autenticação alterados (por exemplo, função/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.
|
||||
|
||||
Mais detalhes: [Pareamento](/pt-BR/channels/pairing#pair-via-telegram-recommended-for-ios).
|
||||
|
||||
@ -481,7 +481,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `all`
|
||||
- `allowlist` (padrão)
|
||||
|
||||
`capabilities: ["inlineButtons"]` legado é mapeado para `inlineButtons: "all"`.
|
||||
`capabilities: ["inlineButtons"]` legado mapeia para `inlineButtons: "all"`.
|
||||
|
||||
Exemplo de ação de mensagem:
|
||||
|
||||
@ -501,7 +501,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Cliques de callback são passados ao agente como texto:
|
||||
Cliques de callback são passados para o agente como texto:
|
||||
`callback_data: <value>`
|
||||
|
||||
</Accordion>
|
||||
@ -509,33 +509,33 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
<Accordion title="Ações de mensagem do Telegram para agentes e automação">
|
||||
As ações de ferramenta do Telegram incluem:
|
||||
|
||||
- `sendMessage` (`to`, `content`, opcional `mediaUrl`, `replyToMessageId`, `messageThreadId`)
|
||||
- `sendMessage` (`to`, `content`, `mediaUrl` opcional, `replyToMessageId`, `messageThreadId`)
|
||||
- `react` (`chatId`, `messageId`, `emoji`)
|
||||
- `deleteMessage` (`chatId`, `messageId`)
|
||||
- `editMessage` (`chatId`, `messageId`, `content`)
|
||||
- `createForumTopic` (`chatId`, `name`, opcional `iconColor`, `iconCustomEmojiId`)
|
||||
- `createForumTopic` (`chatId`, `name`, `iconColor` opcional, `iconCustomEmojiId`)
|
||||
|
||||
Ações de mensagem de canal expõem aliases ergonômicos (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`).
|
||||
|
||||
Controles de bloqueio:
|
||||
Controles de habilitação:
|
||||
|
||||
- `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` atualmente são ativados por padrão e não têm alternâncias separadas em `channels.telegram.actions.*`.
|
||||
Envios em tempo de execução usam o snapshot ativo de configuração/segredos (inicialização/recarregamento), então caminhos de ação não fazem nova resolução ad hoc de SecretRef a cada envio.
|
||||
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 tempo de execução usam o snapshot ativo de configuração/segredos (inicialização/recarregamento), então caminhos de ação não fazem nova resolução ad hoc de SecretRef por envio.
|
||||
|
||||
Semântica de remoção de reação: [/tools/reactions](/pt-BR/tools/reactions)
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Tags de encadeamento de resposta">
|
||||
O Telegram oferece suporte a tags explícitas de encadeamento de resposta na saída gerada:
|
||||
<Accordion title="Tags de encadeamento de respostas">
|
||||
O Telegram dá suporte a tags explícitas de encadeamento de respostas na saída gerada:
|
||||
|
||||
- `[[reply_to_current]]` responde à mensagem acionadora
|
||||
- `[[reply_to:<id>]]` responde a um ID específico de mensagem do Telegram
|
||||
- `[[reply_to:<id>]]` responde a um ID de mensagem específico do Telegram
|
||||
|
||||
`channels.telegram.replyToMode` controla o tratamento:
|
||||
|
||||
@ -543,9 +543,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `first`
|
||||
- `all`
|
||||
|
||||
Quando o encadeamento de resposta está ativado e o texto ou a legenda original do Telegram está disponível, o OpenClaw inclui automaticamente um trecho de citação nativa do Telegram. O Telegram limita o texto de citação nativa a 1024 unidades de código UTF-16, então mensagens mais longas são citadas a partir do início e recorrem a uma resposta simples se o Telegram rejeitar a citação.
|
||||
Quando o encadeamento de respostas está ativado e o texto ou a legenda original do Telegram está disponível, o OpenClaw inclui automaticamente um trecho de citação nativa do Telegram. O Telegram limita texto de citação nativa a 1024 unidades de código UTF-16, então mensagens mais longas são citadas desde o início e retornam a uma resposta simples se o Telegram rejeitar a citação.
|
||||
|
||||
Observação: `off` desativa o encadeamento implícito de resposta. Tags explícitas `[[reply_to_*]]` ainda são respeitadas.
|
||||
Observação: `off` desativa o encadeamento implícito de respostas. Tags explícitas `[[reply_to_*]]` ainda são respeitadas.
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -553,17 +553,17 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
Supergrupos de fórum:
|
||||
|
||||
- chaves de sessão de tópico acrescentam `:topic:<threadId>`
|
||||
- respostas e indicação de digitação miram a thread do tópico
|
||||
- caminho de configuração de tópico:
|
||||
- respostas e digitação miram a thread do tópico
|
||||
- caminho de configuração do tópico:
|
||||
`channels.telegram.groups.<chatId>.topics.<threadId>`
|
||||
|
||||
Caso especial do tópico geral (`threadId=1`):
|
||||
Caso especial do tópico Geral (`threadId=1`):
|
||||
|
||||
- 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, a menos que sejam substituídas (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`).
|
||||
`agentId` é exclusivo do tópico e não herda os padrões do grupo.
|
||||
Herança de tópico: entradas de tópico herdam configurações de grupo, a menos que sejam sobrescritas (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`).
|
||||
`agentId` é somente 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:
|
||||
|
||||
@ -587,24 +587,24 @@ 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`
|
||||
|
||||
**Vínculo persistente de tópico ACP**: Tópicos de fórum podem fixar sessões de harness ACP por meio de vínculos ACP tipados de nível superior (`bindings[]` com `type: "acp"` e `match.channel: "telegram"`, `peer.kind: "group"` e um id qualificado por tópico como `-1001234567890:topic:42`). Atualmente limitado a tópicos de fórum em grupos/supergrupos. Consulte [Agentes ACP](/pt-BR/tools/acp-agents).
|
||||
**Vinculação persistente de tópico ACP**: Tópicos de fórum podem fixar sessões de harness ACP por meio de vinculações ACP tipadas de nível superior (`bindings[]` com `type: "acp"` e `match.channel: "telegram"`, `peer.kind: "group"` e um id qualificado por tópico como `-1001234567890:topic:42`). Atualmente limitado a tópicos de fórum em grupos/supergrupos. Consulte [Agentes ACP](/pt-BR/tools/acp-agents).
|
||||
|
||||
**Spawn de ACP vinculado à thread a partir do chat**: `/acp spawn <agent> --thread here|auto` vincula o tópico atual a uma nova sessão ACP; acompanhamentos são roteados diretamente para lá. O OpenClaw fixa a confirmação de spawn no tópico. Exige que `channels.telegram.threadBindings.spawnSessions` permaneça ativado (padrão: `true`).
|
||||
**Geração de ACP vinculada à thread a partir do chat**: `/acp spawn <agent> --thread here|auto` vincula o tópico atual a uma nova sessão ACP; acompanhamentos são roteados diretamente para lá. O OpenClaw fixa a confirmação de geração no tópico. Exige que `channels.telegram.threadBindings.spawnSessions` permaneça ativado (padrão: `true`).
|
||||
|
||||
O contexto do template expõe `MessageThreadId` e `IsForum`. Conversas diretas com `message_thread_id` mantêm roteamento de mensagem direta e metadados de resposta em sessões planas por padrão; elas só usam chaves de sessão com reconhecimento de encadeamento quando configuradas com `threadReplies: "inbound"`, `threadReplies: "always"`, `requireTopic: true` ou uma configuração de tópico correspondente. Use `channels.telegram.dm.threadReplies` no nível superior para o padrão da conta, ou `direct.<chatId>.threadReplies` para uma conversa direta.
|
||||
O contexto do template expõe `MessageThreadId` e `IsForum`. Chats de DM com `message_thread_id` mantêm o roteamento de DM e os metadados de resposta em sessões planas por padrão; eles só usam chaves de sessão cientes de threads quando configurados com `threadReplies: "inbound"`, `threadReplies: "always"`, `requireTopic: true` ou uma configuração de tópico correspondente. Use `channels.telegram.dm.threadReplies` no nível superior como padrão da conta, ou `direct.<chatId>.threadReplies` para uma DM.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Áudio, vídeo e figurinhas">
|
||||
<Accordion title="Áudio, vídeo e stickers">
|
||||
### Mensagens de áudio
|
||||
|
||||
O Telegram distingue 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 o envio como nota de voz
|
||||
- transcrições de notas de voz recebidas são enquadradas como texto gerado por máquina
|
||||
e não confiável no contexto do agente; a detecção de menção ainda usa a transcrição
|
||||
bruta para que mensagens de voz controladas por menção continuem funcionando.
|
||||
- transcrições de notas de voz recebidas são enquadradas como texto gerado por máquina,
|
||||
não confiável, no contexto do agente; a detecção de menções ainda usa a transcrição
|
||||
bruta, então mensagens de voz controladas por menção continuam funcionando.
|
||||
|
||||
Exemplo de ação de mensagem:
|
||||
|
||||
@ -634,17 +634,17 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Notas de vídeo não aceitam legendas; o texto de mensagem fornecido é enviado separadamente.
|
||||
Notas de vídeo não oferecem suporte a legendas; o texto da mensagem fornecido é enviado separadamente.
|
||||
|
||||
### Figurinhas
|
||||
### Stickers
|
||||
|
||||
Tratamento de figurinhas recebidas:
|
||||
Tratamento de stickers recebidos:
|
||||
|
||||
- WEBP estático: baixado e processado (placeholder `<media:sticker>`)
|
||||
- TGS animado: ignorado
|
||||
- WEBM de vídeo: ignorado
|
||||
|
||||
Campos de contexto de figurinha:
|
||||
Campos de contexto de sticker:
|
||||
|
||||
- `Sticker.emoji`
|
||||
- `Sticker.setName`
|
||||
@ -652,13 +652,13 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `Sticker.fileUniqueId`
|
||||
- `Sticker.cachedDescription`
|
||||
|
||||
Arquivo de cache de figurinhas:
|
||||
Arquivo de cache de stickers:
|
||||
|
||||
- `~/.openclaw/telegram/sticker-cache.json`
|
||||
|
||||
Figurinhas são descritas uma vez (quando possível) e armazenadas em cache para reduzir chamadas de visão repetidas.
|
||||
Stickers são descritos uma vez (quando possível) e armazenados em cache para reduzir chamadas repetidas de visão.
|
||||
|
||||
Habilitar ações de figurinha:
|
||||
Ativar ações de sticker:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -672,7 +672,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Ação para enviar figurinha:
|
||||
Ação para enviar sticker:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -683,7 +683,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Pesquisar figurinhas em cache:
|
||||
Pesquisar stickers em cache:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -697,9 +697,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Notificações de reação">
|
||||
As reações do Telegram chegam como atualizações `message_reaction` (separadas dos conteúdos das mensagens).
|
||||
Reações do Telegram chegam como atualizações `message_reaction` (separadas dos payloads de mensagem).
|
||||
|
||||
Quando habilitado, o OpenClaw enfileira eventos de sistema como:
|
||||
Quando ativado, o OpenClaw enfileira eventos de sistema como:
|
||||
|
||||
- `Telegram reaction added: 👍 by Alice (@alice) on msg 42`
|
||||
|
||||
@ -712,11 +712,11 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
- `own` significa apenas reações de usuários a mensagens enviadas pelo bot (melhor esforço via cache de mensagens enviadas).
|
||||
- Eventos de reação ainda respeitam os controles de acesso do Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); remetentes não autorizados são descartados.
|
||||
- O Telegram não fornece IDs de encadeamento em atualizações de reação.
|
||||
- grupos que não são fóruns roteiam para a sessão do chat em grupo
|
||||
- grupos de fórum roteiam para a sessão do tópico geral do grupo (`:topic:1`), não para o tópico exato de origem
|
||||
- O Telegram não fornece IDs de thread em atualizações de reação.
|
||||
- grupos sem fórum roteiam para a sessão de chat do grupo
|
||||
- grupos com fórum roteiam para a sessão de tópico geral do grupo (`:topic:1`), não para o tópico exato de origem
|
||||
|
||||
`allowed_updates` para sondagem/Webhook inclui `message_reaction` automaticamente.
|
||||
`allowed_updates` para polling/Webhook inclui `message_reaction` automaticamente.
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -728,24 +728,24 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `channels.telegram.accounts.<accountId>.ackReaction`
|
||||
- `channels.telegram.ackReaction`
|
||||
- `messages.ackReaction`
|
||||
- alternativa de emoji da identidade do agente (`agents.list[].identity.emoji`, senão "👀")
|
||||
- fallback do emoji da identidade do agente (`agents.list[].identity.emoji`, senão "👀")
|
||||
|
||||
Observações:
|
||||
|
||||
- O Telegram espera emoji Unicode (por exemplo, "👀").
|
||||
- Use `""` para desabilitar a reação para um canal ou uma conta.
|
||||
- O Telegram espera emoji unicode (por exemplo, "👀").
|
||||
- Use `""` para desativar a reação para um canal ou conta.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Gravações de configuração de eventos e comandos do Telegram">
|
||||
Gravações de configuração de canal são habilitadas por padrão (`configWrites !== false`).
|
||||
<Accordion title="Gravações de configuração a partir de eventos e comandos do Telegram">
|
||||
Gravações de configuração de canal são ativadas por padrão (`configWrites !== false`).
|
||||
|
||||
Gravações disparadas pelo Telegram incluem:
|
||||
|
||||
- eventos de migração de grupo (`migrate_to_chat_id`) para atualizar `channels.telegram.groups`
|
||||
- `/config set` e `/config unset` (requer habilitação de comando)
|
||||
- `/config set` e `/config unset` (exige ativação de comandos)
|
||||
|
||||
Desabilitar:
|
||||
Desativar:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -759,39 +759,40 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Sondagem longa vs Webhook">
|
||||
O padrão é sondagem longa. Para o modo Webhook, defina `channels.telegram.webhookUrl` e `channels.telegram.webhookSecret`; opcionais: `webhookPath`, `webhookHost`, `webhookPort` (padrões `/telegram-webhook`, `127.0.0.1`, `8787`).
|
||||
<Accordion title="Long polling vs Webhook">
|
||||
O padrão é long polling. Para o modo Webhook, defina `channels.telegram.webhookUrl` e `channels.telegram.webhookSecret`; `webhookPath`, `webhookHost`, `webhookPort` opcionais (padrões `/telegram-webhook`, `127.0.0.1`, `8787`).
|
||||
|
||||
O ouvinte local se vincula a `127.0.0.1:8787`. Para entrada pública, coloque um proxy reverso na frente da porta local ou defina `webhookHost: "0.0.0.0"` intencionalmente.
|
||||
O listener local faz bind em `127.0.0.1:8787`. Para ingresso público, coloque um proxy reverso na frente da porta local ou defina `webhookHost: "0.0.0.0"` intencionalmente.
|
||||
|
||||
O modo Webhook valida proteções de requisição, o token secreto do Telegram e o corpo JSON antes de retornar `200` ao Telegram.
|
||||
O OpenClaw então processa a atualização de forma assíncrona pelas mesmas filas do bot por chat/por tópico usadas pela sondagem longa, então turnos lentos do agente não seguram a confirmação de entrega do Telegram.
|
||||
O modo Webhook valida proteções de solicitação, o token secreto do Telegram e o corpo JSON antes de retornar `200` ao Telegram.
|
||||
O OpenClaw então processa a atualização de forma assíncrona pelas mesmas filas de bot por chat/por tópico usadas pelo long polling, então turnos lentos do agente não seguram o ACK de entrega do Telegram.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<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 tamanho.
|
||||
- `channels.telegram.mediaMaxMb` (padrão 100) limita o tamanho de mídia recebida e enviada pelo Telegram.
|
||||
- `channels.telegram.mediaGroupFlushMs` (padrão 500) controla por quanto tempo álbuns/grupos de mídia do Telegram são mantidos em buffer antes que o OpenClaw os despache como uma única mensagem recebida. Aumente esse valor se partes do álbum chegarem tarde; reduza-o para diminuir a latência de resposta do álbum.
|
||||
- `channels.telegram.timeoutSeconds` substitui o tempo limite do cliente da API do Telegram (se não definido, aplica-se o padrão do grammY). Clientes de bot limitam valores configurados abaixo da proteção de requisição de texto/digitação de saída de 60 segundos para que o grammY não aborte a entrega da resposta visível antes que a proteção de transporte e a alternativa do OpenClaw possam executar. A sondagem longa ainda usa uma proteção de requisição `getUpdates` de 45 segundos para que sondagens ociosas não sejam abandonadas indefinidamente.
|
||||
- O padrão de `channels.telegram.pollingStallThresholdMs` é `120000`; ajuste entre `30000` e `600000` apenas para reinícios de sondagem travada por falso positivo.
|
||||
- O histórico de contexto de grupo usa `channels.telegram.historyLimit` ou `messages.groupChat.historyLimit` (padrão 50); `0` desabilita.
|
||||
- Contexto suplementar de resposta/citação/encaminhamento é atualmente passado como recebido.
|
||||
- Listas de permissão do Telegram controlam principalmente quem pode acionar o agente, não uma fronteira completa de redação de contexto suplementar.
|
||||
- Controles de histórico de mensagens diretas:
|
||||
<Accordion title="Limites, repetição e destinos da CLI">
|
||||
- `channels.telegram.textChunkLimit` tem padrão 4000.
|
||||
- `channels.telegram.chunkMode="newline"` prefere limites de parágrafo (linhas em branco) antes de dividir por comprimento.
|
||||
- `channels.telegram.mediaMaxMb` (padrão 100) limita o tamanho de mídia recebida e enviada do Telegram.
|
||||
- `channels.telegram.mediaGroupFlushMs` (padrão 500) controla por quanto tempo álbuns/grupos de mídia do Telegram são armazenados em buffer antes que o OpenClaw os despache como uma mensagem recebida. Aumente se partes do álbum chegarem tarde; diminua para reduzir a latência de resposta do álbum.
|
||||
- `channels.telegram.timeoutSeconds` substitui o timeout do cliente da API do Telegram (se não definido, o padrão do grammY se aplica). Clientes de bot limitam valores configurados abaixo da proteção de solicitação de texto/digitação de saída de 60 segundos, para que o grammY não aborte a entrega de respostas visíveis antes que a proteção de transporte e o fallback do OpenClaw possam executar. Long polling ainda usa uma proteção de solicitação `getUpdates` de 45 segundos, para que polls ociosos não sejam abandonados indefinidamente.
|
||||
- `channels.telegram.pollingStallThresholdMs` usa `120000` por padrão; ajuste entre `30000` e `600000` apenas para reinícios por travamento de polling falsos positivos.
|
||||
- o histórico de contexto de grupo usa `channels.telegram.historyLimit` ou `messages.groupChat.historyLimit` (padrão 50); `0` desativa.
|
||||
- contexto suplementar de resposta/citação/encaminhamento atualmente é passado como recebido.
|
||||
- allowlists do Telegram controlam principalmente quem pode acionar o agente, não uma fronteira completa de redação de contexto suplementar.
|
||||
- controles de histórico de DM:
|
||||
- `channels.telegram.dmHistoryLimit`
|
||||
- `channels.telegram.dms["<user_id>"].historyLimit`
|
||||
- A configuração `channels.telegram.retry` se aplica aos auxiliares de envio do Telegram (CLI/ferramentas/ações) para erros recuperáveis da API de saída. A entrega da resposta final a mensagens recebidas também usa uma nova tentativa limitada de envio seguro para falhas pré-conexão do Telegram, mas não repete envelopes de rede ambíguos pós-envio que poderiam duplicar mensagens visíveis.
|
||||
- a configuração `channels.telegram.retry` se aplica aos helpers de envio do Telegram (CLI/ferramentas/ações) para erros recuperáveis da API de saída. A entrega da resposta final recebida também usa uma repetição safe-send limitada para falhas de pré-conexão do Telegram, mas não repete envelopes de rede ambíguos pós-envio que poderiam duplicar mensagens visíveis.
|
||||
|
||||
O destino de envio da CLI pode ser um ID numérico de chat ou um nome de usuário:
|
||||
Destinos de envio da CLI e da ferramenta de mensagem podem ser ID numérico do chat, nome de usuário ou um destino de tópico de fórum:
|
||||
|
||||
```bash
|
||||
openclaw message send --channel telegram --target 123456789 --message "hi"
|
||||
openclaw message send --channel telegram --target @name --message "hi"
|
||||
openclaw message send --channel telegram --target -1001234567890:topic:42 --message "hi topic"
|
||||
```
|
||||
|
||||
Enquetes do Telegram usam `openclaw message poll` e aceitam tópicos de fórum:
|
||||
Polls do Telegram usam `openclaw message poll` e oferecem suporte a tópicos de fórum:
|
||||
|
||||
```bash
|
||||
openclaw message poll --channel telegram --target 123456789 \
|
||||
@ -801,41 +802,41 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
--poll-duration-seconds 300 --poll-public
|
||||
```
|
||||
|
||||
Opções de enquete exclusivas do Telegram:
|
||||
Flags de poll exclusivas do Telegram:
|
||||
|
||||
- `--poll-duration-seconds` (5-600)
|
||||
- `--poll-anonymous`
|
||||
- `--poll-public`
|
||||
- `--thread-id` para tópicos de fórum (ou use um destino `:topic:`)
|
||||
|
||||
O envio pelo Telegram também aceita:
|
||||
O envio pelo Telegram também oferece suporte a:
|
||||
|
||||
- `--presentation` com blocos `buttons` para teclados em linha quando `channels.telegram.capabilities.inlineButtons` permite
|
||||
- `--pin` ou `--delivery '{"pin":true}'` para solicitar entrega fixada quando o bot puder fixar nesse chat
|
||||
- `--presentation` com blocos `buttons` para teclados inline quando `channels.telegram.capabilities.inlineButtons` permite
|
||||
- `--pin` ou `--delivery '{"pin":true}'` para solicitar entrega fixada quando o bot pode fixar naquele chat
|
||||
- `--force-document` para enviar imagens e GIFs de saída como documentos em vez de uploads de foto compactada ou mídia animada
|
||||
|
||||
Controle de ações:
|
||||
|
||||
- `channels.telegram.actions.sendMessage=false` desabilita mensagens de saída do Telegram, incluindo enquetes
|
||||
- `channels.telegram.actions.poll=false` desabilita a criação de enquetes do Telegram enquanto mantém envios regulares habilitados
|
||||
- `channels.telegram.actions.sendMessage=false` desativa mensagens de saída do Telegram, incluindo polls
|
||||
- `channels.telegram.actions.poll=false` desativa a criação de polls do Telegram, mantendo envios regulares ativados
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Aprovações de execução no Telegram">
|
||||
O Telegram oferece suporte a aprovações de execução em mensagens diretas de aprovadores e pode, opcionalmente, publicar solicitações no chat ou tópico de origem. Aprovadores devem ser IDs numéricos de usuário do Telegram.
|
||||
O Telegram oferece suporte a aprovações de execução em DMs de aprovadores e pode opcionalmente publicar prompts no chat ou tópico de origem. Aprovadores devem ser IDs numéricos de usuários do Telegram.
|
||||
|
||||
Caminho de configuração:
|
||||
|
||||
- `channels.telegram.execApprovals.enabled` (habilita automaticamente quando pelo menos um aprovador é resolvível)
|
||||
- `channels.telegram.execApprovals.approvers` (recorre aos IDs numéricos dos proprietários em `commands.ownerAllowFrom`)
|
||||
- `channels.telegram.execApprovals.enabled` (ativado automaticamente quando pelo menos um aprovador pode ser resolvido)
|
||||
- `channels.telegram.execApprovals.approvers` (recai para IDs numéricos de proprietários de `commands.ownerAllowFrom`)
|
||||
- `channels.telegram.execApprovals.target`: `dm` (padrão) | `channel` | `both`
|
||||
- `agentFilter`, `sessionFilter`
|
||||
|
||||
`channels.telegram.allowFrom`, `groupAllowFrom` e `defaultTo` controlam quem pode falar com o bot e para onde ele envia respostas normais. Eles não tornam alguém um aprovador de execução. O primeiro pareamento de mensagem direta aprovado inicializa `commands.ownerAllowFrom` quando ainda não existe proprietário de comando, então a configuração com um único proprietário ainda funciona sem duplicar IDs em `execApprovals.approvers`.
|
||||
`channels.telegram.allowFrom`, `groupAllowFrom` e `defaultTo` controlam quem pode falar com o bot e para onde ele envia respostas normais. Eles não tornam alguém um aprovador de execução. O primeiro pareamento de DM aprovado inicializa `commands.ownerAllowFrom` quando ainda não existe proprietário de comando, então a configuração com um único proprietário ainda funciona sem duplicar IDs em `execApprovals.approvers`.
|
||||
|
||||
A entrega no canal mostra o texto do comando no chat; habilite `channel` ou `both` apenas em grupos/tópicos confiáveis. Quando a solicitação chega em um tópico de fórum, o OpenClaw preserva o tópico para a solicitação de aprovação e o acompanhamento. Aprovações de execução expiram após 30 minutos por padrão.
|
||||
A entrega no canal mostra o texto do comando no chat; ative `channel` ou `both` apenas em grupos/tópicos confiáveis. Quando o prompt chega a um tópico de fórum, o OpenClaw preserva o tópico para o prompt de aprovação e o acompanhamento. Aprovações de execução expiram após 30 minutos por padrão.
|
||||
|
||||
Botões de aprovação em linha também exigem que `channels.telegram.capabilities.inlineButtons` permita a superfície de destino (`dm`, `group` ou `all`). IDs de aprovação prefixados com `plugin:` são resolvidos por aprovações de Plugin; os demais são resolvidos primeiro por aprovações de execução.
|
||||
Botões inline de aprovação também exigem que `channels.telegram.capabilities.inlineButtons` permita a superfície de destino (`dm`, `group` ou `all`). IDs de aprovação prefixados com `plugin:` são resolvidos por aprovações de Plugin; outros são resolvidos primeiro por aprovações de execução.
|
||||
|
||||
Consulte [Aprovações de execução](/pt-BR/tools/exec-approvals).
|
||||
|
||||
@ -846,12 +847,12 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
|
||||
Quando o agente encontra um erro de entrega ou de provedor, o Telegram pode responder com o texto do erro ou suprimi-lo. Duas chaves de configuração controlam esse comportamento:
|
||||
|
||||
| Chave | Valores | Padrão | Descrição |
|
||||
| ----------------------------------- | ----------------- | ------- | ----------------------------------------------------------------------------------------------- |
|
||||
| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` envia uma mensagem de erro amigável ao chat. `silent` suprime totalmente respostas de erro. |
|
||||
| Chave | Valores | Padrão | Descrição |
|
||||
| ----------------------------------- | ----------------- | ------- | ------------------------------------------------------------------------------------------ |
|
||||
| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` envia uma mensagem de erro amigável ao chat. `silent` suprime respostas de erro por completo. |
|
||||
| `channels.telegram.errorCooldownMs` | número (ms) | `60000` | Tempo mínimo entre respostas de erro para o mesmo chat. Evita spam de erros durante indisponibilidades. |
|
||||
|
||||
Sobrescritas por conta, grupo e tópico são aceitas (mesma herança de outras chaves de configuração do Telegram).
|
||||
Há suporte a substituições por conta, por grupo e por tópico (mesma herança de outras chaves de configuração do Telegram).
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -875,53 +876,53 @@ Sobrescritas por conta, grupo e tópico são aceitas (mesma herança de outras c
|
||||
<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 total.
|
||||
- BotFather: `/setprivacy` -> Desabilitar
|
||||
- em seguida, remova + adicione o bot novamente ao grupo
|
||||
- BotFather: `/setprivacy` -> Desativar
|
||||
- depois remova e adicione novamente o bot ao grupo
|
||||
- `openclaw channels status` avisa quando a configuração espera mensagens de grupo sem menção.
|
||||
- `openclaw channels status --probe` pode verificar IDs numéricos explícitos de grupo; o curinga `"*"` não pode ter a associação verificada.
|
||||
- `openclaw channels status --probe` pode verificar IDs numéricos explícitos de grupos; o curinga `"*"` não pode ter a associação verificada.
|
||||
- teste rápido de sessão: `/activation always`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="O bot não está vendo nenhuma mensagem de grupo">
|
||||
<Accordion title="Bot não vê mensagens do grupo de forma alguma">
|
||||
|
||||
- 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
|
||||
- revise os logs: `openclaw logs --follow` para ver os motivos de ignorar mensagens
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Os comandos funcionam parcialmente ou não funcionam">
|
||||
<Accordion title="Comandos funcionam parcialmente ou não funcionam">
|
||||
|
||||
- autorize sua identidade de remetente (pareamento e/ou `allowFrom` numérico)
|
||||
- a autorização de comandos ainda se aplica mesmo quando a política de grupo é `open`
|
||||
- `setMyCommands failed` com `BOT_COMMANDS_TOO_MUCH` significa que o menu nativo tem entradas demais; reduza comandos de Plugin/Skills/personalizados ou desative menus nativos
|
||||
- as chamadas de inicialização `deleteMyCommands` / `setMyCommands` e as chamadas de digitação `sendChatAction` são limitadas e tentam novamente uma vez por meio do fallback de transporte do Telegram em caso de timeout da solicitação. Erros persistentes de rede/fetch geralmente indicam problemas de acessibilidade DNS/HTTPS para `api.telegram.org`
|
||||
- `setMyCommands failed` com `BOT_COMMANDS_TOO_MUCH` significa que o menu nativo tem entradas demais; reduza comandos de Plugin/skill/personalizados ou desative menus nativos
|
||||
- chamadas de inicialização `deleteMyCommands` / `setMyCommands` e chamadas de digitação `sendChatAction` são limitadas e tentadas novamente uma vez pelo fallback de transporte do Telegram em caso de timeout de solicitação. Erros persistentes de rede/fetch geralmente indicam problemas de DNS/HTTPS para acessar `api.telegram.org`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="A inicialização relata token não autorizado">
|
||||
<Accordion title="Inicialização relata token não autorizado">
|
||||
|
||||
- `getMe returned 401` é uma falha de autenticação do Telegram para o token de bot configurado.
|
||||
- Copie novamente ou regenere o token de bot no BotFather e, em seguida, atualize `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts.<id>.botToken` ou `TELEGRAM_BOT_TOKEN` para a conta padrão.
|
||||
- `deleteWebhook 401 Unauthorized` durante a inicialização também é uma falha de autenticação; tratá-la como "nenhum webhook existe" apenas adiaria a mesma falha de token inválido para chamadas de API posteriores.
|
||||
- Copie novamente ou regenere o token do bot no BotFather, depois atualize `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts.<id>.botToken` ou `TELEGRAM_BOT_TOKEN` para a conta padrão.
|
||||
- `deleteWebhook 401 Unauthorized` durante a inicialização também é uma falha de autenticação; tratá-la como "nenhum Webhook existe" apenas adiaria a mesma falha de token inválido para chamadas de API posteriores.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Instabilidade de polling ou rede">
|
||||
<Accordion title="Instabilidade de polling ou de rede">
|
||||
|
||||
- Node 22+ + fetch/proxy personalizado pode acionar comportamento de abort imediato se os tipos de AbortSignal forem incompatíveis.
|
||||
- Alguns hosts resolvem `api.telegram.org` primeiro para IPv6; saída IPv6 quebrada pode causar falhas intermitentes da API do Telegram.
|
||||
- Node 22+ + fetch/proxy personalizado pode acionar comportamento de aborto imediato se os tipos de AbortSignal não corresponderem.
|
||||
- Alguns hosts resolvem `api.telegram.org` primeiro para IPv6; saída IPv6 com problemas pode causar falhas intermitentes na API do Telegram.
|
||||
- Se os logs incluírem `TypeError: fetch failed` ou `Network request for 'getUpdates' failed!`, o OpenClaw agora tenta novamente esses erros como erros de rede recuperáveis.
|
||||
- Durante a inicialização do polling, o OpenClaw reutiliza a sondagem `getMe` bem-sucedida da inicialização para o grammY, para que o executor não precise de um segundo `getMe` antes do primeiro `getUpdates`.
|
||||
- Se `deleteWebhook` falhar com um erro de rede transitório durante a inicialização do polling, o OpenClaw continua para long polling em vez de fazer outra chamada de plano de controle antes do polling. Um Webhook ainda ativo aparece como um conflito de `getUpdates`; então o OpenClaw reconstrói o transporte do Telegram e tenta novamente a limpeza do Webhook.
|
||||
- Se os sockets do Telegram forem reciclados em uma cadência fixa curta, verifique se `channels.telegram.timeoutSeconds` está baixo; clientes de bot limitam valores configurados abaixo dos limites de solicitações de saída e `getUpdates`, mas versões mais antigas podiam abortar cada polling ou resposta quando isso era definido abaixo desses limites.
|
||||
- Se os logs incluírem `Polling stall detected`, o OpenClaw reinicia o polling e reconstrói o transporte do Telegram após 120 segundos sem liveness concluída de long polling por padrão.
|
||||
- `openclaw channels status --probe` e `openclaw doctor` avisam quando uma conta de polling em execução não concluiu `getUpdates` após a tolerância de inicialização, quando uma conta de Webhook em execução não concluiu `setWebhook` após a tolerância de inicialização, ou quando a última atividade de transporte de polling bem-sucedida está obsoleta.
|
||||
- Aumente `channels.telegram.pollingStallThresholdMs` somente quando chamadas `getUpdates` de longa duração estiverem saudáveis, mas seu host ainda relatar reinicializações falsas por polling travado. Travamentos persistentes geralmente apontam para problemas de proxy, DNS, IPv6 ou saída TLS entre o host e `api.telegram.org`.
|
||||
- O Telegram também respeita env de proxy do processo para transporte da Bot API, incluindo `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` e suas variantes em minúsculas. `NO_PROXY` / `no_proxy` ainda pode contornar `api.telegram.org`.
|
||||
- Se o proxy gerenciado do OpenClaw estiver configurado por meio de `OPENCLAW_PROXY_URL` para um ambiente de serviço e nenhum env de proxy padrão estiver presente, o Telegram também usa essa URL para o transporte da Bot API.
|
||||
- Em hosts VPS com saída direta/TLS instável, roteie chamadas da API do Telegram por meio de `channels.telegram.proxy`:
|
||||
- Durante a inicialização de polling, o OpenClaw reutiliza a sondagem `getMe` bem-sucedida da inicialização para o grammY, de modo que o executor não precise de um segundo `getMe` antes do primeiro `getUpdates`.
|
||||
- Se `deleteWebhook` falhar com um erro de rede transitório durante a inicialização de polling, o OpenClaw continua para long polling em vez de fazer outra chamada de plano de controle antes do polling. Um Webhook ainda ativo aparece como conflito de `getUpdates`; então o OpenClaw reconstrói o transporte do Telegram e tenta novamente a limpeza do Webhook.
|
||||
- Se os sockets do Telegram forem reciclados em uma cadência fixa curta, verifique se `channels.telegram.timeoutSeconds` está baixo; clientes de bot limitam valores configurados abaixo das proteções de solicitações de saída e `getUpdates`, mas versões antigas podiam abortar cada polling ou resposta quando isso era definido abaixo dessas proteções.
|
||||
- Se os logs incluírem `Polling stall detected`, o OpenClaw reinicia o polling e reconstrói o transporte do Telegram após 120 segundos sem liveness de long-poll concluído por padrão.
|
||||
- `openclaw channels status --probe` e `openclaw doctor` avisam quando uma conta de polling em execução não concluiu `getUpdates` após o período de graça da inicialização, quando uma conta de Webhook em execução não concluiu `setWebhook` após o período de graça da inicialização ou quando a última atividade bem-sucedida do transporte de polling está obsoleta.
|
||||
- Aumente `channels.telegram.pollingStallThresholdMs` somente quando chamadas `getUpdates` de longa duração estiverem saudáveis, mas seu host ainda relatar reinicializações falsas por travamento de polling. Travamentos persistentes geralmente apontam para problemas de proxy, DNS, IPv6 ou saída TLS entre o host e `api.telegram.org`.
|
||||
- O Telegram também respeita env de proxy do processo para transporte da Bot API, incluindo `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` e suas variantes em minúsculas. `NO_PROXY` / `no_proxy` ainda pode ignorar `api.telegram.org`.
|
||||
- Se o proxy gerenciado do OpenClaw estiver configurado por `OPENCLAW_PROXY_URL` para um ambiente de serviço e nenhum env de proxy padrão estiver presente, o Telegram também usa essa URL para transporte da Bot API.
|
||||
- Em hosts VPS com saída direta/TLS instável, roteie chamadas da API do Telegram por `channels.telegram.proxy`:
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
@ -929,7 +930,7 @@ channels:
|
||||
proxy: socks5://<user>:<password>@proxy-host:1080
|
||||
```
|
||||
|
||||
- Node 22+ usa `autoSelectFamily=true` por padrão (exceto WSL2). A ordem dos resultados DNS do Telegram respeita `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER`, depois `channels.telegram.network.dnsResultOrder`, depois o padrão do processo, como `NODE_OPTIONS=--dns-result-order=ipv4first`; se nada se aplicar, Node 22+ volta para `ipv4first`.
|
||||
- Node 22+ usa `autoSelectFamily=true` por padrão (exceto WSL2). A ordem de resultados DNS do Telegram respeita `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER`, depois `channels.telegram.network.dnsResultOrder`, depois o padrão do processo, como `NODE_OPTIONS=--dns-result-order=ipv4first`; se nada se aplicar, Node 22+ volta para `ipv4first`.
|
||||
- Se seu host for WSL2 ou funcionar explicitamente melhor com comportamento somente IPv4, force a seleção de família:
|
||||
|
||||
```yaml
|
||||
@ -952,18 +953,19 @@ channels:
|
||||
dangerouslyAllowPrivateNetwork: true
|
||||
```
|
||||
|
||||
- A mesma opção está disponível por conta em
|
||||
- A mesma adesão está disponível por conta em
|
||||
`channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork`.
|
||||
- Se seu proxy resolver hosts de mídia do Telegram para `198.18.x.x`, deixe a
|
||||
flag perigosa desativada primeiro. A mídia do Telegram já permite o intervalo
|
||||
de benchmark RFC 2544 por padrão.
|
||||
|
||||
<Warning>
|
||||
`channels.telegram.network.dangerouslyAllowPrivateNetwork` enfraquece as proteções
|
||||
SSRF de mídia do Telegram. Use-a somente 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 do intervalo de benchmark
|
||||
RFC 2544. Deixe-a desativada 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 somente para ambientes de proxy
|
||||
confiáveis e controlados pelo operador, como roteamento fake-IP do Clash,
|
||||
Mihomo ou Surge, quando eles sintetizam respostas privadas ou de uso especial
|
||||
fora do intervalo de benchmark RFC 2544. Deixe desativado para acesso normal
|
||||
do Telegram pela internet pública.
|
||||
</Warning>
|
||||
|
||||
- Substituições de ambiente (temporárias):
|
||||
@ -986,13 +988,13 @@ Mais ajuda: [Solução de problemas de canais](/pt-BR/channels/troubleshooting).
|
||||
|
||||
Referência principal: [Referência de configuração - Telegram](/pt-BR/gateway/config-channels#telegram).
|
||||
|
||||
<Accordion title="Campos de alto sinal do Telegram">
|
||||
<Accordion title="Campos do Telegram de alto sinal">
|
||||
|
||||
- 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[]` de nível superior (`type: "acp"`)
|
||||
- aprovações de exec: `execApprovals`, `accounts.*.execApprovals`
|
||||
- comando/menu: `commands.native`, `commands.nativeSkills`, `customCommands`
|
||||
- threads/respostas: `replyToMode`, `dm.threadReplies`, `direct.*.threadReplies`
|
||||
- encadeamento/respostas: `replyToMode`, `dm.threadReplies`, `direct.*.threadReplies`
|
||||
- streaming: `streaming` (prévia), `streaming.preview.toolProgress`, `blockStreaming`
|
||||
- formatação/entrega: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix`
|
||||
- mídia/rede: `mediaMaxMb`, `mediaGroupFlushMs`, `timeoutSeconds`, `pollingStallThresholdMs`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy`
|
||||
@ -1006,7 +1008,7 @@ Referência principal: [Referência de configuração - Telegram](/pt-BR/gateway
|
||||
</Accordion>
|
||||
|
||||
<Note>
|
||||
Precedência de várias contas: quando dois ou mais IDs de conta estiverem configurados, defina `channels.telegram.defaultAccount` (ou inclua `channels.telegram.accounts.default`) para tornar o roteamento padrão explícito. Caso contrário, o OpenClaw usa como fallback o primeiro ID de conta normalizado e `openclaw doctor` avisa. Contas nomeadas herdam `channels.telegram.allowFrom` / `groupAllowFrom`, mas não valores de `accounts.default.*`.
|
||||
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. Caso contrário, o OpenClaw volta para o primeiro ID de conta normalizado e `openclaw doctor` avisa. Contas nomeadas herdam `channels.telegram.allowFrom` / `groupAllowFrom`, mas não valores de `accounts.default.*`.
|
||||
</Note>
|
||||
|
||||
## Relacionados
|
||||
@ -1016,7 +1018,7 @@ Precedência de várias contas: quando dois ou mais IDs de conta estiverem confi
|
||||
Pareie um usuário do Telegram ao Gateway.
|
||||
</Card>
|
||||
<Card title="Grupos" icon="users" href="/pt-BR/channels/groups">
|
||||
Comportamento de lista de permissões de grupos e tópicos.
|
||||
Comportamento de allowlist de grupos e tópicos.
|
||||
</Card>
|
||||
<Card title="Roteamento de canais" icon="route" href="/pt-BR/channels/channel-routing">
|
||||
Roteie mensagens recebidas para agentes.
|
||||
|
||||
@ -1,14 +1,14 @@
|
||||
---
|
||||
read_when:
|
||||
- Adicionando ou modificando ações da CLI de mensagens
|
||||
- Adicionar ou modificar ações de mensagem da CLI
|
||||
- Alterando o comportamento do canal de saída
|
||||
summary: Referência da CLI para `openclaw message` (envio + ações de canal)
|
||||
title: Mensagem
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T20:44:06Z"
|
||||
generated_at: "2026-05-04T09:37:00Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 6b73a50da34838f80ad5d0d266f5c66f95436f8535e6312296ae022918b1ab55
|
||||
source_hash: 9ef57d33c93206a61a6d044667de4faf6340f7d8cc324300f235e838ee3b7ff1
|
||||
source_path: cli/message.md
|
||||
workflow: 16
|
||||
---
|
||||
@ -28,33 +28,33 @@ Seleção de canal:
|
||||
|
||||
- `--channel` é obrigatório se mais de um canal estiver configurado.
|
||||
- Se exatamente um canal estiver configurado, ele se torna o padrão.
|
||||
- Valores: `discord|googlechat|imessage|matrix|mattermost|msteams|signal|slack|telegram|whatsapp` (Mattermost requer Plugin)
|
||||
- `openclaw message` resolve o canal selecionado para seu Plugin proprietário quando `--channel` ou um destino prefixado por canal está presente; caso contrário, ele carrega Plugins de canal configurados para inferência do canal padrão.
|
||||
- Valores: `discord|googlechat|imessage|matrix|mattermost|msteams|signal|slack|telegram|whatsapp` (Mattermost exige Plugin)
|
||||
- `openclaw message` resolve o canal selecionado para o Plugin responsável quando `--channel` ou um destino com prefixo de canal está presente; caso contrário, ele carrega os Plugins de canal configurados para inferência do canal padrão.
|
||||
|
||||
Formatos de destino (`--target`):
|
||||
|
||||
- WhatsApp: E.164, JID de grupo ou JID de Canal/Newsletter do WhatsApp (`...@newsletter`)
|
||||
- Telegram: id do chat ou `@username`
|
||||
- Discord: `channel:<id>` ou `user:<id>` (ou menção `<@id>`; ids numéricos brutos são tratados como canais)
|
||||
- Telegram: ID do chat, `@username` ou destino de tópico de fórum (`-1001234567890:topic:42`, ou `--thread-id 42`)
|
||||
- Discord: `channel:<id>` ou `user:<id>` (ou menção `<@id>`; IDs numéricos brutos são tratados como canais)
|
||||
- Google Chat: `spaces/<spaceId>` ou `users/<userId>`
|
||||
- Slack: `channel:<id>` ou `user:<id>` (id bruto de canal é aceito)
|
||||
- Mattermost (Plugin): `channel:<id>`, `user:<id>` ou `@username` (ids simples são tratados como canais)
|
||||
- Slack: `channel:<id>` ou `user:<id>` (ID bruto de canal é aceito)
|
||||
- Mattermost (Plugin): `channel:<id>`, `user:<id>` ou `@username` (IDs simples são tratados como canais)
|
||||
- Signal: `+E.164`, `group:<id>`, `signal:+E.164`, `signal:group:<id>` ou `username:<name>`/`u:<name>`
|
||||
- iMessage: identificador, `chat_id:<id>`, `chat_guid:<guid>` ou `chat_identifier:<id>`
|
||||
- Matrix: `@user:server`, `!room:server` ou `#alias:server`
|
||||
- Microsoft Teams: id da conversa (`19:...@thread.tacv2`) ou `conversation:<id>` ou `user:<aad-object-id>`
|
||||
- Microsoft Teams: ID da conversa (`19:...@thread.tacv2`) ou `conversation:<id>` ou `user:<aad-object-id>`
|
||||
|
||||
Busca por nome:
|
||||
|
||||
- Para provedores compatíveis (Discord/Slack/etc), nomes de canal como `Help` ou `#help` são resolvidos pelo cache de diretório.
|
||||
- Em caso de ausência no cache, o OpenClaw tentará uma busca ativa no diretório quando o provedor oferecer suporte.
|
||||
- Em caso de ausência no cache, o OpenClaw tentará uma busca de diretório ao vivo quando o provedor oferecer suporte.
|
||||
|
||||
## Flags comuns
|
||||
|
||||
- `--channel <name>`
|
||||
- `--account <id>`
|
||||
- `--target <dest>` (canal ou usuário de destino para send/poll/read/etc)
|
||||
- `--targets <name>` (repetível; somente broadcast)
|
||||
- `--targets <name>` (repita; apenas broadcast)
|
||||
- `--json`
|
||||
- `--dry-run`
|
||||
- `--verbose`
|
||||
@ -62,12 +62,12 @@ Busca por nome:
|
||||
## Comportamento de SecretRef
|
||||
|
||||
- `openclaw message` resolve SecretRefs de canais compatíveis antes de executar a ação selecionada.
|
||||
- A resolução fica restrita ao destino da ação ativa quando possível:
|
||||
- com escopo de canal quando `--channel` é definido (ou inferido de destinos prefixados como `discord:...`)
|
||||
- com escopo de conta quando `--account` é definido (globais do canal + superfícies da conta selecionada)
|
||||
- A resolução fica no escopo do destino da ação ativa quando possível:
|
||||
- no escopo do canal quando `--channel` está definido (ou inferido de destinos prefixados como `discord:...`)
|
||||
- no escopo da conta quando `--account` está definido (globais do canal + superfícies da conta selecionada)
|
||||
- quando `--account` é omitido, o OpenClaw não força um escopo de SecretRef da conta `default`
|
||||
- SecretRefs não resolvidas em canais não relacionados não bloqueiam uma ação de mensagem direcionada.
|
||||
- Se a SecretRef do canal/conta selecionado não for resolvida, o comando falha fechado para essa ação.
|
||||
- Se a SecretRef do canal/conta selecionado não for resolvida, o comando falha de modo fechado para essa ação.
|
||||
|
||||
## Ações
|
||||
|
||||
@ -75,30 +75,30 @@ Busca por nome:
|
||||
|
||||
- `send`
|
||||
- Canais: WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost (Plugin)/Signal/iMessage/Matrix/Microsoft Teams
|
||||
- Obrigatório: `--target`, além de `--message`, `--media` ou `--presentation`
|
||||
- Obrigatório: `--target`, mais `--message`, `--media` ou `--presentation`
|
||||
- Opcional: `--media`, `--presentation`, `--delivery`, `--pin`, `--reply-to`, `--thread-id`, `--gif-playback`, `--force-document`, `--silent`
|
||||
- Payloads de apresentação compartilhados: `--presentation` envia blocos semânticos (`text`, `context`, `divider`, `buttons`, `select`) que o núcleo renderiza por meio das capacidades declaradas do canal selecionado. Consulte [Apresentação de mensagens](/pt-BR/plugins/message-presentation).
|
||||
- Payloads de apresentação compartilhados: `--presentation` envia blocos semânticos (`text`, `context`, `divider`, `buttons`, `select`) que o núcleo renderiza por meio das capacidades declaradas do canal selecionado. Consulte [Apresentação de mensagem](/pt-BR/plugins/message-presentation).
|
||||
- Preferências genéricas de entrega: `--delivery` aceita dicas de entrega como `{ "pin": true }`; `--pin` é um atalho para entrega fixada quando o canal oferece suporte.
|
||||
- Somente Telegram: `--force-document` (envia imagens e GIFs como documentos para evitar a compactação do Telegram)
|
||||
- Somente Telegram: `--thread-id` (id do tópico de fórum)
|
||||
- Somente Slack: `--thread-id` (timestamp da thread; `--reply-to` usa o mesmo campo)
|
||||
- Apenas Telegram: `--force-document` (envia imagens e GIFs como documentos para evitar compressão do Telegram)
|
||||
- Apenas Telegram: `--thread-id` (ID do tópico de fórum)
|
||||
- Apenas Slack: `--thread-id` (timestamp da thread; `--reply-to` usa o mesmo campo)
|
||||
- Telegram + Discord: `--silent`
|
||||
- Somente WhatsApp: `--gif-playback`; Canais/Newsletters do WhatsApp são endereçados com seu JID nativo `@newsletter`.
|
||||
- Apenas WhatsApp: `--gif-playback`; Canais/Newsletters do WhatsApp são endereçados com seu JID nativo `@newsletter`.
|
||||
|
||||
- `poll`
|
||||
- Canais: WhatsApp/Telegram/Discord/Matrix/Microsoft Teams
|
||||
- Obrigatório: `--target`, `--poll-question`, `--poll-option` (repetível)
|
||||
- Obrigatório: `--target`, `--poll-question`, `--poll-option` (repita)
|
||||
- Opcional: `--poll-multi`
|
||||
- Somente Discord: `--poll-duration-hours`, `--silent`, `--message`
|
||||
- Somente Telegram: `--poll-duration-seconds` (5-600), `--silent`, `--poll-anonymous` / `--poll-public`, `--thread-id`
|
||||
- Apenas Discord: `--poll-duration-hours`, `--silent`, `--message`
|
||||
- Apenas Telegram: `--poll-duration-seconds` (5-600), `--silent`, `--poll-anonymous` / `--poll-public`, `--thread-id`
|
||||
|
||||
- `react`
|
||||
- Canais: Discord/Google Chat/Slack/Telegram/WhatsApp/Signal/Matrix
|
||||
- Obrigatório: `--message-id`, `--target`
|
||||
- Opcional: `--emoji`, `--remove`, `--participant`, `--from-me`, `--target-author`, `--target-author-uuid`
|
||||
- Observação: `--remove` requer `--emoji` (omita `--emoji` para limpar as próprias reações onde houver suporte; consulte /tools/reactions)
|
||||
- Somente WhatsApp: `--participant`, `--from-me`
|
||||
- Reações em grupos do Signal: `--target-author` ou `--target-author-uuid` obrigatório
|
||||
- Observação: `--remove` exige `--emoji` (omita `--emoji` para limpar as próprias reações onde houver suporte; consulte /tools/reactions)
|
||||
- Apenas WhatsApp: `--participant`, `--from-me`
|
||||
- Reações de grupo no Signal: `--target-author` ou `--target-author-uuid` obrigatório
|
||||
|
||||
- `reactions`
|
||||
- Canais: Discord/Google Chat/Slack/Matrix
|
||||
@ -109,8 +109,8 @@ Busca por nome:
|
||||
- Canais: Discord/Slack/Matrix
|
||||
- Obrigatório: `--target`
|
||||
- Opcional: `--limit`, `--message-id`, `--before`, `--after`
|
||||
- Somente Slack: `--message-id` lê um timestamp específico de mensagem do Slack; combine com `--thread-id` para ler uma resposta exata da thread.
|
||||
- Somente Discord: `--around`
|
||||
- Apenas Slack: `--message-id` lê um timestamp específico de mensagem do Slack; combine com `--thread-id` para ler uma resposta exata de thread.
|
||||
- Apenas Discord: `--around`
|
||||
|
||||
- `edit`
|
||||
- Canais: Discord/Slack/Matrix
|
||||
@ -131,18 +131,18 @@ Busca por nome:
|
||||
- `permissions`
|
||||
- Canais: Discord/Matrix
|
||||
- Obrigatório: `--target`
|
||||
- Somente Matrix: disponível quando a criptografia do Matrix está habilitada e ações de verificação são permitidas
|
||||
- Apenas Matrix: disponível quando a criptografia do Matrix está habilitada e ações de verificação são permitidas
|
||||
|
||||
- `search`
|
||||
- Canais: Discord
|
||||
- Obrigatório: `--guild-id`, `--query`
|
||||
- Opcional: `--channel-id`, `--channel-ids` (repetível), `--author-id`, `--author-ids` (repetível), `--limit`
|
||||
- Opcional: `--channel-id`, `--channel-ids` (repita), `--author-id`, `--author-ids` (repita), `--limit`
|
||||
|
||||
### Threads
|
||||
|
||||
- `thread create`
|
||||
- Canais: Discord
|
||||
- Obrigatório: `--thread-name`, `--target` (id do canal)
|
||||
- Obrigatório: `--thread-name`, `--target` (ID do canal)
|
||||
- Opcional: `--message-id`, `--message`, `--auto-archive-min`
|
||||
|
||||
- `thread list`
|
||||
@ -152,7 +152,7 @@ Busca por nome:
|
||||
|
||||
- `thread reply`
|
||||
- Canais: Discord
|
||||
- Obrigatório: `--target` (id da thread), `--message`
|
||||
- Obrigatório: `--target` (ID da thread), `--message`
|
||||
- Opcional: `--media`, `--reply-to`
|
||||
|
||||
### Emojis
|
||||
@ -164,20 +164,20 @@ Busca por nome:
|
||||
- `emoji upload`
|
||||
- Canais: Discord
|
||||
- Obrigatório: `--guild-id`, `--emoji-name`, `--media`
|
||||
- Opcional: `--role-ids` (repetível)
|
||||
- Opcional: `--role-ids` (repita)
|
||||
|
||||
### Figurinhas
|
||||
### Stickers
|
||||
|
||||
- `sticker send`
|
||||
- Canais: Discord
|
||||
- Obrigatório: `--target`, `--sticker-id` (repetível)
|
||||
- Obrigatório: `--target`, `--sticker-id` (repita)
|
||||
- Opcional: `--message`
|
||||
|
||||
- `sticker upload`
|
||||
- Canais: Discord
|
||||
- Obrigatório: `--guild-id`, `--sticker-name`, `--sticker-desc`, `--sticker-tags`, `--media`
|
||||
|
||||
### Funções / Canais / Membros / Voz
|
||||
### Cargos / Canais / Membros / Voz
|
||||
|
||||
- `role info` (Discord): `--guild-id`
|
||||
- `role add` / `role remove` (Discord): `--guild-id`, `--user-id`, `--role-id`
|
||||
@ -194,10 +194,10 @@ Busca por nome:
|
||||
|
||||
### Moderação (Discord)
|
||||
|
||||
- `timeout`: `--guild-id`, `--user-id` (`--duration-min` ou `--until` opcional; omita ambos para limpar o timeout)
|
||||
- `timeout`: `--guild-id`, `--user-id` (opcional `--duration-min` ou `--until`; omita ambos para limpar o timeout)
|
||||
- `kick`: `--guild-id`, `--user-id` (+ `--reason`)
|
||||
- `ban`: `--guild-id`, `--user-id` (+ `--delete-days`, `--reason`)
|
||||
- `timeout` também oferece suporte a `--reason`
|
||||
- `timeout` também aceita `--reason`
|
||||
|
||||
### Broadcast
|
||||
|
||||
@ -223,7 +223,7 @@ openclaw message send --channel discord \
|
||||
--presentation '{"blocks":[{"type":"buttons","buttons":[{"label":"Approve","value":"approve","style":"success"},{"label":"Decline","value":"decline","style":"danger"}]}]}'
|
||||
```
|
||||
|
||||
O núcleo renderiza o mesmo payload `presentation` em componentes do Discord, blocos do Slack, botões inline do Telegram, props do Mattermost ou cards do Teams/Feishu, dependendo da capacidade do canal. Consulte [Apresentação de mensagens](/pt-BR/plugins/message-presentation) para ver o contrato completo e as regras de fallback.
|
||||
O núcleo renderiza o mesmo payload `presentation` em componentes do Discord, blocos do Slack, botões inline do Telegram, props do Mattermost ou cartões do Teams/Feishu, dependendo da capacidade do canal. Consulte [Apresentação de mensagem](/pt-BR/plugins/message-presentation) para o contrato completo e as regras de fallback.
|
||||
|
||||
Enviar um payload de apresentação mais rico:
|
||||
|
||||
@ -284,14 +284,14 @@ openclaw message react --channel signal \
|
||||
--emoji "✅" --target-author-uuid 123e4567-e89b-12d3-a456-426614174000
|
||||
```
|
||||
|
||||
Enviar botões inline do Telegram por meio da apresentação genérica:
|
||||
Enviar botões inline do Telegram por meio de apresentação genérica:
|
||||
|
||||
```
|
||||
openclaw message send --channel telegram --target @mychat --message "Choose:" \
|
||||
--presentation '{"blocks":[{"type":"buttons","buttons":[{"label":"Yes","value":"cmd:yes"},{"label":"No","value":"cmd:no"}]}]}'
|
||||
```
|
||||
|
||||
Enviar um card do Teams por meio da apresentação genérica:
|
||||
Enviar um cartão do Teams por meio de apresentação genérica:
|
||||
|
||||
```bash
|
||||
openclaw message send --channel msteams \
|
||||
@ -299,14 +299,14 @@ openclaw message send --channel msteams \
|
||||
--presentation '{"title":"Status update","blocks":[{"type":"text","text":"Build completed"}]}'
|
||||
```
|
||||
|
||||
Enviar uma imagem do Telegram como documento para evitar compactação:
|
||||
Enviar uma imagem do Telegram como documento para evitar compressão:
|
||||
|
||||
```bash
|
||||
openclaw message send --channel telegram --target @mychat \
|
||||
--media ./diagram.png --force-document
|
||||
```
|
||||
|
||||
## Relacionados
|
||||
## Relacionado
|
||||
|
||||
- [Referência da CLI](/pt-BR/cli)
|
||||
- [Envio pelo agente](/pt-BR/tools/agent-send)
|
||||
- [Envio de agente](/pt-BR/tools/agent-send)
|
||||
|
||||
@ -1,20 +1,20 @@
|
||||
---
|
||||
read_when:
|
||||
- Você quer instalar ou gerenciar plugins do Gateway ou pacotes compatíveis
|
||||
- Você quer depurar falhas no carregamento de Plugin
|
||||
- Você deseja instalar ou gerenciar plugins do Gateway ou pacotes compatíveis
|
||||
- Você quer depurar falhas de carregamento de Plugin
|
||||
sidebarTitle: Plugins
|
||||
summary: Referência da CLI para `openclaw plugins` (list, install, marketplace, uninstall, enable/disable, doctor)
|
||||
summary: Referência da CLI para `openclaw plugins` (listar, instalar, marketplace, desinstalar, habilitar/desabilitar, doctor)
|
||||
title: Plugins
|
||||
x-i18n:
|
||||
generated_at: "2026-05-04T05:52:01Z"
|
||||
generated_at: "2026-05-04T09:37:13Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 36ae7edb12986ead7e126f25e0761bf312b2644b35017181b674082105886776
|
||||
source_hash: f561ce098181b07f25db3520b1726162863469ac05fb4a3e786915257d97c9a4
|
||||
source_path: cli/plugins.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Gerencie plugins do Gateway, pacotes de hooks e bundles compatíveis.
|
||||
Gerencie Plugins do Gateway, pacotes de hooks e bundles compatíveis.
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Sistema de Plugin" href="/pt-BR/tools/plugin">
|
||||
@ -67,11 +67,11 @@ comando com `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1`. O rastreamento grava os tempos
|
||||
em stderr e mantém a saída JSON analisável. Consulte [Depuração](/pt-BR/help/debugging#plugin-lifecycle-trace).
|
||||
|
||||
<Note>
|
||||
Plugins incluídos são distribuídos com o OpenClaw. Alguns são habilitados por padrão (por exemplo, provedores de modelo incluídos, provedores de fala incluídos e o plugin de navegador incluído); outros exigem `plugins enable`.
|
||||
Plugins empacotados são distribuídos com o OpenClaw. Alguns são habilitados por padrão (por exemplo, provedores de modelo empacotados, provedores de fala empacotados e o Plugin de navegador empacotado); outros exigem `plugins enable`.
|
||||
|
||||
Plugins nativos do OpenClaw devem distribuir `openclaw.plugin.json` com um JSON Schema embutido (`configSchema`, mesmo que vazio). Bundles compatíveis usam seus próprios manifestos de bundle.
|
||||
Plugins nativos do OpenClaw devem incluir `openclaw.plugin.json` com um JSON Schema embutido (`configSchema`, mesmo que vazio). Bundles compatíveis usam seus próprios manifestos de bundle.
|
||||
|
||||
`plugins list` mostra `Format: openclaw` ou `Format: bundle`. A saída detalhada de list/info também mostra o subtipo de bundle (`codex`, `claude` ou `cursor`) mais os recursos de bundle detectados.
|
||||
`plugins list` mostra `Format: openclaw` ou `Format: bundle`. A saída detalhada de list/info também mostra o subtipo do bundle (`codex`, `claude` ou `cursor`) além das capacidades de bundle detectadas.
|
||||
</Note>
|
||||
|
||||
### Instalar
|
||||
@ -93,71 +93,71 @@ openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Nomes de pacote simples instalam a partir do npm por padrão durante a transição de lançamento. Use `clawhub:<package>` para ClawHub. Trate instalações de plugins como execução de código. Prefira versões fixadas.
|
||||
Nomes de pacote simples são instalados a partir do npm por padrão durante a transição de lançamento. Use `clawhub:<package>` para o ClawHub. Trate instalações de plugins como execução de código. Prefira versões fixadas.
|
||||
</Warning>
|
||||
|
||||
`plugins search` consulta o ClawHub em busca de pacotes de plugins instaláveis e imprime
|
||||
nomes de pacotes prontos para instalação. Ele pesquisa pacotes de plugins de código e de bundles,
|
||||
nomes de pacotes prontos para instalação. Ele pesquisa pacotes de Plugin de código e Plugin de bundle,
|
||||
não Skills. Use `openclaw skills search` para Skills do ClawHub.
|
||||
|
||||
<Note>
|
||||
ClawHub é a principal superfície de distribuição e descoberta para a maioria dos plugins. O npm
|
||||
continua sendo um fallback compatível e um caminho de instalação direta. Pacotes de plugins
|
||||
`@openclaw/*` pertencentes ao OpenClaw são publicados no npm novamente; veja a lista atual
|
||||
continua sendo um fallback compatível e um caminho de instalação direta. Pacotes de Plugin
|
||||
`@openclaw/*` mantidos pelo OpenClaw foram publicados novamente no npm; veja a lista atual
|
||||
em [npmjs.com/org/openclaw](https://www.npmjs.com/org/openclaw) ou no
|
||||
[inventário de plugins](/pt-BR/plugins/plugin-inventory). Instalações estáveis usam `latest`.
|
||||
Instalações e atualizações do canal beta preferem a dist-tag `beta` do npm quando essa tag
|
||||
está disponível, depois retornam para `latest`.
|
||||
está disponível, depois recorrem a `latest`.
|
||||
</Note>
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Includes de configuração e reparo de configuração inválida">
|
||||
Se a seção `plugins` for apoiada por um `$include` de arquivo único, `plugins install/update/enable/disable/uninstall` grava nesse arquivo incluído e deixa `openclaw.json` intacto. Includes raiz, arrays de include e includes com sobrescritas irmãs falham de forma fechada em vez de nivelar. Consulte [Includes de configuração](/pt-BR/gateway/configuration) para os formatos compatíveis.
|
||||
Se sua seção `plugins` for apoiada por um `$include` de arquivo único, `plugins install/update/enable/disable/uninstall` grava nesse arquivo incluído e deixa `openclaw.json` intacto. Includes raiz, arrays de includes e includes com substituições irmãs falham de forma fechada em vez de serem achatados. Consulte [Includes de configuração](/pt-BR/gateway/configuration) para os formatos compatíveis.
|
||||
|
||||
Se a configuração estiver inválida durante a instalação, `plugins install` normalmente falha de forma fechada e informa que você deve executar `openclaw doctor --fix` primeiro. Durante a inicialização do Gateway e o recarregamento a quente, uma configuração de plugin inválida falha de forma fechada como qualquer outra configuração inválida; `openclaw doctor --fix` pode colocar em quarentena a entrada de plugin inválida. A única exceção documentada no momento da instalação é um caminho restrito de recuperação de plugins incluídos para plugins que optam explicitamente por `openclaw.install.allowInvalidConfigRecovery`.
|
||||
Se a configuração estiver inválida durante a instalação, `plugins install` normalmente falha de forma fechada e orienta você a executar `openclaw doctor --fix` primeiro. Durante a inicialização do Gateway e o recarregamento a quente, uma configuração de Plugin inválida falha de forma fechada como qualquer outra configuração inválida; `openclaw doctor --fix` pode colocar a entrada inválida do Plugin em quarentena. A única exceção documentada em tempo de instalação é um caminho estreito de recuperação de Plugin empacotado para plugins que optam explicitamente por `openclaw.install.allowInvalidConfigRecovery`.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="--force e reinstalar versus atualizar">
|
||||
`--force` reutiliza o destino de instalação existente e sobrescreve no local um plugin ou pacote de hooks já instalado. Use quando você estiver reinstalando intencionalmente o mesmo id a partir de um novo caminho local, arquivo compactado, pacote do ClawHub ou artefato do npm. Para upgrades rotineiros de um plugin npm já rastreado, prefira `openclaw plugins update <id-or-npm-spec>`.
|
||||
<Accordion title="--force e reinstalação versus atualização">
|
||||
`--force` reutiliza o destino de instalação existente e sobrescreve um Plugin ou pacote de hooks já instalado no lugar. Use quando você estiver reinstalando intencionalmente o mesmo id a partir de um novo caminho local, arquivo, pacote do ClawHub ou artefato npm. Para upgrades rotineiros de um Plugin npm já rastreado, prefira `openclaw plugins update <id-or-npm-spec>`.
|
||||
|
||||
Se você executar `plugins install` para um id de plugin que já está instalado, o OpenClaw interrompe e aponta para `plugins update <id-or-npm-spec>` para um upgrade normal, ou para `plugins install <package> --force` quando você realmente quiser sobrescrever a instalação atual a partir de uma fonte diferente.
|
||||
Se você executar `plugins install` para um id de Plugin que já está instalado, o OpenClaw interrompe e aponta para `plugins update <id-or-npm-spec>` para um upgrade normal, ou para `plugins install <package> --force` quando você realmente quiser sobrescrever a instalação atual a partir de uma fonte diferente.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Escopo de --pin">
|
||||
`--pin` se aplica apenas a instalações npm. Ele não é compatível com instalações `git:`; use uma referência git explícita, como `git:github.com/acme/plugin@v1.2.3`, quando quiser uma fonte fixada. Ele não é compatível com `--marketplace`, porque instalações de marketplace persistem metadados de origem do marketplace em vez de uma especificação npm.
|
||||
`--pin` se aplica apenas a instalações npm. Ele não é compatível com instalações `git:`; use uma ref git explícita, como `git:github.com/acme/plugin@v1.2.3`, quando quiser uma fonte fixada. Ele não é compatível com `--marketplace`, porque instalações de marketplace persistem metadados de fonte do marketplace em vez de uma especificação npm.
|
||||
</Accordion>
|
||||
<Accordion title="--dangerously-force-unsafe-install">
|
||||
`--dangerously-force-unsafe-install` é uma opção de emergência para falsos positivos no scanner interno de código perigoso. Ela permite que a instalação continue mesmo quando o scanner interno relata achados `critical`, mas **não** ignora bloqueios de política do hook `before_install` do plugin e **não** ignora falhas de varredura.
|
||||
`--dangerously-force-unsafe-install` é uma opção de emergência para falsos positivos no verificador integrado de código perigoso. Ela permite que a instalação continue mesmo quando o verificador integrado relata achados `critical`, mas **não** ignora bloqueios de política de hook `before_install` do Plugin e **não** ignora falhas de varredura.
|
||||
|
||||
Essa flag da CLI se aplica a fluxos de instalação/atualização de plugins. Instalações de dependências de Skills apoiadas pelo Gateway usam a substituição de solicitação correspondente `dangerouslyForceUnsafeInstall`, enquanto `openclaw skills install` continua sendo um fluxo separado de download/instalação de Skills do ClawHub.
|
||||
Essa flag da CLI se aplica a fluxos de instalação/atualização de Plugin. Instalações de dependências de Skills apoiadas pelo Gateway usam a substituição de solicitação correspondente `dangerouslyForceUnsafeInstall`, enquanto `openclaw skills install` continua sendo um fluxo separado de download/instalação de Skills do ClawHub.
|
||||
|
||||
Se um plugin que você publicou no ClawHub for bloqueado por uma varredura do registro, use as etapas de publicador em [ClawHub](/pt-BR/tools/clawhub).
|
||||
Se um Plugin que você publicou no ClawHub for bloqueado por uma varredura de registro, use as etapas para publicadores em [ClawHub](/pt-BR/tools/clawhub).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Pacotes de hooks e especificações npm">
|
||||
`plugins install` também é a superfície de instalação para pacotes de hooks que expõem `openclaw.hooks` em `package.json`. Use `openclaw hooks` para visibilidade filtrada de hooks e habilitação por hook, não para instalação de pacotes.
|
||||
`plugins install` também é a superfície de instalação para pacotes de hooks que expõem `openclaw.hooks` em `package.json`. Use `openclaw hooks` para visibilidade filtrada de hooks e habilitação por hook, não para instalação de pacote.
|
||||
|
||||
Especificações npm são **somente de registro** (nome do pacote + **versão exata** opcional ou **dist-tag**). Especificações Git/URL/arquivo e intervalos semver são rejeitados. Instalações de dependências são executadas localmente no projeto com `--ignore-scripts` por segurança, mesmo quando seu shell tem configurações globais de instalação npm.
|
||||
Especificações npm são **somente de registro** (nome do pacote + **versão exata** opcional ou **dist-tag**). Especificações Git/URL/arquivo e intervalos semver são rejeitados. Instalações de dependências rodam localmente no projeto com `--ignore-scripts` por segurança, mesmo quando seu shell tem configurações globais de instalação npm.
|
||||
|
||||
Use `npm:<package>` quando quiser explicitar a resolução por npm. Especificações simples de pacote também instalam diretamente do npm durante a transição de lançamento.
|
||||
Use `npm:<package>` quando quiser explicitar a resolução npm. Especificações de pacote simples também instalam diretamente do npm durante a transição de lançamento.
|
||||
|
||||
Especificações simples e `@latest` permanecem na trilha estável. Versões de correção datadas do OpenClaw, como `2026.5.3-1`, são versões estáveis para esta verificação. Se o npm resolver qualquer uma delas para uma pré-versão, o OpenClaw interrompe e pede que você opte explicitamente por uma tag de pré-versão, como `@beta`/`@rc`, ou uma versão de pré-lançamento exata, como `@1.2.3-beta.4`.
|
||||
Especificações simples e `@latest` permanecem na faixa estável. Versões de correção datadas do OpenClaw, como `2026.5.3-1`, são versões estáveis para esta verificação. Se o npm resolver qualquer uma delas para uma pré-versão, o OpenClaw interrompe e pede que você aceite explicitamente com uma tag de pré-versão, como `@beta`/`@rc`, ou uma versão de pré-lançamento exata, como `@1.2.3-beta.4`.
|
||||
|
||||
Se uma especificação simples de instalação corresponder a um id de plugin oficial (por exemplo, `diffs`), o OpenClaw instala diretamente a entrada do catálogo. Para instalar um pacote npm com o mesmo nome, use uma especificação com escopo explícita (por exemplo, `@scope/diffs`).
|
||||
Se uma especificação de instalação simples corresponder a um id oficial de Plugin (por exemplo, `diffs`), o OpenClaw instala a entrada do catálogo diretamente. Para instalar um pacote npm com o mesmo nome, use uma especificação com escopo explícito (por exemplo, `@scope/diffs`).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Repositórios Git">
|
||||
Use `git:<repo>` para instalar diretamente de um repositório git. Formatos compatíveis incluem URLs de clone `git:github.com/owner/repo`, `git:owner/repo`, `https://` completo, `ssh://`, `git://`, `file://` e `git@host:owner/repo.git`. Adicione `@<ref>` ou `#<ref>` para fazer checkout de uma branch, tag ou commit antes da instalação.
|
||||
Use `git:<repo>` para instalar diretamente de um repositório git. Formatos compatíveis incluem `git:github.com/owner/repo`, `git:owner/repo`, URLs completas `https://`, `ssh://`, `git://`, `file://` e `git@host:owner/repo.git` de clone. Adicione `@<ref>` ou `#<ref>` para fazer checkout de um branch, tag ou commit antes da instalação.
|
||||
|
||||
Instalações git clonam em um diretório temporário, fazem checkout da referência solicitada quando presente e então usam o instalador normal de diretório de plugin. Isso significa que validação de manifesto, varredura de código perigoso, trabalho de instalação do gerenciador de pacotes e registros de instalação se comportam como instalações npm. Instalações git registradas incluem a URL/ref de origem mais o commit resolvido para que `openclaw plugins update` possa resolver novamente a origem depois.
|
||||
Instalações Git clonam para um diretório temporário, fazem checkout da ref solicitada quando presente e então usam o instalador normal de diretório de Plugin. Isso significa que validação de manifesto, varredura de código perigoso, trabalho de instalação do gerenciador de pacotes e registros de instalação se comportam como instalações npm. Instalações git registradas incluem a URL/ref de origem mais o commit resolvido para que `openclaw plugins update` possa resolver novamente a fonte mais tarde.
|
||||
|
||||
Depois de instalar a partir do git, use `openclaw plugins inspect <id> --runtime --json` para verificar registros de runtime, como métodos de gateway e comandos da CLI. Se o plugin registrou uma raiz de CLI com `api.registerCli`, execute esse comando diretamente pela CLI raiz do OpenClaw, por exemplo `openclaw demo-plugin ping`.
|
||||
Depois de instalar a partir de git, use `openclaw plugins inspect <id> --runtime --json` para verificar registros de runtime, como métodos de gateway e comandos da CLI. Se o Plugin registrou uma raiz de CLI com `api.registerCli`, execute esse comando diretamente pela CLI raiz do OpenClaw, por exemplo `openclaw demo-plugin ping`.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Arquivos compactados">
|
||||
Arquivos compactados compatíveis: `.zip`, `.tgz`, `.tar.gz`, `.tar`. Arquivos compactados de plugins nativos do OpenClaw devem conter um `openclaw.plugin.json` válido na raiz extraída do plugin; arquivos compactados que contêm apenas `package.json` são rejeitados antes que o OpenClaw grave registros de instalação.
|
||||
<Accordion title="Arquivos">
|
||||
Arquivos compatíveis: `.zip`, `.tgz`, `.tar.gz`, `.tar`. Arquivos de Plugin nativo do OpenClaw devem conter um `openclaw.plugin.json` válido na raiz extraída do Plugin; arquivos que contêm apenas `package.json` são rejeitados antes que o OpenClaw grave registros de instalação.
|
||||
|
||||
Instalações do marketplace do Claude também são compatíveis.
|
||||
Instalações do marketplace Claude também são compatíveis.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -169,7 +169,7 @@ openclaw plugins install clawhub:openclaw-codex-app-server
|
||||
openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3
|
||||
```
|
||||
|
||||
Especificações simples de plugins seguras para npm instalam a partir do npm por padrão durante a transição de lançamento:
|
||||
Especificações de Plugin simples seguras para npm instalam a partir do npm por padrão durante a transição de lançamento:
|
||||
|
||||
```bash
|
||||
openclaw plugins install openclaw-codex-app-server
|
||||
@ -182,8 +182,8 @@ openclaw plugins install npm:openclaw-codex-app-server
|
||||
openclaw plugins install npm:@scope/plugin-name@1.0.1
|
||||
```
|
||||
|
||||
O OpenClaw verifica a API de plugin anunciada / compatibilidade mínima do gateway antes da instalação. Quando a versão selecionada do ClawHub publica um artefato ClawPack, o OpenClaw baixa o `.tgz` versionado do npm-pack, verifica o cabeçalho de digest do ClawHub e o digest do artefato, e então o instala pelo caminho normal de arquivo compactado. Versões mais antigas do ClawHub sem metadados ClawPack ainda instalam pelo caminho legado de verificação de arquivo compactado de pacote. Instalações registradas mantêm seus metadados de origem do ClawHub, tipo de artefato, integridade npm, shasum npm, nome do tarball e fatos de digest do ClawPack para atualizações futuras.
|
||||
Instalações não versionadas do ClawHub mantêm uma especificação registrada sem versão para que `openclaw plugins update` possa acompanhar versões mais novas do ClawHub; seletores explícitos de versão ou tag, como `clawhub:pkg@1.2.3` e `clawhub:pkg@beta`, permanecem fixados nesse seletor.
|
||||
O OpenClaw verifica a API de Plugin anunciada / compatibilidade mínima do gateway antes da instalação. Quando a versão selecionada do ClawHub publica um artefato ClawPack, o OpenClaw baixa o `.tgz` versionado do npm-pack, verifica o cabeçalho de digest do ClawHub e o digest do artefato, e então o instala pelo caminho normal de arquivo. Versões antigas do ClawHub sem metadados ClawPack ainda são instaladas pelo caminho legado de verificação de arquivo de pacote. Instalações registradas mantêm seus metadados de origem do ClawHub, tipo de artefato, integridade npm, shasum npm, nome do tarball e fatos de digest do ClawPack para atualizações posteriores.
|
||||
Instalações não versionadas do ClawHub mantêm uma especificação registrada não versionada para que `openclaw plugins update` possa acompanhar versões mais novas do ClawHub; seletores explícitos de versão ou tag, como `clawhub:pkg@1.2.3` e `clawhub:pkg@beta`, permanecem fixados nesse seletor.
|
||||
|
||||
#### Atalho de marketplace
|
||||
|
||||
@ -194,7 +194,7 @@ openclaw plugins marketplace list <marketplace-name>
|
||||
openclaw plugins install <plugin-name>@<marketplace-name>
|
||||
```
|
||||
|
||||
Use `--marketplace` quando quiser passar a origem do marketplace explicitamente:
|
||||
Use `--marketplace` quando quiser passar a fonte do marketplace explicitamente:
|
||||
|
||||
```bash
|
||||
openclaw plugins install <plugin-name> --marketplace <marketplace-name>
|
||||
@ -204,28 +204,28 @@ openclaw plugins install <plugin-name> --marketplace ./my-marketplace
|
||||
```
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Fontes de marketplace">
|
||||
<Tab title="Marketplace sources">
|
||||
- um nome de marketplace conhecido do Claude em `~/.claude/plugins/known_marketplaces.json`
|
||||
- uma raiz de marketplace local ou caminho de `marketplace.json`
|
||||
- uma abreviação de repositório GitHub, como `owner/repo`
|
||||
- uma URL de repositório GitHub, como `https://github.com/owner/repo`
|
||||
- uma raiz de marketplace local ou um caminho `marketplace.json`
|
||||
- um atalho de repositório do GitHub, como `owner/repo`
|
||||
- uma URL de repositório do GitHub, como `https://github.com/owner/repo`
|
||||
- uma URL git
|
||||
|
||||
</Tab>
|
||||
<Tab title="Regras de marketplace remoto">
|
||||
Para marketplaces remotos carregados do GitHub ou por git, as entradas de Plugin devem permanecer dentro do repositório de marketplace clonado. OpenClaw aceita fontes de caminho relativo desse repositório e rejeita HTTP(S), caminho absoluto, git, GitHub e outras fontes de Plugin que não sejam caminhos em manifestos remotos.
|
||||
<Tab title="Remote marketplace rules">
|
||||
Para marketplaces remotos carregados do GitHub ou git, as entradas de Plugin devem permanecer dentro do repositório de marketplace clonado. O OpenClaw aceita fontes de caminho relativo desse repositório e rejeita HTTP(S), caminhos absolutos, git, GitHub e outras fontes de Plugin que não sejam caminhos em manifests remotos.
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
Para caminhos e arquivos locais, OpenClaw detecta automaticamente:
|
||||
Para caminhos locais e arquivos compactados, o OpenClaw detecta automaticamente:
|
||||
|
||||
- plugins nativos do OpenClaw (`openclaw.plugin.json`)
|
||||
- Plugins nativos do OpenClaw (`openclaw.plugin.json`)
|
||||
- pacotes compatíveis com Codex (`.codex-plugin/plugin.json`)
|
||||
- pacotes compatíveis com Claude (`.claude-plugin/plugin.json` ou o layout padrão de componentes do Claude)
|
||||
- pacotes compatíveis com Cursor (`.cursor-plugin/plugin.json`)
|
||||
|
||||
<Note>
|
||||
Pacotes compatíveis são instalados na raiz normal de plugins e participam do mesmo fluxo de listar/informações/habilitar/desabilitar. Hoje, há suporte a Skills de pacote, command-skills do Claude, padrões de `settings.json` do Claude, padrões de `.lsp.json` do Claude / `lspServers` declarados no manifesto, command-skills do Cursor e diretórios de hooks compatíveis do Codex; outros recursos de pacote detectados são mostrados em diagnósticos/informações, mas ainda não estão conectados à execução em runtime.
|
||||
Pacotes compatíveis são instalados na raiz normal de Plugins e participam do mesmo fluxo de listar/informações/habilitar/desabilitar. Hoje, há suporte a Skills de pacote, Skills de comando do Claude, padrões de `settings.json` do Claude, padrões de `.lsp.json` do Claude / `lspServers` declarados no manifest, Skills de comando do Cursor e diretórios de hooks compatíveis do Codex; outros recursos de pacote detectados são mostrados em diagnósticos/informações, mas ainda não estão conectados à execução em runtime.
|
||||
</Note>
|
||||
|
||||
### Listar
|
||||
@ -241,29 +241,29 @@ openclaw plugins search <query> --json
|
||||
```
|
||||
|
||||
<ParamField path="--enabled" type="boolean">
|
||||
Mostra apenas plugins habilitados.
|
||||
Mostra apenas Plugins habilitados.
|
||||
</ParamField>
|
||||
<ParamField path="--verbose" type="boolean">
|
||||
Alterna da visualização em tabela para linhas de detalhes por Plugin com metadados de fonte/origem/versão/ativação.
|
||||
Alterna da visualização em tabela para linhas detalhadas por Plugin com metadados de fonte/origem/versão/ativação.
|
||||
</ParamField>
|
||||
<ParamField path="--json" type="boolean">
|
||||
Inventário legível por máquina, além de diagnósticos de registro e estado de instalação de dependências de pacotes.
|
||||
Inventário legível por máquina, além de diagnósticos de registro e estado de instalação de dependências de pacote.
|
||||
</ParamField>
|
||||
|
||||
<Note>
|
||||
`plugins list` lê primeiro o registro local persistido de plugins, com um fallback derivado apenas do manifesto quando o registro está ausente ou inválido. Ele é útil para verificar se um Plugin está instalado, habilitado e visível para o planejamento de inicialização fria, mas não é uma sondagem de runtime ao vivo de um processo Gateway já em execução. Depois de alterar código de Plugin, habilitação, política de hook ou `plugins.load.paths`, reinicie o Gateway que atende ao canal antes de esperar que novo código `register(api)` ou hooks sejam executados. Para implantações remotas/em contêiner, verifique se você está reiniciando o filho `openclaw gateway run` real, não apenas um processo wrapper.
|
||||
`plugins list` lê primeiro o registro local persistido de Plugins, com um fallback derivado apenas de manifest quando o registro está ausente ou inválido. Ele é útil para verificar se um Plugin está instalado, habilitado e visível para o planejamento de inicialização a frio, mas não é uma sondagem de runtime em tempo real de um processo Gateway já em execução. Depois de alterar código de Plugin, habilitação, política de hooks ou `plugins.load.paths`, reinicie o Gateway que atende o canal antes de esperar que novo código `register(api)` ou hooks sejam executados. Para implantações remotas/em contêiner, verifique se você está reiniciando o filho real de `openclaw gateway run`, não apenas um processo wrapper.
|
||||
|
||||
`plugins list --json` inclui o `dependencyStatus` de cada Plugin a partir de `dependencies` e `optionalDependencies` em `package.json`. OpenClaw verifica se esses nomes de pacote estão presentes ao longo do caminho normal de busca `node_modules` do Node para o Plugin; ele não importa código de runtime do Plugin, não executa um gerenciador de pacotes nem repara dependências ausentes.
|
||||
`plugins list --json` inclui o `dependencyStatus` de cada Plugin a partir de `dependencies` e `optionalDependencies` de `package.json`. O OpenClaw verifica se esses nomes de pacote estão presentes ao longo do caminho normal de busca `node_modules` do Node do Plugin; ele não importa código de runtime do Plugin, não executa um gerenciador de pacotes nem repara dependências ausentes.
|
||||
</Note>
|
||||
|
||||
`plugins search` é uma consulta remota ao catálogo ClawHub. Ela não inspeciona o estado local, não altera configuração, não instala pacotes nem carrega código de runtime de Plugin. Os resultados da busca incluem o nome do pacote ClawHub, família, canal, versão, resumo e uma dica de instalação como `openclaw plugins install clawhub:<package>`.
|
||||
`plugins search` é uma consulta remota ao catálogo do ClawHub. Ela não inspeciona o estado local, não altera configuração, não instala pacotes nem carrega código de runtime de Plugin. Os resultados da busca incluem o nome do pacote no ClawHub, família, canal, versão, resumo e uma dica de instalação, como `openclaw plugins install clawhub:<package>`.
|
||||
|
||||
Para trabalho em Plugin incluído dentro de uma imagem Docker empacotada, monte o diretório de origem do Plugin sobre o caminho de origem empacotado correspondente, como `/app/extensions/synology-chat`. OpenClaw descobrirá essa sobreposição de origem montada antes de `/app/dist/extensions/synology-chat`; um diretório de origem simplesmente copiado permanece inerte, então instalações empacotadas normais ainda usam o dist compilado.
|
||||
Para trabalho com Plugin incluído dentro de uma imagem Docker empacotada, monte o diretório de origem do Plugin sobre o caminho de origem empacotado correspondente, como `/app/extensions/synology-chat`. O OpenClaw descobrirá essa sobreposição de origem montada antes de `/app/dist/extensions/synology-chat`; um diretório de origem simplesmente copiado permanece inerte, de modo que instalações empacotadas normais continuam usando o dist compilado.
|
||||
|
||||
Para depuração de hooks em runtime:
|
||||
|
||||
- `openclaw plugins inspect <id> --runtime --json` mostra hooks registrados e diagnósticos de uma passagem de inspeção com módulo carregado. A inspeção em runtime nunca instala dependências; use `openclaw doctor --fix` para limpar estado legado de dependências ou instalar plugins baixáveis configurados ausentes.
|
||||
- `openclaw gateway status --deep --require-rpc` confirma o Gateway alcançável, dicas de serviço/processo, caminho de configuração e saúde do RPC.
|
||||
- `openclaw plugins inspect <id> --runtime --json` mostra hooks registrados e diagnósticos de uma passagem de inspeção com módulo carregado. A inspeção de runtime nunca instala dependências; use `openclaw doctor --fix` para limpar estado legado de dependências ou instalar Plugins baixáveis configurados que estejam ausentes.
|
||||
- `openclaw gateway status --deep --require-rpc` confirma o Gateway acessível, dicas de serviço/processo, caminho de configuração e integridade de RPC.
|
||||
- Hooks de conversa não incluídos (`llm_input`, `llm_output`, `before_agent_finalize`, `agent_end`) exigem `plugins.entries.<id>.hooks.allowConversationAccess=true`.
|
||||
|
||||
Use `--link` para evitar copiar um diretório local (adiciona a `plugins.load.paths`):
|
||||
@ -275,14 +275,14 @@ openclaw plugins install -l ./my-plugin
|
||||
<Note>
|
||||
`--force` não é compatível com `--link` porque instalações vinculadas reutilizam o caminho de origem em vez de copiar sobre um destino de instalação gerenciado.
|
||||
|
||||
Use `--pin` em instalações npm para salvar a especificação exata resolvida (`name@version`) no índice de plugins gerenciados, mantendo o comportamento padrão sem fixação.
|
||||
Use `--pin` em instalações npm para salvar a especificação exata resolvida (`name@version`) no índice de Plugins gerenciado, mantendo o comportamento padrão sem fixação.
|
||||
</Note>
|
||||
|
||||
### Índice de Plugin
|
||||
### Índice de Plugins
|
||||
|
||||
Metadados de instalação de Plugin são estado gerenciado por máquina, não configuração de usuário. Instalações e atualizações os gravam em `plugins/installs.json` no diretório de estado ativo do OpenClaw. Seu mapa de nível superior `installRecords` é a fonte durável de metadados de instalação, incluindo registros de manifestos de Plugin quebrados ou ausentes. O array `plugins` é o cache de registro frio derivado do manifesto. O arquivo inclui um aviso de não editar e é usado por `openclaw plugins update`, desinstalação, diagnósticos e o registro frio de plugins.
|
||||
Metadados de instalação de Plugin são estado gerenciado pela máquina, não configuração do usuário. Instalações e atualizações os gravam em `plugins/installs.json` no diretório de estado ativo do OpenClaw. Seu mapa de nível superior `installRecords` é a fonte durável de metadados de instalação, incluindo registros de manifests de Plugin quebrados ou ausentes. O array `plugins` é o cache de registro frio derivado de manifest. O arquivo inclui um aviso de não editar e é usado por `openclaw plugins update`, desinstalação, diagnósticos e o registro frio de Plugins.
|
||||
|
||||
Quando OpenClaw encontra registros legados enviados em `plugins.installs` na configuração, ele os move para o índice de Plugin e remove a chave de configuração; se qualquer gravação falhar, os registros de configuração são mantidos para que os metadados de instalação não sejam perdidos.
|
||||
Quando o OpenClaw vê registros legados enviados de `plugins.installs` na configuração, ele os move para o índice de Plugins e remove a chave de configuração; se qualquer uma das gravações falhar, os registros de configuração são mantidos para que os metadados de instalação não sejam perdidos.
|
||||
|
||||
### Desinstalar
|
||||
|
||||
@ -292,10 +292,10 @@ openclaw plugins uninstall <id> --dry-run
|
||||
openclaw plugins uninstall <id> --keep-files
|
||||
```
|
||||
|
||||
`uninstall` remove registros de Plugin de `plugins.entries`, do índice persistido de plugins, de entradas de lista de permissão/bloqueio de plugins e de entradas vinculadas em `plugins.load.paths` quando aplicável. A menos que `--keep-files` esteja definido, a desinstalação também remove o diretório rastreado de instalação gerenciada quando ele está dentro da raiz de extensões de Plugin do OpenClaw. Para plugins de Active Memory, o slot de memória é redefinido para `memory-core`.
|
||||
`uninstall` remove registros de Plugin de `plugins.entries`, do índice persistido de Plugins, de entradas de lista de permissão/negação de Plugins e de entradas vinculadas de `plugins.load.paths` quando aplicável. A menos que `--keep-files` esteja definido, a desinstalação também remove o diretório de instalação gerenciado rastreado quando ele está dentro da raiz de extensões de Plugins do OpenClaw. Para Plugins de Active Memory, o slot de memória é redefinido para `memory-core`.
|
||||
|
||||
<Note>
|
||||
`--keep-config` é compatível como alias obsoleto de `--keep-files`.
|
||||
`--keep-config` é compatível como um alias obsoleto de `--keep-files`.
|
||||
</Note>
|
||||
|
||||
### Atualizar
|
||||
@ -308,29 +308,29 @@ openclaw plugins update @openclaw/voice-call
|
||||
openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install
|
||||
```
|
||||
|
||||
Atualizações se aplicam a instalações de Plugin rastreadas no índice gerenciado de plugins e a instalações de hook-pack rastreadas em `hooks.internal.installs`.
|
||||
Atualizações se aplicam a instalações de Plugin rastreadas no índice de Plugins gerenciado e a instalações de pacotes de hooks rastreadas em `hooks.internal.installs`.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Resolvendo id de Plugin vs especificação npm">
|
||||
Quando você passa um id de Plugin, OpenClaw reutiliza a especificação de instalação registrada para esse Plugin. Isso significa que dist-tags armazenadas anteriormente, como `@beta`, e versões fixadas exatas continuam sendo usadas em execuções posteriores de `update <id>`.
|
||||
<Accordion title="Resolving plugin id vs npm spec">
|
||||
Quando você passa um id de Plugin, o OpenClaw reutiliza a especificação de instalação registrada para esse Plugin. Isso significa que dist-tags armazenadas anteriormente, como `@beta`, e versões exatas fixadas continuam sendo usadas em execuções posteriores de `update <id>`.
|
||||
|
||||
Para instalações npm, você também pode passar uma especificação explícita de pacote npm com uma dist-tag ou versão exata. OpenClaw resolve esse nome de pacote de volta para o registro de Plugin rastreado, atualiza esse Plugin instalado e registra a nova especificação npm para futuras atualizações baseadas em id.
|
||||
Para instalações npm, você também pode passar uma especificação explícita de pacote npm com uma dist-tag ou versão exata. O OpenClaw resolve esse nome de pacote de volta para o registro de Plugin rastreado, atualiza esse Plugin instalado e registra a nova especificação npm para futuras atualizações baseadas em id.
|
||||
|
||||
Passar o nome do pacote npm sem versão ou tag também resolve de volta para o registro de Plugin rastreado. Use isso quando um Plugin tiver sido fixado em uma versão exata e você quiser movê-lo de volta para a linha de lançamento padrão do registro.
|
||||
Passar o nome do pacote npm sem versão ou tag também resolve de volta para o registro de Plugin rastreado. Use isso quando um Plugin tiver sido fixado a uma versão exata e você quiser movê-lo de volta para a linha de lançamento padrão do registro.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Atualizações do canal beta">
|
||||
`openclaw plugins update` reutiliza a especificação de Plugin rastreada, a menos que você passe uma nova especificação. `openclaw update` também conhece o canal ativo de atualização do OpenClaw: no canal beta, registros de Plugin npm e ClawHub da linha padrão tentam `@beta` primeiro e depois voltam para a especificação padrão/latest registrada se não existir lançamento beta do Plugin. Versões exatas e tags explícitas permanecem fixadas nesse seletor.
|
||||
<Accordion title="Beta channel updates">
|
||||
`openclaw plugins update` reutiliza a especificação de Plugin rastreada, a menos que você passe uma nova especificação. `openclaw update` também conhece o canal de atualização ativo do OpenClaw: no canal beta, registros de Plugin npm e ClawHub da linha padrão tentam `@beta` primeiro e, em seguida, fazem fallback para a especificação padrão/latest registrada se não existir lançamento beta do Plugin. Versões exatas e tags explícitas permanecem fixadas nesse seletor.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Verificações de versão e desvio de integridade">
|
||||
Antes de uma atualização npm ao vivo, OpenClaw verifica a versão do pacote instalado em relação aos metadados do registro npm. Se a versão instalada e a identidade do artefato registrado já corresponderem ao destino resolvido, a atualização é ignorada sem baixar, reinstalar ou reescrever `openclaw.json`.
|
||||
<Accordion title="Version checks and integrity drift">
|
||||
Antes de uma atualização npm em tempo real, o OpenClaw verifica a versão do pacote instalado em relação aos metadados do registro npm. Se a versão instalada e a identidade do artefato registrada já corresponderem ao destino resolvido, a atualização é ignorada sem baixar, reinstalar ou reescrever `openclaw.json`.
|
||||
|
||||
Quando existe um hash de integridade armazenado e o hash do artefato obtido muda, OpenClaw trata isso como desvio de artefato npm. O comando interativo `openclaw plugins update` imprime os hashes esperado e real e pede confirmação antes de prosseguir. Auxiliares de atualização não interativos falham de forma fechada, a menos que o chamador forneça uma política explícita de continuação.
|
||||
Quando existe um hash de integridade armazenado e o hash do artefato obtido muda, o OpenClaw trata isso como desvio de artefato npm. O comando interativo `openclaw plugins update` imprime os hashes esperado e real e pede confirmação antes de continuar. Auxiliares de atualização não interativos falham em modo fechado, a menos que o chamador forneça uma política de continuação explícita.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="--dangerously-force-unsafe-install na atualização">
|
||||
`--dangerously-force-unsafe-install` também está disponível em `plugins update` como uma substituição emergencial para falsos positivos da varredura integrada de código perigoso durante atualizações de Plugin. Ele ainda não contorna bloqueios de política `before_install` de Plugin nem bloqueio por falha de varredura, e se aplica apenas a atualizações de Plugin, não a atualizações de hook-pack.
|
||||
<Accordion title="--dangerously-force-unsafe-install on update">
|
||||
`--dangerously-force-unsafe-install` também está disponível em `plugins update` como uma substituição de emergência para falsos positivos da varredura integrada de código perigoso durante atualizações de Plugin. Ele ainda não contorna bloqueios de política `before_install` do Plugin nem bloqueio por falha de varredura, e se aplica apenas a atualizações de Plugin, não a atualizações de pacotes de hooks.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@ -342,9 +342,9 @@ openclaw plugins inspect <id> --runtime
|
||||
openclaw plugins inspect <id> --json
|
||||
```
|
||||
|
||||
A inspeção mostra identidade, status de carregamento, fonte, recursos do manifesto, flags de política, diagnósticos, metadados de instalação, recursos de pacote e qualquer suporte detectado a servidor MCP ou LSP, sem importar runtime de Plugin por padrão. Adicione `--runtime` para carregar o módulo do Plugin e incluir hooks, ferramentas, comandos, serviços, métodos de Gateway e rotas HTTP registrados. A inspeção em runtime relata diretamente dependências ausentes de Plugin; instalações e reparos permanecem em `openclaw plugins install`, `openclaw plugins update` e `openclaw doctor --fix`.
|
||||
A inspeção mostra identidade, estado de carregamento, fonte, recursos do manifest, flags de política, diagnósticos, metadados de instalação, recursos de pacote e qualquer suporte detectado a servidores MCP ou LSP sem importar o runtime do Plugin por padrão. Adicione `--runtime` para carregar o módulo do Plugin e incluir hooks, ferramentas, comandos, serviços, métodos de Gateway e rotas HTTP registrados. A inspeção de runtime relata dependências ausentes do Plugin diretamente; instalações e reparos permanecem em `openclaw plugins install`, `openclaw plugins update` e `openclaw doctor --fix`.
|
||||
|
||||
Comandos de CLI pertencentes a Plugin são instalados como grupos de comandos raiz de `openclaw`. Depois que `inspect --runtime` mostrar um comando em `cliCommands`, execute-o como `openclaw <command> ...`; por exemplo, um Plugin que registra `demo-git` pode ser verificado com `openclaw demo-git ping`.
|
||||
Comandos de CLI pertencentes a Plugins são instalados como grupos de comandos raiz `openclaw`. Depois que `inspect --runtime` mostrar um comando em `cliCommands`, execute-o como `openclaw <command> ...`; por exemplo, um Plugin que registra `demo-git` pode ser verificado com `openclaw demo-git ping`.
|
||||
|
||||
Cada Plugin é classificado pelo que ele realmente registra em runtime:
|
||||
|
||||
@ -353,7 +353,7 @@ Cada Plugin é classificado pelo que ele realmente registra em runtime:
|
||||
- **hook-only** — apenas hooks, sem recursos ou superfícies
|
||||
- **non-capability** — ferramentas/comandos/serviços, mas sem recursos
|
||||
|
||||
Veja [Formatos de Plugin](/pt-BR/plugins/architecture#plugin-shapes) para mais sobre o modelo de recursos.
|
||||
Consulte [Formatos de Plugin](/pt-BR/plugins/architecture#plugin-shapes) para saber mais sobre o modelo de recursos.
|
||||
|
||||
<Note>
|
||||
A flag `--json` gera um relatório legível por máquina adequado para scripts e auditoria. `inspect --all` renderiza uma tabela de toda a frota com colunas de formato, tipos de recurso, avisos de compatibilidade, recursos de pacote e resumo de hooks. `info` é um alias de `inspect`.
|
||||
@ -365,9 +365,9 @@ A flag `--json` gera um relatório legível por máquina adequado para scripts e
|
||||
openclaw plugins doctor
|
||||
```
|
||||
|
||||
`doctor` relata erros de carregamento de Plugin, diagnósticos de manifesto/descoberta e avisos de compatibilidade. Quando tudo está limpo, ele imprime `No plugin issues detected.`
|
||||
`doctor` relata erros de carregamento de Plugin, diagnósticos de manifest/descoberta e avisos de compatibilidade. Quando tudo está limpo, ele imprime `No plugin issues detected.`
|
||||
|
||||
Se um Plugin configurado estiver presente em disco, mas bloqueado pelas verificações de segurança de caminho do carregador, a validação de configuração mantém a entrada do Plugin e a relata como `present but blocked`. Corrija o diagnóstico anterior de Plugin bloqueado, como propriedade do caminho ou permissões graváveis por todos, em vez de remover a configuração `plugins.entries.<id>` ou `plugins.allow`.
|
||||
Se um Plugin configurado estiver presente no disco, mas bloqueado pelas verificações de segurança de caminho do loader, a validação de configuração mantém a entrada do Plugin e a relata como `present but blocked`. Corrija o diagnóstico anterior de Plugin bloqueado, como propriedade de caminho ou permissões graváveis pelo mundo, em vez de remover a configuração `plugins.entries.<id>` ou `plugins.allow`.
|
||||
|
||||
Para falhas de formato de módulo, como exports `register`/`activate` ausentes, execute novamente com `OPENCLAW_PLUGIN_LOAD_DEBUG=1` para incluir um resumo compacto do formato dos exports na saída de diagnóstico.
|
||||
|
||||
@ -379,25 +379,27 @@ openclaw plugins registry --refresh
|
||||
openclaw plugins registry --json
|
||||
```
|
||||
|
||||
O registro local de plugins é o modelo de leitura fria persistido do OpenClaw para identidade de Plugin instalado, habilitação, metadados de fonte e propriedade de contribuições. Inicialização normal, busca de proprietário de provedor, classificação de configuração de canal e inventário de Plugin podem lê-lo sem importar módulos de runtime de Plugin.
|
||||
O registro local de Plugins é o modelo persistido de leitura fria do OpenClaw para identidade de Plugins instalados, habilitação, metadados de fonte e propriedade de contribuição. A inicialização normal, a busca de proprietário de provedor, a classificação de configuração de canal e o inventário de Plugins podem lê-lo sem importar módulos de runtime de Plugin.
|
||||
|
||||
Use `plugins registry` para inspecionar se o registro persistido está presente, atual ou obsoleto. Use `--refresh` para reconstruí-lo a partir do índice de Plugin persistido, da política de configuração e dos metadados de manifesto/pacote. Este é um caminho de reparo, não um caminho de ativação em tempo de execução.
|
||||
Use `plugins registry` para inspecionar se o registro persistido está presente, atual ou obsoleto. Use `--refresh` para reconstruí-lo a partir do índice persistido de Plugins, da política de configuração e dos metadados de manifesto/pacote. Este é um caminho de reparo, não um caminho de ativação em tempo de execução.
|
||||
|
||||
`openclaw doctor --fix` também repara desvios de npm gerenciado adjacentes ao registro: se um pacote `@openclaw/*` órfão ou recuperado sob a raiz npm de Plugins gerenciados sombrear um Plugin incluído, o doctor remove esse pacote obsoleto e reconstrói o registro para que a inicialização valide contra o manifesto incluído.
|
||||
|
||||
<Warning>
|
||||
`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` é um interruptor de compatibilidade emergencial obsoleto para falhas de leitura do registro. Prefira `plugins registry --refresh` ou `openclaw doctor --fix`; o fallback por variável de ambiente é apenas para recuperação emergencial de inicialização enquanto a migração é distribuída.
|
||||
`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` é uma chave de compatibilidade emergencial obsoleta para falhas de leitura do registro. Prefira `plugins registry --refresh` ou `openclaw doctor --fix`; o fallback por env é apenas para recuperação emergencial de inicialização enquanto a migração é distribuída.
|
||||
</Warning>
|
||||
|
||||
### Marketplace
|
||||
### Mercado
|
||||
|
||||
```bash
|
||||
openclaw plugins marketplace list <source>
|
||||
openclaw plugins marketplace list <source> --json
|
||||
```
|
||||
|
||||
A listagem do Marketplace aceita um caminho de Marketplace local, um caminho de `marketplace.json`, uma abreviação do GitHub como `owner/repo`, uma URL de repositório do GitHub ou uma URL git. `--json` imprime o rótulo da origem resolvida, além do manifesto do Marketplace analisado e das entradas de Plugin.
|
||||
A listagem do mercado aceita um caminho local de mercado, um caminho `marketplace.json`, um atalho do GitHub como `owner/repo`, uma URL de repositório do GitHub ou uma URL git. `--json` imprime o rótulo da fonte resolvida, além do manifesto de mercado analisado e das entradas de Plugin.
|
||||
|
||||
## Relacionado
|
||||
|
||||
- [Como criar Plugins](/pt-BR/plugins/building-plugins)
|
||||
- [Criando Plugins](/pt-BR/plugins/building-plugins)
|
||||
- [Referência da CLI](/pt-BR/cli)
|
||||
- [Plugins da comunidade](/pt-BR/plugins/community)
|
||||
|
||||
@ -1,20 +1,20 @@
|
||||
---
|
||||
read_when:
|
||||
- Adicionar ou modificar migrações do doctor
|
||||
- Introduzindo alterações incompatíveis na configuração
|
||||
- Adicionando ou modificando migrações do doctor
|
||||
- Introduzindo alterações de configuração incompatíveis
|
||||
sidebarTitle: Doctor
|
||||
summary: 'Comando doctor: verificações de integridade, migrações de configuração e etapas de reparo'
|
||||
title: Diagnóstico
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T21:32:10Z"
|
||||
generated_at: "2026-05-04T09:36:57Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 20b2cb3c3cd88e01050cb285a08a020603642439bd35668b7414360801fc03ff
|
||||
source_hash: 1bc8615f5e49e8c20785a9dc9779c447fd0d5794c80663d2396b0a20b4187798
|
||||
source_path: gateway/doctor.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
`openclaw doctor` é a ferramenta de reparo + migração do OpenClaw. Ela corrige configurações/estados obsoletos, verifica a integridade e fornece etapas de reparo acionáveis.
|
||||
`openclaw doctor` é a ferramenta de reparo + migração do OpenClaw. Ela corrige configurações/estado obsoletos, verifica a integridade e fornece etapas de reparo acionáveis.
|
||||
|
||||
## Início rápido
|
||||
|
||||
@ -30,7 +30,7 @@ openclaw doctor
|
||||
openclaw doctor --yes
|
||||
```
|
||||
|
||||
Aceita os padrões sem solicitar confirmação (incluindo etapas de reparo de reinício/serviço/sandbox quando aplicável).
|
||||
Aceita os padrões sem solicitar confirmação (incluindo etapas de reparo de reinicialização/serviço/sandbox quando aplicável).
|
||||
|
||||
</Tab>
|
||||
<Tab title="--repair">
|
||||
@ -38,7 +38,7 @@ openclaw doctor
|
||||
openclaw doctor --repair
|
||||
```
|
||||
|
||||
Aplica os reparos recomendados sem solicitar confirmação (reparos + reinícios quando seguro).
|
||||
Aplica os reparos recomendados sem solicitar confirmação (reparos + reinicializações quando seguro).
|
||||
|
||||
</Tab>
|
||||
<Tab title="--repair --force">
|
||||
@ -46,7 +46,7 @@ openclaw doctor
|
||||
openclaw doctor --repair --force
|
||||
```
|
||||
|
||||
Também aplica reparos agressivos (sobrescreve configurações personalizadas do supervisor).
|
||||
Aplica também reparos agressivos (sobrescreve configurações personalizadas de supervisor).
|
||||
|
||||
</Tab>
|
||||
<Tab title="--non-interactive">
|
||||
@ -54,7 +54,7 @@ openclaw doctor
|
||||
openclaw doctor --non-interactive
|
||||
```
|
||||
|
||||
Executa sem prompts e aplica apenas migrações seguras (normalização de configuração + movimentações de estado em disco). Ignora ações de reinício/serviço/sandbox que exigem confirmação humana. Migrações de estado legado são executadas automaticamente quando detectadas.
|
||||
Executa sem prompts e aplica apenas migrações seguras (normalização de configuração + movimentações de estado em disco). Ignora ações de reinicialização/serviço/sandbox que exigem confirmação humana. Migrações de estado legado são executadas automaticamente quando detectadas.
|
||||
|
||||
</Tab>
|
||||
<Tab title="--deep">
|
||||
@ -62,12 +62,12 @@ openclaw doctor
|
||||
openclaw doctor --deep
|
||||
```
|
||||
|
||||
Examina serviços do sistema em busca de instalações extras do gateway (launchd/systemd/schtasks).
|
||||
Verifica serviços do sistema em busca de instalações extras do gateway (launchd/systemd/schtasks).
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
Se quiser revisar as alterações antes de gravar, abra o arquivo de configuração primeiro:
|
||||
Se quiser revisar as mudanças antes de gravar, abra o arquivo de configuração primeiro:
|
||||
|
||||
```bash
|
||||
cat ~/.openclaw/openclaw.json
|
||||
@ -78,104 +78,104 @@ cat ~/.openclaw/openclaw.json
|
||||
<AccordionGroup>
|
||||
<Accordion title="Integridade, UI e atualizações">
|
||||
- Atualização prévia opcional para instalações via git (somente interativo).
|
||||
- Verificação de atualização do protocolo da UI (reconstrói a Control UI quando o esquema do protocolo é mais novo).
|
||||
- Verificação de integridade + prompt de reinício.
|
||||
- Resumo de status de Skills (elegíveis/ausentes/bloqueadas) e status de plugins.
|
||||
- Verificação de atualização do protocolo da UI (recompila a Control UI quando o schema do protocolo é mais recente).
|
||||
- Verificação de integridade + prompt de reinicialização.
|
||||
- Resumo de status de Skills (elegíveis/ausentes/bloqueadas) e status de Plugin.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Configuração e migrações">
|
||||
- Normalização de configuração para valores legados.
|
||||
- Migração da configuração de Talk de campos planos legados `talk.*` para `talk.provider` + `talk.providers.<provider>`.
|
||||
- Verificações de migração de navegador para configurações legadas de extensão do Chrome e prontidão do MCP do Chrome.
|
||||
- Migração da configuração do Talk de campos planos legados `talk.*` para `talk.provider` + `talk.providers.<provider>`.
|
||||
- Verificações de migração do navegador para configurações legadas da extensão do Chrome e prontidão do Chrome MCP.
|
||||
- Avisos de substituição do provedor OpenCode (`models.providers.opencode` / `models.providers.opencode-go`).
|
||||
- Avisos de sombreamento do OAuth do Codex (`models.providers.openai-codex`).
|
||||
- Verificação de pré-requisitos de TLS do OAuth para perfis OAuth do OpenAI Codex.
|
||||
- Avisos de allowlist de plugins/ferramentas quando `plugins.allow` é restritivo, mas a política de ferramentas ainda solicita curingas ou ferramentas pertencentes a plugins.
|
||||
- Migração de estado legado em disco (sessions/agent dir/WhatsApp auth).
|
||||
- Migração de chaves legadas do contrato de manifesto de plugins (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`).
|
||||
- Migração do armazenamento legado de cron (`jobId`, `schedule.cron`, campos de entrega/payload de nível superior, `provider` do payload, tarefas webhook fallback simples `notify: true`).
|
||||
- Migração da política de runtime de agentes legada para `agents.defaults.agentRuntime` e `agents.list[].agentRuntime`.
|
||||
- Limpeza de configuração obsoleta de plugins quando plugins estão habilitados; quando `plugins.enabled=false`, referências obsoletas a plugins são tratadas como configuração de contenção inerte e preservadas.
|
||||
- Avisos de lista de permissões de plugins/ferramentas quando `plugins.allow` é restritiva, mas a política de ferramentas ainda pede curingas ou ferramentas pertencentes a plugins.
|
||||
- Migração de estado legado em disco (sessions/agent dir/autenticação do WhatsApp).
|
||||
- Migração de chaves legadas de contrato de manifesto de plugin (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`).
|
||||
- Migração de armazenamento Cron legado (`jobId`, `schedule.cron`, campos de entrega/payload de nível superior, payload `provider`, tarefas simples de fallback de Webhook `notify: true`).
|
||||
- Migração de política de runtime de agentes legada para `agents.defaults.agentRuntime` e `agents.list[].agentRuntime`.
|
||||
- Limpeza de configuração obsoleta de Plugin quando plugins estão habilitados; quando `plugins.enabled=false`, referências obsoletas de Plugin são tratadas como configuração inerte de contenção e são preservadas.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Estado e integridade">
|
||||
- Inspeção de arquivos de bloqueio de sessão e limpeza de bloqueios obsoletos.
|
||||
- Reparo de transcritos de sessão para ramificações duplicadas de reescrita de prompt criadas por builds 2026.4.24 afetados.
|
||||
- Detecção de tombstone de recuperação por reinício de subagente travado, com suporte a `--fix` para limpar flags obsoletas de recuperação abortada, para que a inicialização não continue tratando o filho como abortado por reinício.
|
||||
- Verificações de integridade de estado e permissões (sessions, transcripts, state dir).
|
||||
- Verificações de permissão do arquivo de configuração (chmod 600) ao executar localmente.
|
||||
- Integridade de autenticação de modelos: verifica expiração de OAuth, pode atualizar tokens prestes a expirar e relata estados de cooldown/desabilitado de perfis de autenticação.
|
||||
- Detecção de diretório de workspace extra (`~/openclaw`).
|
||||
- Reparo de transcrições de sessão para branches duplicados de reescrita de prompt criados por builds 2026.4.24 afetadas.
|
||||
- Detecção de tombstone de recuperação de reinicialização de subagentes travados, com suporte a `--fix` para limpar flags obsoletas de recuperação abortada para que a inicialização não continue tratando o filho como abortado na reinicialização.
|
||||
- Verificações de integridade de estado e permissões (sessões, transcrições, diretório de estado).
|
||||
- Verificações de permissões do arquivo de configuração (chmod 600) ao executar localmente.
|
||||
- Integridade da autenticação de modelos: verifica expiração de OAuth, pode atualizar tokens prestes a expirar e informa estados de cooldown/desabilitado de perfis de autenticação.
|
||||
- Detecção de diretório extra de workspace (`~/openclaw`).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Gateway, serviços e supervisores">
|
||||
- Reparo de imagem de sandbox quando sandboxing está habilitado.
|
||||
- Migração de serviço legado e detecção de gateway extra.
|
||||
- Migração de estado legado do canal Matrix (em modo `--fix` / `--repair`).
|
||||
- Verificações de runtime do gateway (serviço instalado, mas não em execução; rótulo launchd em cache).
|
||||
- Reparo da imagem de sandbox quando o sandboxing está habilitado.
|
||||
- Migração de serviço legado e detecção de gateways extras.
|
||||
- Migração de estado legado do canal Matrix (no modo `--fix` / `--repair`).
|
||||
- Verificações de runtime do Gateway (serviço instalado, mas não em execução; rótulo launchd em cache).
|
||||
- Avisos de status de canais (sondados a partir do gateway em execução).
|
||||
- Auditoria de configuração do supervisor (launchd/systemd/schtasks) com reparo opcional.
|
||||
- Limpeza do ambiente de proxy embutido para serviços de gateway que capturaram valores de shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` durante a instalação ou atualização.
|
||||
- Verificações de boas práticas de runtime do gateway (Node vs Bun, caminhos de gerenciadores de versão).
|
||||
- Diagnósticos de colisão de porta do gateway (padrão `18789`).
|
||||
- Auditoria de configuração de supervisor (launchd/systemd/schtasks) com reparo opcional.
|
||||
- Limpeza do ambiente de proxy embutido para serviços de Gateway que capturaram valores de shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` durante a instalação ou atualização.
|
||||
- Verificações de boas práticas de runtime do Gateway (Node vs Bun, caminhos de gerenciadores de versão).
|
||||
- Diagnósticos de colisão de porta do Gateway (padrão `18789`).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Autenticação, segurança e pareamento">
|
||||
- Avisos de segurança para políticas abertas de DM.
|
||||
- Verificações de autenticação do gateway para modo de token local (oferece geração de token quando não existe fonte de token; não sobrescreve configurações SecretRef de token).
|
||||
- Detecção de problemas de pareamento de dispositivo (solicitações pendentes de primeiro pareamento, upgrades pendentes de função/escopo, desvio obsoleto do cache local de token de dispositivo e desvio de autenticação de registro pareado).
|
||||
- Avisos de segurança para políticas de DM abertas.
|
||||
- Verificações de autenticação do Gateway para modo de token local (oferece geração de token quando não existe fonte de token; não sobrescreve configurações de SecretRef de token).
|
||||
- Detecção de problemas de pareamento de dispositivos (solicitações pendentes de primeiro pareamento, upgrades pendentes de função/escopo, divergência obsoleta do cache local de token de dispositivo e divergência de autenticação de registro pareado).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Workspace e shell">
|
||||
- Verificação de linger do systemd no Linux.
|
||||
- Verificação de tamanho do arquivo de bootstrap do workspace (avisos de truncamento/próximo do limite para arquivos de contexto).
|
||||
- Verificação de prontidão de Skills para o agente padrão; relata skills permitidas com bins, env, configuração ou requisitos de SO ausentes, e `--fix` pode desabilitar skills indisponíveis em `skills.entries`.
|
||||
- Verificação de status de complementação de shell e instalação/atualização automática.
|
||||
- Verificação de prontidão de Skills para o agente padrão; informa skills permitidas com bins, env, configuração ou requisitos de SO ausentes, e `--fix` pode desabilitar skills indisponíveis em `skills.entries`.
|
||||
- Verificação de status de conclusão do shell e instalação/upgrade automático.
|
||||
- Verificação de prontidão do provedor de embeddings de busca de memória (modelo local, chave de API remota ou binário QMD).
|
||||
- Verificações de instalação a partir do código-fonte (incompatibilidade de workspace pnpm, assets de UI ausentes, binário tsx ausente).
|
||||
- Verificações de instalação a partir do código-fonte (incompatibilidade do workspace pnpm, assets de UI ausentes, binário tsx ausente).
|
||||
- Grava configuração atualizada + metadados do assistente.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Preenchimento retroativo e redefinição da UI Dreams
|
||||
## Backfill e reset da UI Dreams
|
||||
|
||||
A cena Dreams da Control UI inclui ações **Preenchimento retroativo**, **Redefinir** e **Limpar fundamentadas** para o fluxo de trabalho de grounded dreaming. Essas ações usam métodos RPC no estilo do doctor do gateway, mas **não** fazem parte do reparo/migração da CLI `openclaw doctor`.
|
||||
A cena Dreams da Control UI inclui as ações **Backfill**, **Reset** e **Clear Grounded** para o fluxo de trabalho de dreaming ancorado. Essas ações usam métodos RPC no estilo doctor do gateway, mas **não** fazem parte do reparo/migração da CLI `openclaw doctor`.
|
||||
|
||||
O que elas fazem:
|
||||
|
||||
- **Preenchimento retroativo** examina arquivos históricos `memory/YYYY-MM-DD.md` no workspace ativo, executa a passagem de diário REM fundamentada e grava entradas reversíveis de preenchimento retroativo em `DREAMS.md`.
|
||||
- **Redefinir** remove apenas essas entradas de diário de preenchimento retroativo marcadas de `DREAMS.md`.
|
||||
- **Limpar fundamentadas** remove apenas entradas de curto prazo staged apenas fundamentadas que vieram de replay histórico e ainda não acumularam recall ao vivo ou suporte diário.
|
||||
- **Backfill** verifica arquivos históricos `memory/YYYY-MM-DD.md` no workspace ativo, executa a passagem de diário REM ancorado e grava entradas reversíveis de backfill em `DREAMS.md`.
|
||||
- **Reset** remove apenas essas entradas marcadas de diário de backfill de `DREAMS.md`.
|
||||
- **Clear Grounded** remove apenas entradas encenadas de curto prazo, somente ancoradas, que vieram de replay histórico e ainda não acumularam recordação ao vivo ou suporte diário.
|
||||
|
||||
O que elas **não** fazem por si só:
|
||||
|
||||
- elas não editam `MEMORY.md`
|
||||
- elas não executam migrações completas do doctor
|
||||
- elas não staged automaticamente candidatas fundamentadas no armazenamento de promoção de curto prazo ao vivo, a menos que você execute explicitamente o caminho staged da CLI primeiro
|
||||
- elas não encenam automaticamente candidatos ancorados no armazenamento de promoção de curto prazo ao vivo, a menos que você execute explicitamente o caminho encenado da CLI primeiro
|
||||
|
||||
Se quiser que o replay histórico fundamentado influencie a trilha normal de promoção profunda, use o fluxo da CLI em vez disso:
|
||||
Se quiser que o replay histórico ancorado influencie a faixa normal de promoção profunda, use o fluxo da CLI em vez disso:
|
||||
|
||||
```bash
|
||||
openclaw memory rem-backfill --path ./memory --stage-short-term
|
||||
```
|
||||
|
||||
Isso coloca candidatas duráveis fundamentadas no armazenamento de dreaming de curto prazo, mantendo `DREAMS.md` como a superfície de revisão.
|
||||
Isso encena candidatos duráveis ancorados no armazenamento de dreaming de curto prazo, mantendo `DREAMS.md` como a superfície de revisão.
|
||||
|
||||
## Comportamento detalhado e justificativa
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="0. Atualização opcional (instalações via git)">
|
||||
Se esta for uma checkout git e o doctor estiver sendo executado interativamente, ele oferece atualizar (fetch/rebase/build) antes de executar o doctor.
|
||||
Se este for um checkout git e o doctor estiver sendo executado de forma interativa, ele oferece atualizar (fetch/rebase/build) antes de executar o doctor.
|
||||
</Accordion>
|
||||
<Accordion title="1. Normalização de configuração">
|
||||
Se a configuração contiver formatos de valores legados (por exemplo, `messages.ackReaction` sem uma substituição específica de canal), o doctor os normaliza para o esquema atual.
|
||||
Se a configuração contiver formatos de valores legados (por exemplo, `messages.ackReaction` sem uma substituição específica de canal), o doctor os normaliza para o schema atual.
|
||||
|
||||
Isso inclui campos planos legados do Talk. A configuração pública atual do Talk é `talk.provider` + `talk.providers.<provider>`. O doctor reescreve formatos antigos `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` para o mapa de provedores.
|
||||
|
||||
O doctor também avisa quando `plugins.allow` não está vazio e a política de ferramentas usa
|
||||
entradas de ferramenta curinga ou pertencentes a plugins. `tools.allow: ["*"]` corresponde apenas a ferramentas
|
||||
de plugins que realmente carregam; ele não contorna a allowlist exclusiva de plugins.
|
||||
curingas ou entradas de ferramentas pertencentes a plugins. `tools.allow: ["*"]` corresponde apenas a ferramentas
|
||||
de plugins que realmente carregam; ele não ignora a lista de permissões exclusiva de plugins.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="2. Migrações de chaves de configuração legadas">
|
||||
@ -184,10 +184,10 @@ Isso coloca candidatas duráveis fundamentadas no armazenamento de dreaming de c
|
||||
O doctor irá:
|
||||
|
||||
- Explicar quais chaves legadas foram encontradas.
|
||||
- Mostrar a migração aplicada.
|
||||
- Reescrever `~/.openclaw/openclaw.json` com o esquema atualizado.
|
||||
- Mostrar a migração que ele aplicou.
|
||||
- Reescrever `~/.openclaw/openclaw.json` com o schema atualizado.
|
||||
|
||||
O Gateway também executa automaticamente migrações do doctor na inicialização quando detecta um formato de configuração legado, então configurações obsoletas são reparadas sem intervenção manual. Migrações do armazenamento de tarefas Cron são tratadas por `openclaw doctor --fix`.
|
||||
O Gateway também executa automaticamente migrações do doctor na inicialização quando detecta um formato de configuração legado, então configurações obsoletas são reparadas sem intervenção manual. Migrações de armazenamento de tarefas Cron são tratadas por `openclaw doctor --fix`.
|
||||
|
||||
Migrações atuais:
|
||||
|
||||
@ -197,9 +197,9 @@ Isso coloca candidatas duráveis fundamentadas no armazenamento de dreaming de c
|
||||
- `routing.groupChat.mentionPatterns` → `messages.groupChat.mentionPatterns`
|
||||
- configurações de canais configurados sem política de resposta visível → `messages.groupChat.visibleReplies: "message_tool"`
|
||||
- `routing.queue` → `messages.queue`
|
||||
- `routing.bindings` → `bindings` no nível superior
|
||||
- `routing.bindings` → `bindings` de nível superior
|
||||
- `routing.agents`/`routing.defaultAgentId` → `agents.list` + `agents.list[].default`
|
||||
- legado `talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` → `talk.provider` + `talk.providers.<provider>`
|
||||
- `talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` legados → `talk.provider` + `talk.providers.<provider>`
|
||||
- `routing.agentToAgent` → `tools.agentToAgent`
|
||||
- `routing.transcribeAudio` → `tools.media.audio.models`
|
||||
- `messages.tts.<provider>` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `messages.tts.providers.<provider>`
|
||||
@ -213,70 +213,70 @@ Isso coloca candidatas duráveis fundamentadas no armazenamento de dreaming de c
|
||||
- `plugins.entries.voice-call.config.streaming.sttProvider` → `plugins.entries.voice-call.config.streaming.provider`
|
||||
- `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold` → `plugins.entries.voice-call.config.streaming.providers.openai.*`
|
||||
- `bindings[].match.accountID` → `bindings[].match.accountId`
|
||||
- Para canais com `accounts` nomeadas, mas com valores de canal de nível superior de conta única remanescentes, mova esses valores com escopo de conta para a conta promovida escolhida para esse canal (`accounts.default` para a maioria dos canais; Matrix pode preservar um destino nomeado/padrão correspondente existente)
|
||||
- Para canais com `accounts` nomeadas, mas valores de canal de nível superior de conta única remanescentes, mova esses valores com escopo de conta para a conta promovida escolhida para esse canal (`accounts.default` para a maioria dos canais; Matrix pode preservar um destino nomeado/padrão correspondente existente)
|
||||
- `identity` → `agents.list[].identity`
|
||||
- `agent.*` → `agents.defaults` + `tools.*` (tools/elevated/exec/sandbox/subagents)
|
||||
- `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks` → `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks`
|
||||
- remova `agents.defaults.llm`; use `models.providers.<id>.timeoutSeconds` para tempos limite de provedores/modelos lentos
|
||||
- `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`
|
||||
- `browser.profiles.*.driver: "extension"` → `"existing-session"`
|
||||
- remova `browser.relayBindHost` (configuração legada de relay da extensão)
|
||||
- legado `models.providers.*.api: "openai"` → `"openai-completions"` (a inicialização do Gateway também ignora provedores cujo `api` esteja definido como um valor de enumeração futuro ou desconhecido, em vez de falhar de forma fechada)
|
||||
- remova `browser.relayBindHost` (configuração legada de retransmissão da extensão)
|
||||
- `models.providers.*.api: "openai"` legado → `"openai-completions"` (a inicialização do gateway também ignora provedores cujo `api` está definido como um valor enum futuro ou desconhecido, em vez de falhar fechado)
|
||||
|
||||
Os avisos do Doctor também incluem orientação de conta padrão para canais com várias contas:
|
||||
Os avisos do doctor também incluem orientação de conta padrão para canais com várias contas:
|
||||
|
||||
- Se duas ou mais entradas `channels.<channel>.accounts` forem configuradas sem `channels.<channel>.defaultAccount` ou `accounts.default`, o doctor avisa que o roteamento de fallback pode escolher uma conta inesperada.
|
||||
- Se duas ou mais entradas `channels.<channel>.accounts` estiverem configuradas sem `channels.<channel>.defaultAccount` ou `accounts.default`, o doctor avisa que o roteamento de fallback pode escolher uma conta inesperada.
|
||||
- Se `channels.<channel>.defaultAccount` estiver definido como um ID de conta desconhecido, o doctor avisa e lista os IDs de conta configurados.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="2b. Substituições de provedor OpenCode">
|
||||
<Accordion title="2b. Substituições do provedor OpenCode">
|
||||
Se você adicionou `models.providers.opencode`, `opencode-zen` ou `opencode-go` manualmente, isso substitui o catálogo OpenCode integrado de `@mariozechner/pi-ai`. Isso pode forçar modelos para a API errada ou zerar custos. O doctor avisa para que você possa remover a substituição e restaurar o roteamento de API + custos por modelo.
|
||||
</Accordion>
|
||||
<Accordion title="2c. Migração do navegador e prontidão para Chrome MCP">
|
||||
Se a configuração do seu navegador ainda aponta para o caminho da extensão Chrome removida, o doctor a normaliza para o modelo atual de anexação Chrome MCP local ao host:
|
||||
<Accordion title="2c. Migração de navegador e prontidão do Chrome MCP">
|
||||
Se a configuração do seu navegador ainda aponta para o caminho removido da extensão do Chrome, o doctor a normaliza para o modelo atual de anexação do Chrome MCP local ao host:
|
||||
|
||||
- `browser.profiles.*.driver: "extension"` se torna `"existing-session"`
|
||||
- `browser.relayBindHost` é removido
|
||||
|
||||
O doctor também audita o caminho Chrome MCP local ao host quando você usa `defaultProfile: "user"` ou um perfil `existing-session` configurado:
|
||||
O doctor também audita o caminho do Chrome MCP local ao host quando você usa `defaultProfile: "user"` ou um perfil `existing-session` configurado:
|
||||
|
||||
- verifica se o Google Chrome está instalado no mesmo host para perfis padrão de conexão automática
|
||||
- verifica a versão detectada do Chrome e avisa quando ela está abaixo do Chrome 144
|
||||
- lembra você de habilitar a depuração remota na página de inspeção do navegador (por exemplo, `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging` ou `edge://inspect/#remote-debugging`)
|
||||
|
||||
O Doctor não pode habilitar a configuração do lado do Chrome para você. O Chrome MCP local ao host ainda exige:
|
||||
O doctor não pode habilitar a configuração do lado do Chrome para você. O Chrome MCP local ao host ainda exige:
|
||||
|
||||
- um navegador baseado em Chromium 144+ no host do gateway/node
|
||||
- o navegador em execução localmente
|
||||
- depuração remota habilitada nesse navegador
|
||||
- aprovação do primeiro prompt de consentimento de anexação no navegador
|
||||
|
||||
A prontidão aqui é apenas sobre pré-requisitos de anexação local. Existing-session mantém os limites atuais de rota do Chrome MCP; rotas avançadas como `responsebody`, exportação de PDF, interceptação de download e ações em lote ainda exigem um navegador gerenciado ou perfil CDP bruto.
|
||||
A prontidão aqui diz respeito apenas aos pré-requisitos de anexação local. `Existing-session` mantém os limites atuais de rota do Chrome MCP; rotas avançadas como `responsebody`, exportação de PDF, interceptação de download e ações em lote ainda exigem um navegador gerenciado ou perfil CDP bruto.
|
||||
|
||||
Essa verificação **não** se aplica a Docker, sandbox, remote-browser ou outros fluxos headless. Esses continuam usando CDP bruto.
|
||||
Esta verificação **não** se aplica a Docker, sandbox, navegador remoto ou outros fluxos headless. Eles continuam usando CDP bruto.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="2d. Pré-requisitos de TLS do OAuth">
|
||||
Quando um perfil OAuth do OpenAI Codex é configurado, o doctor consulta o endpoint de autorização da OpenAI para verificar se a pilha TLS local do Node/OpenSSL consegue validar a cadeia de certificados. Se a sondagem falhar com um erro de certificado (por exemplo, `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, certificado expirado ou certificado autoassinado), o doctor imprime orientação de correção específica da plataforma. No macOS com um Node do Homebrew, a correção geralmente é `brew postinstall ca-certificates`. Com `--deep`, a sondagem é executada mesmo que o gateway esteja íntegro.
|
||||
Quando um perfil OAuth do OpenAI Codex está configurado, o doctor consulta o endpoint de autorização da OpenAI para verificar se a pilha TLS local de Node/OpenSSL consegue validar a cadeia de certificados. Se a consulta falhar com um erro de certificado (por exemplo, `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, certificado expirado ou certificado autoassinado), o doctor imprime orientação de correção específica para a plataforma. No macOS com um Node do Homebrew, a correção geralmente é `brew postinstall ca-certificates`. Com `--deep`, a consulta é executada mesmo se o gateway estiver saudável.
|
||||
</Accordion>
|
||||
<Accordion title="2e. Substituições do provedor OAuth do Codex">
|
||||
Se você adicionou anteriormente configurações legadas de transporte da OpenAI em `models.providers.openai-codex`, elas podem encobrir o caminho integrado do provedor OAuth do Codex que versões mais novas usam automaticamente. O Doctor avisa quando vê essas configurações antigas de transporte junto com OAuth do Codex, para que você possa remover ou reescrever a substituição obsoleta de transporte e recuperar o comportamento integrado de roteamento/fallback. Proxies personalizados e substituições apenas de cabeçalho ainda são compatíveis e não acionam esse aviso.
|
||||
Se você adicionou anteriormente configurações legadas de transporte da OpenAI em `models.providers.openai-codex`, elas podem sombrear o caminho integrado do provedor OAuth do Codex que versões mais novas usam automaticamente. O doctor avisa quando vê essas configurações antigas de transporte junto com o OAuth do Codex para que você possa remover ou reescrever a substituição de transporte obsoleta e recuperar o comportamento integrado de roteamento/fallback. Proxies personalizados e substituições apenas de cabeçalho ainda são compatíveis e não acionam este aviso.
|
||||
</Accordion>
|
||||
<Accordion title="2f. Avisos de rota do Plugin Codex">
|
||||
Quando o Plugin Codex integrado está habilitado, o doctor também verifica se referências de modelo primário `openai-codex/*` ainda são resolvidas pelo runner PI padrão. Essa combinação é válida quando você quer autenticação OAuth/assinatura do Codex por meio do PI, mas é fácil confundi-la com o harness nativo de servidor de app do Codex. O Doctor avisa e aponta para o formato explícito de servidor de app: `openai/*` mais `agentRuntime.id: "codex"` ou `OPENCLAW_AGENT_RUNTIME=codex`.
|
||||
Quando o Plugin Codex incluído está habilitado, o doctor também verifica se referências de modelo primário `openai-codex/*` ainda são resolvidas pelo executor padrão do PI. Essa combinação é válida quando você quer autenticação OAuth/assinatura do Codex pelo PI, mas é fácil confundi-la com o harness nativo do app-server do Codex. O doctor avisa e aponta para o formato explícito do app-server: `openai/*` mais `agentRuntime.id: "codex"` ou `OPENCLAW_AGENT_RUNTIME=codex`.
|
||||
|
||||
O Doctor não repara isso automaticamente porque ambas as rotas são válidas:
|
||||
O doctor não repara isso automaticamente porque ambas as rotas são válidas:
|
||||
|
||||
- `openai-codex/*` + PI significa "usar autenticação OAuth/assinatura do Codex pelo runner normal do OpenClaw."
|
||||
- `openai/*` + `agentRuntime.id: "codex"` significa "executar o turno incorporado pelo servidor de app nativo do Codex."
|
||||
- `/codex ...` significa "controlar ou vincular uma conversa nativa do Codex a partir do chat."
|
||||
- `openai-codex/*` + PI significa "usar autenticação OAuth/assinatura do Codex pelo executor normal do OpenClaw."
|
||||
- `openai/*` + `agentRuntime.id: "codex"` significa "executar o turno incorporado pelo app-server nativo do Codex."
|
||||
- `/codex ...` significa "controlar ou vincular uma conversa nativa do Codex pelo chat."
|
||||
- `/acp ...` ou `runtime: "acp"` significa "usar o adaptador externo ACP/acpx."
|
||||
|
||||
Se o aviso aparecer, escolha a rota pretendida e edite a configuração manualmente. Mantenha o aviso como está quando PI Codex OAuth for intencional.
|
||||
Se o aviso aparecer, escolha a rota pretendida e edite a configuração manualmente. Mantenha o aviso como está quando o OAuth do Codex via PI for intencional.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="3. Migrações de estado legado (layout em disco)">
|
||||
O Doctor pode migrar layouts antigos em disco para a estrutura atual:
|
||||
O doctor pode migrar layouts mais antigos em disco para a estrutura atual:
|
||||
|
||||
- Armazenamento de sessões + transcrições:
|
||||
- de `~/.openclaw/sessions/` para `~/.openclaw/agents/<agentId>/sessions/`
|
||||
@ -286,14 +286,14 @@ Isso coloca candidatas duráveis fundamentadas no armazenamento de dreaming de c
|
||||
- de `~/.openclaw/credentials/*.json` legado (exceto `oauth.json`)
|
||||
- para `~/.openclaw/credentials/whatsapp/<accountId>/...` (ID da conta padrão: `default`)
|
||||
|
||||
Essas migrações são de melhor esforço e idempotentes; o doctor emitirá avisos quando deixar quaisquer pastas legadas para trás como backups. O Gateway/CLI também migra automaticamente o armazenamento legado de sessões + diretório do agente na inicialização, para que histórico/autenticação/modelos fiquem no caminho por agente sem execução manual do doctor. A autenticação do WhatsApp é intencionalmente migrada apenas por meio de `openclaw doctor`. A normalização de provedor/mapa de provedores de fala agora compara por igualdade estrutural, então diferenças apenas na ordem de chaves não acionam mais alterações repetidas sem efeito de `doctor --fix`.
|
||||
Essas migrações são por melhor esforço e idempotentes; o doctor emitirá avisos quando deixar quaisquer pastas legadas para trás como backups. O Gateway/CLI também migra automaticamente o armazenamento legado de sessões + diretório do agente na inicialização para que histórico/autenticação/modelos cheguem ao caminho por agente sem uma execução manual do doctor. A autenticação do WhatsApp é intencionalmente migrada apenas via `openclaw doctor`. A normalização de provedor/mapa de provedores de conversa agora compara por igualdade estrutural, então diferenças apenas na ordem das chaves não acionam mais alterações repetidas sem efeito de `doctor --fix`.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="3a. Migrações de manifesto de Plugin legado">
|
||||
O Doctor examina todos os manifestos de Plugin instalados em busca de chaves de capacidade de nível superior obsoletas (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). Quando encontradas, ele oferece movê-las para o objeto `contracts` e reescrever o arquivo de manifesto no local. Essa migração é idempotente; se a chave `contracts` já tiver os mesmos valores, a chave legada será removida sem duplicar os dados.
|
||||
<Accordion title="3a. Migrações de manifestos de Plugin legados">
|
||||
O doctor verifica todos os manifestos de Plugin instalados em busca de chaves de capacidade de nível superior obsoletas (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). Quando encontradas, ele oferece movê-las para o objeto `contracts` e reescrever o arquivo de manifesto no local. Esta migração é idempotente; se a chave `contracts` já tiver os mesmos valores, a chave legada é removida sem duplicar os dados.
|
||||
</Accordion>
|
||||
<Accordion title="3b. Migrações de armazenamento Cron legado">
|
||||
O Doctor também verifica o armazenamento de jobs do cron (`~/.openclaw/cron/jobs.json` por padrão, ou `cron.store` quando substituído) em busca de formatos antigos de jobs que o agendador ainda aceita por compatibilidade.
|
||||
O doctor também verifica o armazenamento de trabalhos cron (`~/.openclaw/cron/jobs.json` por padrão, ou `cron.store` quando substituído) em busca de formatos antigos de trabalhos que o agendador ainda aceita por compatibilidade.
|
||||
|
||||
As limpezas atuais de cron incluem:
|
||||
|
||||
@ -301,196 +301,196 @@ Isso coloca candidatas duráveis fundamentadas no armazenamento de dreaming de c
|
||||
- `schedule.cron` → `schedule.expr`
|
||||
- campos de payload de nível superior (`message`, `model`, `thinking`, ...) → `payload`
|
||||
- campos de entrega de nível superior (`deliver`, `channel`, `to`, `provider`, ...) → `delivery`
|
||||
- aliases de entrega `provider` no payload → `delivery.channel` explícito
|
||||
- jobs simples legados de fallback de webhook `notify: true` → `delivery.mode="webhook"` explícito com `delivery.to=cron.webhook`
|
||||
- aliases de entrega `provider` do payload → `delivery.channel` explícito
|
||||
- trabalhos simples legados de fallback de webhook `notify: true` → `delivery.mode="webhook"` explícito com `delivery.to=cron.webhook`
|
||||
|
||||
O Doctor só migra automaticamente jobs `notify: true` quando consegue fazer isso sem alterar o comportamento. Se um job combinar fallback legado de notificação com um modo de entrega não webhook existente, o doctor avisa e deixa esse job para revisão manual.
|
||||
O doctor só migra automaticamente trabalhos `notify: true` quando consegue fazer isso sem alterar o comportamento. Se um trabalho combina fallback legado de notificação com um modo de entrega não webhook existente, o doctor avisa e deixa esse trabalho para revisão manual.
|
||||
|
||||
No Linux, o doctor também avisa quando o crontab do usuário ainda invoca o legado `~/.openclaw/bin/ensure-whatsapp.sh`. Esse script local ao host não é mantido pelo OpenClaw atual e pode escrever mensagens falsas de `Gateway inactive` em `~/.openclaw/logs/whatsapp-health.log` quando o cron não consegue alcançar o barramento de usuário do systemd. Remova a entrada obsoleta do crontab com `crontab -e`; use `openclaw channels status --probe`, `openclaw doctor` e `openclaw gateway status` para verificações de integridade atuais.
|
||||
No Linux, o doctor também avisa quando o crontab do usuário ainda invoca o `~/.openclaw/bin/ensure-whatsapp.sh` legado. Esse script local ao host não é mantido pelo OpenClaw atual e pode gravar mensagens falsas de `Gateway inactive` em `~/.openclaw/logs/whatsapp-health.log` quando o cron não consegue alcançar o barramento de usuário do systemd. Remova a entrada obsoleta do crontab com `crontab -e`; use `openclaw channels status --probe`, `openclaw doctor` e `openclaw gateway status` para verificações de integridade atuais.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="3c. Limpeza de bloqueio de sessão">
|
||||
O doctor verifica cada diretório de sessão de agente em busca de arquivos de bloqueio de escrita obsoletos — arquivos deixados para trás quando uma sessão foi encerrada de forma anormal. Para cada arquivo de bloqueio encontrado, ele informa: o caminho, o PID, se o PID ainda está ativo, a idade do bloqueio e se ele é considerado obsoleto (PID morto ou mais antigo que 30 minutos). No modo `--fix` / `--repair`, ele remove arquivos de bloqueio obsoletos automaticamente; caso contrário, imprime uma observação e instrui você a executar novamente com `--fix`.
|
||||
<Accordion title="3c. Limpeza de bloqueios de sessão">
|
||||
O doctor verifica cada diretório de sessão de agente em busca de arquivos de bloqueio de escrita obsoletos — arquivos deixados para trás quando uma sessão foi encerrada de forma anormal. Para cada arquivo de bloqueio encontrado, ele relata: o caminho, PID, se o PID ainda está ativo, a idade do bloqueio e se ele é considerado obsoleto (PID inativo ou mais antigo que 30 minutos). No modo `--fix` / `--repair`, ele remove arquivos de bloqueio obsoletos automaticamente; caso contrário, imprime uma observação e instrui você a executar novamente com `--fix`.
|
||||
</Accordion>
|
||||
<Accordion title="3d. Reparo de ramificação de transcrição de sessão">
|
||||
O doctor verifica arquivos JSONL de sessão de agente em busca do formato de ramificação duplicado criado pelo bug de reescrita de transcrição de prompt da versão 2026.4.24: um turno de usuário abandonado com contexto interno de runtime do OpenClaw mais um irmão ativo contendo o mesmo prompt de usuário visível. No modo `--fix` / `--repair`, o doctor faz backup de cada arquivo afetado ao lado do original e reescreve a transcrição para a ramificação ativa, para que o histórico do Gateway e os leitores de memória não vejam mais turnos duplicados.
|
||||
O doctor verifica arquivos JSONL de sessão de agente em busca do formato de ramificação duplicada criado pelo bug de reescrita de transcrição de prompt de 2026.4.24: uma interação de usuário abandonada com contexto de runtime interno do OpenClaw mais uma ramificação irmã ativa contendo o mesmo prompt de usuário visível. No modo `--fix` / `--repair`, o doctor faz backup de cada arquivo afetado ao lado do original e reescreve a transcrição para a ramificação ativa, para que o histórico do Gateway e os leitores de memória não vejam mais interações duplicadas.
|
||||
</Accordion>
|
||||
<Accordion title="4. Verificações de integridade de estado (persistência de sessão, roteamento e segurança)">
|
||||
O diretório de estado é o tronco cerebral operacional. Se ele desaparecer, você perde sessões, credenciais, logs e configuração (a menos que tenha backups em outro lugar).
|
||||
O diretório de estado é o tronco encefálico operacional. Se ele desaparecer, você perde sessões, credenciais, logs e configuração (a menos que tenha backups em outro lugar).
|
||||
|
||||
O doctor verifica:
|
||||
|
||||
- **Diretório de estado ausente**: avisa sobre perda catastrófica de estado, solicita recriar o diretório e lembra que não pode recuperar dados ausentes.
|
||||
- **Permissões do diretório de estado**: verifica a capacidade de escrita; oferece reparar permissões (e emite uma dica de `chown` quando uma incompatibilidade de proprietário/grupo é detectada).
|
||||
- **Diretório de estado sincronizado com a nuvem no macOS**: avisa quando o estado é resolvido sob iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) ou `~/Library/CloudStorage/...`, porque caminhos baseados em sincronização podem causar I/O mais lento e corridas de bloqueio/sincronização.
|
||||
- **Diretório de estado em SD ou eMMC no Linux**: avisa quando o estado é resolvido para uma origem de montagem `mmcblk*`, porque I/O aleatório baseado em SD ou eMMC pode ser mais lento e se desgastar mais rapidamente sob escritas de sessão e credenciais.
|
||||
- **Diretório de estado ausente**: alerta sobre perda catastrófica de estado, solicita recriar o diretório e lembra que não consegue recuperar dados ausentes.
|
||||
- **Permissões do diretório de estado**: verifica a permissão de escrita; oferece reparar permissões (e emite uma dica de `chown` quando uma incompatibilidade de proprietário/grupo é detectada).
|
||||
- **Diretório de estado sincronizado com nuvem no macOS**: alerta quando o estado é resolvido sob iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) ou `~/Library/CloudStorage/...`, porque caminhos com sincronização podem causar E/S mais lenta e corridas de bloqueio/sincronização.
|
||||
- **Diretório de estado em SD ou eMMC no Linux**: alerta quando o estado é resolvido para uma origem de montagem `mmcblk*`, porque E/S aleatória baseada em SD ou eMMC pode ser mais lenta e desgastar mais rapidamente com escritas de sessão e credenciais.
|
||||
- **Diretórios de sessão ausentes**: `sessions/` e o diretório de armazenamento de sessões são necessários para persistir histórico e evitar falhas `ENOENT`.
|
||||
- **Incompatibilidade de transcrição**: avisa quando entradas de sessão recentes têm arquivos de transcrição ausentes.
|
||||
- **Sessão principal "JSONL de 1 linha"**: sinaliza quando a transcrição principal tem apenas uma linha (o histórico não está se acumulando).
|
||||
- **Múltiplos diretórios de estado**: avisa quando várias pastas `~/.openclaw` existem entre diretórios home ou quando `OPENCLAW_STATE_DIR` aponta para outro lugar (o histórico pode se dividir entre instalações).
|
||||
- **Incompatibilidade de transcrição**: alerta quando entradas recentes de sessão têm arquivos de transcrição ausentes.
|
||||
- **Sessão principal "JSONL de 1 linha"**: sinaliza quando a transcrição principal tem apenas uma linha (o histórico não está acumulando).
|
||||
- **Múltiplos diretórios de estado**: alerta quando existem várias pastas `~/.openclaw` entre diretórios home ou quando `OPENCLAW_STATE_DIR` aponta para outro lugar (o histórico pode se dividir entre instalações).
|
||||
- **Lembrete de modo remoto**: se `gateway.mode=remote`, o doctor lembra você de executá-lo no host remoto (o estado fica lá).
|
||||
- **Permissões do arquivo de configuração**: avisa se `~/.openclaw/openclaw.json` pode ser lido por grupo/todos e oferece restringir para `600`.
|
||||
- **Permissões do arquivo de configuração**: alerta se `~/.openclaw/openclaw.json` pode ser lido por grupo/todos e oferece restringir para `600`.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="5. Integridade da autenticação de modelo (expiração de OAuth)">
|
||||
O doctor inspeciona perfis OAuth no armazenamento de autenticação, avisa quando tokens estão expirando/expirados e pode atualizá-los quando for seguro. Se o perfil OAuth/token da Anthropic estiver obsoleto, ele sugere uma chave de API da Anthropic ou o caminho de token de configuração da Anthropic. Solicitações de atualização só aparecem ao executar interativamente (TTY); `--non-interactive` ignora tentativas de atualização.
|
||||
<Accordion title="5. Saúde da autenticação de modelo (expiração de OAuth)">
|
||||
O doctor inspeciona perfis OAuth no armazenamento de autenticação, alerta quando tokens estão expirando/expirados e pode renová-los quando for seguro. Se o perfil OAuth/token da Anthropic estiver obsoleto, ele sugere uma chave de API da Anthropic ou o caminho de token de configuração da Anthropic. Solicitações de renovação só aparecem ao executar interativamente (TTY); `--non-interactive` ignora tentativas de renovação.
|
||||
|
||||
Quando uma atualização OAuth falha permanentemente (por exemplo, `refresh_token_reused`, `invalid_grant` ou um provedor dizendo para você entrar novamente), o doctor informa que uma nova autenticação é necessária e imprime o comando exato `openclaw models auth login --provider ...` a executar.
|
||||
Quando uma renovação OAuth falha permanentemente (por exemplo, `refresh_token_reused`, `invalid_grant` ou um provedor dizendo para você entrar novamente), o doctor informa que uma nova autenticação é necessária e imprime o comando exato `openclaw models auth login --provider ...` a ser executado.
|
||||
|
||||
O doctor também informa perfis de autenticação temporariamente inutilizáveis devido a:
|
||||
O doctor também relata perfis de autenticação temporariamente inutilizáveis devido a:
|
||||
|
||||
- cooldowns curtos (limites de taxa/timeouts/falhas de autenticação)
|
||||
- períodos curtos de espera (limites de taxa/timeouts/falhas de autenticação)
|
||||
- desativações mais longas (falhas de cobrança/crédito)
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="6. Validação de modelo de hooks">
|
||||
Se `hooks.gmail.model` estiver definido, o doctor valida a referência do modelo em relação ao catálogo e à allowlist e avisa quando ela não puder ser resolvida ou não for permitida.
|
||||
Se `hooks.gmail.model` estiver definido, o doctor valida a referência do modelo contra o catálogo e a allowlist e alerta quando ela não puder ser resolvida ou não for permitida.
|
||||
</Accordion>
|
||||
<Accordion title="7. Reparo de imagem de sandbox">
|
||||
Quando o sandboxing está ativado, o doctor verifica imagens Docker e oferece criar ou mudar para nomes legados se a imagem atual estiver ausente.
|
||||
Quando o sandboxing está ativado, o doctor verifica imagens Docker e oferece criar ou trocar para nomes legados se a imagem atual estiver ausente.
|
||||
</Accordion>
|
||||
<Accordion title="7b. Limpeza de instalação de Plugin">
|
||||
O doctor remove estado legado de preparação de dependências de plugins gerado pelo OpenClaw no modo `openclaw doctor --fix` / `openclaw doctor --repair`. Isso cobre raízes de dependência geradas obsoletas, diretórios antigos de etapa de instalação e detritos locais de pacote de código anterior de reparo de dependências de plugins incluídos.
|
||||
O doctor remove estado legado de preparação de dependências de Plugin gerado pelo OpenClaw no modo `openclaw doctor --fix` / `openclaw doctor --repair`. Isso cobre raízes obsoletas de dependências geradas, diretórios antigos de etapa de instalação, resíduos locais de pacote de código anterior de reparo de dependências de Plugin empacotado e cópias npm gerenciadas órfãs ou recuperadas de Plugins `@openclaw/*` empacotados que podem sombrear o manifesto empacotado atual.
|
||||
|
||||
O doctor também pode reinstalar plugins baixáveis configurados quando a configuração os referencia, mas o registro local de plugins não consegue encontrá-los. Para a externalização de plugins incluídos da versão 2026.5.2, o doctor instala automaticamente plugins baixáveis que a configuração existente já usa e então se baseia em `meta.lastTouchedVersion` para executar essa passagem de versão apenas uma vez. A inicialização do Gateway e o recarregamento de configuração não executam gerenciadores de pacotes; instalações de plugins continuam sendo trabalho explícito de doctor/install/update.
|
||||
O doctor também pode reinstalar Plugins baixáveis configurados quando a configuração os referencia, mas o registro local de Plugins não consegue encontrá-los. Para a externalização de Plugins empacotados de 2026.5.2, o doctor instala automaticamente Plugins baixáveis que a configuração existente já usa e então depende de `meta.lastTouchedVersion` para executar essa passagem de versão apenas uma vez. A inicialização do Gateway e o recarregamento de configuração não executam gerenciadores de pacotes; instalações de Plugin continuam sendo trabalho explícito de doctor/instalação/atualização.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="8. Migrações de serviço Gateway e dicas de limpeza">
|
||||
O doctor detecta serviços Gateway legados (launchd/systemd/schtasks) e oferece removê-los e instalar o serviço OpenClaw usando a porta Gateway atual. Ele também pode verificar serviços extras semelhantes ao Gateway e imprimir dicas de limpeza. Serviços Gateway do OpenClaw nomeados por perfil são considerados de primeira classe e não são sinalizados como "extras".
|
||||
<Accordion title="8. Migrações de serviço do Gateway e dicas de limpeza">
|
||||
O doctor detecta serviços legados do Gateway (launchd/systemd/schtasks) e oferece removê-los e instalar o serviço OpenClaw usando a porta atual do Gateway. Ele também pode procurar serviços extras semelhantes ao Gateway e imprimir dicas de limpeza. Serviços do Gateway do OpenClaw nomeados por perfil são considerados de primeira classe e não são sinalizados como "extras".
|
||||
|
||||
No Linux, se o serviço Gateway em nível de usuário estiver ausente, mas existir um serviço Gateway do OpenClaw em nível de sistema, o doctor não instala automaticamente um segundo serviço em nível de usuário. Inspecione com `openclaw gateway status --deep` ou `openclaw doctor --deep`, depois remova a duplicata ou defina `OPENCLAW_SERVICE_REPAIR_POLICY=external` quando um supervisor do sistema for dono do ciclo de vida do Gateway.
|
||||
No Linux, se o serviço de Gateway em nível de usuário estiver ausente, mas existir um serviço de Gateway do OpenClaw em nível de sistema, o doctor não instala automaticamente um segundo serviço em nível de usuário. Inspecione com `openclaw gateway status --deep` ou `openclaw doctor --deep` e, em seguida, remova a duplicata ou defina `OPENCLAW_SERVICE_REPAIR_POLICY=external` quando um supervisor de sistema for responsável pelo ciclo de vida do Gateway.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="8b. Migração de inicialização do Matrix">
|
||||
Quando uma conta de canal Matrix tem uma migração de estado legado pendente ou acionável, o doctor (no modo `--fix` / `--repair`) cria um snapshot pré-migração e então executa as etapas de migração de melhor esforço: migração de estado legado do Matrix e preparação de estado criptografado legado. Ambas as etapas não são fatais; erros são registrados e a inicialização continua. No modo somente leitura (`openclaw doctor` sem `--fix`), essa verificação é totalmente ignorada.
|
||||
</Accordion>
|
||||
<Accordion title="8c. Pareamento de dispositivo e desvio de autenticação">
|
||||
O doctor agora inspeciona o estado de pareamento de dispositivos como parte da passagem normal de integridade.
|
||||
O doctor agora inspeciona o estado de pareamento de dispositivos como parte da passagem normal de saúde.
|
||||
|
||||
O que ele informa:
|
||||
O que ele relata:
|
||||
|
||||
- solicitações pendentes de primeiro pareamento
|
||||
- solicitações de pareamento inicial pendentes
|
||||
- upgrades de função pendentes para dispositivos já pareados
|
||||
- upgrades de escopo pendentes para dispositivos já pareados
|
||||
- reparos de incompatibilidade de chave pública quando o id do dispositivo ainda corresponde, mas a identidade do dispositivo não corresponde mais ao registro aprovado
|
||||
- reparos de incompatibilidade de chave pública em que o ID do dispositivo ainda corresponde, mas a identidade do dispositivo não corresponde mais ao registro aprovado
|
||||
- registros pareados sem um token ativo para uma função aprovada
|
||||
- tokens pareados cujos escopos desviam para fora da linha de base de pareamento aprovada
|
||||
- entradas locais em cache de token de dispositivo para a máquina atual anteriores a uma rotação de token no lado do Gateway ou com metadados de escopo obsoletos
|
||||
- tokens pareados cujos escopos se desviaram da linha de base de pareamento aprovada
|
||||
- entradas locais em cache de token de dispositivo para a máquina atual que são anteriores a uma rotação de token no lado do Gateway ou carregam metadados de escopo obsoletos
|
||||
|
||||
O doctor não aprova automaticamente solicitações de pareamento nem rotaciona automaticamente tokens de dispositivo. Em vez disso, ele imprime as próximas etapas exatas:
|
||||
|
||||
- inspecione solicitações pendentes com `openclaw devices list`
|
||||
- aprove a solicitação exata com `openclaw devices approve <requestId>`
|
||||
- rotacione um token novo com `openclaw devices rotate --device <deviceId> --role <role>`
|
||||
- remova e aprove novamente um registro obsoleto com `openclaw devices remove <deviceId>`
|
||||
- remova e reaprove um registro obsoleto com `openclaw devices remove <deviceId>`
|
||||
|
||||
Isso fecha a lacuna comum de "já pareado, mas ainda recebendo pareamento necessário": o doctor agora distingue primeiro pareamento de upgrades pendentes de função/escopo e de desvio obsoleto de token/identidade do dispositivo.
|
||||
Isso fecha a lacuna comum de "já pareado, mas ainda recebendo pareamento necessário": agora o doctor distingue pareamento inicial de upgrades pendentes de função/escopo e de desvio de token/identidade do dispositivo obsoleto.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="9. Avisos de segurança">
|
||||
O doctor emite avisos quando um provedor está aberto a DMs sem uma allowlist, ou quando uma política está configurada de forma perigosa.
|
||||
O doctor emite avisos quando um provedor está aberto a DMs sem uma lista de permissão, ou quando uma política está configurada de forma perigosa.
|
||||
</Accordion>
|
||||
<Accordion title="10. systemd linger (Linux)">
|
||||
Se estiver em execução como um serviço de usuário systemd, o doctor garante que o lingering esteja ativado para que o Gateway permaneça ativo após o logout.
|
||||
<Accordion title="10. Linger do systemd (Linux)">
|
||||
Se estiver em execução como um serviço de usuário do systemd, o doctor garante que o linger esteja habilitado para que o Gateway permaneça ativo após o logout.
|
||||
</Accordion>
|
||||
<Accordion title="11. Status do workspace (skills, plugins e diretórios legados)">
|
||||
O doctor imprime um resumo do estado do workspace para o agente padrão:
|
||||
|
||||
- **Status de Skills**: conta Skills elegíveis, com requisitos ausentes e bloqueadas por allowlist.
|
||||
- **Diretórios legados do workspace**: avisa quando `~/openclaw` ou outros diretórios legados de workspace existem ao lado do workspace atual.
|
||||
- **Status de Plugin**: conta plugins ativados/desativados/com erro; lista IDs de plugin para quaisquer erros; informa capacidades de plugins incluídos.
|
||||
- **Avisos de compatibilidade de Plugin**: sinaliza plugins com problemas de compatibilidade com o runtime atual.
|
||||
- **Status das Skills**: conta Skills elegíveis, com requisitos ausentes e bloqueadas pela lista de permissão.
|
||||
- **Diretórios legados do workspace**: avisa quando `~/openclaw` ou outros diretórios legados do workspace existem junto ao workspace atual.
|
||||
- **Status de Plugin**: conta plugins habilitados/desabilitados/com erro; lista IDs de plugins para quaisquer erros; relata capacidades de plugins de pacote.
|
||||
- **Avisos de compatibilidade de Plugin**: sinaliza plugins que têm problemas de compatibilidade com o runtime atual.
|
||||
- **Diagnósticos de Plugin**: expõe quaisquer avisos ou erros em tempo de carregamento emitidos pelo registro de plugins.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="11b. Tamanho do arquivo de bootstrap">
|
||||
O doctor verifica se os arquivos de bootstrap do workspace (por exemplo, `AGENTS.md`, `CLAUDE.md` ou outros arquivos de contexto injetados) estão perto ou acima do orçamento de caracteres configurado. Ele informa contagens de caracteres brutas vs. injetadas por arquivo, porcentagem de truncamento, causa do truncamento (`max/file` ou `max/total`) e total de caracteres injetados como fração do orçamento total. Quando arquivos são truncados ou estão perto do limite, o doctor imprime dicas para ajustar `agents.defaults.bootstrapMaxChars` e `agents.defaults.bootstrapTotalMaxChars`.
|
||||
O doctor verifica se os arquivos de bootstrap do workspace (por exemplo, `AGENTS.md`, `CLAUDE.md` ou outros arquivos de contexto injetados) estão próximos ou acima do orçamento de caracteres configurado. Ele relata, por arquivo, contagens de caracteres brutos vs. injetados, percentual de truncamento, causa do truncamento (`max/file` ou `max/total`) e o total de caracteres injetados como uma fração do orçamento total. Quando os arquivos são truncados ou estão próximos do limite, o doctor imprime dicas para ajustar `agents.defaults.bootstrapMaxChars` e `agents.defaults.bootstrapTotalMaxChars`.
|
||||
</Accordion>
|
||||
<Accordion title="11d. Limpeza de plugin de canal obsoleto">
|
||||
Quando `openclaw doctor --fix` remove um plugin de canal ausente, ele também remove a configuração pendente no escopo do canal que referenciava esse plugin: entradas `channels.<id>`, alvos de Heartbeat que nomeavam o canal e substituições `agents.*.models["<channel>/*"]`. Isso evita loops de inicialização do Gateway em que o runtime do canal se foi, mas a configuração ainda pede que o Gateway se vincule a ele.
|
||||
<Accordion title="11d. Limpeza de Plugin de canal obsoleto">
|
||||
Quando `openclaw doctor --fix` remove um Plugin de canal ausente, ele também remove a configuração pendente com escopo de canal que referenciava esse Plugin: entradas `channels.<id>`, destinos de Heartbeat que nomeavam o canal e substituições de `agents.*.models["<channel>/*"]`. Isso evita loops de inicialização do Gateway em que o runtime do canal desapareceu, mas a configuração ainda solicita que o Gateway se vincule a ele.
|
||||
</Accordion>
|
||||
<Accordion title="11c. Conclusão de shell">
|
||||
O doctor verifica se a conclusão por tab está instalada para o shell atual (zsh, bash, fish ou PowerShell):
|
||||
<Accordion title="11c. Completação do shell">
|
||||
O doctor verifica se a completação por tab está instalada para o shell atual (zsh, bash, fish ou PowerShell):
|
||||
|
||||
- Se o perfil de shell usa um padrão lento de conclusão dinâmica (`source <(openclaw completion ...)`), o doctor o atualiza para a variante mais rápida de arquivo em cache.
|
||||
- Se a conclusão está configurada no perfil, mas o arquivo de cache está ausente, o doctor regenera o cache automaticamente.
|
||||
- Se nenhuma conclusão estiver configurada, o doctor solicita instalá-la (apenas modo interativo; ignorado com `--non-interactive`).
|
||||
- Se o perfil do shell usa um padrão lento de completação dinâmica (`source <(openclaw completion ...)`), o doctor o atualiza para a variante mais rápida de arquivo em cache.
|
||||
- Se a completação está configurada no perfil, mas o arquivo de cache está ausente, o doctor regenera o cache automaticamente.
|
||||
- Se nenhuma completação está configurada, o doctor solicita a instalação (somente modo interativo; ignorado com `--non-interactive`).
|
||||
|
||||
Execute `openclaw completion --write-state` para regenerar o cache manualmente.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="12. Verificações de autenticação do Gateway (token local)">
|
||||
O doctor verifica a prontidão da autenticação por token local do Gateway.
|
||||
O doctor verifica a prontidão da autenticação por token do gateway local.
|
||||
|
||||
- Se o modo de token precisa de um token e nenhuma fonte de token existe, o doctor oferece gerar um.
|
||||
- Se `gateway.auth.token` é gerenciado por SecretRef, mas está indisponível, o doctor avisa e não o sobrescreve com texto simples.
|
||||
- `openclaw doctor --generate-gateway-token` força a geração apenas quando nenhum SecretRef de token está configurado.
|
||||
- Se `gateway.auth.token` é gerenciado por SecretRef, mas está indisponível, o doctor avisa e não o substitui por texto simples.
|
||||
- `openclaw doctor --generate-gateway-token` força a geração somente quando nenhum SecretRef de token está configurado.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="12b. Reparos somente leitura cientes de SecretRef">
|
||||
Alguns fluxos de reparo precisam inspecionar credenciais configuradas sem enfraquecer o comportamento fail-fast do runtime.
|
||||
|
||||
- `openclaw doctor --fix` agora usa o mesmo modelo de resumo SecretRef somente leitura que os comandos da família de status para reparos direcionados de configuração.
|
||||
- Exemplo: o reparo de `allowFrom` / `groupAllowFrom` `@username` do Telegram tenta usar credenciais configuradas do bot quando disponíveis.
|
||||
- Se o token do bot Telegram estiver configurado via SecretRef, mas indisponível no caminho de comando atual, o doctor informa que a credencial está configurada, mas indisponível, e ignora a resolução automática em vez de falhar ou informar incorretamente o token como ausente.
|
||||
- `openclaw doctor --fix` agora usa o mesmo modelo de resumo SecretRef somente leitura dos comandos da família de status para reparos de configuração direcionados.
|
||||
- Exemplo: o reparo de `allowFrom` / `groupAllowFrom` `@username` do Telegram tenta usar credenciais de bot configuradas quando disponíveis.
|
||||
- Se o token do bot do Telegram estiver configurado via SecretRef, mas indisponível no caminho de comando atual, o doctor relata que a credencial está configurada, mas indisponível, e ignora a resolução automática em vez de travar ou relatar incorretamente o token como ausente.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="13. Verificação de integridade do Gateway + reinício">
|
||||
O diagnóstico executa uma verificação de integridade e oferece reiniciar o Gateway quando ele parece não estar saudável.
|
||||
<Accordion title="13. Verificação de integridade do Gateway + reinicialização">
|
||||
O Doctor executa uma verificação de integridade e oferece reiniciar o Gateway quando ele parece não estar saudável.
|
||||
</Accordion>
|
||||
<Accordion title="13b. Prontidão da busca de memória">
|
||||
O diagnóstico verifica se o provedor configurado de embeddings para busca de memória está pronto para o agente padrão. O comportamento depende do backend e do provedor configurados:
|
||||
O Doctor verifica se o provedor de embeddings de busca de memória configurado está pronto para o agente padrão. O comportamento depende do backend e do provedor configurados:
|
||||
|
||||
- **Backend QMD**: verifica se o binário `qmd` está disponível e pode ser iniciado. Caso contrário, imprime orientações de correção, incluindo o pacote npm e uma opção de caminho manual para o binário.
|
||||
- **Provedor local explícito**: verifica se há um arquivo de modelo local ou uma URL reconhecida de modelo remoto/baixável. Se estiver ausente, sugere mudar para um provedor remoto.
|
||||
- **Provedor remoto explícito** (`openai`, `voyage`, etc.): verifica se há uma chave de API presente no ambiente ou no armazenamento de autenticação. Imprime dicas de correção acionáveis se estiver ausente.
|
||||
- **Backend QMD**: verifica se o binário `qmd` está disponível e pode ser iniciado. Caso contrário, imprime orientações de correção incluindo o pacote npm e uma opção de caminho manual para o binário.
|
||||
- **Provedor local explícito**: verifica se há um arquivo de modelo local ou uma URL de modelo remoto/baixável reconhecida. Se estiver ausente, sugere mudar para um provedor remoto.
|
||||
- **Provedor remoto explícito** (`openai`, `voyage` etc.): verifica se uma chave de API está presente no ambiente ou no armazenamento de autenticação. Imprime dicas de correção acionáveis se estiver ausente.
|
||||
- **Provedor automático**: verifica primeiro a disponibilidade do modelo local e depois tenta cada provedor remoto na ordem de seleção automática.
|
||||
|
||||
Quando um resultado de sondagem do Gateway em cache está disponível (o Gateway estava saudável no momento da verificação), o diagnóstico cruza seu resultado com a configuração visível pela CLI e observa qualquer discrepância. O diagnóstico não inicia um novo ping de embedding no caminho padrão; use o comando profundo de status de memória quando quiser uma verificação ao vivo do provedor.
|
||||
Quando há um resultado de sondagem do Gateway em cache disponível (o Gateway estava íntegro no momento da verificação), o Doctor cruza seu resultado com a configuração visível pela CLI e observa qualquer discrepância. O Doctor não inicia um novo ping de embedding no caminho padrão; use o comando de status profundo da memória quando quiser uma verificação ao vivo do provedor.
|
||||
|
||||
Use `openclaw memory status --deep` para verificar a prontidão de embeddings em tempo de execução.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="14. Avisos de status de canais">
|
||||
Se o Gateway estiver saudável, o diagnóstico executa uma sondagem de status de canal e relata avisos com correções sugeridas.
|
||||
<Accordion title="14. Avisos de status de canal">
|
||||
Se o Gateway estiver íntegro, o Doctor executa uma sondagem de status de canal e relata avisos com correções sugeridas.
|
||||
</Accordion>
|
||||
<Accordion title="15. Auditoria + reparo da configuração do supervisor">
|
||||
O diagnóstico verifica a configuração instalada do supervisor (launchd/systemd/schtasks) em busca de padrões ausentes ou desatualizados (por exemplo, dependências systemd network-online e atraso de reinício). Quando encontra uma incompatibilidade, recomenda uma atualização e pode reescrever o arquivo de serviço/tarefa para os padrões atuais.
|
||||
O Doctor verifica a configuração do supervisor instalada (launchd/systemd/schtasks) em busca de padrões ausentes ou desatualizados (por exemplo, dependências `network-online` do systemd e atraso de reinicialização). Quando encontra uma incompatibilidade, ele recomenda uma atualização e pode reescrever o arquivo de serviço/tarefa para os padrões atuais.
|
||||
|
||||
Observações:
|
||||
|
||||
- `openclaw doctor` solicita confirmação antes de reescrever a configuração do supervisor.
|
||||
- `openclaw doctor --yes` aceita os prompts de reparo padrão.
|
||||
- `openclaw doctor --repair` aplica as correções recomendadas sem prompts.
|
||||
- `openclaw doctor --yes` aceita as solicitações de reparo padrão.
|
||||
- `openclaw doctor --repair` aplica as correções recomendadas sem solicitações.
|
||||
- `openclaw doctor --repair --force` sobrescreve configurações personalizadas do supervisor.
|
||||
- `OPENCLAW_SERVICE_REPAIR_POLICY=external` mantém o diagnóstico somente leitura para o ciclo de vida do serviço do Gateway. Ele ainda relata a integridade do serviço e executa reparos não relacionados ao serviço, mas ignora instalação/inicialização/reinicialização/bootstrap do serviço, reescritas da configuração do supervisor e limpeza de serviço legado porque um supervisor externo controla esse ciclo de vida.
|
||||
- No Linux, o diagnóstico não reescreve metadados de comando/ponto de entrada enquanto a unidade systemd correspondente do Gateway está ativa. Ele também ignora unidades extras inativas não legadas semelhantes ao Gateway durante a varredura de serviços duplicados, para que arquivos de serviço auxiliares não gerem ruído de limpeza.
|
||||
- Se a autenticação por token exigir um token e `gateway.auth.token` for gerenciado por SecretRef, a instalação/reparo do serviço pelo diagnóstico valida o SecretRef, mas não persiste valores de token em texto puro resolvidos nos metadados de ambiente do serviço do supervisor.
|
||||
- O diagnóstico detecta valores de ambiente de serviço gerenciado por `.env`/SecretRef que instalações antigas de LaunchAgent, systemd ou Tarefa Agendada do Windows incorporaram inline e reescreve os metadados do serviço para que esses valores sejam carregados da fonte de runtime em vez da definição do supervisor.
|
||||
- O diagnóstico detecta quando o comando de serviço ainda fixa um `--port` antigo depois que `gateway.port` muda e reescreve os metadados do serviço para a porta atual.
|
||||
- Se a autenticação por token exigir um token e o SecretRef de token configurado não puder ser resolvido, o diagnóstico bloqueia o caminho de instalação/reparo com orientações acionáveis.
|
||||
- Se tanto `gateway.auth.token` quanto `gateway.auth.password` estiverem configurados e `gateway.auth.mode` não estiver definido, o diagnóstico bloqueia a instalação/reparo até que o modo seja definido explicitamente.
|
||||
- Para unidades systemd de usuário no Linux, as verificações de divergência de token do diagnóstico agora incluem fontes `Environment=` e `EnvironmentFile=` ao comparar metadados de autenticação do serviço.
|
||||
- Os reparos de serviço do diagnóstico se recusam a reescrever, parar ou reiniciar um serviço de Gateway a partir de um binário OpenClaw mais antigo quando a configuração foi gravada pela última vez por uma versão mais nova. Consulte [Solução de problemas do Gateway](/pt-BR/gateway/troubleshooting#split-brain-installs-and-newer-config-guard).
|
||||
- `OPENCLAW_SERVICE_REPAIR_POLICY=external` mantém o Doctor somente leitura para o ciclo de vida do serviço do Gateway. Ele ainda relata a integridade do serviço e executa reparos que não são de serviço, mas ignora instalação/início/reinício/bootstrap do serviço, reescritas da configuração do supervisor e limpeza de serviço legado porque um supervisor externo é dono desse ciclo de vida.
|
||||
- No Linux, o Doctor não reescreve metadados de comando/entrypoint enquanto a unidade systemd correspondente do Gateway estiver ativa. Ele também ignora unidades extras inativas semelhantes ao Gateway que não sejam legadas durante a varredura de serviços duplicados, para que arquivos de serviço auxiliares não gerem ruído de limpeza.
|
||||
- Se a autenticação por token exigir um token e `gateway.auth.token` for gerenciado por SecretRef, a instalação/reparo do serviço pelo Doctor valida o SecretRef, mas não persiste valores de token em texto simples resolvidos nos metadados de ambiente do serviço do supervisor.
|
||||
- O Doctor detecta valores de ambiente de serviço gerenciados com suporte em `.env`/SecretRef que instalações antigas de LaunchAgent, systemd ou Tarefa Agendada do Windows incorporaram inline e reescreve os metadados do serviço para que esses valores sejam carregados da origem de tempo de execução em vez da definição do supervisor.
|
||||
- O Doctor detecta quando o comando de serviço ainda fixa uma `--port` antiga após alterações em `gateway.port` e reescreve os metadados do serviço para a porta atual.
|
||||
- Se a autenticação por token exigir um token e o SecretRef de token configurado não puder ser resolvido, o Doctor bloqueia o caminho de instalação/reparo com orientação acionável.
|
||||
- Se `gateway.auth.token` e `gateway.auth.password` estiverem configurados e `gateway.auth.mode` não estiver definido, o Doctor bloqueia instalação/reparo até que o modo seja definido explicitamente.
|
||||
- Para unidades user-systemd no Linux, as verificações de divergência de token do Doctor agora incluem fontes `Environment=` e `EnvironmentFile=` ao comparar metadados de autenticação do serviço.
|
||||
- Reparos de serviço pelo Doctor se recusam a reescrever, interromper ou reiniciar um serviço de Gateway de um binário OpenClaw mais antigo quando a configuração foi gravada pela última vez por uma versão mais nova. Consulte [Solução de problemas do Gateway](/pt-BR/gateway/troubleshooting#split-brain-installs-and-newer-config-guard).
|
||||
- Você sempre pode forçar uma reescrita completa via `openclaw gateway install --force`.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="16. Diagnósticos de runtime + porta do Gateway">
|
||||
O diagnóstico inspeciona o runtime do serviço (PID, último status de saída) e avisa quando o serviço está instalado, mas não está realmente em execução. Ele também verifica colisões de porta na porta do Gateway (padrão `18789`) e relata causas prováveis (Gateway já em execução, túnel SSH).
|
||||
<Accordion title="16. Diagnósticos de tempo de execução + porta do Gateway">
|
||||
O Doctor inspeciona o tempo de execução do serviço (PID, último status de saída) e avisa quando o serviço está instalado, mas não está realmente em execução. Ele também verifica colisões de porta na porta do Gateway (padrão `18789`) e relata causas prováveis (Gateway já em execução, túnel SSH).
|
||||
</Accordion>
|
||||
<Accordion title="17. Boas práticas de runtime do Gateway">
|
||||
O diagnóstico avisa quando o serviço do Gateway é executado no Bun ou em um caminho de Node gerenciado por versão (`nvm`, `fnm`, `volta`, `asdf`, etc.). Os canais WhatsApp + Telegram exigem Node, e caminhos de gerenciadores de versão podem quebrar após atualizações porque o serviço não carrega a inicialização do seu shell. O diagnóstico oferece migrar para uma instalação de Node do sistema quando disponível (Homebrew/apt/choco).
|
||||
<Accordion title="17. Boas práticas de tempo de execução do Gateway">
|
||||
O Doctor avisa quando o serviço do Gateway é executado no Bun ou em um caminho do Node gerenciado por versão (`nvm`, `fnm`, `volta`, `asdf` etc.). Os canais WhatsApp + Telegram exigem Node, e caminhos de gerenciadores de versão podem quebrar após upgrades porque o serviço não carrega a inicialização do seu shell. O Doctor oferece migrar para uma instalação do Node do sistema quando disponível (Homebrew/apt/choco).
|
||||
|
||||
LaunchAgents do macOS recém-instalados ou reparados usam um PATH de sistema canônico (`/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`) em vez de copiar o PATH do shell interativo, para que Volta, asdf, fnm, pnpm e outros diretórios de gerenciadores de versão não alterem qual Node os processos filhos resolvem. Serviços Linux ainda mantêm raízes de ambiente explícitas (`NVM_DIR`, `FNM_DIR`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `BUN_INSTALL`, `PNPM_HOME`) e diretórios user-bin estáveis, mas diretórios de fallback inferidos de gerenciadores de versão só são gravados no PATH do serviço quando esses diretórios existem no disco.
|
||||
LaunchAgents do macOS recém-instalados ou reparados usam um PATH canônico do sistema (`/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`) em vez de copiar o PATH do shell interativo, de modo que Volta, asdf, fnm, pnpm e outros diretórios de gerenciadores de versão não alterem qual Node os processos filhos resolvem. Serviços Linux ainda mantêm raízes de ambiente explícitas (`NVM_DIR`, `FNM_DIR`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `BUN_INSTALL`, `PNPM_HOME`) e diretórios user-bin estáveis, mas diretórios fallback presumidos de gerenciadores de versão só são gravados no PATH do serviço quando esses diretórios existem no disco.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="18. Gravação de configuração + metadados do assistente">
|
||||
O diagnóstico persiste quaisquer alterações de configuração e registra metadados do assistente para registrar a execução do diagnóstico.
|
||||
O Doctor persiste quaisquer alterações de configuração e carimba metadados do assistente para registrar a execução do Doctor.
|
||||
</Accordion>
|
||||
<Accordion title="19. Dicas de workspace (backup + sistema de memória)">
|
||||
O diagnóstico sugere um sistema de memória de workspace quando ausente e imprime uma dica de backup se o workspace ainda não estiver sob git.
|
||||
O Doctor sugere um sistema de memória do workspace quando ausente e imprime uma dica de backup se o workspace ainda não estiver sob git.
|
||||
|
||||
Consulte [/concepts/agent-workspace](/pt-BR/concepts/agent-workspace) para um guia completo sobre estrutura de workspace e backup com git (GitHub ou GitLab privado recomendado).
|
||||
Consulte [/concepts/agent-workspace](/pt-BR/concepts/agent-workspace) para um guia completo sobre a estrutura do workspace e backup com git (GitHub ou GitLab privado recomendado).
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@ -1,20 +1,20 @@
|
||||
---
|
||||
read_when:
|
||||
- Você está decidindo se um Plugin é distribuído no pacote npm principal ou instalado separadamente
|
||||
- Você está atualizando os metadados do pacote de Plugin incluído ou a automação de lançamento
|
||||
- Você está decidindo se um plugin é distribuído no pacote npm principal ou instalado separadamente
|
||||
- Você está atualizando metadados de pacote de Plugin incluído ou automação de lançamento
|
||||
- Você precisa da lista canônica de Plugins internos versus externos
|
||||
summary: Inventário gerado de plugins do OpenClaw enviados no core, publicados externamente ou mantidos apenas como código-fonte
|
||||
summary: Inventário gerado de Plugins do OpenClaw incluídos no núcleo, publicados externamente ou mantidos apenas como código-fonte
|
||||
title: Inventário de Plugin
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T05:51:20Z"
|
||||
generated_at: "2026-05-04T09:37:11Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 2099d8a67847f54040db332287708a1f79aa6c08e6e33125425389fe962865cb
|
||||
source_hash: 64f3d27ae65faacf89deeaad1b456318fa72993fdcf16262f30fb3f48b898024
|
||||
source_path: plugins/plugin-inventory.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
# Inventário de Plugin
|
||||
# Inventário de Plugins
|
||||
|
||||
Esta página é gerada a partir de `extensions/*/package.json`, `openclaw.plugin.json`,
|
||||
e das exclusões de `files` do pacote npm raiz. Regere-a com:
|
||||
@ -25,102 +25,122 @@ pnpm plugins:inventory:gen
|
||||
|
||||
## Definições
|
||||
|
||||
- **Pacote npm principal:** integrado ao pacote npm `openclaw` e disponível sem uma instalação separada de Plugin.
|
||||
- **Pacote npm principal:** incorporado ao pacote npm `openclaw` e disponível sem uma instalação separada de Plugin.
|
||||
- **Pacote externo oficial:** Plugin mantido pela OpenClaw omitido do pacote npm principal, mantido neste inventário oficial e instalado sob demanda pelo ClawHub e/ou npm.
|
||||
- **Apenas checkout do código-fonte:** Plugin local do repositório omitido dos artefatos npm publicados e não anunciado como pacote instalável.
|
||||
- **Apenas checkout de código-fonte:** Plugin local do repositório omitido dos artefatos npm publicados e não divulgado como pacote instalável.
|
||||
|
||||
Checkouts do código-fonte são diferentes de instalações npm: após `pnpm install`, Plugins
|
||||
incluídos são carregados de `extensions/<id>`, portanto edições locais e dependências
|
||||
de workspace locais do pacote ficam disponíveis.
|
||||
Checkouts de código-fonte são diferentes de instalações npm: após `pnpm install`, Plugins
|
||||
incluídos carregam de `extensions/<id>`, então edições locais e dependências do
|
||||
workspace locais do pacote ficam disponíveis.
|
||||
|
||||
## Instalar um Plugin
|
||||
|
||||
Use a coluna **Distribuição** para decidir se a instalação é necessária. Plugins que
|
||||
dizem `included in OpenClaw` já estão presentes no pacote principal. Pacotes
|
||||
externos oficiais precisam de uma instalação e, depois, de uma reinicialização do Gateway.
|
||||
|
||||
Por exemplo, Discord é um pacote externo oficial:
|
||||
|
||||
```bash
|
||||
openclaw plugins install @openclaw/discord
|
||||
openclaw gateway restart
|
||||
openclaw plugins inspect discord --runtime --json
|
||||
```
|
||||
|
||||
Especificações de pacote simples tentam o ClawHub primeiro e, em seguida, usam npm como fallback. Para forçar uma fonte, use
|
||||
`clawhub:@openclaw/discord` ou `npm:@openclaw/discord`. Após a instalação, siga
|
||||
o documento de configuração do Plugin, como [Discord](/pt-BR/channels/discord), para adicionar credenciais
|
||||
e configuração do canal. Consulte [Gerenciar Plugins](/pt-BR/plugins/manage-plugins) para comandos de atualização,
|
||||
desinstalação e publicação.
|
||||
|
||||
## Pacote npm principal
|
||||
|
||||
| Plugin | Descrição | Distribuição | Superfície |
|
||||
| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| [alibaba](/pt-BR/plugins/reference/alibaba) | Adiciona suporte a provedor de geração de vídeo. | `@openclaw/alibaba-provider`<br />incluído no OpenClaw | contracts: videoGenerationProviders |
|
||||
| [amazon-bedrock](/pt-BR/plugins/reference/amazon-bedrock) | Adiciona suporte ao provedor de modelos Amazon Bedrock ao OpenClaw. | `@openclaw/amazon-bedrock-provider`<br />incluído no OpenClaw | providers: amazon-bedrock; contracts: memoryEmbeddingProviders |
|
||||
| [amazon-bedrock-mantle](/pt-BR/plugins/reference/amazon-bedrock-mantle) | Adiciona suporte ao provedor de modelos Amazon Bedrock Mantle ao OpenClaw. | `@openclaw/amazon-bedrock-mantle-provider`<br />incluído no OpenClaw | providers: amazon-bedrock-mantle |
|
||||
| [anthropic](/pt-BR/plugins/reference/anthropic) | Adiciona suporte ao provedor de modelos Anthropic ao OpenClaw. | `@openclaw/anthropic-provider`<br />incluído no OpenClaw | providers: anthropic; contracts: mediaUnderstandingProviders |
|
||||
| [anthropic-vertex](/pt-BR/plugins/reference/anthropic-vertex) | Adiciona suporte ao provedor de modelos Anthropic Vertex ao OpenClaw. | `@openclaw/anthropic-vertex-provider`<br />incluído no OpenClaw | providers: anthropic-vertex |
|
||||
| [arcee](/pt-BR/plugins/reference/arcee) | Adiciona suporte ao provedor de modelos Arcee ao OpenClaw. | `@openclaw/arcee-provider`<br />incluído no OpenClaw | providers: arcee |
|
||||
| [azure-speech](/pt-BR/plugins/reference/azure-speech) | Texto para fala do Azure AI Speech (MP3, notas de voz nativas em Ogg/Opus, telefonia PCM). | `@openclaw/azure-speech`<br />incluído no OpenClaw | contracts: speechProviders |
|
||||
| [bonjour](/pt-BR/plugins/reference/bonjour) | Anuncia o Gateway local do OpenClaw via Bonjour/mDNS. | `@openclaw/bonjour`<br />incluído no OpenClaw | plugin |
|
||||
| [browser](/pt-BR/plugins/reference/browser) | Adiciona ferramentas que podem ser chamadas por agentes. | `@openclaw/browser-plugin`<br />incluído no OpenClaw | contracts: tools; skills |
|
||||
| [byteplus](/pt-BR/plugins/reference/byteplus) | Adiciona suporte aos provedores de modelos BytePlus e BytePlus Plan ao OpenClaw. | `@openclaw/byteplus-provider`<br />incluído no OpenClaw | providers: byteplus, byteplus-plan; contracts: videoGenerationProviders |
|
||||
| [cerebras](/pt-BR/plugins/reference/cerebras) | Adiciona suporte ao provedor de modelos Cerebras ao OpenClaw. | `@openclaw/cerebras-provider`<br />incluído no OpenClaw | providers: cerebras |
|
||||
| [chutes](/pt-BR/plugins/reference/chutes) | Adiciona suporte ao provedor de modelos Chutes ao OpenClaw. | `@openclaw/chutes-provider`<br />incluído no OpenClaw | providers: chutes |
|
||||
| [cloudflare-ai-gateway](/pt-BR/plugins/reference/cloudflare-ai-gateway) | Adiciona suporte ao provedor de modelos Cloudflare AI Gateway ao OpenClaw. | `@openclaw/cloudflare-ai-gateway-provider`<br />incluído no OpenClaw | providers: cloudflare-ai-gateway |
|
||||
| [comfy](/pt-BR/plugins/reference/comfy) | Adiciona suporte ao provedor de modelos ComfyUI ao OpenClaw. | `@openclaw/comfy-provider`<br />incluído no OpenClaw | providers: comfy; contracts: imageGenerationProviders, musicGenerationProviders, videoGenerationProviders |
|
||||
| [copilot-proxy](/pt-BR/plugins/reference/copilot-proxy) | Adiciona suporte ao provedor de modelos Copilot Proxy ao OpenClaw. | `@openclaw/copilot-proxy`<br />incluído no OpenClaw | providers: copilot-proxy |
|
||||
| [deepgram](/pt-BR/plugins/reference/deepgram) | Adiciona suporte a provedor de compreensão de mídia. Adiciona suporte a provedor de transcrição em tempo real. | `@openclaw/deepgram-provider`<br />incluído no OpenClaw | contracts: mediaUnderstandingProviders, realtimeTranscriptionProviders |
|
||||
| [deepinfra](/pt-BR/plugins/reference/deepinfra) | Adiciona suporte ao provedor de modelos DeepInfra ao OpenClaw. | `@openclaw/deepinfra-provider`<br />incluído no OpenClaw | providers: deepinfra; contracts: imageGenerationProviders, mediaUnderstandingProviders, memoryEmbeddingProviders, speechProviders, videoGenerationProviders |
|
||||
| [deepseek](/pt-BR/plugins/reference/deepseek) | Adiciona suporte ao provedor de modelos DeepSeek ao OpenClaw. | `@openclaw/deepseek-provider`<br />incluído no OpenClaw | providers: deepseek |
|
||||
| [document-extract](/pt-BR/plugins/reference/document-extract) | Extrai texto e imagens de página alternativas de anexos de documentos locais. | `@openclaw/document-extract-plugin`<br />incluído no OpenClaw | contracts: documentExtractors |
|
||||
| [duckduckgo](/pt-BR/plugins/reference/duckduckgo) | Adiciona suporte a provedor de pesquisa na web. | `@openclaw/duckduckgo-plugin`<br />incluído no OpenClaw | contracts: webSearchProviders |
|
||||
| [elevenlabs](/pt-BR/plugins/reference/elevenlabs) | Adiciona suporte a provedor de compreensão de mídia. Adiciona suporte a provedor de transcrição em tempo real. Adiciona suporte a provedor de texto para fala. | `@openclaw/elevenlabs-speech`<br />incluído no OpenClaw | contracts: mediaUnderstandingProviders, realtimeTranscriptionProviders, speechProviders |
|
||||
| [exa](/pt-BR/plugins/reference/exa) | Adiciona suporte a provedor de pesquisa na web. | `@openclaw/exa-plugin`<br />incluído no OpenClaw | contracts: webSearchProviders |
|
||||
| [fal](/pt-BR/plugins/reference/fal) | Adiciona suporte ao provedor de modelos fal ao OpenClaw. | `@openclaw/fal-provider`<br />incluído no OpenClaw | providers: fal; contracts: imageGenerationProviders, videoGenerationProviders |
|
||||
| [file-transfer](/pt-BR/plugins/reference/file-transfer) | Busca, lista e grava arquivos em Nodes pareados por meio de comandos dedicados de Node. Contorna o truncamento de stdout do bash usando base64 via node.invoke para binários de até 16 MB. | `@openclaw/file-transfer`<br />incluído no OpenClaw | contracts: tools |
|
||||
| [firecrawl](/pt-BR/plugins/reference/firecrawl) | Adiciona ferramentas chamáveis por agente. Adiciona suporte a provedor de busca na web. Adiciona suporte a provedor de pesquisa na web. | `@openclaw/firecrawl-plugin`<br />incluído no OpenClaw | contracts: tools, webFetchProviders, webSearchProviders |
|
||||
| [fireworks](/pt-BR/plugins/reference/fireworks) | Adiciona suporte ao provedor de modelos Fireworks ao OpenClaw. | `@openclaw/fireworks-provider`<br />incluído no OpenClaw | providers: fireworks |
|
||||
| [github-copilot](/pt-BR/plugins/reference/github-copilot) | Adiciona suporte ao provedor de modelos GitHub Copilot ao OpenClaw. | `@openclaw/github-copilot-provider`<br />incluído no OpenClaw | providers: github-copilot; contracts: memoryEmbeddingProviders |
|
||||
| [google](/pt-BR/plugins/reference/google) | Adiciona suporte aos provedores de modelos Google, Google Gemini CLI e Google Vertex ao OpenClaw. | `@openclaw/google-plugin`<br />incluído no OpenClaw | providers: google, google-gemini-cli, google-vertex; contracts: imageGenerationProviders, mediaUnderstandingProviders, memoryEmbeddingProviders, musicGenerationProviders, realtimeVoiceProviders, speechProviders, videoGenerationProviders, webSearchProviders |
|
||||
| [gradium](/pt-BR/plugins/reference/gradium) | Adiciona suporte a provedor de texto para fala. | `@openclaw/gradium-speech`<br />incluído no OpenClaw | contracts: speechProviders |
|
||||
| [groq](/pt-BR/plugins/reference/groq) | Adiciona suporte ao provedor de modelos Groq ao OpenClaw. | `@openclaw/groq-provider`<br />incluído no OpenClaw | providers: groq; contracts: mediaUnderstandingProviders |
|
||||
| [huggingface](/pt-BR/plugins/reference/huggingface) | Adiciona suporte ao provedor de modelos Hugging Face ao OpenClaw. | `@openclaw/huggingface-provider`<br />incluído no OpenClaw | providers: huggingface |
|
||||
| [imessage](/pt-BR/plugins/reference/imessage) | Adiciona a superfície de canal do iMessage para enviar e receber mensagens do OpenClaw. | `@openclaw/imessage`<br />incluído no OpenClaw | channels: imessage |
|
||||
| [inworld](/pt-BR/plugins/reference/inworld) | Texto para fala por streaming da Inworld (MP3, OGG_OPUS, PCM telefônico). | `@openclaw/inworld-speech`<br />incluído no OpenClaw | contracts: speechProviders |
|
||||
| [irc](/pt-BR/plugins/reference/irc) | Adiciona a superfície de canal IRC para enviar e receber mensagens do OpenClaw. | `@openclaw/irc`<br />incluído no OpenClaw | channels: irc |
|
||||
| [kilocode](/pt-BR/plugins/reference/kilocode) | Adiciona suporte ao provedor de modelos Kilocode ao OpenClaw. | `@openclaw/kilocode-provider`<br />incluído no OpenClaw | providers: kilocode |
|
||||
| [kimi](/pt-BR/plugins/reference/kimi) | Adiciona suporte aos provedores de modelos Kimi e Kimi Coding ao OpenClaw. | `@openclaw/kimi-provider`<br />incluído no OpenClaw | providers: kimi, kimi-coding |
|
||||
| [litellm](/pt-BR/plugins/reference/litellm) | Adiciona suporte ao provedor de modelos LiteLLM ao OpenClaw. | `@openclaw/litellm-provider`<br />incluído no OpenClaw | providers: litellm; contracts: imageGenerationProviders |
|
||||
| [llm-task](/pt-BR/plugins/reference/llm-task) | Ferramenta LLM genérica somente JSON para tarefas estruturadas chamável a partir de workflows. | `@openclaw/llm-task`<br />incluído no OpenClaw | contracts: tools |
|
||||
| [lmstudio](/pt-BR/plugins/reference/lmstudio) | Adiciona suporte ao provedor de modelos LM Studio ao OpenClaw. | `@openclaw/lmstudio-provider`<br />incluído no OpenClaw | providers: lmstudio; contracts: memoryEmbeddingProviders |
|
||||
| [matrix](/pt-BR/plugins/reference/matrix) | Adiciona a superfície de canal Matrix para enviar e receber mensagens do OpenClaw. | `@openclaw/matrix`<br />incluído no OpenClaw | channels: matrix |
|
||||
| [mattermost](/pt-BR/plugins/reference/mattermost) | Adiciona a superfície do canal Mattermost para enviar e receber mensagens do OpenClaw. | `@openclaw/mattermost`<br />incluído no OpenClaw | channels: mattermost |
|
||||
| [memory-core](/pt-BR/plugins/reference/memory-core) | Adiciona suporte a provedores de embeddings de memória. Adiciona ferramentas chamáveis por agentes. | `@openclaw/memory-core`<br />incluído no OpenClaw | contracts: memoryEmbeddingProviders, tools |
|
||||
| [memory-wiki](/pt-BR/plugins/reference/memory-wiki) | Compilador de wiki persistente e cofre de conhecimento compatível com Obsidian para OpenClaw. | `@openclaw/memory-wiki`<br />incluído no OpenClaw | contracts: tools; skills |
|
||||
| Plugin | Descrição | Distribuição | Superfície |
|
||||
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| [alibaba](/pt-BR/plugins/reference/alibaba) | Adiciona suporte a provedores de geração de vídeo. | `@openclaw/alibaba-provider`<br />incluído no OpenClaw | contracts: videoGenerationProviders |
|
||||
| [amazon-bedrock](/pt-BR/plugins/reference/amazon-bedrock) | Adiciona ao OpenClaw suporte ao provedor de modelos Amazon Bedrock. | `@openclaw/amazon-bedrock-provider`<br />incluído no OpenClaw | providers: amazon-bedrock; contracts: memoryEmbeddingProviders |
|
||||
| [amazon-bedrock-mantle](/pt-BR/plugins/reference/amazon-bedrock-mantle) | Adiciona ao OpenClaw suporte ao provedor de modelos Amazon Bedrock Mantle. | `@openclaw/amazon-bedrock-mantle-provider`<br />incluído no OpenClaw | providers: amazon-bedrock-mantle |
|
||||
| [anthropic](/pt-BR/plugins/reference/anthropic) | Adiciona ao OpenClaw suporte ao provedor de modelos Anthropic. | `@openclaw/anthropic-provider`<br />incluído no OpenClaw | providers: anthropic; contracts: mediaUnderstandingProviders |
|
||||
| [anthropic-vertex](/pt-BR/plugins/reference/anthropic-vertex) | Adiciona ao OpenClaw suporte ao provedor de modelos Anthropic Vertex. | `@openclaw/anthropic-vertex-provider`<br />incluído no OpenClaw | providers: anthropic-vertex |
|
||||
| [arcee](/pt-BR/plugins/reference/arcee) | Adiciona ao OpenClaw suporte ao provedor de modelos Arcee. | `@openclaw/arcee-provider`<br />incluído no OpenClaw | providers: arcee |
|
||||
| [azure-speech](/pt-BR/plugins/reference/azure-speech) | Conversão de texto em fala do Azure AI Speech (MP3, notas de voz nativas em Ogg/Opus, telefonia PCM). | `@openclaw/azure-speech`<br />incluído no OpenClaw | contracts: speechProviders |
|
||||
| [bonjour](/pt-BR/plugins/reference/bonjour) | Anuncia o Gateway local do OpenClaw por Bonjour/mDNS. | `@openclaw/bonjour`<br />incluído no OpenClaw | plugin |
|
||||
| [browser](/pt-BR/plugins/reference/browser) | Adiciona ferramentas chamáveis pelo agente. | `@openclaw/browser-plugin`<br />incluído no OpenClaw | contracts: tools; skills |
|
||||
| [byteplus](/pt-BR/plugins/reference/byteplus) | Adiciona ao OpenClaw suporte aos provedores de modelos BytePlus e BytePlus Plan. | `@openclaw/byteplus-provider`<br />incluído no OpenClaw | providers: byteplus, byteplus-plan; contracts: videoGenerationProviders |
|
||||
| [cerebras](/pt-BR/plugins/reference/cerebras) | Adiciona ao OpenClaw suporte ao provedor de modelos Cerebras. | `@openclaw/cerebras-provider`<br />incluído no OpenClaw | providers: cerebras |
|
||||
| [chutes](/pt-BR/plugins/reference/chutes) | Adiciona ao OpenClaw suporte ao provedor de modelos Chutes. | `@openclaw/chutes-provider`<br />incluído no OpenClaw | providers: chutes |
|
||||
| [cloudflare-ai-gateway](/pt-BR/plugins/reference/cloudflare-ai-gateway) | Adiciona ao OpenClaw suporte ao provedor de modelos Cloudflare AI Gateway. | `@openclaw/cloudflare-ai-gateway-provider`<br />incluído no OpenClaw | providers: cloudflare-ai-gateway |
|
||||
| [comfy](/pt-BR/plugins/reference/comfy) | Adiciona ao OpenClaw suporte ao provedor de modelos ComfyUI. | `@openclaw/comfy-provider`<br />incluído no OpenClaw | providers: comfy; contracts: imageGenerationProviders, musicGenerationProviders, videoGenerationProviders |
|
||||
| [copilot-proxy](/pt-BR/plugins/reference/copilot-proxy) | Adiciona ao OpenClaw suporte ao provedor de modelos Copilot Proxy. | `@openclaw/copilot-proxy`<br />incluído no OpenClaw | providers: copilot-proxy |
|
||||
| [deepgram](/pt-BR/plugins/reference/deepgram) | Adiciona suporte a provedor de compreensão de mídia. Adiciona suporte a provedor de transcrição em tempo real. | `@openclaw/deepgram-provider`<br />incluído no OpenClaw | contracts: mediaUnderstandingProviders, realtimeTranscriptionProviders |
|
||||
| [deepinfra](/pt-BR/plugins/reference/deepinfra) | Adiciona ao OpenClaw suporte ao provedor de modelos DeepInfra. | `@openclaw/deepinfra-provider`<br />incluído no OpenClaw | providers: deepinfra; contracts: imageGenerationProviders, mediaUnderstandingProviders, memoryEmbeddingProviders, speechProviders, videoGenerationProviders |
|
||||
| [deepseek](/pt-BR/plugins/reference/deepseek) | Adiciona ao OpenClaw suporte ao provedor de modelos DeepSeek. | `@openclaw/deepseek-provider`<br />incluído no OpenClaw | providers: deepseek |
|
||||
| [document-extract](/pt-BR/plugins/reference/document-extract) | Extrai texto e imagens de páginas de fallback de anexos de documentos locais. | `@openclaw/document-extract-plugin`<br />incluído no OpenClaw | contracts: documentExtractors |
|
||||
| [duckduckgo](/pt-BR/plugins/reference/duckduckgo) | Adiciona suporte a provedor de pesquisa na web. | `@openclaw/duckduckgo-plugin`<br />incluído no OpenClaw | contracts: webSearchProviders |
|
||||
| [elevenlabs](/pt-BR/plugins/reference/elevenlabs) | Adiciona suporte a provedor de compreensão de mídia. Adiciona suporte a provedor de transcrição em tempo real. Adiciona suporte a provedor de conversão de texto em fala. | `@openclaw/elevenlabs-speech`<br />incluído no OpenClaw | contracts: mediaUnderstandingProviders, realtimeTranscriptionProviders, speechProviders |
|
||||
| [exa](/pt-BR/plugins/reference/exa) | Adiciona suporte a provedor de pesquisa na web. | `@openclaw/exa-plugin`<br />incluído no OpenClaw | contracts: webSearchProviders |
|
||||
| [fal](/pt-BR/plugins/reference/fal) | Adiciona suporte ao provedor de modelos fal no OpenClaw. | `@openclaw/fal-provider`<br />incluído no OpenClaw | providers: fal; contracts: imageGenerationProviders, videoGenerationProviders |
|
||||
| [file-transfer](/pt-BR/plugins/reference/file-transfer) | Busca, lista e grava arquivos em Nodes pareados por meio de comandos Node dedicados. Contorna o truncamento de stdout do bash usando base64 sobre node.invoke para binários de até 16 MB. | `@openclaw/file-transfer`<br />incluído no OpenClaw | contracts: tools |
|
||||
| [firecrawl](/pt-BR/plugins/reference/firecrawl) | Adiciona ferramentas que podem ser chamadas pelo agente. Adiciona suporte a provedor de busca na web. Adiciona suporte a provedor de pesquisa na web. | `@openclaw/firecrawl-plugin`<br />incluído no OpenClaw | contracts: tools, webFetchProviders, webSearchProviders |
|
||||
| [fireworks](/pt-BR/plugins/reference/fireworks) | Adiciona suporte ao provedor de modelos Fireworks no OpenClaw. | `@openclaw/fireworks-provider`<br />incluído no OpenClaw | providers: fireworks |
|
||||
| [github-copilot](/pt-BR/plugins/reference/github-copilot) | Adiciona suporte ao provedor de modelos GitHub Copilot no OpenClaw. | `@openclaw/github-copilot-provider`<br />incluído no OpenClaw | providers: github-copilot; contracts: memoryEmbeddingProviders |
|
||||
| [google](/pt-BR/plugins/reference/google) | Adiciona suporte aos provedores de modelos Google, Google Gemini CLI e Google Vertex no OpenClaw. | `@openclaw/google-plugin`<br />incluído no OpenClaw | providers: google, google-gemini-cli, google-vertex; contracts: imageGenerationProviders, mediaUnderstandingProviders, memoryEmbeddingProviders, musicGenerationProviders, realtimeVoiceProviders, speechProviders, videoGenerationProviders, webSearchProviders |
|
||||
| [gradium](/pt-BR/plugins/reference/gradium) | Adiciona suporte a provedor de conversão de texto em fala. | `@openclaw/gradium-speech`<br />incluído no OpenClaw | contracts: speechProviders |
|
||||
| [groq](/pt-BR/plugins/reference/groq) | Adiciona suporte ao provedor de modelos Groq no OpenClaw. | `@openclaw/groq-provider`<br />incluído no OpenClaw | providers: groq; contracts: mediaUnderstandingProviders |
|
||||
| [huggingface](/pt-BR/plugins/reference/huggingface) | Adiciona suporte ao provedor de modelos Hugging Face no OpenClaw. | `@openclaw/huggingface-provider`<br />incluído no OpenClaw | providers: huggingface |
|
||||
| [imessage](/pt-BR/plugins/reference/imessage) | Adiciona a superfície de canal do iMessage para enviar e receber mensagens do OpenClaw. | `@openclaw/imessage`<br />incluído no OpenClaw | channels: imessage |
|
||||
| [inworld](/pt-BR/plugins/reference/inworld) | Conversão de texto em fala por streaming da Inworld (MP3, OGG_OPUS, telefonia PCM). | `@openclaw/inworld-speech`<br />incluído no OpenClaw | contracts: speechProviders |
|
||||
| [irc](/pt-BR/plugins/reference/irc) | Adiciona a superfície de canal IRC para enviar e receber mensagens do OpenClaw. | `@openclaw/irc`<br />incluído no OpenClaw | channels: irc |
|
||||
| [kilocode](/pt-BR/plugins/reference/kilocode) | Adiciona suporte ao provedor de modelos Kilocode no OpenClaw. | `@openclaw/kilocode-provider`<br />incluído no OpenClaw | providers: kilocode |
|
||||
| [kimi](/pt-BR/plugins/reference/kimi) | Adiciona suporte aos provedores de modelos Kimi e Kimi Coding no OpenClaw. | `@openclaw/kimi-provider`<br />incluído no OpenClaw | providers: kimi, kimi-coding |
|
||||
| [litellm](/pt-BR/plugins/reference/litellm) | Adiciona suporte ao provedor de modelos LiteLLM no OpenClaw. | `@openclaw/litellm-provider`<br />incluído no OpenClaw | providers: litellm; contracts: imageGenerationProviders |
|
||||
| [llm-task](/pt-BR/plugins/reference/llm-task) | Ferramenta LLM genérica somente JSON para tarefas estruturadas que podem ser chamadas de fluxos de trabalho. | `@openclaw/llm-task`<br />incluído no OpenClaw | contracts: tools |
|
||||
| [lmstudio](/pt-BR/plugins/reference/lmstudio) | Adiciona suporte ao provedor de modelos LM Studio no OpenClaw. | `@openclaw/lmstudio-provider`<br />incluído no OpenClaw | providers: lmstudio; contracts: memoryEmbeddingProviders |
|
||||
| [matrix](/pt-BR/plugins/reference/matrix) | Adiciona a superfície de canal Matrix para enviar e receber mensagens do OpenClaw. | `@openclaw/matrix`<br />incluído no OpenClaw | channels: matrix |
|
||||
| [mattermost](/pt-BR/plugins/reference/mattermost) | Adiciona a superfície de canal Mattermost para enviar e receber mensagens do OpenClaw. | `@openclaw/mattermost`<br />incluído no OpenClaw | channels: mattermost |
|
||||
| [memory-core](/pt-BR/plugins/reference/memory-core) | Adiciona suporte a provedores de embeddings de memória. Adiciona ferramentas chamáveis pelo agente. | `@openclaw/memory-core`<br />incluído no OpenClaw | contracts: memoryEmbeddingProviders, tools |
|
||||
| [memory-wiki](/pt-BR/plugins/reference/memory-wiki) | Compilador de wiki persistente e cofre de conhecimento compatível com Obsidian para o OpenClaw. | `@openclaw/memory-wiki`<br />incluído no OpenClaw | contracts: tools; skills |
|
||||
| [microsoft](/pt-BR/plugins/reference/microsoft) | Adiciona suporte a provedores de conversão de texto em fala. | `@openclaw/microsoft-speech`<br />incluído no OpenClaw | contracts: speechProviders |
|
||||
| [microsoft-foundry](/pt-BR/plugins/reference/microsoft-foundry) | Adiciona suporte ao provedor de modelos Microsoft Foundry ao OpenClaw. | `@openclaw/microsoft-foundry`<br />incluído no OpenClaw | providers: microsoft-foundry |
|
||||
| [migrate-claude](/pt-BR/plugins/reference/migrate-claude) | Importa instruções do Claude Code e do Claude Desktop, servidores MCP, Skills e configuração segura para o OpenClaw. | `@openclaw/migrate-claude`<br />incluído no OpenClaw | contracts: migrationProviders |
|
||||
| [migrate-hermes](/pt-BR/plugins/reference/migrate-hermes) | Importa configuração, memórias, Skills e credenciais compatíveis do Hermes para o OpenClaw. | `@openclaw/migrate-hermes`<br />incluído no OpenClaw | contracts: migrationProviders |
|
||||
| [migrate-claude](/pt-BR/plugins/reference/migrate-claude) | Importa instruções do Claude Code e Claude Desktop, servidores MCP, Skills e configuração segura para o OpenClaw. | `@openclaw/migrate-claude`<br />incluído no OpenClaw | contracts: migrationProviders |
|
||||
| [migrate-hermes](/pt-BR/plugins/reference/migrate-hermes) | Importa configuração do Hermes, memórias, Skills e credenciais compatíveis para o OpenClaw. | `@openclaw/migrate-hermes`<br />incluído no OpenClaw | contracts: migrationProviders |
|
||||
| [minimax](/pt-BR/plugins/reference/minimax) | Adiciona suporte aos provedores de modelos MiniMax e MiniMax Portal ao OpenClaw. | `@openclaw/minimax-provider`<br />incluído no OpenClaw | providers: minimax, minimax-portal; contracts: imageGenerationProviders, mediaUnderstandingProviders, musicGenerationProviders, speechProviders, videoGenerationProviders, webSearchProviders |
|
||||
| [mistral](/pt-BR/plugins/reference/mistral) | Adiciona suporte ao provedor de modelos Mistral ao OpenClaw. | `@openclaw/mistral-provider`<br />incluído no OpenClaw | providers: mistral; contracts: mediaUnderstandingProviders, memoryEmbeddingProviders, realtimeTranscriptionProviders |
|
||||
| [moonshot](/pt-BR/plugins/reference/moonshot) | Adiciona suporte ao provedor de modelos Moonshot ao OpenClaw. | `@openclaw/moonshot-provider`<br />incluído no OpenClaw | providers: moonshot; contracts: mediaUnderstandingProviders, webSearchProviders |
|
||||
| [nvidia](/pt-BR/plugins/reference/nvidia) | Adiciona suporte ao provedor de modelos NVIDIA ao OpenClaw. | `@openclaw/nvidia-provider`<br />incluído no OpenClaw | providers: nvidia |
|
||||
| [ollama](/pt-BR/plugins/reference/ollama) | Adiciona suporte ao provedor de modelos Ollama ao OpenClaw. | `@openclaw/ollama-provider`<br />incluído no OpenClaw | providers: ollama; contracts: memoryEmbeddingProviders, webSearchProviders |
|
||||
| [open-prose](/pt-BR/plugins/reference/open-prose) | Pacote de Skills da VM OpenProse com um comando de barra `/prose`. | `@openclaw/open-prose`<br />incluído no OpenClaw | skills |
|
||||
| [open-prose](/pt-BR/plugins/reference/open-prose) | Pacote de Skills da VM OpenProse com um comando de barra /prose. | `@openclaw/open-prose`<br />incluído no OpenClaw | skills |
|
||||
| [openai](/pt-BR/plugins/reference/openai) | Adiciona suporte aos provedores de modelos OpenAI e OpenAI Codex ao OpenClaw. | `@openclaw/openai-provider`<br />incluído no OpenClaw | providers: openai, openai-codex; contracts: imageGenerationProviders, mediaUnderstandingProviders, memoryEmbeddingProviders, realtimeTranscriptionProviders, realtimeVoiceProviders, speechProviders, videoGenerationProviders |
|
||||
| [opencode](/pt-BR/plugins/reference/opencode) | Adiciona suporte ao provedor de modelos OpenCode ao OpenClaw. | `@openclaw/opencode-provider`<br />incluído no OpenClaw | providers: opencode; contracts: mediaUnderstandingProviders |
|
||||
| [opencode-go](/pt-BR/plugins/reference/opencode-go) | Adiciona suporte ao provedor de modelos OpenCode Go ao OpenClaw. | `@openclaw/opencode-go-provider`<br />incluído no OpenClaw | providers: opencode-go; contracts: mediaUnderstandingProviders |
|
||||
| [openrouter](/pt-BR/plugins/reference/openrouter) | Adiciona suporte ao provedor de modelos OpenRouter ao OpenClaw. | `@openclaw/openrouter-provider`<br />incluído no OpenClaw | providers: openrouter; contracts: imageGenerationProviders, mediaUnderstandingProviders, speechProviders, videoGenerationProviders |
|
||||
| [openshell](/pt-BR/plugins/reference/openshell) | Backend de sandbox baseado no OpenShell, com workspaces locais espelhados e execução de comandos baseada em SSH. | `@openclaw/openshell-sandbox`<br />incluído no OpenClaw | plugin |
|
||||
| [openshell](/pt-BR/plugins/reference/openshell) | Back-end de sandbox alimentado pelo OpenShell com workspaces locais espelhados e execução de comandos baseada em SSH. | `@openclaw/openshell-sandbox`<br />incluído no OpenClaw | plugin |
|
||||
| [perplexity](/pt-BR/plugins/reference/perplexity) | Adiciona suporte a provedores de pesquisa na web. | `@openclaw/perplexity-plugin`<br />incluído no OpenClaw | contracts: webSearchProviders |
|
||||
| [qianfan](/pt-BR/plugins/reference/qianfan) | Adiciona suporte ao provedor de modelos Qianfan ao OpenClaw. | `@openclaw/qianfan-provider`<br />incluído no OpenClaw | providers: qianfan |
|
||||
| [qwen](/pt-BR/plugins/reference/qwen) | Adiciona suporte aos provedores de modelos Qwen, Qwen Cloud, Model Studio e DashScope ao OpenClaw. | `@openclaw/qwen-provider`<br />incluído no OpenClaw | providers: qwen, qwencloud, modelstudio, dashscope; contracts: mediaUnderstandingProviders, videoGenerationProviders |
|
||||
| [runway](/pt-BR/plugins/reference/runway) | Adiciona suporte a provedor de geração de vídeo. | `@openclaw/runway-provider`<br />incluído no OpenClaw | contracts: videoGenerationProviders |
|
||||
| [searxng](/pt-BR/plugins/reference/searxng) | Adiciona suporte a provedor de pesquisa na web. | `@openclaw/searxng-plugin`<br />incluído no OpenClaw | contracts: webSearchProviders |
|
||||
| [searxng](/pt-BR/plugins/reference/searxng) | Adiciona suporte a provedor de busca na web. | `@openclaw/searxng-plugin`<br />incluído no OpenClaw | contracts: webSearchProviders |
|
||||
| [senseaudio](/pt-BR/plugins/reference/senseaudio) | Adiciona suporte a provedor de compreensão de mídia. | `@openclaw/senseaudio-provider`<br />incluído no OpenClaw | contracts: mediaUnderstandingProviders |
|
||||
| [sglang](/pt-BR/plugins/reference/sglang) | Adiciona suporte ao provedor de modelos SGLang ao OpenClaw. | `@openclaw/sglang-provider`<br />incluído no OpenClaw | providers: sglang |
|
||||
| [signal](/pt-BR/plugins/reference/signal) | Adiciona a superfície de canal do Signal para enviar e receber mensagens do OpenClaw. | `@openclaw/signal`<br />incluído no OpenClaw | channels: signal |
|
||||
| [skill-workshop](/pt-BR/plugins/reference/skill-workshop) | Captura fluxos de trabalho repetíveis como skills do workspace, com revisão pendente, gravações seguras e atualização de prompt de skill. | `@openclaw/skill-workshop`<br />incluído no OpenClaw | contracts: tools |
|
||||
| [slack](/pt-BR/plugins/reference/slack) | Adiciona a superfície de canal do Slack para enviar e receber mensagens do OpenClaw. | `@openclaw/slack`<br />incluído no OpenClaw | channels: slack |
|
||||
| [stepfun](/pt-BR/plugins/reference/stepfun) | Adiciona suporte aos provedores de modelos StepFun e StepFun Plan ao OpenClaw. | `@openclaw/stepfun-provider`<br />incluído no OpenClaw | providers: stepfun, stepfun-plan |
|
||||
| [synthetic](/pt-BR/plugins/reference/synthetic) | Adiciona suporte ao provedor de modelos Synthetic ao OpenClaw. | `@openclaw/synthetic-provider`<br />incluído no OpenClaw | providers: synthetic |
|
||||
| [tavily](/pt-BR/plugins/reference/tavily) | Adiciona ferramentas chamáveis por agentes. Adiciona suporte a provedor de pesquisa na web. | `@openclaw/tavily-plugin`<br />incluído no OpenClaw | contracts: tools, webSearchProviders; skills |
|
||||
| [telegram](/pt-BR/plugins/reference/telegram) | Adiciona a superfície de canal do Telegram para enviar e receber mensagens do OpenClaw. | `@openclaw/telegram`<br />incluído no OpenClaw | channels: telegram |
|
||||
| [tencent](/pt-BR/plugins/reference/tencent) | Adiciona suporte ao provedor de modelos Tencent TokenHub ao OpenClaw. | `@openclaw/tencent-provider`<br />incluído no OpenClaw | providers: tencent-tokenhub |
|
||||
| [together](/pt-BR/plugins/reference/together) | Adiciona suporte ao provedor de modelos Together ao OpenClaw. | `@openclaw/together-provider`<br />incluído no OpenClaw | providers: together; contracts: videoGenerationProviders |
|
||||
| [tokenjuice](/pt-BR/plugins/reference/tokenjuice) | Compacta resultados das ferramentas exec e bash com redutores tokenjuice. | `@openclaw/tokenjuice`<br />incluído no OpenClaw | contracts: agentToolResultMiddleware |
|
||||
| [tts-local-cli](/pt-BR/plugins/reference/tts-local-cli) | Adiciona suporte a provedor de conversão de texto em fala. | `@openclaw/tts-local-cli`<br />incluído no OpenClaw | contracts: speechProviders |
|
||||
| [venice](/pt-BR/plugins/reference/venice) | Adiciona suporte ao provedor de modelos Venice ao OpenClaw. | `@openclaw/venice-provider`<br />incluído no OpenClaw | providers: venice |
|
||||
| [vercel-ai-gateway](/pt-BR/plugins/reference/vercel-ai-gateway) | Adiciona suporte ao provedor de modelos Vercel AI Gateway ao OpenClaw. | `@openclaw/vercel-ai-gateway-provider`<br />incluído no OpenClaw | providers: vercel-ai-gateway |
|
||||
| [vllm](/pt-BR/plugins/reference/vllm) | Adiciona suporte ao provedor de modelos vLLM ao OpenClaw. | `@openclaw/vllm-provider`<br />incluído no OpenClaw | providers: vllm |
|
||||
| [volcengine](/pt-BR/plugins/reference/volcengine) | Adiciona suporte aos provedores de modelos Volcengine e Volcengine Plan ao OpenClaw. | `@openclaw/volcengine-provider`<br />incluído no OpenClaw | providers: volcengine, volcengine-plan; contracts: speechProviders |
|
||||
| [sglang](/pt-BR/plugins/reference/sglang) | Adiciona suporte ao provedor de modelos SGLang ao OpenClaw. | `@openclaw/sglang-provider`<br />incluído no OpenClaw | providers: sglang |
|
||||
| [signal](/pt-BR/plugins/reference/signal) | Adiciona a superfície de canal Signal para enviar e receber mensagens do OpenClaw. | `@openclaw/signal`<br />incluído no OpenClaw | channels: signal |
|
||||
| [skill-workshop](/pt-BR/plugins/reference/skill-workshop) | Captura fluxos de trabalho repetíveis como Skills do workspace, com revisão pendente, gravações seguras e atualização do prompt de Skill. | `@openclaw/skill-workshop`<br />incluído no OpenClaw | contracts: tools |
|
||||
| [slack](/pt-BR/plugins/reference/slack) | Adiciona a superfície de canal Slack para enviar e receber mensagens do OpenClaw. | `@openclaw/slack`<br />incluído no OpenClaw | channels: slack |
|
||||
| [stepfun](/pt-BR/plugins/reference/stepfun) | Adiciona suporte aos provedores de modelos StepFun e StepFun Plan ao OpenClaw. | `@openclaw/stepfun-provider`<br />incluído no OpenClaw | providers: stepfun, stepfun-plan |
|
||||
| [synthetic](/pt-BR/plugins/reference/synthetic) | Adiciona suporte ao provedor de modelos Synthetic ao OpenClaw. | `@openclaw/synthetic-provider`<br />incluído no OpenClaw | providers: synthetic |
|
||||
| [tavily](/pt-BR/plugins/reference/tavily) | Adiciona ferramentas chamáveis por agentes. Adiciona suporte a provedor de busca na web. | `@openclaw/tavily-plugin`<br />incluído no OpenClaw | contracts: tools, webSearchProviders; skills |
|
||||
| [telegram](/pt-BR/plugins/reference/telegram) | Adiciona a superfície de canal Telegram para enviar e receber mensagens do OpenClaw. | `@openclaw/telegram`<br />incluído no OpenClaw | channels: telegram |
|
||||
| [tencent](/pt-BR/plugins/reference/tencent) | Adiciona suporte ao provedor de modelos Tencent TokenHub ao OpenClaw. | `@openclaw/tencent-provider`<br />incluído no OpenClaw | providers: tencent-tokenhub |
|
||||
| [together](/pt-BR/plugins/reference/together) | Adiciona suporte ao provedor de modelos Together ao OpenClaw. | `@openclaw/together-provider`<br />incluído no OpenClaw | providers: together; contracts: videoGenerationProviders |
|
||||
| [tokenjuice](/pt-BR/plugins/reference/tokenjuice) | Compacta resultados de ferramentas exec e bash com redutores tokenjuice. | `@openclaw/tokenjuice`<br />incluído no OpenClaw | contracts: agentToolResultMiddleware |
|
||||
| [tts-local-cli](/pt-BR/plugins/reference/tts-local-cli) | Adiciona suporte a provedor de conversão de texto em fala. | `@openclaw/tts-local-cli`<br />incluído no OpenClaw | contracts: speechProviders |
|
||||
| [venice](/pt-BR/plugins/reference/venice) | Adiciona suporte ao provedor de modelos Venice ao OpenClaw. | `@openclaw/venice-provider`<br />incluído no OpenClaw | providers: venice |
|
||||
| [vercel-ai-gateway](/pt-BR/plugins/reference/vercel-ai-gateway) | Adiciona suporte ao provedor de modelos Vercel AI Gateway ao OpenClaw. | `@openclaw/vercel-ai-gateway-provider`<br />incluído no OpenClaw | providers: vercel-ai-gateway |
|
||||
| [vllm](/pt-BR/plugins/reference/vllm) | Adiciona suporte ao provedor de modelos vLLM ao OpenClaw. | `@openclaw/vllm-provider`<br />incluído no OpenClaw | providers: vllm |
|
||||
| [volcengine](/pt-BR/plugins/reference/volcengine) | Adiciona suporte aos provedores de modelos Volcengine e Volcengine Plan ao OpenClaw. | `@openclaw/volcengine-provider`<br />incluído no OpenClaw | providers: volcengine, volcengine-plan; contracts: speechProviders |
|
||||
| [voyage](/pt-BR/plugins/reference/voyage) | Adiciona suporte a provedor de embeddings de memória. | `@openclaw/voyage-provider`<br />incluído no OpenClaw | contracts: memoryEmbeddingProviders |
|
||||
| [vydra](/pt-BR/plugins/reference/vydra) | Adiciona suporte ao provedor de modelos Vydra ao OpenClaw. | `@openclaw/vydra-provider`<br />incluído no OpenClaw | providers: vydra; contracts: imageGenerationProviders, speechProviders, videoGenerationProviders |
|
||||
| [web-readability](/pt-BR/plugins/reference/web-readability) | Extrai conteúdo legível de artigos de respostas locais de busca web em HTML. | `@openclaw/web-readability-plugin`<br />incluído no OpenClaw | contracts: webContentExtractors |
|
||||
| [webhooks](/pt-BR/plugins/reference/webhooks) | Webhooks de entrada autenticados que vinculam automações externas a TaskFlows do OpenClaw. | `@openclaw/webhooks`<br />incluído no OpenClaw | plugin |
|
||||
| [vydra](/pt-BR/plugins/reference/vydra) | Adiciona suporte ao provedor de modelos Vydra ao OpenClaw. | `@openclaw/vydra-provider`<br />incluído no OpenClaw | providers: vydra; contracts: imageGenerationProviders, speechProviders, videoGenerationProviders |
|
||||
| [web-readability](/pt-BR/plugins/reference/web-readability) | Extrai conteúdo legível de artigos a partir de respostas locais de busca de HTML da web. | `@openclaw/web-readability-plugin`<br />incluído no OpenClaw | contracts: webContentExtractors |
|
||||
| [webhooks](/pt-BR/plugins/reference/webhooks) | Webhooks de entrada autenticados que vinculam automação externa a TaskFlows do OpenClaw. | `@openclaw/webhooks`<br />incluído no OpenClaw | plugin |
|
||||
| [xai](/pt-BR/plugins/reference/xai) | Adiciona suporte ao provedor de modelos xAI ao OpenClaw. | `@openclaw/xai-plugin`<br />incluído no OpenClaw | providers: xai; contracts: imageGenerationProviders, mediaUnderstandingProviders, realtimeTranscriptionProviders, speechProviders, tools, videoGenerationProviders, webSearchProviders |
|
||||
| [xiaomi](/pt-BR/plugins/reference/xiaomi) | Adiciona suporte ao provedor de modelos Xiaomi ao OpenClaw. | `@openclaw/xiaomi-provider`<br />incluído no OpenClaw | providers: xiaomi; contracts: speechProviders |
|
||||
| [zai](/pt-BR/plugins/reference/zai) | Adiciona suporte ao provedor de modelos Z.AI ao OpenClaw. | `@openclaw/zai-provider`<br />incluído no OpenClaw | providers: zai; contracts: mediaUnderstandingProviders |
|
||||
@ -128,21 +148,21 @@ de workspace locais do pacote ficam disponíveis.
|
||||
## Pacotes externos oficiais
|
||||
|
||||
| Plugin | Descrição | Distribuição | Superfície |
|
||||
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
|
||||
| [acpx](/pt-BR/plugins/reference/acpx) | Backend de tempo de execução ACP incorporado, com gerenciamento de sessão e transporte pertencente ao Plugin. | `@openclaw/acpx`<br />npm; ClawHub | skills |
|
||||
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
|
||||
| [acpx](/pt-BR/plugins/reference/acpx) | Backend de runtime ACP incorporado com sessão e gerenciamento de transporte próprios do plugin. | `@openclaw/acpx`<br />npm; ClawHub | skills |
|
||||
| [bluebubbles](/pt-BR/plugins/reference/bluebubbles) | Adiciona a superfície de canal BlueBubbles para enviar e receber mensagens do OpenClaw. | `@openclaw/bluebubbles`<br />npm; ClawHub | channels: bluebubbles |
|
||||
| [brave](/pt-BR/plugins/reference/brave) | Adiciona suporte ao provedor de pesquisa na web. | `@openclaw/brave-plugin`<br />npm; ClawHub | contracts: webSearchProviders |
|
||||
| [codex](/pt-BR/plugins/reference/codex) | Arnês de servidor de app do Codex e catálogo de modelos GPT gerenciado pelo Codex. | `@openclaw/codex`<br />npm; ClawHub | providers: codex; contracts: mediaUnderstandingProviders, migrationProviders |
|
||||
| [brave](/pt-BR/plugins/reference/brave) | Adiciona suporte a provedor de pesquisa na web. | `@openclaw/brave-plugin`<br />npm; ClawHub | contracts: webSearchProviders |
|
||||
| [codex](/pt-BR/plugins/reference/codex) | Arnês de servidor de aplicativo Codex e catálogo de modelos GPT gerenciado pelo Codex. | `@openclaw/codex`<br />npm; ClawHub | providers: codex; contracts: mediaUnderstandingProviders, migrationProviders |
|
||||
| [diagnostics-otel](/pt-BR/plugins/reference/diagnostics-otel) | Exportador OpenTelemetry de diagnósticos do OpenClaw. | `@openclaw/diagnostics-otel`<br />npm; ClawHub: `clawhub:@openclaw/diagnostics-otel` | plugin |
|
||||
| [diagnostics-prometheus](/pt-BR/plugins/reference/diagnostics-prometheus) | Exportador Prometheus de diagnósticos do OpenClaw. | `@openclaw/diagnostics-prometheus`<br />npm; ClawHub: `clawhub:@openclaw/diagnostics-prometheus` | plugin |
|
||||
| [diffs](/pt-BR/plugins/reference/diffs) | Visualizador de diff somente leitura e renderizador de arquivos para agentes. | `@openclaw/diffs`<br />npm; ClawHub | contracts: tools; skills |
|
||||
| [discord](/pt-BR/plugins/reference/discord) | Adiciona a superfície de canal Discord para enviar e receber mensagens do OpenClaw. | `@openclaw/discord`<br />npm; ClawHub | channels: discord |
|
||||
| [feishu](/pt-BR/plugins/reference/feishu) | Adiciona a superfície de canal Feishu para enviar e receber mensagens do OpenClaw. | `@openclaw/feishu`<br />npm; ClawHub | channels: feishu; contracts: tools; skills |
|
||||
| [google-meet](/pt-BR/plugins/reference/google-meet) | Entre em chamadas do Google Meet por meio de transportes Chrome ou Twilio. | `@openclaw/google-meet`<br />npm; ClawHub | contracts: tools |
|
||||
| [google-meet](/pt-BR/plugins/reference/google-meet) | Participe de chamadas do Google Meet por meio de transportes Chrome ou Twilio. | `@openclaw/google-meet`<br />npm; ClawHub | contracts: tools |
|
||||
| [googlechat](/pt-BR/plugins/reference/googlechat) | Adiciona a superfície de canal Google Chat para enviar e receber mensagens do OpenClaw. | `@openclaw/googlechat`<br />npm; ClawHub | channels: googlechat |
|
||||
| [line](/pt-BR/plugins/reference/line) | Adiciona a superfície de canal LINE para enviar e receber mensagens do OpenClaw. | `@openclaw/line`<br />npm; ClawHub | channels: line |
|
||||
| [lobster](/pt-BR/plugins/reference/lobster) | Ferramenta de fluxo de trabalho tipada com aprovações retomáveis. | `@openclaw/lobster`<br />npm; ClawHub | contracts: tools |
|
||||
| [memory-lancedb](/pt-BR/plugins/reference/memory-lancedb) | Adiciona ferramentas chamáveis por agentes. | `@openclaw/memory-lancedb`<br />npm; ClawHub | contracts: tools |
|
||||
| [memory-lancedb](/pt-BR/plugins/reference/memory-lancedb) | Adiciona ferramentas chamáveis por agente. | `@openclaw/memory-lancedb`<br />npm; ClawHub | contracts: tools |
|
||||
| [msteams](/pt-BR/plugins/reference/msteams) | Adiciona a superfície de canal Microsoft Teams para enviar e receber mensagens do OpenClaw. | `@openclaw/msteams`<br />npm; ClawHub | channels: msteams |
|
||||
| [nextcloud-talk](/pt-BR/plugins/reference/nextcloud-talk) | Adiciona a superfície de canal Nextcloud Talk para enviar e receber mensagens do OpenClaw. | `@openclaw/nextcloud-talk`<br />npm; ClawHub | channels: nextcloud-talk |
|
||||
| [nostr](/pt-BR/plugins/reference/nostr) | Adiciona a superfície de canal Nostr para enviar e receber mensagens do OpenClaw. | `@openclaw/nostr`<br />npm; ClawHub | channels: nostr |
|
||||
@ -150,15 +170,15 @@ de workspace locais do pacote ficam disponíveis.
|
||||
| [synology-chat](/pt-BR/plugins/reference/synology-chat) | Adiciona a superfície de canal Synology Chat para enviar e receber mensagens do OpenClaw. | `@openclaw/synology-chat`<br />npm; ClawHub | channels: synology-chat |
|
||||
| [tlon](/pt-BR/plugins/reference/tlon) | Adiciona a superfície de canal Tlon para enviar e receber mensagens do OpenClaw. | `@openclaw/tlon`<br />npm; ClawHub | channels: tlon; contracts: tools; skills |
|
||||
| [twitch](/pt-BR/plugins/reference/twitch) | Adiciona a superfície de canal Twitch para enviar e receber mensagens do OpenClaw. | `@openclaw/twitch`<br />npm; ClawHub | channels: twitch |
|
||||
| [voice-call](/pt-BR/plugins/reference/voice-call) | Adiciona ferramentas chamáveis por agentes. | `@openclaw/voice-call`<br />npm; ClawHub | contracts: tools |
|
||||
| [voice-call](/pt-BR/plugins/reference/voice-call) | Adiciona ferramentas chamáveis por agente. | `@openclaw/voice-call`<br />npm; ClawHub | contracts: tools |
|
||||
| [whatsapp](/pt-BR/plugins/reference/whatsapp) | Adiciona a superfície de canal WhatsApp para enviar e receber mensagens do OpenClaw. | `@openclaw/whatsapp`<br />npm; ClawHub | channels: whatsapp |
|
||||
| [zalo](/pt-BR/plugins/reference/zalo) | Adiciona a superfície de canal Zalo para enviar e receber mensagens do OpenClaw. | `@openclaw/zalo`<br />npm; ClawHub | channels: zalo |
|
||||
| [zalouser](/pt-BR/plugins/reference/zalouser) | Adiciona a superfície de canal Zalo Personal para enviar e receber mensagens do OpenClaw. | `@openclaw/zalouser`<br />npm; ClawHub | channels: zalouser; contracts: tools |
|
||||
|
||||
## Somente checkout do código-fonte
|
||||
|
||||
| Plugin | Descrição | Distribuição | Superfície |
|
||||
| Plugin | Descrição | Distribuição | Superfície |
|
||||
| ------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------ | -------------------- |
|
||||
| [qa-channel](/pt-BR/plugins/reference/qa-channel) | Adiciona a superfície de canal QA Channel para enviar e receber mensagens do OpenClaw. | `@openclaw/qa-channel`<br />somente checkout do código-fonte | channels: qa-channel |
|
||||
| [qa-lab](/pt-BR/plugins/reference/qa-lab) | Plugin de laboratório de QA do OpenClaw com interface privada de depurador e executor de cenários. | `@openclaw/qa-lab`<br />somente checkout do código-fonte | plugin |
|
||||
| [qa-matrix](/pt-BR/plugins/reference/qa-matrix) | Executor e substrato de transporte de QA Matrix. | `@openclaw/qa-matrix`<br />somente checkout do código-fonte | plugin |
|
||||
| [qa-lab](/pt-BR/plugins/reference/qa-lab) | Plugin de laboratório de QA do OpenClaw com UI privada de depuração e executor de cenários. | `@openclaw/qa-lab`<br />somente checkout do código-fonte | plugin |
|
||||
| [qa-matrix](/pt-BR/plugins/reference/qa-matrix) | Executor e substrato de transporte Matrix QA. | `@openclaw/qa-matrix`<br />somente checkout do código-fonte | plugin |
|
||||
|
||||
@ -1,28 +1,28 @@
|
||||
---
|
||||
read_when:
|
||||
- Você precisa chamar auxiliares do núcleo a partir de um Plugin (TTS, STT, geração de imagem, pesquisa na web, subagente, nós)
|
||||
- Você precisa chamar auxiliares do núcleo a partir de um Plugin (TTS, STT, geração de imagens, busca na web, subagente, nós)
|
||||
- Você quer entender o que api.runtime expõe
|
||||
- Você está acessando auxiliares de configuração, agente ou mídia a partir do código do plugin
|
||||
- Você está acessando auxiliares de configuração, agente ou mídia a partir do código do Plugin
|
||||
sidebarTitle: Runtime helpers
|
||||
summary: api.runtime -- os auxiliares de runtime injetados disponíveis para plugins
|
||||
summary: api.runtime -- os auxiliares de tempo de execução injetados disponíveis para plugins
|
||||
title: Auxiliares de tempo de execução do Plugin
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T21:03:03Z"
|
||||
generated_at: "2026-05-04T09:37:19Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 26df37a2ad0dcd29648e382eb579b6892068af4dea1c47460cfd379458a8081c
|
||||
source_hash: c968f30052ecba4359bdaa9b1c640c1220268933ce01ccef06bcade225b50b7d
|
||||
source_path: plugins/sdk-runtime.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Referência para o objeto `api.runtime` injetado em cada plugin durante o registro. Use esses auxiliares em vez de importar internos do host diretamente.
|
||||
Referência para o objeto `api.runtime` injetado em todo plugin durante o registro. Use esses helpers em vez de importar internals do host diretamente.
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Plugins de canal" href="/pt-BR/plugins/sdk-channel-plugins">
|
||||
Guia passo a passo que usa esses auxiliares no contexto de plugins de canal.
|
||||
Guia passo a passo que usa esses helpers em contexto para plugins de canal.
|
||||
</Card>
|
||||
<Card title="Plugins de provedor" href="/pt-BR/plugins/sdk-provider-plugins">
|
||||
Guia passo a passo que usa esses auxiliares no contexto de plugins de provedor.
|
||||
Guia passo a passo que usa esses helpers em contexto para plugins de provedor.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -32,40 +32,40 @@ register(api) {
|
||||
}
|
||||
```
|
||||
|
||||
## Carregamento e gravações de configuração
|
||||
## Carregamento E Escritas De Configuração
|
||||
|
||||
Prefira a configuração que já foi passada para o caminho de chamada ativo, por exemplo `api.config` durante o registro ou um argumento `cfg` em callbacks de canal/provedor. Isso mantém um snapshot de processo fluindo pelo trabalho em vez de reanalisar a configuração em caminhos críticos.
|
||||
|
||||
Use `api.runtime.config.current()` somente quando um manipulador de longa duração precisar do snapshot atual do processo e nenhuma configuração tiver sido passada para essa função. O valor retornado é somente leitura; clone ou use um auxiliar de mutação antes de editar.
|
||||
Use `api.runtime.config.current()` somente quando um handler de longa duração precisar do snapshot atual do processo e nenhuma configuração tiver sido passada para essa função. O valor retornado é somente leitura; clone ou use um helper de mutação antes de editar.
|
||||
|
||||
Fábricas de ferramentas recebem `ctx.runtimeConfig` mais `ctx.getRuntimeConfig()`. Use o getter dentro do callback `execute` de uma ferramenta de longa duração quando a configuração puder mudar depois que a definição da ferramenta foi criada.
|
||||
|
||||
Persista alterações com `api.runtime.config.mutateConfigFile(...)` ou `api.runtime.config.replaceConfigFile(...)`. Cada gravação deve escolher uma política explícita de `afterWrite`:
|
||||
Persista alterações com `api.runtime.config.mutateConfigFile(...)` ou `api.runtime.config.replaceConfigFile(...)`. Cada escrita deve escolher uma política `afterWrite` explícita:
|
||||
|
||||
- `afterWrite: { mode: "auto" }` deixa o planejador de recarregamento do Gateway decidir.
|
||||
- `afterWrite: { mode: "restart", reason: "..." }` força uma reinicialização limpa quando o gravador sabe que o recarregamento a quente não é seguro.
|
||||
- `afterWrite: { mode: "none", reason: "..." }` suprime o recarregamento/reinicialização automático somente quando o chamador é responsável pelo acompanhamento.
|
||||
- `afterWrite: { mode: "auto" }` permite que a decisão de recarregamento do Gateway decida.
|
||||
- `afterWrite: { mode: "restart", reason: "..." }` força uma reinicialização limpa quando o autor da escrita sabe que o hot reload não é seguro.
|
||||
- `afterWrite: { mode: "none", reason: "..." }` suprime recarregamento/reinicialização automáticos somente quando o chamador é responsável pelo acompanhamento.
|
||||
|
||||
Os auxiliares de mutação retornam `afterWrite` mais um resumo `followUp` tipado para que os chamadores possam registrar em log ou testar se solicitaram uma reinicialização. O Gateway ainda é responsável por quando essa reinicialização realmente acontece.
|
||||
Os helpers de mutação retornam `afterWrite` mais um resumo tipado `followUp` para que chamadores possam registrar em log ou testar se solicitaram uma reinicialização. O Gateway ainda controla quando essa reinicialização realmente acontece.
|
||||
|
||||
`api.runtime.config.loadConfig()` e `api.runtime.config.writeConfigFile(...)` são auxiliares de compatibilidade obsoletos em `runtime-config-load-write`. Eles avisam uma vez em tempo de execução e continuam disponíveis para plugins externos antigos durante a janela de migração. Plugins integrados não devem usá-los; as proteções de limite de configuração falham se o código do plugin os chamar ou importar esses auxiliares de subcaminhos do SDK de plugin.
|
||||
`api.runtime.config.loadConfig()` e `api.runtime.config.writeConfigFile(...)` são helpers de compatibilidade obsoletos sob `runtime-config-load-write`. Eles avisam uma vez em runtime e permanecem disponíveis para plugins externos antigos durante a janela de migração. Plugins incluídos não devem usá-los; os guardas de limite de configuração falham se o código do plugin chamá-los ou importar esses helpers de subcaminhos do SDK de plugins.
|
||||
|
||||
Para importações diretas do SDK, use os subcaminhos focados de configuração em vez do barrel amplo de compatibilidade
|
||||
Para importações diretas do SDK, use os subcaminhos de configuração focados em vez do barrel amplo de compatibilidade
|
||||
`openclaw/plugin-sdk/config-runtime`: `config-types` para
|
||||
tipos, `plugin-config-runtime` para asserções de configuração já carregada e busca de
|
||||
entrada de plugin, `runtime-config-snapshot` para snapshots atuais do processo, e
|
||||
`config-mutation` para gravações. Testes de plugins integrados devem simular esses subcaminhos focados
|
||||
diretamente em vez de simular o barrel amplo de compatibilidade.
|
||||
entrada de plugin, `runtime-config-snapshot` para snapshots atuais do processo e
|
||||
`config-mutation` para escritas. Testes de plugins incluídos devem simular diretamente esses
|
||||
subcaminhos focados em vez de simular o barrel amplo de compatibilidade.
|
||||
|
||||
O código interno de runtime do OpenClaw segue a mesma direção: carregar a configuração uma vez no limite da CLI, do Gateway ou do processo e então passar esse valor adiante. Gravações de mutação bem-sucedidas atualizam o snapshot de runtime do processo e avançam sua revisão interna; caches de longa duração devem se basear na chave de cache pertencente ao runtime em vez de serializar a configuração localmente. Módulos de runtime de longa duração têm um scanner de tolerância zero para chamadas ambientes a `loadConfig()`; use um `cfg` passado, um `context.getRuntimeConfig()` de requisição ou `getRuntimeConfig()` em um limite explícito de processo.
|
||||
O código interno de runtime do OpenClaw segue a mesma direção: carregar a configuração uma vez na CLI, no Gateway ou no limite do processo, depois passar esse valor adiante. Escritas de mutação bem-sucedidas atualizam o snapshot de runtime do processo e avançam sua revisão interna; caches de longa duração devem usar como chave a chave de cache pertencente ao runtime em vez de serializar a configuração localmente. Módulos de runtime de longa duração têm um scanner de tolerância zero para chamadas `loadConfig()` ambientes; use um `cfg` passado, um `context.getRuntimeConfig()` de requisição ou `getRuntimeConfig()` em um limite explícito do processo.
|
||||
|
||||
Caminhos de execução de provedores e canais devem usar o snapshot de configuração de runtime ativo, não um snapshot de arquivo retornado para releitura ou edição da configuração. Snapshots de arquivo preservam valores de origem, como marcadores SecretRef, para a UI e gravações; callbacks de provedor precisam da visão de runtime resolvida. Quando um auxiliar puder ser chamado tanto com o snapshot de origem ativo quanto com o snapshot de runtime ativo, roteie por `selectApplicableRuntimeConfig()` antes de ler credenciais.
|
||||
Caminhos de execução de provedor e canal devem usar o snapshot de configuração de runtime ativo, não um snapshot de arquivo retornado para releitura ou edição de configuração. Snapshots de arquivo preservam valores de origem como marcadores SecretRef para UI e escritas; callbacks de provedor precisam da visão de runtime resolvida. Quando um helper puder ser chamado com o snapshot de origem ativo ou o snapshot de runtime ativo, encaminhe por `selectApplicableRuntimeConfig()` antes de ler credenciais.
|
||||
|
||||
## Namespaces de runtime
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="api.runtime.agent">
|
||||
Identidade do agente, diretórios e gerenciamento de sessões.
|
||||
Identidade do agente, diretórios e gerenciamento de sessão.
|
||||
|
||||
```typescript
|
||||
// Resolve the agent's working directory
|
||||
@ -109,15 +109,15 @@ Caminhos de execução de provedores e canais devem usar o snapshot de configura
|
||||
});
|
||||
```
|
||||
|
||||
`runEmbeddedAgent(...)` é o auxiliar neutro para iniciar uma rodada normal de agente OpenClaw a partir do código de plugin. Ele usa a mesma resolução de provedor/modelo e seleção do harness de agente que respostas disparadas por canal.
|
||||
`runEmbeddedAgent(...)` é o helper neutro para iniciar um turno normal de agente OpenClaw a partir de código de plugin. Ele usa a mesma resolução de provedor/modelo e seleção de harness de agente que respostas disparadas por canal.
|
||||
|
||||
`runEmbeddedPiAgent(...)` permanece como um alias de compatibilidade.
|
||||
`runEmbeddedPiAgent(...)` permanece como alias de compatibilidade.
|
||||
|
||||
`resolveThinkingPolicy(...)` retorna os níveis de raciocínio compatíveis do provedor/modelo e o padrão opcional. Plugins de provedor são responsáveis pelo perfil específico do modelo por meio de seus hooks de raciocínio, então plugins de ferramenta devem chamar esse auxiliar de runtime em vez de importar ou duplicar listas de provedores.
|
||||
`resolveThinkingPolicy(...)` retorna os níveis de raciocínio compatíveis do provedor/modelo e o padrão opcional. Plugins de provedor são responsáveis pelo perfil específico do modelo por meio de seus hooks de raciocínio, então plugins de ferramenta devem chamar este helper de runtime em vez de importar ou duplicar listas de provedores.
|
||||
|
||||
`normalizeThinkingLevel(...)` converte texto do usuário como `on`, `x-high` ou `extra high` para o nível armazenado canônico antes de verificá-lo contra a política resolvida.
|
||||
|
||||
**Auxiliares de armazenamento de sessão** ficam em `api.runtime.agent.session`:
|
||||
**Helpers de armazenamento de sessão** ficam em `api.runtime.agent.session`:
|
||||
|
||||
```typescript
|
||||
const storePath = api.runtime.agent.session.resolveStorePath(cfg);
|
||||
@ -129,7 +129,7 @@ Caminhos de execução de provedores e canais devem usar o snapshot de configura
|
||||
const filePath = api.runtime.agent.session.resolveSessionFilePath(cfg, sessionId);
|
||||
```
|
||||
|
||||
Prefira `updateSessionStore(...)` ou `updateSessionStoreEntry(...)` para gravações em runtime. Eles roteiam pelo gravador de armazenamento de sessão pertencente ao Gateway, preservam atualizações concorrentes e reutilizam o cache quente. `saveSessionStore(...)` permanece disponível para compatibilidade e regravações no estilo de manutenção offline.
|
||||
Prefira `updateSessionStore(...)` ou `updateSessionStoreEntry(...)` para escritas de runtime. Eles passam pelo escritor de armazenamento de sessão pertencente ao Gateway, preservam atualizações concorrentes e reutilizam o cache quente. `saveSessionStore(...)` permanece disponível para compatibilidade e reescritas de manutenção offline.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.agent.defaults">
|
||||
@ -142,7 +142,7 @@ Caminhos de execução de provedores e canais devem usar o snapshot de configura
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.subagent">
|
||||
Inicie e gerencie execuções de subagentes em segundo plano.
|
||||
Inicie e gerencie execuções de subagente em segundo plano.
|
||||
|
||||
```typescript
|
||||
// Start a subagent run
|
||||
@ -173,11 +173,11 @@ Caminhos de execução de provedores e canais devem usar o snapshot de configura
|
||||
Sobrescritas de modelo (`provider`/`model`) exigem opt-in do operador via `plugins.entries.<id>.subagent.allowModelOverride: true` na configuração. Plugins não confiáveis ainda podem executar subagentes, mas solicitações de sobrescrita são rejeitadas.
|
||||
</Warning>
|
||||
|
||||
`deleteSession(...)` pode excluir sessões criadas pelo mesmo plugin por meio de `api.runtime.subagent.run(...)`. Excluir sessões arbitrárias de usuários ou operadores ainda exige uma requisição de Gateway com escopo de administrador.
|
||||
`deleteSession(...)` pode excluir sessões criadas pelo mesmo plugin por meio de `api.runtime.subagent.run(...)`. Excluir sessões arbitrárias de usuário ou operador ainda exige uma requisição ao Gateway com escopo de administrador.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.nodes">
|
||||
Liste nós conectados e invoque um comando hospedado no nó a partir de código de plugin carregado pelo Gateway ou de comandos CLI de plugin. Use isso quando um plugin for responsável por trabalho local em um dispositivo pareado, por exemplo uma ponte de navegador ou áudio em outro Mac.
|
||||
Liste nós conectados e invoque um comando hospedado em nó a partir de código de plugin carregado pelo Gateway ou de comandos de CLI do plugin. Use isto quando um plugin for responsável por trabalho local em um dispositivo pareado, por exemplo uma ponte de navegador ou áudio em outro Mac.
|
||||
|
||||
```typescript
|
||||
const { nodes } = await api.runtime.nodes.list({ connected: true });
|
||||
@ -190,13 +190,13 @@ Caminhos de execução de provedores e canais devem usar o snapshot de configura
|
||||
});
|
||||
```
|
||||
|
||||
Dentro do Gateway, esse runtime é em processo. Em comandos CLI de plugin, ele chama o Gateway configurado por RPC, então comandos como `openclaw googlemeet recover-tab` podem inspecionar nós pareados a partir do terminal. Comandos de Node ainda passam pelo pareamento normal de nós do Gateway, allowlists de comandos, políticas de invocação de nó de plugin e tratamento de comandos locais do nó.
|
||||
Dentro do Gateway, este runtime é em processo. Em comandos de CLI de plugin, ele chama o Gateway configurado por RPC, então comandos como `openclaw googlemeet recover-tab` podem inspecionar nós pareados a partir do terminal. Comandos de nó ainda passam pelo pareamento normal de nós do Gateway, allowlists de comandos, políticas de invocação de nó do plugin e tratamento de comando local ao nó.
|
||||
|
||||
Plugins que expõem comandos perigosos hospedados no nó devem registrar uma política de invocação de nó com `api.registerNodeInvokePolicy(...)`. A política é executada no Gateway depois das verificações de allowlist de comandos e antes de o comando ser encaminhado ao nó, de modo que chamadas diretas a `node.invoke` e ferramentas de plugin de nível mais alto compartilhem o mesmo caminho de aplicação.
|
||||
Plugins que expõem comandos perigosos hospedados em nó devem registrar uma política de invocação de nó com `api.registerNodeInvokePolicy(...)`. A política é executada no Gateway depois das verificações de allowlist de comando e antes que o comando seja encaminhado ao nó, para que chamadas diretas de `node.invoke` e ferramentas de plugin de nível mais alto compartilhem o mesmo caminho de aplicação.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.tasks.managedFlows">
|
||||
Vincule um runtime de TaskFlow a uma chave de sessão OpenClaw existente ou a um contexto de ferramenta confiável e então crie e gerencie TaskFlows sem passar um proprietário em cada chamada.
|
||||
Vincule um runtime de Task Flow a uma chave de sessão OpenClaw existente ou a um contexto de ferramenta confiável, depois crie e gerencie Task Flows sem passar um proprietário em cada chamada.
|
||||
|
||||
```typescript
|
||||
const taskFlow = api.runtime.tasks.managedFlows.fromToolContext(ctx);
|
||||
@ -223,11 +223,11 @@ Caminhos de execução de provedores e canais devem usar o snapshot de configura
|
||||
});
|
||||
```
|
||||
|
||||
Use `bindSession({ sessionKey, requesterOrigin })` quando você já tiver uma chave de sessão OpenClaw confiável da sua própria camada de vinculação. Não vincule a partir de entrada bruta do usuário.
|
||||
Use `bindSession({ sessionKey, requesterOrigin })` quando você já tiver uma chave de sessão OpenClaw confiável da sua própria camada de vinculação. Não vincule a partir de entrada bruta de usuário.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.tts">
|
||||
Síntese de texto em fala.
|
||||
Síntese de texto para fala.
|
||||
|
||||
```typescript
|
||||
// Standard TTS
|
||||
@ -249,7 +249,7 @@ Caminhos de execução de provedores e canais devem usar o snapshot de configura
|
||||
});
|
||||
```
|
||||
|
||||
Usa a configuração central `messages.tts` e a seleção de provedor. Retorna buffer de áudio PCM + taxa de amostragem.
|
||||
Usa a configuração central `messages.tts` e seleção de provedor. Retorna buffer de áudio PCM + taxa de amostragem.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.mediaUnderstanding">
|
||||
@ -286,12 +286,12 @@ Caminhos de execução de provedores e canais devem usar o snapshot de configura
|
||||
Retorna `{ text: undefined }` quando nenhuma saída é produzida (por exemplo, entrada ignorada).
|
||||
|
||||
<Info>
|
||||
`api.runtime.stt.transcribeAudioFile(...)` continua sendo um alias de compatibilidade para `api.runtime.mediaUnderstanding.transcribeAudioFile(...)`.
|
||||
`api.runtime.stt.transcribeAudioFile(...)` permanece como um alias de compatibilidade para `api.runtime.mediaUnderstanding.transcribeAudioFile(...)`.
|
||||
</Info>
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.imageGeneration">
|
||||
Geração de imagens.
|
||||
Geração de imagem.
|
||||
|
||||
```typescript
|
||||
const result = await api.runtime.imageGeneration.generate({
|
||||
@ -342,7 +342,7 @@ Caminhos de execução de provedores e canais devem usar o snapshot de configura
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.config">
|
||||
Snapshot da configuração de runtime atual e gravações transacionais de configuração. Prefira
|
||||
Snapshot da configuração atual de runtime e gravações transacionais de configuração. Prefira
|
||||
a configuração que já foi passada para o caminho de chamada ativo; use
|
||||
`current()` somente quando o manipulador precisar diretamente do snapshot do processo.
|
||||
|
||||
@ -356,14 +356,14 @@ Caminhos de execução de provedores e canais devem usar o snapshot de configura
|
||||
});
|
||||
```
|
||||
|
||||
`mutateConfigFile(...)` e `replaceConfigFile(...)` retornam um valor
|
||||
`followUp`, por exemplo `{ mode: "restart", requiresRestart: true, reason }`,
|
||||
que registra a intenção de quem gravou sem tirar o controle de reinicialização do
|
||||
`mutateConfigFile(...)` e `replaceConfigFile(...)` retornam um valor `followUp`,
|
||||
por exemplo `{ mode: "restart", requiresRestart: true, reason }`,
|
||||
que registra a intenção do gravador sem tirar o controle de reinício do
|
||||
Gateway.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.system">
|
||||
Utilitários de nível de sistema.
|
||||
Utilitários em nível de sistema.
|
||||
|
||||
```typescript
|
||||
await api.runtime.system.enqueueSystemEvent(event);
|
||||
@ -401,7 +401,7 @@ Caminhos de execução de provedores e canais devem usar o snapshot de configura
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.modelAuth">
|
||||
Resolução de autenticação de modelos e provedores.
|
||||
Resolução de autenticação de modelo e provedor.
|
||||
|
||||
```typescript
|
||||
const auth = await api.runtime.modelAuth.getApiKeyForModel({ model, cfg });
|
||||
@ -413,7 +413,7 @@ Caminhos de execução de provedores e canais devem usar o snapshot de configura
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.state">
|
||||
Resolução do diretório de estado e armazenamento chaveado baseado em SQLite.
|
||||
Resolução de diretório de estado e armazenamento por chave baseado em SQLite.
|
||||
|
||||
```typescript
|
||||
const stateDir = api.runtime.state.resolveStateDir(process.env);
|
||||
@ -424,15 +424,16 @@ Caminhos de execução de provedores e canais devem usar o snapshot de configura
|
||||
});
|
||||
|
||||
await store.register("key-1", { value: "hello" });
|
||||
const claimed = await store.registerIfAbsent("dedupe-key", { value: "first" });
|
||||
const value = await store.lookup("key-1");
|
||||
await store.consume("key-1");
|
||||
await store.clear();
|
||||
```
|
||||
|
||||
Armazenamentos chaveados sobrevivem a reinicializações e são isolados pelo id do plugin vinculado ao runtime. Limites: `maxEntries` por namespace, 1.000 linhas ativas por plugin, valores JSON abaixo de 64 KB e expiração TTL opcional.
|
||||
Armazenamentos por chave sobrevivem a reinícios e são isolados pelo id do plugin vinculado ao runtime. Use `registerIfAbsent(...)` para reivindicações atômicas de desduplicação: ele retorna `true` quando a chave estava ausente ou expirada e foi registrada, ou `false` quando um valor ativo já existe sem sobrescrever seu valor, hora de criação ou TTL. Limites: `maxEntries` por namespace, 1.000 linhas ativas por plugin, valores JSON abaixo de 64 KB e expiração opcional por TTL.
|
||||
|
||||
<Warning>
|
||||
Apenas plugins integrados nesta versão.
|
||||
Somente plugins incluídos nesta versão.
|
||||
</Warning>
|
||||
|
||||
</Accordion>
|
||||
@ -447,9 +448,9 @@ Caminhos de execução de provedores e canais devem usar o snapshot de configura
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.channel">
|
||||
Auxiliares de runtime específicos de canal (disponíveis quando um plugin de canal é carregado).
|
||||
Helpers de runtime específicos de canal (disponíveis quando um plugin de canal está carregado).
|
||||
|
||||
`api.runtime.channel.mentions` é a superfície compartilhada de política de menções de entrada para plugins de canal integrados que usam injeção de runtime:
|
||||
`api.runtime.channel.mentions` é a superfície compartilhada de política de menções de entrada para plugins de canal incluídos que usam injeção de runtime:
|
||||
|
||||
```typescript
|
||||
const mentionMatch = api.runtime.channel.mentions.matchesMentionWithExplicit(text, {
|
||||
@ -476,7 +477,7 @@ Caminhos de execução de provedores e canais devem usar o snapshot de configura
|
||||
});
|
||||
```
|
||||
|
||||
Auxiliares de menção disponíveis:
|
||||
Helpers de menção disponíveis:
|
||||
|
||||
- `buildMentionRegexes`
|
||||
- `matchesMentionPatterns`
|
||||
@ -484,17 +485,17 @@ Caminhos de execução de provedores e canais devem usar o snapshot de configura
|
||||
- `implicitMentionKindWhen`
|
||||
- `resolveInboundMentionDecision`
|
||||
|
||||
`api.runtime.channel.mentions` intencionalmente não expõe os auxiliares de compatibilidade `resolveMentionGating*` mais antigos. Prefira o caminho normalizado `{ facts, policy }`.
|
||||
`api.runtime.channel.mentions` intencionalmente não expõe os helpers de compatibilidade `resolveMentionGating*` mais antigos. Prefira o caminho normalizado `{ facts, policy }`.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Armazenamento de referências de runtime
|
||||
## Armazenando referências de runtime
|
||||
|
||||
Use `createPluginRuntimeStore` para armazenar a referência de runtime para uso fora do callback `register`:
|
||||
|
||||
<Steps>
|
||||
<Step title="Create the store">
|
||||
<Step title="Criar o armazenamento">
|
||||
```typescript
|
||||
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
|
||||
import type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store";
|
||||
@ -506,7 +507,7 @@ Use `createPluginRuntimeStore` para armazenar a referência de runtime para uso
|
||||
```
|
||||
|
||||
</Step>
|
||||
<Step title="Wire into the entry point">
|
||||
<Step title="Conectar ao ponto de entrada">
|
||||
```typescript
|
||||
export default defineChannelPluginEntry({
|
||||
id: "my-plugin",
|
||||
@ -517,7 +518,7 @@ Use `createPluginRuntimeStore` para armazenar a referência de runtime para uso
|
||||
});
|
||||
```
|
||||
</Step>
|
||||
<Step title="Access from other files">
|
||||
<Step title="Acessar de outros arquivos">
|
||||
```typescript
|
||||
export function getRuntime() {
|
||||
return store.getRuntime(); // throws if not initialized
|
||||
@ -532,7 +533,7 @@ Use `createPluginRuntimeStore` para armazenar a referência de runtime para uso
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
Prefira `pluginId` para a identidade do runtime-store. A forma de nível mais baixo `key` é para casos incomuns em que um plugin intencionalmente precisa de mais de um slot de runtime.
|
||||
Prefira `pluginId` para a identidade do armazenamento de runtime. A forma de nível mais baixo `key` é para casos incomuns em que um plugin intencionalmente precisa de mais de um slot de runtime.
|
||||
</Note>
|
||||
|
||||
## Outros campos `api` de nível superior
|
||||
@ -540,13 +541,13 @@ Prefira `pluginId` para a identidade do runtime-store. A forma de nível mais ba
|
||||
Além de `api.runtime`, o objeto de API também fornece:
|
||||
|
||||
<ParamField path="api.id" type="string">
|
||||
ID do Plugin.
|
||||
Id do plugin.
|
||||
</ParamField>
|
||||
<ParamField path="api.name" type="string">
|
||||
Nome de exibição do Plugin.
|
||||
Nome de exibição do plugin.
|
||||
</ParamField>
|
||||
<ParamField path="api.config" type="OpenClawConfig">
|
||||
Snapshot da configuração atual (snapshot de runtime ativo em memória quando disponível).
|
||||
Snapshot da configuração atual (snapshot ativo do runtime em memória quando disponível).
|
||||
</ParamField>
|
||||
<ParamField path="api.pluginConfig" type="Record<string, unknown>">
|
||||
Configuração específica do plugin de `plugins.entries.<id>.config`.
|
||||
@ -555,7 +556,7 @@ Além de `api.runtime`, o objeto de API também fornece:
|
||||
Logger com escopo (`debug`, `info`, `warn`, `error`).
|
||||
</ParamField>
|
||||
<ParamField path="api.registrationMode" type="PluginRegistrationMode">
|
||||
Modo de carregamento atual; `"setup-runtime"` é a janela leve de inicialização/configuração antes da entrada completa.
|
||||
Modo de carregamento atual; `"setup-runtime"` é a janela leve de inicialização/configuração anterior à entrada completa.
|
||||
</ParamField>
|
||||
<ParamField path="api.resolvePath(input)" type="(string) => string">
|
||||
Resolve um caminho relativo à raiz do plugin.
|
||||
@ -563,6 +564,6 @@ Além de `api.runtime`, o objeto de API também fornece:
|
||||
|
||||
## Relacionados
|
||||
|
||||
- [Componentes internos do Plugin](/pt-BR/plugins/architecture) — modelo de capacidades e registro
|
||||
- [Internos do plugin](/pt-BR/plugins/architecture) — modelo de capacidade e registro
|
||||
- [Pontos de entrada do SDK](/pt-BR/plugins/sdk-entrypoints) — opções de `definePluginEntry`
|
||||
- [Visão geral do SDK](/pt-BR/plugins/sdk-overview) — referência de subcaminhos
|
||||
|
||||
@ -1,37 +1,37 @@
|
||||
---
|
||||
read_when:
|
||||
- Depurando por que um agente respondeu, falhou ou chamou ferramentas de determinada forma
|
||||
- Depuração do motivo pelo qual um agente respondeu, falhou ou invocou ferramentas de determinada forma
|
||||
- Exportando um pacote de suporte para uma sessão do OpenClaw
|
||||
- Investigando contexto do prompt, chamadas de ferramentas, erros de tempo de execução ou metadados de uso
|
||||
- Desabilitar ou realocar a captura de trajetória
|
||||
- Investigando o contexto do prompt, chamadas de ferramenta, erros de tempo de execução ou metadados de uso
|
||||
- Desabilitando ou realocando a captura de trajetória
|
||||
summary: Exporte pacotes de trajetória com dados sensíveis removidos para depurar uma sessão de agente do OpenClaw
|
||||
title: Pacotes de trajetória
|
||||
title: Pacotes de trajetórias
|
||||
x-i18n:
|
||||
generated_at: "2026-04-30T10:13:15Z"
|
||||
generated_at: "2026-05-04T09:37:13Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 8dad01b3662d5e75b7626eb7ed3c3ac2dce4e3a7db2ba5952d7086c721151d1f
|
||||
source_hash: b8b1256e52d27185a48ceddaf7937b4f37ad6d57d075fea0d0b6d3abb871f1d8
|
||||
source_path: tools/trajectory.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
A captura de trajetória é o gravador de voo por sessão do OpenClaw. Ela registra uma
|
||||
linha do tempo estruturada para cada execução de agente; então `/export-trajectory` empacota a
|
||||
sessão atual em um pacote de suporte redigido.
|
||||
linha do tempo estruturada para cada execução de agente; depois, `/export-trajectory` empacota a
|
||||
sessão atual em um pacote de suporte com informações sensíveis ocultadas.
|
||||
|
||||
Use-a quando precisar responder a perguntas como:
|
||||
|
||||
- Qual prompt, prompt do sistema e ferramentas foram enviados ao modelo?
|
||||
- Quais mensagens de transcrição e chamadas de ferramenta levaram a esta resposta?
|
||||
- A execução expirou, foi abortada, compactada ou encontrou um erro do provedor?
|
||||
- Quais modelo, plugins, Skills e configurações de runtime estavam ativos?
|
||||
- Quais metadados de uso e cache de prompt o provedor retornou?
|
||||
- Quais mensagens da transcrição e chamadas de ferramenta levaram a esta resposta?
|
||||
- A execução atingiu tempo limite, foi abortada, compactada ou encontrou um erro de provedor?
|
||||
- Qual modelo, plugins, Skills e configurações de runtime estavam ativos?
|
||||
- Quais metadados de uso e de cache de prompt o provedor retornou?
|
||||
|
||||
Se você estiver abrindo um relatório de suporte amplo para um problema em um Gateway ao vivo, comece com
|
||||
[`/diagnostics`](/pt-BR/gateway/diagnostics#chat-command). O diagnóstico coleta o
|
||||
pacote sanitizado do Gateway e, para sessões do harness OpenAI Codex, também pode enviar
|
||||
Se você estiver registrando um relatório de suporte amplo para um problema em um Gateway ativo, comece com
|
||||
[`/diagnostics`](/pt-BR/gateway/diagnostics#chat-command). O Diagnostics coleta o
|
||||
pacote sanitizado do Gateway e, para sessões do harness do OpenAI Codex, também pode enviar
|
||||
feedback do Codex aos servidores da OpenAI após aprovação. Use `/export-trajectory` quando
|
||||
precisar especificamente da linha do tempo detalhada por sessão de prompt, ferramenta e transcrição.
|
||||
precisar especificamente da linha do tempo detalhada por sessão de prompts, ferramentas e transcrição.
|
||||
|
||||
## Início rápido
|
||||
|
||||
@ -62,15 +62,15 @@ Você pode escolher um nome de diretório de saída relativo:
|
||||
O caminho personalizado é resolvido dentro de `.openclaw/trajectory-exports/`. Caminhos
|
||||
absolutos e caminhos com `~` são rejeitados.
|
||||
|
||||
Pacotes de trajetória podem conter prompts, mensagens de modelo, esquemas de ferramentas, resultados de ferramentas,
|
||||
eventos de runtime e caminhos locais. Por isso, o comando de barra do chat passa
|
||||
por aprovação de exec todas as vezes. Aprove a exportação uma vez quando pretender
|
||||
Pacotes de trajetória podem conter prompts, mensagens do modelo, esquemas de ferramentas, resultados de ferramentas,
|
||||
eventos de runtime e caminhos locais. Portanto, o comando de barra do chat passa
|
||||
por aprovação de execução todas as vezes. Aprove a exportação uma vez quando pretender
|
||||
criar o pacote; não use permitir tudo. Em chats em grupo, o OpenClaw envia o
|
||||
prompt de aprovação e o resultado da exportação ao proprietário em privado, em vez de publicar os
|
||||
prompt de aprovação e o resultado da exportação para o proprietário em privado, em vez de publicar os
|
||||
detalhes da trajetória de volta na sala compartilhada.
|
||||
|
||||
Para inspeção local ou fluxos de suporte, você também pode executar o caminho de comando
|
||||
aprovado diretamente:
|
||||
Para inspeção local ou fluxos de suporte, você também pode executar diretamente o caminho
|
||||
do comando aprovado:
|
||||
|
||||
```bash
|
||||
openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --workspace .
|
||||
@ -78,12 +78,12 @@ openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:12
|
||||
|
||||
## Acesso
|
||||
|
||||
A exportação de trajetória é um comando de proprietário. O remetente deve passar nas verificações normais de
|
||||
autorização de comando e nas verificações de proprietário do canal.
|
||||
A exportação de trajetória é um comando do proprietário. O remetente precisa passar pelas verificações normais
|
||||
de autorização de comando e pelas verificações de proprietário do canal.
|
||||
|
||||
## O que é registrado
|
||||
|
||||
A captura de trajetória fica ativada por padrão para execuções de agentes do OpenClaw.
|
||||
A captura de trajetória fica ativada por padrão para execuções de agente do OpenClaw.
|
||||
|
||||
Eventos de runtime incluem:
|
||||
|
||||
@ -91,22 +91,22 @@ Eventos de runtime incluem:
|
||||
- `trace.metadata`
|
||||
- `context.compiled`
|
||||
- `prompt.submitted`
|
||||
- `model.fallback_step`, incluindo o modelo de origem, o próximo modelo, o motivo/detalhe da falha, a posição na cadeia e se o fallback avançou, teve sucesso ou esgotou a cadeia
|
||||
- `model.fallback_step`, incluindo o modelo de origem, próximo modelo, motivo/detalhe da falha, posição na cadeia e se o fallback avançou, teve sucesso ou esgotou a cadeia
|
||||
- `model.completed`
|
||||
- `trace.artifacts`
|
||||
- `session.ended`
|
||||
|
||||
Eventos de transcrição também são reconstruídos a partir do ramo ativo da sessão:
|
||||
Eventos de transcrição também são reconstruídos a partir do branch de sessão ativo:
|
||||
|
||||
- mensagens de usuário
|
||||
- mensagens do usuário
|
||||
- mensagens do assistente
|
||||
- chamadas de ferramenta
|
||||
- resultados de ferramenta
|
||||
- compactações
|
||||
- alterações de modelo
|
||||
- rótulos e entradas personalizadas de sessão
|
||||
- resultados de ferramentas
|
||||
- compactions
|
||||
- mudanças de modelo
|
||||
- rótulos e entradas de sessão personalizadas
|
||||
|
||||
Os eventos são gravados como JSON Lines com este marcador de esquema:
|
||||
Os eventos são gravados como JSON Lines com este marcador de schema:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -121,19 +121,19 @@ Um pacote exportado pode conter:
|
||||
|
||||
| Arquivo | Conteúdo |
|
||||
| --------------------- | ---------------------------------------------------------------------------------------------- |
|
||||
| `manifest.json` | Esquema do pacote, arquivos de origem, contagens de eventos e lista de arquivos gerados |
|
||||
| `manifest.json` | Schema do pacote, arquivos de origem, contagens de eventos e lista de arquivos gerados |
|
||||
| `events.jsonl` | Linha do tempo ordenada de runtime e transcrição |
|
||||
| `session-branch.json` | Ramo de transcrição ativo redigido e cabeçalho da sessão |
|
||||
| `session-branch.json` | Branch de transcrição ativo com informações sensíveis ocultadas e cabeçalho da sessão |
|
||||
| `metadata.json` | Versão do OpenClaw, SO/runtime, modelo, snapshot de configuração, plugins, Skills e metadados de prompt |
|
||||
| `artifacts.json` | Status final, erros, uso, cache de prompt, contagem de compactação, texto do assistente e metadados de ferramentas |
|
||||
| `prompts.json` | Prompts enviados e detalhes selecionados de construção de prompt |
|
||||
| `artifacts.json` | Status final, erros, uso, cache de prompt, contagem de compaction, texto do assistente e metadados de ferramentas |
|
||||
| `prompts.json` | Prompts enviados e detalhes selecionados de construção de prompt |
|
||||
| `system-prompt.txt` | Prompt do sistema compilado mais recente, quando capturado |
|
||||
| `tools.json` | Definições de ferramentas enviadas ao modelo, quando capturadas |
|
||||
|
||||
`manifest.json` lista os arquivos presentes nesse pacote. Alguns arquivos são omitidos
|
||||
`manifest.json` lista os arquivos presentes naquele pacote. Alguns arquivos são omitidos
|
||||
quando a sessão não capturou os dados de runtime correspondentes.
|
||||
|
||||
## Local da captura
|
||||
## Local de captura
|
||||
|
||||
Por padrão, eventos de trajetória de runtime são gravados ao lado do arquivo de sessão:
|
||||
|
||||
@ -154,13 +154,13 @@ diretório dedicado:
|
||||
export OPENCLAW_TRAJECTORY_DIR=/var/lib/openclaw/trajectories
|
||||
```
|
||||
|
||||
Quando essa variável é definida, o OpenClaw grava um arquivo JSONL por ID de sessão nesse
|
||||
Quando essa variável é definida, o OpenClaw grava um arquivo JSONL por id de sessão nesse
|
||||
diretório.
|
||||
|
||||
A manutenção de sessões remove sidecars de trajetória quando sua entrada de sessão proprietária
|
||||
é podada, limitada ou expulsa pelo orçamento de disco de sessões. Arquivos de runtime fora
|
||||
do diretório de sessões são removidos apenas quando o destino do ponteiro ainda comprova que
|
||||
pertence a essa sessão.
|
||||
é podada, limitada ou removida pelo orçamento de disco de sessões. Arquivos de runtime fora
|
||||
do diretório de sessões são removidos somente quando o destino do ponteiro ainda comprova que
|
||||
pertence àquela sessão.
|
||||
|
||||
## Desativar captura
|
||||
|
||||
@ -171,29 +171,29 @@ export OPENCLAW_TRAJECTORY=0
|
||||
```
|
||||
|
||||
Isso desativa a captura de trajetória de runtime. `/export-trajectory` ainda pode exportar
|
||||
o ramo da transcrição, mas arquivos apenas de runtime, como contexto compilado,
|
||||
o branch da transcrição, mas arquivos apenas de runtime, como contexto compilado,
|
||||
artefatos do provedor e metadados de prompt, podem estar ausentes.
|
||||
|
||||
## Privacidade e limites
|
||||
|
||||
Pacotes de trajetória são projetados para suporte e depuração, não para publicação pública.
|
||||
O OpenClaw redige valores sensíveis antes de gravar arquivos de exportação:
|
||||
O OpenClaw oculta valores sensíveis antes de gravar arquivos de exportação:
|
||||
|
||||
- credenciais e campos de payload conhecidos como semelhantes a segredos
|
||||
- credenciais e campos de payload conhecidos com aparência de segredo
|
||||
- dados de imagem
|
||||
- caminhos de estado local
|
||||
- caminhos de workspace, substituídos por `$WORKSPACE_DIR`
|
||||
- caminhos do diretório pessoal, quando detectados
|
||||
- caminhos do workspace, substituídos por `$WORKSPACE_DIR`
|
||||
- caminhos do diretório inicial, quando detectados
|
||||
|
||||
O exportador também limita o tamanho da entrada:
|
||||
|
||||
- arquivos sidecar de runtime: 50 MiB
|
||||
- arquivos sidecar de runtime: a captura ativa para em 10 MiB e registra um evento de truncamento quando ainda há espaço; a exportação aceita sidecars de runtime existentes de até 50 MiB
|
||||
- arquivos de sessão: 50 MiB
|
||||
- eventos de runtime: 200.000
|
||||
- total de eventos exportados: 250.000
|
||||
- linhas individuais de eventos de runtime são truncadas acima de 256 KiB
|
||||
|
||||
Revise os pacotes antes de compartilhá-los fora da sua equipe. A redação é feita por melhor esforço
|
||||
Revise os pacotes antes de compartilhá-los fora da sua equipe. A ocultação é de melhor esforço
|
||||
e não consegue conhecer todos os segredos específicos de cada aplicação.
|
||||
|
||||
## Solução de problemas
|
||||
@ -212,7 +212,7 @@ Se o comando rejeitar o caminho de saída:
|
||||
- mantenha a exportação dentro de `.openclaw/trajectory-exports/`
|
||||
|
||||
Se a exportação falhar com um erro de tamanho, a sessão ou o sidecar excedeu os
|
||||
limites de segurança de exportação. Inicie uma nova sessão ou exporte uma reprodução menor.
|
||||
limites de segurança da exportação. Inicie uma nova sessão ou exporte uma reprodução menor.
|
||||
|
||||
## Relacionado
|
||||
|
||||
|
||||
@ -1,20 +1,20 @@
|
||||
---
|
||||
read_when:
|
||||
- Você deseja operar o Gateway a partir de um navegador
|
||||
- Você quer operar o Gateway a partir de um navegador
|
||||
- Você quer acesso à Tailnet sem túneis SSH
|
||||
sidebarTitle: Control UI
|
||||
summary: Interface de controle baseada no navegador para o Gateway (chat, nós, configuração)
|
||||
summary: Interface de controle baseada no navegador para o Gateway (conversa, nós, configuração)
|
||||
title: Interface de controle
|
||||
x-i18n:
|
||||
generated_at: "2026-05-04T07:04:08Z"
|
||||
generated_at: "2026-05-04T09:37:55Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 07fbbe1c7fec5f67a04a231e02bdf0f7d16be9c5fe188915674d71fcd69002a5
|
||||
source_hash: 4b68b5203b369de6a3354a7e7442ee38ee790875b2d7054b0c8ec997098fd9de
|
||||
source_path: web/control-ui.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
A UI de Controle é um pequeno app de página única **Vite + Lit** servido pelo Gateway:
|
||||
A interface de controle é um pequeno aplicativo de página única **Vite + Lit** servido pelo Gateway:
|
||||
|
||||
- padrão: `http://<host>:18789/`
|
||||
- prefixo opcional: defina `gateway.controlUi.basePath` (por exemplo, `/openclaw`)
|
||||
@ -29,20 +29,20 @@ Se o Gateway estiver em execução no mesmo computador, abra:
|
||||
|
||||
Se a página não carregar, inicie o Gateway primeiro: `openclaw gateway`.
|
||||
|
||||
A autenticação é fornecida durante o handshake do WebSocket por meio de:
|
||||
A autenticação é fornecida durante o handshake do WebSocket via:
|
||||
|
||||
- `connect.params.auth.token`
|
||||
- `connect.params.auth.password`
|
||||
- cabeçalhos de identidade do Tailscale Serve quando `gateway.auth.allowTailscale: true`
|
||||
- cabeçalhos de identidade de proxy confiável quando `gateway.auth.mode: "trusted-proxy"`
|
||||
|
||||
O painel de configurações do dashboard mantém um token para a sessão da aba atual do navegador e para a URL do gateway selecionada; senhas não são persistidas. O onboarding geralmente gera um token do gateway para autenticação por segredo compartilhado na primeira conexão, mas a autenticação por senha também funciona quando `gateway.auth.mode` é `"password"`.
|
||||
O painel de configurações do dashboard mantém um token para a sessão atual da aba do navegador e a URL do gateway selecionada; senhas não são persistidas. O onboarding geralmente gera um token de gateway para autenticação por segredo compartilhado na primeira conexão, mas a autenticação por senha também funciona quando `gateway.auth.mode` é `"password"`.
|
||||
|
||||
## Pareamento de dispositivo (primeira conexão)
|
||||
|
||||
Quando você se conecta à UI de Controle por um novo navegador ou dispositivo, o Gateway geralmente exige uma **aprovação de pareamento única**. Esta é uma medida de segurança para impedir acesso não autorizado.
|
||||
Quando você se conecta à interface de controle a partir de um novo navegador ou dispositivo, o Gateway geralmente exige uma **aprovação de pareamento única**. Esta é uma medida de segurança para impedir acesso não autorizado.
|
||||
|
||||
**O que você verá:** "desconectado (1008): pareamento obrigatório"
|
||||
**O que você verá:** "disconnected (1008): pairing required"
|
||||
|
||||
<Steps>
|
||||
<Step title="Listar solicitações pendentes">
|
||||
@ -57,96 +57,97 @@ Quando você se conecta à UI de Controle por um novo navegador ou dispositivo,
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
Se o navegador tentar parear novamente com detalhes de autenticação alterados (função/escopos/chave pública), a solicitação pendente anterior será substituída e um novo `requestId` será criado. Execute `openclaw devices list` novamente antes da aprovação.
|
||||
Se o navegador tentar parear novamente com detalhes de autenticação alterados (função/escopos/chave pública), a solicitação pendente anterior será substituída e um novo `requestId` será criado. Execute novamente `openclaw devices list` antes da aprovação.
|
||||
|
||||
Se o navegador já estiver pareado e você o alterar de acesso de leitura para acesso de escrita/admin, isso será tratado como uma atualização de aprovação, não como uma reconexão silenciosa. O OpenClaw mantém a aprovação antiga ativa, bloqueia a reconexão mais ampla e solicita que você aprove explicitamente o novo conjunto de escopos.
|
||||
Se o navegador já estiver pareado e você o alterar de acesso de leitura para acesso de escrita/administração, isso será tratado como uma atualização de aprovação, não como uma reconexão silenciosa. O OpenClaw mantém a aprovação antiga ativa, bloqueia a reconexão mais ampla e pede que você aprove explicitamente o novo conjunto de escopos.
|
||||
|
||||
Depois de aprovado, o dispositivo é lembrado e não exigirá nova aprovação, a menos que você o revogue com `openclaw devices revoke --device <id> --role <role>`. Consulte [CLI de Dispositivos](/pt-BR/cli/devices) para rotação e revogação de tokens.
|
||||
Depois de aprovado, o dispositivo é lembrado e não exigirá nova aprovação, a menos que você o revogue com `openclaw devices revoke --device <id> --role <role>`. Consulte [CLI de dispositivos](/pt-BR/cli/devices) para rotação e revogação de tokens.
|
||||
|
||||
<Note>
|
||||
- Conexões diretas de navegador por local loopback (`127.0.0.1` / `localhost`) são aprovadas automaticamente.
|
||||
- O Tailscale Serve pode pular a rodada de pareamento para sessões de operador da UI de Controle quando `gateway.auth.allowTailscale: true`, a identidade do Tailscale é verificada e o navegador apresenta sua identidade de dispositivo.
|
||||
- Vínculos diretos de Tailnet, conexões de navegador pela LAN e perfis de navegador sem identidade de dispositivo ainda exigem aprovação explícita.
|
||||
- Cada perfil de navegador gera um ID de dispositivo exclusivo, portanto trocar de navegador ou limpar os dados do navegador exigirá novo pareamento.
|
||||
- Conexões diretas do navegador via local loopback (`127.0.0.1` / `localhost`) são aprovadas automaticamente.
|
||||
- O Tailscale Serve pode ignorar a ida e volta de pareamento para sessões de operador da interface de controle quando `gateway.auth.allowTailscale: true`, a identidade do Tailscale é verificada e o navegador apresenta sua identidade de dispositivo.
|
||||
- Vinculações diretas de Tailnet, conexões de navegador na LAN e perfis de navegador sem identidade de dispositivo ainda exigem aprovação explícita.
|
||||
- Cada perfil de navegador gera um ID de dispositivo único, portanto trocar de navegador ou limpar os dados do navegador exigirá novo pareamento.
|
||||
|
||||
</Note>
|
||||
|
||||
## Identidade pessoal (local do navegador)
|
||||
|
||||
A UI de Controle oferece suporte a uma identidade pessoal por navegador (nome de exibição e avatar) anexada às mensagens de saída para atribuição em sessões compartilhadas. Ela fica no armazenamento do navegador, tem escopo no perfil atual do navegador e não é sincronizada com outros dispositivos nem persistida no servidor além dos metadados normais de autoria do transcript nas mensagens que você realmente envia. Limpar os dados do site ou trocar de navegador redefine isso para vazio.
|
||||
A interface de controle oferece suporte a uma identidade pessoal por navegador (nome de exibição e avatar) anexada às mensagens enviadas para atribuição em sessões compartilhadas. Ela fica no armazenamento do navegador, é limitada ao perfil atual do navegador e não é sincronizada com outros dispositivos nem persistida no servidor além dos metadados normais de autoria do transcript nas mensagens que você realmente envia. Limpar os dados do site ou trocar de navegador a redefine para vazio.
|
||||
|
||||
O mesmo padrão local do navegador se aplica à substituição do avatar do assistente. Avatares de assistente enviados sobrepõem a identidade resolvida pelo gateway apenas no navegador local e nunca fazem ida e volta por `config.patch`. O campo de configuração compartilhado `ui.assistant.avatar` ainda está disponível para clientes que não sejam de UI gravarem o campo diretamente (como gateways roteirizados ou dashboards personalizados).
|
||||
O mesmo padrão local do navegador se aplica à substituição do avatar do assistente. Avatares de assistente enviados sobrepõem a identidade resolvida pelo gateway apenas no navegador local e nunca fazem ida e volta por `config.patch`. O campo de configuração compartilhado `ui.assistant.avatar` ainda está disponível para clientes que não são da interface escrevendo o campo diretamente (como gateways com script ou dashboards personalizados).
|
||||
|
||||
## Endpoint de configuração em runtime
|
||||
## Endpoint de configuração de runtime
|
||||
|
||||
A UI de Controle busca suas configurações em runtime em `/__openclaw/control-ui-config.json`. Esse endpoint é protegido pela mesma autenticação do gateway que o restante da superfície HTTP: navegadores não autenticados não conseguem buscá-lo, e uma busca bem-sucedida exige um token/senha de gateway já válido, identidade do Tailscale Serve ou identidade de proxy confiável.
|
||||
A interface de controle busca suas configurações de runtime em `/__openclaw/control-ui-config.json`. Esse endpoint é protegido pela mesma autenticação do gateway que o restante da superfície HTTP: navegadores não autenticados não conseguem buscá-lo, e uma busca bem-sucedida exige um token/senha de gateway já válido, identidade do Tailscale Serve ou identidade de proxy confiável.
|
||||
|
||||
## Suporte a idiomas
|
||||
|
||||
A UI de Controle pode se localizar no primeiro carregamento com base no idioma do seu navegador. Para substituí-lo depois, abra **Visão geral -> Acesso ao Gateway -> Idioma**. O seletor de localidade fica no cartão Acesso ao Gateway, não em Aparência.
|
||||
A interface de controle pode se localizar no primeiro carregamento com base na localidade do seu navegador. Para substituí-la depois, abra **Visão geral -> Acesso ao Gateway -> Idioma**. O seletor de localidade fica no cartão Acesso ao Gateway, não em Aparência.
|
||||
|
||||
- Localidades compatíveis: `en`, `zh-CN`, `zh-TW`, `pt-BR`, `de`, `es`, `ja-JP`, `ko`, `fr`, `ar`, `it`, `tr`, `uk`, `id`, `pl`, `th`, `vi`, `nl`, `fa`
|
||||
- Traduções para idiomas diferentes do inglês são carregadas sob demanda no navegador.
|
||||
- Traduções que não sejam em inglês são carregadas sob demanda no navegador.
|
||||
- A localidade selecionada é salva no armazenamento do navegador e reutilizada em visitas futuras.
|
||||
- Chaves de tradução ausentes usam inglês como fallback.
|
||||
- Chaves de tradução ausentes recorrem ao inglês.
|
||||
|
||||
As traduções da documentação são geradas para o mesmo conjunto de localidades diferentes do inglês, mas o seletor de idiomas integrado do site de documentação do Mintlify é limitado aos códigos de localidade aceitos pelo Mintlify. A documentação em tailandês (`th`) e persa (`fa`) ainda é gerada no repositório de publicação; ela pode não aparecer nesse seletor até que o Mintlify ofereça suporte a esses códigos.
|
||||
As traduções da documentação são geradas para o mesmo conjunto de localidades que não são em inglês, mas o seletor de idioma integrado do site de documentação no Mintlify é limitado aos códigos de localidade aceitos pelo Mintlify. A documentação em tailandês (`th`) e persa (`fa`) ainda é gerada no repositório de publicação; ela pode não aparecer nesse seletor até que o Mintlify ofereça suporte a esses códigos.
|
||||
|
||||
## Temas de aparência
|
||||
|
||||
O painel Aparência mantém os temas integrados Claw, Knot e Dash, além de um slot de importação tweakcn local do navegador. Para importar um tema, abra o [editor tweakcn](https://tweakcn.com/editor/theme), escolha ou crie um tema, clique em **Compartilhar** e cole o link do tema copiado em Aparência. O importador também aceita URLs de registro `https://tweakcn.com/r/themes/<id>`, URLs do editor como `https://tweakcn.com/editor/theme?theme=amethyst-haze`, caminhos relativos `/themes/<id>`, IDs brutos de tema e nomes de tema padrão como `amethyst-haze`.
|
||||
O painel Aparência mantém os temas integrados Claw, Knot e Dash, além de um slot de importação tweakcn local do navegador. Para importar um tema, abra o [editor tweakcn](https://tweakcn.com/editor/theme), escolha ou crie um tema, clique em **Compartilhar** e cole o link do tema copiado em Aparência. O importador também aceita URLs de registro `https://tweakcn.com/r/themes/<id>`, URLs do editor como `https://tweakcn.com/editor/theme?theme=amethyst-haze`, caminhos relativos `/themes/<id>`, IDs de tema brutos e nomes de tema padrão como `amethyst-haze`.
|
||||
|
||||
Temas importados são armazenados apenas no perfil atual do navegador. Eles não são gravados na configuração do gateway e não são sincronizados entre dispositivos. Substituir o tema importado atualiza o único slot local; limpá-lo troca o tema ativo de volta para Claw se o tema importado estava selecionado.
|
||||
Temas importados são armazenados apenas no perfil atual do navegador. Eles não são gravados na configuração do gateway e não são sincronizados entre dispositivos. Substituir o tema importado atualiza o único slot local; limpá-lo muda o tema ativo de volta para Claw se o tema importado estava selecionado.
|
||||
|
||||
## O que ela consegue fazer (hoje)
|
||||
## O que ela pode fazer (hoje)
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Chat e Conversa por Voz">
|
||||
- Converse com o modelo via WS do Gateway (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`).
|
||||
- Converse por meio de sessões em tempo real do navegador. A OpenAI usa WebRTC direto, o Google Live usa um token de navegador restrito e de uso único por WebSocket, e plugins de voz em tempo real somente de backend usam o transporte de retransmissão do Gateway. A retransmissão mantém as credenciais do provedor no Gateway enquanto o navegador transmite PCM do microfone por RPCs `talk.realtime.relay*` e envia chamadas de ferramenta `openclaw_agent_consult` de volta por `chat.send` para o modelo OpenClaw maior configurado.
|
||||
<Accordion title="Chat e fala">
|
||||
- Converse com o modelo via Gateway WS (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`).
|
||||
- Fale por sessões em tempo real do navegador. A OpenAI usa WebRTC direto, o Google Live usa um token de navegador restrito e de uso único por WebSocket, e plugins de voz em tempo real somente de backend usam o transporte de retransmissão do Gateway. A retransmissão mantém as credenciais do provedor no Gateway enquanto o navegador transmite PCM do microfone por RPCs `talk.realtime.relay*` e envia chamadas de ferramenta `openclaw_agent_consult` de volta por `chat.send` para o modelo maior do OpenClaw configurado.
|
||||
- Transmita chamadas de ferramenta + cartões de saída de ferramenta ao vivo no Chat (eventos do agente).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Canais, instâncias, sessões, dreams">
|
||||
- Canais: status de canais integrados e de canais de plugins empacotados/externos, login por QR e configuração por canal (`channels.status`, `web.login.*`, `config.patch`).
|
||||
<Accordion title="Canais, instâncias, sessões, sonhos">
|
||||
- Canais: status de canais integrados e de plugins empacotados/externos, login por QR e configuração por canal (`channels.status`, `web.login.*`, `config.patch`).
|
||||
- Instâncias: lista de presença + atualização (`system-presence`).
|
||||
- Sessões: lista + substituições por sessão de modelo/thinking/rápido/verboso/trace/reasoning (`sessions.list`, `sessions.patch`).
|
||||
- Dreams: status de dreaming, alternância para ativar/desativar e leitor do Dream Diary (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`).
|
||||
- Sessões: lista + substituições por sessão de modelo/thinking/rápido/verbose/trace/reasoning (`sessions.list`, `sessions.patch`).
|
||||
- Sonhos: status de dreaming, alternância para ativar/desativar e leitor do Diário de sonhos (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Cron, Skills, nodes, aprovações de exec">
|
||||
- Jobs de Cron: listar/adicionar/editar/executar/ativar/desativar + histórico de execuções (`cron.*`).
|
||||
<Accordion title="Cron, Skills, nós, aprovações de exec">
|
||||
- Tarefas Cron: listar/adicionar/editar/executar/ativar/desativar + histórico de execução (`cron.*`).
|
||||
- Skills: status, ativar/desativar, instalar, atualizações de chave de API (`skills.*`).
|
||||
- Nodes: lista + capacidades (`node.list`).
|
||||
- Aprovações de exec: editar allowlists do gateway ou node + política de solicitação para `exec host=gateway/node` (`exec.approvals.*`).
|
||||
- Nós: lista + capacidades (`node.list`).
|
||||
- Aprovações de exec: edite allowlists de gateway ou nó + política de solicitação para `exec host=gateway/node` (`exec.approvals.*`).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Configuração">
|
||||
- Visualize/edite `~/.openclaw/openclaw.json` (`config.get`, `config.set`).
|
||||
- Aplique + reinicie com validação (`config.apply`) e acorde a última sessão ativa.
|
||||
- Gravações incluem uma proteção por hash base para evitar sobrescrever edições concorrentes.
|
||||
- Gravações (`config.set`/`config.apply`/`config.patch`) fazem pré-validação da resolução de SecretRef ativa para refs no payload de configuração enviado; refs enviadas ativas não resolvidas são rejeitadas antes da gravação.
|
||||
- Renderização de esquema + formulário (`config.schema` / `config.schema.lookup`, incluindo `title` / `description` de campo, dicas de UI correspondentes, resumos de filhos imediatos, metadados de documentação em nodes aninhados de objeto/wildcard/array/composição, além de esquemas de plugin + canal quando disponíveis); o editor JSON bruto só fica disponível quando o snapshot tem uma ida e volta bruta segura.
|
||||
- Se um snapshot não puder fazer ida e volta de texto bruto com segurança, a UI de Controle força o modo Formulário e desativa o modo Bruto para esse snapshot.
|
||||
- "Redefinir para salvo" no editor JSON bruto preserva o formato autorado em bruto (formatação, comentários, layout de `$include`) em vez de renderizar novamente um snapshot achatado, de modo que edições externas sobrevivam a uma redefinição quando o snapshot puder fazer ida e volta com segurança.
|
||||
- Valores de objeto SecretRef estruturados são renderizados como somente leitura em entradas de texto do formulário para evitar corrupção acidental de objeto para string.
|
||||
- Gravações incluem uma proteção de hash base para impedir sobrescrever edições concorrentes.
|
||||
- Gravações (`config.set`/`config.apply`/`config.patch`) verificam antecipadamente a resolução de SecretRef ativo para refs no payload de configuração enviado; refs enviados ativos não resolvidos são rejeitados antes da gravação.
|
||||
- Esquema + renderização de formulário (`config.schema` / `config.schema.lookup`, incluindo `title` / `description` de campo, dicas de UI correspondentes, resumos de filhos imediatos, metadados de documentação em nós aninhados de objeto/wildcard/array/composition, além de esquemas de plugin + canal quando disponíveis); o editor JSON bruto fica disponível apenas quando o snapshot tem uma ida e volta bruta segura.
|
||||
- Se um snapshot não puder fazer ida e volta de texto bruto com segurança, a interface de controle força o modo Formulário e desativa o modo Bruto para esse snapshot.
|
||||
- "Redefinir para salvo" do editor JSON bruto preserva o formato escrito no bruto (formatação, comentários, layout de `$include`) em vez de renderizar novamente um snapshot achatado, para que edições externas sobrevivam a uma redefinição quando o snapshot puder fazer ida e volta com segurança.
|
||||
- Valores de objeto SecretRef estruturados são renderizados como somente leitura em entradas de texto de formulário para impedir corrupção acidental de objeto para string.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Depuração, logs, atualização">
|
||||
- Depuração: snapshots de status/saúde/modelos + log de eventos + chamadas RPC manuais (`status`, `health`, `models.list`).
|
||||
- O log de eventos inclui tempos de atualização/RPC da interface de controle, além de entradas de responsividade do navegador para quadros de animação longos ou tarefas longas quando o navegador expõe esses tipos de entrada PerformanceObserver.
|
||||
- Logs: acompanhamento ao vivo dos logs de arquivo do gateway com filtro/exportação (`logs.tail`).
|
||||
- Atualização: execute uma atualização de pacote/git + reinicie (`update.run`) com um relatório de reinicialização e, depois, consulte `update.status` após reconectar para verificar a versão do gateway em execução.
|
||||
- Atualização: execute uma atualização de pacote/git + reinicialização (`update.run`) com um relatório de reinicialização e, em seguida, consulte `update.status` após reconectar para verificar a versão do gateway em execução.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Observações do painel de jobs de Cron">
|
||||
- Para jobs isolados, a entrega usa resumo de anúncio como padrão. Você pode mudar para nenhuma se quiser execuções apenas internas.
|
||||
- Os campos de canal/destino aparecem quando anúncio é selecionado.
|
||||
<Accordion title="Notas do painel de tarefas Cron">
|
||||
- Para tarefas isoladas, a entrega tem como padrão anunciar resumo. Você pode mudar para nenhum se quiser execuções apenas internas.
|
||||
- Campos de canal/destino aparecem quando anunciar está selecionado.
|
||||
- O modo Webhook usa `delivery.mode = "webhook"` com `delivery.to` definido como uma URL de webhook HTTP(S) válida.
|
||||
- Para jobs de sessão principal, os modos de entrega Webhook e nenhuma estão disponíveis.
|
||||
- Controles de edição avançada incluem excluir após execução, limpar substituição de agente, opções exatas/escalonadas de cron, substituições de modelo/thinking do agente e alternâncias de entrega por melhor esforço.
|
||||
- A validação do formulário é inline com erros por campo; valores inválidos desativam o botão de salvar até serem corrigidos.
|
||||
- Para tarefas de sessão principal, os modos de entrega webhook e nenhum estão disponíveis.
|
||||
- Controles avançados de edição incluem excluir após execução, limpar substituição de agente, opções exatas/escalonadas de cron, substituições de modelo/thinking do agente e alternâncias de entrega por melhor esforço.
|
||||
- A validação de formulário é inline com erros em nível de campo; valores inválidos desativam o botão salvar até serem corrigidos.
|
||||
- Defina `cron.webhookToken` para enviar um token bearer dedicado; se omitido, o webhook é enviado sem cabeçalho de autenticação.
|
||||
- Fallback obsoleto: jobs legados armazenados com `notify: true` ainda podem usar `cron.webhook` até serem migrados.
|
||||
- Fallback obsoleto: tarefas legadas armazenadas com `notify: true` ainda podem usar `cron.webhook` até serem migradas.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -155,51 +156,54 @@ Temas importados são armazenados apenas no perfil atual do navegador. Eles não
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Semântica de envio e histórico">
|
||||
- `chat.send` é **não bloqueante**: confirma imediatamente com `{ runId, status: "started" }` e a resposta é transmitida via eventos `chat`.
|
||||
- Uploads de chat aceitam imagens e arquivos que não sejam vídeos. Imagens mantêm o caminho de imagem nativo; outros arquivos são armazenados como mídia gerenciada e exibidos no histórico como links de anexo.
|
||||
- Reenviar com o mesmo `idempotencyKey` retorna `{ status: "in_flight" }` enquanto estiver em execução, e `{ status: "ok" }` após a conclusão.
|
||||
- As respostas de `chat.history` têm limite de tamanho para segurança da UI. Quando entradas da transcrição são grandes demais, o Gateway pode truncar campos de texto longos, omitir blocos pesados de metadados e substituir mensagens grandes demais por um placeholder (`[chat.history omitted: message too large]`).
|
||||
- Imagens do assistente/geradas são persistidas como referências de mídia gerenciada e servidas de volta por URLs de mídia autenticadas do Gateway, para que recarregamentos não dependam de payloads brutos de imagem em base64 permanecerem na resposta do histórico de chat.
|
||||
- `chat.history` também remove tags de diretivas inline apenas de exibição do texto visível do assistente (por exemplo `[[reply_to_*]]` e `[[audio_as_voice]]`), payloads XML de chamadas de ferramenta em texto puro (incluindo `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>` e blocos truncados de chamadas de ferramenta), além de tokens de controle do modelo ASCII/de largura cheia vazados, e omite entradas do assistente cujo texto visível inteiro seja apenas o token silencioso exato `NO_REPLY` / `no_reply`.
|
||||
- Durante um envio ativo e a atualização final do histórico, a visualização de chat mantém visíveis as mensagens locais otimistas do usuário/assistente se `chat.history` retornar brevemente um snapshot mais antigo; a transcrição canônica substitui essas mensagens locais quando o histórico do Gateway se atualiza.
|
||||
- `chat.send` é **não bloqueante**: confirma imediatamente com `{ runId, status: "started" }` e a resposta é transmitida por eventos `chat`.
|
||||
- Uploads de chat aceitam imagens e arquivos que não sejam vídeo. Imagens mantêm o caminho de imagem nativo; outros arquivos são armazenados como mídia gerenciada e exibidos no histórico como links de anexos.
|
||||
- Reenviar com a mesma `idempotencyKey` retorna `{ status: "in_flight" }` enquanto estiver em execução, e `{ status: "ok" }` após a conclusão.
|
||||
- As respostas de `chat.history` têm tamanho limitado para segurança da UI. Quando entradas da transcrição são grandes demais, o Gateway pode truncar campos de texto longos, omitir blocos pesados de metadados e substituir mensagens grandes demais por um espaço reservado (`[chat.history omitted: message too large]`).
|
||||
- Imagens de assistente/geradas são persistidas como referências de mídia gerenciada e servidas de volta por URLs de mídia autenticadas do Gateway, então recarregamentos não dependem de payloads brutos de imagem em base64 permanecerem na resposta do histórico de chat.
|
||||
- `chat.history` também remove tags de diretiva inline somente de exibição do texto visível do assistente (por exemplo `[[reply_to_*]]` e `[[audio_as_voice]]`), payloads XML de chamadas de ferramenta em texto simples (incluindo `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>` e blocos truncados de chamadas de ferramenta), e tokens vazados de controle do modelo em ASCII/largura completa, e omite entradas do assistente cujo texto visível inteiro seja apenas o token silencioso exato `NO_REPLY` / `no_reply`.
|
||||
- Durante um envio ativo e a atualização final do histórico, a visualização de chat mantém mensagens locais otimistas do usuário/assistente visíveis se `chat.history` retornar brevemente um snapshot mais antigo; a transcrição canônica substitui essas mensagens locais quando o histórico do Gateway se atualiza.
|
||||
- Eventos `chat` ao vivo são estado de entrega, enquanto `chat.history` é reconstruído a partir da transcrição durável da sessão. Após eventos finais de ferramenta, a Control UI recarrega o histórico e mescla apenas uma pequena cauda otimista; o limite da transcrição está documentado em [WebChat](/pt-BR/web/webchat).
|
||||
- `chat.inject` anexa uma nota do assistente à transcrição da sessão e transmite um evento `chat` para atualizações apenas da UI (sem execução de agente, sem entrega por canal).
|
||||
- Os seletores de modelo e de raciocínio no cabeçalho do chat aplicam patch à sessão ativa imediatamente por `sessions.patch`; eles são substituições persistentes de sessão, não opções de envio válidas apenas para uma interação.
|
||||
- Digitar `/new` na Control UI cria e alterna para a mesma nova sessão do painel que New Chat. Digitar `/reset` mantém a redefinição explícita in-place do Gateway para a sessão atual.
|
||||
- O seletor de modelo do chat solicita a visualização de modelos configurada do Gateway. Se `agents.defaults.models` estiver presente, essa lista de permissões orienta o seletor. Caso contrário, o seletor mostra entradas explícitas de `models.providers.*.models` e provedores com autenticação utilizável. O catálogo completo continua disponível pelo RPC de depuração `models.list` com `view: "all"`.
|
||||
- Quando relatórios recentes de uso da sessão do Gateway mostram alta pressão de contexto, a área do compositor de chat exibe um aviso de contexto e, nos níveis recomendados de Compaction, um botão compacto que executa o caminho normal de Compaction da sessão. Snapshots obsoletos de tokens ficam ocultos até que o Gateway relate uso recente novamente.
|
||||
- `chat.inject` anexa uma nota do assistente à transcrição da sessão e transmite um evento `chat` para atualizações somente de UI (sem execução de agente, sem entrega de canal).
|
||||
- O cabeçalho do chat mostra o filtro de agente antes do seletor de sessão, e o seletor de sessão é limitado ao agente selecionado. Trocar de agente mostra apenas sessões vinculadas a esse agente e volta para a sessão principal desse agente quando ele ainda não tem sessões de painel salvas.
|
||||
- Em larguras de desktop, os controles de chat permanecem em uma única linha compacta e recolhem ao rolar para baixo na transcrição; rolar para cima, voltar ao topo ou chegar ao fim restaura os controles.
|
||||
- Mensagens consecutivas duplicadas somente de texto são renderizadas como um único balão com um selo de contagem. Mensagens que carregam imagens, anexos, saída de ferramenta ou pré-visualizações de canvas não são recolhidas.
|
||||
- Os seletores de modelo e raciocínio do cabeçalho do chat aplicam patch à sessão ativa imediatamente por meio de `sessions.patch`; eles são substituições persistentes de sessão, não opções de envio válidas apenas para um turno.
|
||||
- Digitar `/new` na Control UI cria e alterna para a mesma nova sessão de painel que New Chat. Digitar `/reset` mantém a redefinição explícita in-place do Gateway para a sessão atual.
|
||||
- O seletor de modelo do chat solicita a visualização de modelos configurada do Gateway. Se `agents.defaults.models` estiver presente, essa allowlist orienta o seletor. Caso contrário, o seletor mostra entradas explícitas de `models.providers.*.models` mais provedores com autenticação utilizável. O catálogo completo continua disponível pelo RPC de depuração `models.list` com `view: "all"`.
|
||||
- Quando relatórios recentes de uso da sessão do Gateway mostram alta pressão de contexto, a área do compositor de chat mostra um aviso de contexto e, nos níveis recomendados de Compaction, um botão compacto que executa o caminho normal de Compaction da sessão. Snapshots obsoletos de tokens ficam ocultos até que o Gateway reporte uso recente novamente.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Modo de conversa (tempo real no navegador)">
|
||||
O modo de conversa usa um provedor de voz em tempo real registrado. Configure a OpenAI com `talk.provider: "openai"` mais `talk.providers.openai.apiKey`, ou configure o Google com `talk.provider: "google"` mais `talk.providers.google.apiKey`; a configuração do provedor em tempo real de Voice Call ainda pode ser reutilizada como fallback. O navegador nunca recebe uma chave de API padrão do provedor. A OpenAI recebe um segredo efêmero de cliente Realtime para WebRTC. O Google Live recebe um token de autenticação Live API restrito e de uso único para uma sessão WebSocket do navegador, com instruções e declarações de ferramentas bloqueadas no token pelo Gateway. Provedores que expõem apenas uma ponte em tempo real de backend passam pelo transporte de retransmissão do Gateway, de modo que credenciais e sockets de fornecedor permaneçam no servidor enquanto o áudio do navegador passa por RPCs autenticados do Gateway. O prompt da sessão Realtime é montado pelo Gateway; `talk.realtime.session` não aceita substituições de instruções fornecidas pelo chamador.
|
||||
O modo de conversa usa um provedor de voz em tempo real registrado. Configure a OpenAI com `talk.provider: "openai"` mais `talk.providers.openai.apiKey`, ou configure o Google com `talk.provider: "google"` mais `talk.providers.google.apiKey`; a configuração de provedor em tempo real de Voice Call ainda pode ser reutilizada como fallback. O navegador nunca recebe uma chave de API de provedor padrão. A OpenAI recebe um segredo efêmero de cliente Realtime para WebRTC. O Google Live recebe um token de autenticação Live API restrito e de uso único para uma sessão WebSocket no navegador, com instruções e declarações de ferramentas bloqueadas no token pelo Gateway. Provedores que expõem apenas uma ponte em tempo real de backend passam pelo transporte de relay do Gateway, então credenciais e sockets de fornecedor permanecem no lado do servidor enquanto o áudio do navegador passa por RPCs autenticados do Gateway. O prompt da sessão Realtime é montado pelo Gateway; `talk.realtime.session` não aceita substituições de instrução fornecidas pelo chamador.
|
||||
|
||||
No compositor de Chat, o controle Talk é o botão de ondas ao lado do botão de ditado por microfone. Quando Talk inicia, a linha de status do compositor mostra `Connecting Talk...`, depois `Talk live` enquanto o áudio está conectado, ou `Asking OpenClaw...` enquanto uma chamada de ferramenta em tempo real consulta o modelo maior configurado por `chat.send`.
|
||||
No compositor de Chat, o controle de conversa é o botão de ondas ao lado do botão de ditado por microfone. Quando a conversa inicia, a linha de status do compositor mostra `Connecting Talk...`, depois `Talk live` enquanto o áudio está conectado, ou `Asking OpenClaw...` enquanto uma chamada de ferramenta em tempo real consulta o modelo maior configurado por meio de `chat.send`.
|
||||
|
||||
Smoke ao vivo para mantenedores: `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` verifica a troca SDP do WebRTC de navegador da OpenAI, a configuração do WebSocket de navegador com token restrito do Google Live e o adaptador de navegador de retransmissão do Gateway com mídia de microfone falsa. O comando imprime apenas o status do provedor e não registra segredos.
|
||||
Smoke ao vivo de mantenedor: `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` verifica a troca de SDP WebRTC do navegador da OpenAI, a configuração de WebSocket no navegador com token restrito do Google Live e o adaptador de navegador do relay do Gateway com mídia de microfone falsa. O comando imprime apenas o status do provedor e não registra segredos.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Parar e abortar">
|
||||
- Clique em **Parar** (chama `chat.abort`).
|
||||
- Enquanto uma execução está ativa, acompanhamentos normais entram na fila. Clique em **Direcionar** em uma mensagem enfileirada para injetar esse acompanhamento na interação em execução.
|
||||
- Digite `/stop` (ou frases autônomas de abortar como `stop`, `stop action`, `stop run`, `stop openclaw`, `please stop`) para abortar fora da banda.
|
||||
- `chat.abort` aceita `{ sessionKey }` (sem `runId`) para abortar todas as execuções ativas dessa sessão.
|
||||
- Enquanto uma execução está ativa, acompanhamentos normais entram na fila. Clique em **Direcionar** em uma mensagem na fila para injetar esse acompanhamento no turno em execução.
|
||||
- Digite `/stop` (ou frases de aborto isoladas como `stop`, `stop action`, `stop run`, `stop openclaw`, `please stop`) para abortar fora da banda.
|
||||
- `chat.abort` oferece suporte a `{ sessionKey }` (sem `runId`) para abortar todas as execuções ativas dessa sessão.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Retenção parcial após abortar">
|
||||
- Quando uma execução é abortada, texto parcial do assistente ainda pode ser mostrado na UI.
|
||||
- O Gateway persiste texto parcial abortado do assistente no histórico da transcrição quando há saída em buffer.
|
||||
- Entradas persistidas incluem metadados de abortamento para que consumidores da transcrição consigam distinguir parciais abortadas de saída de conclusão normal.
|
||||
<Accordion title="Retenção parcial de aborto">
|
||||
- Quando uma execução é abortada, o texto parcial do assistente ainda pode ser mostrado na UI.
|
||||
- O Gateway persiste texto parcial abortado do assistente no histórico da transcrição quando existe saída em buffer.
|
||||
- Entradas persistidas incluem metadados de aborto para que consumidores da transcrição consigam diferenciar parciais de aborto de saída de conclusão normal.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Instalação PWA e web push
|
||||
## Instalação de PWA e web push
|
||||
|
||||
A Control UI inclui um `manifest.webmanifest` e um service worker, então navegadores modernos podem instalá-la como uma PWA independente. Web Push permite que o Gateway acorde a PWA instalada com notificações mesmo quando a aba ou janela do navegador não está aberta.
|
||||
A Control UI inclui um `manifest.webmanifest` e um service worker, então navegadores modernos podem instalá-la como uma PWA standalone. Web Push permite que o Gateway desperte a PWA instalada com notificações mesmo quando a aba ou a janela do navegador não está aberta.
|
||||
|
||||
| Superfície | O que faz |
|
||||
| Superfície | O que faz |
|
||||
| ----------------------------------------------------- | ------------------------------------------------------------------ |
|
||||
| `ui/public/manifest.webmanifest` | Manifesto PWA. Navegadores oferecem "Instalar app" quando ele está acessível. |
|
||||
| `ui/public/manifest.webmanifest` | Manifesto da PWA. Navegadores oferecem "Instalar app" quando ele está acessível. |
|
||||
| `ui/public/sw.js` | Service worker que lida com eventos `push` e cliques em notificações. |
|
||||
| `push/vapid-keys.json` (no diretório de estado do OpenClaw) | Par de chaves VAPID gerado automaticamente usado para assinar payloads de Web Push. |
|
||||
| `push/web-push-subscriptions.json` | Endpoints de assinatura de navegador persistidos. |
|
||||
@ -210,7 +214,7 @@ Substitua o par de chaves VAPID por variáveis de ambiente no processo do Gatewa
|
||||
- `OPENCLAW_VAPID_PRIVATE_KEY`
|
||||
- `OPENCLAW_VAPID_SUBJECT` (o padrão é `mailto:openclaw@localhost`)
|
||||
|
||||
A Control UI usa estes métodos do Gateway com escopo restrito para registrar e testar assinaturas do navegador:
|
||||
A Control UI usa estes métodos do Gateway restritos por escopo para registrar e testar assinaturas de navegador:
|
||||
|
||||
- `push.web.vapidPublicKey` — busca a chave pública VAPID ativa.
|
||||
- `push.web.subscribe` — registra um `endpoint` mais `keys.p256dh`/`keys.auth`.
|
||||
@ -218,7 +222,7 @@ A Control UI usa estes métodos do Gateway com escopo restrito para registrar e
|
||||
- `push.web.test` — envia uma notificação de teste para a assinatura do chamador.
|
||||
|
||||
<Note>
|
||||
Web Push é independente do caminho de retransmissão APNS do iOS (veja [Configuração](/pt-BR/gateway/configuration) para push com retransmissão) e do método `push.test` existente, que miram o pareamento móvel nativo.
|
||||
Web Push é independente do caminho de relay APNS do iOS (consulte [Configuração](/pt-BR/gateway/configuration) para push com suporte por relay) e do método existente `push.test`, que mira o pareamento móvel nativo.
|
||||
</Note>
|
||||
|
||||
## Embeds hospedados
|
||||
@ -227,13 +231,13 @@ Mensagens do assistente podem renderizar conteúdo web hospedado inline com o sh
|
||||
|
||||
<Tabs>
|
||||
<Tab title="strict">
|
||||
Desativa a execução de scripts dentro de embeds hospedados.
|
||||
Desabilita a execução de scripts dentro de embeds hospedados.
|
||||
</Tab>
|
||||
<Tab title="scripts (padrão)">
|
||||
Permite embeds interativos mantendo o isolamento de origem; esse é o padrão e normalmente é suficiente para jogos/widgets de navegador autossuficientes.
|
||||
<Tab title="scripts (default)">
|
||||
Permite embeds interativos mantendo o isolamento de origem; este é o padrão e geralmente é suficiente para jogos/widgets de navegador autocontidos.
|
||||
</Tab>
|
||||
<Tab title="trusted">
|
||||
Adiciona `allow-same-origin` sobre `allow-scripts` para documentos do mesmo site que intencionalmente precisam de privilégios mais fortes.
|
||||
Adiciona `allow-same-origin` sobre `allow-scripts` para documentos no mesmo site que intencionalmente precisam de privilégios mais fortes.
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
@ -250,10 +254,10 @@ Exemplo:
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Use `trusted` somente quando o documento incorporado realmente precisar de comportamento de mesma origem. Para a maioria dos jogos e canvases interativos gerados por agente, `scripts` é a escolha mais segura.
|
||||
Use `trusted` apenas quando o documento incorporado realmente precisar de comportamento de mesma origem. Para a maioria dos jogos gerados por agentes e canvas interativos, `scripts` é a escolha mais segura.
|
||||
</Warning>
|
||||
|
||||
URLs absolutas externas de embed `http(s)` permanecem bloqueadas por padrão. Se você quiser intencionalmente que `[embed url="https://..."]` carregue páginas de terceiros, defina `gateway.controlUi.allowExternalEmbedUrls: true`.
|
||||
URLs absolutas externas de embed `http(s)` permanecem bloqueadas por padrão. Se você intencionalmente quiser que `[embed url="https://..."]` carregue páginas de terceiros, defina `gateway.controlUi.allowExternalEmbedUrls: true`.
|
||||
|
||||
## Largura da mensagem de chat
|
||||
|
||||
@ -269,13 +273,13 @@ Mensagens de chat agrupadas usam uma largura máxima padrão legível. Implanta
|
||||
}
|
||||
```
|
||||
|
||||
O valor é validado antes de chegar ao navegador. Valores compatíveis incluem comprimentos e porcentagens simples, como `960px` ou `82%`, além de expressões de largura restritas `min(...)`, `max(...)`, `clamp(...)`, `calc(...)` e `fit-content(...)`.
|
||||
O valor é validado antes de chegar ao navegador. Valores aceitos incluem comprimentos simples e porcentagens como `960px` ou `82%`, além de expressões de largura restritas `min(...)`, `max(...)`, `clamp(...)`, `calc(...)` e `fit-content(...)`.
|
||||
|
||||
## Acesso pela tailnet (recomendado)
|
||||
## Acesso à tailnet (recomendado)
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Tailscale Serve integrado (preferido)">
|
||||
Mantenha o Gateway em local loopback e deixe o Tailscale Serve fazer proxy dele com HTTPS:
|
||||
Mantenha o Gateway em loopback e deixe o Tailscale Serve fazer proxy dele com HTTPS:
|
||||
|
||||
```bash
|
||||
openclaw gateway --tailscale serve
|
||||
@ -285,9 +289,9 @@ O valor é validado antes de chegar ao navegador. Valores compatíveis incluem c
|
||||
|
||||
- `https://<magicdns>/` (ou seu `gateway.controlUi.basePath` configurado)
|
||||
|
||||
Por padrão, solicitações Serve da Control UI/WebSocket podem autenticar via cabeçalhos de identidade do Tailscale (`tailscale-user-login`) quando `gateway.auth.allowTailscale` é `true`. O OpenClaw verifica a identidade resolvendo o endereço `x-forwarded-for` com `tailscale whois` e correspondendo-o ao cabeçalho, e aceita esses cabeçalhos apenas quando a solicitação chega ao loopback com os cabeçalhos `x-forwarded-*` do Tailscale. Para sessões de operador da Control UI com identidade de dispositivo no navegador, esse caminho Serve verificado também pula a ida e volta de pareamento de dispositivo; navegadores sem dispositivo e conexões com função de nó ainda seguem as verificações normais de dispositivo. Defina `gateway.auth.allowTailscale: false` se quiser exigir credenciais explícitas de segredo compartilhado mesmo para tráfego Serve. Depois use `gateway.auth.mode: "token"` ou `"password"`.
|
||||
Por padrão, solicitações Serve da Control UI/WebSocket podem autenticar por cabeçalhos de identidade do Tailscale (`tailscale-user-login`) quando `gateway.auth.allowTailscale` é `true`. O OpenClaw verifica a identidade resolvendo o endereço `x-forwarded-for` com `tailscale whois` e comparando-o ao cabeçalho, e aceita isso apenas quando a solicitação chega ao loopback com os cabeçalhos `x-forwarded-*` do Tailscale. Para sessões de operador da Control UI com identidade de dispositivo no navegador, esse caminho Serve verificado também pula a ida e volta de pareamento de dispositivo; navegadores sem dispositivo e conexões com função de nó ainda seguem as verificações normais de dispositivo. Defina `gateway.auth.allowTailscale: false` se quiser exigir credenciais explícitas de segredo compartilhado até mesmo para tráfego Serve. Então use `gateway.auth.mode: "token"` ou `"password"`.
|
||||
|
||||
Para esse caminho assíncrono de identidade Serve, tentativas de autenticação malsucedidas para o mesmo IP de cliente e escopo de autenticação são serializadas antes das gravações de limite de taxa. Retentativas ruins concorrentes do mesmo navegador podem, portanto, mostrar `retry later` na segunda solicitação em vez de duas incompatibilidades simples competindo em paralelo.
|
||||
Para esse caminho assíncrono de identidade Serve, tentativas de autenticação com falha para o mesmo IP de cliente e escopo de autenticação são serializadas antes das gravações de limite de taxa. Portanto, novas tentativas ruins simultâneas do mesmo navegador podem mostrar `retry later` na segunda solicitação em vez de duas incompatibilidades simples competindo em paralelo.
|
||||
|
||||
<Warning>
|
||||
Autenticação Serve sem token pressupõe que o host do Gateway é confiável. Se código local não confiável puder ser executado nesse host, exija autenticação por token/senha.
|
||||
@ -299,7 +303,7 @@ O valor é validado antes de chegar ao navegador. Valores compatíveis incluem c
|
||||
openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)"
|
||||
```
|
||||
|
||||
Depois abra:
|
||||
Então abra:
|
||||
|
||||
- `http://<tailscale-ip>:18789/` (ou seu `gateway.controlUi.basePath` configurado)
|
||||
|
||||
@ -310,21 +314,21 @@ O valor é validado antes de chegar ao navegador. Valores compatíveis incluem c
|
||||
|
||||
## HTTP inseguro
|
||||
|
||||
Se você abrir o painel por HTTP simples (`http://<lan-ip>` ou `http://<tailscale-ip>`), o navegador roda em um **contexto não seguro** e bloqueia WebCrypto. Por padrão, o OpenClaw **bloqueia** conexões da Control UI sem identidade de dispositivo.
|
||||
Se você abrir o painel por HTTP simples (`http://<lan-ip>` ou `http://<tailscale-ip>`), o navegador roda em um **contexto não seguro** e bloqueia o WebCrypto. Por padrão, o OpenClaw **bloqueia** conexões da Control UI sem identidade do dispositivo.
|
||||
|
||||
Exceções documentadas:
|
||||
|
||||
- compatibilidade com HTTP inseguro apenas em localhost com `gateway.controlUi.allowInsecureAuth=true`
|
||||
- autenticação bem-sucedida de operador da Control UI por `gateway.auth.mode: "trusted-proxy"`
|
||||
- opção de emergência `gateway.controlUi.dangerouslyDisableDeviceAuth=true`
|
||||
- autenticação bem-sucedida da Control UI do operador por meio de `gateway.auth.mode: "trusted-proxy"`
|
||||
- recurso de emergência `gateway.controlUi.dangerouslyDisableDeviceAuth=true`
|
||||
|
||||
**Correção recomendada:** use HTTPS (Tailscale Serve) ou abra a UI localmente:
|
||||
|
||||
- `https://<magicdns>/` (Serve)
|
||||
- `http://127.0.0.1:18789/` (no host do gateway)
|
||||
- `http://127.0.0.1:18789/` (no host do Gateway)
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Insecure-auth toggle behavior">
|
||||
<Accordion title="Comportamento do alternador de autenticação insegura">
|
||||
```json5
|
||||
{
|
||||
gateway: {
|
||||
@ -335,14 +339,14 @@ Exceções documentadas:
|
||||
}
|
||||
```
|
||||
|
||||
`allowInsecureAuth` é apenas uma opção local de compatibilidade:
|
||||
`allowInsecureAuth` é apenas um alternador de compatibilidade local:
|
||||
|
||||
- Ela permite que sessões localhost da Control UI continuem sem identidade do dispositivo em contextos HTTP não seguros.
|
||||
- Ela não ignora verificações de pareamento.
|
||||
- Ela não relaxa os requisitos de identidade de dispositivo remoto (não localhost).
|
||||
- Ele permite que sessões localhost da Control UI prossigam sem identidade do dispositivo em contextos HTTP não seguros.
|
||||
- Ele não ignora as verificações de pareamento.
|
||||
- Ele não afrouxa os requisitos de identidade de dispositivo remoto (não localhost).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Break-glass only">
|
||||
<Accordion title="Somente emergência">
|
||||
```json5
|
||||
{
|
||||
gateway: {
|
||||
@ -354,14 +358,14 @@ Exceções documentadas:
|
||||
```
|
||||
|
||||
<Warning>
|
||||
`dangerouslyDisableDeviceAuth` desativa as verificações de identidade de dispositivo da Control UI e é uma redução grave de segurança. Reverta rapidamente após o uso emergencial.
|
||||
`dangerouslyDisableDeviceAuth` desativa as verificações de identidade de dispositivo da Control UI e é uma degradação grave de segurança. Reverta rapidamente após o uso emergencial.
|
||||
</Warning>
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Trusted-proxy note">
|
||||
- A autenticação trusted-proxy bem-sucedida pode admitir sessões **operator** da Control UI sem identidade do dispositivo.
|
||||
- Isso **não** se estende a sessões da Control UI com função de node.
|
||||
- Proxies reversos de loopback no mesmo host ainda não satisfazem a autenticação trusted-proxy; consulte [Autenticação de proxy confiável](/pt-BR/gateway/trusted-proxy-auth).
|
||||
<Accordion title="Observação sobre proxy confiável">
|
||||
- A autenticação bem-sucedida por proxy confiável pode admitir sessões da Control UI de **operador** sem identidade do dispositivo.
|
||||
- Isso **não** se estende a sessões da Control UI com função de nó.
|
||||
- Proxies reversos de local loopback no mesmo host ainda não satisfazem a autenticação de proxy confiável; consulte [Autenticação por proxy confiável](/pt-BR/gateway/trusted-proxy-auth).
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -370,46 +374,46 @@ Consulte [Tailscale](/pt-BR/gateway/tailscale) para orientações de configuraç
|
||||
|
||||
## Política de segurança de conteúdo
|
||||
|
||||
A Control UI é fornecida com uma política `img-src` restrita: somente ativos de **mesma origem**, URLs `data:` e URLs `blob:` geradas localmente são permitidas. URLs de imagem remotas `http(s)` e relativas a protocolo são rejeitadas pelo navegador e não emitem buscas de rede.
|
||||
A Control UI vem com uma política `img-src` rígida: apenas ativos de **mesma origem**, URLs `data:` e URLs `blob:` gerados localmente são permitidos. URLs de imagem remotas `http(s)` e relativas a protocolo são rejeitadas pelo navegador e não emitem buscas de rede.
|
||||
|
||||
O que isso significa na prática:
|
||||
|
||||
- Avatares e imagens servidos em caminhos relativos (por exemplo, `/avatars/<id>`) ainda são renderizados, incluindo rotas de avatar autenticadas que a UI busca e converte em URLs `blob:` locais.
|
||||
- URLs `data:image/...` embutidas ainda são renderizadas (úteis para cargas dentro do protocolo).
|
||||
- URLs `blob:` locais criadas pela Control UI ainda são renderizadas.
|
||||
- URLs remotas de avatar emitidas pelos metadados do canal são removidas pelos auxiliares de avatar da Control UI e substituídas pelo logotipo/selo integrado, para que um canal comprometido ou malicioso não possa forçar buscas arbitrárias de imagens remotas a partir do navegador de um operador.
|
||||
- Avatares e imagens servidos em caminhos relativos (por exemplo, `/avatars/<id>`) continuam sendo renderizados, incluindo rotas de avatar autenticadas que a UI busca e converte em URLs `blob:` locais.
|
||||
- URLs inline `data:image/...` continuam sendo renderizadas (útil para cargas úteis dentro do protocolo).
|
||||
- URLs `blob:` locais criados pela Control UI continuam sendo renderizados.
|
||||
- URLs de avatar remotas emitidas por metadados de canal são removidas nos auxiliares de avatar da Control UI e substituídas pelo logotipo/selo integrado, de modo que um canal comprometido ou malicioso não possa forçar buscas arbitrárias de imagens remotas a partir do navegador de um operador.
|
||||
|
||||
Você não precisa alterar nada para obter esse comportamento — ele está sempre ativado e não é configurável.
|
||||
|
||||
## Autenticação da rota de avatar
|
||||
|
||||
Quando a autenticação do gateway está configurada, o endpoint de avatar da Control UI exige o mesmo token do gateway que o restante da API:
|
||||
Quando a autenticação do Gateway está configurada, o endpoint de avatar da Control UI exige o mesmo token do Gateway que o restante da API:
|
||||
|
||||
- `GET /avatar/<agentId>` retorna a imagem do avatar apenas para chamadores autenticados. `GET /avatar/<agentId>?meta=1` retorna os metadados do avatar sob a mesma regra.
|
||||
- Solicitações não autenticadas a qualquer uma das rotas são rejeitadas (correspondendo à rota irmã assistant-media). Isso impede que a rota de avatar vaze a identidade do agente em hosts que, de outra forma, estão protegidos.
|
||||
- A própria Control UI encaminha o token do gateway como um cabeçalho bearer ao buscar avatares e usa URLs blob autenticadas para que a imagem ainda seja renderizada em dashboards.
|
||||
- Solicitações não autenticadas para qualquer uma das rotas são rejeitadas (correspondendo à rota irmã de mídia do assistente). Isso impede que a rota de avatar vaze a identidade do agente em hosts que, de outra forma, estão protegidos.
|
||||
- A própria Control UI encaminha o token do Gateway como um cabeçalho bearer ao buscar avatares e usa URLs blob autenticadas para que a imagem ainda seja renderizada nos painéis.
|
||||
|
||||
Se você desativar a autenticação do gateway (não recomendado em hosts compartilhados), a rota de avatar também se torna não autenticada, alinhada ao restante do gateway.
|
||||
Se você desativar a autenticação do Gateway (não recomendado em hosts compartilhados), a rota de avatar também se tornará não autenticada, em linha com o restante do Gateway.
|
||||
|
||||
## Autenticação da rota de mídia do assistente
|
||||
|
||||
Quando a autenticação do gateway está configurada, pré-visualizações de mídia local do assistente usam uma rota em duas etapas:
|
||||
Quando a autenticação do Gateway está configurada, as prévias de mídia local do assistente usam uma rota em duas etapas:
|
||||
|
||||
- `GET /__openclaw__/assistant-media?meta=1&source=<path>` exige a autenticação normal de operador da Control UI. O navegador envia o token do gateway como um cabeçalho bearer ao verificar a disponibilidade.
|
||||
- Respostas de metadados bem-sucedidas incluem um `mediaTicket` de curta duração, com escopo limitado ao caminho exato da origem.
|
||||
- URLs de imagem, áudio, vídeo e documento renderizadas pelo navegador usam `mediaTicket=<ticket>` em vez do token ou da senha ativa do gateway. O tíquete expira rapidamente e não pode autorizar uma origem diferente.
|
||||
- `GET /__openclaw__/assistant-media?meta=1&source=<path>` exige a autenticação normal de operador da Control UI. O navegador envia o token do Gateway como um cabeçalho bearer ao verificar a disponibilidade.
|
||||
- Respostas de metadados bem-sucedidas incluem um `mediaTicket` de curta duração com escopo limitado exatamente a esse caminho de origem.
|
||||
- URLs de imagem, áudio, vídeo e documento renderizadas pelo navegador usam `mediaTicket=<ticket>` em vez do token ou senha ativos do Gateway. O ticket expira rapidamente e não pode autorizar uma origem diferente.
|
||||
|
||||
Isso mantém a renderização normal de mídia compatível com elementos de mídia nativos do navegador sem colocar credenciais reutilizáveis do gateway em URLs de mídia visíveis.
|
||||
Isso mantém a renderização normal de mídia compatível com elementos de mídia nativos do navegador sem colocar credenciais reutilizáveis do Gateway em URLs de mídia visíveis.
|
||||
|
||||
## Compilando a UI
|
||||
## Construindo a UI
|
||||
|
||||
O Gateway serve arquivos estáticos de `dist/control-ui`. Compile-os com:
|
||||
O Gateway serve arquivos estáticos de `dist/control-ui`. Construa-os com:
|
||||
|
||||
```bash
|
||||
pnpm ui:build
|
||||
```
|
||||
|
||||
Base absoluta opcional (quando você quiser URLs fixas de ativos):
|
||||
Base absoluta opcional (quando você quiser URLs de ativos fixas):
|
||||
|
||||
```bash
|
||||
OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build
|
||||
@ -421,24 +425,24 @@ Para desenvolvimento local (servidor de desenvolvimento separado):
|
||||
pnpm ui:dev
|
||||
```
|
||||
|
||||
Em seguida, aponte a UI para a URL WS do seu Gateway (por exemplo, `ws://127.0.0.1:18789`).
|
||||
Depois aponte a UI para a URL WS do seu Gateway (por exemplo, `ws://127.0.0.1:18789`).
|
||||
|
||||
## Depuração/testes: servidor de desenvolvimento + Gateway remoto
|
||||
|
||||
A Control UI consiste em arquivos estáticos; o destino WebSocket é configurável e pode ser diferente da origem HTTP. Isso é útil quando você quer o servidor de desenvolvimento Vite localmente, mas o Gateway executa em outro lugar.
|
||||
A Control UI é composta por arquivos estáticos; o destino WebSocket é configurável e pode ser diferente da origem HTTP. Isso é útil quando você quer o servidor de desenvolvimento Vite localmente, mas o Gateway roda em outro lugar.
|
||||
|
||||
<Steps>
|
||||
<Step title="Start the UI dev server">
|
||||
<Step title="Inicie o servidor de desenvolvimento da UI">
|
||||
```bash
|
||||
pnpm ui:dev
|
||||
```
|
||||
</Step>
|
||||
<Step title="Open with gatewayUrl">
|
||||
<Step title="Abra com gatewayUrl">
|
||||
```text
|
||||
http://localhost:5173/?gatewayUrl=ws%3A%2F%2F<gateway-host>%3A18789
|
||||
```
|
||||
|
||||
Autenticação opcional de uso único (se necessário):
|
||||
Autenticação única opcional (se necessário):
|
||||
|
||||
```text
|
||||
http://localhost:5173/?gatewayUrl=wss%3A%2F%2F<gateway-host>%3A18789#token=<gateway-token>
|
||||
@ -448,18 +452,18 @@ A Control UI consiste em arquivos estáticos; o destino WebSocket é configuráv
|
||||
</Steps>
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Notes">
|
||||
<Accordion title="Observações">
|
||||
- `gatewayUrl` é armazenado em localStorage após o carregamento e removido da URL.
|
||||
- Se você passar um endpoint `ws://` ou `wss://` completo via `gatewayUrl`, codifique em URL o valor de `gatewayUrl` para que o navegador analise a string de consulta corretamente.
|
||||
- `token` deve ser passado pelo fragmento da URL (`#token=...`) sempre que possível. Fragmentos não são enviados ao servidor, o que evita vazamento em logs de solicitação e no Referer. Parâmetros de consulta legados `?token=` ainda são importados uma vez para compatibilidade, mas apenas como fallback, e são removidos imediatamente após o bootstrap.
|
||||
- Se você passar um endpoint `ws://` ou `wss://` completo via `gatewayUrl`, codifique em URL o valor de `gatewayUrl` para que o navegador analise corretamente a string de consulta.
|
||||
- `token` deve ser passado pelo fragmento da URL (`#token=...`) sempre que possível. Fragmentos não são enviados ao servidor, o que evita vazamento em logs de solicitação e Referer. Parâmetros de consulta legados `?token=` ainda são importados uma vez por compatibilidade, mas apenas como fallback, e são removidos imediatamente após a inicialização.
|
||||
- `password` é mantido apenas em memória.
|
||||
- Quando `gatewayUrl` está definido, a UI não recorre a credenciais de configuração ou ambiente. Forneça `token` (ou `password`) explicitamente. Credenciais explícitas ausentes são um erro.
|
||||
- Use `wss://` quando o Gateway estiver atrás de TLS (Tailscale Serve, proxy HTTPS etc.).
|
||||
- `gatewayUrl` só é aceito em uma janela de nível superior (não incorporada) para evitar clickjacking.
|
||||
- Implantações não loopback da Control UI devem definir `gateway.controlUi.allowedOrigins` explicitamente (origens completas). Isso inclui configurações remotas de desenvolvimento.
|
||||
- A inicialização do Gateway pode semear origens locais como `http://localhost:<port>` e `http://127.0.0.1:<port>` a partir do bind e da porta efetivos em tempo de execução, mas origens remotas de navegador ainda precisam de entradas explícitas.
|
||||
- Não use `gateway.controlUi.allowedOrigins: ["*"]` exceto para testes locais rigidamente controlados. Isso significa permitir qualquer origem de navegador, não "corresponder a qualquer host que eu esteja usando".
|
||||
- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` habilita o modo de fallback de origem por cabeçalho Host, mas é um modo de segurança perigoso.
|
||||
- Implantações não loopback da Control UI devem definir `gateway.controlUi.allowedOrigins` explicitamente (origens completas). Isso inclui configurações de desenvolvimento remoto.
|
||||
- A inicialização do Gateway pode semear origens locais como `http://localhost:<port>` e `http://127.0.0.1:<port>` a partir do bind e da porta efetivos em tempo de execução, mas origens de navegador remotas ainda precisam de entradas explícitas.
|
||||
- Não use `gateway.controlUi.allowedOrigins: ["*"]`, exceto para testes locais estritamente controlados. Isso significa permitir qualquer origem de navegador, não "corresponder a qualquer host que eu esteja usando".
|
||||
- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` ativa o modo de fallback de origem pelo cabeçalho Host, mas esse é um modo de segurança perigoso.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -480,7 +484,7 @@ Detalhes de configuração de acesso remoto: [Acesso remoto](/pt-BR/gateway/remo
|
||||
|
||||
## Relacionados
|
||||
|
||||
- [Dashboard](/pt-BR/web/dashboard) — dashboard do gateway
|
||||
- [Health Checks](/pt-BR/gateway/health) — monitoramento de integridade do gateway
|
||||
- [Dashboard](/pt-BR/web/dashboard) — painel do gateway
|
||||
- [Verificações de integridade](/pt-BR/gateway/health) — monitoramento de integridade do gateway
|
||||
- [TUI](/pt-BR/web/tui) — interface de usuário de terminal
|
||||
- [WebChat](/pt-BR/web/webchat) — interface de chat baseada em navegador
|
||||
|
||||
Loading…
Reference in New Issue
Block a user