chore(i18n): refresh pt-BR translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
4bb4460efe
commit
dfd84aba5a
File diff suppressed because it is too large
Load Diff
@ -1,27 +1,27 @@
|
||||
---
|
||||
read_when:
|
||||
- Configuração do Slack ou depuração do modo de soquete/HTTP do Slack
|
||||
summary: Configuração do Slack e comportamento em tempo de execução (Modo Socket + URLs de solicitação HTTP)
|
||||
- Configurando o Slack ou depurando o modo socket/HTTP do Slack
|
||||
summary: Configuração do Slack e comportamento em tempo de execução (Modo Socket + URLs de requisição HTTP)
|
||||
title: Slack
|
||||
x-i18n:
|
||||
generated_at: "2026-05-04T02:22:07Z"
|
||||
generated_at: "2026-05-04T07:02:49Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 2be45f03511a64373b1f4316c59800eeeef8baccb4c00454b49999258b2e546b
|
||||
source_hash: d4a91fc1ae5f1e03f714308be54e164ef204809e74efabed8dc75c3035c14228
|
||||
source_path: channels/slack.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Pronto para produção para DMs e canais por meio de integrações do app Slack. O modo padrão é Socket Mode; HTTP Request URLs também são compatíveis.
|
||||
Pronto para produção para DMs e canais via integrações de app do Slack. O modo padrão é Socket Mode; URLs de requisição HTTP também são compatíveis.
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Pairing" icon="link" href="/pt-BR/channels/pairing">
|
||||
<Card title="Pareamento" icon="link" href="/pt-BR/channels/pairing">
|
||||
DMs do Slack usam o modo de pareamento por padrão.
|
||||
</Card>
|
||||
<Card title="Slash commands" icon="terminal" href="/pt-BR/tools/slash-commands">
|
||||
Comportamento de comando nativo e catálogo de comandos.
|
||||
<Card title="Comandos slash" icon="terminal" href="/pt-BR/tools/slash-commands">
|
||||
Comportamento nativo de comandos e catálogo de comandos.
|
||||
</Card>
|
||||
<Card title="Channel troubleshooting" icon="wrench" href="/pt-BR/channels/troubleshooting">
|
||||
<Card title="Solução de problemas de canais" icon="wrench" href="/pt-BR/channels/troubleshooting">
|
||||
Diagnósticos entre canais e playbooks de reparo.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@ -29,19 +29,19 @@ Pronto para produção para DMs e canais por meio de integrações do app Slack.
|
||||
## Configuração rápida
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Socket Mode (default)">
|
||||
<Tab title="Socket Mode (padrão)">
|
||||
<Steps>
|
||||
<Step title="Create a new Slack app">
|
||||
Nas configurações do app Slack, pressione o botão **[Create New App](https://api.slack.com/apps/new)**:
|
||||
<Step title="Criar um novo app do Slack">
|
||||
Nas configurações do app do Slack, pressione o botão **[Create New App](https://api.slack.com/apps/new)**:
|
||||
|
||||
- escolha **from a manifest** e selecione um workspace para seu app
|
||||
- cole o [manifesto de exemplo](#manifest-and-scope-checklist) abaixo e continue para criar
|
||||
- gere um **App-Level Token** (`xapp-...`) com `connections:write`
|
||||
- instale o app e copie o **Bot Token** (`xoxb-...`) exibido
|
||||
- gere um **Token em nível de app** (`xapp-...`) com `connections:write`
|
||||
- instale o app e copie o **Token do bot** (`xoxb-...`) exibido
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Configure OpenClaw">
|
||||
<Step title="Configurar o OpenClaw">
|
||||
|
||||
Configuração SecretRef recomendada:
|
||||
|
||||
@ -64,7 +64,7 @@ openclaw config patch --file ./slack.socket.patch.json5 --dry-run
|
||||
openclaw config patch --file ./slack.socket.patch.json5
|
||||
```
|
||||
|
||||
Fallback por env (somente conta padrão):
|
||||
Fallback de env (somente conta padrão):
|
||||
|
||||
```bash
|
||||
SLACK_APP_TOKEN=xapp-...
|
||||
@ -73,7 +73,7 @@ SLACK_BOT_TOKEN=xoxb-...
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Start gateway">
|
||||
<Step title="Iniciar o Gateway">
|
||||
|
||||
```bash
|
||||
openclaw gateway
|
||||
@ -84,19 +84,19 @@ openclaw gateway
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="HTTP Request URLs">
|
||||
<Tab title="URLs de requisição HTTP">
|
||||
<Steps>
|
||||
<Step title="Create a new Slack app">
|
||||
Nas configurações do app Slack, pressione o botão **[Create New App](https://api.slack.com/apps/new)**:
|
||||
<Step title="Criar um novo app do Slack">
|
||||
Nas configurações do app do Slack, pressione o botão **[Create New App](https://api.slack.com/apps/new)**:
|
||||
|
||||
- escolha **from a manifest** e selecione um workspace para seu app
|
||||
- cole o [manifesto de exemplo](#manifest-and-scope-checklist) e atualize as URLs antes de criar
|
||||
- salve o **Signing Secret** para verificação de solicitações
|
||||
- instale o app e copie o **Bot Token** (`xoxb-...`) exibido
|
||||
- salve o **Segredo de assinatura** para verificação de requisições
|
||||
- instale o app e copie o **Token do bot** (`xoxb-...`) exibido
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Configure OpenClaw">
|
||||
<Step title="Configurar o OpenClaw">
|
||||
|
||||
Configuração SecretRef recomendada:
|
||||
|
||||
@ -128,7 +128,7 @@ openclaw config patch --file ./slack.http.patch.json5
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Start gateway">
|
||||
<Step title="Iniciar o Gateway">
|
||||
|
||||
```bash
|
||||
openclaw gateway
|
||||
@ -140,9 +140,9 @@ openclaw gateway
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Ajuste do transporte Socket Mode
|
||||
## Ajuste de transporte do Socket Mode
|
||||
|
||||
O OpenClaw define o tempo limite de pong do cliente do SDK do Slack como 15 segundos por padrão para Socket Mode. Substitua as configurações de transporte somente quando precisar de ajustes específicos para o workspace ou o host:
|
||||
O OpenClaw define o tempo limite de pong do cliente do SDK do Slack como 15 segundos por padrão para Socket Mode. Substitua as configurações de transporte somente quando precisar de ajuste específico para workspace ou host:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -159,11 +159,11 @@ O OpenClaw define o tempo limite de pong do cliente do SDK do Slack como 15 segu
|
||||
}
|
||||
```
|
||||
|
||||
Use isso somente para workspaces em Socket Mode que registram tempos limite de pong/server-ping do websocket do Slack ou executam em hosts com starvation conhecido do loop de eventos. `clientPingTimeout` é a espera pelo pong depois que o SDK envia um ping do cliente; `serverPingTimeout` é a espera pelos pings do servidor do Slack. Mensagens e eventos do app permanecem como estado da aplicação, não como sinais de vivacidade do transporte.
|
||||
Use isto somente para workspaces em Socket Mode que registrem timeouts de pong/websocket ou server-ping do Slack, ou que rodem em hosts com starvation conhecida do loop de eventos. `clientPingTimeout` é a espera pelo pong depois que o SDK envia um ping do cliente; `serverPingTimeout` é a espera por pings do servidor do Slack. Mensagens e eventos do app continuam sendo estado da aplicação, não sinais de vivacidade do transporte.
|
||||
|
||||
## Checklist de manifesto e escopos
|
||||
|
||||
O manifesto base do app Slack é o mesmo para Socket Mode e HTTP Request URLs. Apenas o bloco `settings` (e a `url` do comando slash) difere.
|
||||
O manifesto base do app do Slack é o mesmo para Socket Mode e URLs de requisição HTTP. Somente o bloco `settings` (e a `url` do comando slash) difere.
|
||||
|
||||
Manifesto base (Socket Mode padrão):
|
||||
|
||||
@ -240,7 +240,7 @@ Manifesto base (Socket Mode padrão):
|
||||
}
|
||||
```
|
||||
|
||||
Para o **modo HTTP Request URLs**, substitua `settings` pela variante HTTP e adicione `url` a cada comando slash. URL pública obrigatória:
|
||||
Para o **modo de URLs de requisição HTTP**, substitua `settings` pela variante HTTP e adicione `url` a cada comando slash. URL pública obrigatória:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -284,22 +284,22 @@ Para o **modo HTTP Request URLs**, substitua `settings` pela variante HTTP e adi
|
||||
|
||||
### Configurações adicionais do manifesto
|
||||
|
||||
Exiba recursos diferentes que estendem os padrões acima.
|
||||
Exponha recursos diferentes que ampliam os padrões acima.
|
||||
|
||||
O manifesto padrão habilita a aba **Home** do Slack App Home e assina `app_home_opened`. Quando um membro do workspace abre a aba Home, o OpenClaw publica uma visualização Home padrão segura com `views.publish`; nenhum payload de conversa ou configuração privada é incluído. A aba **Messages** permanece habilitada para DMs do Slack.
|
||||
O manifesto padrão habilita a aba **Home** do Slack App Home e assina `app_home_opened`. Quando um membro do workspace abre a aba Home, o OpenClaw publica uma visualização Home padrão segura com `views.publish`; nenhum payload de conversa nem configuração privada é incluído. A aba **Messages** continua habilitada para DMs do Slack.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Optional native slash commands">
|
||||
<Accordion title="Comandos slash nativos opcionais">
|
||||
|
||||
Vários [comandos slash nativos](#commands-and-slash-behavior) podem ser usados em vez de um único comando configurado, com uma nuance:
|
||||
Vários [comandos slash nativos](#commands-and-slash-behavior) podem ser usados em vez de um único comando configurado, com nuances:
|
||||
|
||||
- Use `/agentstatus` em vez de `/status` porque o comando `/status` é reservado.
|
||||
- No máximo 25 comandos slash podem ficar disponíveis ao mesmo tempo.
|
||||
- Não mais que 25 comandos slash podem ser disponibilizados de uma vez.
|
||||
|
||||
Substitua sua seção `features.slash_commands` existente por um subconjunto dos [comandos disponíveis](/pt-BR/tools/slash-commands#command-list):
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Socket Mode (default)">
|
||||
<Tab title="Socket Mode (padrão)">
|
||||
|
||||
```json
|
||||
{
|
||||
@ -422,7 +422,7 @@ O manifesto padrão habilita a aba **Home** do Slack App Home e assina `app_home
|
||||
```
|
||||
|
||||
</Tab>
|
||||
<Tab title="HTTP Request URLs">
|
||||
<Tab title="URLs de requisição HTTP">
|
||||
Use a mesma lista `slash_commands` do Socket Mode acima e adicione `"url": "https://gateway-host.example.com/slack/events"` a cada entrada. Exemplo:
|
||||
|
||||
```json
|
||||
@ -450,7 +450,7 @@ O manifesto padrão habilita a aba **Home** do Slack App Home e assina `app_home
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Escopos opcionais de autoria (operações de escrita)">
|
||||
Adicione o escopo de bot `chat:write.customize` se quiser que as mensagens de saída usem a identidade do agente ativo (nome de usuário e ícone personalizados) em vez da identidade padrão do app Slack.
|
||||
Adicione o escopo de bot `chat:write.customize` se quiser que as mensagens enviadas usem a identidade do agente ativo (nome de usuário e ícone personalizados) em vez da identidade padrão do app Slack.
|
||||
|
||||
Se você usar um ícone de emoji, o Slack espera a sintaxe `:emoji_name:`.
|
||||
|
||||
@ -464,57 +464,57 @@ O manifesto padrão habilita a aba **Home** do Slack App Home e assina `app_home
|
||||
- `reactions:read`
|
||||
- `pins:read`
|
||||
- `emoji:read`
|
||||
- `search:read` (se você depender de leituras da busca do Slack)
|
||||
- `search:read` (se você depende de leituras de busca do Slack)
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Modelo de tokens
|
||||
## Modelo de token
|
||||
|
||||
- `botToken` + `appToken` são obrigatórios para Socket Mode.
|
||||
- O modo HTTP exige `botToken` + `signingSecret`.
|
||||
- `botToken`, `appToken`, `signingSecret` e `userToken` aceitam strings em texto claro
|
||||
- `botToken`, `appToken`, `signingSecret` e `userToken` aceitam strings em texto simples
|
||||
ou objetos SecretRef.
|
||||
- Tokens de configuração substituem o fallback de env.
|
||||
- O fallback de env `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` se aplica apenas à conta padrão.
|
||||
- `userToken` (`xoxp-...`) é somente por configuração (sem fallback de env) e o padrão é comportamento somente leitura (`userTokenReadOnly: true`).
|
||||
- `userToken` (`xoxp-...`) é apenas de configuração (sem fallback de env) e usa por padrão comportamento somente leitura (`userTokenReadOnly: true`).
|
||||
|
||||
Comportamento do snapshot de status:
|
||||
Comportamento do instantâneo de status:
|
||||
|
||||
- A inspeção da conta Slack rastreia campos `*Source` e `*Status`
|
||||
- A inspeção de conta do Slack rastreia campos `*Source` e `*Status`
|
||||
por credencial (`botToken`, `appToken`, `signingSecret`, `userToken`).
|
||||
- O status é `available`, `configured_unavailable` ou `missing`.
|
||||
- `configured_unavailable` significa que a conta está configurada por SecretRef
|
||||
ou outra origem de segredo não inline, mas o caminho de comando/runtime atual
|
||||
ou outra fonte de segredo não embutida, mas o comando/caminho de runtime atual
|
||||
não conseguiu resolver o valor real.
|
||||
- No modo HTTP, `signingSecretStatus` é incluído; em Socket Mode, o
|
||||
- No modo HTTP, `signingSecretStatus` é incluído; no Socket Mode, o
|
||||
par obrigatório é `botTokenStatus` + `appTokenStatus`.
|
||||
|
||||
<Tip>
|
||||
Para ações/leituras de diretório, o token de usuário pode ser preferido quando configurado. Para escritas, o token de bot continua sendo preferido; escritas com token de usuário só são permitidas quando `userTokenReadOnly: false` e o token de bot está indisponível.
|
||||
Para ações/leituras de diretório, o token de usuário pode ser preferido quando configurado. Para escritas, o token de bot continua preferido; escritas com token de usuário só são permitidas quando `userTokenReadOnly: false` e o token de bot está indisponível.
|
||||
</Tip>
|
||||
|
||||
## Ações e gates
|
||||
|
||||
As ações do Slack são controladas por `channels.slack.actions.*`.
|
||||
|
||||
Grupos de ação disponíveis nas ferramentas Slack atuais:
|
||||
Grupos de ações disponíveis nas ferramentas atuais do Slack:
|
||||
|
||||
| Grupo | Padrão |
|
||||
| ---------- | ------- |
|
||||
| messages | ativado |
|
||||
| reactions | ativado |
|
||||
| pins | ativado |
|
||||
| memberInfo | ativado |
|
||||
| emojiList | ativado |
|
||||
| messages | habilitado |
|
||||
| reactions | habilitado |
|
||||
| pins | habilitado |
|
||||
| memberInfo | habilitado |
|
||||
| emojiList | habilitado |
|
||||
|
||||
As ações de mensagem Slack atuais incluem `send`, `upload-file`, `download-file`, `read`, `edit`, `delete`, `pin`, `unpin`, `list-pins`, `member-info` e `emoji-list`. `download-file` aceita IDs de arquivo Slack mostrados nos placeholders de arquivos recebidos e retorna prévias de imagem para imagens ou metadados de arquivo local para outros tipos de arquivo.
|
||||
As ações atuais de mensagem do Slack incluem `send`, `upload-file`, `download-file`, `read`, `edit`, `delete`, `pin`, `unpin`, `list-pins`, `member-info` e `emoji-list`. `download-file` aceita IDs de arquivo do Slack mostrados nos placeholders de arquivos recebidos e retorna prévias de imagem para imagens ou metadados de arquivo local para outros tipos de arquivo.
|
||||
|
||||
## Controle de acesso e roteamento
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Política de DM">
|
||||
`channels.slack.dmPolicy` controla o acesso por DM. `channels.slack.allowFrom` é a allowlist canônica de DM.
|
||||
`channels.slack.dmPolicy` controla o acesso por DM. `channels.slack.allowFrom` é a lista de permissões canônica de DM.
|
||||
|
||||
- `pairing` (padrão)
|
||||
- `allowlist`
|
||||
@ -527,9 +527,9 @@ As ações de mensagem Slack atuais incluem `send`, `upload-file`, `download-fil
|
||||
- `channels.slack.allowFrom`
|
||||
- `dm.allowFrom` (legado)
|
||||
- `dm.groupEnabled` (DMs em grupo padrão false)
|
||||
- `dm.groupChannels` (allowlist opcional de MPIM)
|
||||
- `dm.groupChannels` (lista de permissões MPIM opcional)
|
||||
|
||||
Precedência em várias contas:
|
||||
Precedência de várias contas:
|
||||
|
||||
- `channels.slack.accounts.default.allowFrom` se aplica apenas à conta `default`.
|
||||
- Contas nomeadas herdam `channels.slack.allowFrom` quando seu próprio `allowFrom` não está definido.
|
||||
@ -537,31 +537,31 @@ As ações de mensagem Slack atuais incluem `send`, `upload-file`, `download-fil
|
||||
|
||||
`channels.slack.dm.policy` e `channels.slack.dm.allowFrom` legados ainda são lidos por compatibilidade. `openclaw doctor --fix` os migra para `dmPolicy` e `allowFrom` quando consegue fazer isso sem alterar o acesso.
|
||||
|
||||
O pareamento em DMs usa `openclaw pairing approve slack <code>`.
|
||||
O emparelhamento em DMs usa `openclaw pairing approve slack <code>`.
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Política de canais">
|
||||
<Tab title="Política de canal">
|
||||
`channels.slack.groupPolicy` controla o tratamento de canais:
|
||||
|
||||
- `open`
|
||||
- `allowlist`
|
||||
- `disabled`
|
||||
|
||||
A allowlist de canais fica em `channels.slack.channels` e **deve usar IDs estáveis de canal Slack** (por exemplo, `C12345678`) como chaves de configuração.
|
||||
A lista de permissões de canais fica em `channels.slack.channels` e **deve usar IDs estáveis de canal do Slack** (por exemplo, `C12345678`) como chaves de configuração.
|
||||
|
||||
Nota de runtime: se `channels.slack` estiver completamente ausente (configuração somente por env), o runtime volta para `groupPolicy="allowlist"` e registra um aviso (mesmo se `channels.defaults.groupPolicy` estiver definido).
|
||||
Observação de runtime: se `channels.slack` estiver completamente ausente (configuração somente por env), o runtime faz fallback para `groupPolicy="allowlist"` e registra um aviso (mesmo que `channels.defaults.groupPolicy` esteja definido).
|
||||
|
||||
Resolução de nome/ID:
|
||||
|
||||
- entradas da allowlist de canais e entradas da allowlist de DM são resolvidas na inicialização quando o acesso por token permite
|
||||
- entradas não resolvidas por nome de canal são mantidas como configuradas, mas ignoradas para roteamento por padrão
|
||||
- autorização de entrada e roteamento de canal são ID-first por padrão; correspondência direta por nome de usuário/slug exige `channels.slack.dangerouslyAllowNameMatching: true`
|
||||
- entradas da lista de permissões de canais e entradas da lista de permissões de DM são resolvidas na inicialização quando o acesso por token permite
|
||||
- entradas de nome de canal não resolvidas são mantidas como configuradas, mas ignoradas para roteamento por padrão
|
||||
- autorização de entrada e roteamento de canal são ID-first por padrão; correspondência direta de nome de usuário/slug exige `channels.slack.dangerouslyAllowNameMatching: true`
|
||||
|
||||
<Warning>
|
||||
Chaves baseadas em nome (`#channel-name` ou `channel-name`) **não** correspondem em `groupPolicy: "allowlist"`. A busca de canal é ID-first por padrão, portanto uma chave baseada em nome nunca roteará com sucesso, e todas as mensagens nesse canal serão bloqueadas silenciosamente. Isso difere de `groupPolicy: "open"`, em que a chave do canal não é exigida para roteamento e uma chave baseada em nome parece funcionar.
|
||||
Chaves baseadas em nome (`#channel-name` ou `channel-name`) **não** correspondem sob `groupPolicy: "allowlist"`. A busca de canal é ID-first por padrão, então uma chave baseada em nome nunca será roteada com sucesso e todas as mensagens nesse canal serão bloqueadas silenciosamente. Isso difere de `groupPolicy: "open"`, em que a chave de canal não é obrigatória para roteamento e uma chave baseada em nome parece funcionar.
|
||||
|
||||
Sempre use o ID do canal Slack como chave. Para encontrá-lo: clique com o botão direito no canal no Slack → **Copy link** — o ID (`C...`) aparece no fim da URL.
|
||||
Sempre use o ID do canal do Slack como chave. Para encontrá-lo: clique com o botão direito no canal no Slack → **Copiar link** — o ID (`C...`) aparece no final da URL.
|
||||
|
||||
Correto:
|
||||
|
||||
@ -578,7 +578,7 @@ As ações de mensagem Slack atuais incluem `send`, `upload-file`, `download-fil
|
||||
}
|
||||
```
|
||||
|
||||
Incorreto (bloqueado silenciosamente em `groupPolicy: "allowlist"`):
|
||||
Incorreto (bloqueado silenciosamente sob `groupPolicy: "allowlist"`):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -596,28 +596,28 @@ As ações de mensagem Slack atuais incluem `send`, `upload-file`, `download-fil
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Menções e usuários de canal">
|
||||
Mensagens de canal exigem menção por padrão.
|
||||
<Tab title="Mentions and channel users">
|
||||
Mensagens de canal são controladas por menções por padrão.
|
||||
|
||||
Origens de menção:
|
||||
Fontes de menção:
|
||||
|
||||
- menção explícita ao app (`<@botId>`)
|
||||
- menção a grupo de usuários do Slack (`<!subteam^S...>`) quando o usuário bot é membro desse grupo de usuários; exige `usergroups:read`
|
||||
- menção a grupo de usuários do Slack (`<!subteam^S...>`) quando o usuário bot é membro desse grupo de usuários; requer `usergroups:read`
|
||||
- padrões regex de menção (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`)
|
||||
- comportamento implícito de resposta ao bot em thread (desativado quando `thread.requireExplicitMention` é `true`)
|
||||
- comportamento implícito de resposta para thread do bot (desativado quando `thread.requireExplicitMention` é `true`)
|
||||
|
||||
Controles por canal (`channels.slack.channels.<id>`; nomes apenas por resolução na inicialização ou `dangerouslyAllowNameMatching`):
|
||||
Controles por canal (`channels.slack.channels.<id>`; nomes somente via resolução na inicialização ou `dangerouslyAllowNameMatching`):
|
||||
|
||||
- `requireMention`
|
||||
- `users` (allowlist)
|
||||
- `users` (lista de permissões)
|
||||
- `allowBots`
|
||||
- `skills`
|
||||
- `systemPrompt`
|
||||
- `tools`, `toolsBySender`
|
||||
- formato de chave de `toolsBySender`: `id:`, `e164:`, `username:`, `name:` ou curinga `"*"`
|
||||
(chaves legadas sem prefixo ainda mapeiam apenas para `id:`)
|
||||
- formato da chave `toolsBySender`: `id:`, `e164:`, `username:`, `name:`, ou curinga `"*"`
|
||||
(chaves legadas sem prefixo ainda mapeiam somente para `id:`)
|
||||
|
||||
`allowBots` é conservador para canais e canais privados: mensagens de sala criadas por bots são aceitas apenas quando o bot remetente está explicitamente listado na allowlist `users` dessa sala, ou quando pelo menos um ID explícito de proprietário Slack de `channels.slack.allowFrom` é atualmente membro da sala. Curingas e entradas de proprietário por nome de exibição não satisfazem a presença do proprietário. A presença do proprietário usa `conversations.members` do Slack; verifique se o app tem o escopo de leitura correspondente para o tipo de sala (`channels:read` para canais públicos, `groups:read` para canais privados). Se a busca de membros falhar, o OpenClaw descarta a mensagem de sala criada por bot.
|
||||
`allowBots` é conservador para canais e canais privados: mensagens de sala criadas por bot são aceitas somente quando o bot remetente está listado explicitamente na lista de permissões `users` dessa sala, ou quando pelo menos um ID explícito de proprietário do Slack de `channels.slack.allowFrom` é atualmente membro da sala. Curingas e entradas de proprietário por nome de exibição não satisfazem a presença do proprietário. A presença do proprietário usa `conversations.members` do Slack; certifique-se de que o app tenha o escopo de leitura correspondente para o tipo de sala (`channels:read` para canais públicos, `groups:read` para canais privados). Se a consulta de membros falhar, o OpenClaw descarta a mensagem de sala criada por bot.
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
@ -625,13 +625,13 @@ As ações de mensagem Slack atuais incluem `send`, `upload-file`, `download-fil
|
||||
## Threads, sessões e tags de resposta
|
||||
|
||||
- DMs são roteadas como `direct`; canais como `channel`; MPIMs como `group`.
|
||||
- Vinculações de rota do Slack aceitam IDs brutos de pares e formas de destino Slack, como `channel:C12345678`, `user:U12345678` e `<@U12345678>`.
|
||||
- Com o padrão `session.dmScope=main`, DMs do Slack são colapsadas para a sessão principal do agente.
|
||||
- Associações de rota do Slack aceitam IDs brutos de par, além de formas de destino do Slack como `channel:C12345678`, `user:U12345678` e `<@U12345678>`.
|
||||
- Com o padrão `session.dmScope=main`, DMs do Slack são agrupadas na sessão principal do agente.
|
||||
- Sessões de canal: `agent:<agentId>:slack:channel:<channelId>`.
|
||||
- Respostas em thread podem criar sufixos de sessão de thread (`:thread:<threadTs>`) quando aplicável.
|
||||
- O padrão de `channels.slack.thread.historyScope` é `thread`; o padrão de `thread.inheritParent` é `false`.
|
||||
- `channels.slack.thread.initialHistoryLimit` controla quantas mensagens de thread existentes são buscadas quando uma nova sessão de thread começa (padrão `20`; defina `0` para desativar).
|
||||
- `channels.slack.thread.requireExplicitMention` (padrão `false`): quando `true`, suprime menções implícitas em threads para que o bot só responda a menções explícitas `@bot` dentro de threads, mesmo quando o bot já participou da thread. Sem isso, respostas em uma thread com participação do bot contornam o gate de `requireMention`.
|
||||
- `channels.slack.thread.initialHistoryLimit` controla quantas mensagens existentes da thread são buscadas quando uma nova sessão de thread começa (padrão `20`; defina `0` para desativar).
|
||||
- `channels.slack.thread.requireExplicitMention` (padrão `false`): quando `true`, suprime menções implícitas em thread para que o bot responda somente a menções explícitas `@bot` dentro de threads, mesmo quando o bot já participou da thread. Sem isso, respostas em uma thread com participação do bot ignoram o controle de `requireMention`.
|
||||
|
||||
Controles de threading de resposta:
|
||||
|
||||
@ -639,51 +639,70 @@ Controles de threading de resposta:
|
||||
- `channels.slack.replyToModeByChatType`: por `direct|group|channel`
|
||||
- fallback legado para chats diretos: `channels.slack.dm.replyToMode`
|
||||
|
||||
Tags manuais de resposta têm suporte:
|
||||
Tags manuais de resposta são compatíveis:
|
||||
|
||||
- `[[reply_to_current]]`
|
||||
- `[[reply_to:<id>]]`
|
||||
|
||||
<Note>
|
||||
`replyToMode="off"` desativa **todo** threading de resposta no Slack, incluindo tags explícitas `[[reply_to_*]]`. Isso difere do Telegram, em que tags explícitas ainda são respeitadas no modo `"off"`. Threads do Slack ocultam mensagens do canal, enquanto respostas do Telegram permanecem visíveis inline.
|
||||
`replyToMode="off"` desativa **todo** o threading de respostas no Slack, incluindo tags explícitas `[[reply_to_*]]`. Isso difere do Telegram, em que tags explícitas ainda são respeitadas no modo `"off"`. Threads do Slack ocultam mensagens do canal, enquanto respostas do Telegram permanecem visíveis em linha.
|
||||
</Note>
|
||||
|
||||
## Reações de confirmação
|
||||
|
||||
`ackReaction` envia um emoji de confirmação enquanto o OpenClaw processa uma mensagem recebida.
|
||||
`ackReaction` envia um emoji de confirmação enquanto o OpenClaw está processando uma mensagem recebida.
|
||||
|
||||
Ordem de resolução:
|
||||
|
||||
- `channels.slack.accounts.<accountId>.ackReaction`
|
||||
- `channels.slack.ackReaction`
|
||||
- `messages.ackReaction`
|
||||
- fallback de emoji da identidade do agente (`agents.list[].identity.emoji`, senão "👀")
|
||||
- fallback para emoji de identidade do agente (`agents.list[].identity.emoji`, caso contrário "👀")
|
||||
|
||||
Notas:
|
||||
Observações:
|
||||
|
||||
- O Slack espera shortcodes (por exemplo, `"eyes"`).
|
||||
- Use `""` para desativar a reação para a conta Slack ou globalmente.
|
||||
- Use `""` para desativar a reação para a conta do Slack ou globalmente.
|
||||
|
||||
## Streaming de texto
|
||||
|
||||
`channels.slack.streaming` controla o comportamento de prévia ao vivo:
|
||||
`channels.slack.streaming` controla o comportamento de pré-visualização ao vivo:
|
||||
|
||||
- `off`: desativa streaming de prévia ao vivo.
|
||||
- `partial` (padrão): substitui o texto da prévia pela saída parcial mais recente.
|
||||
- `block`: acrescenta atualizações de prévia em chunks.
|
||||
- `progress`: mostra texto de status de progresso durante a geração e, depois, envia o texto final.
|
||||
- `streaming.preview.toolProgress`: quando a prévia de rascunho está ativa, roteia atualizações de ferramenta/progresso para a mesma mensagem de prévia editada (padrão: `true`). Defina `false` para manter mensagens separadas de ferramenta/progresso.
|
||||
- `off`: desativa streaming de pré-visualização ao vivo.
|
||||
- `partial` (padrão): substitui o texto de pré-visualização pela saída parcial mais recente.
|
||||
- `block`: acrescenta atualizações de pré-visualização em blocos.
|
||||
- `progress`: mostra texto de status de progresso durante a geração e depois envia o texto final.
|
||||
- `streaming.preview.toolProgress`: quando a pré-visualização de rascunho está ativa, roteia atualizações de ferramenta/progresso para a mesma mensagem de pré-visualização editada (padrão: `true`). Defina `false` para manter mensagens separadas de ferramenta/progresso.
|
||||
- `streaming.preview.commandText` / `streaming.progress.commandText`: defina como `status` para manter linhas compactas de progresso de ferramenta enquanto oculta texto bruto de comando/execução (padrão: `raw`).
|
||||
|
||||
Oculte texto bruto de comando/execução enquanto mantém linhas compactas de progresso:
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"slack": {
|
||||
"streaming": {
|
||||
"mode": "progress",
|
||||
"progress": {
|
||||
"toolProgress": true,
|
||||
"commandText": "status"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`channels.slack.streaming.nativeTransport` controla o streaming de texto nativo do Slack quando `channels.slack.streaming.mode` é `partial` (padrão: `true`).
|
||||
|
||||
- Uma thread de resposta precisa estar disponível para que o streaming de texto nativo e o status de thread de assistente do Slack apareçam. A seleção de thread ainda segue `replyToMode`.
|
||||
- Canais, chats em grupo e raízes de DM de nível superior ainda podem usar a prévia de rascunho normal quando o streaming nativo está indisponível ou não existe thread de resposta.
|
||||
- DMs Slack de nível superior ficam fora de thread por padrão, então não mostram a prévia de stream/status nativo no estilo de thread do Slack; o OpenClaw publica e edita uma prévia de rascunho na DM em vez disso.
|
||||
- Payloads de mídia e não texto fazem fallback para a entrega normal.
|
||||
- Finais de mídia/erro cancelam edições de prévia pendentes; finais elegíveis de texto/bloco só são descarregados quando conseguem editar a prévia no local.
|
||||
- Se o streaming falhar no meio da resposta, o OpenClaw faz fallback para a entrega normal para os payloads restantes.
|
||||
- Raízes de canal, chat em grupo e DM de nível superior ainda podem usar a pré-visualização normal de rascunho quando o streaming nativo está indisponível ou nenhuma thread de resposta existe.
|
||||
- DMs de nível superior do Slack ficam fora de thread por padrão, então não exibem a pré-visualização de stream/status nativo em estilo de thread do Slack; em vez disso, o OpenClaw publica e edita uma pré-visualização de rascunho na DM.
|
||||
- Mídia e payloads não textuais recorrem à entrega normal.
|
||||
- Finais de mídia/erro cancelam edições pendentes de pré-visualização; finais de texto/bloco elegíveis são descarregados somente quando podem editar a pré-visualização no local.
|
||||
- Se o streaming falhar no meio da resposta, o OpenClaw recorre à entrega normal para os payloads restantes.
|
||||
|
||||
Use prévia de rascunho em vez de streaming de texto nativo do Slack:
|
||||
Use pré-visualização de rascunho em vez de streaming de texto nativo do Slack:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -700,58 +719,58 @@ Use prévia de rascunho em vez de streaming de texto nativo do Slack:
|
||||
|
||||
Chaves legadas:
|
||||
|
||||
- `channels.slack.streamMode` (`replace | status_final | append`) é migrado automaticamente para `channels.slack.streaming.mode`.
|
||||
- `channels.slack.streamMode` (`replace | status_final | append`) é migrada automaticamente para `channels.slack.streaming.mode`.
|
||||
- booleano `channels.slack.streaming` é migrado automaticamente para `channels.slack.streaming.mode` e `channels.slack.streaming.nativeTransport`.
|
||||
- `channels.slack.nativeStreaming` legado é migrado automaticamente para `channels.slack.streaming.nativeTransport`.
|
||||
|
||||
## Fallback de reação de digitação
|
||||
|
||||
`typingReaction` adiciona uma reação temporária à mensagem Slack recebida enquanto o OpenClaw processa uma resposta e a remove quando a execução termina. Isso é mais útil fora de respostas em thread, que usam um indicador de status padrão "is typing...".
|
||||
`typingReaction` adiciona uma reação temporária à mensagem de entrada do Slack enquanto o OpenClaw processa uma resposta e a remove quando a execução termina. Isso é mais útil fora de respostas em thread, que usam um indicador de status padrão "está digitando...".
|
||||
|
||||
Ordem de resolução:
|
||||
|
||||
- `channels.slack.accounts.<accountId>.typingReaction`
|
||||
- `channels.slack.typingReaction`
|
||||
|
||||
Notas:
|
||||
Observações:
|
||||
|
||||
- O Slack espera shortcodes (por exemplo `"hourglass_flowing_sand"`).
|
||||
- A reação é best-effort, e a limpeza é tentada automaticamente depois que o caminho de resposta ou falha é concluído.
|
||||
- O Slack espera shortcodes (por exemplo, `"hourglass_flowing_sand"`).
|
||||
- A reação é de melhor esforço, e a limpeza é tentada automaticamente após a conclusão da resposta ou do caminho de falha.
|
||||
|
||||
## Mídia, fragmentação e entrega
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Inbound attachments">
|
||||
Os anexos de arquivo do Slack são baixados de URLs privadas hospedadas pelo Slack (fluxo de solicitação autenticado por token) e gravados no armazenamento de mídia quando a busca tem sucesso e os limites de tamanho permitem. Os placeholders de arquivo incluem o `fileId` do Slack para que os agentes possam buscar o arquivo original com `download-file`.
|
||||
<Accordion title="Anexos de entrada">
|
||||
Anexos de arquivos do Slack são baixados de URLs privadas hospedadas pelo Slack (fluxo de solicitação autenticada por token) e gravados no armazenamento de mídia quando a busca é bem-sucedida e os limites de tamanho permitem. Os placeholders de arquivo incluem o `fileId` do Slack para que os agentes possam buscar o arquivo original com `download-file`.
|
||||
|
||||
Os downloads usam tempos limite ociosos e totais delimitados. Se a recuperação de arquivos do Slack travar ou falhar, o OpenClaw continua processando a mensagem e recorre ao placeholder de arquivo.
|
||||
Os downloads usam tempos limite delimitados de inatividade e totais. Se a recuperação de arquivos do Slack travar ou falhar, o OpenClaw continua processando a mensagem e recorre ao placeholder de arquivo.
|
||||
|
||||
O limite de tamanho de entrada em tempo de execução usa `20MB` por padrão, a menos que seja substituído por `channels.slack.mediaMaxMb`.
|
||||
O limite de tamanho de entrada em runtime usa `20MB` por padrão, a menos que seja substituído por `channels.slack.mediaMaxMb`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Outbound text and files">
|
||||
<Accordion title="Texto e arquivos de saída">
|
||||
- fragmentos de texto usam `channels.slack.textChunkLimit` (padrão 4000)
|
||||
- `channels.slack.chunkMode="newline"` habilita a divisão priorizando parágrafos
|
||||
- envios de arquivos usam APIs de upload do Slack e podem incluir respostas em threads (`thread_ts`)
|
||||
- envios de arquivos usam APIs de upload do Slack e podem incluir respostas em thread (`thread_ts`)
|
||||
- o limite de mídia de saída segue `channels.slack.mediaMaxMb` quando configurado; caso contrário, os envios do canal usam padrões por tipo MIME do pipeline de mídia
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Delivery targets">
|
||||
Destinos explícitos preferenciais:
|
||||
<Accordion title="Destinos de entrega">
|
||||
Destinos explícitos preferidos:
|
||||
|
||||
- `user:<id>` para DMs
|
||||
- `channel:<id>` para canais
|
||||
|
||||
DMs do Slack somente com texto/blocos podem publicar diretamente em IDs de usuário; uploads de arquivos e envios em threads abrem a DM primeiro por meio das APIs de conversa do Slack porque esses caminhos exigem um ID de conversa concreto.
|
||||
DMs do Slack somente com texto/blocos podem postar diretamente em IDs de usuário; uploads de arquivo e envios em thread abrem a DM primeiro pelas APIs de conversa do Slack porque esses caminhos exigem um ID de conversa concreto.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Comandos e comportamento de slash
|
||||
|
||||
Comandos slash aparecem no Slack como um único comando configurado ou vários comandos nativos. Configure `channels.slack.slashCommand` para alterar os padrões de comando:
|
||||
Comandos slash aparecem no Slack como um único comando configurado ou como vários comandos nativos. Configure `channels.slack.slashCommand` para alterar os padrões de comando:
|
||||
|
||||
- `enabled: false`
|
||||
- `name: "openclaw"`
|
||||
@ -762,30 +781,30 @@ Comandos slash aparecem no Slack como um único comando configurado ou vários c
|
||||
/openclaw /help
|
||||
```
|
||||
|
||||
Comandos nativos exigem [configurações adicionais de manifesto](#additional-manifest-settings) no seu app do Slack e são habilitados com `channels.slack.commands.native: true` ou `commands.native: true` em configurações globais.
|
||||
Comandos nativos exigem [configurações adicionais de manifesto](#additional-manifest-settings) no seu aplicativo Slack e são habilitados com `channels.slack.commands.native: true` ou `commands.native: true` em configurações globais.
|
||||
|
||||
- O modo automático de comandos nativos fica **desativado** para Slack, então `commands.native: "auto"` não habilita comandos nativos do Slack.
|
||||
- O modo automático de comandos nativos fica **desativado** para o Slack, então `commands.native: "auto"` não habilita comandos nativos do Slack.
|
||||
|
||||
```txt
|
||||
/help
|
||||
```
|
||||
|
||||
Menus de argumentos nativos usam uma estratégia de renderização adaptativa que mostra um modal de confirmação antes de despachar o valor da opção selecionada:
|
||||
Menus de argumentos nativos usam uma estratégia de renderização adaptativa que mostra um modal de confirmação antes de despachar um valor de opção selecionado:
|
||||
|
||||
- até 5 opções: blocos de botão
|
||||
- 6-100 opções: menu de seleção estática
|
||||
- mais de 100 opções: seleção externa com filtragem assíncrona de opções quando handlers de opções de interatividade estão disponíveis
|
||||
- até 5 opções: blocos de botões
|
||||
- 6-100 opções: menu de seleção estático
|
||||
- mais de 100 opções: seleção externa com filtragem assíncrona de opções quando manipuladores de opções de interatividade estiverem disponíveis
|
||||
- limites do Slack excedidos: valores de opção codificados recorrem a botões
|
||||
|
||||
```txt
|
||||
/think
|
||||
```
|
||||
|
||||
Sessões slash usam chaves isoladas como `agent:<agentId>:slack:slash:<userId>` e ainda roteiam execuções de comandos para a sessão da conversa de destino usando `CommandTargetSessionKey`.
|
||||
Sessões slash usam chaves isoladas como `agent:<agentId>:slack:slash:<userId>` e ainda roteiam execuções de comando para a sessão de conversa de destino usando `CommandTargetSessionKey`.
|
||||
|
||||
## Respostas interativas
|
||||
|
||||
O Slack pode renderizar controles de resposta interativos criados por agentes, mas esse recurso é desabilitado por padrão.
|
||||
O Slack pode renderizar controles de resposta interativa criados por agentes, mas esse recurso fica desabilitado por padrão.
|
||||
|
||||
Habilite globalmente:
|
||||
|
||||
@ -801,7 +820,7 @@ Habilite globalmente:
|
||||
}
|
||||
```
|
||||
|
||||
Ou habilite somente para uma conta do Slack:
|
||||
Ou habilite para apenas uma conta do Slack:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -819,30 +838,30 @@ Ou habilite somente para uma conta do Slack:
|
||||
}
|
||||
```
|
||||
|
||||
Quando habilitado, agentes podem emitir diretivas de resposta exclusivas do Slack:
|
||||
Quando habilitado, os agentes podem emitir diretivas de resposta exclusivas do Slack:
|
||||
|
||||
- `[[slack_buttons: Approve:approve, Reject:reject]]`
|
||||
- `[[slack_select: Choose a target | Canary:canary, Production:production]]`
|
||||
|
||||
Essas diretivas são compiladas para Slack Block Kit e roteiam cliques ou seleções de volta pelo caminho de eventos de interação existente do Slack.
|
||||
Essas diretivas são compiladas para Slack Block Kit e roteiam cliques ou seleções de volta pelo caminho de evento de interação existente do Slack.
|
||||
|
||||
Observações:
|
||||
|
||||
- Esta é uma UI específica do Slack. Outros canais não traduzem diretivas do Slack Block Kit para seus próprios sistemas de botões.
|
||||
- Os valores de callback interativo são tokens opacos gerados pelo OpenClaw, não valores brutos criados pelo agente.
|
||||
- Se os blocos interativos gerados excederem os limites do Slack Block Kit, o OpenClaw recorre à resposta de texto original em vez de enviar uma carga de blocos inválida.
|
||||
- Se os blocos interativos gerados excederem os limites do Slack Block Kit, o OpenClaw recorre à resposta de texto original em vez de enviar uma carga útil de blocos inválida.
|
||||
|
||||
## Aprovações de exec no Slack
|
||||
## Aprovações de execução no Slack
|
||||
|
||||
O Slack pode atuar como um cliente de aprovação nativo com botões e interações interativas, em vez de recorrer à UI Web ou ao terminal.
|
||||
O Slack pode atuar como um cliente de aprovação nativo com botões e interações interativos, em vez de recorrer à UI Web ou ao terminal.
|
||||
|
||||
- Aprovações de exec usam `channels.slack.execApprovals.*` para roteamento nativo de DM/canal.
|
||||
- Aprovações de Plugin ainda podem ser resolvidas pela mesma superfície de botões nativa do Slack quando a solicitação já chega ao Slack e o tipo do ID de aprovação é `plugin:`.
|
||||
- A autorização de aprovadores continua sendo aplicada: somente usuários identificados como aprovadores podem aprovar ou negar solicitações pelo Slack.
|
||||
- Aprovações de execução usam `channels.slack.execApprovals.*` para roteamento nativo de DM/canal.
|
||||
- Aprovações de Plugin ainda podem ser resolvidas pela mesma superfície de botões nativa do Slack quando a solicitação já chega ao Slack e o tipo de ID de aprovação é `plugin:`.
|
||||
- A autorização do aprovador ainda é aplicada: somente usuários identificados como aprovadores podem aprovar ou negar solicitações pelo Slack.
|
||||
|
||||
Isso usa a mesma superfície compartilhada de botões de aprovação de outros canais. Quando `interactivity` está habilitado nas configurações do seu app do Slack, prompts de aprovação são renderizados como botões do Block Kit diretamente na conversa.
|
||||
Isso usa a mesma superfície compartilhada de botões de aprovação que outros canais. Quando `interactivity` está habilitado nas configurações do seu aplicativo Slack, prompts de aprovação são renderizados como botões do Block Kit diretamente na conversa.
|
||||
Quando esses botões estão presentes, eles são a UX principal de aprovação; o OpenClaw
|
||||
só deve incluir um comando manual `/approve` quando o resultado da ferramenta diz que aprovações
|
||||
só deve incluir um comando manual `/approve` quando o resultado da ferramenta disser que aprovações
|
||||
por chat estão indisponíveis ou que a aprovação manual é o único caminho.
|
||||
|
||||
Caminho de configuração:
|
||||
@ -852,11 +871,11 @@ Caminho de configuração:
|
||||
- `channels.slack.execApprovals.target` (`dm` | `channel` | `both`, padrão: `dm`)
|
||||
- `agentFilter`, `sessionFilter`
|
||||
|
||||
O Slack habilita automaticamente aprovações de exec nativas quando `enabled` não está definido ou é `"auto"` e pelo menos um
|
||||
O Slack habilita automaticamente aprovações de execução nativas quando `enabled` não está definido ou é `"auto"` e pelo menos um
|
||||
aprovador é resolvido. Defina `enabled: false` para desabilitar explicitamente o Slack como cliente de aprovação nativo.
|
||||
Defina `enabled: true` para forçar aprovações nativas quando aprovadores forem resolvidos.
|
||||
|
||||
Comportamento padrão sem configuração explícita de aprovação de exec do Slack:
|
||||
Comportamento padrão sem configuração explícita de aprovação de execução do Slack:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -883,37 +902,37 @@ optar por entrega no chat de origem:
|
||||
}
|
||||
```
|
||||
|
||||
O encaminhamento compartilhado de `approvals.exec` é separado. Use-o somente quando prompts de aprovação de exec também precisarem
|
||||
O encaminhamento compartilhado de `approvals.exec` é separado. Use-o somente quando prompts de aprovação de execução também precisarem
|
||||
ser roteados para outros chats ou destinos explícitos fora de banda. O encaminhamento compartilhado de `approvals.plugin` também é
|
||||
separado; botões nativos do Slack ainda podem resolver aprovações de Plugin quando essas solicitações já chegam
|
||||
ao Slack.
|
||||
|
||||
`/approve` no mesmo chat também funciona em canais e DMs do Slack que já aceitam comandos. Consulte [Aprovações de exec](/pt-BR/tools/exec-approvals) para ver o modelo completo de encaminhamento de aprovações.
|
||||
`/approve` no mesmo chat também funciona em canais e DMs do Slack que já dão suporte a comandos. Consulte [Aprovações de execução](/pt-BR/tools/exec-approvals) para ver o modelo completo de encaminhamento de aprovação.
|
||||
|
||||
## Eventos e comportamento operacional
|
||||
|
||||
- Edições/exclusões de mensagens são mapeadas para eventos do sistema.
|
||||
- Transmissões de threads (respostas de thread com "Também enviar ao canal") são processadas como mensagens normais de usuário.
|
||||
- Eventos de adição/remoção de reação são mapeados para eventos do sistema.
|
||||
- Eventos de entrada/saída de membro, canal criado/renomeado e adição/remoção de pin são mapeados para eventos do sistema.
|
||||
- Transmissões de thread (respostas de thread "Também enviar para o canal") são processadas como mensagens normais de usuário.
|
||||
- Eventos de adicionar/remover reação são mapeados para eventos do sistema.
|
||||
- Eventos de entrada/saída de membro, canal criado/renomeado e adicionar/remover fixação são mapeados para eventos do sistema.
|
||||
- `channel_id_changed` pode migrar chaves de configuração de canal quando `configWrites` está habilitado.
|
||||
- Metadados de tópico/propósito do canal são tratados como contexto não confiável e podem ser injetados no contexto de roteamento.
|
||||
- O iniciador da thread e a semeadura inicial de contexto de histórico da thread são filtrados por allowlists de remetentes configuradas quando aplicável.
|
||||
- Ações de bloco e interações modais emitem eventos do sistema estruturados `Slack interaction: ...` com campos de carga ricos:
|
||||
- Metadados de tópico/finalidade do canal são tratados como contexto não confiável e podem ser injetados no contexto de roteamento.
|
||||
- A semente de contexto do iniciador da thread e do histórico inicial da thread é filtrada por allowlists de remetentes configuradas quando aplicável.
|
||||
- Ações de bloco e interações modais emitem eventos de sistema estruturados `Slack interaction: ...` com campos de carga útil ricos:
|
||||
- ações de bloco: valores selecionados, rótulos, valores de seletores e metadados `workflow_*`
|
||||
- eventos modais `view_submission` e `view_closed` com metadados de canal roteados e entradas de formulário
|
||||
- eventos modais `view_submission` e `view_closed` com metadados de canal roteado e entradas de formulário
|
||||
|
||||
## Referência de configuração
|
||||
|
||||
Referência principal: [Referência de configuração - Slack](/pt-BR/gateway/config-channels#slack).
|
||||
|
||||
<Accordion title="High-signal Slack fields">
|
||||
<Accordion title="Campos Slack de alto sinal">
|
||||
|
||||
- modo/auth: `mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*`
|
||||
- modo/autenticação: `mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*`
|
||||
- acesso a DM: `dm.enabled`, `dmPolicy`, `allowFrom` (legado: `dm.policy`, `dm.allowFrom`), `dm.groupEnabled`, `dm.groupChannels`
|
||||
- alternância de compatibilidade: `dangerouslyAllowNameMatching` (quebra-vidro; mantenha desativado, a menos que necessário)
|
||||
- acesso a canais: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention`
|
||||
- threading/histórico: `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit`
|
||||
- alternância de compatibilidade: `dangerouslyAllowNameMatching` (uso emergencial; mantenha desativado a menos que necessário)
|
||||
- acesso a canal: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention`
|
||||
- threads/histórico: `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit`
|
||||
- entrega: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `streaming.nativeTransport`, `streaming.preview.toolProgress`
|
||||
- ops/recursos: `configWrites`, `commands.native`, `slashCommand.*`, `actions.*`, `userToken`, `userTokenReadOnly`
|
||||
|
||||
@ -922,13 +941,13 @@ Referência principal: [Referência de configuração - Slack](/pt-BR/gateway/co
|
||||
## Solução de problemas
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="No replies in channels">
|
||||
<Accordion title="Sem respostas em canais">
|
||||
Verifique, na ordem:
|
||||
|
||||
- `groupPolicy`
|
||||
- allowlist de canal (`channels.slack.channels`) — **as chaves devem ser IDs de canal** (`C12345678`), não nomes (`#channel-name`). Chaves baseadas em nome falham silenciosamente sob `groupPolicy: "allowlist"` porque o roteamento de canais prioriza IDs por padrão. Para encontrar um ID: clique com o botão direito no canal no Slack → **Copiar link** — o valor `C...` no fim da URL é o ID do canal.
|
||||
- allowlist de canais (`channels.slack.channels`) — **as chaves devem ser IDs de canal** (`C12345678`), não nomes (`#channel-name`). Chaves baseadas em nome falham silenciosamente em `groupPolicy: "allowlist"` porque o roteamento de canal prioriza IDs por padrão. Para encontrar um ID: clique com o botão direito no canal no Slack → **Copiar link** — o valor `C...` no fim da URL é o ID do canal.
|
||||
- `requireMention`
|
||||
- allowlist `users` por canal
|
||||
- allowlist de `users` por canal
|
||||
|
||||
Comandos úteis:
|
||||
|
||||
@ -940,14 +959,14 @@ openclaw doctor
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="DM messages ignored">
|
||||
<Accordion title="Mensagens de DM ignoradas">
|
||||
Verifique:
|
||||
|
||||
- `channels.slack.dm.enabled`
|
||||
- `channels.slack.dmPolicy` (ou o legado `channels.slack.dm.policy`)
|
||||
- `channels.slack.dmPolicy` (ou legado `channels.slack.dm.policy`)
|
||||
- aprovações de pareamento / entradas de allowlist
|
||||
- Eventos de DM do Slack Assistant: logs detalhados mencionando `drop message_changed`
|
||||
geralmente significam que o Slack enviou um evento de thread do Assistant editado sem um
|
||||
- eventos de DM do Slack Assistant: logs detalhados mencionando `drop message_changed`
|
||||
geralmente significam que o Slack enviou um evento editado de thread do Assistant sem um
|
||||
remetente humano recuperável nos metadados da mensagem
|
||||
|
||||
```bash
|
||||
@ -956,54 +975,54 @@ openclaw pairing list slack
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Socket mode not connecting">
|
||||
Valide tokens de bot + app e a habilitação do Socket Mode nas configurações do app do Slack.
|
||||
<Accordion title="Socket mode não conecta">
|
||||
Valide tokens de bot + app e a habilitação do Socket Mode nas configurações do aplicativo Slack.
|
||||
|
||||
Se `openclaw channels status --probe --json` mostrar `botTokenStatus` ou
|
||||
`appTokenStatus: "configured_unavailable"`, a conta do Slack está
|
||||
configurada, mas o runtime atual não conseguiu resolver o valor baseado em
|
||||
SecretRef.
|
||||
configurada, mas o runtime atual não conseguiu resolver o valor
|
||||
respaldado por SecretRef.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="HTTP mode not receiving events">
|
||||
<Accordion title="Modo HTTP não recebe eventos">
|
||||
Valide:
|
||||
|
||||
- segredo de assinatura
|
||||
- caminho de Webhook
|
||||
- URLs de solicitação do Slack (Eventos + Interatividade + Comandos slash)
|
||||
- `webhookPath` único por conta HTTP
|
||||
- URLs de solicitação do Slack (Eventos + Interatividade + Comandos Slash)
|
||||
- `webhookPath` exclusivo por conta HTTP
|
||||
|
||||
Se `signingSecretStatus: "configured_unavailable"` aparecer em snapshots de conta,
|
||||
a conta HTTP está configurada, mas o runtime atual não conseguiu
|
||||
resolver o segredo de assinatura baseado em SecretRef.
|
||||
resolver o segredo de assinatura respaldado por SecretRef.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Native/slash commands not firing">
|
||||
<Accordion title="Comandos nativos/slash não disparam">
|
||||
Verifique se você pretendia usar:
|
||||
|
||||
- modo de comando nativo (`channels.slack.commands.native: true`) com comandos slash correspondentes registrados no Slack
|
||||
- ou modo de comando slash único (`channels.slack.slashCommand.enabled: true`)
|
||||
|
||||
Também verifique `commands.useAccessGroups` e allowlists de canal/usuário.
|
||||
Verifique também `commands.useAccessGroups` e allowlists de canais/usuários.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Referência de visão de anexos
|
||||
|
||||
O Slack pode anexar mídia baixada ao turno do agente quando downloads de arquivos do Slack têm sucesso e os limites de tamanho permitem. Arquivos de imagem podem ser passados pelo caminho de compreensão de mídia ou diretamente para um modelo de resposta compatível com visão; outros arquivos são retidos como contexto de arquivo baixável em vez de tratados como entrada de imagem.
|
||||
O Slack pode anexar mídia baixada ao turno do agente quando downloads de arquivo do Slack são bem-sucedidos e os limites de tamanho permitem. Arquivos de imagem podem passar pelo caminho de compreensão de mídia ou diretamente para um modelo de resposta com capacidade de visão; outros arquivos são mantidos como contexto de arquivo baixável, em vez de serem tratados como entrada de imagem.
|
||||
|
||||
### Tipos de mídia compatíveis
|
||||
|
||||
| Tipo de mídia | Origem | Comportamento atual | Observações |
|
||||
| ------------------------------ | -------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
|
||||
| Imagens JPEG / PNG / GIF / WebP | URL de arquivo do Slack | Baixadas e anexadas ao turno para tratamento com suporte a visão | Limite por arquivo: `channels.slack.mediaMaxMb` (padrão 20 MB) |
|
||||
| Tipo de mídia | Origem | Comportamento atual | Observações |
|
||||
| ------------------------------ | -------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
|
||||
| Imagens JPEG / PNG / GIF / WebP | URL de arquivo do Slack | Baixadas e anexadas ao turno para tratamento compatível com visão | Limite por arquivo: `channels.slack.mediaMaxMb` (padrão 20 MB) |
|
||||
| Arquivos PDF | URL de arquivo do Slack | Baixados e expostos como contexto de arquivo para ferramentas como `download-file` ou `pdf` | A entrada do Slack não converte PDFs automaticamente em entrada de visão por imagem |
|
||||
| Outros arquivos | URL de arquivo do Slack | Baixados quando possível e expostos como contexto de arquivo | Arquivos binários não são tratados como entrada de imagem |
|
||||
| Respostas em thread | Arquivos do iniciador da thread | Arquivos da mensagem raiz podem ser hidratados como contexto quando a resposta não tem mídia direta | Iniciadores apenas com arquivo usam um placeholder de anexo |
|
||||
| Mensagens com várias imagens | Vários arquivos do Slack | Cada arquivo é avaliado independentemente | O processamento do Slack é limitado a oito arquivos por mensagem |
|
||||
| Outros arquivos | URL de arquivo do Slack | Baixados quando possível e expostos como contexto de arquivo | Arquivos binários não são tratados como entrada de imagem |
|
||||
| Respostas em thread | Arquivos do início da thread | Arquivos da mensagem raiz podem ser hidratados como contexto quando a resposta não tem mídia direta | Inícios somente com arquivo usam um placeholder de anexo |
|
||||
| Mensagens com múltiplas imagens | Vários arquivos do Slack | Cada arquivo é avaliado de forma independente | O processamento do Slack é limitado a oito arquivos por mensagem |
|
||||
|
||||
### Pipeline de entrada
|
||||
|
||||
@ -1011,70 +1030,70 @@ Quando uma mensagem do Slack com anexos de arquivo chega:
|
||||
|
||||
1. O OpenClaw baixa o arquivo da URL privada do Slack usando o token do bot (`xoxb-...`).
|
||||
2. O arquivo é gravado no armazenamento de mídia em caso de sucesso.
|
||||
3. Caminhos de mídia baixada e tipos de conteúdo são adicionados ao contexto de entrada.
|
||||
4. Caminhos de modelo/ferramenta com suporte a imagem podem usar anexos de imagem desse contexto.
|
||||
5. Arquivos que não são imagens permanecem disponíveis como metadados de arquivo ou referências de mídia para ferramentas que conseguem processá-los.
|
||||
3. Os caminhos de mídia baixados e os tipos de conteúdo são adicionados ao contexto de entrada.
|
||||
4. Caminhos de modelo/ferramenta compatíveis com imagem podem usar anexos de imagem desse contexto.
|
||||
5. Arquivos que não são imagem permanecem disponíveis como metadados de arquivo ou referências de mídia para ferramentas que conseguem lidar com eles.
|
||||
|
||||
### Herança de anexos da raiz da thread
|
||||
|
||||
Quando uma mensagem chega em uma thread (tem um pai `thread_ts`):
|
||||
|
||||
- Se a própria resposta não tiver mídia direta e a mensagem raiz incluída tiver arquivos, o Slack pode hidratar os arquivos da raiz como contexto do iniciador da thread.
|
||||
- Se a própria resposta não tiver mídia direta e a mensagem raiz incluída tiver arquivos, o Slack pode hidratar os arquivos raiz como contexto de início da thread.
|
||||
- Anexos diretos da resposta têm precedência sobre anexos da mensagem raiz.
|
||||
- Uma mensagem raiz que tem apenas arquivos e nenhum texto é representada com um placeholder de anexo para que o fallback ainda possa incluir seus arquivos.
|
||||
|
||||
### Tratamento de vários anexos
|
||||
### Tratamento de múltiplos anexos
|
||||
|
||||
Quando uma única mensagem do Slack contém vários anexos de arquivo:
|
||||
|
||||
- Cada anexo é processado independentemente pelo pipeline de mídia.
|
||||
- Referências de mídia baixada são agregadas ao contexto da mensagem.
|
||||
- Cada anexo é processado de forma independente pelo pipeline de mídia.
|
||||
- Referências de mídia baixadas são agregadas ao contexto da mensagem.
|
||||
- A ordem de processamento segue a ordem dos arquivos do Slack no payload do evento.
|
||||
- Uma falha no download de um anexo não bloqueia os demais.
|
||||
- Uma falha no download de um anexo não bloqueia os outros.
|
||||
|
||||
### Limites de tamanho, download e modelo
|
||||
|
||||
- **Limite de tamanho**: Padrão de 20 MB por arquivo. Configurável via `channels.slack.mediaMaxMb`.
|
||||
- **Falhas de download**: Arquivos que o Slack não consegue servir, URLs expiradas, arquivos inacessíveis, arquivos grandes demais e respostas HTML de autenticação/login do Slack são ignorados em vez de serem relatados como formatos não compatíveis.
|
||||
- **Modelo de visão**: A análise de imagem usa o modelo de resposta ativo quando ele tem suporte a visão, ou o modelo de imagem configurado em `agents.defaults.imageModel`.
|
||||
- **Limite de tamanho**: padrão de 20 MB por arquivo. Configurável via `channels.slack.mediaMaxMb`.
|
||||
- **Falhas de download**: arquivos que o Slack não consegue servir, URLs expiradas, arquivos inacessíveis, arquivos grandes demais e respostas HTML de autenticação/login do Slack são ignorados em vez de serem relatados como formatos incompatíveis.
|
||||
- **Modelo de visão**: a análise de imagem usa o modelo de resposta ativo quando ele oferece suporte a visão, ou o modelo de imagem configurado em `agents.defaults.imageModel`.
|
||||
|
||||
### Limites conhecidos
|
||||
|
||||
| Cenário | Comportamento atual | Solução alternativa |
|
||||
| Cenário | Comportamento atual | Solução alternativa |
|
||||
| -------------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
|
||||
| URL de arquivo do Slack expirada | Arquivo ignorado; nenhum erro exibido | Reenvie o arquivo no Slack |
|
||||
| Modelo de visão não configurado | Anexos de imagem são armazenados como referências de mídia, mas não analisados como imagens | Configure `agents.defaults.imageModel` ou use um modelo de resposta com suporte a visão |
|
||||
| Imagens muito grandes (> 20 MB por padrão) | Ignoradas pelo limite de tamanho | Aumente `channels.slack.mediaMaxMb` se o Slack permitir |
|
||||
| Anexos encaminhados/compartilhados | Texto e mídia de imagem/arquivo hospedada no Slack são tratados em modo best-effort | Compartilhe novamente diretamente na thread do OpenClaw |
|
||||
| Anexos PDF | Armazenados como contexto de arquivo/mídia, não roteados automaticamente pela visão de imagem | Use `download-file` para metadados de arquivo ou a ferramenta `pdf` para análise de PDF |
|
||||
| URL de arquivo do Slack expirada | Arquivo ignorado; nenhum erro exibido | Reenvie o arquivo no Slack |
|
||||
| Modelo de visão não configurado | Anexos de imagem são armazenados como referências de mídia, mas não analisados como imagens | Configure `agents.defaults.imageModel` ou use um modelo de resposta compatível com visão |
|
||||
| Imagens muito grandes (> 20 MB por padrão) | Ignoradas pelo limite de tamanho | Aumente `channels.slack.mediaMaxMb` se o Slack permitir |
|
||||
| Anexos encaminhados/compartilhados | Texto e mídia de imagem/arquivo hospedada no Slack são tratados da melhor forma possível | Recompartilhe diretamente na thread do OpenClaw |
|
||||
| Anexos PDF | Armazenados como contexto de arquivo/mídia, não roteados automaticamente pela visão de imagem | Use `download-file` para metadados de arquivo ou a ferramenta `pdf` para análise de PDF |
|
||||
|
||||
### Documentação relacionada
|
||||
|
||||
- [Pipeline de compreensão de mídia](/pt-BR/nodes/media-understanding)
|
||||
- [Ferramenta PDF](/pt-BR/tools/pdf)
|
||||
- Épico: [#51349](https://github.com/openclaw/openclaw/issues/51349) — habilitação de visão para anexos do Slack
|
||||
- Epic: [#51349](https://github.com/openclaw/openclaw/issues/51349) — habilitação de visão para anexos do Slack
|
||||
- Testes de regressão: [#51353](https://github.com/openclaw/openclaw/issues/51353)
|
||||
- Verificação ao vivo: [#51354](https://github.com/openclaw/openclaw/issues/51354)
|
||||
|
||||
## Relacionado
|
||||
## Relacionados
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Pairing" icon="link" href="/pt-BR/channels/pairing">
|
||||
Emparelhe um usuário do Slack ao Gateway.
|
||||
<Card title="Pareamento" icon="link" href="/pt-BR/channels/pairing">
|
||||
Pareie um usuário do Slack ao Gateway.
|
||||
</Card>
|
||||
<Card title="Groups" icon="users" href="/pt-BR/channels/groups">
|
||||
Comportamento de canais e DMs de grupo.
|
||||
<Card title="Grupos" icon="users" href="/pt-BR/channels/groups">
|
||||
Comportamento de canal e DM em grupo.
|
||||
</Card>
|
||||
<Card title="Channel routing" icon="route" href="/pt-BR/channels/channel-routing">
|
||||
<Card title="Roteamento de canal" icon="route" href="/pt-BR/channels/channel-routing">
|
||||
Roteie mensagens de entrada para agentes.
|
||||
</Card>
|
||||
<Card title="Security" icon="shield" href="/pt-BR/gateway/security">
|
||||
<Card title="Segurança" icon="shield" href="/pt-BR/gateway/security">
|
||||
Modelo de ameaças e hardening.
|
||||
</Card>
|
||||
<Card title="Configuration" icon="sliders" href="/pt-BR/gateway/configuration">
|
||||
Layout e precedência da configuração.
|
||||
<Card title="Configuração" icon="sliders" href="/pt-BR/gateway/configuration">
|
||||
Layout e precedência de configuração.
|
||||
</Card>
|
||||
<Card title="Slash commands" icon="terminal" href="/pt-BR/tools/slash-commands">
|
||||
<Card title="Comandos slash" icon="terminal" href="/pt-BR/tools/slash-commands">
|
||||
Catálogo e comportamento de comandos.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -4,24 +4,24 @@ read_when:
|
||||
summary: Status de suporte, recursos e configuração do bot do Telegram
|
||||
title: Telegram
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T21:27:12Z"
|
||||
generated_at: "2026-05-04T07:02:43Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 528ace9dae29eda22f98cc1436ec16146eb9d83edc73aa6db1ab8283f4f873c0
|
||||
source_hash: 6ef1b019a6a0e261b33972b5edffaedd29310b1333d112bade2e79e9d56887c6
|
||||
source_path: channels/telegram.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Pronto para produção para DMs e grupos de bot via grammY. Long polling é o modo padrão; o modo webhook é opcional.
|
||||
Pronto para produção para DMs e grupos de bots via grammY. O long polling é o modo padrão; o modo Webhook é opcional.
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Pairing" icon="link" href="/pt-BR/channels/pairing">
|
||||
A política padrão de DM para Telegram é pairing.
|
||||
<Card title="Emparelhamento" icon="link" href="/pt-BR/channels/pairing">
|
||||
A política padrão de DM para Telegram é emparelhamento.
|
||||
</Card>
|
||||
<Card title="Channel troubleshooting" icon="wrench" href="/pt-BR/channels/troubleshooting">
|
||||
<Card title="Solução de problemas de canais" icon="wrench" href="/pt-BR/channels/troubleshooting">
|
||||
Diagnósticos entre canais e playbooks de reparo.
|
||||
</Card>
|
||||
<Card title="Gateway configuration" icon="settings" href="/pt-BR/gateway/configuration">
|
||||
<Card title="Configuração do Gateway" icon="settings" href="/pt-BR/gateway/configuration">
|
||||
Padrões e exemplos completos de configuração de canal.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@ -29,14 +29,14 @@ Pronto para produção para DMs e grupos de bot via grammY. Long polling é o mo
|
||||
## Configuração rápida
|
||||
|
||||
<Steps>
|
||||
<Step title="Create the bot token in BotFather">
|
||||
<Step title="Crie o token do bot no BotFather">
|
||||
Abra o Telegram e converse com **@BotFather** (confirme que o identificador é exatamente `@BotFather`).
|
||||
|
||||
Execute `/newbot`, siga as instruções e salve o token.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Configure token and DM policy">
|
||||
<Step title="Configure o token e a política de DM">
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -52,11 +52,11 @@ Pronto para produção para DMs e grupos de bot via grammY. Long polling é o mo
|
||||
```
|
||||
|
||||
Fallback de env: `TELEGRAM_BOT_TOKEN=...` (somente conta padrão).
|
||||
Telegram **não** usa `openclaw channels login telegram`; configure o token em config/env e então inicie o gateway.
|
||||
Telegram **não** usa `openclaw channels login telegram`; configure o token na configuração/env e depois inicie o Gateway.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Start gateway and approve first DM">
|
||||
<Step title="Inicie o Gateway e aprove a primeira DM">
|
||||
|
||||
```bash
|
||||
openclaw gateway
|
||||
@ -64,42 +64,42 @@ openclaw pairing list telegram
|
||||
openclaw pairing approve telegram <CODE>
|
||||
```
|
||||
|
||||
Códigos de pairing expiram após 1 hora.
|
||||
Os códigos de emparelhamento expiram após 1 hora.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Add the bot to a group">
|
||||
Adicione o bot ao seu grupo e então defina `channels.telegram.groups` e `groupPolicy` para corresponder ao seu modelo de acesso.
|
||||
<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.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
A ordem de resolução de tokens considera a conta. Na prática, valores de configuração prevalecem sobre o fallback de env, e `TELEGRAM_BOT_TOKEN` se aplica apenas à conta padrão.
|
||||
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.
|
||||
</Note>
|
||||
|
||||
## Configurações no lado do Telegram
|
||||
## Configurações do lado do Telegram
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Privacy mode and group visibility">
|
||||
Bots do Telegram usam **Privacy Mode** por padrão, o que limita quais mensagens de grupo eles recebem.
|
||||
<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:
|
||||
Se o bot precisar ver todas as mensagens de grupo, faça uma destas opções:
|
||||
|
||||
- desative o modo de privacidade via `/setprivacy`, ou
|
||||
- torne o bot um administrador do grupo.
|
||||
- torne o bot administrador do grupo.
|
||||
|
||||
Ao alternar o modo de privacidade, remova e adicione novamente o bot em cada grupo para que o Telegram aplique a alteração.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Group permissions">
|
||||
O status de administrador é controlado nas configurações do grupo do Telegram.
|
||||
<Accordion title="Permissões de grupo">
|
||||
O status de administrador é controlado nas configurações de grupo do Telegram.
|
||||
|
||||
Bots administradores recebem todas as mensagens de grupo, o que é útil para comportamento de grupo sempre ativo.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Helpful BotFather toggles">
|
||||
<Accordion title="Alternâncias úteis do BotFather">
|
||||
|
||||
- `/setjoingroups` para permitir/negar adições a grupos
|
||||
- `/setprivacy` para comportamento de visibilidade em grupos
|
||||
@ -110,7 +110,7 @@ A ordem de resolução de tokens considera a conta. Na prática, valores de conf
|
||||
## Controle de acesso e ativação
|
||||
|
||||
<Tabs>
|
||||
<Tab title="DM policy">
|
||||
<Tab title="Política de DM">
|
||||
`channels.telegram.dmPolicy` controla o acesso por mensagem direta:
|
||||
|
||||
- `pairing` (padrão)
|
||||
@ -118,23 +118,23 @@ A ordem de resolução de tokens considera a conta. Na prática, valores de conf
|
||||
- `open` (exige que `allowFrom` inclua `"*"`)
|
||||
- `disabled`
|
||||
|
||||
`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 apenas para bots intencionalmente públicos com ferramentas estritamente restritas; bots de um único proprietário devem usar `allowlist` com IDs numéricos de usuário.
|
||||
`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 múltiplas 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 allowlist 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 apenas IDs numéricos de usuário.
|
||||
Se você atualizou e sua configuração contém entradas de allowlist `@username`, execute `openclaw doctor --fix` para resolvê-las (melhor esforço; exige um token de bot do Telegram).
|
||||
Se você dependia anteriormente de arquivos de allowlist do armazenamento de pairing, `openclaw doctor --fix` pode recuperar entradas para `channels.telegram.allowFrom` em fluxos de allowlist (por exemplo, quando `dmPolicy: "allowlist"` ainda não tem IDs explícitos).
|
||||
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).
|
||||
|
||||
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 pairing 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 emparelhamento anteriores).
|
||||
|
||||
Confusão comum: aprovação de pairing por DM não significa "este remetente está autorizado em todos os lugares".
|
||||
O pairing concede acesso por DM. Se ainda não existir proprietário de comandos, o primeiro pairing aprovado também define `commands.ownerAllowFrom` para que comandos somente de proprietário e aprovações de execução tenham uma conta de operador explícita.
|
||||
A autorização de remetente em grupo ainda vem de allowlists explícitas na configuração.
|
||||
Se você quer "eu 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 somente de proprietário, verifique se `commands.ownerAllowFrom` contém `telegram:<your user id>`.
|
||||
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>`.
|
||||
|
||||
### Encontrar seu ID de usuário do Telegram
|
||||
### Encontrando seu ID de usuário do Telegram
|
||||
|
||||
Mais seguro (sem bot de terceiros):
|
||||
|
||||
@ -152,14 +152,14 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Group policy and allowlists">
|
||||
<Tab title="Política de grupo e listas de permissões">
|
||||
Dois controles se aplicam em conjunto:
|
||||
|
||||
1. **Quais grupos são permitidos** (`channels.telegram.groups`)
|
||||
- sem configuração `groups`:
|
||||
- com `groupPolicy: "open"`: qualquer grupo pode passar nas verificações de ID de grupo
|
||||
- com `groupPolicy: "allowlist"` (padrão): grupos são bloqueados até você adicionar entradas em `groups` (ou `"*"`)
|
||||
- `groups` configurado: atua como allowlist (IDs explícitos ou `"*"`)
|
||||
- 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 `"*"`)
|
||||
|
||||
2. **Quais remetentes são permitidos em grupos** (`channels.telegram.groupPolicy`)
|
||||
- `open`
|
||||
@ -168,13 +168,13 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
`groupAllowFrom` é usado para filtragem de remetentes em grupo. Se não definido, 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 grupo ou supergrupo do Telegram em `groupAllowFrom`. IDs de chat negativos pertencem a `channels.telegram.groups`.
|
||||
Não coloque IDs de chat de grupos ou supergrupos 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 do armazenamento de pairing de DM.
|
||||
Pairing continua sendo somente para DM. Para grupos, defina `groupAllowFrom` ou `allowFrom` por grupo/por tópico.
|
||||
Se `groupAllowFrom` não estiver definido, Telegram recorre ao `allowFrom` da configuração, não ao armazenamento de pairing.
|
||||
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`.
|
||||
Nota de runtime: se `channels.telegram` estiver completamente ausente, o runtime usa por padrão fail-closed `groupPolicy="allowlist"`, 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 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.
|
||||
|
||||
Exemplo: permitir qualquer membro em um grupo específico:
|
||||
|
||||
@ -211,17 +211,17 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Erro comum: `groupAllowFrom` não é uma allowlist de grupos do Telegram.
|
||||
Erro comum: `groupAllowFrom` não é uma lista de permissões de grupos do Telegram.
|
||||
|
||||
- Coloque IDs de chat negativos de grupo ou supergrupo do Telegram, como `-1001234567890`, em `channels.telegram.groups`.
|
||||
- Coloque IDs de chat negativos de grupos ou supergrupos do Telegram, como `-1001234567890`, em `channels.telegram.groups`.
|
||||
- Coloque IDs de usuário do Telegram, como `8734062810`, em `groupAllowFrom` quando quiser limitar quais pessoas dentro de um grupo permitido podem acionar o bot.
|
||||
- Use `groupAllowFrom: ["*"]` somente quando quiser que qualquer membro de um grupo permitido possa falar com o bot.
|
||||
- Use `groupAllowFrom: ["*"]` somente quando quiser que qualquer membro de um grupo permitido consiga falar com o bot.
|
||||
|
||||
</Warning>
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Mention behavior">
|
||||
<Tab title="Comportamento de menção">
|
||||
Respostas em grupo exigem menção por padrão.
|
||||
|
||||
A menção pode vir de:
|
||||
@ -236,7 +236,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `/activation always`
|
||||
- `/activation mention`
|
||||
|
||||
Elas atualizam apenas o estado da sessão. Use configuração para persistência.
|
||||
Elas atualizam somente o estado da sessão. Use configuração para persistência.
|
||||
|
||||
Exemplo de configuração persistente:
|
||||
|
||||
@ -252,7 +252,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Obter o ID do chat de grupo:
|
||||
Obtendo o ID do chat do grupo:
|
||||
|
||||
- encaminhe uma mensagem do grupo para `@userinfobot` / `@getidsbot`
|
||||
- ou leia `chat.id` em `openclaw logs --follow`
|
||||
@ -263,20 +263,20 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
## Comportamento de runtime
|
||||
|
||||
- Telegram é propriedade do processo do gateway.
|
||||
- O roteamento é determinístico: entradas do Telegram respondem de volta ao Telegram (o modelo não escolhe canais).
|
||||
- Mensagens de entrada são normalizadas para o envelope de canal compartilhado com metadados de resposta e placeholders de mídia.
|
||||
- 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.
|
||||
- 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 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 de DM.
|
||||
- Long polling usa grammY runner com sequenciamento por chat/por thread. A concorrência geral do sink 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 OpenClaw, script ou poller externo provavelmente está usando o mesmo token.
|
||||
- Reinícios do watchdog de long polling são acionados após 120 segundos sem liveness de `getUpdates` concluído por padrão. Aumente `channels.telegram.pollingStallThresholdMs` somente se sua implantação ainda vir reinícios falsos por polling paralisado 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 Telegram Bot API não oferece suporte a confirmação de leitura (`sendReadReceipts` não se aplica).
|
||||
- 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).
|
||||
|
||||
## Referência de recursos
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Live stream preview (message edits)">
|
||||
<Accordion title="Prévia de transmissão ao vivo (edições de mensagem)">
|
||||
OpenClaw pode transmitir respostas parciais em tempo real:
|
||||
|
||||
- chats diretos: mensagem de prévia + `editMessageText`
|
||||
@ -286,10 +286,11 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
- `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
|
||||
- `streaming.preview.toolProgress` controla se atualizações de ferramenta/progresso reutilizam a mesma mensagem de prévia editada (padrão: `true` quando streaming de prévia está ativo)
|
||||
- `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`
|
||||
|
||||
Atualizações de prévia de progresso de ferramentas são as linhas curtas de status mostradas enquanto ferramentas executam, por exemplo execução de comandos, leituras de arquivos, atualizações de planejamento ou resumos de patches. Telegram mantém essas atualizações 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 ferramentas, defina:
|
||||
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:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -306,25 +307,61 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Use `streaming.mode: "off"` somente quando você quiser entrega apenas final: as edições de prévia do Telegram são desativadas e a conversa genérica de ferramentas/progresso é suprimida em vez de ser enviada como mensagens de status independentes. Prompts de aprovação, cargas de mídia e erros ainda são roteados pela entrega final normal. Use `streaming.preview.toolProgress: false` quando você quiser apenas manter as edições de prévia da resposta enquanto oculta as linhas de status de progresso da ferramenta.
|
||||
Para manter o progresso de ferramenta visível, mas ocultar texto de comando/execução, defina:
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"telegram": {
|
||||
"streaming": {
|
||||
"mode": "partial",
|
||||
"preview": {
|
||||
"commandText": "status"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Para o modo de rascunho de progresso, coloque a mesma política de texto de comando em `streaming.progress`:
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"telegram": {
|
||||
"streaming": {
|
||||
"mode": "progress",
|
||||
"progress": {
|
||||
"toolProgress": true,
|
||||
"commandText": "status"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
<Note>
|
||||
Respostas com citação selecionada 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évia da resposta, portanto `streaming.preview.toolProgress` não consegue mostrar as linhas curtas de status nesse turno. 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 for mais importante do que respostas nativas com citação, ou defina `streaming.preview.toolProgress: false` para reconhecer a troca.
|
||||
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.
|
||||
</Note>
|
||||
|
||||
Para respostas somente de texto:
|
||||
Para respostas somente em texto:
|
||||
|
||||
- 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 de prévia tenha sido enviada depois que a prévia apareceu
|
||||
- prévias seguidas por saída visível que não seja de prévia: o OpenClaw envia a resposta concluída como uma nova mensagem final e limpa a prévia mais antiga, para 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 então limpa a prévia, para que o timestamp visível do Telegram reflita o horário de conclusão em vez do horário de criação da prévia
|
||||
- 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
|
||||
|
||||
Para respostas complexas (por exemplo, cargas de mídia), o OpenClaw recorre à entrega final normal e então limpa a mensagem de 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.
|
||||
|
||||
Streaming de prévia é separado de streaming de blocos. Quando o streaming de blocos é explicitamente habilitado para Telegram, o OpenClaw ignora o stream de prévia para evitar streaming duplicado.
|
||||
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.
|
||||
|
||||
Stream de raciocínio exclusivo do Telegram:
|
||||
Stream de raciocínio somente no Telegram:
|
||||
|
||||
- `/reasoning stream` envia o raciocínio para a prévia ao vivo durante a geração
|
||||
- `/reasoning stream` envia o raciocínio para a pré-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
|
||||
- a resposta final é enviada sem texto de raciocínio
|
||||
|
||||
</Accordion>
|
||||
@ -332,20 +369,20 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
<Accordion title="Formatação e fallback de HTML">
|
||||
O texto de saída usa `parse_mode: "HTML"` do Telegram.
|
||||
|
||||
- Texto no estilo Markdown é renderizado como HTML seguro para Telegram.
|
||||
- Texto no estilo Markdown é renderizado como HTML seguro para o 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.
|
||||
|
||||
Prévias de link são habilitadas por padrão e podem ser desabilitadas com `channels.telegram.linkPreview: false`.
|
||||
Pré-visualizações de links 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 comandos nativos:
|
||||
Padrões de comando nativo:
|
||||
|
||||
- `commands.native: "auto"` habilita comandos nativos para Telegram
|
||||
- `commands.native: "auto"` ativa comandos nativos para o Telegram
|
||||
|
||||
Adicione entradas personalizadas ao menu de comandos:
|
||||
|
||||
@ -367,37 +404,37 @@ 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
|
||||
- conflitos/duplicatas são ignorados e registrados em log
|
||||
|
||||
Observações:
|
||||
|
||||
- comandos personalizados são apenas entradas de menu; eles não implementam comportamento automaticamente
|
||||
- comandos de plugin/skill ainda podem funcionar quando digitados, mesmo se não forem mostrados no menu do Telegram
|
||||
- comandos de Plugin/Skills ainda podem funcionar quando digitados, mesmo que não apareçam no menu do Telegram
|
||||
|
||||
Se comandos nativos estiverem desabilitados, os integrados sã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 o corte; reduza comandos de plugin/skill/personalizados ou desabilite `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 uma terminação acidental `/bot<TOKEN>`.
|
||||
- `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, portanto isso não é relatado como 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/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 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`)
|
||||
### Comandos de pareamento de dispositivo (Plugin `device-pair`)
|
||||
|
||||
Quando o plugin `device-pair` estiver instalado:
|
||||
Quando o Plugin `device-pair` está instalado:
|
||||
|
||||
1. `/pair` gera código de configuração
|
||||
1. `/pair` gera o 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:
|
||||
- `/pair approve <requestId>` para aprovação explícita
|
||||
- `/pair approve` quando houver apenas uma solicitação pendente
|
||||
- `/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. O handoff de bootstrap integrado mantém o token do node primário em `scopes: []`; qualquer token de operador repassado 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 só satisfaz solicitações de operador; funções que não são 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 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.
|
||||
|
||||
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 novamente `/pair pending` antes de aprovar.
|
||||
Se um dispositivo tentar novamente com detalhes de autenticação alterados (por exemplo, função/escopos/chave pública), a solicitação pendente anterior será substituída e a nova solicitação usará um `requestId` diferente. Execute `/pair pending` novamente antes de aprovar.
|
||||
|
||||
Mais detalhes: [Pareamento](/pt-BR/channels/pairing#pair-via-telegram-recommended-for-ios).
|
||||
|
||||
@ -444,7 +481,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `all`
|
||||
- `allowlist` (padrão)
|
||||
|
||||
`capabilities: ["inlineButtons"]` legado mapeia para `inlineButtons: "all"`.
|
||||
`capabilities: ["inlineButtons"]` legado é mapeado para `inlineButtons: "all"`.
|
||||
|
||||
Exemplo de ação de mensagem:
|
||||
|
||||
@ -469,36 +506,36 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Ações de mensagens do Telegram para agentes e automação">
|
||||
<Accordion title="Ações de mensagem do Telegram para agentes e automação">
|
||||
As ações de ferramenta do Telegram incluem:
|
||||
|
||||
- `sendMessage` (`to`, `content`, `mediaUrl` opcional, `replyToMessageId`, `messageThreadId`)
|
||||
- `sendMessage` (`to`, `content`, opcional `mediaUrl`, `replyToMessageId`, `messageThreadId`)
|
||||
- `react` (`chatId`, `messageId`, `emoji`)
|
||||
- `deleteMessage` (`chatId`, `messageId`)
|
||||
- `editMessage` (`chatId`, `messageId`, `content`)
|
||||
- `createForumTopic` (`chatId`, `name`, `iconColor` opcional, `iconCustomEmojiId`)
|
||||
- `createForumTopic` (`chatId`, `name`, opcional `iconColor`, `iconCustomEmojiId`)
|
||||
|
||||
Ações de mensagens de canal expõem aliases ergonômicos (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`).
|
||||
Ações de mensagem de canal expõem aliases ergonômicos (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`).
|
||||
|
||||
Controles de restrição:
|
||||
Controles de bloqueio:
|
||||
|
||||
- `channels.telegram.actions.sendMessage`
|
||||
- `channels.telegram.actions.deleteMessage`
|
||||
- `channels.telegram.actions.reactions`
|
||||
- `channels.telegram.actions.sticker` (padrão: desabilitado)
|
||||
- `channels.telegram.actions.sticker` (padrão: desativado)
|
||||
|
||||
Observação: `edit` e `topic-create` estão atualmente habilitados por padrão e não têm toggles `channels.telegram.actions.*` separados.
|
||||
Envios em runtime usam o snapshot ativo de configuração/segredos (inicialização/reload), portanto caminhos de ação não executam nova resolução ad hoc de SecretRef por envio.
|
||||
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.
|
||||
|
||||
Semântica de remoção de reação: [/tools/reactions](/pt-BR/tools/reactions)
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Tags de encadeamento de respostas">
|
||||
O Telegram oferece suporte a tags explícitas de encadeamento de respostas na saída gerada:
|
||||
<Accordion title="Tags de encadeamento de resposta">
|
||||
O Telegram oferece suporte a tags explícitas de encadeamento de resposta na saída gerada:
|
||||
|
||||
- `[[reply_to_current]]` responde à mensagem disparadora
|
||||
- `[[reply_to:<id>]]` responde a um ID de mensagem específico do Telegram
|
||||
- `[[reply_to_current]]` responde à mensagem acionadora
|
||||
- `[[reply_to:<id>]]` responde a um ID específico de mensagem do Telegram
|
||||
|
||||
`channels.telegram.replyToMode` controla o tratamento:
|
||||
|
||||
@ -506,9 +543,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `first`
|
||||
- `all`
|
||||
|
||||
Quando o encadeamento de respostas está habilitado e o texto ou 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 desde o início e recorrem a uma resposta simples se o Telegram rejeitar a citação.
|
||||
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.
|
||||
|
||||
Observação: `off` desabilita o encadeamento de respostas implícito. Tags explícitas `[[reply_to_*]]` ainda são respeitadas.
|
||||
Observação: `off` desativa o encadeamento implícito de resposta. Tags explícitas `[[reply_to_*]]` ainda são respeitadas.
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -516,8 +553,8 @@ 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 digitação miram a thread do tópico
|
||||
- caminho de configuração do tópico:
|
||||
- respostas e indicação de digitação miram a thread do tópico
|
||||
- caminho de configuração de tópico:
|
||||
`channels.telegram.groups.<chatId>.topics.<threadId>`
|
||||
|
||||
Caso especial do tópico geral (`threadId=1`):
|
||||
@ -525,8 +562,8 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- envios de mensagem omitem `message_thread_id` (o Telegram rejeita `sendMessage(...thread_id=1)`)
|
||||
- ações de digitação ainda incluem `message_thread_id`
|
||||
|
||||
Herança de tópico: entradas de tópico herdam configurações de grupo, a menos que sejam substituídas (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`).
|
||||
`agentId` é exclusivo do tópico e não herda dos padrões do grupo.
|
||||
Herança de tópico: entradas de tópico herdam configurações do grupo, a menos que sejam substituídas (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`).
|
||||
`agentId` é exclusivo do tópico e não herda os 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:
|
||||
|
||||
@ -550,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`
|
||||
|
||||
**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).
|
||||
**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).
|
||||
|
||||
**Spawn ACP vinculado a 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. Requer que `channels.telegram.threadBindings.spawnSessions` permaneça habilitado (padrão: `true`).
|
||||
**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`).
|
||||
|
||||
O contexto do template expõe `MessageThreadId` e `IsForum`. Chats de DM com `message_thread_id` mantêm roteamento de DM e metadados de resposta em sessões planas por padrão; eles só usam chaves de sessão com reconhecimento de thread quando configurados com `threadReplies: "inbound"`, `threadReplies: "always"`, `requireTopic: true` ou uma configuração de tópico correspondente. Use `channels.telegram.dm.threadReplies` de nível superior para o padrão da conta, ou `direct.<chatId>.threadReplies` para uma DM.
|
||||
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.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Áudio, vídeo e stickers">
|
||||
<Accordion title="Áudio, vídeo e figurinhas">
|
||||
### 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 envio como nota de voz
|
||||
- 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ção ainda usa a transcrição
|
||||
bruta, então mensagens de voz restritas por menção continuam funcionando.
|
||||
- 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.
|
||||
|
||||
Exemplo de ação de mensagem:
|
||||
|
||||
@ -583,7 +620,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
### Mensagens de vídeo
|
||||
|
||||
Telegram distingue arquivos de vídeo de notas de vídeo.
|
||||
O Telegram distingue arquivos de vídeo de notas de vídeo.
|
||||
|
||||
Exemplo de ação de mensagem:
|
||||
|
||||
@ -597,7 +634,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Notas de vídeo não oferecem suporte a legendas; o texto de mensagem fornecido é enviado separadamente.
|
||||
Notas de vídeo não aceitam legendas; o texto de mensagem fornecido é enviado separadamente.
|
||||
|
||||
### Figurinhas
|
||||
|
||||
@ -607,7 +644,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- TGS animado: ignorado
|
||||
- WEBM de vídeo: ignorado
|
||||
|
||||
Campos de contexto da figurinha:
|
||||
Campos de contexto de figurinha:
|
||||
|
||||
- `Sticker.emoji`
|
||||
- `Sticker.setName`
|
||||
@ -619,7 +656,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
- `~/.openclaw/telegram/sticker-cache.json`
|
||||
|
||||
As figurinhas são descritas uma vez (quando possível) e armazenadas em cache para reduzir chamadas repetidas de visão.
|
||||
Figurinhas são descritas uma vez (quando possível) e armazenadas em cache para reduzir chamadas de visão repetidas.
|
||||
|
||||
Habilitar ações de figurinha:
|
||||
|
||||
@ -635,7 +672,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Ação de enviar figurinha:
|
||||
Ação para enviar figurinha:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -660,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 payloads de mensagem).
|
||||
As reações do Telegram chegam como atualizações `message_reaction` (separadas dos conteúdos das mensagens).
|
||||
|
||||
Quando habilitado, o OpenClaw enfileira eventos do sistema como:
|
||||
Quando habilitado, o OpenClaw enfileira eventos de sistema como:
|
||||
|
||||
- `Telegram reaction added: 👍 by Alice (@alice) on msg 42`
|
||||
|
||||
@ -673,40 +710,40 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Observações:
|
||||
|
||||
- `own` significa reações do usuário apenas a mensagens enviadas pelo bot (melhor esforço via cache de mensagens enviadas).
|
||||
- `own` significa apenas reações de usuários a mensagens enviadas pelo bot (melhor esforço via cache de mensagens enviadas).
|
||||
- Eventos de reação ainda respeitam os controles de acesso do Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); remetentes não autorizados são descartados.
|
||||
- O Telegram não fornece IDs de thread em atualizações de reação.
|
||||
- grupos que não são fórum são roteados para a sessão de chat do grupo
|
||||
- grupos de fórum são roteados 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 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
|
||||
|
||||
`allowed_updates` para polling/webhook inclui `message_reaction` automaticamente.
|
||||
`allowed_updates` para sondagem/Webhook inclui `message_reaction` automaticamente.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Reações de confirmação">
|
||||
`ackReaction` envia um emoji de confirmação enquanto o OpenClaw está processando uma mensagem recebida.
|
||||
`ackReaction` envia um emoji de confirmação enquanto o OpenClaw processa uma mensagem recebida.
|
||||
|
||||
Ordem de resolução:
|
||||
|
||||
- `channels.telegram.accounts.<accountId>.ackReaction`
|
||||
- `channels.telegram.ackReaction`
|
||||
- `messages.ackReaction`
|
||||
- fallback de emoji da identidade do agente (`agents.list[].identity.emoji`, caso contrário "👀")
|
||||
- alternativa de 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 conta.
|
||||
- O Telegram espera emoji Unicode (por exemplo, "👀").
|
||||
- Use `""` para desabilitar a reação para um canal ou uma conta.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Gravações de configuração a partir de eventos e comandos do Telegram">
|
||||
<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`).
|
||||
|
||||
Gravações acionadas pelo Telegram incluem:
|
||||
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 comandos)
|
||||
- `/config set` e `/config unset` (requer habilitação de comando)
|
||||
|
||||
Desabilitar:
|
||||
|
||||
@ -722,39 +759,39 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Long polling vs webhook">
|
||||
O padrão é long polling. Para o modo webhook, defina `channels.telegram.webhookUrl` e `channels.telegram.webhookSecret`; opcionalmente `webhookPath`, `webhookHost`, `webhookPort` (padrões `/telegram-webhook`, `127.0.0.1`, `8787`).
|
||||
<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`).
|
||||
|
||||
O listener local se vincula a `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 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 modo webhook valida proteções de requisição, o token secreto do Telegram e o corpo JSON antes de retornar `200` ao Telegram.
|
||||
Em seguida, o OpenClaw processa a atualização de forma assíncrona pelas mesmas lanes 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.
|
||||
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.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Limites, repetição e alvos da CLI">
|
||||
- `channels.telegram.textChunkLimit` padrão é 4000.
|
||||
<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 do Telegram recebida e enviada.
|
||||
- `channels.telegram.mediaGroupFlushMs` (padrão 500) controla por quanto tempo álbuns/grupos de mídia do Telegram são armazenados em buffer antes de o OpenClaw despachá-los como uma única mensagem recebida. Aumente se as partes do álbum chegarem atrasadas; 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, aplica-se o padrão do grammY). Clientes de bot limitam valores configurados abaixo da proteção de 60 segundos para requisições de texto/typing de saída, para que o grammY não aborte a entrega de resposta visível antes que a proteção de transporte e o fallback do OpenClaw possam executar. Long polling ainda usa uma proteção de requisiçã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 reinicializações de polling-stall falso-positivas.
|
||||
- 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.
|
||||
- allowlists do Telegram controlam principalmente quem pode acionar o agente, não um limite completo de redação de contexto suplementar.
|
||||
- Controles de histórico de DM:
|
||||
- `channels.telegram.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:
|
||||
- `channels.telegram.dmHistoryLimit`
|
||||
- `channels.telegram.dms["<user_id>"].historyLimit`
|
||||
- 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 de entrada 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.
|
||||
- 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.
|
||||
|
||||
O alvo de envio da CLI pode ser ID numérico de chat ou nome de usuário:
|
||||
O destino de envio da CLI pode ser um ID numérico de chat ou um nome de usuário:
|
||||
|
||||
```bash
|
||||
openclaw message send --channel telegram --target 123456789 --message "hi"
|
||||
openclaw message send --channel telegram --target @name --message "hi"
|
||||
```
|
||||
|
||||
Polls do Telegram usam `openclaw message poll` e oferecem suporte a tópicos de fórum:
|
||||
Enquetes do Telegram usam `openclaw message poll` e aceitam tópicos de fórum:
|
||||
|
||||
```bash
|
||||
openclaw message poll --channel telegram --target 123456789 \
|
||||
@ -764,57 +801,57 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
--poll-duration-seconds 300 --poll-public
|
||||
```
|
||||
|
||||
Flags de poll exclusivas do Telegram:
|
||||
Opções de enquete exclusivas do Telegram:
|
||||
|
||||
- `--poll-duration-seconds` (5-600)
|
||||
- `--poll-anonymous`
|
||||
- `--poll-public`
|
||||
- `--thread-id` para tópicos de fórum (ou use um alvo `:topic:`)
|
||||
- `--thread-id` para tópicos de fórum (ou use um destino `:topic:`)
|
||||
|
||||
Envio pelo Telegram também oferece suporte a:
|
||||
O envio pelo Telegram também aceita:
|
||||
|
||||
- `--presentation` com blocos `buttons` para teclados inline quando `channels.telegram.capabilities.inlineButtons` permite
|
||||
- `--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
|
||||
- `--force-document` para enviar imagens e GIFs de saída como documentos em vez de uploads de foto comprimida ou mídia animada
|
||||
- `--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 polls
|
||||
- `channels.telegram.actions.poll=false` desabilita a criação de polls do Telegram enquanto mantém envios regulares habilitados
|
||||
- `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
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Aprovações de exec no Telegram">
|
||||
O Telegram oferece suporte a aprovações de exec em DMs de aprovadores e pode opcionalmente publicar prompts no chat ou tópico de origem. Aprovadores devem ser IDs numéricos de usuário do Telegram.
|
||||
<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.
|
||||
|
||||
Caminho de configuração:
|
||||
|
||||
- `channels.telegram.execApprovals.enabled` (habilita automaticamente quando pelo menos um aprovador é resolvível)
|
||||
- `channels.telegram.execApprovals.approvers` (faz fallback para IDs numéricos de proprietários de `commands.ownerAllowFrom`)
|
||||
- `channels.telegram.execApprovals.approvers` (recorre aos IDs numéricos dos proprietários em `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 exec. O primeiro pareamento de DM aprovado inicializa `commands.ownerAllowFrom` quando ainda não existe proprietário de comando, então a configuração de um único proprietário continua funcionando 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 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`.
|
||||
|
||||
A entrega no canal mostra o texto do comando no chat; habilite `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 exec expiram após 30 minutos por padrão.
|
||||
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.
|
||||
|
||||
Botões de aprovação inline também exigem que `channels.telegram.capabilities.inlineButtons` permita a superfície alvo (`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 exec.
|
||||
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.
|
||||
|
||||
Consulte [aprovações de exec](/pt-BR/tools/exec-approvals).
|
||||
Consulte [Aprovações de execução](/pt-BR/tools/exec-approvals).
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Controles de resposta de erro
|
||||
|
||||
Quando o agente encontra um erro de entrega ou provedor, o Telegram pode responder com o texto do erro ou suprimi-lo. Duas chaves de configuração controlam esse comportamento:
|
||||
Quando o agente encontra um erro de entrega ou 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 respostas de erro totalmente. |
|
||||
| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | Tempo mínimo entre respostas de erro para o mesmo chat. Evita spam de erro durante indisponibilidades. |
|
||||
| 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. |
|
||||
| `channels.telegram.errorCooldownMs` | número (ms) | `60000` | Tempo mínimo entre respostas de erro para o mesmo chat. Evita spam de erros durante indisponibilidades. |
|
||||
|
||||
Substituições por conta, por grupo e por tópico são aceitas (mesma herança que outras chaves de configuração do Telegram).
|
||||
Sobrescritas por conta, grupo e tópico são aceitas (mesma herança de outras chaves de configuração do Telegram).
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -839,52 +876,52 @@ Substituições por conta, por grupo e por tópico são aceitas (mesma herança
|
||||
|
||||
- Se `requireMention=false`, o modo de privacidade do Telegram deve permitir visibilidade total.
|
||||
- BotFather: `/setprivacy` -> Desabilitar
|
||||
- depois remova e adicione novamente o bot ao grupo
|
||||
- em seguida, remova + adicione o bot novamente 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 de grupo explícitos; o curinga `"*"` não pode ter associação verificada por probe.
|
||||
- `openclaw channels status --probe` pode verificar IDs numéricos explícitos de grupo; o curinga `"*"` não pode ter a associação verificada.
|
||||
- teste rápido de sessão: `/activation always`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Bot não vê nenhuma mensagem de grupo">
|
||||
<Accordion title="O bot não está vendo nenhuma mensagem de grupo">
|
||||
|
||||
- quando `channels.telegram.groups` existe, o grupo deve estar listado (ou incluir `"*"`)
|
||||
- verifique a associação do bot no grupo
|
||||
- revise logs: `openclaw logs --follow` para motivos de salto
|
||||
- verifique a associação do bot ao grupo
|
||||
- revise os logs: `openclaw logs --follow` para motivos de ignorar
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Comandos funcionam parcialmente ou não funcionam">
|
||||
<Accordion title="Os comandos funcionam parcialmente ou não funcionam">
|
||||
|
||||
- autorize sua identidade de remetente (pareamento e/ou `allowFrom` numérico)
|
||||
- a autorização de comando ainda se aplica mesmo quando a política de grupo é `open`
|
||||
- `setMyCommands failed` com `BOT_COMMANDS_TOO_MUCH` significa que o menu nativo tem entradas demais; reduza comandos de Plugin/Skills/personalizados ou desabilite menus nativos
|
||||
- chamadas de inicialização `deleteMyCommands` / `setMyCommands` e chamadas de typing `sendChatAction` são limitadas e repetem uma vez pelo fallback de transporte do Telegram em caso de timeout de requisição. Erros persistentes de rede/fetch geralmente indicam problemas de alcançabilidade DNS/HTTPS para `api.telegram.org`
|
||||
- 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`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Inicialização relata token não autorizado">
|
||||
<Accordion title="A 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 do bot no BotFather e 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á-lo como "nenhum Webhook existe" apenas adiaria a mesma falha de token inválido para chamadas de API posteriores.
|
||||
- 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.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Instabilidade de polling ou rede">
|
||||
|
||||
- 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` para IPv6 primeiro; egresso IPv6 com problemas pode causar falhas intermitentes da API do Telegram.
|
||||
- Se os logs incluírem `TypeError: fetch failed` ou `Network request for 'getUpdates' failed!`, o OpenClaw agora tenta novamente esses casos como erros de rede recuperáveis.
|
||||
- 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.
|
||||
- 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; os clientes de bot limitam valores configurados abaixo das proteções de solicitação de saída e `getUpdates`, mas versões mais 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 tolerância da inicialização, quando uma conta de Webhook em execução não concluiu `setWebhook` após o período de tolerância 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 indicam problemas de proxy, DNS, IPv6 ou egresso TLS entre o host e `api.telegram.org`.
|
||||
- O Telegram também respeita variáveis de ambiente de proxy do processo para o transporte da Bot API, incluindo `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` e suas variantes em minúsculas. `NO_PROXY` / `no_proxy` ainda podem ignorar `api.telegram.org`.
|
||||
- Se o proxy gerenciado do OpenClaw estiver configurado por meio de `OPENCLAW_PROXY_URL` para um ambiente de serviço e nenhuma variável de ambiente de proxy padrão estiver presente, o Telegram também usa essa URL para o transporte da Bot API.
|
||||
- Em hosts VPS com egresso direto/TLS instável, roteie chamadas da API do Telegram por `channels.telegram.proxy`:
|
||||
- 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`:
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
@ -892,8 +929,8 @@ channels:
|
||||
proxy: socks5://<user>:<password>@proxy-host:1080
|
||||
```
|
||||
|
||||
- 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 o seu host for WSL2 ou funcionar explicitamente melhor com comportamento somente IPv4, force a seleção de família:
|
||||
- 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`.
|
||||
- Se seu host for WSL2 ou funcionar explicitamente melhor com comportamento somente IPv4, force a seleção de família:
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
@ -903,8 +940,8 @@ channels:
|
||||
```
|
||||
|
||||
- Respostas de intervalo de benchmark RFC 2544 (`198.18.0.0/15`) já são permitidas
|
||||
por padrão para downloads de mídia do Telegram. Se um proxy fake-IP ou
|
||||
transparente confiável reescrever `api.telegram.org` para algum outro
|
||||
para downloads de mídia do Telegram por padrão. Se um fake-IP confiável ou
|
||||
proxy transparente reescrever `api.telegram.org` para algum outro
|
||||
endereço privado/interno/de uso especial durante downloads de mídia, você pode optar
|
||||
pelo bypass exclusivo do Telegram:
|
||||
|
||||
@ -917,19 +954,19 @@ channels:
|
||||
|
||||
- A mesma opção está disponível por conta em
|
||||
`channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork`.
|
||||
- Se o seu proxy resolver hosts de mídia do Telegram para `198.18.x.x`, deixe a
|
||||
- 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 isso somente em ambientes de proxy confiáveis
|
||||
controlados pelo operador, como roteamento fake-IP de 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 ao Telegram pela internet pública.
|
||||
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.
|
||||
</Warning>
|
||||
|
||||
- Sobrescritas de ambiente (temporárias):
|
||||
- Substituições de ambiente (temporárias):
|
||||
- `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1`
|
||||
- `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1`
|
||||
- `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first`
|
||||
@ -953,9 +990,9 @@ Referência principal: [Referência de configuração - Telegram](/pt-BR/gateway
|
||||
|
||||
- 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 execução: `execApprovals`, `accounts.*.execApprovals`
|
||||
- aprovações de exec: `execApprovals`, `accounts.*.execApprovals`
|
||||
- comando/menu: `commands.native`, `commands.nativeSkills`, `customCommands`
|
||||
- encadeamento/respostas: `replyToMode`, `dm.threadReplies`, `direct.*.threadReplies`
|
||||
- threads/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`
|
||||
@ -969,7 +1006,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 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.*`.
|
||||
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.*`.
|
||||
</Note>
|
||||
|
||||
## Relacionados
|
||||
@ -981,11 +1018,11 @@ Precedência de várias contas: quando dois ou mais IDs de conta estiverem confi
|
||||
<Card title="Grupos" icon="users" href="/pt-BR/channels/groups">
|
||||
Comportamento de lista de permissões de grupos e tópicos.
|
||||
</Card>
|
||||
<Card title="Roteamento de canal" icon="route" href="/pt-BR/channels/channel-routing">
|
||||
<Card title="Roteamento de canais" icon="route" href="/pt-BR/channels/channel-routing">
|
||||
Roteie mensagens recebidas para agentes.
|
||||
</Card>
|
||||
<Card title="Segurança" icon="shield" href="/pt-BR/gateway/security">
|
||||
Modelo de ameaças e hardening.
|
||||
Modelo de ameaças e fortalecimento.
|
||||
</Card>
|
||||
<Card title="Roteamento multiagente" icon="sitemap" href="/pt-BR/concepts/multi-agent">
|
||||
Mapeie grupos e tópicos para agentes.
|
||||
|
||||
@ -1,13 +1,13 @@
|
||||
---
|
||||
read_when:
|
||||
- Você quer listar sessões armazenadas e ver a atividade recente
|
||||
- Você quer listar as sessões armazenadas e ver a atividade recente
|
||||
summary: Referência da CLI para `openclaw sessions` (listar sessões armazenadas + uso)
|
||||
title: Sessões
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T20:44:05Z"
|
||||
generated_at: "2026-05-04T07:02:44Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 5c9ec3ca55f7c5b6217b481e9da62f5416df73e69405a0dc15e77d2afeac723f
|
||||
source_hash: 8dc90344f40c53513bd6db3696bc709279155f26e7c3b6ea27e81a07a2f9f15e
|
||||
source_path: cli/sessions.md
|
||||
workflow: 16
|
||||
---
|
||||
@ -18,6 +18,8 @@ Liste sessões de conversa armazenadas.
|
||||
|
||||
Listas de sessões não são verificações de disponibilidade de canal/provedor. Elas mostram linhas de conversa persistidas dos armazenamentos de sessões. Um Discord, Slack, Telegram ou outro canal silencioso pode se reconectar com sucesso sem criar uma nova linha de sessão até que uma mensagem seja processada. Use `openclaw channels status --probe`, `openclaw status --deep` ou `openclaw health --verbose` quando precisar de conectividade de canal ao vivo.
|
||||
|
||||
As respostas `sessions.list` do Gateway são limitadas por padrão para que armazenamentos grandes e de longa duração não monopolizem o loop de eventos do Gateway. Passe um `limit` positivo explícito de clientes RPC quando uma janela de resultados diferente for necessária; as respostas incluem `totalCount`, `limitApplied` e `hasMore` quando os chamadores precisam mostrar que existem mais linhas.
|
||||
|
||||
```bash
|
||||
openclaw sessions
|
||||
openclaw sessions --agent work
|
||||
@ -30,10 +32,10 @@ openclaw sessions --json
|
||||
Seleção de escopo:
|
||||
|
||||
- padrão: armazenamento do agente padrão configurado
|
||||
- `--verbose`: registro detalhado
|
||||
- `--verbose`: registro em log detalhado
|
||||
- `--agent <id>`: um armazenamento de agente configurado
|
||||
- `--all-agents`: agrega todos os armazenamentos de agentes configurados
|
||||
- `--store <path>`: caminho de armazenamento explícito (não pode ser combinado com `--agent` ou `--all-agents`)
|
||||
- `--store <path>`: caminho explícito do armazenamento (não pode ser combinado com `--agent` ou `--all-agents`)
|
||||
|
||||
Exporte um pacote de trajetória para uma sessão armazenada:
|
||||
|
||||
@ -42,9 +44,9 @@ openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:12
|
||||
openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --output bug-123 --json
|
||||
```
|
||||
|
||||
Este é o caminho de comando usado pelo comando de barra `/export-trajectory` depois que o proprietário aprova a solicitação de execução. O diretório de saída é sempre resolvido dentro de `.openclaw/trajectory-exports/` no espaço de trabalho selecionado.
|
||||
Este é o caminho de comando usado pelo comando de barra `/export-trajectory` depois que o proprietário aprova a solicitação de exec. O diretório de saída é sempre resolvido dentro de `.openclaw/trajectory-exports/` no workspace selecionado.
|
||||
|
||||
`openclaw sessions --all-agents` lê armazenamentos de agentes configurados. A descoberta de sessões do Gateway e do ACP é mais ampla: ela também inclui armazenamentos somente em disco encontrados sob a raiz padrão `agents/` ou uma raiz `session.store` baseada em modelo. Esses armazenamentos descobertos devem resolver para arquivos `sessions.json` regulares dentro da raiz do agente; links simbólicos e caminhos fora da raiz são ignorados.
|
||||
`openclaw sessions --all-agents` lê armazenamentos de agentes configurados. A descoberta de sessões do Gateway e do ACP é mais ampla: ela também inclui armazenamentos somente em disco encontrados sob a raiz padrão `agents/` ou uma raiz `session.store` com modelo. Esses armazenamentos descobertos devem resolver para arquivos `sessions.json` regulares dentro da raiz do agente; symlinks e caminhos fora da raiz são ignorados.
|
||||
|
||||
Exemplos JSON:
|
||||
|
||||
@ -69,7 +71,7 @@ Exemplos JSON:
|
||||
|
||||
## Manutenção de limpeza
|
||||
|
||||
Execute a manutenção agora (em vez de aguardar o próximo ciclo de gravação):
|
||||
Execute a manutenção agora (em vez de esperar pelo próximo ciclo de gravação):
|
||||
|
||||
```bash
|
||||
openclaw sessions cleanup --dry-run
|
||||
@ -80,21 +82,21 @@ openclaw sessions cleanup --enforce --active-key "agent:main:telegram:direct:123
|
||||
openclaw sessions cleanup --json
|
||||
```
|
||||
|
||||
`openclaw sessions cleanup` usa as configurações de `session.maintenance` da configuração:
|
||||
`openclaw sessions cleanup` usa as configurações `session.maintenance` da configuração:
|
||||
|
||||
- Observação de escopo: `openclaw sessions cleanup` mantém armazenamentos de sessões, transcrições e arquivos auxiliares de trajetória. Ele não limpa logs de execução de cron (`cron/runs/<jobId>.jsonl`), que são gerenciados por `cron.runLog.maxBytes` e `cron.runLog.keepLines` em [Configuração de Cron](/pt-BR/automation/cron-jobs#configuration) e explicados em [Manutenção de Cron](/pt-BR/automation/cron-jobs#maintenance).
|
||||
- Observação de escopo: `openclaw sessions cleanup` faz manutenção de armazenamentos de sessões, transcrições e sidecars de trajetória. Ele não remove logs de execução de Cron (`cron/runs/<jobId>.jsonl`), que são gerenciados por `cron.runLog.maxBytes` e `cron.runLog.keepLines` em [configuração de Cron](/pt-BR/automation/cron-jobs#configuration) e explicados em [manutenção de Cron](/pt-BR/automation/cron-jobs#maintenance).
|
||||
|
||||
- `--dry-run`: pré-visualiza quantas entradas seriam removidas/limitadas sem gravar.
|
||||
- `--dry-run`: visualiza quantas entradas seriam removidas/limitadas sem gravar.
|
||||
- No modo de texto, dry-run imprime uma tabela de ações por sessão (`Action`, `Key`, `Age`, `Model`, `Flags`) para que você veja o que seria mantido ou removido.
|
||||
- `--enforce`: aplica a manutenção mesmo quando `session.maintenance.mode` é `warn`.
|
||||
- `--fix-missing`: remove entradas cujos arquivos de transcrição estão ausentes, mesmo que normalmente elas ainda não fossem removidas por idade/contagem.
|
||||
- `--active-key <key>`: protege uma chave ativa específica contra remoção por orçamento de disco. Ponteiros duráveis para conversas externas, como sessões em grupo e sessões de chat com escopo de thread, também são mantidos pela manutenção por idade/contagem/orçamento de disco.
|
||||
- `--enforce`: aplica manutenção mesmo quando `session.maintenance.mode` é `warn`.
|
||||
- `--fix-missing`: remove entradas cujos arquivos de transcrição estão ausentes, mesmo que elas normalmente ainda não fossem removidas por idade/contagem.
|
||||
- `--active-key <key>`: protege uma chave ativa específica da remoção por orçamento de disco. Ponteiros duráveis de conversas externas, como sessões de grupo e sessões de chat com escopo de thread, também são mantidos pela manutenção de idade/contagem/orçamento de disco.
|
||||
- `--agent <id>`: executa a limpeza para um armazenamento de agente configurado.
|
||||
- `--all-agents`: executa a limpeza para todos os armazenamentos de agentes configurados.
|
||||
- `--store <path>`: executa contra um arquivo `sessions.json` específico.
|
||||
- `--json`: imprime um resumo JSON. Com `--all-agents`, a saída inclui um resumo por armazenamento.
|
||||
|
||||
Quando um Gateway está acessível, a limpeza sem dry-run para armazenamentos de agentes configurados é enviada pelo Gateway para que ela compartilhe o mesmo gravador de armazenamento de sessões do tráfego em tempo de execução. Use `--store <path>` para o reparo offline explícito de um arquivo de armazenamento.
|
||||
Quando um Gateway está acessível, a limpeza sem dry-run para armazenamentos de agentes configurados é enviada pelo Gateway para que ela compartilhe o mesmo gravador de armazenamento de sessões que o tráfego de runtime. Use `--store <path>` para reparo offline explícito de um arquivo de armazenamento.
|
||||
|
||||
`openclaw sessions cleanup --all-agents --dry-run --json`:
|
||||
|
||||
|
||||
@ -6,15 +6,15 @@ read_when:
|
||||
summary: Fluxo de mensagens, sessões, enfileiramento e visibilidade do raciocínio
|
||||
title: Mensagens
|
||||
x-i18n:
|
||||
generated_at: "2026-04-30T16:27:50Z"
|
||||
generated_at: "2026-05-04T07:03:01Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: fdeee014d92767a725501691fbe0c4ee6b631acc9a2ab5cbbcf321bfee9679b9
|
||||
source_hash: 15242e21fd17a9f2013561003e108d197204d834caf51bbcdc53ffb3f118b14f
|
||||
source_path: concepts/messages.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
OpenClaw lida com mensagens recebidas por meio de um pipeline de resolução de sessão, enfileiramento, streaming, execução de ferramentas e visibilidade de raciocínio. Esta página mapeia o caminho da mensagem recebida até a resposta.
|
||||
OpenClaw lida com mensagens recebidas por meio de um pipeline de resolução de sessão, enfileiramento, streaming, execução de ferramentas e visibilidade do raciocínio. Esta página mapeia o caminho da mensagem recebida até a resposta.
|
||||
|
||||
## Fluxo de mensagens (alto nível)
|
||||
|
||||
@ -29,24 +29,24 @@ Inbound message
|
||||
Os principais controles ficam na configuração:
|
||||
|
||||
- `messages.*` para prefixos, enfileiramento e comportamento de grupos.
|
||||
- `agents.defaults.*` para padrões de streaming em blocos e fragmentação.
|
||||
- Sobrescritas de canal (`channels.whatsapp.*`, `channels.telegram.*` etc.) para limites e alternâncias de streaming.
|
||||
- `agents.defaults.*` para padrões de streaming em blocos e divisão em partes.
|
||||
- Substituições por canal (`channels.whatsapp.*`, `channels.telegram.*` etc.) para limites e alternâncias de streaming.
|
||||
|
||||
Consulte [Configuração](/pt-BR/gateway/configuration) para ver o esquema completo.
|
||||
Consulte [Configuração](/pt-BR/gateway/configuration) para o esquema completo.
|
||||
|
||||
## Deduplicação de recebimento
|
||||
## Desduplicação de recebimento
|
||||
|
||||
Canais podem reenviar a mesma mensagem após reconexões. O OpenClaw mantém um
|
||||
cache de curta duração indexado por canal/conta/par/sessão/id da mensagem para que entregas
|
||||
duplicadas não acionem outra execução do agente.
|
||||
Canais podem reenviar a mesma mensagem após reconexões. O OpenClaw mantém um cache
|
||||
de curta duração indexado por canal/conta/par/sessão/ID da mensagem para que entregas
|
||||
duplicadas não disparem outra execução do agente.
|
||||
|
||||
## Debounce de recebimento
|
||||
|
||||
Mensagens consecutivas rápidas do **mesmo remetente** podem ser agrupadas em um único
|
||||
turno do agente por meio de `messages.inbound`. O debounce tem escopo por canal + conversa
|
||||
e usa a mensagem mais recente para encadeamento/IDs de resposta.
|
||||
turno do agente via `messages.inbound`. O debounce é limitado por canal + conversa
|
||||
e usa a mensagem mais recente para encadeamento/IDs da resposta.
|
||||
|
||||
Configuração (padrão global + sobrescritas por canal):
|
||||
Configuração (padrão global + substituições por canal):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -65,69 +65,69 @@ Configuração (padrão global + sobrescritas por canal):
|
||||
|
||||
Observações:
|
||||
|
||||
- O debounce se aplica a mensagens **somente de texto**; mídia/anexos são liberados imediatamente.
|
||||
- Comandos de controle ignoram o debounce para permanecerem autônomos — **exceto** quando um canal opta explicitamente por coalescência de DM do mesmo remetente (por exemplo, [BlueBubbles `coalesceSameSenderDms`](/pt-BR/channels/bluebubbles#coalescing-split-send-dms-command--url-in-one-composition)), em que comandos de DM aguardam dentro da janela de debounce para que uma carga útil enviada em partes possa entrar no mesmo turno do agente.
|
||||
- O debounce se aplica a mensagens **somente de texto**; mídia/anexos são descarregados imediatamente.
|
||||
- Comandos de controle ignoram o debounce para permanecerem independentes — **exceto** quando um canal opta explicitamente pela coalescência de DMs do mesmo remetente (por exemplo, [BlueBubbles `coalesceSameSenderDms`](/pt-BR/channels/bluebubbles#coalescing-split-send-dms-command--url-in-one-composition)), em que comandos de DM aguardam dentro da janela de debounce para que uma carga enviada em partes possa entrar no mesmo turno do agente.
|
||||
|
||||
## Sessões e dispositivos
|
||||
|
||||
As sessões pertencem ao gateway, não aos clientes.
|
||||
As sessões pertencem ao Gateway, não aos clientes.
|
||||
|
||||
- Conversas diretas são consolidadas na chave de sessão principal do agente.
|
||||
- Conversas diretas convergem para a chave da sessão principal do agente.
|
||||
- Grupos/canais recebem suas próprias chaves de sessão.
|
||||
- O armazenamento de sessões e as transcrições ficam no host do Gateway.
|
||||
|
||||
Vários dispositivos/canais podem mapear para a mesma sessão, mas o histórico não é totalmente
|
||||
sincronizado de volta para todos os clientes. Recomendação: use um dispositivo principal para conversas
|
||||
longas a fim de evitar contexto divergente. A Control UI e a TUI sempre mostram a
|
||||
transcrição da sessão respaldada pelo Gateway, portanto são a fonte da verdade.
|
||||
longas a fim de evitar contexto divergente. A Interface de Controle e a TUI sempre mostram a
|
||||
transcrição da sessão mantida pelo Gateway, portanto elas são a fonte da verdade.
|
||||
|
||||
Detalhes: [Gerenciamento de sessões](/pt-BR/concepts/session).
|
||||
|
||||
## Metadados de resultado de ferramenta
|
||||
|
||||
`content` do resultado da ferramenta é o resultado visível para o modelo. `details` do resultado da ferramenta é
|
||||
metadado de runtime para renderização de UI, diagnósticos, entrega de mídia e plugins.
|
||||
O `content` do resultado da ferramenta é o resultado visível para o modelo. O `details` do resultado da ferramenta são
|
||||
metadados de runtime para renderização de UI, diagnósticos, entrega de mídia e plugins.
|
||||
|
||||
O OpenClaw mantém esse limite explícito:
|
||||
|
||||
- `toolResult.details` é removido antes de repetição pelo provedor e entrada de Compaction.
|
||||
- Transcrições de sessão persistidas mantêm apenas `details` limitados; metadados grandes demais
|
||||
são substituídos por um resumo compacto marcado como `persistedDetailsTruncated: true`.
|
||||
- Plugins e ferramentas devem colocar o texto que o modelo precisa ler em `content`, não apenas
|
||||
- `toolResult.details` é removido antes do replay do provedor e da entrada de Compaction.
|
||||
- Transcrições de sessão persistidas mantêm apenas `details` limitados; metadados
|
||||
grandes demais são substituídos por um resumo compacto marcado como `persistedDetailsTruncated: true`.
|
||||
- Plugins e ferramentas devem colocar texto que o modelo precisa ler em `content`, não apenas
|
||||
em `details`.
|
||||
|
||||
## Corpos recebidos e contexto de histórico
|
||||
|
||||
O OpenClaw separa o **corpo do prompt** do **corpo do comando**:
|
||||
|
||||
- `BodyForAgent`: texto primário voltado ao modelo para a mensagem atual. Plugins de canal
|
||||
devem mantê-lo focado no texto atual do remetente que contém o prompt.
|
||||
- `Body`: fallback legado de prompt. Ele pode incluir envelopes do canal e
|
||||
wrappers opcionais de histórico, mas canais atuais não devem depender dele como
|
||||
entrada primária do modelo quando `BodyForAgent` estiver disponível.
|
||||
- `BodyForAgent`: texto principal voltado ao modelo para a mensagem atual. Plugins de canal
|
||||
devem manter isto focado no texto atual do remetente que contém o prompt.
|
||||
- `Body`: fallback de prompt legado. Isto pode incluir envelopes de canal e
|
||||
wrappers opcionais de histórico, mas canais atuais não devem depender dele como a
|
||||
entrada principal do modelo quando `BodyForAgent` estiver disponível.
|
||||
- `CommandBody`: texto bruto do usuário para análise de diretivas/comandos.
|
||||
- `RawBody`: alias legado de `CommandBody` (mantido por compatibilidade).
|
||||
- `RawBody`: alias legado para `CommandBody` (mantido para compatibilidade).
|
||||
|
||||
Quando um canal fornece histórico, ele usa um wrapper compartilhado:
|
||||
|
||||
- `[Chat messages since your last reply - for context]`
|
||||
- `[Current message - respond to this]`
|
||||
- `[Mensagens de chat desde sua última resposta - para contexto]`
|
||||
- `[Mensagem atual - responda a isto]`
|
||||
|
||||
Para **conversas não diretas** (grupos/canais/salas), o **corpo da mensagem atual** recebe como prefixo o
|
||||
rótulo do remetente (o mesmo estilo usado para entradas de histórico). Isso mantém mensagens em tempo real e mensagens enfileiradas/de histórico
|
||||
Para **chats não diretos** (grupos/canais/salas), o **corpo da mensagem atual** recebe como prefixo o
|
||||
rótulo do remetente (mesmo estilo usado para entradas de histórico). Isso mantém mensagens em tempo real e enfileiradas/de histórico
|
||||
consistentes no prompt do agente.
|
||||
|
||||
Buffers de histórico são **somente pendentes**: incluem mensagens de grupo que _não_
|
||||
acionaram uma execução (por exemplo, mensagens controladas por menção) e **excluem** mensagens
|
||||
Buffers de histórico são **somente pendentes**: eles incluem mensagens de grupo que _não_
|
||||
dispararam uma execução (por exemplo, mensagens filtradas por menção) e **excluem** mensagens
|
||||
já presentes na transcrição da sessão.
|
||||
|
||||
A remoção de diretivas se aplica apenas à seção da **mensagem atual**, para que o histórico
|
||||
permaneça intacto. Canais que encapsulam histórico devem definir `CommandBody` (ou
|
||||
`RawBody`) como o texto original da mensagem e manter `Body` como o prompt combinado.
|
||||
Histórico estruturado, resposta, encaminhamento e metadados de canal são renderizados como
|
||||
blocos de contexto não confiável no papel de usuário durante a montagem do prompt.
|
||||
blocos de contexto não confiável com papel de usuário durante a montagem do prompt.
|
||||
Buffers de histórico são configuráveis via `messages.groupChat.historyLimit` (padrão
|
||||
global) e sobrescritas por canal como `channels.slack.historyLimit` ou
|
||||
global) e substituições por canal, como `channels.slack.historyLimit` ou
|
||||
`channels.telegram.accounts.<id>.historyLimit` (defina `0` para desativar).
|
||||
|
||||
## Enfileiramento e acompanhamentos
|
||||
@ -138,82 +138,82 @@ execução atual ou coletadas para um turno de acompanhamento.
|
||||
- Configure via `messages.queue` (e `messages.queue.byChannel`).
|
||||
- O modo padrão é `steer`, com um debounce de acompanhamento de 500 ms quando o direcionamento recai
|
||||
para entrega de acompanhamento enfileirada.
|
||||
- Modos: `steer`, `followup`, `collect`, `steer-backlog`, `interrupt` e o
|
||||
modo legado um-por-vez `queue`.
|
||||
- Modos: `steer`, `followup`, `collect`, `steer-backlog`, `interrupt` e o modo legado
|
||||
`queue`, de um por vez.
|
||||
|
||||
Detalhes: [Fila de comandos](/pt-BR/concepts/queue) e [Fila de direcionamento](/pt-BR/concepts/queue-steering).
|
||||
|
||||
## Propriedade da execução do canal
|
||||
## Propriedade de execução do canal
|
||||
|
||||
Plugins de canal podem preservar a ordenação, aplicar debounce à entrada e aplicar contrapressão
|
||||
de transporte antes que uma mensagem entre na fila da sessão. Eles não devem impor um
|
||||
Plugins de canal podem preservar ordenação, aplicar debounce à entrada e aplicar
|
||||
backpressure de transporte antes que uma mensagem entre na fila da sessão. Eles não devem impor um
|
||||
timeout separado em torno do próprio turno do agente. Depois que uma mensagem é roteada para uma
|
||||
sessão, trabalhos de longa duração são regidos pelo ciclo de vida da sessão, da ferramenta e do runtime,
|
||||
para que todos os canais relatem e se recuperem de turnos lentos de forma consistente.
|
||||
sessão, trabalhos de longa duração são governados pelo ciclo de vida da sessão, da ferramenta e do
|
||||
runtime para que todos os canais relatem e se recuperem de turnos lentos de forma consistente.
|
||||
|
||||
## Streaming, fragmentação e agrupamento
|
||||
## Streaming, divisão em partes e agrupamento
|
||||
|
||||
Streaming em blocos envia respostas parciais conforme o modelo produz blocos de texto.
|
||||
A fragmentação respeita os limites de texto do canal e evita dividir blocos de código cercados.
|
||||
O streaming em blocos envia respostas parciais conforme o modelo produz blocos de texto.
|
||||
A divisão em partes respeita limites de texto do canal e evita dividir código cercado.
|
||||
|
||||
Configurações principais:
|
||||
|
||||
- `agents.defaults.blockStreamingDefault` (`on|off`, padrão desativado)
|
||||
- `agents.defaults.blockStreamingDefault` (`on|off`, desativado por padrão)
|
||||
- `agents.defaults.blockStreamingBreak` (`text_end|message_end`)
|
||||
- `agents.defaults.blockStreamingChunk` (`minChars|maxChars|breakPreference`)
|
||||
- `agents.defaults.blockStreamingCoalesce` (agrupamento baseado em ociosidade)
|
||||
- `agents.defaults.humanDelay` (pausa semelhante à humana entre respostas em blocos)
|
||||
- Sobrescritas de canal: `*.blockStreaming` e `*.blockStreamingCoalesce` (canais que não sejam Telegram exigem `*.blockStreaming: true` explícito)
|
||||
- `agents.defaults.humanDelay` (pausa semelhante à humana entre respostas em bloco)
|
||||
- Substituições por canal: `*.blockStreaming` e `*.blockStreamingCoalesce` (canais não Telegram exigem `*.blockStreaming: true` explícito)
|
||||
|
||||
Detalhes: [Streaming + fragmentação](/pt-BR/concepts/streaming).
|
||||
Detalhes: [Streaming + divisão em partes](/pt-BR/concepts/streaming).
|
||||
|
||||
## Visibilidade de raciocínio e tokens
|
||||
## Visibilidade do raciocínio e tokens
|
||||
|
||||
O OpenClaw pode expor ou ocultar o raciocínio do modelo:
|
||||
|
||||
- `/reasoning on|off|stream` controla a visibilidade.
|
||||
- O conteúdo de raciocínio ainda conta para o uso de tokens quando produzido pelo modelo.
|
||||
- O Telegram oferece suporte a streaming de raciocínio no balão de rascunho.
|
||||
- O Telegram oferece suporte a streaming de raciocínio em um balão de rascunho transitório que é excluído após a entrega final; use `/reasoning on` para saída de raciocínio persistente.
|
||||
|
||||
Detalhes: [Diretivas de pensamento + raciocínio](/pt-BR/tools/thinking) e [Uso de tokens](/pt-BR/reference/token-use).
|
||||
|
||||
## Prefixos, encadeamento e respostas
|
||||
|
||||
A formatação de mensagens de saída é centralizada em `messages`:
|
||||
A formatação de mensagens enviadas é centralizada em `messages`:
|
||||
|
||||
- `messages.responsePrefix`, `channels.<channel>.responsePrefix` e `channels.<channel>.accounts.<id>.responsePrefix` (cascata de prefixo de saída), além de `channels.whatsapp.messagePrefix` (prefixo de entrada do WhatsApp)
|
||||
- `messages.responsePrefix`, `channels.<channel>.responsePrefix` e `channels.<channel>.accounts.<id>.responsePrefix` (cascata de prefixo de saída), mais `channels.whatsapp.messagePrefix` (prefixo de entrada do WhatsApp)
|
||||
- Encadeamento de respostas via `replyToMode` e padrões por canal
|
||||
|
||||
Detalhes: [Configuração](/pt-BR/gateway/config-agents#messages) e documentação dos canais.
|
||||
|
||||
## Respostas silenciosas
|
||||
|
||||
O token silencioso exato `NO_REPLY` / `no_reply` significa “não entregar uma resposta visível ao usuário”.
|
||||
O token silencioso exato `NO_REPLY` / `no_reply` significa “não entregue uma resposta visível ao usuário”.
|
||||
Quando um turno também tem mídia de ferramenta pendente, como áudio TTS gerado, o OpenClaw
|
||||
remove o texto silencioso, mas ainda entrega o anexo de mídia.
|
||||
O OpenClaw resolve esse comportamento por tipo de conversa:
|
||||
|
||||
- Conversas diretas não permitem silêncio por padrão e reescrevem uma resposta
|
||||
silenciosa pura para um fallback curto e visível.
|
||||
silenciosa isolada para um fallback curto visível.
|
||||
- Grupos/canais permitem silêncio por padrão.
|
||||
- Orquestração interna permite silêncio por padrão.
|
||||
|
||||
O OpenClaw também usa respostas silenciosas para falhas internas do executor que acontecem
|
||||
antes de qualquer resposta do assistente em conversas não diretas, para que grupos/canais não vejam
|
||||
texto boilerplate de erro do gateway. Conversas diretas mostram texto compacto de falha por padrão;
|
||||
detalhes brutos do executor são mostrados somente quando `/verbose` está `on` ou `full`.
|
||||
antes de qualquer resposta do assistente em chats não diretos, para que grupos/canais não vejam
|
||||
texto padrão de erro do Gateway. Conversas diretas mostram uma cópia compacta da falha por padrão;
|
||||
detalhes brutos do executor são mostrados apenas quando `/verbose` está `on` ou `full`.
|
||||
|
||||
Os padrões ficam em `agents.defaults.silentReply` e
|
||||
`agents.defaults.silentReplyRewrite`; `surfaces.<id>.silentReply` e
|
||||
`surfaces.<id>.silentReplyRewrite` podem sobrescrevê-los por superfície.
|
||||
`surfaces.<id>.silentReplyRewrite` podem substituí-los por superfície.
|
||||
|
||||
Quando a sessão pai tem uma ou mais execuções de subagente geradas pendentes, respostas
|
||||
silenciosas puras são descartadas em todas as superfícies em vez de serem reescritas, para que o
|
||||
Quando a sessão pai tem uma ou mais execuções pendentes de subagentes gerados, respostas
|
||||
silenciosas isoladas são descartadas em todas as superfícies em vez de serem reescritas, para que o
|
||||
pai permaneça quieto até que o evento de conclusão do filho entregue a resposta real.
|
||||
|
||||
## Relacionados
|
||||
|
||||
- [Streaming](/pt-BR/concepts/streaming) — entrega de mensagens em tempo real
|
||||
- [Tentativa novamente](/pt-BR/concepts/retry) — comportamento de nova tentativa de entrega de mensagens
|
||||
- [Nova tentativa](/pt-BR/concepts/retry) — comportamento de nova tentativa de entrega de mensagens
|
||||
- [Fila](/pt-BR/concepts/queue) — fila de processamento de mensagens
|
||||
- [Canais](/pt-BR/channels) — integrações com plataformas de mensagens
|
||||
|
||||
@ -1,15 +1,15 @@
|
||||
---
|
||||
read_when:
|
||||
- Explicando como a transmissão contínua ou a divisão em partes funciona nos canais
|
||||
- Alterando o comportamento de streaming de blocos ou fragmentação de canal
|
||||
- Depuração de respostas de bloco duplicadas/antecipadas ou do streaming de pré-visualização do canal
|
||||
summary: Comportamento de transmissão contínua + fragmentação (respostas em bloco, transmissão contínua de pré-visualização do canal, mapeamento de modos)
|
||||
title: Transmissão contínua e fragmentação
|
||||
- Explicando como a transmissão contínua ou a divisão em partes funcionam nos canais
|
||||
- Alterando o comportamento de streaming de blocos ou de fragmentação de canais
|
||||
- Depuração de respostas de bloco duplicadas/antecipadas ou do streaming de prévia do canal
|
||||
summary: Comportamento de transmissão + fragmentação (respostas em bloco, transmissão da prévia do canal, mapeamento de modos)
|
||||
title: Transmissão em fluxo e fragmentação
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T21:30:57Z"
|
||||
generated_at: "2026-05-04T07:03:07Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 1335f4f5532060bd8bf839683a2b1fbab38f38887c5583135652b4753e0f6a50
|
||||
source_hash: ff7b6cd8127255352fe16fb746469e9828e7d5aea183d3799ab10cc768515bd1
|
||||
source_path: concepts/streaming.md
|
||||
workflow: 16
|
||||
---
|
||||
@ -17,13 +17,13 @@ x-i18n:
|
||||
OpenClaw tem duas camadas de streaming separadas:
|
||||
|
||||
- **Streaming de blocos (canais):** emite **blocos** concluídos enquanto o assistente escreve. Essas são mensagens normais de canal (não deltas de tokens).
|
||||
- **Streaming de pré-visualização (Telegram/Discord/Slack):** atualiza uma **mensagem de pré-visualização** temporária durante a geração.
|
||||
- **Streaming de prévia (Telegram/Discord/Slack):** atualiza uma **mensagem de prévia** temporária durante a geração.
|
||||
|
||||
Atualmente, **não há streaming real de deltas de tokens** para mensagens de canal. O streaming de pré-visualização é baseado em mensagens (envio + edições/anexos).
|
||||
Atualmente, **não há streaming real de delta de tokens** para mensagens de canal. O streaming de prévia é baseado em mensagens (envio + edições/acréscimos).
|
||||
|
||||
## Streaming de blocos (mensagens de canal)
|
||||
|
||||
O streaming de blocos envia a saída do assistente em partes maiores conforme ela fica disponível.
|
||||
O streaming de blocos envia a saída do assistente em partes maiores à medida que ela fica disponível.
|
||||
|
||||
```
|
||||
Model output
|
||||
@ -38,173 +38,162 @@ Model output
|
||||
Legenda:
|
||||
|
||||
- `text_delta/events`: eventos de stream do modelo (podem ser esparsos para modelos sem streaming).
|
||||
- `chunker`: `EmbeddedBlockChunker` aplicando limites mínimo/máximo + preferência de quebra.
|
||||
- `channel send`: mensagens de saída reais (respostas em blocos).
|
||||
- `chunker`: `EmbeddedBlockChunker` aplicando limites mínimos/máximos + preferência de quebra.
|
||||
- `channel send`: mensagens de saída reais (respostas em bloco).
|
||||
|
||||
**Controles:**
|
||||
|
||||
- `agents.defaults.blockStreamingDefault`: `"on"`/`"off"` (desativado por padrão).
|
||||
- Substituições de canal: `*.blockStreaming` (e variantes por conta) para forçar `"on"`/`"off"` por canal.
|
||||
- Sobrescritas de canal: `*.blockStreaming` (e variantes por conta) para forçar `"on"`/`"off"` por canal.
|
||||
- `agents.defaults.blockStreamingBreak`: `"text_end"` ou `"message_end"`.
|
||||
- `agents.defaults.blockStreamingChunk`: `{ minChars, maxChars, breakPreference? }`.
|
||||
- `agents.defaults.blockStreamingCoalesce`: `{ minChars?, maxChars?, idleMs? }` (mescla blocos transmitidos antes do envio).
|
||||
- Limite rígido do canal: `*.textChunkLimit` (por exemplo, `channels.whatsapp.textChunkLimit`).
|
||||
- Modo de divisão do canal: `*.chunkMode` (`length` padrão, `newline` divide em linhas em branco (limites de parágrafo) antes da divisão por tamanho).
|
||||
- Limite flexível do Discord: `channels.discord.maxLinesPerMessage` (padrão 17) divide respostas altas para evitar cortes na UI.
|
||||
- Modo de divisão do canal: `*.chunkMode` (`length` é o padrão, `newline` divide em linhas em branco (limites de parágrafo) antes da divisão por tamanho).
|
||||
- Limite flexível do Discord: `channels.discord.maxLinesPerMessage` (padrão 17) divide respostas altas para evitar corte na UI.
|
||||
|
||||
**Semântica de limites:**
|
||||
**Semântica de limite:**
|
||||
|
||||
- `text_end`: transmite blocos assim que o chunker emite; descarrega a cada `text_end`.
|
||||
- `message_end`: espera a mensagem do assistente terminar e então descarrega a saída em buffer.
|
||||
- `text_end`: transmite blocos assim que o divisor emite; descarrega em cada `text_end`.
|
||||
- `message_end`: aguarda até que a mensagem do assistente termine e então descarrega a saída em buffer.
|
||||
|
||||
`message_end` ainda usa o chunker se o texto em buffer exceder `maxChars`, portanto pode emitir vários blocos no final.
|
||||
`message_end` ainda usa o divisor se o texto em buffer exceder `maxChars`, então ele pode emitir várias partes ao final.
|
||||
|
||||
### Entrega de mídia com streaming de blocos
|
||||
|
||||
Diretivas `MEDIA:` são metadados normais de entrega. Quando o streaming de blocos envia um bloco de mídia antecipadamente, o OpenClaw se lembra dessa entrega no turno. Se a carga final do assistente repetir a mesma URL de mídia, a entrega final remove a mídia duplicada em vez de enviar o anexo novamente.
|
||||
Diretivas `MEDIA:` são metadados normais de entrega. Quando o streaming de blocos envia um bloco de mídia antecipadamente, o OpenClaw lembra dessa entrega para o turno. Se a carga final do assistente repetir a mesma URL de mídia, a entrega final remove a mídia duplicada em vez de enviar o anexo novamente.
|
||||
|
||||
Cargas finais exatamente duplicadas são suprimidas. Se a carga final adicionar texto distinto ao redor de mídia que já foi transmitida, o OpenClaw ainda envia o novo texto mantendo a mídia com entrega única. Isso evita notas de voz ou arquivos duplicados em canais como Telegram quando um agente emite `MEDIA:` durante o streaming e o provedor também a inclui na resposta concluída.
|
||||
Cargas finais exatamente duplicadas são suprimidas. Se a carga final adicionar texto distinto ao redor de mídia que já foi transmitida, o OpenClaw ainda envia o novo texto mantendo a mídia com entrega única. Isso evita notas de voz ou arquivos duplicados em canais como Telegram quando um agente emite `MEDIA:` durante o streaming e o provedor também o inclui na resposta concluída.
|
||||
|
||||
## Algoritmo de divisão (limites baixo/alto)
|
||||
|
||||
A divisão de blocos é implementada por `EmbeddedBlockChunker`:
|
||||
A divisão em blocos é implementada por `EmbeddedBlockChunker`:
|
||||
|
||||
- **Limite baixo:** não emite até o buffer >= `minChars` (a menos que seja forçado).
|
||||
- **Limite baixo:** não emite até que o buffer >= `minChars` (a menos que seja forçado).
|
||||
- **Limite alto:** prefere divisões antes de `maxChars`; se forçado, divide em `maxChars`.
|
||||
- **Preferência de quebra:** `paragraph` → `newline` → `sentence` → `whitespace` → quebra rígida.
|
||||
- **Cercas de código:** nunca divide dentro de cercas; quando forçado em `maxChars`, fecha + reabre a cerca para manter o Markdown válido.
|
||||
- **Blocos de código:** nunca divide dentro de blocos; quando forçado em `maxChars`, fecha + reabre o bloco para manter o Markdown válido.
|
||||
|
||||
`maxChars` é limitado ao `textChunkLimit` do canal, então você não pode exceder os limites por canal.
|
||||
`maxChars` é limitado ao `textChunkLimit` do canal, então você não consegue exceder os limites por canal.
|
||||
|
||||
## Coalescência (mesclar blocos transmitidos)
|
||||
|
||||
Quando o streaming de blocos está ativado, o OpenClaw pode **mesclar blocos consecutivos**
|
||||
antes de enviá-los. Isso reduz “spam de linha única” enquanto ainda fornece
|
||||
saída progressiva.
|
||||
Quando o streaming de blocos está ativado, o OpenClaw pode **mesclar partes de blocos consecutivas** antes de enviá-las. Isso reduz “spam de uma linha” enquanto ainda fornece saída progressiva.
|
||||
|
||||
- A coalescência espera **intervalos ociosos** (`idleMs`) antes de descarregar.
|
||||
- Buffers são limitados por `maxChars` e serão descarregados se excederem esse valor.
|
||||
- `minChars` impede que fragmentos minúsculos sejam enviados até que texto suficiente se acumule
|
||||
(a descarga final sempre envia o texto restante).
|
||||
- O juntador é derivado de `blockStreamingChunk.breakPreference`
|
||||
(`paragraph` → `\n\n`, `newline` → `\n`, `sentence` → espaço).
|
||||
- Substituições de canal estão disponíveis via `*.blockStreamingCoalesce` (incluindo configurações por conta).
|
||||
- O `minChars` padrão de coalescência é aumentado para 1500 para Signal/Slack/Discord, a menos que seja substituído.
|
||||
- A coalescência aguarda **intervalos ociosos** (`idleMs`) antes de descarregar.
|
||||
- Buffers são limitados por `maxChars` e serão descarregados se o excederem.
|
||||
- `minChars` impede o envio de fragmentos pequenos até que texto suficiente se acumule (o descarregamento final sempre envia o texto restante).
|
||||
- O conector é derivado de `blockStreamingChunk.breakPreference` (`paragraph` → `\n\n`, `newline` → `\n`, `sentence` → espaço).
|
||||
- Sobrescritas de canal estão disponíveis via `*.blockStreamingCoalesce` (incluindo configurações por conta).
|
||||
- O `minChars` padrão da coalescência é aumentado para 1500 para Signal/Slack/Discord, a menos que seja sobrescrito.
|
||||
|
||||
## Ritmo semelhante ao humano entre blocos
|
||||
|
||||
Quando o streaming de blocos está ativado, você pode adicionar uma **pausa aleatória** entre
|
||||
respostas em blocos (após o primeiro bloco). Isso faz respostas com várias bolhas parecerem
|
||||
mais naturais.
|
||||
Quando o streaming de blocos está ativado, você pode adicionar uma **pausa aleatória** entre respostas em bloco (após o primeiro bloco). Isso faz respostas em múltiplos balões parecerem mais naturais.
|
||||
|
||||
- Configuração: `agents.defaults.humanDelay` (substitua por agente via `agents.list[].humanDelay`).
|
||||
- Configuração: `agents.defaults.humanDelay` (sobrescreva por agente via `agents.list[].humanDelay`).
|
||||
- Modos: `off` (padrão), `natural` (800–2500ms), `custom` (`minMs`/`maxMs`).
|
||||
- Aplica-se apenas a **respostas em blocos**, não a respostas finais ou resumos de ferramentas.
|
||||
- Aplica-se apenas a **respostas em bloco**, não a respostas finais ou resumos de ferramentas.
|
||||
|
||||
## "Transmitir partes ou tudo"
|
||||
|
||||
Isso corresponde a:
|
||||
|
||||
- **Transmitir partes:** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"` (emite conforme avança). Canais que não sejam Telegram também precisam de `*.blockStreaming: true`.
|
||||
- **Transmitir tudo no final:** `blockStreamingBreak: "message_end"` (descarrega uma vez, possivelmente em vários blocos se for muito longo).
|
||||
- **Transmitir tudo ao final:** `blockStreamingBreak: "message_end"` (descarrega uma vez, possivelmente em várias partes se for muito longo).
|
||||
- **Sem streaming de blocos:** `blockStreamingDefault: "off"` (apenas resposta final).
|
||||
|
||||
**Observação sobre canais:** O streaming de blocos fica **desativado a menos que**
|
||||
`*.blockStreaming` seja definido explicitamente como `true`. Os canais podem transmitir uma pré-visualização ao vivo
|
||||
(`channels.<channel>.streaming`) sem respostas em blocos.
|
||||
**Observação de canal:** O streaming de blocos fica **desativado a menos que**
|
||||
`*.blockStreaming` esteja explicitamente definido como `true`. Canais podem transmitir uma prévia ao vivo
|
||||
(`channels.<channel>.streaming`) sem respostas em bloco.
|
||||
|
||||
Lembrete de localização da configuração: os padrões `blockStreaming*` ficam em
|
||||
`agents.defaults`, não na configuração raiz.
|
||||
|
||||
## Modos de streaming de pré-visualização
|
||||
## Modos de streaming de prévia
|
||||
|
||||
Chave canônica: `channels.<channel>.streaming`
|
||||
|
||||
Modos:
|
||||
|
||||
- `off`: desativa o streaming de pré-visualização.
|
||||
- `partial`: pré-visualização única que é substituída pelo texto mais recente.
|
||||
- `block`: pré-visualização atualizada em etapas divididas/anexadas.
|
||||
- `progress`: pré-visualização de progresso/status durante a geração, resposta final ao concluir.
|
||||
- `off`: desativa o streaming de prévia.
|
||||
- `partial`: prévia única que é substituída pelo texto mais recente.
|
||||
- `block`: atualizações de prévia em etapas divididas/acrescentadas.
|
||||
- `progress`: prévia de progresso/status durante a geração, resposta final ao concluir.
|
||||
|
||||
`streaming.mode: "block"` é um modo de streaming de pré-visualização para canais com suporte a edição
|
||||
como Discord e Telegram. Ele não habilita a entrega de blocos de canal ali.
|
||||
Use `streaming.block.enabled` ou a chave legada de canal `blockStreaming` quando
|
||||
quiser respostas normais em blocos. Microsoft Teams é a exceção: ele não tem
|
||||
transporte de bloco de pré-visualização de rascunho, então `streaming.mode: "block"` é mapeado para entrega de blocos do Teams
|
||||
em vez de streaming parcial/progresso nativo.
|
||||
`streaming.mode: "block"` é um modo de streaming de prévia para canais com suporte a edição, como Discord e Telegram. Ele não habilita a entrega de blocos do canal nesses casos. Use `streaming.block.enabled` ou a chave de canal legada `blockStreaming` quando quiser respostas normais em bloco. Microsoft Teams é a exceção: ele não tem transporte de blocos de prévia de rascunho, então `streaming.mode: "block"` mapeia para a entrega de blocos do Teams em vez de streaming parcial/progresso nativo.
|
||||
|
||||
### Mapeamento de canais
|
||||
|
||||
| Canal | `off` | `partial` | `block` | `progress` |
|
||||
| ---------- | ----- | --------- | ------- | -------------------------- |
|
||||
| Canal | `off` | `partial` | `block` | `progress` |
|
||||
| ---------- | ----- | --------- | ------- | ----------------------- |
|
||||
| Telegram | ✅ | ✅ | ✅ | rascunho de progresso editável |
|
||||
| Discord | ✅ | ✅ | ✅ | rascunho de progresso editável |
|
||||
| Slack | ✅ | ✅ | ✅ | ✅ |
|
||||
| Mattermost | ✅ | ✅ | ✅ | ✅ |
|
||||
| MS Teams | ✅ | ✅ | ✅ | stream de progresso nativo |
|
||||
| Slack | ✅ | ✅ | ✅ | ✅ |
|
||||
| Mattermost | ✅ | ✅ | ✅ | ✅ |
|
||||
| MS Teams | ✅ | ✅ | ✅ | stream de progresso nativo |
|
||||
|
||||
Somente Slack:
|
||||
|
||||
- `channels.slack.streaming.nativeTransport` alterna chamadas à API de streaming nativa do Slack quando `channels.slack.streaming.mode="partial"` (padrão: `true`).
|
||||
- O streaming nativo do Slack e o status de thread de assistente do Slack exigem um destino de thread de resposta. DMs no nível superior não mostram essa pré-visualização em estilo de thread, mas ainda podem usar publicações e edições de pré-visualização de rascunho do Slack.
|
||||
- O streaming nativo do Slack e o status de thread do assistente do Slack exigem um destino de thread de resposta. DMs de nível superior não mostram essa prévia no estilo thread, mas ainda podem usar publicações e edições de prévia de rascunho do Slack.
|
||||
|
||||
Migração de chaves legadas:
|
||||
Migração de chave legada:
|
||||
|
||||
- Telegram: valores legados `streamMode` e valores escalares/booleanos de `streaming` são detectados e migrados pelos caminhos de compatibilidade de doctor/config para `streaming.mode`.
|
||||
- Discord: `streamMode` + `streaming` booleano migram automaticamente para o enum `streaming`.
|
||||
- Slack: `streamMode` migra automaticamente para `streaming.mode`; `streaming` booleano migra automaticamente para `streaming.mode` mais `streaming.nativeTransport`; `nativeStreaming` legado migra automaticamente para `streaming.nativeTransport`.
|
||||
- Telegram: valores legados de `streamMode` e valores escalares/booleanos de `streaming` são detectados e migrados pelos caminhos de compatibilidade de doctor/config para `streaming.mode`.
|
||||
- Discord: `streamMode` + booleano `streaming` migram automaticamente para o enum `streaming`.
|
||||
- Slack: `streamMode` migra automaticamente para `streaming.mode`; booleano `streaming` migra automaticamente para `streaming.mode` mais `streaming.nativeTransport`; `nativeStreaming` legado migra automaticamente para `streaming.nativeTransport`.
|
||||
|
||||
### Comportamento em tempo de execução
|
||||
### Comportamento em runtime
|
||||
|
||||
Telegram:
|
||||
|
||||
- Usa `sendMessage` + atualizações de pré-visualização `editMessageText` em DMs e grupos/tópicos.
|
||||
- Envia uma nova mensagem final em vez de editar no mesmo lugar quando uma pré-visualização ficou visível por cerca de um minuto, depois limpa a pré-visualização para que o carimbo de data/hora do Telegram reflita a conclusão da resposta.
|
||||
- O streaming de pré-visualização é ignorado quando o streaming de blocos do Telegram está explicitamente ativado (para evitar streaming duplo).
|
||||
- `/reasoning stream` pode escrever o raciocínio na pré-visualização.
|
||||
- Usa `sendMessage` + atualizações de prévia com `editMessageText` em DMs e grupos/tópicos.
|
||||
- Envia uma nova mensagem final em vez de editar no local quando uma prévia ficou visível por cerca de um minuto, então limpa a prévia para que o timestamp do Telegram reflita a conclusão da resposta.
|
||||
- O streaming de prévia é ignorado quando o streaming de blocos do Telegram está explicitamente habilitado (para evitar streaming duplo).
|
||||
- `/reasoning stream` pode escrever o raciocínio em uma prévia transitória que é excluída após a entrega final.
|
||||
|
||||
Discord:
|
||||
|
||||
- Usa envio + edição de mensagens de pré-visualização.
|
||||
- Usa mensagens de prévia com envio + edição.
|
||||
- O modo `block` usa divisão de rascunho (`draftChunk`).
|
||||
- O streaming de pré-visualização é ignorado quando o streaming de blocos do Discord está explicitamente ativado.
|
||||
- Mídia final, erro e cargas de resposta explícita cancelam pré-visualizações pendentes sem descarregar um novo rascunho e então usam a entrega normal.
|
||||
- O streaming de prévia é ignorado quando o streaming de blocos do Discord está explicitamente habilitado.
|
||||
- Mídia final, erro e cargas de resposta explícita cancelam prévias pendentes sem descarregar um novo rascunho, então usam a entrega normal.
|
||||
|
||||
Slack:
|
||||
|
||||
- `partial` pode usar streaming nativo do Slack (`chat.startStream`/`append`/`stop`) quando disponível.
|
||||
- `block` usa pré-visualizações de rascunho em estilo de anexo.
|
||||
- `progress` usa texto de pré-visualização de status e depois a resposta final.
|
||||
- DMs no nível superior sem uma thread de resposta usam publicações e edições de pré-visualização de rascunho em vez de streaming nativo do Slack.
|
||||
- Streaming de pré-visualização nativo e de rascunho suprime respostas em blocos para esse turno, então uma resposta do Slack é transmitida por apenas um caminho de entrega.
|
||||
- Cargas finais de mídia/erro e finais de progresso não criam mensagens de rascunho descartáveis; apenas finais de texto/bloco que podem editar a pré-visualização descarregam texto de rascunho pendente.
|
||||
- `partial` pode usar o streaming nativo do Slack (`chat.startStream`/`append`/`stop`) quando disponível.
|
||||
- `block` usa prévias de rascunho no estilo acréscimo.
|
||||
- `progress` usa texto de prévia de status, então a resposta final.
|
||||
- DMs de nível superior sem uma thread de resposta usam publicações e edições de prévia de rascunho em vez do streaming nativo do Slack.
|
||||
- O streaming de prévia nativo e de rascunho suprime respostas em bloco para esse turno, então uma resposta do Slack é transmitida por apenas um caminho de entrega.
|
||||
- Cargas finais de mídia/erro e finais de progresso não criam mensagens de rascunho descartáveis; apenas finais de texto/bloco que podem editar a prévia descarregam o texto de rascunho pendente.
|
||||
|
||||
Mattermost:
|
||||
|
||||
- Transmite pensamento, atividade de ferramentas e texto parcial de resposta em uma única publicação de pré-visualização de rascunho que finaliza no mesmo lugar quando a resposta final é segura para enviar.
|
||||
- Recai para o envio de uma nova publicação final se a publicação de pré-visualização foi excluída ou está indisponível no momento da finalização.
|
||||
- Cargas finais de mídia/erro cancelam atualizações de pré-visualização pendentes antes da entrega normal em vez de descarregar uma publicação temporária de pré-visualização.
|
||||
- Transmite pensamento, atividade de ferramentas e texto parcial de resposta em uma única publicação de prévia de rascunho que é finalizada no local quando a resposta final pode ser enviada com segurança.
|
||||
- Recorre ao envio de uma nova publicação final se a publicação de prévia tiver sido excluída ou estiver indisponível no momento da finalização.
|
||||
- Cargas finais de mídia/erro cancelam atualizações de prévia pendentes antes da entrega normal em vez de descarregar uma publicação de prévia temporária.
|
||||
|
||||
Matrix:
|
||||
|
||||
- Pré-visualizações de rascunho finalizam no mesmo lugar quando o texto final pode reutilizar o evento de pré-visualização.
|
||||
- Finais apenas com mídia, erro e incompatibilidade de destino de resposta cancelam atualizações de pré-visualização pendentes antes da entrega normal; uma pré-visualização obsoleta já visível é redigida.
|
||||
- Prévias de rascunho são finalizadas no local quando o texto final pode reutilizar o evento de prévia.
|
||||
- Finais somente com mídia, erro e incompatibilidade de destino de resposta cancelam atualizações de prévia pendentes antes da entrega normal; uma prévia obsoleta já visível é redigida.
|
||||
|
||||
### Atualizações de pré-visualização de progresso de ferramentas
|
||||
### Atualizações de prévia de progresso de ferramentas
|
||||
|
||||
O streaming de pré-visualização também pode incluir atualizações de **progresso de ferramentas** — linhas curtas de status como "pesquisando na web", "lendo arquivo" ou "chamando ferramenta" — que aparecem na mesma mensagem de pré-visualização enquanto as ferramentas estão em execução, antes da resposta final. Isso mantém turnos de ferramenta em várias etapas visualmente ativos em vez de silenciosos entre a primeira pré-visualização de pensamento e a resposta final.
|
||||
O streaming de prévia também pode incluir atualizações de **progresso de ferramentas** — linhas curtas de status como "pesquisando na web", "lendo arquivo" ou "chamando ferramenta" — que aparecem na mesma mensagem de prévia enquanto as ferramentas estão em execução, antes da resposta final. Isso mantém turnos de ferramentas com várias etapas visualmente ativos em vez de silenciosos entre a primeira prévia de pensamento e a resposta final.
|
||||
|
||||
Superfícies compatíveis:
|
||||
|
||||
- **Discord**, **Slack**, **Telegram** e **Matrix** transmitem progresso de ferramentas para a edição de pré-visualização ao vivo por padrão quando o streaming de pré-visualização está ativo. Microsoft Teams usa seu stream de progresso nativo em conversas pessoais.
|
||||
- Telegram foi lançado com atualizações de pré-visualização de progresso de ferramentas ativadas desde `v2026.4.22`; mantê-las ativadas preserva esse comportamento lançado.
|
||||
- **Mattermost** já incorpora atividade de ferramentas em sua única publicação de pré-visualização de rascunho (veja acima).
|
||||
- Edições de progresso de ferramentas seguem o modo ativo de streaming de pré-visualização; elas são ignoradas quando o streaming de pré-visualização está `off` ou quando o streaming de blocos assumiu a mensagem. No Telegram, `streaming.mode: "off"` é somente final: conversas genéricas de progresso também são suprimidas em vez de serem entregues como mensagens de status independentes, enquanto solicitações de aprovação, cargas de mídia e erros ainda são roteados normalmente.
|
||||
- Para manter o streaming de pré-visualização mas ocultar linhas de progresso de ferramentas, defina `streaming.preview.toolProgress` como `false` para esse canal. Para desativar totalmente edições de pré-visualização, defina `streaming.mode` como `off`.
|
||||
- Respostas a citações selecionadas do Telegram são uma exceção: quando `replyToMode` não está `"off"` e há texto de citação selecionada, o OpenClaw ignora o stream de pré-visualização da resposta para esse turno, então linhas de pré-visualização de progresso de ferramentas não podem ser renderizadas. Respostas à mensagem atual sem texto de citação selecionada ainda mantêm o streaming de pré-visualização. Veja [documentação do canal Telegram](/pt-BR/channels/telegram) para detalhes.
|
||||
- **Discord**, **Slack**, **Telegram** e **Matrix** transmitem progresso de ferramentas na edição da prévia ao vivo por padrão quando o streaming de prévia está ativo. Microsoft Teams usa seu stream de progresso nativo em conversas pessoais.
|
||||
- Telegram foi lançado com atualizações de prévia de progresso de ferramentas habilitadas desde `v2026.4.22`; mantê-las habilitadas preserva esse comportamento lançado.
|
||||
- **Mattermost** já incorpora a atividade de ferramentas em sua única publicação de prévia de rascunho (veja acima).
|
||||
- Edições de progresso de ferramentas seguem o modo de streaming de prévia ativo; elas são ignoradas quando o streaming de prévia está `off` ou quando o streaming de blocos assumiu a mensagem. No Telegram, `streaming.mode: "off"` é apenas final: conversa genérica de progresso também é suprimida em vez de ser entregue como mensagens de status independentes, enquanto prompts de aprovação, cargas de mídia e erros ainda são roteados normalmente.
|
||||
- Para manter o streaming de prévia, mas ocultar linhas de progresso de ferramentas, defina `streaming.preview.toolProgress` como `false` para esse canal. Para manter linhas de progresso de ferramentas visíveis enquanto oculta texto de comando/execução, defina `streaming.preview.commandText` como `"status"` ou `streaming.progress.commandText` como `"status"`; o padrão é `"raw"` para preservar o comportamento lançado. Essa política é compartilhada por canais de rascunho/progresso que usam o renderizador de progresso compacto do OpenClaw, incluindo Discord, Matrix, Microsoft Teams, Mattermost, prévias de rascunho do Slack e Telegram. Para desativar edições de prévia completamente, defina `streaming.mode` como `off`.
|
||||
- Respostas a citações selecionadas no Telegram são uma exceção: quando `replyToMode` não é `"off"` e texto de citação selecionado está presente, o OpenClaw ignora o stream de prévia da resposta para esse turno, então linhas de prévia de progresso de ferramentas não podem ser renderizadas. Respostas à mensagem atual sem texto de citação selecionado ainda mantêm o streaming de prévia. Consulte a [documentação do canal Telegram](/pt-BR/channels/telegram) para detalhes.
|
||||
|
||||
Exemplo:
|
||||
Mantenha as linhas de progresso visíveis, mas oculte o texto bruto de comando/execução:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -213,7 +202,8 @@ Exemplo:
|
||||
"streaming": {
|
||||
"mode": "partial",
|
||||
"preview": {
|
||||
"toolProgress": false
|
||||
"toolProgress": true,
|
||||
"commandText": "status"
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -221,9 +211,27 @@ Exemplo:
|
||||
}
|
||||
```
|
||||
|
||||
## Relacionados
|
||||
Use a mesma forma sob outra chave compacta de canal de progresso, por exemplo `channels.discord`, `channels.matrix`, `channels.msteams`, `channels.mattermost` ou pré-visualizações de rascunhos do Slack. Para o modo de rascunho de progresso, coloque a mesma política sob `streaming.progress`:
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"telegram": {
|
||||
"streaming": {
|
||||
"mode": "progress",
|
||||
"progress": {
|
||||
"toolProgress": true,
|
||||
"commandText": "status"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Relacionado
|
||||
|
||||
- [Rascunhos de progresso](/pt-BR/concepts/progress-drafts) — mensagens visíveis de trabalho em andamento que são atualizadas durante turnos longos
|
||||
- [Mensagens](/pt-BR/concepts/messages) — ciclo de vida e entrega de mensagens
|
||||
- [Tentativa](/pt-BR/concepts/retry) — comportamento de nova tentativa em falha de entrega
|
||||
- [Nova tentativa](/pt-BR/concepts/retry) — comportamento de nova tentativa em caso de falha na entrega
|
||||
- [Canais](/pt-BR/channels) — suporte a streaming por canal
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@ -1,38 +1,38 @@
|
||||
---
|
||||
read_when:
|
||||
- Você quer usar text-to-speech do ElevenLabs no OpenClaw
|
||||
- Você quer usar speech-to-text Scribe do ElevenLabs para anexos de áudio
|
||||
- Você quer transcrição em tempo real do ElevenLabs para Voice Call
|
||||
summary: Use fala do ElevenLabs, STT Scribe e transcrição em tempo real com OpenClaw
|
||||
- Você quer usar a conversão de texto em fala da ElevenLabs no OpenClaw
|
||||
- Você quer a conversão de fala em texto do ElevenLabs Scribe para anexos de áudio
|
||||
- Você quer transcrição em tempo real do ElevenLabs para Chamada de voz ou Google Meet
|
||||
summary: Use a síntese de fala da ElevenLabs, o Scribe STT e a transcrição em tempo real com o OpenClaw
|
||||
title: ElevenLabs
|
||||
x-i18n:
|
||||
generated_at: "2026-04-25T13:54:19Z"
|
||||
model: gpt-5.4
|
||||
generated_at: "2026-05-04T07:03:31Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 1f858a344228c6355cd5fdc3775cddac39e0075f2e9fcf7683271f11be03a31a
|
||||
source_hash: 4c880bf9dcab01ef70779c74576c70ea5d0203b96b5f739291842fafcb4bdb4b
|
||||
source_path: providers/elevenlabs.md
|
||||
workflow: 15
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
O OpenClaw usa ElevenLabs para text-to-speech, speech-to-text em lote com Scribe
|
||||
v2 e STT de streaming do Voice Call com Scribe v2 Realtime.
|
||||
OpenClaw usa ElevenLabs para texto para fala, fala para texto em lote com Scribe
|
||||
v2 e STT por streaming com Scribe v2 Realtime.
|
||||
|
||||
| Capacidade | Superfície do OpenClaw | Padrão |
|
||||
| ----------------------- | --------------------------------------------- | ------------------------ |
|
||||
| Text-to-speech | `messages.tts` / `talk` | `eleven_multilingual_v2` |
|
||||
| Speech-to-text em lote | `tools.media.audio` | `scribe_v2` |
|
||||
| Speech-to-text em streaming | Voice Call `streaming.provider: "elevenlabs"` | `scribe_v2_realtime` |
|
||||
| Recurso | Superfície do OpenClaw | Padrão |
|
||||
| ------------------------ | -------------------------------------------------------------------- | ------------------------ |
|
||||
| Texto para fala | `messages.tts` / `talk` | `eleven_multilingual_v2` |
|
||||
| Fala para texto em lote | `tools.media.audio` | `scribe_v2` |
|
||||
| Fala para texto por streaming | streaming de chamada de voz ou Google Meet `realtime.transcriptionProvider` | `scribe_v2_realtime` |
|
||||
|
||||
## Autenticação
|
||||
|
||||
Defina `ELEVENLABS_API_KEY` no ambiente. `XI_API_KEY` também é aceito por
|
||||
compatibilidade com ferramentas existentes do ElevenLabs.
|
||||
Defina `ELEVENLABS_API_KEY` no ambiente. `XI_API_KEY` também é aceito para
|
||||
compatibilidade com ferramentas existentes da ElevenLabs.
|
||||
|
||||
```bash
|
||||
export ELEVENLABS_API_KEY="..."
|
||||
```
|
||||
|
||||
## Text-to-speech
|
||||
## Texto para fala
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -50,10 +50,10 @@ export ELEVENLABS_API_KEY="..."
|
||||
}
|
||||
```
|
||||
|
||||
Defina `modelId` como `eleven_v3` para usar TTS v3 do ElevenLabs. O OpenClaw mantém
|
||||
Defina `modelId` como `eleven_v3` para usar TTS v3 da ElevenLabs. OpenClaw mantém
|
||||
`eleven_multilingual_v2` como padrão para instalações existentes.
|
||||
|
||||
## Speech-to-text
|
||||
## Fala para texto
|
||||
|
||||
Use Scribe v2 para anexos de áudio recebidos e segmentos curtos de voz gravada:
|
||||
|
||||
@ -70,22 +70,22 @@ Use Scribe v2 para anexos de áudio recebidos e segmentos curtos de voz gravada:
|
||||
}
|
||||
```
|
||||
|
||||
O OpenClaw envia áudio multipart para `/v1/speech-to-text` do ElevenLabs com
|
||||
`model_id: "scribe_v2"`. Dicas de idioma são mapeadas para `language_code` quando presentes.
|
||||
OpenClaw envia áudio multipart para ElevenLabs `/v1/speech-to-text` com
|
||||
`model_id: "scribe_v2"`. As dicas de idioma são mapeadas para `language_code` quando presentes.
|
||||
|
||||
## STT de streaming para Voice Call
|
||||
## STT por streaming
|
||||
|
||||
O Plugin integrado `elevenlabs` registra Scribe v2 Realtime para
|
||||
transcrição em streaming do Voice Call.
|
||||
O Plugin `elevenlabs` incluído registra o Scribe v2 Realtime para transcrição por streaming
|
||||
em modo agente de chamada de voz e Google Meet.
|
||||
|
||||
| Configuração | Caminho de configuração | Padrão |
|
||||
| ---------------- | --------------------------------------------------------------------------- | -------------------------------------------------- |
|
||||
| Chave de API | `plugins.entries.voice-call.config.streaming.providers.elevenlabs.apiKey` | Usa `ELEVENLABS_API_KEY` / `XI_API_KEY` como fallback |
|
||||
| Modelo | `...elevenlabs.modelId` | `scribe_v2_realtime` |
|
||||
| Formato de áudio | `...elevenlabs.audioFormat` | `ulaw_8000` |
|
||||
| Sample rate | `...elevenlabs.sampleRate` | `8000` |
|
||||
| Estratégia de commit | `...elevenlabs.commitStrategy` | `vad` |
|
||||
| Idioma | `...elevenlabs.languageCode` | (não definido) |
|
||||
| Configuração | Caminho de configuração | Padrão |
|
||||
| --------------- | ------------------------------------------------------------------------- | ------------------------------------------------- |
|
||||
| Chave de API | `plugins.entries.voice-call.config.streaming.providers.elevenlabs.apiKey` | Recorre a `ELEVENLABS_API_KEY` / `XI_API_KEY` |
|
||||
| Modelo | `...elevenlabs.modelId` | `scribe_v2_realtime` |
|
||||
| Formato de áudio | `...elevenlabs.audioFormat` | `ulaw_8000` |
|
||||
| Taxa de amostragem | `...elevenlabs.sampleRate` | `8000` |
|
||||
| Estratégia de commit | `...elevenlabs.commitStrategy` | `vad` |
|
||||
| Idioma | `...elevenlabs.languageCode` | (não definido) |
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -113,12 +113,18 @@ transcrição em streaming do Voice Call.
|
||||
```
|
||||
|
||||
<Note>
|
||||
O Voice Call recebe mídia do Twilio como G.711 u-law a 8 kHz. O provider
|
||||
realtime do ElevenLabs usa `ulaw_8000` por padrão, então quadros de telefonia podem ser encaminhados sem
|
||||
A chamada de voz recebe mídia da Twilio como G.711 u-law a 8 kHz. O provedor em tempo real
|
||||
da ElevenLabs usa `ulaw_8000` como padrão, então quadros de telefonia podem ser encaminhados sem
|
||||
transcodificação.
|
||||
</Note>
|
||||
|
||||
Para o modo agente do Google Meet, defina
|
||||
`plugins.entries.google-meet.config.realtime.transcriptionProvider` como
|
||||
`"elevenlabs"` e configure o mesmo bloco de provedor em
|
||||
`plugins.entries.google-meet.config.realtime.providers.elevenlabs`.
|
||||
|
||||
## Relacionados
|
||||
|
||||
- [Text-to-speech](/pt-BR/tools/tts)
|
||||
- [Texto para fala](/pt-BR/tools/tts)
|
||||
- [Google Meet](/pt-BR/plugins/google-meet)
|
||||
- [Seleção de modelo](/pt-BR/concepts/model-providers)
|
||||
|
||||
@ -1,284 +1,188 @@
|
||||
---
|
||||
read_when:
|
||||
- Procurando definições públicas de canais de lançamento
|
||||
- Executando validação de lançamento ou aceitação de pacote
|
||||
- Procurando nomenclatura e cadência de versões
|
||||
summary: Canais de lançamento, checklist do operador, caixas de validação, nomenclatura de versões e cadência
|
||||
- Procurando definições de canais de lançamento públicos
|
||||
- Executando a validação de release ou a aceitação de pacote
|
||||
- Buscando nomenclatura e cadência de versões
|
||||
summary: Faixas de lançamento, lista de verificação do operador, caixas de validação, nomenclatura de versões e cadência
|
||||
title: Política de lançamento
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T21:36:44Z"
|
||||
generated_at: "2026-05-04T07:03:56Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 566088d826e1e2bac21b11443b82b62cb73ed1fd9c508c3fb865149cf8a428ba
|
||||
source_hash: ef50d3ef5d1e23b4e2c2b097fc4ca9f6d46bf8acb9aea0c9bca6d14e213b88b6
|
||||
source_path: reference/RELEASING.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
OpenClaw tem três canais públicos de lançamento:
|
||||
OpenClaw tem três canais públicos de release:
|
||||
|
||||
- estável: versões marcadas que publicam no npm `beta` por padrão, ou no npm `latest` quando solicitado explicitamente
|
||||
- beta: tags de pré-lançamento que publicam no npm `beta`
|
||||
- estável: releases marcadas que publicam no npm `beta` por padrão, ou no npm `latest` quando solicitado explicitamente
|
||||
- beta: tags de pré-release que publicam no npm `beta`
|
||||
- dev: o head móvel de `main`
|
||||
|
||||
## Nomenclatura de versões
|
||||
|
||||
- Versão de lançamento estável: `YYYY.M.D`
|
||||
- Versão de release estável: `YYYY.M.D`
|
||||
- Tag Git: `vYYYY.M.D`
|
||||
- Versão de correção estável: `YYYY.M.D-N`
|
||||
- Versão de release de correção estável: `YYYY.M.D-N`
|
||||
- Tag Git: `vYYYY.M.D-N`
|
||||
- Versão beta de pré-lançamento: `YYYY.M.D-beta.N`
|
||||
- Versão de pré-release beta: `YYYY.M.D-beta.N`
|
||||
- Tag Git: `vYYYY.M.D-beta.N`
|
||||
- Não preencha mês ou dia com zeros à esquerda
|
||||
- `latest` significa a versão npm estável promovida atual
|
||||
- `beta` significa o alvo atual de instalação beta
|
||||
- Lançamentos estáveis e de correção estável publicam no npm `beta` por padrão; operadores de release podem mirar `latest` explicitamente, ou promover uma build beta validada posteriormente
|
||||
- Todo lançamento estável do OpenClaw entrega o pacote npm e o app macOS juntos;
|
||||
lançamentos beta normalmente validam e publicam primeiro o caminho npm/pacote, com
|
||||
- Não preencha mês ou dia com zero à esquerda
|
||||
- `latest` significa o release npm estável promovido atual
|
||||
- `beta` significa o destino atual de instalação beta
|
||||
- Releases estáveis e releases de correção estáveis publicam no npm `beta` por padrão; operadores de release podem direcionar para `latest` explicitamente, ou promover uma build beta validada posteriormente
|
||||
- Todo release estável do OpenClaw entrega o pacote npm e o app macOS juntos;
|
||||
releases beta normalmente validam e publicam primeiro o caminho npm/pacote, com
|
||||
build/assinatura/notarização do app Mac reservados para estável, salvo solicitação explícita
|
||||
|
||||
## Cadência de lançamento
|
||||
## Cadência de release
|
||||
|
||||
- Lançamentos seguem primeiro para beta
|
||||
- Estável vem somente depois que o beta mais recente é validado
|
||||
- Mantenedores normalmente criam lançamentos a partir de uma branch `release/YYYY.M.D` criada
|
||||
a partir do `main` atual, para que validação e correções de release não bloqueiem novo
|
||||
desenvolvimento no `main`
|
||||
- Releases avançam primeiro para beta
|
||||
- Estável vem somente depois que a beta mais recente é validada
|
||||
- Mantenedores normalmente criam releases a partir de uma branch `release/YYYY.M.D` criada
|
||||
a partir da `main` atual, para que validação e correções de release não bloqueiem novo
|
||||
desenvolvimento na `main`
|
||||
- Se uma tag beta tiver sido enviada ou publicada e precisar de correção, mantenedores criam
|
||||
a próxima tag `-beta.N` em vez de excluir ou recriar a tag beta antiga
|
||||
- Procedimento detalhado de release, aprovações, credenciais e notas de recuperação são
|
||||
exclusivos para mantenedores
|
||||
apenas para mantenedores
|
||||
|
||||
## Checklist do operador de release
|
||||
|
||||
Este checklist é a forma pública do fluxo de release. Credenciais privadas,
|
||||
Este checklist é o formato público do fluxo de release. Credenciais privadas,
|
||||
assinatura, notarização, recuperação de dist-tag e detalhes de rollback de emergência ficam no
|
||||
runbook de release exclusivo para mantenedores.
|
||||
runbook de release restrito a mantenedores.
|
||||
|
||||
1. Comece do `main` atual: baixe a versão mais recente, confirme que o commit alvo foi enviado,
|
||||
e confirme que o CI atual do `main` está verde o suficiente para criar uma branch a partir dele.
|
||||
2. Reescreva a seção superior do `CHANGELOG.md` a partir do histórico real de commits com
|
||||
`/changelog`, mantenha as entradas voltadas ao usuário, faça commit, envie e faça rebase/pull
|
||||
1. Comece pela `main` atual: puxe a versão mais recente, confirme que o commit de destino foi enviado,
|
||||
e confirme que o CI da `main` atual está verde o suficiente para criar uma branch a partir dele.
|
||||
2. Reescreva a seção superior de `CHANGELOG.md` a partir do histórico real de commits com
|
||||
`/changelog`, mantenha as entradas voltadas ao usuário, faça commit, envie, e faça rebase/pull
|
||||
mais uma vez antes de criar a branch.
|
||||
3. Revise registros de compatibilidade de release em
|
||||
3. Revise os registros de compatibilidade de release em
|
||||
`src/plugins/compat/registry.ts` e
|
||||
`src/commands/doctor/shared/deprecation-compat.ts`. Remova compatibilidade expirada
|
||||
somente quando o caminho de upgrade continuar coberto, ou registre por que ela está
|
||||
sendo mantida intencionalmente.
|
||||
4. Crie `release/YYYY.M.D` a partir do `main` atual; não faça trabalho normal de release
|
||||
diretamente no `main`.
|
||||
5. Atualize todos os locais de versão obrigatórios para a tag pretendida, execute
|
||||
`pnpm plugins:sync` para que pacotes de Plugin publicáveis compartilhem a versão de release
|
||||
e os metadados de compatibilidade, então execute o preflight determinístico local:
|
||||
4. Crie `release/YYYY.M.D` a partir da `main` atual; não faça trabalho normal de release
|
||||
diretamente na `main`.
|
||||
5. Atualize todas as localizações de versão exigidas para a tag pretendida, execute
|
||||
`pnpm plugins:sync` para que os pacotes de Plugin publicáveis compartilhem a versão
|
||||
de release e os metadados de compatibilidade, depois execute o preflight determinístico local:
|
||||
`pnpm check:test-types`, `pnpm check:architecture`,
|
||||
`pnpm build && pnpm ui:build`, `pnpm plugins:sync:check` e
|
||||
`pnpm release:check`.
|
||||
6. Execute `OpenClaw NPM Release` com `preflight_only=true`. Antes de existir uma tag,
|
||||
um SHA completo de 40 caracteres da branch de release é permitido somente para validação
|
||||
preflight. Salve o `preflight_run_id` bem-sucedido.
|
||||
um SHA completo de 40 caracteres da branch de release é permitido para preflight
|
||||
apenas de validação. Salve o `preflight_run_id` bem-sucedido.
|
||||
7. Inicie todos os testes de pré-release com `Full Release Validation` para a
|
||||
branch de release, tag ou SHA completo do commit. Este é o único ponto de entrada manual
|
||||
para as quatro grandes caixas de teste de release: Vitest, Docker, QA Lab e Package.
|
||||
8. Se a validação falhar, corrija na branch de release e execute novamente o menor
|
||||
arquivo, canal, job de workflow, perfil de pacote, provedor ou allowlist de modelo que
|
||||
comprove a correção. Execute novamente o guarda-chuva completo somente quando a superfície
|
||||
alterada tornar evidências anteriores obsoletas.
|
||||
9. Para beta, marque `vYYYY.M.D-beta.N`, então execute `OpenClaw Release Publish` a partir
|
||||
8. Se a validação falhar, corrija na branch de release e reexecute o menor
|
||||
arquivo, canal, job de workflow, perfil de pacote, provedor ou allowlist de modelo com falha que
|
||||
comprove a correção. Reexecute o guarda-chuva completo somente quando a superfície alterada tornar
|
||||
as evidências anteriores obsoletas.
|
||||
9. Para beta, marque `vYYYY.M.D-beta.N`, depois execute `OpenClaw Release Publish` a partir
|
||||
da branch `release/YYYY.M.D` correspondente. Ele verifica `pnpm plugins:sync:check`,
|
||||
publica todos os pacotes de Plugin publicáveis no npm primeiro, publica o mesmo
|
||||
conjunto no ClawHub em seguida como tarballs npm-pack ClawPack e então promove o
|
||||
artefato preflight npm preparado do OpenClaw com a dist-tag correspondente. Após
|
||||
publicar, execute a aceitação de pacote pós-publicação contra o pacote
|
||||
`openclaw@YYYY.M.D-beta.N` ou `openclaw@beta` publicado. Se um pré-lançamento enviado
|
||||
ou publicado precisar de correção, crie o próximo número de pré-lançamento correspondente;
|
||||
não exclua nem reescreva o pré-lançamento antigo.
|
||||
10. Para estável, continue somente depois que o beta validado ou candidato a release tiver a
|
||||
evidência de validação necessária. A publicação npm estável também passa por
|
||||
`OpenClaw Release Publish`, reutilizando o artefato preflight bem-sucedido via
|
||||
`preflight_run_id`; a prontidão para release estável do macOS também exige os
|
||||
`.zip`, `.dmg`, `.dSYM.zip` empacotados e o `appcast.xml` atualizado no `main`.
|
||||
publica primeiro todos os pacotes de Plugin publicáveis no npm, publica o mesmo
|
||||
conjunto no ClawHub em segundo lugar como tarballs ClawPack npm-pack, e então promove o
|
||||
artefato de preflight npm preparado do OpenClaw com a dist-tag correspondente. Após
|
||||
publicar, execute a aceitação de pacote pós-publicação
|
||||
contra o pacote publicado `openclaw@YYYY.M.D-beta.N` ou
|
||||
`openclaw@beta`. Se uma pré-release enviada ou publicada precisar de correção,
|
||||
crie o próximo número de pré-release correspondente; não exclua nem reescreva a pré-release
|
||||
antiga.
|
||||
10. Para estável, continue somente depois que a beta validada ou o release candidate tiver as
|
||||
evidências de validação exigidas. A publicação npm estável também passa por
|
||||
`OpenClaw Release Publish`, reutilizando o artefato de preflight bem-sucedido via
|
||||
`preflight_run_id`; a prontidão do release macOS estável também exige os
|
||||
`.zip`, `.dmg`, `.dSYM.zip` empacotados e o `appcast.xml` atualizado na `main`.
|
||||
11. Após publicar, execute o verificador npm pós-publicação, o E2E opcional do Telegram
|
||||
publicado via npm independente quando você precisar de prova de canal pós-publicação,
|
||||
usando npm publicado independente quando precisar de prova de canal pós-publicação,
|
||||
promoção de dist-tag quando necessário, notas de release/pré-release do GitHub a partir da
|
||||
seção completa correspondente do `CHANGELOG.md` e as etapas de anúncio de release.
|
||||
seção completa correspondente de `CHANGELOG.md`, e as etapas de anúncio de release.
|
||||
|
||||
## Preflight de release
|
||||
|
||||
- Execute `pnpm check:test-types` antes do preflight de release para que o TypeScript dos testes continue
|
||||
coberto fora do gate local mais rápido `pnpm check`
|
||||
- Execute `pnpm check:architecture` antes do preflight de release para que as verificações mais amplas de ciclo de importação
|
||||
e limites de arquitetura estejam verdes fora do gate local mais rápido
|
||||
- Execute `pnpm build && pnpm ui:build` antes de `pnpm release:check` para que os artefatos de release esperados
|
||||
`dist/*` e o pacote da Control UI existam para a etapa de validação
|
||||
do pacote
|
||||
- Execute `pnpm plugins:sync` depois do bump da versão raiz e antes de marcar a tag. Ele
|
||||
atualiza as versões dos pacotes de Plugin publicáveis, os metadados de compatibilidade
|
||||
de peer/API do OpenClaw, os metadados de build e os stubs de changelog dos plugins para corresponder à versão
|
||||
de release do core. `pnpm plugins:sync:check` é a proteção de release sem mutação;
|
||||
o workflow de publicação falha antes de qualquer mutação no registro se esta etapa tiver sido
|
||||
esquecida.
|
||||
- Execute o workflow manual `Full Release Validation` antes da aprovação de release para
|
||||
iniciar todas as caixas de teste de pré-release a partir de um único ponto de entrada. Ele aceita uma branch,
|
||||
tag ou SHA completo de commit, dispara `CI` manual e dispara
|
||||
`OpenClaw Release Checks` para smoke de instalação, aceitação de pacote, suítes de caminho de release Docker,
|
||||
live/E2E, OpenWebUI, paridade do QA Lab, Matrix e faixas Telegram. Com
|
||||
`release_profile=full` e `rerun_group=all`, ele também executa o E2E de pacote
|
||||
Telegram contra o artefato `release-package-under-test` dos checks de release. Forneça
|
||||
`npm_telegram_package_spec` após a publicação quando o mesmo E2E Telegram também deve comprovar o pacote npm publicado. Forneça
|
||||
`package_acceptance_package_spec` após a publicação quando Package Acceptance
|
||||
deve executar sua matriz de pacote/atualização contra o pacote npm entregue em vez
|
||||
do artefato construído a partir do SHA. Forneça
|
||||
`evidence_package_spec` quando o relatório privado de evidências deve comprovar que a
|
||||
validação corresponde a um pacote npm publicado sem forçar o E2E Telegram.
|
||||
Exemplo:
|
||||
- Execute `pnpm check:test-types` antes do preflight de release para que o TypeScript de teste continue coberto fora do gate local mais rápido `pnpm check`
|
||||
- Execute `pnpm check:architecture` antes do preflight de release para que as verificações mais amplas de ciclos de importação e limites de arquitetura fiquem verdes fora do gate local mais rápido
|
||||
- Execute `pnpm build && pnpm ui:build` antes de `pnpm release:check` para que os artefatos de release esperados em `dist/*` e o bundle da Control UI existam para a etapa de validação do pack
|
||||
- Execute `pnpm plugins:sync` depois do bump da versão raiz e antes de criar a tag. Ele atualiza versões de pacotes de plugins publicáveis, metadados de compatibilidade de peer/API do OpenClaw, metadados de build e stubs de changelog dos plugins para corresponder à versão de release do core. `pnpm plugins:sync:check` é o guardião de release não mutável; o workflow de publicação falha antes de qualquer mutação no registry se esta etapa tiver sido esquecida.
|
||||
- Execute o workflow manual `Full Release Validation` antes da aprovação de release para iniciar todas as caixas de teste pré-release a partir de um único ponto de entrada. Ele aceita uma branch, tag ou SHA completo de commit, dispara `CI` manual e dispara `OpenClaw Release Checks` para smoke de instalação, aceitação de pacote, suítes de caminho de release do Docker, live/E2E, OpenWebUI, paridade do QA Lab, Matrix e faixas do Telegram. Com `release_profile=full` e `rerun_group=all`, ele também executa o E2E de pacote do Telegram contra o artefato `release-package-under-test` das verificações de release. Forneça `npm_telegram_package_spec` depois da publicação quando o mesmo E2E do Telegram também precisar comprovar o pacote npm publicado. Forneça `package_acceptance_package_spec` depois da publicação quando Package Acceptance precisar executar sua matriz de pacote/atualização contra o pacote npm entregue em vez do artefato criado a partir do SHA. Forneça `evidence_package_spec` quando o relatório privado de evidências precisar comprovar que a validação corresponde a um pacote npm publicado sem forçar E2E do Telegram. Exemplo:
|
||||
`gh workflow run full-release-validation.yml --ref main -f ref=release/YYYY.M.D`
|
||||
- Execute o workflow manual `Package Acceptance` quando quiser uma comprovação paralela
|
||||
para um candidato a pacote enquanto o trabalho de release continua. Use `source=npm` para
|
||||
`openclaw@beta`, `openclaw@latest` ou uma versão exata de release; `source=ref`
|
||||
para empacotar uma branch/tag/SHA confiável de `package_ref` com o harness atual
|
||||
`workflow_ref`; `source=url` para um tarball HTTPS com um SHA-256 obrigatório;
|
||||
ou `source=artifact` para um tarball enviado por outro run do GitHub
|
||||
Actions. O workflow resolve o candidato para
|
||||
`package-under-test`, reutiliza o agendador de release Docker E2E contra esse
|
||||
tarball e pode executar QA Telegram contra o mesmo tarball com
|
||||
`telegram_mode=mock-openai` ou `telegram_mode=live-frontier`. Quando as
|
||||
faixas Docker selecionadas incluem `published-upgrade-survivor`, o artefato do pacote
|
||||
é o candidato e `published_upgrade_survivor_baseline` seleciona
|
||||
a baseline publicada.
|
||||
- Execute o workflow manual `Package Acceptance` quando quiser prova por canal lateral para um candidato de pacote enquanto o trabalho de release continua. Use `source=npm` para `openclaw@beta`, `openclaw@latest` ou uma versão exata de release; `source=ref` para empacotar uma branch/tag/SHA `package_ref` confiável com o harness `workflow_ref` atual; `source=url` para um tarball HTTPS com SHA-256 obrigatório; ou `source=artifact` para um tarball enviado por outra execução do GitHub Actions. O workflow resolve o candidato para `package-under-test`, reutiliza o agendador de release Docker E2E contra esse tarball e pode executar QA do Telegram contra o mesmo tarball com `telegram_mode=mock-openai` ou `telegram_mode=live-frontier`. Quando as faixas Docker selecionadas incluem `published-upgrade-survivor`, o artefato do pacote é o candidato e `published_upgrade_survivor_baseline` seleciona a linha de base publicada.
|
||||
Exemplo: `gh workflow run package-acceptance.yml --ref main -f workflow_ref=main -f source=npm -f package_spec=openclaw@beta -f suite_profile=product -f published_upgrade_survivor_baseline=openclaw@2026.4.26 -f telegram_mode=mock-openai`
|
||||
Perfis comuns:
|
||||
- `smoke`: faixas de instalação/canal/agente, rede do Gateway e recarregamento de config
|
||||
- `package`: faixas nativas de artefato para pacote/atualização/Plugin sem OpenWebUI ou ClawHub live
|
||||
- `smoke`: faixas de instalação/canal/agente, rede do Gateway e recarregamento de configuração
|
||||
- `package`: faixas nativas de artefato para pacote/atualização/plugin sem OpenWebUI ou ClawHub live
|
||||
- `product`: perfil de pacote mais canais MCP, limpeza de cron/subagente,
|
||||
busca web da OpenAI e OpenWebUI
|
||||
- `full`: blocos de caminho de release Docker com OpenWebUI
|
||||
- `custom`: seleção exata de `docker_lanes` para uma nova execução focada
|
||||
- Execute o workflow manual `CI` diretamente quando precisar apenas da cobertura completa normal de CI
|
||||
para o candidato a release. Disparos manuais de CI ignoram o escopo por mudanças
|
||||
e forçam os shards Linux Node, shards de plugins incluídos, contratos de canal,
|
||||
compatibilidade com Node 22, `check`, `check-additional`, smoke de build,
|
||||
checks de documentação, Skills Python, Windows, macOS, Android e faixas de i18n
|
||||
da Control UI.
|
||||
- `full`: partes do caminho de release Docker com OpenWebUI
|
||||
- `custom`: seleção exata de `docker_lanes` para uma reexecução focada
|
||||
- Execute o workflow manual `CI` diretamente quando você só precisar da cobertura completa normal de CI para o candidato de release. Disparos manuais de CI ignoram o escopo por alterações e forçam as shards Linux Node, shards de plugins agrupados, contratos de canais, compatibilidade com Node 22, `check`, `check-additional`, smoke de build, verificações de docs, Skills em Python, Windows, macOS, Android e faixas de i18n da Control UI.
|
||||
Exemplo: `gh workflow run ci.yml --ref release/YYYY.M.D`
|
||||
- Execute `pnpm qa:otel:smoke` ao validar a telemetria de release. Ele exercita
|
||||
o QA-lab por meio de um receptor OTLP/HTTP local e verifica os nomes de spans
|
||||
de trace exportados, atributos limitados e redação de conteúdo/identificador sem
|
||||
exigir Opik, Langfuse ou outro coletor externo.
|
||||
- Execute `pnpm release:check` antes de todo release com tag
|
||||
- Execute `OpenClaw Release Publish` para a sequência de publicação com mutação depois que a
|
||||
tag existir. Dispare-o a partir de `release/YYYY.M.D` (ou `main` ao publicar uma
|
||||
tag alcançável por main), passe a tag de release e o `preflight_run_id` bem-sucedido
|
||||
do npm do OpenClaw, e mantenha o escopo padrão de publicação de Plugin
|
||||
`all-publishable`, a menos que você esteja executando deliberadamente um reparo focado. O
|
||||
workflow serializa a publicação npm de Plugin, a publicação de Plugin no ClawHub e a publicação npm
|
||||
do OpenClaw para que o pacote core não seja publicado antes de seus
|
||||
plugins externalizados.
|
||||
- Os checks de release agora rodam em um workflow manual separado:
|
||||
- Execute `pnpm qa:otel:smoke` ao validar telemetria de release. Ele exercita o QA-lab por meio de um receptor OTLP/HTTP local e verifica os nomes de spans de trace exportados, atributos limitados e redação de conteúdo/identificadores sem exigir Opik, Langfuse ou outro coletor externo.
|
||||
- Execute `pnpm release:check` antes de toda release com tag
|
||||
- Execute `OpenClaw Release Publish` para a sequência de publicação mutável depois que a tag existir. Dispare-o a partir de `release/YYYY.M.D` (ou `main` ao publicar uma tag alcançável por main), passe a tag de release e o `preflight_run_id` npm do OpenClaw bem-sucedido, e mantenha o escopo padrão de publicação de plugins `all-publishable`, a menos que você esteja executando deliberadamente um reparo focado. O workflow serializa a publicação npm de plugins, a publicação ClawHub de plugins e a publicação npm do OpenClaw para que o pacote core não seja publicado antes dos seus plugins externalizados.
|
||||
- As verificações de release agora são executadas em um workflow manual separado:
|
||||
`OpenClaw Release Checks`
|
||||
- `OpenClaw Release Checks` também executa a faixa de paridade mock do QA Lab mais o perfil rápido
|
||||
live Matrix e a faixa QA Telegram antes da aprovação de release. As faixas live
|
||||
usam o ambiente `qa-live-shared`; Telegram também usa concessões de credenciais Convex CI.
|
||||
Execute o workflow manual `QA-Lab - All Lanes` com
|
||||
`matrix_profile=all` e `matrix_shards=true` quando quiser o inventário completo de transporte,
|
||||
mídia e E2EE do Matrix em paralelo.
|
||||
- A validação de runtime de instalação e upgrade entre sistemas operacionais faz parte dos
|
||||
`OpenClaw Release Checks` e `Full Release Validation` públicos, que chamam diretamente
|
||||
o workflow reutilizável
|
||||
`.github/workflows/openclaw-cross-os-release-checks-reusable.yml`
|
||||
- Essa separação é intencional: manter o caminho real de release npm curto,
|
||||
determinístico e focado em artefatos, enquanto checks live mais lentos ficam em sua
|
||||
própria faixa para não atrasarem nem bloquearem a publicação
|
||||
- Checks de release com segredos devem ser disparados por meio de `Full Release
|
||||
Validation` ou a partir da ref de workflow `main`/release para que a lógica do workflow e os
|
||||
segredos permaneçam controlados
|
||||
- `OpenClaw Release Checks` aceita uma branch, tag ou SHA completo de commit desde que
|
||||
o commit resolvido seja alcançável a partir de uma branch do OpenClaw ou tag de release
|
||||
- O preflight somente de validação de `OpenClaw NPM Release` também aceita o SHA completo
|
||||
atual de 40 caracteres do commit da branch do workflow sem exigir uma tag enviada
|
||||
- Esse caminho por SHA é somente de validação e não pode ser promovido para uma publicação real
|
||||
- No modo SHA, o workflow sintetiza `v<package.json version>` apenas para a
|
||||
verificação de metadados do pacote; a publicação real ainda exige uma tag real de release
|
||||
- Ambos os workflows mantêm o caminho real de publicação e promoção em runners hospedados pelo GitHub,
|
||||
enquanto o caminho de validação sem mutação pode usar os runners Linux maiores
|
||||
da Blacksmith
|
||||
- `OpenClaw Release Checks` também executa a faixa de paridade mock do QA Lab mais o perfil Matrix live rápido e a faixa QA do Telegram antes da aprovação de release. As faixas live usam o ambiente `qa-live-shared`; o Telegram também usa concessões de credenciais CI do Convex. Execute o workflow manual `QA-Lab - All Lanes` com `matrix_profile=all` e `matrix_shards=true` quando quiser o inventário completo de transporte Matrix, mídia e E2EE em paralelo.
|
||||
- A validação de runtime de instalação e atualização entre sistemas operacionais faz parte dos workflows públicos `OpenClaw Release Checks` e `Full Release Validation`, que chamam diretamente o workflow reutilizável `.github/workflows/openclaw-cross-os-release-checks-reusable.yml`
|
||||
- Essa divisão é intencional: manter o caminho real de release npm curto, determinístico e focado em artefatos, enquanto verificações live mais lentas permanecem na própria faixa para não atrasarem nem bloquearem a publicação
|
||||
- Verificações de release que carregam segredos devem ser disparadas por meio de `Full Release Validation` ou a partir do ref de workflow `main`/release para que a lógica do workflow e os segredos permaneçam controlados
|
||||
- `OpenClaw Release Checks` aceita uma branch, tag ou SHA completo de commit desde que o commit resolvido seja alcançável a partir de uma branch OpenClaw ou tag de release
|
||||
- O preflight apenas de validação de `OpenClaw NPM Release` também aceita o SHA completo de 40 caracteres do commit atual da branch do workflow sem exigir uma tag enviada
|
||||
- Esse caminho por SHA é apenas de validação e não pode ser promovido para uma publicação real
|
||||
- No modo SHA, o workflow sintetiza `v<package.json version>` apenas para a verificação de metadados do pacote; a publicação real ainda exige uma tag de release real
|
||||
- Ambos os workflows mantêm o caminho real de publicação e promoção em runners hospedados pelo GitHub, enquanto o caminho de validação não mutável pode usar os runners Linux maiores do Blacksmith
|
||||
- Esse workflow executa
|
||||
`OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache`
|
||||
usando os segredos de workflow `OPENAI_API_KEY` e `ANTHROPIC_API_KEY`
|
||||
- O preflight de release npm não espera mais pela faixa separada de checks de release
|
||||
- O preflight de release npm não espera mais pela faixa separada de verificações de release
|
||||
- Execute `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts`
|
||||
(ou a tag beta/correção correspondente) antes da aprovação
|
||||
- Depois da publicação npm, execute
|
||||
`node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D`
|
||||
(ou a versão beta/correção correspondente) para verificar o caminho de instalação
|
||||
do registro publicado em um prefixo temporário novo
|
||||
(ou a versão beta/correção correspondente) para verificar o caminho de instalação pelo registry publicado em um prefixo temporário novo
|
||||
- Depois de uma publicação beta, execute `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live`
|
||||
para verificar o onboarding do pacote instalado, a configuração do Telegram e o E2E real do Telegram
|
||||
contra o pacote npm publicado usando o pool compartilhado de credenciais Telegram concedidas.
|
||||
Execuções locais pontuais de mantenedores podem omitir as vars Convex e passar diretamente as três
|
||||
credenciais de env `OPENCLAW_QA_TELEGRAM_*`.
|
||||
- Mantenedores podem executar o mesmo check pós-publicação pelo GitHub Actions por meio do
|
||||
workflow manual `NPM Telegram Beta E2E`. Ele é intencionalmente apenas manual e
|
||||
não roda a cada merge.
|
||||
- A automação de release de mantenedores agora usa preflight-depois-promover:
|
||||
- a publicação npm real deve passar por um `preflight_run_id` npm bem-sucedido
|
||||
para verificar onboarding do pacote instalado, configuração do Telegram e E2E real do Telegram contra o pacote npm publicado usando o pool compartilhado de credenciais alugadas do Telegram. Execuções pontuais locais de mantenedores podem omitir as vars do Convex e passar diretamente as três credenciais de env `OPENCLAW_QA_TELEGRAM_*`.
|
||||
- Para executar o smoke beta pós-publicação completo a partir de uma máquina de mantenedor, use `pnpm release:beta-smoke -- --beta betaN`. O helper executa validação de atualização npm/fresh-target do Parallels, dispara `NPM Telegram Beta E2E`, consulta a execução exata do workflow, baixa o artefato e imprime o relatório do Telegram.
|
||||
- Mantenedores podem executar a mesma verificação pós-publicação a partir do GitHub Actions por meio do workflow manual `NPM Telegram Beta E2E`. Ele é intencionalmente apenas manual e não roda em todo merge.
|
||||
- A automação de release de mantenedores agora usa preflight-depois-promote:
|
||||
- a publicação npm real deve passar um `preflight_run_id` npm bem-sucedido
|
||||
- a publicação npm real deve ser disparada a partir da mesma branch `main` ou
|
||||
`release/YYYY.M.D` que o run de preflight bem-sucedido
|
||||
`release/YYYY.M.D` da execução de preflight bem-sucedida
|
||||
- releases npm estáveis usam `beta` por padrão
|
||||
- a publicação npm estável pode mirar `latest` explicitamente via input do workflow
|
||||
- a mutação de dist-tag npm baseada em token agora fica em
|
||||
- a mutação de dist-tag npm baseada em token agora vive em
|
||||
`openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`
|
||||
por segurança, porque `npm dist-tag add` ainda precisa de `NPM_TOKEN` enquanto o
|
||||
repositório público mantém publicação somente por OIDC
|
||||
- `macOS Release` público é somente de validação; quando uma tag existe apenas em uma
|
||||
por segurança, porque `npm dist-tag add` ainda precisa de `NPM_TOKEN`, enquanto o repo público mantém publicação somente com OIDC
|
||||
- `macOS Release` público é apenas validação; quando uma tag existe apenas em uma
|
||||
branch de release, mas o workflow é disparado a partir de `main`, defina
|
||||
`public_release_branch=release/YYYY.M.D`
|
||||
- a publicação privada real para mac deve passar por `preflight_run_id` e `validate_run_id`
|
||||
privados de mac bem-sucedidos
|
||||
- os caminhos reais de publicação promovem artefatos preparados em vez de reconstruí-los
|
||||
novamente
|
||||
- Para releases estáveis de correção como `YYYY.M.D-N`, o verificador pós-publicação
|
||||
também verifica o mesmo caminho de upgrade com prefixo temporário de `YYYY.M.D` para `YYYY.M.D-N`,
|
||||
para que correções de release não deixem silenciosamente instalações globais mais antigas no
|
||||
payload estável base
|
||||
- O preflight de release npm falha fechado a menos que o tarball inclua tanto
|
||||
`dist/control-ui/index.html` quanto um payload não vazio de `dist/control-ui/assets/`
|
||||
para que não publiquemos novamente um painel de navegador vazio
|
||||
- A verificação pós-publicação também confere que os entrypoints de Plugin publicados e
|
||||
os metadados de pacote estão presentes no layout instalado do registro. Um release que
|
||||
entrega payloads de runtime de Plugin ausentes falha no verificador pós-publicação e
|
||||
não pode ser promovido para `latest`.
|
||||
- `pnpm test:install:smoke` também aplica o orçamento de `unpackedSize` do pacote npm no
|
||||
tarball candidato de atualização, para que o e2e do instalador capture crescimento acidental do pacote
|
||||
antes do caminho de publicação de release
|
||||
- Se o trabalho de release tocou o planejamento de CI, manifests de timing de extensions ou
|
||||
matrizes de teste de extensions, regenere e revise as saídas de matriz
|
||||
`plugin-prerelease-extension-shard` pertencentes ao planejador de
|
||||
`.github/workflows/plugin-prerelease.yml` antes da aprovação para que as notas de release não
|
||||
descrevam um layout de CI obsoleto
|
||||
- A prontidão de release estável para macOS também inclui as superfícies do atualizador:
|
||||
- o release no GitHub deve terminar com os arquivos `.zip`, `.dmg` e `.dSYM.zip` empacotados
|
||||
- a publicação privada real do mac deve passar por `preflight_run_id` e `validate_run_id` privados de mac bem-sucedidos
|
||||
- os caminhos reais de publicação promovem artefatos preparados em vez de reconstruí-los novamente
|
||||
- Para releases de correção estáveis como `YYYY.M.D-N`, o verificador pós-publicação também checa o mesmo caminho de atualização com prefixo temporário de `YYYY.M.D` para `YYYY.M.D-N`, para que correções de release não deixem silenciosamente instalações globais antigas no payload estável base
|
||||
- O preflight de release npm falha fechado, a menos que o tarball inclua tanto `dist/control-ui/index.html` quanto um payload não vazio em `dist/control-ui/assets/`, para que não entreguemos novamente um dashboard de navegador vazio
|
||||
- A verificação pós-publicação também checa se os entrypoints de plugins publicados e os metadados de pacote estão presentes no layout instalado do registry. Uma release que entrega payloads de runtime de plugins ausentes falha no verificador postpublish e não pode ser promovida para `latest`.
|
||||
- `pnpm test:install:smoke` também impõe o orçamento de `unpackedSize` do pack npm no tarball candidato de atualização, para que o e2e do instalador detecte crescimento acidental do pack antes do caminho de publicação de release
|
||||
- Se o trabalho de release tocou planejamento de CI, manifests de timing de extensões ou matrizes de teste de extensões, regenere e revise as saídas de matriz `plugin-prerelease-extension-shard`, de propriedade do planejador, a partir de `.github/workflows/plugin-prerelease.yml` antes da aprovação para que as notas de release não descrevam um layout de CI obsoleto
|
||||
- A prontidão de release estável do macOS também inclui as superfícies do atualizador:
|
||||
- a release do GitHub deve acabar com os `.zip`, `.dmg` e `.dSYM.zip` empacotados
|
||||
- `appcast.xml` em `main` deve apontar para o novo zip estável depois da publicação
|
||||
- o app empacotado deve manter um bundle id que não seja de debug, uma URL de feed Sparkle
|
||||
não vazia e um `CFBundleVersion` no piso canônico de build Sparkle
|
||||
ou acima dele para essa versão de release
|
||||
- o app empacotado deve manter um bundle id não debug, uma URL de feed Sparkle não vazia e um `CFBundleVersion` igual ou superior ao piso canônico de build do Sparkle para essa versão de release
|
||||
|
||||
## Caixas de teste de release
|
||||
|
||||
`Full Release Validation` é como operadores iniciam todos os testes de pré-release a partir de
|
||||
um único ponto de entrada. Para uma comprovação de commit fixado em uma branch que muda rapidamente, use o
|
||||
helper para que todo workflow filho rode a partir de uma branch temporária fixada no SHA
|
||||
alvo:
|
||||
`Full Release Validation` é como operadores iniciam todos os testes pré-release a partir de um único ponto de entrada. Para uma prova de commit fixado em uma branch de movimentação rápida, use o helper para que todo workflow filho rode a partir de uma branch temporária fixada no SHA de destino:
|
||||
|
||||
```bash
|
||||
pnpm ci:full-release --sha <full-sha>
|
||||
```
|
||||
|
||||
O auxiliar faz push de `release-ci/<sha>-...`, dispara `Full Release Validation`
|
||||
a partir dessa branch com `ref=<sha>`, verifica se cada workflow filho `headSha`
|
||||
corresponde ao alvo e então exclui a branch temporária. Isso evita validar por
|
||||
acidente uma execução filha de um `main` mais recente.
|
||||
O helper envia `release-ci/<sha>-...`, dispara `Full Release Validation` a partir dessa branch com `ref=<sha>`, verifica se todo `headSha` de workflow filho corresponde ao alvo e então exclui a branch temporária. Isso evita comprovar por acidente uma execução filha de `main` mais nova.
|
||||
|
||||
Para validação de branch ou tag de lançamento, execute-o a partir da ref
|
||||
confiável de workflow `main` e passe a branch ou tag de lançamento como `ref`:
|
||||
Para validação de branch ou tag de release, execute a partir do ref de workflow confiável `main` e passe a branch ou tag de release como `ref`:
|
||||
|
||||
```bash
|
||||
gh workflow run full-release-validation.yml \
|
||||
@ -290,39 +194,50 @@ gh workflow run full-release-validation.yml \
|
||||
-f evidence_package_spec=openclaw@YYYY.M.D-beta.N
|
||||
```
|
||||
|
||||
O fluxo de trabalho resolve o ref de destino, dispara o `CI` manual com
|
||||
`target_ref=<release-ref>`, dispara `OpenClaw Release Checks`, prepara um
|
||||
artefato pai `release-package-under-test` para verificações voltadas a pacote e
|
||||
dispara o E2E independente do pacote Telegram quando `release_profile=full` com
|
||||
`rerun_group=all` ou quando `npm_telegram_package_spec` está definido. `OpenClaw Release
|
||||
Checks` então expande para smoke de instalação, verificações de lançamento entre sistemas operacionais, cobertura live/E2E do caminho de lançamento do Docker, Package Acceptance com QA do pacote Telegram, paridade do QA Lab, Matrix ao vivo e Telegram ao vivo. Uma execução completa só é aceitável quando o
|
||||
resumo de `Full Release Validation`
|
||||
mostra `normal_ci` e `release_checks` como bem-sucedidos. No modo full/all,
|
||||
o filho `npm_telegram` também deve ser bem-sucedido; fora de full/all ele é ignorado
|
||||
a menos que um `npm_telegram_package_spec` publicado tenha sido fornecido. O resumo final
|
||||
do verificador inclui tabelas dos jobs mais lentos para cada execução filha, para que o gerente de lançamento possa ver o caminho crítico atual sem baixar logs.
|
||||
Consulte [Validação completa de lançamento](/pt-BR/reference/full-release-validation) para a
|
||||
matriz completa de estágios, nomes exatos dos jobs do fluxo de trabalho, diferenças entre perfis estável e completo, artefatos e identificadores de reexecução focada.
|
||||
Fluxos de trabalho filhos são disparados a partir do ref confiável que executa `Full Release
|
||||
Validation`, normalmente `--ref main`, mesmo quando o `ref` de destino aponta para um
|
||||
branch ou tag de lançamento mais antigo. Não há uma entrada separada de ref de fluxo de trabalho para Full Release Validation; escolha o harness confiável escolhendo o ref da execução do fluxo de trabalho.
|
||||
Não use `--ref main -f ref=<sha>` para comprovação exata de commit em `main` móvel;
|
||||
SHAs de commit brutos não podem ser refs de despacho de fluxo de trabalho, então use
|
||||
`pnpm ci:full-release --sha <sha>` para criar o branch temporário fixado.
|
||||
O fluxo de trabalho resolve a ref de destino, despacha o `CI` manual com
|
||||
`target_ref=<release-ref>`, despacha `OpenClaw Release Checks`, prepara um
|
||||
artefato pai `release-package-under-test` para verificações voltadas a pacotes e
|
||||
despacha o E2E independente do pacote Telegram quando `release_profile=full` com
|
||||
`rerun_group=all` ou quando `npm_telegram_package_spec` está definido. Em
|
||||
seguida, `OpenClaw Release Checks` distribui smoke de instalação, verificações de
|
||||
lançamento entre sistemas operacionais, cobertura do caminho de lançamento
|
||||
live/E2E em Docker, Package Acceptance com QA do pacote Telegram, paridade do QA
|
||||
Lab, Matrix live e Telegram live. Uma execução completa só é aceitável quando o
|
||||
resumo de `Full Release Validation` mostra `normal_ci` e `release_checks` como
|
||||
bem-sucedidos. No modo full/all, o filho `npm_telegram` também deve ser
|
||||
bem-sucedido; fora de full/all, ele é ignorado, a menos que um
|
||||
`npm_telegram_package_spec` publicado tenha sido fornecido. O resumo final do
|
||||
verificador inclui tabelas dos jobs mais lentos para cada execução filha, para
|
||||
que o gerente de lançamento possa ver o caminho crítico atual sem baixar logs.
|
||||
Consulte [Validação completa de lançamento](/pt-BR/reference/full-release-validation)
|
||||
para ver a matriz de estágios completa, os nomes exatos dos jobs de workflow, as
|
||||
diferenças entre os perfis stable e full, artefatos e identificadores de nova
|
||||
execução focada.
|
||||
Os workflows filhos são despachados a partir da ref confiável que executa
|
||||
`Full Release Validation`, normalmente `--ref main`, mesmo quando a `ref` de
|
||||
destino aponta para um branch ou tag de lançamento mais antigo. Não há uma
|
||||
entrada separada de ref do workflow Full Release Validation; escolha o harness
|
||||
confiável escolhendo a ref da execução do workflow. Não use `--ref main -f
|
||||
ref=<sha>` para prova de commit exata em uma `main` móvel; SHAs brutos de commit
|
||||
não podem ser refs de despacho de workflow, então use `pnpm ci:full-release
|
||||
--sha <sha>` para criar o branch temporário fixado.
|
||||
|
||||
Use `release_profile` para selecionar a abrangência live/provedor:
|
||||
Use `release_profile` para selecionar a amplitude live/de provedor:
|
||||
|
||||
- `minimum`: caminho mais rápido crítico para lançamento de OpenAI/core live e Docker
|
||||
- `stable`: mínimo mais cobertura estável de provedor/backend para aprovação de lançamento
|
||||
- `full`: estável mais cobertura ampla de provedor/mídia consultiva
|
||||
- `minimum`: caminho live e Docker mais rápido, crítico para lançamento, de OpenAI/core
|
||||
- `stable`: minimum mais cobertura estável de provedor/backend para aprovação de lançamento
|
||||
- `full`: stable mais cobertura ampla de provedores/mídia consultiva
|
||||
|
||||
`OpenClaw Release Checks` usa o ref confiável do fluxo de trabalho para resolver o ref de destino
|
||||
uma vez como `release-package-under-test` e reutiliza esse artefato tanto nas verificações Docker de caminho de lançamento quanto no Package Acceptance. Isso mantém todas as caixas voltadas a pacote nos mesmos bytes e evita builds repetidos de pacote.
|
||||
O smoke de instalação OpenAI entre sistemas operacionais usa `OPENCLAW_CROSS_OS_OPENAI_MODEL` quando a
|
||||
variável de repositório/org está definida, caso contrário `openai/gpt-5.4`, porque essa lane está
|
||||
comprovando instalação do pacote, onboarding, inicialização do gateway e uma rodada de agente ao vivo
|
||||
em vez de medir o desempenho do modelo padrão mais lento. A matriz live de provedores mais ampla
|
||||
continua sendo o local para cobertura específica de modelo.
|
||||
`OpenClaw Release Checks` usa a ref confiável do workflow para resolver a ref de
|
||||
destino uma vez como `release-package-under-test` e reutiliza esse artefato tanto
|
||||
nas verificações Docker do caminho de lançamento quanto no Package Acceptance.
|
||||
Isso mantém todas as caixas voltadas a pacotes nos mesmos bytes e evita builds de
|
||||
pacote repetidos. O smoke de instalação OpenAI entre sistemas operacionais usa
|
||||
`OPENCLAW_CROSS_OS_OPENAI_MODEL` quando a variável de repo/org está definida;
|
||||
caso contrário, usa `openai/gpt-5.4`, porque esta lane prova a instalação do
|
||||
pacote, onboarding, inicialização do Gateway e uma interação live de agente, em
|
||||
vez de fazer benchmark do modelo padrão mais lento. A matriz live mais ampla de
|
||||
provedores continua sendo o lugar para cobertura específica por modelo.
|
||||
|
||||
Use estas variantes dependendo do estágio de lançamento:
|
||||
|
||||
@ -354,35 +269,47 @@ gh workflow run full-release-validation.yml \
|
||||
-f npm_telegram_provider_mode=mock-openai
|
||||
```
|
||||
|
||||
Não use o guarda-chuva completo como a primeira reexecução após uma correção focada. Se uma caixa
|
||||
falhar, use o fluxo de trabalho filho, job, lane Docker, perfil de pacote, provedor de modelo
|
||||
ou lane de QA que falhou para a próxima comprovação. Execute o guarda-chuva completo novamente apenas quando
|
||||
a correção alterou a orquestração compartilhada de lançamento ou tornou obsoleta a evidência anterior de todas as caixas. O verificador final do guarda-chuva verifica novamente os ids registrados das execuções dos fluxos de trabalho filhos, então, depois que um fluxo de trabalho filho for reexecutado com sucesso, reexecute apenas o job pai
|
||||
Não use o guarda-chuva completo como a primeira nova execução após uma correção
|
||||
focada. Se uma caixa falhar, use o workflow filho, job, lane Docker, perfil de
|
||||
pacote, provedor de modelo ou lane de QA que falhou para a próxima prova.
|
||||
Execute o guarda-chuva completo novamente somente quando a correção tiver
|
||||
alterado a orquestração compartilhada de lançamento ou tornado obsoleta a
|
||||
evidência anterior de todas as caixas. O verificador final do guarda-chuva
|
||||
reverifica os ids registrados das execuções de workflows filhos; portanto, depois
|
||||
que um workflow filho for reexecutado com sucesso, reexecute apenas o job pai
|
||||
`Verify full validation` que falhou.
|
||||
|
||||
Para recuperação delimitada, passe `rerun_group` para o guarda-chuva. `all` é a execução real
|
||||
de candidato a lançamento, `ci` executa apenas o filho normal de CI, `plugin-prerelease`
|
||||
executa apenas o filho de plugin exclusivo de lançamento, `release-checks` executa todas as caixas de lançamento, e os grupos de lançamento mais estreitos são `install-smoke`, `cross-os`,
|
||||
`live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` e `npm-telegram`.
|
||||
Reexecuções focadas de `npm-telegram` exigem `npm_telegram_package_spec`; execuções full/all
|
||||
com `release_profile=full` usam o artefato de pacote de release-checks.
|
||||
Para recuperação limitada, passe `rerun_group` ao guarda-chuva. `all` é a
|
||||
execução real do candidato a lançamento, `ci` executa apenas o filho de CI normal,
|
||||
`plugin-prerelease` executa apenas o filho de plugin exclusivo de lançamento,
|
||||
`release-checks` executa todas as caixas de lançamento, e os grupos de lançamento
|
||||
mais estreitos são `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`,
|
||||
`qa-parity`, `qa-live` e `npm-telegram`. Novas execuções focadas de
|
||||
`npm-telegram` exigem `npm_telegram_package_spec`; execuções full/all com
|
||||
`release_profile=full` usam o artefato de pacote de release-checks.
|
||||
|
||||
### Vitest
|
||||
|
||||
A caixa Vitest é o fluxo de trabalho filho `CI` manual. O CI manual intencionalmente
|
||||
contorna o escopo por alterações e força o grafo normal de testes para o candidato a lançamento: shards Linux Node, shards de plugins empacotados, contratos de canais, compatibilidade com Node 22, `check`, `check-additional`, smoke de build, verificações de docs, Skills Python, Windows, macOS, Android e i18n da Control UI.
|
||||
A caixa Vitest é o workflow filho `CI` manual. O CI manual ignora
|
||||
intencionalmente o escopo por mudanças e força o grafo de testes normal para o
|
||||
candidato a lançamento: shards Linux Node, shards de plugins agrupados,
|
||||
contratos de canais, compatibilidade com Node 22, `check`, `check-additional`,
|
||||
smoke de build, verificações de docs, Skills Python, Windows, macOS, Android e
|
||||
i18n da Control UI.
|
||||
|
||||
Use esta caixa para responder "a árvore de código-fonte passou pela suíte normal completa de testes?"
|
||||
Ela não é o mesmo que validação de produto no caminho de lançamento. Evidências a manter:
|
||||
Use esta caixa para responder "a árvore de código-fonte passou na suíte completa
|
||||
normal de testes?" Ela não é a mesma coisa que validação de produto no caminho de
|
||||
lançamento. Evidências a manter:
|
||||
|
||||
- resumo de `Full Release Validation` mostrando a URL da execução de `CI` disparada
|
||||
- execução de `CI` verde no SHA exato de destino
|
||||
- resumo de `Full Release Validation` mostrando a URL da execução `CI` despachada
|
||||
- execução `CI` verde no SHA de destino exato
|
||||
- nomes de shards com falha ou lentos dos jobs de CI ao investigar regressões
|
||||
- artefatos de tempo do Vitest, como `.artifacts/vitest-shard-timings.json`, quando
|
||||
uma execução precisar de análise de desempenho
|
||||
- artefatos de temporização do Vitest, como `.artifacts/vitest-shard-timings.json`, quando
|
||||
uma execução precisa de análise de desempenho
|
||||
|
||||
Execute o CI manual diretamente apenas quando o lançamento precisar de CI normal determinístico, mas
|
||||
não das caixas Docker, QA Lab, live, entre sistemas operacionais ou de pacote:
|
||||
Execute o CI manual diretamente somente quando o lançamento precisar de CI normal
|
||||
determinístico, mas não das caixas Docker, QA Lab, live, entre sistemas
|
||||
operacionais ou de pacote:
|
||||
|
||||
```bash
|
||||
gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D
|
||||
@ -390,18 +317,18 @@ gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D
|
||||
|
||||
### Docker
|
||||
|
||||
A caixa Docker vive em `OpenClaw Release Checks` por meio de
|
||||
`openclaw-live-and-e2e-checks-reusable.yml`, além do fluxo de trabalho `install-smoke`
|
||||
em modo de lançamento. Ela valida o candidato a lançamento por ambientes Docker empacotados
|
||||
em vez de apenas testes em nível de código-fonte.
|
||||
A caixa Docker fica em `OpenClaw Release Checks` por meio de
|
||||
`openclaw-live-and-e2e-checks-reusable.yml`, além do workflow `install-smoke` em
|
||||
modo de lançamento. Ela valida o candidato a lançamento por meio de ambientes
|
||||
Docker empacotados, em vez de apenas testes em nível de código-fonte.
|
||||
|
||||
A cobertura Docker de lançamento inclui:
|
||||
|
||||
- smoke completo de instalação com o smoke lento de instalação global Bun habilitado
|
||||
- preparação/reutilização da imagem de smoke do Dockerfile raiz por SHA de destino, com QR,
|
||||
root/gateway e jobs de smoke de instalador/Bun executando como shards separados de install-smoke
|
||||
- preparação/reutilização da imagem smoke do Dockerfile raiz por SHA de destino, com QR,
|
||||
raiz/Gateway e jobs de smoke de instalador/Bun executando como shards separados de install-smoke
|
||||
- lanes E2E do repositório
|
||||
- chunks Docker de caminho de lançamento: `core`, `package-update-openai`,
|
||||
- chunks Docker do caminho de lançamento: `core`, `package-update-openai`,
|
||||
`package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`,
|
||||
`plugins-runtime-services`,
|
||||
`plugins-runtime-install-a`, `plugins-runtime-install-b`,
|
||||
@ -409,85 +336,98 @@ A cobertura Docker de lançamento inclui:
|
||||
`plugins-runtime-install-e`, `plugins-runtime-install-f`,
|
||||
`plugins-runtime-install-g` e `plugins-runtime-install-h`
|
||||
- cobertura OpenWebUI dentro do chunk `plugins-runtime-services` quando solicitada
|
||||
- lanes divididas de instalação/desinstalação de plugins empacotados
|
||||
`bundled-plugin-install-uninstall-0` até
|
||||
- lanes divididas de instalação/desinstalação de plugin agrupado,
|
||||
de `bundled-plugin-install-uninstall-0` até
|
||||
`bundled-plugin-install-uninstall-23`
|
||||
- suítes de provedores live/E2E e cobertura de modelo Docker live quando as verificações de lançamento
|
||||
incluem suítes live
|
||||
- suítes live/E2E de provedores e cobertura de modelo live em Docker quando as verificações
|
||||
de lançamento incluem suítes live
|
||||
|
||||
Use artefatos Docker antes de reexecutar. O agendador de caminho de lançamento envia
|
||||
`.artifacts/docker-tests/` com logs de lanes, `summary.json`, `failures.json`,
|
||||
tempos de fases, JSON do plano do agendador e comandos de reexecução. Para recuperação focada,
|
||||
use `docker_lanes=<lane[,lane]>` no fluxo de trabalho live/E2E reutilizável em vez de
|
||||
reexecutar todos os chunks de lançamento. Comandos de reexecução gerados incluem
|
||||
`package_artifact_run_id` anterior e entradas de imagem Docker preparadas quando disponíveis, para que uma
|
||||
lane com falha possa reutilizar o mesmo tarball e imagens GHCR.
|
||||
Use os artefatos Docker antes de reexecutar. O agendador do caminho de lançamento
|
||||
envia `.artifacts/docker-tests/` com logs de lanes, `summary.json`,
|
||||
`failures.json`, temporizações de fases, JSON do plano do agendador e comandos de
|
||||
nova execução. Para recuperação focada, use `docker_lanes=<lane[,lane]>` no
|
||||
workflow reutilizável live/E2E em vez de reexecutar todos os chunks de
|
||||
lançamento. Comandos gerados de nova execução incluem o
|
||||
`package_artifact_run_id` anterior e entradas preparadas de imagem Docker quando
|
||||
disponíveis, para que uma lane com falha possa reutilizar o mesmo tarball e as
|
||||
mesmas imagens GHCR.
|
||||
|
||||
### QA Lab
|
||||
|
||||
A caixa QA Lab também faz parte de `OpenClaw Release Checks`. Ela é o gate de lançamento de comportamento agêntico e de nível de canal, separada da mecânica de pacote do Vitest e do Docker.
|
||||
A caixa QA Lab também faz parte de `OpenClaw Release Checks`. Ela é o gate de
|
||||
lançamento de comportamento agentivo e em nível de canal, separado do Vitest e
|
||||
dos mecanismos de pacote do Docker.
|
||||
|
||||
A cobertura QA Lab de lançamento inclui:
|
||||
|
||||
- lane de paridade mock comparando a lane candidata OpenAI com a baseline Opus 4.6
|
||||
usando o pacote de paridade agêntica
|
||||
usando o pacote de paridade agentiva
|
||||
- perfil rápido de QA Matrix live usando o ambiente `qa-live-shared`
|
||||
- lane de QA Telegram live usando leases de credenciais Convex CI
|
||||
- `pnpm qa:otel:smoke` quando a telemetria de lançamento precisa de comprovação local explícita
|
||||
- lane de QA Telegram live usando locações de credenciais CI do Convex
|
||||
- `pnpm qa:otel:smoke` quando a telemetria de lançamento precisa de prova local explícita
|
||||
|
||||
Use esta caixa para responder "o lançamento se comporta corretamente em cenários de QA e
|
||||
fluxos de canais live?" Mantenha as URLs de artefatos para as lanes de paridade, Matrix e Telegram ao aprovar o lançamento. A cobertura completa de Matrix continua disponível como uma
|
||||
execução manual shardada do QA-Lab, em vez da lane crítica padrão de lançamento.
|
||||
Use esta caixa para responder "o lançamento se comporta corretamente em cenários
|
||||
de QA e fluxos live de canal?" Mantenha as URLs de artefatos para as lanes de
|
||||
paridade, Matrix e Telegram ao aprovar o lançamento. A cobertura Matrix completa
|
||||
continua disponível como uma execução QA-Lab manual em shards, em vez da lane
|
||||
padrão crítica para lançamento.
|
||||
|
||||
### Pacote
|
||||
|
||||
A caixa Package é o gate de produto instalável. Ela é apoiada por
|
||||
A caixa Pacote é o gate do produto instalável. Ela é apoiada por
|
||||
`Package Acceptance` e pelo resolvedor
|
||||
`scripts/resolve-openclaw-package-candidate.mjs`. O resolvedor normaliza um
|
||||
candidato no tarball `package-under-test` consumido pelo Docker E2E, valida
|
||||
o inventário do pacote, registra a versão do pacote e o SHA-256, e mantém o
|
||||
ref do harness do fluxo de trabalho separado do ref de origem do pacote.
|
||||
candidato no tarball `package-under-test` consumido pelo Docker E2E, valida o
|
||||
inventário do pacote, registra a versão do pacote e o SHA-256, e mantém a ref do
|
||||
harness do workflow separada da ref do código-fonte do pacote.
|
||||
|
||||
Fontes de candidato compatíveis:
|
||||
|
||||
- `source=npm`: `openclaw@beta`, `openclaw@latest` ou uma versão exata de lançamento do OpenClaw
|
||||
- `source=ref`: empacote um branch, tag ou SHA completo de commit de `package_ref` confiável
|
||||
- `source=ref`: empacota um branch, tag ou SHA completo de commit de `package_ref` confiável
|
||||
com o harness `workflow_ref` selecionado
|
||||
- `source=url`: baixe um `.tgz` HTTPS com `package_sha256` obrigatório
|
||||
- `source=artifact`: reutilize um `.tgz` enviado por outra execução do GitHub Actions
|
||||
- `source=url`: baixa um `.tgz` HTTPS com `package_sha256` obrigatório
|
||||
- `source=artifact`: reutiliza um `.tgz` enviado por outra execução do GitHub Actions
|
||||
|
||||
`OpenClaw Release Checks` executa Package Acceptance com `source=artifact`, o
|
||||
artefato preparado do pacote de lançamento, `suite_profile=custom`,
|
||||
artefato de pacote de lançamento preparado, `suite_profile=custom`,
|
||||
`docker_lanes=doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update`,
|
||||
`published_upgrade_survivor_baselines=all-since-2026.4.23`,
|
||||
`published_upgrade_survivor_scenarios=reported-issues` e
|
||||
`telegram_mode=mock-openai`. Package Acceptance mantém migração, atualização, limpeza de dependências obsoletas de plugins, fixtures de plugins offline, atualização de plugins e QA de pacote Telegram contra o mesmo tarball resolvido. A matriz de upgrade cobre toda baseline estável publicada no npm de `2026.4.23` até `latest`; use
|
||||
Package Acceptance com `source=npm` para um candidato já lançado, ou
|
||||
`source=ref`/`source=artifact` para um tarball npm local respaldado por SHA antes da
|
||||
publicação. Ela é a substituição nativa do GitHub
|
||||
para a maior parte da cobertura de pacote/atualização que antes exigia
|
||||
Parallels. Verificações de lançamento entre sistemas operacionais ainda importam para onboarding,
|
||||
instalador e comportamento específicos de SO, mas a validação de produto de pacote/atualização deve
|
||||
preferir Package Acceptance.
|
||||
`telegram_mode=mock-openai`. Package Acceptance mantém migração, atualização,
|
||||
limpeza de dependências obsoletas de plugin, fixtures de plugin offline,
|
||||
atualização de plugin e QA de pacote Telegram contra o mesmo tarball resolvido. A
|
||||
matriz de upgrade cobre todas as baselines estáveis publicadas no npm de
|
||||
`2026.4.23` até `latest`; use Package Acceptance com `source=npm` para um
|
||||
candidato já enviado, ou `source=ref`/`source=artifact` para um tarball npm local
|
||||
com base em SHA antes da publicação. Ele é o substituto nativo do GitHub para a
|
||||
maior parte da cobertura de pacote/atualização que antes exigia Parallels. As
|
||||
verificações de lançamento entre sistemas operacionais ainda importam para
|
||||
onboarding, instalador e comportamento de plataforma específicos de SO, mas a
|
||||
validação de produto de pacote/atualização deve preferir Package Acceptance.
|
||||
|
||||
A checklist canônica para validação de atualização e plugin é
|
||||
[Testando atualizações e plugins](/pt-BR/help/testing-updates-plugins). Use-a ao
|
||||
decidir qual lane local, Docker, Package Acceptance ou release-check comprova uma
|
||||
instalação/atualização de plugin, limpeza do doctor ou alteração de migração de pacote publicado.
|
||||
A migração exaustiva de atualização publicada de todo pacote estável `2026.4.23+` é
|
||||
um fluxo de trabalho manual `Update Migration` separado, não parte do Full Release CI.
|
||||
decidir qual lane local, Docker, Package Acceptance ou de release-check prova uma
|
||||
instalação/atualização de plugin, limpeza pelo doctor ou mudança de migração de
|
||||
pacote publicado. A migração exaustiva de atualização publicada a partir de cada
|
||||
pacote estável `2026.4.23+` é um workflow manual separado `Update Migration`, não
|
||||
parte do Full Release CI.
|
||||
|
||||
A leniência legada de package-acceptance é intencionalmente limitada no tempo. Pacotes até
|
||||
`2026.4.25` podem usar o caminho de compatibilidade para lacunas de metadados já publicadas
|
||||
no npm: entradas privadas de inventário de QA ausentes no tarball, ausência de
|
||||
`gateway install --wrapper`, arquivos de patch ausentes na fixture git derivada do tarball,
|
||||
ausência de `update.channel` persistido, locais legados de registro de instalação de plugins,
|
||||
ausência de persistência de registro de instalação do marketplace e migração de metadados de configuração durante `plugins update`. O pacote publicado `2026.4.26` pode avisar
|
||||
sobre arquivos locais de carimbo de metadados de build que já foram lançados. Pacotes posteriores
|
||||
devem satisfazer os contratos modernos de pacote; essas mesmas lacunas falham na validação de lançamento.
|
||||
A leniência legada de package-acceptance é intencionalmente limitada no tempo.
|
||||
Pacotes até `2026.4.25` podem usar o caminho de compatibilidade para lacunas de
|
||||
metadados já publicadas no npm: entradas privadas de inventário de QA ausentes no
|
||||
tarball, `gateway install --wrapper` ausente, arquivos de patch ausentes no
|
||||
fixture git derivado do tarball, `update.channel` persistido ausente, locais
|
||||
legados de registro de instalação de plugin, persistência ausente de registro de
|
||||
instalação do marketplace e migração de metadados de configuração durante
|
||||
`plugins update`. O pacote `2026.4.26` publicado pode avisar sobre arquivos de
|
||||
carimbo de metadados de build local que já foram enviados. Pacotes posteriores
|
||||
devem satisfazer os contratos modernos de pacote; essas mesmas lacunas fazem a
|
||||
validação de lançamento falhar.
|
||||
|
||||
Use perfis mais amplos de Package Acceptance quando a pergunta de lançamento for sobre um
|
||||
pacote realmente instalável:
|
||||
Use perfis Package Acceptance mais amplos quando a pergunta de lançamento for
|
||||
sobre um pacote instalável real:
|
||||
|
||||
```bash
|
||||
gh workflow run package-acceptance.yml \
|
||||
@ -501,33 +441,33 @@ gh workflow run package-acceptance.yml \
|
||||
|
||||
Perfis comuns de pacote:
|
||||
|
||||
- `smoke`: lanes rápidas de instalação de pacote/canal/agente, rede do Gateway e
|
||||
- `smoke`: faixas rápidas de instalação de pacote/canal/agente, rede do Gateway e
|
||||
recarregamento de configuração
|
||||
- `package`: contratos de instalação/atualização/pacote de Plugin sem ClawHub ao vivo; este é o padrão de
|
||||
verificação de release
|
||||
- `product`: `package` mais canais MCP, limpeza de cron/subagente, pesquisa na web da OpenAI
|
||||
- `package`: contratos de instalação/atualização/pacote de Plugin sem ClawHub ao vivo; este é o
|
||||
padrão de verificação de lançamento
|
||||
- `product`: `package` mais canais MCP, limpeza de cron/subagente, pesquisa web da OpenAI
|
||||
e OpenWebUI
|
||||
- `full`: partes do caminho de release do Docker com OpenWebUI
|
||||
- `full`: partes do caminho de lançamento Docker com OpenWebUI
|
||||
- `custom`: lista exata de `docker_lanes` para reexecuções focadas
|
||||
|
||||
Para comprovação de Telegram de pacote candidato, habilite `telegram_mode=mock-openai` ou
|
||||
`telegram_mode=live-frontier` em Package Acceptance. O workflow passa o
|
||||
tarball `package-under-test` resolvido para a lane do Telegram; o workflow
|
||||
independente do Telegram ainda aceita uma especificação npm publicada para verificações pós-publicação.
|
||||
Para prova do Telegram com pacote candidato, habilite `telegram_mode=mock-openai` ou
|
||||
`telegram_mode=live-frontier` em Package Acceptance. O workflow passa o tarball
|
||||
resolvido de `package-under-test` para a faixa do Telegram; o workflow avulso do
|
||||
Telegram ainda aceita uma especificação npm publicada para verificações pós-publicação.
|
||||
|
||||
## Automação de publicação de release
|
||||
## Automação de publicação de lançamento
|
||||
|
||||
`OpenClaw Release Publish` é o ponto de entrada normal de publicação mutante. Ele
|
||||
orquestra os workflows de publicador confiável na ordem necessária para a release:
|
||||
`OpenClaw Release Publish` é o ponto de entrada mutável normal de publicação. Ele
|
||||
orquestra os workflows de publicador confiável na ordem exigida pelo lançamento:
|
||||
|
||||
1. Fazer checkout da tag da release e resolver seu SHA de commit.
|
||||
2. Verificar se a tag é acessível a partir de `main` ou `release/*`.
|
||||
1. Fazer checkout da tag de lançamento e resolver seu SHA de commit.
|
||||
2. Verificar se a tag é alcançável a partir de `main` ou `release/*`.
|
||||
3. Executar `pnpm plugins:sync:check`.
|
||||
4. Disparar `Plugin NPM Release` com `publish_scope=all-publishable` e
|
||||
`ref=<release-sha>`.
|
||||
5. Disparar `Plugin ClawHub Release` com o mesmo escopo e SHA.
|
||||
6. Disparar `OpenClaw NPM Release` com a tag da release, a dist-tag npm e
|
||||
o `preflight_run_id` salvo.
|
||||
6. Disparar `OpenClaw NPM Release` com a tag de lançamento, a dist-tag npm e o
|
||||
`preflight_run_id` salvo.
|
||||
|
||||
Exemplo de publicação beta:
|
||||
|
||||
@ -549,7 +489,7 @@ gh workflow run openclaw-release-publish.yml \
|
||||
-f npm_dist_tag=beta
|
||||
```
|
||||
|
||||
Promoção estável diretamente para `latest` é explícita:
|
||||
A promoção estável diretamente para `latest` é explícita:
|
||||
|
||||
```bash
|
||||
gh workflow run openclaw-release-publish.yml \
|
||||
@ -560,18 +500,18 @@ gh workflow run openclaw-release-publish.yml \
|
||||
```
|
||||
|
||||
Use os workflows de nível mais baixo `Plugin NPM Release` e `Plugin ClawHub Release`
|
||||
somente para trabalho focado de reparo ou republicação. Para um reparo de Plugin selecionado, passe
|
||||
`plugin_publish_scope=selected` e `plugins=@openclaw/name` para
|
||||
`OpenClaw Release Publish`, ou dispare o workflow filho diretamente quando o
|
||||
pacote OpenClaw não deve ser publicado.
|
||||
apenas para trabalhos focados de reparo ou republicação. Para um reparo de Plugin
|
||||
selecionado, passe `plugin_publish_scope=selected` e `plugins=@openclaw/name` para
|
||||
`OpenClaw Release Publish`, ou dispare o workflow filho diretamente quando o pacote
|
||||
OpenClaw não deve ser publicado.
|
||||
|
||||
## Entradas do workflow NPM
|
||||
|
||||
`OpenClaw NPM Release` aceita estas entradas controladas pelo operador:
|
||||
|
||||
- `tag`: tag de release obrigatória, como `v2026.4.2`, `v2026.4.2-1` ou
|
||||
`v2026.4.2-beta.1`; quando `preflight_only=true`, também pode ser o SHA de commit completo
|
||||
atual de 40 caracteres da branch do workflow para preflight somente de validação
|
||||
- `tag`: tag de lançamento obrigatória, como `v2026.4.2`, `v2026.4.2-1` ou
|
||||
`v2026.4.2-beta.1`; quando `preflight_only=true`, também pode ser o SHA de commit
|
||||
completo de 40 caracteres do branch do workflow atual para preflight apenas de validação
|
||||
- `preflight_only`: `true` apenas para validação/build/pacote, `false` para o
|
||||
caminho real de publicação
|
||||
- `preflight_run_id`: obrigatório no caminho real de publicação para que o workflow reutilize
|
||||
@ -580,70 +520,70 @@ pacote OpenClaw não deve ser publicado.
|
||||
|
||||
`OpenClaw Release Publish` aceita estas entradas controladas pelo operador:
|
||||
|
||||
- `tag`: tag de release obrigatória; já deve existir
|
||||
- `tag`: tag de lançamento obrigatória; já deve existir
|
||||
- `preflight_run_id`: id da execução de preflight bem-sucedida de `OpenClaw NPM Release`;
|
||||
obrigatório quando `publish_openclaw_npm=true`
|
||||
- `npm_dist_tag`: tag npm de destino para o pacote OpenClaw
|
||||
- `plugin_publish_scope`: o padrão é `all-publishable`; use `selected` somente
|
||||
- `plugin_publish_scope`: o padrão é `all-publishable`; use `selected` apenas
|
||||
para trabalho focado de reparo
|
||||
- `plugins`: nomes de pacotes `@openclaw/*` separados por vírgula quando
|
||||
`plugin_publish_scope=selected`
|
||||
- `publish_openclaw_npm`: o padrão é `true`; defina como `false` somente ao usar o
|
||||
workflow como orquestrador de reparo somente de Plugin
|
||||
- `publish_openclaw_npm`: o padrão é `true`; defina como `false` apenas ao usar o
|
||||
workflow como orquestrador de reparo somente de Plugins
|
||||
|
||||
`OpenClaw Release Checks` aceita estas entradas controladas pelo operador:
|
||||
|
||||
- `ref`: branch, tag ou SHA de commit completo a validar. Verificações com segredos
|
||||
exigem que o commit resolvido seja acessível a partir de uma branch do OpenClaw ou
|
||||
tag de release.
|
||||
- `ref`: branch, tag ou SHA de commit completo a validar. Verificações que carregam segredos
|
||||
exigem que o commit resolvido seja alcançável a partir de um branch do OpenClaw ou
|
||||
tag de lançamento.
|
||||
|
||||
Regras:
|
||||
|
||||
- Tags estáveis e de correção podem publicar em `beta` ou `latest`
|
||||
- Tags de pré-release beta podem publicar somente em `beta`
|
||||
- Para `OpenClaw NPM Release`, a entrada de SHA de commit completo é permitida somente quando
|
||||
- Tags beta de pré-lançamento podem publicar apenas em `beta`
|
||||
- Para `OpenClaw NPM Release`, a entrada de SHA de commit completo é permitida apenas quando
|
||||
`preflight_only=true`
|
||||
- `OpenClaw Release Checks` e `Full Release Validation` são sempre
|
||||
somente validação
|
||||
apenas de validação
|
||||
- O caminho real de publicação deve usar o mesmo `npm_dist_tag` usado durante o preflight;
|
||||
o workflow verifica esses metadados antes que a publicação continue
|
||||
o workflow verifica esses metadados antes de a publicação continuar
|
||||
|
||||
## Sequência de release npm estável
|
||||
## Sequência de lançamento npm estável
|
||||
|
||||
Ao preparar uma release npm estável:
|
||||
Ao preparar um lançamento npm estável:
|
||||
|
||||
1. Execute `OpenClaw NPM Release` com `preflight_only=true`
|
||||
- Antes de existir uma tag, você pode usar o SHA de commit completo atual da branch do workflow
|
||||
para uma simulação somente de validação do workflow de preflight
|
||||
2. Escolha `npm_dist_tag=beta` para o fluxo normal beta primeiro, ou `latest` somente
|
||||
- Antes de uma tag existir, você pode usar o SHA de commit completo do branch do workflow atual
|
||||
para uma execução simulada apenas de validação do workflow de preflight
|
||||
2. Escolha `npm_dist_tag=beta` para o fluxo normal beta primeiro, ou `latest` apenas
|
||||
quando você quiser intencionalmente uma publicação estável direta
|
||||
3. Execute `Full Release Validation` na branch da release, tag da release ou SHA de commit completo
|
||||
quando quiser CI normal mais cache de prompt ao vivo, Docker, QA Lab,
|
||||
Matrix e cobertura de Telegram a partir de um workflow manual
|
||||
4. Se você intencionalmente só precisa do grafo de testes normal determinístico, execute o
|
||||
workflow manual `CI` na ref da release em vez disso
|
||||
3. Execute `Full Release Validation` no branch de lançamento, tag de lançamento ou SHA de
|
||||
commit completo quando quiser CI normal mais cobertura de cache de prompt ao vivo,
|
||||
Docker, QA Lab, Matrix e Telegram em um único workflow manual
|
||||
4. Se você intencionalmente precisar apenas do grafo de testes normal determinístico, execute o
|
||||
workflow manual `CI` na ref de lançamento
|
||||
5. Salve o `preflight_run_id` bem-sucedido
|
||||
6. Execute `OpenClaw Release Publish` com a mesma `tag`, o mesmo `npm_dist_tag`
|
||||
e o `preflight_run_id` salvo; ele publica Plugins externalizados no npm
|
||||
e no ClawHub antes de promover o pacote npm do OpenClaw
|
||||
7. Se a release caiu em `beta`, use o workflow privado
|
||||
7. Se o lançamento chegou a `beta`, use o workflow privado
|
||||
`openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`
|
||||
para promover essa versão estável de `beta` para `latest`
|
||||
8. Se a release foi publicada intencionalmente diretamente em `latest` e `beta`
|
||||
deve seguir a mesma build estável imediatamente, use o mesmo workflow privado
|
||||
8. Se o lançamento foi publicado intencionalmente diretamente em `latest` e `beta`
|
||||
deve seguir a mesma build estável imediatamente, use esse mesmo workflow privado
|
||||
para apontar ambas as dist-tags para a versão estável, ou deixe a sincronização
|
||||
agendada de autocorreção mover `beta` depois
|
||||
autorreparadora agendada mover `beta` depois
|
||||
|
||||
A mutação de dist-tag fica no repositório privado por segurança, porque ela ainda
|
||||
exige `NPM_TOKEN`, enquanto o repositório público mantém publicação somente com OIDC.
|
||||
A mutação de dist-tag fica no repositório privado por segurança, porque ainda
|
||||
exige `NPM_TOKEN`, enquanto o repositório público mantém publicação apenas com OIDC.
|
||||
|
||||
Isso mantém o caminho de publicação direta e o caminho de promoção beta primeiro
|
||||
Isso mantém tanto o caminho de publicação direta quanto o caminho de promoção beta primeiro
|
||||
documentados e visíveis ao operador.
|
||||
|
||||
Se um mantenedor precisar recorrer à autenticação npm local, execute quaisquer comandos da CLI
|
||||
do 1Password (`op`) somente dentro de uma sessão tmux dedicada. Não chame `op`
|
||||
diretamente a partir do shell principal do agente; mantê-lo dentro do tmux torna prompts,
|
||||
alertas e tratamento de OTP observáveis e evita alertas repetidos do host.
|
||||
do 1Password (`op`) apenas dentro de uma sessão tmux dedicada. Não chame `op`
|
||||
diretamente do shell principal do agente; mantê-lo dentro do tmux torna prompts,
|
||||
alertas e o manuseio de OTP observáveis e evita alertas repetidos no host.
|
||||
|
||||
## Referências públicas
|
||||
|
||||
@ -657,10 +597,10 @@ alertas e tratamento de OTP observáveis e evita alertas repetidos do host.
|
||||
- [`scripts/package-mac-dist.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-dist.sh)
|
||||
- [`scripts/make_appcast.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/make_appcast.sh)
|
||||
|
||||
Mantenedores usam a documentação privada de release em
|
||||
Mantenedores usam os documentos privados de lançamento em
|
||||
[`openclaw/maintainers/release/README.md`](https://github.com/openclaw/maintainers/blob/main/release/README.md)
|
||||
para o runbook real.
|
||||
|
||||
## Relacionado
|
||||
|
||||
- [Canais de release](/pt-BR/install/development-channels)
|
||||
- [Canais de lançamento](/pt-BR/install/development-channels)
|
||||
|
||||
@ -1,20 +1,20 @@
|
||||
---
|
||||
read_when:
|
||||
- Você quer operar o Gateway a partir de um navegador
|
||||
- Você deseja operar o Gateway a partir de um navegador
|
||||
- Você quer acesso à Tailnet sem túneis SSH
|
||||
sidebarTitle: Control UI
|
||||
summary: UI de controle baseada no navegador para o Gateway (chat, nós, configuração)
|
||||
summary: Interface de controle baseada no navegador para o Gateway (chat, nós, configuração)
|
||||
title: Interface de controle
|
||||
x-i18n:
|
||||
generated_at: "2026-05-04T05:56:07Z"
|
||||
generated_at: "2026-05-04T07:04:08Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 99a40ab77276fbc3180aefb103c2dd46804829c7b1b6966a8456ed35b85ed644
|
||||
source_hash: 07fbbe1c7fec5f67a04a231e02bdf0f7d16be9c5fe188915674d71fcd69002a5
|
||||
source_path: web/control-ui.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
A Interface de Controle é um pequeno aplicativo de página única **Vite + Lit** servido pelo Gateway:
|
||||
A UI de Controle é um pequeno app de página única **Vite + Lit** servido pelo Gateway:
|
||||
|
||||
- padrão: `http://<host>:18789/`
|
||||
- prefixo opcional: defina `gateway.controlUi.basePath` (por exemplo, `/openclaw`)
|
||||
@ -36,117 +36,117 @@ A autenticação é fornecida durante o handshake do WebSocket por meio de:
|
||||
- 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 atual da aba do navegador e a URL do gateway selecionada; senhas não são persistidas. A integração inicial normalmente 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"`.
|
||||
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"`.
|
||||
|
||||
## Pareamento de dispositivo (primeira conexão)
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
**O que você verá:** "desconectado (1008): pareamento necessário"
|
||||
**O que você verá:** "desconectado (1008): pareamento obrigatório"
|
||||
|
||||
<Steps>
|
||||
<Step title="Liste as solicitações pendentes">
|
||||
<Step title="Listar solicitações pendentes">
|
||||
```bash
|
||||
openclaw devices list
|
||||
```
|
||||
</Step>
|
||||
<Step title="Aprove pelo ID da solicitação">
|
||||
<Step title="Aprovar por ID da solicitação">
|
||||
```bash
|
||||
openclaw devices approve <requestId>
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
Se o navegador tentar novamente o pareamento 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 `openclaw devices list` novamente antes da aprovação.
|
||||
|
||||
Se o navegador já estiver pareado e você alterá-lo de acesso de leitura para acesso de escrita/administrador, 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/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.
|
||||
|
||||
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 etapa 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 à 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 único, portanto trocar de navegador ou limpar os dados do navegador exigirá novo pareamento.
|
||||
- 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.
|
||||
|
||||
</Note>
|
||||
|
||||
## Identidade pessoal (local do navegador)
|
||||
|
||||
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 da transcrição nas mensagens que você realmente envia. Limpar os dados do site ou trocar de navegador redefine essa identidade para vazia.
|
||||
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.
|
||||
|
||||
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 passam por ida e volta via `config.patch`. O campo de configuração compartilhado `ui.assistant.avatar` ainda está disponível para clientes não UI que escrevem o campo diretamente (como gateways com scripts 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 sejam de UI gravarem o campo diretamente (como gateways roteirizados ou dashboards personalizados).
|
||||
|
||||
## Endpoint de configuração de runtime
|
||||
## Endpoint de configuração em runtime
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
## Suporte a idiomas
|
||||
|
||||
A Interface de Controle pode se localizar automaticamente 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.
|
||||
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.
|
||||
|
||||
- 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 não ingleses são carregadas sob demanda no navegador.
|
||||
- Traduções para idiomas diferentes do 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 recorrem ao inglês.
|
||||
- Chaves de tradução ausentes usam inglês como fallback.
|
||||
|
||||
As traduções da documentação são geradas para o mesmo conjunto de localidades não inglesas, mas o seletor de idioma integrado do site de docs 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 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.
|
||||
|
||||
## 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 de 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`.
|
||||
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`.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
## O que ele pode fazer (hoje)
|
||||
## O que ela consegue fazer (hoje)
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Chat e Conversa">
|
||||
- Converse por chat com o modelo via WS do Gateway (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`).
|
||||
- Converse por sessões realtime do navegador. A OpenAI usa WebRTC direto, o Google Live usa um token de navegador limitado a um único uso via WebSocket, e plugins de voz realtime somente de backend usam o transporte de relay do Gateway. O relay 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.
|
||||
- Transmita chamadas de ferramentas + cartões de saída de ferramenta ao vivo no Chat (eventos de agente).
|
||||
<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.
|
||||
- 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 incluídos/externos, login por QR e configuração por canal (`channels.status`, `web.login.*`, `config.patch`).
|
||||
- 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`).
|
||||
- Instâncias: lista de presença + atualização (`system-presence`).
|
||||
- Sessões: lista + substituições por sessão de modelo/thinking/rápido/detalhado/rastreamento/raciocínio (`sessions.list`, `sessions.patch`).
|
||||
- Dreams: status de dreaming, alternância de 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/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`).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Cron, skills, nodes, aprovações de exec">
|
||||
- Tarefas Cron: listar/adicionar/editar/executar/ativar/desativar + histórico de execução (`cron.*`).
|
||||
<Accordion title="Cron, Skills, nodes, aprovações de exec">
|
||||
- Jobs de Cron: listar/adicionar/editar/executar/ativar/desativar + histórico de execuções (`cron.*`).
|
||||
- Skills: status, ativar/desativar, instalar, atualizações de chave de API (`skills.*`).
|
||||
- Nodes: lista + capacidades (`node.list`).
|
||||
- Aprovações de exec: editar allowlists de gateway ou node + política de solicitação para `exec host=gateway/node` (`exec.approvals.*`).
|
||||
- Aprovações de exec: editar allowlists do gateway ou node + 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 desperte a última sessão ativa.
|
||||
- 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 uma pré-verificaçã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.
|
||||
- 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 docs em nós aninhados de objeto/curinga/array/composição, 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 conseguir fazer ida e volta segura do texto bruto, a Interface de Controle força o modo Formulário e desativa o modo Bruto para esse snapshot.
|
||||
- O editor JSON bruto "Redefinir para salvo" preserva a forma escrita em 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 estruturados de objeto SecretRef são renderizados como somente leitura em entradas de texto de formulário para evitar corrupção acidental de objeto para string.
|
||||
- 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.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Depuração, logs, atualização">
|
||||
- Depuração: snapshots de status/health/modelos + log de eventos + chamadas RPC manuais (`status`, `health`, `models.list`).
|
||||
- Logs: tail ao vivo dos logs de arquivo do gateway com filtro/exportação (`logs.tail`).
|
||||
- Atualização: execute uma atualização de pacote/git + reinício (`update.run`) com um relatório de reinício e, em seguida, consulte `update.status` após a reconexão para verificar a versão do gateway em execução.
|
||||
- Depuração: snapshots de status/saúde/modelos + log de eventos + chamadas RPC manuais (`status`, `health`, `models.list`).
|
||||
- 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.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Observações do painel de tarefas Cron">
|
||||
- Para tarefas isoladas, a entrega usa anúncio de resumo por padrão. Você pode mudar para nenhuma se quiser execuções apenas internas.
|
||||
- Campos de canal/destino aparecem quando anúncio é selecionado.
|
||||
<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.
|
||||
- O modo Webhook usa `delivery.mode = "webhook"` com `delivery.to` definido como uma URL de webhook HTTP(S) válida.
|
||||
- Para tarefas da sessão principal, os modos de entrega webhook e nenhuma ficam disponíveis.
|
||||
- Controles avançados de edição incluem excluir após execução, limpar substituição de agente, opções cron exato/escalonado, 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 por campo; valores inválidos desativam o botão de salvar até serem corrigidos.
|
||||
- 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.
|
||||
- Defina `cron.webhookToken` para enviar um token bearer dedicado; se omitido, o webhook é enviado sem cabeçalho de autenticação.
|
||||
- Fallback obsoleto: tarefas legadas armazenadas com `notify: true` ainda podem usar `cron.webhook` até serem migradas.
|
||||
- Fallback obsoleto: jobs legados armazenados com `notify: true` ainda podem usar `cron.webhook` até serem migrados.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -155,62 +155,62 @@ 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 por eventos `chat`.
|
||||
- Uploads de chat aceitam imagens e arquivos que não sejam vídeo. Imagens mantêm o caminho nativo da imagem; outros arquivos são armazenados como mídia gerenciada e exibidos no histórico como links de anexo.
|
||||
- `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 as 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 geradas/pelo assistente 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 do chat.
|
||||
- `chat.history` também remove tags de diretivas 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 de controle de modelo ASCII/largura total 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 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 alcança o estado atual.
|
||||
- Eventos `chat` ao vivo representam 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 somente da UI (sem execução do agente, sem entrega de canal).
|
||||
- Os seletores de modelo e pensamento do cabeçalho do chat aplicam patches imediatamente na sessão ativa por meio de `sessions.patch`; eles são sobrescritas persistentes de sessão, não opções de envio válidas apenas para uma rodada.
|
||||
- Digitar `/new` na Control UI cria e alterna para a mesma sessão nova de dashboard que Novo 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 permanece disponível pelo RPC de depuração `models.list` com `view: "all"`.
|
||||
- Quando relatórios novos 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, em 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é o Gateway relatar uso novo novamente.
|
||||
- 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.
|
||||
- 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.
|
||||
|
||||
</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 Chamada de Voz 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 de uso único para uma sessão WebSocket do navegador, com instruções e declarações de ferramentas travadas no token pelo Gateway. Provedores que expõem apenas uma ponte em tempo real de backend passam pelo transporte de retransmissão do Gateway, então credenciais e sockets de fornecedores ficam 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 sobrescritas de instrução 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 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.
|
||||
|
||||
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`.
|
||||
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`.
|
||||
|
||||
Smoke ao vivo para mantenedores: `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 WebSocket do 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 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.
|
||||
|
||||
</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 **Orientar** em uma mensagem na fila para injetar esse acompanhamento na rodada em execução.
|
||||
- Digite `/stop` (ou frases independentes de aborto como `stop`, `stop action`, `stop run`, `stop openclaw`, `please stop`) para abortar fora de banda.
|
||||
- `chat.abort` oferece suporte a `{ 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 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.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Retenção parcial de aborto">
|
||||
- Quando uma execução é abortada, o texto parcial do assistente ainda pode ser mostrado na UI.
|
||||
<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 aborto para que consumidores da transcrição consigam distinguir parciais de aborto da saída de conclusão normal.
|
||||
- Entradas persistidas incluem metadados de abortamento para que consumidores da transcrição consigam distinguir parciais abortadas de saída de conclusão normal.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Instalação PWA e push web
|
||||
## Instalação 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 a 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 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.
|
||||
|
||||
| Superfície | O que faz |
|
||||
| Superfície | O que faz |
|
||||
| ----------------------------------------------------- | ------------------------------------------------------------------ |
|
||||
| `ui/public/manifest.webmanifest` | Manifesto PWA. Navegadores oferecem "Instalar app" quando ele fica acessível. |
|
||||
| `ui/public/sw.js` | Service worker que trata eventos `push` e cliques em notificações. |
|
||||
| `push/vapid-keys.json` (sob o diretório de estado do OpenClaw) | Par de chaves VAPID gerado automaticamente usado para assinar payloads Web Push. |
|
||||
| `push/web-push-subscriptions.json` | Endpoints persistidos de assinatura do navegador. |
|
||||
| `ui/public/manifest.webmanifest` | Manifesto 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. |
|
||||
|
||||
Sobrescreva o par de chaves VAPID por variáveis de ambiente no processo do Gateway quando quiser fixar chaves (para implantações multi-host, rotação de segredos ou testes):
|
||||
Substitua o par de chaves VAPID por variáveis de ambiente no processo do Gateway quando quiser fixar chaves (para implantações multi-host, rotação de segredos ou testes):
|
||||
|
||||
- `OPENCLAW_VAPID_PUBLIC_KEY`
|
||||
- `OPENCLAW_VAPID_PRIVATE_KEY`
|
||||
- `OPENCLAW_VAPID_SUBJECT` (padrão: `mailto:openclaw@localhost`)
|
||||
- `OPENCLAW_VAPID_SUBJECT` (o padrão é `mailto:openclaw@localhost`)
|
||||
|
||||
A Control UI usa estes métodos do Gateway com escopo limitado para registrar e testar assinaturas do navegador:
|
||||
A Control UI usa estes métodos do Gateway com escopo restrito para registrar e testar assinaturas do navegador:
|
||||
|
||||
- `push.web.vapidPublicKey` — busca a chave pública VAPID ativa.
|
||||
- `push.web.subscribe` — registra um `endpoint` mais `keys.p256dh`/`keys.auth`.
|
||||
@ -218,7 +218,7 @@ A Control UI usa estes métodos do Gateway com escopo limitado 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 apoiado por retransmissão) e do método `push.test` existente, que mira o pareamento móvel nativo.
|
||||
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.
|
||||
</Note>
|
||||
|
||||
## Embeds hospedados
|
||||
@ -227,13 +227,13 @@ Mensagens do assistente podem renderizar conteúdo web hospedado inline com o sh
|
||||
|
||||
<Tabs>
|
||||
<Tab title="strict">
|
||||
Desabilita a execução de scripts dentro de embeds hospedados.
|
||||
Desativa a execução de scripts dentro de embeds hospedados.
|
||||
</Tab>
|
||||
<Tab title="scripts (default)">
|
||||
Permite embeds interativos enquanto mantém isolamento de origem; este é o padrão e geralmente é suficiente para jogos/widgets de navegador autossuficientes.
|
||||
<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>
|
||||
<Tab title="trusted">
|
||||
Adiciona `allow-same-origin` além de `allow-scripts` para documentos do mesmo site que intencionalmente precisam de privilégios mais fortes.
|
||||
Adiciona `allow-same-origin` sobre `allow-scripts` para documentos do mesmo site que intencionalmente precisam de privilégios mais fortes.
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
@ -250,14 +250,14 @@ Exemplo:
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Use `trusted` somente quando o documento incorporado realmente precisar de comportamento de mesma origem. Para a maioria dos jogos gerados por agente e canvases interativos, `scripts` é a escolha mais segura.
|
||||
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.
|
||||
</Warning>
|
||||
|
||||
URLs externas absolutas 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`.
|
||||
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`.
|
||||
|
||||
## Largura da mensagem de chat
|
||||
|
||||
Mensagens de chat agrupadas usam uma largura máxima padrão legível. Implantações em monitores largos podem sobrescrevê-la sem corrigir o CSS empacotado definindo `gateway.controlUi.chatMessageMaxWidth`:
|
||||
Mensagens de chat agrupadas usam uma largura máxima padrão legível. Implantações em monitores largos podem substituí-la sem aplicar patch ao CSS empacotado definindo `gateway.controlUi.chatMessageMaxWidth`:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -269,13 +269,13 @@ Mensagens de chat agrupadas usam uma largura máxima padrão legível. Implanta
|
||||
}
|
||||
```
|
||||
|
||||
O valor é validado antes de chegar ao navegador. Valores com suporte incluem comprimentos simples e porcentagens 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 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(...)`.
|
||||
|
||||
## Acesso à tailnet (recomendado)
|
||||
## Acesso pela tailnet (recomendado)
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Tailscale Serve integrado (preferencial)">
|
||||
Mantenha o Gateway no loopback e deixe o Tailscale Serve fazer proxy dele com HTTPS:
|
||||
<Tab title="Tailscale Serve integrado (preferido)">
|
||||
Mantenha o Gateway em local loopback e deixe o Tailscale Serve fazer proxy dele com HTTPS:
|
||||
|
||||
```bash
|
||||
openclaw gateway --tailscale serve
|
||||
@ -285,12 +285,12 @@ O valor é validado antes de chegar ao navegador. Valores com suporte incluem co
|
||||
|
||||
- `https://<magicdns>/` (ou seu `gateway.controlUi.basePath` configurado)
|
||||
|
||||
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 só aceita essas solicitações quando elas chegam ao loopback com os cabeçalhos `x-forwarded-*` do Tailscale. Para sessões de operador da Control UI com identidade de dispositivo do navegador, esse caminho Serve verificado também pula a rodada 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. Então use `gateway.auth.mode: "token"` ou `"password"`.
|
||||
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"`.
|
||||
|
||||
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. Novas tentativas 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 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.
|
||||
|
||||
<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.
|
||||
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.
|
||||
</Warning>
|
||||
|
||||
</Tab>
|
||||
@ -299,7 +299,7 @@ O valor é validado antes de chegar ao navegador. Valores com suporte incluem co
|
||||
openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)"
|
||||
```
|
||||
|
||||
Então abra:
|
||||
Depois abra:
|
||||
|
||||
- `http://<tailscale-ip>:18789/` (ou seu `gateway.controlUi.basePath` configurado)
|
||||
|
||||
@ -310,13 +310,13 @@ O valor é validado antes de chegar ao navegador. Valores com suporte incluem co
|
||||
|
||||
## HTTP inseguro
|
||||
|
||||
Se você abrir o dashboard por HTTP simples (`http://<lan-ip>` ou `http://<tailscale-ip>`), o navegador executa 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 WebCrypto. Por padrão, o OpenClaw **bloqueia** conexões da Control UI sem identidade de dispositivo.
|
||||
|
||||
Exceções documentadas:
|
||||
|
||||
- compatibilidade HTTP insegura somente para localhost com `gateway.controlUi.allowInsecureAuth=true`
|
||||
- autenticação bem-sucedida da Control UI de operador por `gateway.auth.mode: "trusted-proxy"`
|
||||
- exceção de emergência `gateway.controlUi.dangerouslyDisableDeviceAuth=true`
|
||||
- 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`
|
||||
|
||||
**Correção recomendada:** use HTTPS (Tailscale Serve) ou abra a UI localmente:
|
||||
|
||||
@ -335,11 +335,11 @@ Exceções documentadas:
|
||||
}
|
||||
```
|
||||
|
||||
`allowInsecureAuth` é apenas uma alternância de compatibilidade local:
|
||||
`allowInsecureAuth` é apenas uma opção local de compatibilidade:
|
||||
|
||||
- Ela permite que sessões da Control UI no localhost prossigam sem identidade do dispositivo em contextos HTTP não seguros.
|
||||
- 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 do dispositivo remoto (não localhost).
|
||||
- Ela não relaxa os requisitos de identidade de dispositivo remoto (não localhost).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Break-glass only">
|
||||
@ -354,14 +354,14 @@ Exceções documentadas:
|
||||
```
|
||||
|
||||
<Warning>
|
||||
`dangerouslyDisableDeviceAuth` desativa as verificações de identidade do dispositivo da Control UI e é um rebaixamento 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 redução grave de segurança. Reverta rapidamente após o uso emergencial.
|
||||
</Warning>
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Trusted-proxy note">
|
||||
- Uma autenticação bem-sucedida de proxy confiável 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 nó.
|
||||
- Proxies reversos de loopback no mesmo host ainda não satisfazem a autenticação de proxy confiável; consulte [Autenticação de proxy confiável](/pt-BR/gateway/trusted-proxy-auth).
|
||||
- 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>
|
||||
</AccordionGroup>
|
||||
@ -370,26 +370,36 @@ 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 permitidos. URLs de imagem remotas `http(s)` e relativas ao protocolo são rejeitadas pelo navegador e não emitem buscas de rede.
|
||||
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.
|
||||
|
||||
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 inline `data:image/...` ainda são renderizadas (úteis para payloads no protocolo).
|
||||
- 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 de avatar remotas emitidas por metadados de canais são removidas pelos auxiliares de avatar da Control UI e substituídas pelo logotipo/distintivo integrado, para que um canal comprometido ou malicioso não consiga forçar buscas arbitrárias de imagens remotas a partir do navegador de um operador.
|
||||
- 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.
|
||||
|
||||
Você não precisa alterar nada para obter esse comportamento — ele está sempre ativo e não é configurável.
|
||||
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:
|
||||
|
||||
- `GET /avatar/<agentId>` retorna a imagem do avatar somente para chamadores autenticados. `GET /avatar/<agentId>?meta=1` retorna os metadados do avatar sob a mesma regra.
|
||||
- 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 de blob autenticadas para que a imagem ainda seja renderizada em painéis.
|
||||
- `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.
|
||||
|
||||
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, em linha com o restante do gateway.
|
||||
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.
|
||||
|
||||
## 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:
|
||||
|
||||
- `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.
|
||||
|
||||
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
|
||||
|
||||
@ -399,7 +409,7 @@ O Gateway serve arquivos estáticos de `dist/control-ui`. Compile-os com:
|
||||
pnpm ui:build
|
||||
```
|
||||
|
||||
Base absoluta opcional (quando você quiser URLs de ativos fixas):
|
||||
Base absoluta opcional (quando você quiser URLs fixas de ativos):
|
||||
|
||||
```bash
|
||||
OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build
|
||||
@ -411,11 +421,11 @@ Para desenvolvimento local (servidor de desenvolvimento separado):
|
||||
pnpm ui:dev
|
||||
```
|
||||
|
||||
Depois aponte a UI para a URL WS do seu Gateway (por exemplo, `ws://127.0.0.1:18789`).
|
||||
Em seguida, 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 é composta por arquivos estáticos; o destino do WebSocket é configurável e pode ser diferente da origem HTTP. Isso é útil quando você quer o servidor de desenvolvimento Vite localmente, mas o Gateway é executado em outro lugar.
|
||||
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.
|
||||
|
||||
<Steps>
|
||||
<Step title="Start the UI dev server">
|
||||
@ -439,17 +449,17 @@ A Control UI é composta por arquivos estáticos; o destino do WebSocket é conf
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Notes">
|
||||
- `gatewayUrl` é armazenado no localStorage após o carregamento e removido da URL.
|
||||
- Se você passar um endpoint `ws://` ou `wss://` completo via `gatewayUrl`, codifique o valor de `gatewayUrl` para URL 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 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 o bootstrap.
|
||||
- `password` é mantido apenas na memória.
|
||||
- Quando `gatewayUrl` está definido, a UI não faz fallback para credenciais de configuração ou ambiente. Forneça `token` (ou `password`) explicitamente. A falta de credenciais explícitas é um erro.
|
||||
- `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.
|
||||
- `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 da Control UI que não sejam de loopback devem definir `gateway.controlUi.allowedOrigins` explicitamente (origens completas). Isso inclui configurações de desenvolvimento remotas.
|
||||
- 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 navegadores remotos 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 ao host que eu estiver usando."
|
||||
- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` habilita o modo de fallback de origem pelo 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 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.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -470,7 +480,7 @@ Detalhes de configuração de acesso remoto: [Acesso remoto](/pt-BR/gateway/remo
|
||||
|
||||
## Relacionados
|
||||
|
||||
- [Painel](/pt-BR/web/dashboard) — painel do gateway
|
||||
- [Verificações de integridade](/pt-BR/gateway/health) — monitoramento de integridade do gateway
|
||||
- [Dashboard](/pt-BR/web/dashboard) — dashboard do gateway
|
||||
- [Health Checks](/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