chore(i18n): refresh pt-BR translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
09ea5ae117
commit
083da599d5
File diff suppressed because it is too large
Load Diff
@ -4,26 +4,26 @@ read_when:
|
||||
summary: Configuração do Slack e comportamento em tempo de execução (Socket Mode + URLs de solicitação HTTP)
|
||||
title: Slack
|
||||
x-i18n:
|
||||
generated_at: "2026-04-21T13:35:14Z"
|
||||
generated_at: "2026-04-21T17:45:34Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 2fe3c3c344e1c20c09b29773f4f68d2790751e76d8bbaa3c6157e3ff75978acf
|
||||
source_hash: f30b372a3ae10b7b649532181306e42792aca76b41422516e9633eb79f73f009
|
||||
source_path: channels/slack.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Slack
|
||||
|
||||
Status: pronto para produção para mensagens diretas + canais via integrações de app do Slack. O modo padrão é Socket Mode; URLs de solicitação HTTP também são compatíveis.
|
||||
Status: pronto para produção para DMs + canais via integrações de app do Slack. O modo padrão é Socket Mode; URLs de solicitação HTTP também são compatíveis.
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Pareamento" icon="link" href="/pt-BR/channels/pairing">
|
||||
As mensagens diretas do Slack usam o modo de pareamento por padrão.
|
||||
As DMs do Slack usam o modo de pareamento por padrão.
|
||||
</Card>
|
||||
<Card title="Comandos de barra" icon="terminal" href="/pt-BR/tools/slash-commands">
|
||||
Comportamento nativo de comandos e catálogo de comandos.
|
||||
</Card>
|
||||
<Card title="Solução de problemas de canal" 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 guias de correção.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@ -33,16 +33,16 @@ Status: pronto para produção para mensagens diretas + canais via integrações
|
||||
<Tabs>
|
||||
<Tab title="Socket Mode (padrão)">
|
||||
<Steps>
|
||||
<Step title="Crie um novo app do Slack">
|
||||
<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 o seu app
|
||||
- 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
|
||||
</Step>
|
||||
|
||||
<Step title="Configure o OpenClaw">
|
||||
<Step title="Configurar o OpenClaw">
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -66,7 +66,7 @@ SLACK_BOT_TOKEN=xoxb-...
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Inicie o Gateway">
|
||||
<Step title="Iniciar o Gateway">
|
||||
|
||||
```bash
|
||||
openclaw gateway
|
||||
@ -79,17 +79,17 @@ openclaw gateway
|
||||
|
||||
<Tab title="URLs de solicitação HTTP">
|
||||
<Steps>
|
||||
<Step title="Crie um novo app do Slack">
|
||||
<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 o seu app
|
||||
- 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
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Configure o OpenClaw">
|
||||
<Step title="Configurar o OpenClaw">
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -106,14 +106,14 @@ openclaw gateway
|
||||
```
|
||||
|
||||
<Note>
|
||||
Use caminhos de webhook exclusivos para HTTP com várias contas
|
||||
Use caminhos de Webhook exclusivos para HTTP com múltiplas contas
|
||||
|
||||
Dê a cada conta um `webhookPath` distinto (o padrão é `/slack/events`) para que os registros não entrem em conflito.
|
||||
Dê a cada conta um `webhookPath` distinto (padrão `/slack/events`) para que os registros não entrem em conflito.
|
||||
</Note>
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Inicie o Gateway">
|
||||
<Step title="Iniciar o Gateway">
|
||||
|
||||
```bash
|
||||
openclaw gateway
|
||||
@ -291,12 +291,12 @@ openclaw gateway
|
||||
|
||||
### Configurações adicionais do manifesto
|
||||
|
||||
Exponha diferentes recursos que estendem os padrões acima.
|
||||
Exiba diferentes recursos que ampliam os padrões acima.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Comandos de barra nativos opcionais">
|
||||
|
||||
Vários [comandos de barra nativos](#commands-and-slash-behavior) podem ser usados em vez de um único comando configurado, com algumas nuances:
|
||||
Vários [comandos de barra nativos](#commands-and-slash-behavior) podem ser usados no lugar de um único comando configurado, com algumas nuances:
|
||||
|
||||
- Use `/agentstatus` em vez de `/status`, porque o comando `/status` é reservado.
|
||||
- Não é possível disponibilizar mais de 25 comandos de barra ao mesmo tempo.
|
||||
@ -328,12 +328,12 @@ Exponha diferentes recursos que estendem os padrões acima.
|
||||
},
|
||||
{
|
||||
"command": "/session",
|
||||
"description": "Gerenciar a expiração da vinculação à thread",
|
||||
"usage_hint": "idle <duration|off> or max-age <duration|off>"
|
||||
"description": "Gerenciar a expiração da vinculação da thread",
|
||||
"usage_hint": "idle <duration|off> ou max-age <duration|off>"
|
||||
},
|
||||
{
|
||||
"command": "/think",
|
||||
"description": "Definir o nível de pensamento",
|
||||
"description": "Definir o nível de raciocínio",
|
||||
"usage_hint": "<level>"
|
||||
},
|
||||
{
|
||||
@ -358,7 +358,7 @@ Exponha diferentes recursos que estendem os padrões acima.
|
||||
},
|
||||
{
|
||||
"command": "/exec",
|
||||
"description": "Mostrar ou definir padrões de exec",
|
||||
"description": "Mostrar ou definir os padrões de execução",
|
||||
"usage_hint": "host=<auto|sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>"
|
||||
},
|
||||
{
|
||||
@ -386,7 +386,7 @@ Exponha diferentes recursos que estendem os padrões acima.
|
||||
},
|
||||
{
|
||||
"command": "/agentstatus",
|
||||
"description": "Mostrar o status em tempo de execução, incluindo uso/cota do provedor quando disponível"
|
||||
"description": "Mostrar o status de tempo de execução, incluindo uso/cota do provedor quando disponível"
|
||||
},
|
||||
{
|
||||
"command": "/tasks",
|
||||
@ -448,13 +448,13 @@ Exponha diferentes recursos que estendem os padrões acima.
|
||||
},
|
||||
{
|
||||
"command": "/session",
|
||||
"description": "Gerenciar a expiração da vinculação à thread",
|
||||
"usage_hint": "idle <duration|off> or max-age <duration|off>",
|
||||
"description": "Gerenciar a expiração da vinculação da thread",
|
||||
"usage_hint": "idle <duration|off> ou max-age <duration|off>",
|
||||
"url": "https://gateway-host.example.com/slack/events"
|
||||
},
|
||||
{
|
||||
"command": "/think",
|
||||
"description": "Definir o nível de pensamento",
|
||||
"description": "Definir o nível de raciocínio",
|
||||
"usage_hint": "<level>",
|
||||
"url": "https://gateway-host.example.com/slack/events"
|
||||
},
|
||||
@ -484,7 +484,7 @@ Exponha diferentes recursos que estendem os padrões acima.
|
||||
},
|
||||
{
|
||||
"command": "/exec",
|
||||
"description": "Mostrar ou definir padrões de exec",
|
||||
"description": "Mostrar ou definir os padrões de execução",
|
||||
"usage_hint": "host=<auto|sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>",
|
||||
"url": "https://gateway-host.example.com/slack/events"
|
||||
},
|
||||
@ -518,7 +518,7 @@ Exponha diferentes recursos que estendem os padrões acima.
|
||||
},
|
||||
{
|
||||
"command": "/agentstatus",
|
||||
"description": "Mostrar o status em tempo de execução, incluindo uso/cota do provedor quando disponível",
|
||||
"description": "Mostrar o status de tempo de execução, incluindo uso/cota do provedor quando disponível",
|
||||
"url": "https://gateway-host.example.com/slack/events"
|
||||
},
|
||||
{
|
||||
@ -562,10 +562,10 @@ Exponha diferentes recursos que estendem os padrões acima.
|
||||
</Tabs>
|
||||
|
||||
</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 do Slack.
|
||||
<Accordion title="Escopos opcionais de autoria (operações de gravação)">
|
||||
Adicione o escopo 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 do Slack.
|
||||
|
||||
Se você usar um ícone de emoji, o Slack espera a sintaxe `:emoji_name:`.
|
||||
Se você usar um ícone de emoji, o Slack espera a sintaxe `:nome_do_emoji:`.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Escopos opcionais de token de usuário (operações de leitura)">
|
||||
@ -586,47 +586,47 @@ Exponha diferentes recursos que estendem os padrões acima.
|
||||
|
||||
- `botToken` + `appToken` são obrigatórios para Socket Mode.
|
||||
- O modo HTTP exige `botToken` + `signingSecret`.
|
||||
- `botToken`, `appToken`, `signingSecret` e `userToken` aceitam strings em texto simples
|
||||
ou objetos SecretRef.
|
||||
- Tokens de configuração substituem o fallback por variável de ambiente.
|
||||
- `botToken`, `appToken`, `signingSecret` e `userToken` aceitam strings
|
||||
em texto simples ou objetos SecretRef.
|
||||
- Os tokens de configuração substituem o fallback por variável de ambiente.
|
||||
- O fallback por variável de ambiente `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` se aplica apenas à conta padrão.
|
||||
- `userToken` (`xoxp-...`) é apenas de configuração (sem fallback por variável de ambiente) e usa comportamento somente leitura por padrão (`userTokenReadOnly: true`).
|
||||
- `userToken` (`xoxp-...`) é somente de configuração (sem fallback por variável de ambiente) e usa comportamento somente leitura por padrão (`userTokenReadOnly: true`).
|
||||
|
||||
Comportamento do snapshot de status:
|
||||
|
||||
- A inspeção da conta do Slack rastreia campos `*Source` e `*Status` por credencial
|
||||
(`botToken`, `appToken`, `signingSecret`, `userToken`).
|
||||
- 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 fonte de segredo não inline, mas o caminho atual de comando/tempo de execução
|
||||
não conseguiu resolver o valor real.
|
||||
- No modo HTTP, `signingSecretStatus` é incluído; em Socket Mode, o
|
||||
par obrigatório é `botTokenStatus` + `appTokenStatus`.
|
||||
- No modo HTTP, `signingSecretStatus` é incluído; em 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 não está disponível.
|
||||
Para ações/leituras de diretório, o token de usuário pode ser preferido quando configurado. Para gravações, o token de bot continua sendo preferido; gravações com token de usuário só são permitidas quando `userTokenReadOnly: false` e o token de bot não está disponível.
|
||||
</Tip>
|
||||
|
||||
## Ações e gates
|
||||
## Ações e controles
|
||||
|
||||
As ações do Slack são controladas por `channels.slack.actions.*`.
|
||||
|
||||
Grupos de ações disponíveis nas ferramentas atuais do Slack:
|
||||
|
||||
| Grupo | Padrão |
|
||||
| ---------- | -------- |
|
||||
| messages | habilitado |
|
||||
| reactions | habilitado |
|
||||
| pins | habilitado |
|
||||
| memberInfo | habilitado |
|
||||
| emojiList | habilitado |
|
||||
| Group | Default |
|
||||
| ---------- | ------- |
|
||||
| messages | enabled |
|
||||
| reactions | enabled |
|
||||
| pins | enabled |
|
||||
| memberInfo | enabled |
|
||||
| emojiList | enabled |
|
||||
|
||||
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`.
|
||||
|
||||
## Controle de acesso e roteamento
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Política de DM">
|
||||
<Tab title="Política de DMs">
|
||||
`channels.slack.dmPolicy` controla o acesso por DM (legado: `channels.slack.dm.policy`):
|
||||
|
||||
- `pairing` (padrão)
|
||||
@ -634,15 +634,15 @@ As ações atuais de mensagem do Slack incluem `send`, `upload-file`, `download-
|
||||
- `open` (exige que `channels.slack.allowFrom` inclua `"*"`; legado: `channels.slack.dm.allowFrom`)
|
||||
- `disabled`
|
||||
|
||||
Sinalizadores de DM:
|
||||
Flags de DM:
|
||||
|
||||
- `dm.enabled` (padrão true)
|
||||
- `channels.slack.allowFrom` (preferido)
|
||||
- `dm.allowFrom` (legado)
|
||||
- `dm.groupEnabled` (DMs em grupo com padrão false)
|
||||
- `dm.groupChannels` (allowlist MPIM opcional)
|
||||
- `dm.groupChannels` (allowlist opcional de MPIM)
|
||||
|
||||
Precedência de várias contas:
|
||||
Precedência em múltiplas 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.
|
||||
@ -652,7 +652,7 @@ As ações atuais de mensagem do Slack incluem `send`, `upload-file`, `download-
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Política de canal">
|
||||
<Tab title="Política de canais">
|
||||
`channels.slack.groupPolicy` controla o tratamento de canais:
|
||||
|
||||
- `open`
|
||||
@ -661,18 +661,18 @@ As ações atuais de mensagem do Slack incluem `send`, `upload-file`, `download-
|
||||
|
||||
A allowlist de canais fica em `channels.slack.channels` e deve usar IDs de canal estáveis.
|
||||
|
||||
Observação de tempo de execução: se `channels.slack` estiver completamente ausente (configuração somente por env), o tempo de execução volta para `groupPolicy="allowlist"` e registra um aviso (mesmo que `channels.defaults.groupPolicy` esteja definido).
|
||||
Observação de tempo de execução: se `channels.slack` estiver completamente ausente (configuração somente por env), o tempo de execução usa `groupPolicy="allowlist"` como fallback e registra um aviso (mesmo que `channels.defaults.groupPolicy` esteja definido).
|
||||
|
||||
Resolução de nome/ID:
|
||||
|
||||
- entradas da allowlist de canais e da allowlist de DM são resolvidas na inicialização quando o acesso do token permite
|
||||
- entradas não resolvidas por nome de canal são mantidas conforme configuradas, mas ignoradas para roteamento por padrão
|
||||
- a autorização de entrada e o roteamento de canal usam ID primeiro por padrão; correspondência direta por nome de usuário/slug exige `channels.slack.dangerouslyAllowNameMatching: true`
|
||||
- entradas da allowlist de canais e da allowlist de DMs são resolvidas na inicialização quando o acesso ao token permite
|
||||
- entradas não resolvidas de nome de canal são mantidas como configuradas, mas ignoradas para roteamento por padrão
|
||||
- a autorização de entrada e o roteamento de canais usam IDs primeiro por padrão; correspondência direta por nome de usuário/slug exige `channels.slack.dangerouslyAllowNameMatching: true`
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Menções e usuários do canal">
|
||||
Mensagens de canal são bloqueadas por menção por padrão.
|
||||
As mensagens de canal são bloqueadas por menção por padrão.
|
||||
|
||||
Fontes de menção:
|
||||
|
||||
@ -688,8 +688,8 @@ As ações atuais de mensagem do Slack incluem `send`, `upload-file`, `download-
|
||||
- `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 são mapeadas apenas para `id:`)
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
@ -697,14 +697,14 @@ As ações atuais de mensagem do Slack incluem `send`, `upload-file`, `download-
|
||||
## Threads, sessões e tags de resposta
|
||||
|
||||
- DMs são roteadas como `direct`; canais como `channel`; MPIMs como `group`.
|
||||
- Com o padrão `session.dmScope=main`, DMs do Slack são agrupadas na sessão principal do agente.
|
||||
- Com o padrão `session.dmScope=main`, as DMs do Slack colapsam para a 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 existentes da thread são buscadas quando uma nova sessão de thread começa (padrão `20`; defina `0` para desabilitar).
|
||||
- `channels.slack.thread.requireExplicitMention` (padrão `false`): quando `true`, suprime menções implícitas em thread para que o bot responda apenas 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 bloqueio de `requireMention`.
|
||||
- `channels.slack.thread.initialHistoryLimit` controla quantas mensagens existentes da thread são buscadas quando uma nova sessão de thread é iniciada (padrão `20`; defina `0` para desabilitar).
|
||||
- `channels.slack.thread.requireExplicitMention` (padrão `false`): quando `true`, suprime menções implícitas em thread para que o bot responda apenas 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 `requireMention`.
|
||||
|
||||
Controles de encadeamento de resposta:
|
||||
Controles de encadeamento de respostas:
|
||||
|
||||
- `channels.slack.replyToMode`: `off|first|all|batched` (padrão `off`)
|
||||
- `channels.slack.replyToModeByChatType`: por `direct|group|channel`
|
||||
@ -715,22 +715,22 @@ Tags manuais de resposta são compatíveis:
|
||||
- `[[reply_to_current]]`
|
||||
- `[[reply_to:<id>]]`
|
||||
|
||||
Observação: `replyToMode="off"` desabilita **todo** o encadeamento de respostas no Slack, incluindo tags explícitas `[[reply_to_*]]`. Isso difere do Telegram, onde tags explícitas ainda são respeitadas no modo `"off"`. A diferença reflete os modelos de thread da plataforma: threads do Slack ocultam mensagens do canal, enquanto respostas do Telegram permanecem visíveis no fluxo principal do chat.
|
||||
Observação: `replyToMode="off"` desabilita **todo** o encadeamento 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"`. A diferença reflete os modelos de threading das plataformas: threads do Slack ocultam mensagens do canal, enquanto respostas do Telegram permanecem visíveis no fluxo principal do chat.
|
||||
|
||||
## 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 para emoji de identidade do agente (`agents.list[].identity.emoji`, caso contrário `"👀"`)
|
||||
- fallback para o emoji da identidade do agente (`agents.list[].identity.emoji`, caso contrário "👀")
|
||||
|
||||
Observações:
|
||||
|
||||
- O Slack espera shortcodes (por exemplo `"eyes"`).
|
||||
- O Slack espera shortcodes (por exemplo, `"eyes"`).
|
||||
- Use `""` para desabilitar a reação para a conta do Slack ou globalmente.
|
||||
|
||||
## Streaming de texto
|
||||
@ -740,17 +740,18 @@ Observações:
|
||||
- `off`: desabilita o streaming de visualização ao vivo.
|
||||
- `partial` (padrão): substitui o texto de visualização pela saída parcial mais recente.
|
||||
- `block`: acrescenta atualizações de visualização em blocos.
|
||||
- `progress`: mostra o texto de status do progresso enquanto gera e, em seguida, envia o texto final.
|
||||
- `progress`: mostra texto de status de progresso durante a geração e, em seguida, envia o texto final.
|
||||
- `streaming.preview.toolProgress`: quando a visualização de rascunho está ativa, encaminha atualizações de ferramenta/progresso para a mesma mensagem de visualização editada (padrão: `true`). Defina como `false` para manter mensagens separadas de ferramenta/progresso.
|
||||
|
||||
`channels.slack.streaming.nativeTransport` controla o streaming de texto nativo do Slack quando `channels.slack.streaming.mode` é `partial` (padrão: `true`).
|
||||
`channels.slack.streaming.nativeTransport` controla o streaming nativo de texto 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 do assistente do Slack apareçam. A seleção de thread ainda segue `replyToMode`.
|
||||
- Uma thread de resposta deve estar disponível para que o streaming nativo de texto e o status de thread do assistente do Slack apareçam. A seleção da thread ainda segue `replyToMode`.
|
||||
- Raízes de canais e chats em grupo ainda podem usar a visualização normal de rascunho quando o streaming nativo não estiver disponível.
|
||||
- DMs de nível superior no Slack permanecem fora de thread por padrão, então não mostram a visualização no estilo de thread; use respostas em thread ou `typingReaction` se quiser progresso visível ali.
|
||||
- Mídia e cargas não textuais voltam para a entrega normal.
|
||||
- Se o streaming falhar no meio da resposta, o OpenClaw volta para a entrega normal para as cargas restantes.
|
||||
- DMs de nível superior no Slack permanecem fora de thread por padrão, então não mostram a visualização no estilo de thread; use respostas em thread ou `typingReaction` se quiser progresso visível nelas.
|
||||
- Mídia e cargas não textuais usam a entrega normal como fallback.
|
||||
- Se o streaming falhar no meio da resposta, o OpenClaw usa a entrega normal como fallback para as cargas restantes.
|
||||
|
||||
Use a visualização de rascunho em vez do streaming de texto nativo do Slack:
|
||||
Use a visualização de rascunho em vez do streaming nativo de texto do Slack:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -773,7 +774,7 @@ Chaves legadas:
|
||||
|
||||
## Fallback de reação de digitação
|
||||
|
||||
`typingReaction` adiciona uma reação temporária à mensagem recebida no 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 padrão de status "is typing...".
|
||||
`typingReaction` adiciona uma reação temporária à mensagem recebida no 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 "is typing...".
|
||||
|
||||
Ordem de resolução:
|
||||
|
||||
@ -782,24 +783,24 @@ Ordem de resolução:
|
||||
|
||||
Observações:
|
||||
|
||||
- O Slack espera shortcodes (por exemplo `"hourglass_flowing_sand"`).
|
||||
- A reação é best-effort, e a limpeza é tentada automaticamente depois que a resposta ou o caminho de falha é concluído.
|
||||
- O Slack espera shortcodes (por exemplo, `"hourglass_flowing_sand"`).
|
||||
- A reação é best-effort 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="Anexos recebidos">
|
||||
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 é bem-sucedida e os limites de tamanho permitem.
|
||||
Os anexos de arquivo 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.
|
||||
|
||||
O limite padrão de tamanho de entrada em tempo de execução é `20MB`, a menos que seja substituído por `channels.slack.mediaMaxMb`.
|
||||
O limite de tamanho de entrada em tempo de execução é `20MB` por padrão, a menos que seja substituído por `channels.slack.mediaMaxMb`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Texto e arquivos enviados">
|
||||
<Accordion title="Texto e arquivos de saída">
|
||||
- blocos de texto usam `channels.slack.textChunkLimit` (padrão 4000)
|
||||
- `channels.slack.chunkMode="newline"` habilita divisão priorizando parágrafos
|
||||
- envios de arquivo 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, envios do canal usam os padrões de tipo MIME do pipeline de mídia
|
||||
- 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="Destinos de entrega">
|
||||
@ -808,14 +809,14 @@ Observações:
|
||||
- `user:<id>` para DMs
|
||||
- `channel:<id>` para canais
|
||||
|
||||
DMs do Slack são abertas por meio das APIs de conversa do Slack ao enviar para destinos de usuário.
|
||||
As DMs do Slack são abertas via APIs de conversa do Slack ao enviar para destinos de usuário.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Comandos e comportamento de slash
|
||||
|
||||
Os comandos de barra aparecem no Slack como um único comando configurado ou vários comandos nativos. Configure `channels.slack.slashCommand` para alterar os padrões do comando:
|
||||
Os comandos de barra 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"`
|
||||
@ -828,28 +829,28 @@ Os comandos de barra aparecem no Slack como um único comando configurado ou vá
|
||||
|
||||
Os comandos nativos exigem [configurações adicionais do manifesto](#additional-manifest-settings) no seu app do Slack e são habilitados com `channels.slack.commands.native: true` ou `commands.native: true` nas configurações globais.
|
||||
|
||||
- O modo automático de comandos nativos fica **desligado** para Slack, então `commands.native: "auto"` não habilita comandos nativos do Slack.
|
||||
- O modo automático de comandos nativos é **off** para Slack, então `commands.native: "auto"` não habilita comandos nativos do Slack.
|
||||
|
||||
```txt
|
||||
/help
|
||||
```
|
||||
|
||||
Os menus nativos de argumentos usam uma estratégia de renderização adaptativa que mostra um modal de confirmação antes de despachar um valor de opção selecionado:
|
||||
Os menus nativos de argumentos usam uma estratégia de renderização adaptativa que mostra um modal de confirmação antes de despachar o valor de uma opção selecionada:
|
||||
|
||||
- até 5 opções: blocos de botões
|
||||
- 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 manipuladores de opções de interatividade estão disponíveis
|
||||
- limites do Slack excedidos: valores de opção codificados voltam para botões
|
||||
- até 5 opções: blocos de botão
|
||||
- 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 os manipuladores de opções de interatividade estão disponíveis
|
||||
- limites do Slack excedidos: valores de opção codificados usam botões como fallback
|
||||
|
||||
```txt
|
||||
/think
|
||||
```
|
||||
|
||||
As sessões de 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`.
|
||||
As sessões de slash usam chaves isoladas como `agent:<agentId>:slack:slash:<userId>` e ainda roteiam execuções de comandos para a sessão de conversa de destino usando `CommandTargetSessionKey`.
|
||||
|
||||
## Respostas interativas
|
||||
|
||||
O Slack pode renderizar controles de resposta interativa criados pelo agente, mas esse recurso fica desabilitado por padrão.
|
||||
O Slack pode renderizar controles interativos de resposta criados pelo agente, mas esse recurso está desabilitado por padrão.
|
||||
|
||||
Habilite globalmente:
|
||||
|
||||
@ -865,7 +866,7 @@ Habilite globalmente:
|
||||
}
|
||||
```
|
||||
|
||||
Ou habilite apenas para uma conta do Slack:
|
||||
Ou habilite para apenas uma conta do Slack:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -883,42 +884,42 @@ Ou habilite apenas 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 em Slack Block Kit e roteiam cliques ou seleções de volta pelo caminho existente de eventos de interação do Slack.
|
||||
Essas diretivas são compiladas em Slack Block Kit e encaminham cliques ou seleções de volta pelo caminho existente de eventos de interação do Slack.
|
||||
|
||||
Observações:
|
||||
|
||||
- Esta é uma UI específica do Slack. Outros canais não traduzem diretivas de Slack Block Kit para seus próprios sistemas de botõ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 volta para a 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 usa a resposta de texto original como fallback em vez de enviar uma carga de blocos inválida.
|
||||
|
||||
## Aprovações de exec no Slack
|
||||
|
||||
O Slack pode atuar como um cliente nativo de aprovação com botões e interações interativas, em vez de voltar para a Web UI ou o terminal.
|
||||
O Slack pode atuar como um cliente nativo de aprovação com botões interativos e interações, em vez de usar a Web UI ou o terminal como fallback.
|
||||
|
||||
- Aprovações de exec usam `channels.slack.execApprovals.*` para roteamento nativo em DM/canal.
|
||||
- Aprovações de Plugin ainda podem ser resolvidas pela mesma superfície nativa de botões do Slack quando a solicitação já chega ao Slack e o tipo de id de aprovação é `plugin:`.
|
||||
- As aprovações de exec usam `channels.slack.execApprovals.*` para roteamento nativo de DM/canal.
|
||||
- As aprovações de Plugin ainda podem ser resolvidas pela mesma superfície nativa de botões do Slack quando a solicitação já chega ao Slack e o tipo do ID de aprovação é `plugin:`.
|
||||
- A autorização do aprovador continua sendo aplicada: apenas 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 que outros canais. Quando `interactivity` está habilitado nas configurações do seu app do Slack, os prompts de aprovação são renderizados como botões 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 app do Slack, os 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
|
||||
deve incluir um comando manual `/approve` apenas quando o resultado da ferramenta disser que aprovações por chat
|
||||
não estão disponíveis ou que a aprovação manual é o único caminho.
|
||||
deve incluir um comando manual `/approve` apenas quando o resultado da ferramenta disser que as
|
||||
aprovações por chat não estão disponíveis ou que a aprovação manual é o único caminho.
|
||||
|
||||
Caminho de configuração:
|
||||
|
||||
- `channels.slack.execApprovals.enabled`
|
||||
- `channels.slack.execApprovals.approvers` (opcional; usa fallback para `commands.ownerAllowFrom` quando possível)
|
||||
- `channels.slack.execApprovals.approvers` (opcional; usa `commands.ownerAllowFrom` como fallback quando possível)
|
||||
- `channels.slack.execApprovals.target` (`dm` | `channel` | `both`, padrão: `dm`)
|
||||
- `agentFilter`, `sessionFilter`
|
||||
|
||||
O Slack habilita automaticamente aprovações nativas de exec quando `enabled` não está definido ou é `"auto"` e pelo menos um
|
||||
aprovador é resolvido. Defina `enabled: false` para desabilitar explicitamente o Slack como cliente nativo de aprovação.
|
||||
Defina `enabled: true` para forçar aprovações nativas quando aprovadores forem resolvidos.
|
||||
Defina `enabled: true` para forçar aprovações nativas quando os aprovadores forem resolvidos.
|
||||
|
||||
Comportamento padrão sem configuração explícita de aprovação de exec no Slack:
|
||||
|
||||
@ -930,7 +931,7 @@ Comportamento padrão sem configuração explícita de aprovação de exec no Sl
|
||||
}
|
||||
```
|
||||
|
||||
A configuração nativa explícita do Slack só é necessária quando você quer substituir aprovadores, adicionar filtros ou
|
||||
A configuração nativa explícita do Slack só é necessária quando você quiser substituir aprovadores, adicionar filtros ou
|
||||
optar pela entrega no chat de origem:
|
||||
|
||||
```json5
|
||||
@ -947,45 +948,45 @@ optar pela entrega no chat de origem:
|
||||
}
|
||||
```
|
||||
|
||||
O encaminhamento compartilhado `approvals.exec` é separado. Use-o apenas quando prompts de aprovação de exec também precisarem
|
||||
ser roteados para outros chats ou destinos explícitos fora de banda. O encaminhamento compartilhado `approvals.plugin` também é
|
||||
separado; botões nativos do Slack ainda podem resolver aprovações de Plugin quando essas solicitações já chegam
|
||||
O encaminhamento compartilhado `approvals.exec` é separado. Use-o apenas quando os prompts de aprovação de exec também precisarem
|
||||
ser encaminhados para outros chats ou destinos explícitos fora de banda. O encaminhamento compartilhado `approvals.plugin` também é
|
||||
separado; os botões nativos do Slack ainda podem resolver aprovações de Plugin quando essas solicitações já chegarem
|
||||
ao Slack.
|
||||
|
||||
`/approve` no mesmo chat também funciona em canais e DMs do Slack que já oferecem suporte a comandos. Consulte [Aprovações de exec](/pt-BR/tools/exec-approvals) para o modelo completo de encaminhamento de aprovações.
|
||||
O `/approve` no mesmo chat também funciona em canais e DMs do Slack que já oferecem suporte a comandos. Consulte [Aprovações de exec](/pt-BR/tools/exec-approvals) para o modelo completo de encaminhamento de aprovação.
|
||||
|
||||
## Eventos e comportamento operacional
|
||||
|
||||
- Edições/exclusões de mensagens e transmissões de thread são mapeadas para eventos de sistema.
|
||||
- Edições/exclusões de mensagens e transmissões em thread são mapeadas para eventos de sistema.
|
||||
- Eventos de adicionar/remover reação são mapeados para eventos de sistema.
|
||||
- Eventos de entrada/saída de membro, canal criado/renomeado e adicionar/remover pin são mapeados para eventos de sistema.
|
||||
- `channel_id_changed` pode migrar chaves de configuração do canal quando `configWrites` está habilitado.
|
||||
- Metadados de tópico/finalidade do canal são tratados como contexto não confiável e podem ser injetados no contexto de roteamento.
|
||||
- O iniciador da thread e o seed inicial de contexto do histórico da thread são filtrados pelas allowlists de remetente configuradas, quando aplicável.
|
||||
- Ações de bloco e interações de modal emitem eventos de sistema estruturados `Slack interaction: ...` com campos de payload ricos:
|
||||
- O iniciador da thread e a semeadura inicial do contexto do histórico da thread são filtrados pelas allowlists configuradas de remetente quando aplicável.
|
||||
- Ações de bloco e interações de modal emitem eventos de sistema estruturados `Slack interaction: ...` com campos ricos de carga:
|
||||
- ações de bloco: valores selecionados, rótulos, valores de seletor e metadados `workflow_*`
|
||||
- eventos de modal `view_submission` e `view_closed` com metadados de canal roteados e entradas de formulário
|
||||
|
||||
## Ponteiros para a referência de configuração
|
||||
## Ponteiros de referência de configuração
|
||||
|
||||
Referência principal:
|
||||
|
||||
- [Referência de configuração - Slack](/pt-BR/gateway/configuration-reference#slack)
|
||||
|
||||
Campos de Slack de alto sinal:
|
||||
Campos do Slack de alto sinal:
|
||||
- modo/auth: `mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*`
|
||||
- acesso por DM: `dm.enabled`, `dmPolicy`, `allowFrom` (legado: `dm.policy`, `dm.allowFrom`), `dm.groupEnabled`, `dm.groupChannels`
|
||||
- alternância de compatibilidade: `dangerouslyAllowNameMatching` (break-glass; mantenha desativado, a menos que seja necessário)
|
||||
- acesso de canal: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention`
|
||||
- acesso a canais: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention`
|
||||
- threading/histórico: `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit`
|
||||
- entrega: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `streaming.nativeTransport`
|
||||
- ops/recursos: `configWrites`, `commands.native`, `slashCommand.*`, `actions.*`, `userToken`, `userTokenReadOnly`
|
||||
- entrega: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `streaming.nativeTransport`, `streaming.preview.toolProgress`
|
||||
- operações/recursos: `configWrites`, `commands.native`, `slashCommand.*`, `actions.*`, `userToken`, `userTokenReadOnly`
|
||||
|
||||
## Solução de problemas
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Sem respostas nos canais">
|
||||
Verifique, nesta ordem:
|
||||
<Accordion title="Sem respostas em canais">
|
||||
Verifique, em ordem:
|
||||
|
||||
- `groupPolicy`
|
||||
- allowlist de canais (`channels.slack.channels`)
|
||||
@ -1021,7 +1022,7 @@ openclaw pairing list slack
|
||||
Se `openclaw channels status --probe --json` mostrar `botTokenStatus` ou
|
||||
`appTokenStatus: "configured_unavailable"`, a conta do Slack está
|
||||
configurada, mas o tempo de execução atual não conseguiu resolver o valor
|
||||
respaldado por SecretRef.
|
||||
apoiado por SecretRef.
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -1029,20 +1030,20 @@ openclaw pairing list slack
|
||||
Valide:
|
||||
|
||||
- signing secret
|
||||
- caminho do webhook
|
||||
- caminho do Webhook
|
||||
- URLs de solicitação do Slack (Eventos + Interatividade + Comandos de barra)
|
||||
- `webhookPath` exclusivo por conta HTTP
|
||||
|
||||
Se `signingSecretStatus: "configured_unavailable"` aparecer nos snapshots
|
||||
da conta, a conta HTTP está configurada, mas o tempo de execução atual não conseguiu
|
||||
resolver o signing secret respaldado por SecretRef.
|
||||
Se `signingSecretStatus: "configured_unavailable"` aparecer nos snapshots da
|
||||
conta, a conta HTTP está configurada, mas o tempo de execução atual não conseguiu
|
||||
resolver o signing secret apoiado por SecretRef.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Comandos nativos/slash não disparam">
|
||||
Verifique se a intenção era:
|
||||
<Accordion title="Comandos nativos/slash não são acionados">
|
||||
Verifique se sua intenção era:
|
||||
|
||||
- modo de comando nativo (`channels.slack.commands.native: true`) com comandos de barra correspondentes registrados no Slack
|
||||
- modo de comando nativo (`channels.slack.commands.native: true`) com os comandos de barra correspondentes registrados no Slack
|
||||
- ou modo de comando de barra único (`channels.slack.slashCommand.enabled: true`)
|
||||
|
||||
Verifique também `commands.useAccessGroups` e as allowlists de canal/usuário.
|
||||
@ -1055,7 +1056,7 @@ openclaw pairing list slack
|
||||
- [Pareamento](/pt-BR/channels/pairing)
|
||||
- [Grupos](/pt-BR/channels/groups)
|
||||
- [Segurança](/pt-BR/gateway/security)
|
||||
- [Roteamento de canal](/pt-BR/channels/channel-routing)
|
||||
- [Roteamento de canais](/pt-BR/channels/channel-routing)
|
||||
- [Solução de problemas](/pt-BR/channels/troubleshooting)
|
||||
- [Configuração](/pt-BR/gateway/configuration)
|
||||
- [Comandos de barra](/pt-BR/tools/slash-commands)
|
||||
|
||||
@ -1,20 +1,20 @@
|
||||
---
|
||||
read_when:
|
||||
- Trabalhando em recursos do Telegram ou Webhooks
|
||||
summary: Status do suporte ao bot do Telegram, capacidades e configuração
|
||||
summary: Status do suporte do bot do Telegram, capacidades e configuração
|
||||
title: Telegram
|
||||
x-i18n:
|
||||
generated_at: "2026-04-21T05:35:29Z"
|
||||
generated_at: "2026-04-21T17:45:32Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: b5c70775b55d4923a31ad8bae7f4c6e7cbae754c05c3a578180d63db2b59e39a
|
||||
source_hash: 816238b53942b319a300843db62ec1d4bf8d84bc11094010926ac9ad457c6d3d
|
||||
source_path: channels/telegram.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Telegram (Bot API)
|
||||
|
||||
Status: pronto para produção para DMs + grupos de bots via grammY. Long polling é o modo padrão; o modo Webhook é opcional.
|
||||
Status: pronto para produção para DMs de bot + grupos via grammY. O long polling é o modo padrão; o modo Webhook é opcional.
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Pareamento" icon="link" href="/pt-BR/channels/pairing">
|
||||
@ -53,8 +53,8 @@ Status: pronto para produção para DMs + grupos de bots via grammY. Long pollin
|
||||
}
|
||||
```
|
||||
|
||||
Fallback de ambiente: `TELEGRAM_BOT_TOKEN=...` (apenas conta padrão).
|
||||
O Telegram **não** usa `openclaw channels login telegram`; configure o token em config/env e, em seguida, inicie o Gateway.
|
||||
Fallback de variável de ambiente: `TELEGRAM_BOT_TOKEN=...` (apenas conta padrão).
|
||||
O Telegram **não** usa `openclaw channels login telegram`; configure o token em config/env e então inicie o Gateway.
|
||||
|
||||
</Step>
|
||||
|
||||
@ -71,39 +71,39 @@ openclaw pairing approve telegram <CODE>
|
||||
</Step>
|
||||
|
||||
<Step title="Adicionar o bot a um grupo">
|
||||
Adicione o bot ao seu grupo e, em seguida, defina `channels.telegram.groups` e `groupPolicy` para corresponder ao seu modelo de acesso.
|
||||
Adicione o bot ao seu grupo e então defina `channels.telegram.groups` e `groupPolicy` para corresponder ao seu modelo de acesso.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
A ordem de resolução do token considera a conta. Na prática, os valores da configuração têm prioridade sobre o fallback de ambiente, e `TELEGRAM_BOT_TOKEN` se aplica apenas à conta padrão.
|
||||
A ordem de resolução do token considera a conta. Na prática, os valores de config vencem o fallback de env, e `TELEGRAM_BOT_TOKEN` se aplica apenas à conta padrão.
|
||||
</Note>
|
||||
|
||||
## Configurações no lado do Telegram
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Modo de privacidade e visibilidade em grupos">
|
||||
Os bots do Telegram usam **Modo de Privacidade** por padrão, o que limita quais mensagens de grupo eles recebem.
|
||||
Bots do Telegram usam **Modo de Privacidade** por padrão, o que limita quais mensagens de grupo eles recebem.
|
||||
|
||||
Se o bot precisar ver todas as mensagens do grupo, faça um destes procedimentos:
|
||||
|
||||
- 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.
|
||||
Ao alternar o modo de privacidade, remova + adicione novamente o bot em cada grupo para que o Telegram aplique a mudança.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Permissões do grupo">
|
||||
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 do grupo no Telegram.
|
||||
|
||||
Bots administradores recebem todas as mensagens do grupo, o que é útil para comportamento contínuo em grupos.
|
||||
Bots administradores recebem todas as mensagens do grupo, o que é útil para comportamento sempre ativo em grupos.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Alternâncias úteis do BotFather">
|
||||
|
||||
- `/setjoingroups` para permitir/negar adições em grupos
|
||||
- `/setjoingroups` para permitir/negar adições a grupos
|
||||
- `/setprivacy` para o comportamento de visibilidade em grupos
|
||||
|
||||
</Accordion>
|
||||
@ -116,27 +116,27 @@ A ordem de resolução do token considera a conta. Na prática, os valores da co
|
||||
`channels.telegram.dmPolicy` controla o acesso a mensagens diretas:
|
||||
|
||||
- `pairing` (padrão)
|
||||
- `allowlist` (requer pelo menos um ID de remetente em `allowFrom`)
|
||||
- `open` (requer que `allowFrom` inclua `"*"`)
|
||||
- `allowlist` (exige pelo menos um ID de remetente em `allowFrom`)
|
||||
- `open` (exige que `allowFrom` inclua `"*"`)
|
||||
- `disabled`
|
||||
|
||||
`channels.telegram.allowFrom` aceita IDs numéricos de usuários do Telegram. Prefixos `telegram:` / `tg:` são aceitos e normalizados.
|
||||
`dmPolicy: "allowlist"` com `allowFrom` vazio bloqueia todas as DMs e é rejeitado pela validação de configuração.
|
||||
A configuração solicita apenas IDs numéricos de usuário.
|
||||
A configuração solicita apenas IDs numéricos de usuários.
|
||||
Se você atualizou e sua configuração contém entradas `@username` na allowlist, execute `openclaw doctor --fix` para resolvê-las (melhor esforço; requer um token de bot do Telegram).
|
||||
Se você dependia anteriormente de arquivos de allowlist do armazenamento de pareamento, `openclaw doctor --fix` pode recuperar entradas para `channels.telegram.allowFrom` em fluxos de allowlist (por exemplo, quando `dmPolicy: "allowlist"` ainda não tem IDs explícitos).
|
||||
Se você antes dependia de arquivos de allowlist do pairing-store, `openclaw doctor --fix` pode recuperar entradas em `channels.telegram.allowFrom` em fluxos de allowlist (por exemplo, quando `dmPolicy: "allowlist"` ainda não tem IDs explícitos).
|
||||
|
||||
Para bots com um único proprietário, prefira `dmPolicy: "allowlist"` com IDs numéricos explícitos em `allowFrom` para manter a política de acesso durável na configuração (em vez de depender de aprovações de pareamento anteriores).
|
||||
Para bots de um único dono, prefira `dmPolicy: "allowlist"` com IDs numéricos explícitos em `allowFrom` para manter a política de acesso persistente na configuração (em vez de depender de aprovações de pareamento anteriores).
|
||||
|
||||
Confusão comum: a aprovação de pareamento de DM não significa "este remetente está autorizado em todos os lugares".
|
||||
O pareamento concede acesso apenas a DM. A autorização de remetentes em grupos ainda vem de allowlists explícitas na configuração.
|
||||
Se você quiser "estou autorizado uma vez e tanto DMs quanto comandos em grupo funcionam", coloque seu ID numérico de usuário do Telegram em `channels.telegram.allowFrom`.
|
||||
Confusão comum: aprovar o pareamento de DM não significa "este remetente está autorizado em todos os lugares".
|
||||
O pareamento concede acesso apenas à DM. A autorização do remetente em grupos ainda vem de allowlists explícitas na configuração.
|
||||
Se você quiser "eu sou autorizado uma vez e tanto DMs quanto comandos em grupo funcionam", coloque seu ID numérico de usuário do Telegram em `channels.telegram.allowFrom`.
|
||||
|
||||
### Encontrando seu ID de usuário do Telegram
|
||||
|
||||
Mais seguro (sem bot de terceiros):
|
||||
|
||||
1. Envie uma DM ao seu bot.
|
||||
1. Envie uma DM para seu bot.
|
||||
2. Execute `openclaw logs --follow`.
|
||||
3. Leia `from.id`.
|
||||
|
||||
@ -151,12 +151,12 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
</Tab>
|
||||
|
||||
<Tab title="Política de grupo e allowlists">
|
||||
Dois controles se aplicam em conjunto:
|
||||
Dois controles se aplicam juntos:
|
||||
|
||||
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 do grupo
|
||||
- com `groupPolicy: "allowlist"` (padrão): os grupos são bloqueados até que você adicione entradas em `groups` (ou `"*"`)
|
||||
- com `groupPolicy: "open"`: qualquer grupo pode passar nas verificações de ID de grupo
|
||||
- com `groupPolicy: "allowlist"` (padrão): os grupos são bloqueados até você adicionar entradas em `groups` (ou `"*"`)
|
||||
- `groups` configurado: atua como allowlist (IDs explícitos ou `"*"`)
|
||||
|
||||
2. **Quais remetentes são permitidos em grupos** (`channels.telegram.groupPolicy`)
|
||||
@ -164,15 +164,15 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `allowlist` (padrão)
|
||||
- `disabled`
|
||||
|
||||
`groupAllowFrom` é usado para filtrar remetentes em grupos. Se não estiver definido, o Telegram usa `allowFrom` como fallback.
|
||||
`groupAllowFrom` é usado para filtragem de remetentes em grupos. Se não estiver definido, o Telegram usa `allowFrom` como fallback.
|
||||
As entradas de `groupAllowFrom` devem ser IDs numéricos de usuários do Telegram (prefixos `telegram:` / `tg:` são normalizados).
|
||||
Não coloque IDs de chat de grupo ou supergrupo do Telegram em `groupAllowFrom`. IDs de chat negativos pertencem a `channels.telegram.groups`.
|
||||
Entradas não numéricas são ignoradas para autorização de remetentes.
|
||||
Limite de segurança (`2026.2.25+`): a autenticação de remetente em grupo **não** herda aprovações do armazenamento de pareamento de DM.
|
||||
Entradas não numéricas são ignoradas para autorização do remetente.
|
||||
Limite de segurança (`2026.2.25+`): a autorização de remetente em grupos **não** herda aprovações de pareamento de DM do pairing-store.
|
||||
O pareamento continua sendo apenas para DM. Para grupos, defina `groupAllowFrom` ou `allowFrom` por grupo/por tópico.
|
||||
Se `groupAllowFrom` não estiver definido, o Telegram usa `allowFrom` da configuração como fallback, não o armazenamento de pareamento.
|
||||
Padrão prático para bots de um único proprietário: defina seu ID de usuário em `channels.telegram.allowFrom`, deixe `groupAllowFrom` sem definir e permita os grupos de destino em `channels.telegram.groups`.
|
||||
Observação de runtime: se `channels.telegram` estiver completamente ausente, os padrões de runtime usam `groupPolicy="allowlist"` em fail-closed, a menos que `channels.defaults.groupPolicy` esteja explicitamente definido.
|
||||
Se `groupAllowFrom` não estiver definido, o Telegram usa `allowFrom` da configuração como fallback, não o pairing store.
|
||||
Padrão prático para bots de um único dono: defina seu ID de usuário em `channels.telegram.allowFrom`, deixe `groupAllowFrom` sem definir e permita os grupos-alvo em `channels.telegram.groups`.
|
||||
Observação de runtime: se `channels.telegram` estiver completamente ausente, os padrões de runtime usam fail-closed `groupPolicy="allowlist"` a menos que `channels.defaults.groupPolicy` seja explicitamente definido.
|
||||
|
||||
Exemplo: permitir qualquer membro em um grupo específico:
|
||||
|
||||
@ -211,8 +211,8 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
<Warning>
|
||||
Erro comum: `groupAllowFrom` não é uma allowlist de grupos do Telegram.
|
||||
|
||||
- Coloque IDs negativos de grupos ou supergrupos do Telegram como `-1001234567890` em `channels.telegram.groups`.
|
||||
- Coloque IDs de usuários do Telegram como `8734062810` em `groupAllowFrom` quando quiser limitar quais pessoas dentro de um grupo permitido podem acionar o bot.
|
||||
- Coloque IDs negativos de grupo ou supergrupo do Telegram como `-1001234567890` em `channels.telegram.groups`.
|
||||
- Coloque IDs de usuário do Telegram como `8734062810` em `groupAllowFrom` quando quiser limitar quais pessoas dentro de um grupo permitido podem acionar o bot.
|
||||
- Use `groupAllowFrom: ["*"]` apenas quando quiser que qualquer membro de um grupo permitido possa falar com o bot.
|
||||
</Warning>
|
||||
|
||||
@ -228,7 +228,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `agents.list[].groupChat.mentionPatterns`
|
||||
- `messages.groupChat.mentionPatterns`
|
||||
|
||||
Alternâncias de comando no nível da sessão:
|
||||
Alternâncias de comando em nível de sessão:
|
||||
|
||||
- `/activation always`
|
||||
- `/activation mention`
|
||||
@ -249,7 +249,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Obtendo o ID do chat em grupo:
|
||||
Obtendo o ID do chat de grupo:
|
||||
|
||||
- encaminhe uma mensagem do grupo para `@userinfobot` / `@getidsbot`
|
||||
- ou leia `chat.id` em `openclaw logs --follow`
|
||||
@ -260,56 +260,57 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
## Comportamento em runtime
|
||||
|
||||
- O Telegram é controlado pelo processo Gateway.
|
||||
- O Telegram é controlado pelo processo do Gateway.
|
||||
- O roteamento é determinístico: respostas recebidas do Telegram voltam para o Telegram (o modelo não escolhe canais).
|
||||
- Mensagens recebidas são normalizadas no envelope compartilhado de canal com metadados de resposta e placeholders de mídia.
|
||||
- As mensagens recebidas são normalizadas no envelope compartilhado de canais com metadados de resposta e placeholders de mídia.
|
||||
- Sessões de grupo são isoladas por ID do grupo. Tópicos de fórum acrescentam `:topic:<threadId>` para manter os tópicos isolados.
|
||||
- Mensagens de DM podem carregar `message_thread_id`; o OpenClaw as roteia com chaves de sessão conscientes de thread e preserva o ID da thread nas respostas.
|
||||
- O long polling usa grammY runner com sequenciamento por chat/por thread. A concorrência geral do sink do runner usa `agents.defaults.maxConcurrent`.
|
||||
- Reinicializações do watchdog de long polling são acionadas após 120 segundos sem atividade concluída de `getUpdates` por padrão. Aumente `channels.telegram.pollingStallThresholdMs` apenas se sua implantação ainda apresentar 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 suportadas.
|
||||
- A Bot API do Telegram não oferece suporte a confirmação de leitura (`sendReadReceipts` não se aplica).
|
||||
- Mensagens de DM podem transportar `message_thread_id`; o OpenClaw as roteia com chaves de sessão com reconhecimento de thread e preserva o ID da thread para respostas.
|
||||
- O long polling usa o runner do grammY com sequenciamento por chat/por thread. A concorrência geral do sink do runner usa `agents.defaults.maxConcurrent`.
|
||||
- Reinicializações do watchdog de long polling são disparadas após 120 segundos sem atividade concluída de `getUpdates` por padrão. Aumente `channels.telegram.pollingStallThresholdMs` apenas se sua implantação ainda vir reinicializações falsas de polling travado durante trabalhos de longa duração. O valor está em milissegundos e é permitido de `30000` a `600000`; substituições por conta são suportadas.
|
||||
- A Telegram Bot API não oferece suporte a confirmação de leitura (`sendReadReceipts` não se aplica).
|
||||
|
||||
## Referência de recursos
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Pré-visualização de stream ao vivo (edições de mensagem)">
|
||||
<Accordion title="Prévia de streaming ao vivo (edições de mensagem)">
|
||||
O OpenClaw pode transmitir respostas parciais em tempo real:
|
||||
|
||||
- chats diretos: mensagem de pré-visualização + `editMessageText`
|
||||
- grupos/tópicos: mensagem de pré-visualização + `editMessageText`
|
||||
- chats diretos: mensagem de prévia + `editMessageText`
|
||||
- grupos/tópicos: mensagem de prévia + `editMessageText`
|
||||
|
||||
Requisito:
|
||||
|
||||
- `channels.telegram.streaming` é `off | partial | block | progress` (padrão: `partial`)
|
||||
- `progress` é mapeado para `partial` no Telegram (compatibilidade com nomenclatura entre canais)
|
||||
- `progress` corresponde a `partial` no Telegram (compatibilidade com nomenclatura entre canais)
|
||||
- `streaming.preview.toolProgress` controla se atualizações de ferramenta/progresso reutilizam a mesma mensagem de prévia editada (padrão: `true`). Defina `false` para manter mensagens separadas de ferramenta/progresso.
|
||||
- `channels.telegram.streamMode` legado e valores booleanos de `streaming` são mapeados automaticamente
|
||||
|
||||
Para respostas somente com texto:
|
||||
Para respostas somente de texto:
|
||||
|
||||
- DM: o OpenClaw mantém a mesma mensagem de pré-visualização e faz uma edição final no mesmo lugar (sem segunda mensagem)
|
||||
- grupo/tópico: o OpenClaw mantém a mesma mensagem de pré-visualização e faz uma edição final no mesmo lugar (sem segunda mensagem)
|
||||
- DM: o OpenClaw mantém a mesma mensagem de prévia e faz uma edição final no mesmo lugar (sem segunda mensagem)
|
||||
- grupo/tópico: o OpenClaw mantém a mesma mensagem de prévia e faz uma edição final no mesmo lugar (sem segunda mensagem)
|
||||
|
||||
Para respostas complexas (por exemplo, payloads de mídia), o OpenClaw usa a entrega final normal como fallback e depois limpa a mensagem de pré-visualização.
|
||||
Para respostas complexas (por exemplo, payloads de mídia), o OpenClaw faz fallback para a entrega final normal e então limpa a mensagem de prévia.
|
||||
|
||||
O streaming de pré-visualização é separado do streaming em bloco. Quando o streaming em bloco está explicitamente habilitado para o Telegram, o OpenClaw ignora o stream de pré-visualização para evitar streaming duplo.
|
||||
O streaming de prévia é separado do streaming em bloco. Quando o streaming em bloco é explicitamente habilitado para Telegram, o OpenClaw ignora o streaming de prévia para evitar streaming duplo.
|
||||
|
||||
Se o transporte nativo de rascunho não estiver disponível/for rejeitado, o OpenClaw automaticamente usa `sendMessage` + `editMessageText` como fallback.
|
||||
Se o transporte nativo de rascunho estiver indisponível/for rejeitado, o OpenClaw faz fallback automaticamente para `sendMessage` + `editMessageText`.
|
||||
|
||||
Stream de raciocínio apenas do Telegram:
|
||||
Stream de raciocínio somente do Telegram:
|
||||
|
||||
- `/reasoning stream` envia o raciocínio para a pré-visualização ao vivo enquanto gera
|
||||
- `/reasoning stream` envia o raciocínio para a prévia ao vivo enquanto gera
|
||||
- a resposta final é enviada sem o texto de raciocínio
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Formatação e fallback para HTML">
|
||||
O texto de saída usa `parse_mode: "HTML"` do Telegram.
|
||||
O texto de saída usa Telegram `parse_mode: "HTML"`.
|
||||
|
||||
- Texto no estilo Markdown é renderizado como HTML seguro para Telegram.
|
||||
- HTML bruto do modelo é escapado para reduzir falhas de parsing do Telegram.
|
||||
- Se o Telegram rejeitar o HTML processado, o OpenClaw tenta novamente como texto simples.
|
||||
- Texto em estilo Markdown é renderizado em HTML seguro para Telegram.
|
||||
- HTML bruto do modelo é escapado para reduzir falhas de parsing no Telegram.
|
||||
- Se o Telegram rejeitar o HTML analisado, o OpenClaw tenta novamente como texto simples.
|
||||
|
||||
As pré-visualizações de links são ativadas por padrão e podem ser desativadas com `channels.telegram.linkPreview: false`.
|
||||
As prévias de link são habilitadas por padrão e podem ser desabilitadas com `channels.telegram.linkPreview: false`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -318,7 +319,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Padrões de comandos nativos:
|
||||
|
||||
- `commands.native: "auto"` habilita comandos nativos para o Telegram
|
||||
- `commands.native: "auto"` habilita comandos nativos para Telegram
|
||||
|
||||
Adicione entradas personalizadas ao menu de comandos:
|
||||
|
||||
@ -337,7 +338,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Regras:
|
||||
|
||||
- os nomes são normalizados (remove `/` inicial, minúsculas)
|
||||
- os nomes são normalizados (remover `/` inicial, minúsculas)
|
||||
- padrão válido: `a-z`, `0-9`, `_`, comprimento `1..32`
|
||||
- comandos personalizados não podem sobrescrever comandos nativos
|
||||
- conflitos/duplicatas são ignorados e registrados em log
|
||||
@ -345,30 +346,30 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
Observações:
|
||||
|
||||
- comandos personalizados são apenas entradas de menu; eles não implementam comportamento automaticamente
|
||||
- comandos de plugin/Skills ainda podem funcionar quando digitados, mesmo que não sejam mostrados no menu do Telegram
|
||||
- comandos de Plugin/Skills ainda podem funcionar quando digitados, mesmo que não sejam mostrados no menu do Telegram
|
||||
|
||||
Se os comandos nativos forem desativados, os integrados serão removidos. Comandos personalizados/de plugin ainda podem ser registrados se configurados.
|
||||
Se os comandos nativos estiverem desabilitados, os embutidos serão removidos. Comandos personalizados/de Plugin ainda podem ser registrados se estiverem configurados.
|
||||
|
||||
Falhas comuns de configuração:
|
||||
|
||||
- `setMyCommands failed` com `BOT_COMMANDS_TOO_MUCH` significa que o menu do Telegram ainda excedeu o limite após a redução; reduza comandos de plugin/Skills/personalizados ou desative `channels.telegram.commands.native`.
|
||||
- `setMyCommands failed` com erros de rede/fetch normalmente significa que o DNS/HTTPS de saída para `api.telegram.org` está bloqueado.
|
||||
- `setMyCommands failed` com `BOT_COMMANDS_TOO_MUCH` significa que o menu do Telegram ainda excedeu o limite após o ajuste; reduza comandos de Plugin/Skills/personalizados ou desabilite `channels.telegram.commands.native`.
|
||||
- `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` está instalado:
|
||||
Quando o Plugin `device-pair` está instalado:
|
||||
|
||||
1. `/pair` gera um código de configuração
|
||||
2. cole o código no app iOS
|
||||
3. `/pair pending` lista solicitações pendentes (incluindo função/escopos)
|
||||
3. `/pair pending` lista solicitações pendentes (incluindo role/scopes)
|
||||
4. aprove a solicitação:
|
||||
- `/pair approve <requestId>` para aprovação explícita
|
||||
- `/pair approve` quando há apenas uma solicitação pendente
|
||||
- `/pair approve` quando houver apenas uma solicitação pendente
|
||||
- `/pair approve latest` para a mais recente
|
||||
|
||||
O código de configuração carrega um token de bootstrap de curta duração. O handoff de bootstrap integrado mantém o token do node 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, então essa allowlist de operador satisfaz apenas solicitações de operador; funções não operadoras ainda precisam de escopos sob o prefixo da própria função.
|
||||
O código de configuração carrega um token bootstrap de curta duração. A transferência bootstrap embutida mantém o token do node primário em `scopes: []`; qualquer token de operador transferido permanece limitado a `operator.approvals`, `operator.read`, `operator.talk.secrets` e `operator.write`. As verificações de escopo bootstrap usam prefixo de role, então essa allowlist de operador satisfaz apenas solicitações de operador; roles que não são de operador ainda precisam de scopes sob o prefixo da própria role.
|
||||
|
||||
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 role/scopes/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).
|
||||
|
||||
@ -415,7 +416,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `all`
|
||||
- `allowlist` (padrão)
|
||||
|
||||
O legado `capabilities: ["inlineButtons"]` é mapeado para `inlineButtons: "all"`.
|
||||
O legado `capabilities: ["inlineButtons"]` corresponde a `inlineButtons: "all"`.
|
||||
|
||||
Exemplo de ação de mensagem:
|
||||
|
||||
@ -435,7 +436,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Cliques de callback são passados ao agente como texto:
|
||||
Cliques em callback são passados ao agente como texto:
|
||||
`callback_data: <value>`
|
||||
|
||||
</Accordion>
|
||||
@ -451,15 +452,15 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
As ações de mensagem do canal expõem aliases ergonômicos (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`).
|
||||
|
||||
Controles de gating:
|
||||
Controles de bloqueio:
|
||||
|
||||
- `channels.telegram.actions.sendMessage`
|
||||
- `channels.telegram.actions.deleteMessage`
|
||||
- `channels.telegram.actions.reactions`
|
||||
- `channels.telegram.actions.sticker` (padrão: desativado)
|
||||
- `channels.telegram.actions.sticker` (padrão: desabilitado)
|
||||
|
||||
Observação: `edit` e `topic-create` estão atualmente habilitados por padrão e não têm alternâncias `channels.telegram.actions.*` separadas.
|
||||
Os envios em runtime usam o snapshot ativo de config/secrets (inicialização/reload), então os caminhos de ação não executam re-resolução ad hoc de SecretRef por envio.
|
||||
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 config/secrets (inicialização/reload), portanto os caminhos de ação não executam nova resolução ad hoc de SecretRef a cada envio.
|
||||
|
||||
Semântica de remoção de reação: [/tools/reactions](/pt-BR/tools/reactions)
|
||||
|
||||
@ -468,7 +469,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
<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 que acionou a ação
|
||||
- `[[reply_to_current]]` responde à mensagem que acionou
|
||||
- `[[reply_to:<id>]]` responde a um ID específico de mensagem do Telegram
|
||||
|
||||
`channels.telegram.replyToMode` controla o tratamento:
|
||||
@ -477,7 +478,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `first`
|
||||
- `all`
|
||||
|
||||
Observação: `off` desativa o encadeamento implícito de resposta. Tags explícitas `[[reply_to_*]]` ainda são respeitadas.
|
||||
Observação: `off` desabilita o encadeamento implícito de resposta. Tags explícitas `[[reply_to_*]]` ainda são respeitadas.
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -489,15 +490,15 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- caminho de configuração do tópico:
|
||||
`channels.telegram.groups.<chatId>.topics.<threadId>`
|
||||
|
||||
Caso especial do tópico Geral (`threadId=1`):
|
||||
Caso especial do tópico geral (`threadId=1`):
|
||||
|
||||
- envios de mensagem omitem `message_thread_id` (o Telegram rejeita `sendMessage(...thread_id=1)`)
|
||||
- ações de digitação ainda incluem `message_thread_id`
|
||||
|
||||
Herança de tópico: entradas de tópico herdam as configurações do grupo, salvo substituição (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`).
|
||||
Herança de tópico: entradas de tópico herdam configurações do grupo, a menos que sejam sobrescritas (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`).
|
||||
`agentId` é exclusivo de tópico e não herda dos padrões do grupo.
|
||||
|
||||
**Roteamento de agente por tópico**: Cada tópico pode rotear para um agente diferente definindo `agentId` na configuração do tópico. Isso dá a cada tópico seu próprio workspace, memória e sessão isolados. Exemplo:
|
||||
**Roteamento de agente por tópico**: cada tópico pode rotear para um agente diferente definindo `agentId` na configuração do tópico. Isso dá a cada tópico seu próprio workspace, memória e sessão isolados. Exemplo:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -506,8 +507,8 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
groups: {
|
||||
"-1001234567890": {
|
||||
topics: {
|
||||
"1": { agentId: "main" }, // Tópico Geral → agente main
|
||||
"3": { agentId: "zu" }, // Tópico de desenvolvimento → agente zu
|
||||
"1": { agentId: "main" }, // Tópico geral → agente main
|
||||
"3": { agentId: "zu" }, // Tópico de dev → agente zu
|
||||
"5": { agentId: "coder" } // Revisão de código → agente coder
|
||||
}
|
||||
}
|
||||
@ -519,7 +520,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Cada tópico então tem sua própria chave de sessão: `agent:zu:telegram:group:-1001234567890:topic:3`
|
||||
|
||||
**Vínculo persistente de tópico ACP**: Tópicos de fórum podem fixar sessões do harness ACP por meio de vínculos ACP tipados de nível superior:
|
||||
**Vinculação persistente de tópico ACP**: tópicos de fórum podem fixar sessões do harness ACP por meio de vinculações ACP tipadas de nível superior:
|
||||
|
||||
- `bindings[]` com `type: "acp"` e `match.channel: "telegram"`
|
||||
|
||||
@ -570,13 +571,13 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Isso atualmente se limita a tópicos de fórum em grupos e supergrupos.
|
||||
Atualmente isso está limitado a tópicos de fórum em grupos e supergrupos.
|
||||
|
||||
**Criação de ACP vinculado à thread a partir do chat**:
|
||||
|
||||
- `/acp spawn <agent> --thread here|auto` pode vincular o tópico atual do Telegram a uma nova sessão ACP.
|
||||
- Mensagens subsequentes no tópico são roteadas diretamente para a sessão ACP vinculada (sem necessidade de `/acp steer`).
|
||||
- O OpenClaw fixa a mensagem de confirmação de criação no tópico após uma vinculação bem-sucedida.
|
||||
- Mensagens posteriores do tópico são roteadas diretamente para a sessão ACP vinculada (sem necessidade de `/acp steer`).
|
||||
- O OpenClaw fixa a mensagem de confirmação de criação dentro do tópico após uma vinculação bem-sucedida.
|
||||
- Requer `channels.telegram.threadBindings.spawnAcpSessions=true`.
|
||||
|
||||
O contexto do template inclui:
|
||||
@ -586,7 +587,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Comportamento de thread em DM:
|
||||
|
||||
- chats privados com `message_thread_id` mantêm o roteamento de DM, mas usam chaves de sessão e destinos de resposta conscientes de thread.
|
||||
- chats privados com `message_thread_id` mantêm o roteamento de DM, mas usam chaves de sessão/alvos de resposta com reconhecimento de thread.
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -596,7 +597,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
O Telegram diferencia notas de voz de arquivos de áudio.
|
||||
|
||||
- padrão: comportamento de arquivo de áudio
|
||||
- tag `[[audio_as_voice]]` na resposta do agente para forçar o envio como nota de voz
|
||||
- tag `[[audio_as_voice]]` na resposta do agente para forçar envio como nota de voz
|
||||
|
||||
Exemplo de ação de mensagem:
|
||||
|
||||
@ -634,7 +635,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
- WEBP estático: baixado e processado (placeholder `<media:sticker>`)
|
||||
- TGS animado: ignorado
|
||||
- WEBM em vídeo: ignorado
|
||||
- WEBM de vídeo: ignorado
|
||||
|
||||
Campos de contexto do sticker:
|
||||
|
||||
@ -648,7 +649,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
- `~/.openclaw/telegram/sticker-cache.json`
|
||||
|
||||
Os stickers são descritos uma vez (quando possível) e armazenados em cache para reduzir chamadas repetidas de vision.
|
||||
Os stickers são descritos uma vez (quando possível) e armazenados em cache para reduzir chamadas repetidas de visão.
|
||||
|
||||
Habilite ações de sticker:
|
||||
|
||||
@ -681,7 +682,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
{
|
||||
action: "sticker-search",
|
||||
channel: "telegram",
|
||||
query: "gato acenando",
|
||||
query: "cat waving",
|
||||
limit: 5,
|
||||
}
|
||||
```
|
||||
@ -702,18 +703,18 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Observações:
|
||||
|
||||
- `own` significa reações de usuário apenas em mensagens enviadas pelo bot (melhor esforço via cache de mensagens enviadas).
|
||||
- `own` significa reações de usuários apenas em mensagens enviadas pelo bot (melhor esforço via cache de mensagens enviadas).
|
||||
- Eventos de reação ainda respeitam os controles de acesso do Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); remetentes não autorizados são descartados.
|
||||
- O Telegram não fornece IDs de thread em atualizações de reação.
|
||||
- grupos sem fórum são roteados para a sessão de chat do grupo
|
||||
- grupos com fórum são roteados para a sessão do tópico geral do grupo (`:topic:1`), não para o tópico de origem exato
|
||||
- O Telegram não fornece IDs de thread nas atualizações de reação.
|
||||
- grupos que não são fórum são roteados para a sessão do chat em 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
|
||||
|
||||
`allowed_updates` para polling/Webhook inclui `message_reaction` automaticamente.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Reações de confirmação">
|
||||
`ackReaction` envia um emoji de confirmação enquanto o OpenClaw processa uma mensagem recebida.
|
||||
<Accordion title="Reações de ack">
|
||||
`ackReaction` envia um emoji de confirmação enquanto o OpenClaw está processando uma mensagem recebida.
|
||||
|
||||
Ordem de resolução:
|
||||
|
||||
@ -724,20 +725,20 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Observações:
|
||||
|
||||
- O Telegram espera emoji unicode (por exemplo, "👀").
|
||||
- Use `""` para desativar 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 conta.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Gravações de configuração a partir de eventos e comandos do Telegram">
|
||||
Gravações de configuração do canal são habilitadas por padrão (`configWrites !== false`).
|
||||
As gravações de configuração do canal são habilitadas por padrão (`configWrites !== false`).
|
||||
|
||||
Gravações acionadas pelo Telegram incluem:
|
||||
As gravações acionadas pelo Telegram incluem:
|
||||
|
||||
- eventos de migração de grupo (`migrate_to_chat_id`) para atualizar `channels.telegram.groups`
|
||||
- `/config set` e `/config unset` (requer habilitação do comando)
|
||||
- `/config set` e `/config unset` (requer habilitação de comando)
|
||||
|
||||
Desative:
|
||||
Desabilitar:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -757,33 +758,33 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
Modo Webhook:
|
||||
|
||||
- defina `channels.telegram.webhookUrl`
|
||||
- defina `channels.telegram.webhookSecret` (obrigatório quando `webhookUrl` estiver definido)
|
||||
- opcional `channels.telegram.webhookPath` (padrão `/telegram-webhook`)
|
||||
- opcional `channels.telegram.webhookHost` (padrão `127.0.0.1`)
|
||||
- opcional `channels.telegram.webhookPort` (padrão `8787`)
|
||||
- defina `channels.telegram.webhookSecret` (obrigatório quando a URL do Webhook está definida)
|
||||
- `channels.telegram.webhookPath` opcional (padrão `/telegram-webhook`)
|
||||
- `channels.telegram.webhookHost` opcional (padrão `127.0.0.1`)
|
||||
- `channels.telegram.webhookPort` opcional (padrão `8787`)
|
||||
|
||||
O listener local padrão para o modo Webhook se associa a `127.0.0.1:8787`.
|
||||
O listener local padrão para o modo Webhook se vincula a `127.0.0.1:8787`.
|
||||
|
||||
Se seu endpoint público for diferente, coloque um proxy reverso na frente e aponte `webhookUrl` para a URL pública.
|
||||
Defina `webhookHost` (por exemplo `0.0.0.0`) quando você intencionalmente precisar de entrada externa.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Limites, repetição e destinos da CLI">
|
||||
<Accordion title="Limites, retry e alvos da CLI">
|
||||
- o padrão de `channels.telegram.textChunkLimit` é 4000.
|
||||
- `channels.telegram.chunkMode="newline"` prefere limites de parágrafo (linhas em branco) antes de dividir por comprimento.
|
||||
- `channels.telegram.mediaMaxMb` (padrão 100) limita o tamanho de mídia do Telegram recebida e enviada.
|
||||
- `channels.telegram.timeoutSeconds` substitui o timeout do cliente da API do Telegram (se não estiver definido, aplica-se o padrão do grammY).
|
||||
- `channels.telegram.pollingStallThresholdMs` tem padrão `120000`; ajuste entre `30000` e `600000` apenas para reinicializações falso-positivas por travamento de polling.
|
||||
- o histórico de contexto de grupo usa `channels.telegram.historyLimit` ou `messages.groupChat.historyLimit` (padrão 50); `0` desativa.
|
||||
- o contexto suplementar de resposta/citação/encaminhamento atualmente é repassado como recebido.
|
||||
- as allowlists do Telegram controlam principalmente quem pode acionar o agente, não um limite completo de redação de contexto suplementar.
|
||||
- `channels.telegram.chunkMode="newline"` prefere limites de parágrafo (linhas em branco) antes da divisão por tamanho.
|
||||
- `channels.telegram.mediaMaxMb` (padrão 100) limita o tamanho de mídia recebida e enviada no Telegram.
|
||||
- `channels.telegram.timeoutSeconds` sobrescreve o timeout do cliente da API do Telegram (se não definido, aplica-se o padrão do grammY).
|
||||
- `channels.telegram.pollingStallThresholdMs` tem padrão `120000`; ajuste entre `30000` e `600000` apenas para reinicializações falsas de polling travado.
|
||||
- o histórico de contexto de grupo usa `channels.telegram.historyLimit` ou `messages.groupChat.historyLimit` (padrão 50); `0` desabilita.
|
||||
- o 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.dmHistoryLimit`
|
||||
- `channels.telegram.dms["<user_id>"].historyLimit`
|
||||
- a configuração `channels.telegram.retry` se aplica aos auxiliares de envio do Telegram (CLI/ferramentas/ações) para erros recuperáveis da API de saída.
|
||||
- a configuração `channels.telegram.retry` se aplica aos helpers de envio do Telegram (CLI/ferramentas/ações) para erros recuperáveis de API de saída.
|
||||
|
||||
O destino de envio da CLI pode ser ID numérico do chat ou nome de usuário:
|
||||
O alvo de envio da CLI pode ser um ID numérico de chat ou username:
|
||||
|
||||
```bash
|
||||
openclaw message send --channel telegram --target 123456789 --message "hi"
|
||||
@ -800,22 +801,22 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
--poll-duration-seconds 300 --poll-public
|
||||
```
|
||||
|
||||
Flags de poll exclusivas do Telegram:
|
||||
Flags de poll somente do Telegram:
|
||||
|
||||
- `--poll-duration-seconds` (5-600)
|
||||
- `--poll-anonymous`
|
||||
- `--poll-public`
|
||||
- `--thread-id` para tópicos de fórum (ou use um destino `:topic:`)
|
||||
- `--thread-id` para tópicos de fórum (ou use um alvo `:topic:`)
|
||||
|
||||
O envio do Telegram também oferece suporte a:
|
||||
O envio no Telegram também oferece suporte a:
|
||||
|
||||
- `--buttons` para teclados inline quando `channels.telegram.capabilities.inlineButtons` permite essa superfície
|
||||
- `--force-document` para enviar imagens e GIFs de saída como documentos em vez de uploads comprimidos de foto ou mídia animada
|
||||
- `--buttons` para teclados inline quando `channels.telegram.capabilities.inlineButtons` permite isso
|
||||
- `--force-document` para enviar imagens e GIFs de saída como documentos em vez de uploads compactados de foto ou mídia animada
|
||||
|
||||
Controle de ações:
|
||||
|
||||
- `channels.telegram.actions.sendMessage=false` desativa mensagens de saída do Telegram, incluindo polls
|
||||
- `channels.telegram.actions.poll=false` desativa a criação de polls no Telegram, mantendo envios regulares habilitados
|
||||
- `channels.telegram.actions.sendMessage=false` desabilita mensagens de saída no Telegram, incluindo polls
|
||||
- `channels.telegram.actions.poll=false` desabilita a criação de polls no Telegram, mantendo envios normais habilitados
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -825,38 +826,38 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
Caminho de configuração:
|
||||
|
||||
- `channels.telegram.execApprovals.enabled`
|
||||
- `channels.telegram.execApprovals.approvers` (opcional; usa como fallback IDs numéricos de proprietário inferidos de `allowFrom` e `defaultTo` direto quando possível)
|
||||
- `channels.telegram.execApprovals.approvers` (opcional; usa como fallback IDs numéricos de owners inferidos de `allowFrom` e `defaultTo` de mensagem direta quando possível)
|
||||
- `channels.telegram.execApprovals.target` (`dm` | `channel` | `both`, padrão: `dm`)
|
||||
- `agentFilter`, `sessionFilter`
|
||||
|
||||
Os aprovadores devem ser IDs numéricos de usuários do Telegram. O Telegram habilita automaticamente aprovações de exec nativas quando `enabled` não está definido ou é `"auto"` e pelo menos um aprovador pode ser resolvido, seja de `execApprovals.approvers` ou da configuração numérica de proprietário da conta (`allowFrom` e `defaultTo` de mensagem direta). Defina `enabled: false` para desativar explicitamente o Telegram como cliente nativo de aprovação. Caso contrário, solicitações de aprovação usam outras rotas de aprovação configuradas ou a política de fallback de aprovação de exec.
|
||||
Os aprovadores devem ser IDs numéricos de usuários do Telegram. O Telegram habilita automaticamente aprovações nativas de exec quando `enabled` não está definido ou é `"auto"` e pelo menos um aprovador pode ser resolvido, seja de `execApprovals.approvers` ou da configuração numérica de owner da conta (`allowFrom` e `defaultTo` de mensagem direta). Defina `enabled: false` para desabilitar explicitamente o Telegram como cliente nativo de aprovação. Caso contrário, solicitações de aprovação usam fallback para outras rotas de aprovação configuradas ou para a política de fallback de aprovação de exec.
|
||||
|
||||
O Telegram também renderiza os botões de aprovação compartilhados usados por outros canais de chat. O adaptador nativo do Telegram adiciona principalmente roteamento de DMs para aprovadores, fanout para canal/tópico e dicas de digitação antes da entrega.
|
||||
O Telegram também renderiza os botões compartilhados de aprovação usados por outros canais de chat. O adaptador nativo do Telegram adiciona principalmente roteamento para DMs de aprovadores, fanout para canal/tópico e dicas de digitação antes da entrega.
|
||||
Quando esses botões estão presentes, eles são a UX principal de aprovação; o OpenClaw
|
||||
deve incluir um comando manual `/approve` apenas quando o resultado da ferramenta disser
|
||||
que aprovações no chat não estão disponíveis ou que a aprovação manual é o único caminho.
|
||||
só deve incluir um comando manual `/approve` quando o resultado da ferramenta disser
|
||||
que aprovações por chat estão indisponíveis ou quando a aprovação manual for o único caminho.
|
||||
|
||||
Regras de entrega:
|
||||
|
||||
- `target: "dm"` envia prompts de aprovação apenas para DMs dos aprovadores resolvidos
|
||||
- `target: "channel"` envia o prompt de volta para o chat/tópico de origem no Telegram
|
||||
- `target: "both"` envia para as DMs dos aprovadores e para o chat/tópico de origem
|
||||
- `target: "both"` envia para DMs dos aprovadores e para o chat/tópico de origem
|
||||
|
||||
Apenas aprovadores resolvidos podem aprovar ou negar. Não aprovadores não podem usar `/approve` nem os botões de aprovação do Telegram.
|
||||
Apenas aprovadores resolvidos podem aprovar ou negar. Não aprovadores não podem usar `/approve` e não podem usar botões de aprovação do Telegram.
|
||||
|
||||
Comportamento de resolução de aprovação:
|
||||
|
||||
- IDs prefixados com `plugin:` sempre são resolvidos por aprovações de plugin.
|
||||
- Outros IDs tentam `exec.approval.resolve` primeiro.
|
||||
- Se o Telegram também estiver autorizado para aprovações de plugin e o Gateway disser
|
||||
que a aprovação de exec é desconhecida/expirada, o Telegram tenta novamente uma vez via
|
||||
- IDs com prefixo `plugin:` sempre são resolvidos via aprovações de Plugin.
|
||||
- Outros IDs de aprovação tentam primeiro `exec.approval.resolve`.
|
||||
- Se o Telegram também estiver autorizado para aprovações de Plugin e o gateway disser
|
||||
que a aprovação de exec é desconhecida/expirada, o Telegram tenta novamente uma vez por
|
||||
`plugin.approval.resolve`.
|
||||
- Negativas/erros reais de aprovação de exec não fazem fallback silencioso para
|
||||
resolução de aprovação de plugin.
|
||||
- Negações/erros reais de aprovação de exec não fazem fallback silencioso para
|
||||
resolução de aprovação de Plugin.
|
||||
|
||||
A entrega no canal mostra o texto do comando no chat, portanto 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 tanto para o prompt de aprovação quanto para o acompanhamento pós-aprovação. As aprovações de exec expiram após 30 minutos por padrão.
|
||||
A entrega no canal mostra o texto do comando no chat, então habilite `channel` ou `both` apenas em grupos/tópicos confiáveis. Quando o prompt chega em um tópico de fórum, o OpenClaw preserva o tópico tanto para o prompt de aprovação quanto para o acompanhamento após a aprovação. As aprovações de exec expiram após 30 minutos por padrão.
|
||||
|
||||
Botões de aprovação inline também dependem de `channels.telegram.capabilities.inlineButtons` permitir a superfície de destino (`dm`, `group` ou `all`).
|
||||
Botões inline de aprovação também dependem de `channels.telegram.capabilities.inlineButtons` permitir a superfície de destino (`dm`, `group` ou `all`).
|
||||
|
||||
Documentação relacionada: [Aprovações de exec](/pt-BR/tools/exec-approvals)
|
||||
|
||||
@ -865,7 +866,7 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
|
||||
## Controles de resposta de erro
|
||||
|
||||
Quando o agente encontra um erro de entrega ou do provedor, o Telegram pode responder com o texto do erro ou suprimi-lo. Duas chaves de configuração controlam esse comportamento:
|
||||
Quando o agente encontra um erro de entrega ou de provider, o Telegram pode responder com o texto do erro ou suprimi-lo. Duas chaves de configuração controlam esse comportamento:
|
||||
|
||||
| Key | Values | Default | Description |
|
||||
| ----------------------------------- | ----------------- | ------- | ----------------------------------------------------------------------------------------------- |
|
||||
@ -895,40 +896,40 @@ Substituições por conta, por grupo e por tópico são suportadas (mesma heran
|
||||
<AccordionGroup>
|
||||
<Accordion title="O bot não responde a mensagens de grupo sem menção">
|
||||
|
||||
- Se `requireMention=false`, o modo de privacidade do Telegram deve permitir visibilidade total.
|
||||
- Se `requireMention=false`, o modo de privacidade do Telegram deve permitir visibilidade completa.
|
||||
- BotFather: `/setprivacy` -> Disable
|
||||
- depois remova + adicione novamente o bot ao grupo
|
||||
- então remova + adicione novamente o bot ao grupo
|
||||
- `openclaw channels status` avisa quando a configuração espera mensagens de grupo sem menção.
|
||||
- `openclaw channels status --probe` pode verificar IDs numéricos explícitos de grupo; o curinga `"*"` não pode ser verificado por associação.
|
||||
- `openclaw channels status --probe` pode verificar IDs numéricos explícitos de grupo; o curinga `"*"` não pode ser verificado por membership probe.
|
||||
- teste rápido de sessão: `/activation always`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="O bot não vê mensagens de grupo de forma alguma">
|
||||
<Accordion title="O bot não está vendo mensagens de grupo de forma alguma">
|
||||
|
||||
- quando `channels.telegram.groups` existe, o grupo deve estar listado (ou incluir `"*"`)
|
||||
- verifique a associação do bot ao grupo
|
||||
- verifique a participação do bot no grupo
|
||||
- revise os logs: `openclaw logs --follow` para motivos de ignorar
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Os comandos funcionam parcialmente ou não funcionam">
|
||||
|
||||
- autorize a identidade do remetente (pareamento e/ou `allowFrom` numérico)
|
||||
- a autorização de comandos ainda se aplica mesmo quando a política de grupo é `open`
|
||||
- `setMyCommands failed` com `BOT_COMMANDS_TOO_MUCH` significa que o menu nativo tem entradas demais; reduza comandos de plugin/Skills/personalizados ou desative menus nativos
|
||||
- autorize a identidade do seu 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
|
||||
- `setMyCommands failed` com erros de rede/fetch normalmente indica problemas de alcance DNS/HTTPS para `api.telegram.org`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Instabilidade de polling ou rede">
|
||||
<Accordion title="Instabilidade de polling ou de rede">
|
||||
|
||||
- Node 22+ + fetch/proxy personalizado podem acionar comportamento de abort imediato se os tipos de AbortSignal não corresponderem.
|
||||
- Alguns hosts resolvem `api.telegram.org` primeiro para IPv6; saída IPv6 com falha pode causar falhas intermitentes da API do Telegram.
|
||||
- Node 22+ + fetch/proxy personalizado pode disparar comportamento de aborto imediato se os tipos de AbortSignal não coincidirem.
|
||||
- Alguns hosts resolvem `api.telegram.org` primeiro para IPv6; saída IPv6 com problema pode causar falhas intermitentes na API do Telegram.
|
||||
- Se os logs incluírem `TypeError: fetch failed` ou `Network request for 'getUpdates' failed!`, o OpenClaw agora tenta novamente esses casos como erros de rede recuperáveis.
|
||||
- Se os logs incluírem `Polling stall detected`, o OpenClaw reinicia o polling e recria o transporte do Telegram após 120 segundos sem atividade concluída de long-poll por padrão.
|
||||
- Aumente `channels.telegram.pollingStallThresholdMs` apenas quando chamadas longas de `getUpdates` estiverem saudáveis, mas seu host ainda relatar reinicializações falso-positivas por travamento de polling. Travamentos persistentes geralmente apontam para problemas de proxy, DNS, IPv6 ou saída TLS entre o host e `api.telegram.org`.
|
||||
- Em hosts VPS com saída/TLS direta instável, roteie chamadas da API do Telegram por `channels.telegram.proxy`:
|
||||
- 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 atividade concluída de long-poll por padrão.
|
||||
- Aumente `channels.telegram.pollingStallThresholdMs` apenas quando chamadas longas de `getUpdates` estiverem saudáveis, mas seu host ainda relatar reinicializações falsas de polling travado. Travamentos persistentes normalmente apontam para problemas de proxy, DNS, IPv6 ou saída TLS entre o host e `api.telegram.org`.
|
||||
- Em hosts VPS com saída direta/TLS instável, roteie chamadas da API do Telegram por `channels.telegram.proxy`:
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
@ -936,7 +937,7 @@ channels:
|
||||
proxy: socks5://<user>:<password>@proxy-host:1080
|
||||
```
|
||||
|
||||
- O Node 22+ usa por padrão `autoSelectFamily=true` (exceto WSL2) e `dnsResultOrder=ipv4first`.
|
||||
- Node 22+ usa por padrão `autoSelectFamily=true` (exceto WSL2) e `dnsResultOrder=ipv4first`.
|
||||
- Se seu host for WSL2 ou explicitamente funcionar melhor com comportamento somente IPv4, force a seleção de família:
|
||||
|
||||
```yaml
|
||||
@ -946,11 +947,11 @@ channels:
|
||||
autoSelectFamily: false
|
||||
```
|
||||
|
||||
- Respostas na faixa de benchmark RFC 2544 (`198.18.0.0/15`) já são permitidas
|
||||
- Respostas no 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 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:
|
||||
habilitar o bypass somente para Telegram:
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
@ -959,21 +960,18 @@ channels:
|
||||
dangerouslyAllowPrivateNetwork: true
|
||||
```
|
||||
|
||||
- O mesmo opt-in está disponível por conta em
|
||||
- A mesma habilitação opcional também está disponível por conta em
|
||||
`channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork`.
|
||||
- Se seu proxy resolver hosts de mídia do Telegram para `198.18.x.x`, deixe a
|
||||
flag perigosa desativada primeiro. A mídia do Telegram já permite a faixa de benchmark RFC 2544
|
||||
por padrão.
|
||||
flag perigosa desabilitada 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 de SSRF de mídia do Telegram. Use isso apenas em ambientes de proxy
|
||||
confiáveis e controlados pelo operador, como roteamento fake-IP do Clash, Mihomo ou Surge quando eles
|
||||
sintetizarem respostas privadas ou de uso especial fora da faixa de benchmark RFC 2544.
|
||||
Deixe desativado para acesso normal do Telegram pela internet pública.
|
||||
proteções SSRF de mídia do Telegram. Use isso apenas em ambientes de proxy
|
||||
confiáveis e controlados pelo operador, como roteamento fake-IP do Clash, Mihomo ou Surge, quando eles sintetizam respostas privadas ou de uso especial fora do intervalo de benchmark RFC 2544. Deixe isso desabilitado para acesso normal ao Telegram pela internet pública.
|
||||
</Warning>
|
||||
|
||||
- Substituições por ambiente (temporárias):
|
||||
- Substituições por variável de ambiente (temporárias):
|
||||
- `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1`
|
||||
- `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1`
|
||||
- `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first`
|
||||
@ -989,7 +987,7 @@ dig +short api.telegram.org AAAA
|
||||
|
||||
Mais ajuda: [Solução de problemas do canal](/pt-BR/channels/troubleshooting).
|
||||
|
||||
## Ponteiros de referência de configuração do Telegram
|
||||
## Ponteiros da referência de configuração do Telegram
|
||||
|
||||
Referência principal:
|
||||
|
||||
@ -997,74 +995,75 @@ Referência principal:
|
||||
- `channels.telegram.botToken`: token do bot (BotFather).
|
||||
- `channels.telegram.tokenFile`: lê o token de um caminho de arquivo regular. Symlinks são rejeitados.
|
||||
- `channels.telegram.dmPolicy`: `pairing | allowlist | open | disabled` (padrão: pairing).
|
||||
- `channels.telegram.allowFrom`: allowlist de DM (IDs numéricos de usuários do Telegram). `allowlist` exige pelo menos um ID de remetente. `open` exige `"*"`. `openclaw doctor --fix` pode resolver entradas legadas `@username` para IDs e pode recuperar entradas de allowlist de arquivos do armazenamento de pareamento em fluxos de migração de allowlist.
|
||||
- `channels.telegram.actions.poll`: habilita ou desabilita a criação de polls no Telegram (padrão: habilitado; ainda requer `sendMessage`).
|
||||
- `channels.telegram.defaultTo`: destino padrão do Telegram usado por `--deliver` da CLI quando nenhum `--reply-to` explícito é fornecido.
|
||||
- `channels.telegram.allowFrom`: allowlist de DM (IDs numéricos de usuários do Telegram). `allowlist` exige pelo menos um ID de remetente. `open` exige `"*"`. `openclaw doctor --fix` pode resolver entradas legadas `@username` para IDs e pode recuperar entradas de allowlist de arquivos do pairing-store em fluxos de migração de allowlist.
|
||||
- `channels.telegram.actions.poll`: habilita ou desabilita a criação de polls no Telegram (padrão: habilitado; ainda exige `sendMessage`).
|
||||
- `channels.telegram.defaultTo`: alvo padrão do Telegram usado por `--deliver` da CLI quando nenhum `--reply-to` explícito é fornecido.
|
||||
- `channels.telegram.groupPolicy`: `open | allowlist | disabled` (padrão: allowlist).
|
||||
- `channels.telegram.groupAllowFrom`: allowlist de remetentes em grupo (IDs numéricos de usuários do Telegram). `openclaw doctor --fix` pode resolver entradas legadas `@username` para IDs. Entradas não numéricas são ignoradas no momento da autenticação. A autenticação de grupo não usa fallback do armazenamento de pareamento de DM (`2026.2.25+`).
|
||||
- `channels.telegram.groupAllowFrom`: allowlist de remetentes em grupo (IDs numéricos de usuários do Telegram). `openclaw doctor --fix` pode resolver entradas legadas `@username` para IDs. Entradas não numéricas são ignoradas no momento da autenticação. A autenticação de grupo não usa fallback do pairing-store de DM (`2026.2.25+`).
|
||||
- Precedência de múltiplas contas:
|
||||
- Quando dois ou mais IDs de conta estão configurados, defina `channels.telegram.defaultAccount` (ou inclua `channels.telegram.accounts.default`) para tornar o roteamento padrão explícito.
|
||||
- Se nenhum dos dois for definido, o OpenClaw usa como fallback o primeiro ID de conta normalizado e `openclaw doctor` emite um aviso.
|
||||
- Quando dois ou mais IDs de conta estão configurados, defina `channels.telegram.defaultAccount` (ou inclua `channels.telegram.accounts.default`) para tornar explícito o roteamento padrão.
|
||||
- Se nenhum dos dois estiver definido, o OpenClaw usa como fallback o primeiro ID de conta normalizado e `openclaw doctor` emite um aviso.
|
||||
- `channels.telegram.accounts.default.allowFrom` e `channels.telegram.accounts.default.groupAllowFrom` se aplicam apenas à conta `default`.
|
||||
- Contas nomeadas herdam `channels.telegram.allowFrom` e `channels.telegram.groupAllowFrom` quando os valores no nível da conta não estão definidos.
|
||||
- Contas nomeadas não herdam `channels.telegram.accounts.default.allowFrom` / `groupAllowFrom`.
|
||||
- `channels.telegram.groups`: padrões por grupo + allowlist (use `"*"` para padrões globais).
|
||||
- `channels.telegram.groups.<id>.groupPolicy`: substituição por grupo para `groupPolicy` (`open | allowlist | disabled`).
|
||||
- `channels.telegram.groups.<id>.requireMention`: padrão de exigência de menção.
|
||||
- `channels.telegram.groups.<id>.groupPolicy`: sobrescrita por grupo para `groupPolicy` (`open | allowlist | disabled`).
|
||||
- `channels.telegram.groups.<id>.requireMention`: padrão de bloqueio por menção.
|
||||
- `channels.telegram.groups.<id>.skills`: filtro de Skills (omitir = todas as Skills, vazio = nenhuma).
|
||||
- `channels.telegram.groups.<id>.allowFrom`: substituição por grupo para allowlist de remetentes.
|
||||
- `channels.telegram.groups.<id>.allowFrom`: sobrescrita da allowlist de remetentes por grupo.
|
||||
- `channels.telegram.groups.<id>.systemPrompt`: prompt de sistema extra para o grupo.
|
||||
- `channels.telegram.groups.<id>.enabled`: desabilita o grupo quando `false`.
|
||||
- `channels.telegram.groups.<id>.topics.<threadId>.*`: substituições por tópico (campos de grupo + `agentId` exclusivo de tópico).
|
||||
- `channels.telegram.groups.<id>.topics.<threadId>.agentId`: roteia este tópico para um agente específico (substitui roteamento no nível de grupo e por binding).
|
||||
- `channels.telegram.groups.<id>.topics.<threadId>.groupPolicy`: substituição por tópico para `groupPolicy` (`open | allowlist | disabled`).
|
||||
- `channels.telegram.groups.<id>.topics.<threadId>.requireMention`: substituição por tópico para exigência de menção.
|
||||
- `bindings[]` no nível superior com `type: "acp"` e ID canônico de tópico `chatId:topic:topicId` em `match.peer.id`: campos de vínculo persistente de tópico ACP (veja [ACP Agents](/pt-BR/tools/acp-agents#channel-specific-settings)).
|
||||
- `channels.telegram.groups.<id>.topics.<threadId>.*`: sobrescritas por tópico (campos de grupo + `agentId` exclusivo de tópico).
|
||||
- `channels.telegram.groups.<id>.topics.<threadId>.agentId`: roteia este tópico para um agente específico (sobrescreve o roteamento no nível do grupo e de bindings).
|
||||
- `channels.telegram.groups.<id>.topics.<threadId>.groupPolicy`: sobrescrita por tópico para `groupPolicy` (`open | allowlist | disabled`).
|
||||
- `channels.telegram.groups.<id>.topics.<threadId>.requireMention`: sobrescrita por tópico para bloqueio por menção.
|
||||
- `bindings[]` de nível superior com `type: "acp"` e ID canônico de tópico `chatId:topic:topicId` em `match.peer.id`: campos de vinculação persistente de tópico ACP (veja [Agentes ACP](/pt-BR/tools/acp-agents#channel-specific-settings)).
|
||||
- `channels.telegram.direct.<id>.topics.<threadId>.agentId`: roteia tópicos de DM para um agente específico (mesmo comportamento de tópicos de fórum).
|
||||
- `channels.telegram.execApprovals.enabled`: habilita o Telegram como cliente de aprovação de exec baseado em chat para esta conta.
|
||||
- `channels.telegram.execApprovals.approvers`: IDs de usuários do Telegram autorizados a aprovar ou negar solicitações de exec. Opcional quando `channels.telegram.allowFrom` ou um `channels.telegram.defaultTo` direto já identifica o proprietário.
|
||||
- `channels.telegram.execApprovals.approvers`: IDs de usuários do Telegram autorizados a aprovar ou negar solicitações de exec. Opcional quando `channels.telegram.allowFrom` ou um `channels.telegram.defaultTo` direto já identifica o owner.
|
||||
- `channels.telegram.execApprovals.target`: `dm | channel | both` (padrão: `dm`). `channel` e `both` preservam o tópico de origem do Telegram quando presente.
|
||||
- `channels.telegram.execApprovals.agentFilter`: filtro opcional de ID de agente para prompts de aprovação encaminhados.
|
||||
- `channels.telegram.execApprovals.sessionFilter`: filtro opcional de chave de sessão (substring ou regex) para prompts de aprovação encaminhados.
|
||||
- `channels.telegram.accounts.<account>.execApprovals`: substituição por conta para roteamento de aprovação de exec no Telegram e autorização de aprovador.
|
||||
- `channels.telegram.execApprovals.agentFilter`: filtro opcional por ID de agente para prompts de aprovação encaminhados.
|
||||
- `channels.telegram.execApprovals.sessionFilter`: filtro opcional por chave de sessão (substring ou regex) para prompts de aprovação encaminhados.
|
||||
- `channels.telegram.accounts.<account>.execApprovals`: sobrescrita por conta para roteamento de aprovação de exec no Telegram e autorização de aprovadores.
|
||||
- `channels.telegram.capabilities.inlineButtons`: `off | dm | group | all | allowlist` (padrão: allowlist).
|
||||
- `channels.telegram.accounts.<account>.capabilities.inlineButtons`: substituição por conta.
|
||||
- `channels.telegram.accounts.<account>.capabilities.inlineButtons`: sobrescrita por conta.
|
||||
- `channels.telegram.commands.nativeSkills`: habilita/desabilita comandos nativos de Skills no Telegram.
|
||||
- `channels.telegram.replyToMode`: `off | first | all` (padrão: `off`).
|
||||
- `channels.telegram.textChunkLimit`: tamanho do chunk de saída (caracteres).
|
||||
- `channels.telegram.chunkMode`: `length` (padrão) ou `newline` para dividir em linhas em branco (limites de parágrafo) antes da divisão por comprimento.
|
||||
- `channels.telegram.linkPreview`: alterna pré-visualizações de links para mensagens de saída (padrão: true).
|
||||
- `channels.telegram.streaming`: `off | partial | block | progress` (pré-visualização de stream ao vivo; padrão: `partial`; `progress` é mapeado para `partial`; `block` é compatibilidade legada de modo de pré-visualização). O streaming de pré-visualização do Telegram usa uma única mensagem de pré-visualização que é editada no mesmo lugar.
|
||||
- `channels.telegram.mediaMaxMb`: limite de mídia do Telegram de entrada/saída (MB, padrão: 100).
|
||||
- `channels.telegram.retry`: política de repetição para auxiliares de envio do Telegram (CLI/ferramentas/ações) em erros recuperáveis da API de saída (attempts, minDelayMs, maxDelayMs, jitter).
|
||||
- `channels.telegram.network.autoSelectFamily`: substitui `autoSelectFamily` do Node (true=habilita, false=desabilita). O padrão é habilitado no Node 22+, com WSL2 tendo padrão desabilitado.
|
||||
- `channels.telegram.network.dnsResultOrder`: substitui a ordem de resultados DNS (`ipv4first` ou `verbatim`). O padrão é `ipv4first` no Node 22+.
|
||||
- `channels.telegram.network.dangerouslyAllowPrivateNetwork`: opt-in perigoso para ambientes confiáveis com fake-IP ou proxy transparente onde downloads de mídia do Telegram resolvem `api.telegram.org` para endereços privados/internos/de uso especial fora da permissão padrão da faixa de benchmark RFC 2544.
|
||||
- `channels.telegram.textChunkLimit`: tamanho dos blocos de saída (caracteres).
|
||||
- `channels.telegram.chunkMode`: `length` (padrão) ou `newline` para dividir em linhas em branco (limites de parágrafo) antes da divisão por tamanho.
|
||||
- `channels.telegram.linkPreview`: alterna prévias de link para mensagens de saída (padrão: true).
|
||||
- `channels.telegram.streaming`: `off | partial | block | progress` (prévia de streaming ao vivo; padrão: `partial`; `progress` corresponde a `partial`; `block` é compatibilidade legada com modo de prévia). O streaming de prévia no Telegram usa uma única mensagem de prévia que é editada no mesmo lugar.
|
||||
- `channels.telegram.streaming.preview.toolProgress`: reutiliza a mensagem de prévia ao vivo para atualizações de ferramenta/progresso quando o streaming de prévia está ativo (padrão: `true`). Defina `false` para manter mensagens separadas de ferramenta/progresso.
|
||||
- `channels.telegram.mediaMaxMb`: limite de mídia recebida/enviada no Telegram (MB, padrão: 100).
|
||||
- `channels.telegram.retry`: política de retry para helpers de envio do Telegram (CLI/ferramentas/ações) em erros recuperáveis de API de saída (tentativas, `minDelayMs`, `maxDelayMs`, jitter).
|
||||
- `channels.telegram.network.autoSelectFamily`: sobrescreve `autoSelectFamily` do Node (true=habilita, false=desabilita). O padrão é habilitado no Node 22+, com WSL2 tendo padrão desabilitado.
|
||||
- `channels.telegram.network.dnsResultOrder`: sobrescreve a ordem de resultado DNS (`ipv4first` ou `verbatim`). O padrão é `ipv4first` no Node 22+.
|
||||
- `channels.telegram.network.dangerouslyAllowPrivateNetwork`: habilitação perigosa opcional para ambientes confiáveis com fake-IP ou proxy transparente nos quais downloads de mídia do Telegram resolvem `api.telegram.org` para endereços privados/internos/de uso especial fora da permissão padrão do intervalo de benchmark RFC 2544.
|
||||
- `channels.telegram.proxy`: URL de proxy para chamadas da Bot API (SOCKS/HTTP).
|
||||
- `channels.telegram.webhookUrl`: habilita o modo Webhook (requer `channels.telegram.webhookSecret`).
|
||||
- `channels.telegram.webhookUrl`: habilita o modo Webhook (exige `channels.telegram.webhookSecret`).
|
||||
- `channels.telegram.webhookSecret`: segredo do Webhook (obrigatório quando `webhookUrl` está definido).
|
||||
- `channels.telegram.webhookPath`: caminho local do Webhook (padrão `/telegram-webhook`).
|
||||
- `channels.telegram.webhookHost`: host local de bind do Webhook (padrão `127.0.0.1`).
|
||||
- `channels.telegram.webhookPort`: porta local de bind do Webhook (padrão `8787`).
|
||||
- `channels.telegram.actions.reactions`: controla reações de ferramenta do Telegram.
|
||||
- `channels.telegram.actions.sendMessage`: controla envios de mensagens de ferramenta do Telegram.
|
||||
- `channels.telegram.actions.deleteMessage`: controla exclusões de mensagens de ferramenta do Telegram.
|
||||
- `channels.telegram.actions.sticker`: controla ações de sticker do Telegram — envio e busca (padrão: false).
|
||||
- `channels.telegram.actions.sendMessage`: controla envios de mensagem de ferramenta do Telegram.
|
||||
- `channels.telegram.actions.deleteMessage`: controla exclusões de mensagem de ferramenta do Telegram.
|
||||
- `channels.telegram.actions.sticker`: controla ações de sticker do Telegram — enviar e pesquisar (padrão: false).
|
||||
- `channels.telegram.reactionNotifications`: `off | own | all` — controla quais reações acionam eventos de sistema (padrão: `own` quando não definido).
|
||||
- `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` — controla a capacidade de reação do agente (padrão: `minimal` quando não definido).
|
||||
- `channels.telegram.errorPolicy`: `reply | silent` — controla o comportamento de resposta de erro (padrão: `reply`). Há suporte a substituições por conta/grupo/tópico.
|
||||
- `channels.telegram.errorPolicy`: `reply | silent` — controla o comportamento de resposta de erro (padrão: `reply`). Sobrescritas por conta/grupo/tópico são suportadas.
|
||||
- `channels.telegram.errorCooldownMs`: ms mínimos entre respostas de erro para o mesmo chat (padrão: `60000`). Evita spam de erros durante indisponibilidades.
|
||||
|
||||
- [Referência de configuração - Telegram](/pt-BR/gateway/configuration-reference#telegram)
|
||||
|
||||
Campos específicos do Telegram com alto sinal:
|
||||
Campos específicos do Telegram com maior sinal:
|
||||
|
||||
- inicialização/autenticação: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` deve apontar para um arquivo regular; symlinks são rejeitados)
|
||||
- controle de acesso: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, `bindings[]` no nível superior (`type: "acp"`)
|
||||
- controle de acesso: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, `bindings[]` de nível superior (`type: "acp"`)
|
||||
- aprovações de exec: `execApprovals`, `accounts.*.execApprovals`
|
||||
- comando/menu: `commands.native`, `commands.nativeSkills`, `customCommands`
|
||||
- threading/respostas: `replyToMode`
|
||||
- streaming: `streaming` (pré-visualização), `blockStreaming`
|
||||
- threads/respostas: `replyToMode`
|
||||
- streaming: `streaming` (prévia), `streaming.preview.toolProgress`, `blockStreaming`
|
||||
- formatação/entrega: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix`
|
||||
- mídia/rede: `mediaMaxMb`, `timeoutSeconds`, `pollingStallThresholdMs`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy`
|
||||
- Webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost`
|
||||
|
||||
@ -1,100 +1,129 @@
|
||||
---
|
||||
read_when:
|
||||
- Executando mais de um Gateway na mesma máquina
|
||||
- Você precisa de configuração/estado/portas isolados por Gateway
|
||||
summary: Executar vários Gateways do OpenClaw no mesmo host (isolamento, portas e perfis)
|
||||
- Você precisa de configuração/estado/portas isolados para cada Gateway
|
||||
summary: Executar vários Gateways do OpenClaw em um único host (isolamento, portas e perfis)
|
||||
title: Vários Gateways
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T12:41:51Z"
|
||||
generated_at: "2026-04-21T17:45:33Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 061f204bf56b28c6bd0e2c9aee6c561a8a162ca219060117fea4d3a007f01899
|
||||
source_hash: 8c3fcb921bc6596040e9249467964bd9dcd40ea7c16e958bb378247b0f994a7b
|
||||
source_path: gateway/multiple-gateways.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Vários Gateways (mesmo host)
|
||||
|
||||
A maioria das configurações deve usar um único Gateway, porque um único Gateway pode lidar com várias conexões de mensagens e agentes. Se você precisar de isolamento mais forte ou redundância (por exemplo, um bot de resgate), execute Gateways separados com perfis/portas isolados.
|
||||
A maioria das configurações deve usar um Gateway, porque um único Gateway pode lidar com várias conexões de mensageria e agents. Se você precisar de isolamento mais forte ou redundância (por exemplo, um bot de resgate), execute Gateways separados com perfis/portas isolados.
|
||||
|
||||
## Checklist de isolamento (obrigatório)
|
||||
## Lista de verificação de isolamento (obrigatória)
|
||||
|
||||
- `OPENCLAW_CONFIG_PATH` — arquivo de configuração por instância
|
||||
- `OPENCLAW_STATE_DIR` — sessões, credenciais, caches por instância
|
||||
- `OPENCLAW_STATE_DIR` — sessões, credenciais e caches por instância
|
||||
- `agents.defaults.workspace` — raiz de workspace por instância
|
||||
- `gateway.port` (ou `--port`) — única por instância
|
||||
- Portas derivadas (browser/canvas) não podem se sobrepor
|
||||
- `gateway.port` (ou `--port`) — exclusivo por instância
|
||||
- As portas derivadas (browser/canvas) não devem se sobrepor
|
||||
|
||||
Se esses itens forem compartilhados, você terá corridas de configuração e conflitos de porta.
|
||||
Se eles forem compartilhados, você terá condições de corrida de configuração e conflitos de porta.
|
||||
|
||||
## Recomendado: perfis (`--profile`)
|
||||
## Recomendado: use o perfil padrão para o principal e um perfil nomeado para o resgate
|
||||
|
||||
Perfis definem automaticamente o escopo de `OPENCLAW_STATE_DIR` + `OPENCLAW_CONFIG_PATH` e adicionam sufixos aos nomes dos serviços.
|
||||
Os perfis aplicam escopo automaticamente a `OPENCLAW_STATE_DIR` + `OPENCLAW_CONFIG_PATH` e adicionam sufixos aos nomes de serviço. Para a maioria das configurações com bot de resgate, mantenha o bot principal no perfil padrão e dê apenas ao bot de resgate um perfil nomeado, como `rescue`.
|
||||
|
||||
```bash
|
||||
# principal
|
||||
openclaw --profile main setup
|
||||
openclaw --profile main gateway --port 18789
|
||||
# principal (perfil padrão)
|
||||
openclaw setup
|
||||
openclaw gateway --port 18789
|
||||
|
||||
# resgate
|
||||
openclaw --profile rescue setup
|
||||
openclaw --profile rescue gateway --port 19001
|
||||
```
|
||||
|
||||
Serviços por perfil:
|
||||
Serviços:
|
||||
|
||||
```bash
|
||||
openclaw --profile main gateway install
|
||||
openclaw gateway install
|
||||
openclaw --profile rescue gateway install
|
||||
```
|
||||
|
||||
Se você quiser que ambos os Gateways usem perfis nomeados, isso também funciona, mas não é obrigatório.
|
||||
|
||||
## Guia do bot de resgate
|
||||
|
||||
Execute um segundo Gateway no mesmo host com seu próprio:
|
||||
Configuração recomendada:
|
||||
|
||||
- perfil/configuração
|
||||
- diretório de estado
|
||||
- workspace
|
||||
- porta base (mais as portas derivadas)
|
||||
- mantenha o bot principal no perfil padrão
|
||||
- execute o bot de resgate em `--profile rescue`
|
||||
- use um bot do Telegram completamente separado para a conta de resgate
|
||||
- mantenha o bot de resgate em uma porta base diferente, como `19001`
|
||||
|
||||
Isso mantém o bot de resgate isolado do bot principal, para que ele possa depurar ou aplicar alterações de configuração se o bot principal estiver fora do ar.
|
||||
Isso mantém o bot de resgate isolado do bot principal, para que ele possa depurar ou aplicar alterações de configuração se o bot principal estiver fora do ar. Deixe pelo menos 20 portas entre as portas base para que as portas derivadas de browser/canvas/CDP nunca colidam.
|
||||
|
||||
Espaçamento de portas: deixe pelo menos 20 portas entre as portas base para que as portas derivadas de browser/canvas/CDP nunca colidam.
|
||||
### Canal/conta de resgate recomendado
|
||||
|
||||
### Como instalar (bot de resgate)
|
||||
Para a maioria das configurações, use um bot do Telegram completamente separado para o perfil de resgate.
|
||||
|
||||
Por que Telegram:
|
||||
|
||||
- fácil de manter apenas para operadores
|
||||
- token e identidade de bot separados
|
||||
- independente do canal/da instalação do app do bot principal
|
||||
- caminho de recuperação simples baseado em DM quando o bot principal estiver com problema
|
||||
|
||||
A parte importante é a independência total: conta de bot separada, credenciais separadas, perfil do OpenClaw separado, workspace separado e porta separada.
|
||||
|
||||
### Fluxo de instalação recomendado
|
||||
|
||||
Use isto como configuração padrão, a menos que você tenha um motivo forte para fazer algo diferente:
|
||||
|
||||
```bash
|
||||
# Bot principal (existente ou novo, sem parâmetro --profile)
|
||||
# Executa na porta 18789 + portas do Chrome CDC/Canvas/...
|
||||
# Bot principal (perfil padrão, porta 18789)
|
||||
openclaw onboard
|
||||
openclaw gateway install
|
||||
|
||||
# Bot de resgate (perfil + portas isolados)
|
||||
# Bot de resgate (bot do Telegram separado, perfil separado, porta 19001)
|
||||
openclaw --profile rescue onboard
|
||||
# Observações:
|
||||
# - o nome do workspace receberá o sufixo -rescue por padrão
|
||||
# - A porta deve ser pelo menos 18789 + 20 portas,
|
||||
# é melhor escolher uma porta base completamente diferente, como 19789,
|
||||
# - o restante da configuração inicial é igual ao normal
|
||||
|
||||
# Para instalar o serviço (se isso não aconteceu automaticamente durante a configuração)
|
||||
openclaw --profile rescue gateway install
|
||||
```
|
||||
|
||||
## Mapeamento de portas (derivadas)
|
||||
Durante `openclaw --profile rescue onboard`:
|
||||
|
||||
- use o token do bot do Telegram separado
|
||||
- mantenha o perfil `rescue`
|
||||
- use uma porta base pelo menos 20 acima da do bot principal
|
||||
- aceite o workspace de resgate padrão, a menos que você já gerencie um por conta própria
|
||||
|
||||
Se o onboarding já tiver instalado o serviço de resgate para você, o `gateway install` final não será necessário.
|
||||
|
||||
### O que o onboarding altera
|
||||
|
||||
`openclaw --profile rescue onboard` usa o fluxo normal de onboarding, mas grava tudo em um perfil separado.
|
||||
|
||||
Na prática, isso significa que o bot de resgate recebe seu próprio:
|
||||
|
||||
- arquivo de configuração
|
||||
- diretório de estado
|
||||
- workspace (por padrão `~/.openclaw/workspace-rescue`)
|
||||
- nome de serviço gerenciado
|
||||
|
||||
Fora isso, os prompts são os mesmos do onboarding normal.
|
||||
|
||||
## Mapeamento de portas (derivado)
|
||||
|
||||
Porta base = `gateway.port` (ou `OPENCLAW_GATEWAY_PORT` / `--port`).
|
||||
|
||||
- porta do serviço de controle do navegador = base + 2 (somente loopback)
|
||||
- o host de canvas é servido no servidor HTTP do Gateway (mesma porta de `gateway.port`)
|
||||
- portas CDP do perfil do navegador são alocadas automaticamente a partir de `browser.controlPort + 9 .. + 108`
|
||||
- porta do serviço de controle do browser = base + 2 (apenas loopback local)
|
||||
- o host do canvas é servido no servidor HTTP do Gateway (mesma porta que `gateway.port`)
|
||||
- as portas CDP do perfil do browser são alocadas automaticamente a partir de `browser.controlPort + 9 .. + 108`
|
||||
|
||||
Se você substituir qualquer uma delas na configuração ou no ambiente, deverá mantê-las exclusivas por instância.
|
||||
Se você substituir qualquer um deles em config ou env, deve mantê-los exclusivos por instância.
|
||||
|
||||
## Observações sobre Browser/CDP (armadilha comum)
|
||||
## Observações sobre browser/CDP (armadilha comum)
|
||||
|
||||
- **Não** fixe `browser.cdpUrl` nos mesmos valores em várias instâncias.
|
||||
- Cada instância precisa de sua própria porta de controle do navegador e intervalo de CDP (derivados da porta do gateway).
|
||||
- Cada instância precisa de sua própria porta de controle do browser e de sua própria faixa de CDP (derivadas da porta do Gateway).
|
||||
- Se você precisar de portas CDP explícitas, defina `browser.profiles.<name>.cdpPort` por instância.
|
||||
- Chrome remoto: use `browser.profiles.<name>.cdpUrl` (por perfil, por instância).
|
||||
|
||||
@ -102,7 +131,7 @@ Se você substituir qualquer uma delas na configuração ou no ambiente, deverá
|
||||
|
||||
```bash
|
||||
OPENCLAW_CONFIG_PATH=~/.openclaw/main.json \
|
||||
OPENCLAW_STATE_DIR=~/.openclaw-main \
|
||||
OPENCLAW_STATE_DIR=~/.openclaw \
|
||||
openclaw gateway --port 18789
|
||||
|
||||
OPENCLAW_CONFIG_PATH=~/.openclaw/rescue.json \
|
||||
@ -113,15 +142,15 @@ openclaw gateway --port 19001
|
||||
## Verificações rápidas
|
||||
|
||||
```bash
|
||||
openclaw --profile main gateway status --deep
|
||||
openclaw gateway status --deep
|
||||
openclaw --profile rescue gateway status --deep
|
||||
openclaw --profile rescue gateway probe
|
||||
openclaw --profile main status
|
||||
openclaw status
|
||||
openclaw --profile rescue status
|
||||
openclaw --profile rescue browser status
|
||||
```
|
||||
|
||||
Interpretação:
|
||||
|
||||
- `gateway status --deep` ajuda a detectar serviços launchd/systemd/schtasks desatualizados de instalações mais antigas.
|
||||
- `gateway status --deep` ajuda a detectar serviços launchd/systemd/schtasks antigos de instalações anteriores.
|
||||
- O texto de aviso de `gateway probe`, como `multiple reachable gateways detected`, é esperado apenas quando você executa intencionalmente mais de um gateway isolado.
|
||||
|
||||
@ -2,35 +2,35 @@
|
||||
read_when:
|
||||
- Usando ou configurando comandos de chat
|
||||
- Depurando o roteamento de comandos ou permissões
|
||||
summary: 'Comandos slash: texto vs nativo, configuração e comandos compatíveis'
|
||||
title: Comandos slash
|
||||
summary: 'Comandos de barra: texto vs nativos, configuração e comandos compatíveis'
|
||||
title: Comandos de barra
|
||||
x-i18n:
|
||||
generated_at: "2026-04-21T13:39:21Z"
|
||||
generated_at: "2026-04-21T17:45:33Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: d90ddee54af7c05b7fdf486590561084581d750e42cd14674d43bbdc0984df5d
|
||||
source_hash: 26923608329ba2aeece2d4bc8edfa40ae86e03719a9f590f26ff79f57d97521d
|
||||
source_path: tools/slash-commands.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Comandos slash
|
||||
# Comandos de barra
|
||||
|
||||
Os comandos são tratados pelo Gateway. A maioria dos comandos deve ser enviada como uma mensagem **autônoma** que começa com `/`.
|
||||
O comando de chat bash somente-host usa `! <cmd>` (com `/bash <cmd>` como alias).
|
||||
O comando de chat bash somente do host usa `! <cmd>` (com `/bash <cmd>` como alias).
|
||||
|
||||
Existem dois sistemas relacionados:
|
||||
Há dois sistemas relacionados:
|
||||
|
||||
- **Comandos**: mensagens autônomas `/...`.
|
||||
- **Diretivas**: `/think`, `/fast`, `/verbose`, `/trace`, `/reasoning`, `/elevated`, `/exec`, `/model`, `/queue`.
|
||||
- As diretivas são removidas da mensagem antes que o modelo a veja.
|
||||
- Em mensagens normais de chat (não somente-diretiva), elas são tratadas como “dicas inline” e **não** persistem configurações da sessão.
|
||||
- Em mensagens somente-diretiva (a mensagem contém apenas diretivas), elas persistem na sessão e respondem com uma confirmação.
|
||||
- As diretivas são aplicadas apenas para **remetentes autorizados**. Se `commands.allowFrom` estiver definido, ele será a única
|
||||
lista de permissões usada; caso contrário, a autorização virá das listas de permissões/pareamento do canal mais `commands.useAccessGroups`.
|
||||
Remetentes não autorizados verão as diretivas tratadas como texto simples.
|
||||
- Em mensagens normais de chat (não apenas com diretivas), elas são tratadas como “dicas inline” e **não** persistem as configurações da sessão.
|
||||
- Em mensagens somente com diretivas (a mensagem contém apenas diretivas), elas persistem na sessão e respondem com uma confirmação.
|
||||
- As diretivas só são aplicadas para **remetentes autorizados**. Se `commands.allowFrom` estiver definido, ele será a única
|
||||
allowlist usada; caso contrário, a autorização vem das allowlists/emparelhamento do canal mais `commands.useAccessGroups`.
|
||||
Remetentes não autorizados veem as diretivas tratadas como texto simples.
|
||||
|
||||
Também há alguns **atalhos inline** (somente remetentes em lista de permissões/autorizados): `/help`, `/commands`, `/status`, `/whoami` (`/id`).
|
||||
Eles são executados imediatamente, são removidos antes que o modelo veja a mensagem, e o texto restante continua pelo fluxo normal.
|
||||
Também há alguns **atalhos inline** (somente remetentes autorizados/na allowlist): `/help`, `/commands`, `/status`, `/whoami` (`/id`).
|
||||
Eles são executados imediatamente, removidos antes que o modelo veja a mensagem, e o texto restante continua pelo fluxo normal.
|
||||
|
||||
## Configuração
|
||||
|
||||
@ -59,109 +59,110 @@ Eles são executados imediatamente, são removidos antes que o modelo veja a men
|
||||
}
|
||||
```
|
||||
|
||||
- `commands.text` (padrão `true`) habilita o parsing de `/...` em mensagens de chat.
|
||||
- Em superfícies sem comandos nativos (WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams), os comandos de texto continuam funcionando mesmo que você defina isso como `false`.
|
||||
- `commands.text` (padrão `true`) ativa a análise de `/...` em mensagens de chat.
|
||||
- Em superfícies sem comandos nativos (WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams), os comandos de texto ainda funcionam mesmo se você definir isso como `false`.
|
||||
- `commands.native` (padrão `"auto"`) registra comandos nativos.
|
||||
- Auto: ligado para Discord/Telegram; desligado para Slack (até você adicionar comandos slash); ignorado para provedores sem suporte nativo.
|
||||
- Auto: ligado para Discord/Telegram; desligado para Slack (até você adicionar slash commands); ignorado para provedores sem suporte nativo.
|
||||
- Defina `channels.discord.commands.native`, `channels.telegram.commands.native` ou `channels.slack.commands.native` para substituir por provedor (bool ou `"auto"`).
|
||||
- `false` limpa comandos registrados anteriormente no Discord/Telegram na inicialização. Os comandos do Slack são gerenciados no app Slack e não são removidos automaticamente.
|
||||
- `commands.nativeSkills` (padrão `"auto"`) registra comandos de **skill** nativamente quando compatível.
|
||||
- Auto: ligado para Discord/Telegram; desligado para Slack (o Slack exige criar um comando slash por skill).
|
||||
- `false` limpa comandos registrados anteriormente no Discord/Telegram na inicialização. Os comandos do Slack são gerenciados no app do Slack e não são removidos automaticamente.
|
||||
- `commands.nativeSkills` (padrão `"auto"`) registra comandos de **skill** de forma nativa quando houver suporte.
|
||||
- Auto: ligado para Discord/Telegram; desligado para Slack (o Slack exige a criação de um slash command por skill).
|
||||
- Defina `channels.discord.commands.nativeSkills`, `channels.telegram.commands.nativeSkills` ou `channels.slack.commands.nativeSkills` para substituir por provedor (bool ou `"auto"`).
|
||||
- `commands.bash` (padrão `false`) habilita `! <cmd>` para executar comandos de shell no host (`/bash <cmd>` é um alias; exige listas de permissões de `tools.elevated`).
|
||||
- `commands.bashForegroundMs` (padrão `2000`) controla por quanto tempo o bash espera antes de mudar para o modo em segundo plano (`0` envia para segundo plano imediatamente).
|
||||
- `commands.config` (padrão `false`) habilita `/config` (lê/grava `openclaw.json`).
|
||||
- `commands.mcp` (padrão `false`) habilita `/mcp` (lê/grava a configuração de MCP gerenciada pelo OpenClaw em `mcp.servers`).
|
||||
- `commands.plugins` (padrão `false`) habilita `/plugins` (descoberta/status de Plugin mais controles de instalar + habilitar/desabilitar).
|
||||
- `commands.debug` (padrão `false`) habilita `/debug` (substituições somente de runtime).
|
||||
- `commands.restart` (padrão `true`) habilita `/restart` mais ações de ferramenta de reinicialização do Gateway.
|
||||
- `commands.ownerAllowFrom` (opcional) define a lista de permissões explícita de owner para superfícies de comando/ferramenta exclusivas do owner. Isso é separado de `commands.allowFrom`.
|
||||
- `commands.ownerDisplay` controla como ids de owner aparecem no prompt de sistema: `raw` ou `hash`.
|
||||
- `commands.bash` (padrão `false`) ativa `! <cmd>` para executar comandos do shell do host (`/bash <cmd>` é um alias; requer allowlists de `tools.elevated`).
|
||||
- `commands.bashForegroundMs` (padrão `2000`) controla quanto tempo o bash espera antes de mudar para o modo em segundo plano (`0` envia para segundo plano imediatamente).
|
||||
- `commands.config` (padrão `false`) ativa `/config` (lê/grava `openclaw.json`).
|
||||
- `commands.mcp` (padrão `false`) ativa `/mcp` (lê/grava a configuração de MCP gerenciada pelo OpenClaw em `mcp.servers`).
|
||||
- `commands.plugins` (padrão `false`) ativa `/plugins` (descoberta/status de plugins mais controles de instalar + ativar/desativar).
|
||||
- `commands.debug` (padrão `false`) ativa `/debug` (substituições somente de runtime).
|
||||
- `commands.restart` (padrão `true`) ativa `/restart` mais ações de ferramenta para reiniciar o gateway.
|
||||
- `commands.ownerAllowFrom` (opcional) define a allowlist explícita do proprietário para superfícies de comandos/ferramentas exclusivas do proprietário. Isso é separado de `commands.allowFrom`.
|
||||
- `commands.ownerDisplay` controla como os ids do proprietário aparecem no prompt do sistema: `raw` ou `hash`.
|
||||
- `commands.ownerDisplaySecret` opcionalmente define o segredo HMAC usado quando `commands.ownerDisplay="hash"`.
|
||||
- `commands.allowFrom` (opcional) define uma lista de permissões por provedor para autorização de comandos. Quando configurado, ela é a
|
||||
única fonte de autorização para comandos e diretivas (listas de permissões/pareamento do canal e `commands.useAccessGroups`
|
||||
são ignorados). Use `"*"` para um padrão global; chaves específicas de provedor o substituem.
|
||||
- `commands.useAccessGroups` (padrão `true`) aplica listas de permissões/políticas para comandos quando `commands.allowFrom` não está definido.
|
||||
- `commands.allowFrom` (opcional) define uma allowlist por provedor para autorização de comandos. Quando configurado, ela é a
|
||||
única fonte de autorização para comandos e diretivas (allowlists/emparelhamento do canal e `commands.useAccessGroups`
|
||||
são ignorados). Use `"*"` para um padrão global; chaves específicas do provedor têm precedência.
|
||||
- `commands.useAccessGroups` (padrão `true`) aplica allowlists/políticas para comandos quando `commands.allowFrom` não está definido.
|
||||
|
||||
## Lista de comandos
|
||||
|
||||
Fonte de verdade atual:
|
||||
Fonte da verdade atual:
|
||||
|
||||
- comandos embutidos do núcleo vêm de `src/auto-reply/commands-registry.shared.ts`
|
||||
- comandos dock gerados vêm de `src/auto-reply/commands-registry.data.ts`
|
||||
- comandos de Plugin vêm de chamadas `registerCommand()` do Plugin
|
||||
- a disponibilidade real no seu Gateway ainda depende de flags de configuração, superfície do canal e Plugins instalados/habilitados
|
||||
- os comandos embutidos do núcleo vêm de `src/auto-reply/commands-registry.shared.ts`
|
||||
- os comandos dock gerados vêm de `src/auto-reply/commands-registry.data.ts`
|
||||
- os comandos de plugins vêm de chamadas `registerCommand()` do plugin
|
||||
- a disponibilidade real no seu gateway ainda depende de flags de configuração, superfície do canal e plugins instalados/ativados
|
||||
|
||||
### Comandos embutidos do núcleo
|
||||
|
||||
Comandos embutidos disponíveis hoje:
|
||||
|
||||
- `/new [model]` inicia uma nova sessão; `/reset` é o alias de redefinição.
|
||||
- `/compact [instructions]` faz Compaction do contexto da sessão. Consulte [/concepts/compaction](/pt-BR/concepts/compaction).
|
||||
- `/stop` aborta a execução atual.
|
||||
- `/session idle <duration|off>` e `/session max-age <duration|off>` gerenciam a expiração do vínculo de thread.
|
||||
- `/think <level>` define o nível de thinking. As opções vêm do perfil do provedor do modelo ativo; níveis comuns são `off`, `minimal`, `low`, `medium` e `high`, com níveis personalizados como `xhigh`, `adaptive`, `max` ou `on` binário apenas onde houver suporte. Aliases: `/thinking`, `/t`.
|
||||
- `/reset soft [message]` mantém a transcrição atual, descarta ids de sessão reutilizados do backend CLI e executa novamente, no lugar, o carregamento inicial/de prompt do sistema.
|
||||
- `/compact [instructions]` compacta o contexto da sessão. Veja [/concepts/compaction](/pt-BR/concepts/compaction).
|
||||
- `/stop` interrompe a execução atual.
|
||||
- `/session idle <duration|off>` e `/session max-age <duration|off>` gerenciam a expiração do vínculo da thread.
|
||||
- `/think <level>` define o nível de raciocínio. As opções vêm do perfil do provedor do modelo ativo; níveis comuns são `off`, `minimal`, `low`, `medium` e `high`, com níveis personalizados como `xhigh`, `adaptive`, `max` ou apenas binário `on` quando houver suporte. Aliases: `/thinking`, `/t`.
|
||||
- `/verbose on|off|full` alterna a saída detalhada. Alias: `/v`.
|
||||
- `/trace on|off` alterna a saída de rastreamento de Plugin para a sessão atual.
|
||||
- `/trace on|off` alterna a saída de rastreamento de plugin para a sessão atual.
|
||||
- `/fast [status|on|off]` mostra ou define o modo rápido.
|
||||
- `/reasoning [on|off|stream]` alterna a visibilidade de reasoning. Alias: `/reason`.
|
||||
- `/reasoning [on|off|stream]` alterna a visibilidade do raciocínio. Alias: `/reason`.
|
||||
- `/elevated [on|off|ask|full]` alterna o modo elevado. Alias: `/elev`.
|
||||
- `/exec host=<auto|sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>` mostra ou define padrões de exec.
|
||||
- `/exec host=<auto|sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>` mostra ou define os padrões de execução.
|
||||
- `/model [name|#|status]` mostra ou define o modelo.
|
||||
- `/models [provider] [page] [limit=<n>|size=<n>|all]` lista provedores ou modelos de um provedor.
|
||||
- `/queue <mode>` gerencia o comportamento da fila (`steer`, `interrupt`, `followup`, `collect`, `steer-backlog`) mais opções como `debounce:2s cap:25 drop:summarize`.
|
||||
- `/help` mostra o resumo curto de ajuda.
|
||||
- `/commands` mostra o catálogo de comandos gerado.
|
||||
- `/tools [compact|verbose]` mostra o que o agente atual pode usar agora.
|
||||
- `/status` mostra o status do runtime, incluindo uso/quota do provedor quando disponível.
|
||||
- `/tasks` lista tarefas ativas/recentes em segundo plano da sessão atual.
|
||||
- `/tools [compact|verbose]` mostra o que o agente atual pode usar neste momento.
|
||||
- `/status` mostra o status do runtime, incluindo uso/cota do provedor quando disponível.
|
||||
- `/tasks` lista tarefas em segundo plano ativas/recentes para a sessão atual.
|
||||
- `/context [list|detail|json]` explica como o contexto é montado.
|
||||
- `/export-session [path]` exporta a sessão atual para HTML. Alias: `/export`.
|
||||
- `/whoami` mostra seu id de remetente. Alias: `/id`.
|
||||
- `/skill <name> [input]` executa uma skill pelo nome.
|
||||
- `/allowlist [list|add|remove] ...` gerencia entradas da lista de permissões. Somente texto.
|
||||
- `/approve <id> <decision>` resolve prompts de aprovação do exec.
|
||||
- `/btw <question>` faz uma pergunta lateral sem alterar o contexto futuro da sessão. Consulte [/tools/btw](/pt-BR/tools/btw).
|
||||
- `/subagents list|kill|log|info|send|steer|spawn` gerencia execuções de subagentes da sessão atual.
|
||||
- `/allowlist [list|add|remove] ...` gerencia entradas da allowlist. Somente texto.
|
||||
- `/approve <id> <decision>` resolve prompts de aprovação de execução.
|
||||
- `/btw <question>` faz uma pergunta paralela sem alterar o contexto futuro da sessão. Veja [/tools/btw](/pt-BR/tools/btw).
|
||||
- `/subagents list|kill|log|info|send|steer|spawn` gerencia execuções de subagentes para a sessão atual.
|
||||
- `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` gerencia sessões ACP e opções de runtime.
|
||||
- `/focus <target>` vincula a thread atual do Discord ou tópico/conversa do Telegram a um destino de sessão.
|
||||
- `/focus <target>` vincula a thread atual do Discord ou o tópico/conversa do Telegram a um alvo de sessão.
|
||||
- `/unfocus` remove o vínculo atual.
|
||||
- `/agents` lista agentes vinculados à thread da sessão atual.
|
||||
- `/kill <id|#|all>` aborta um ou todos os subagentes em execução.
|
||||
- `/agents` lista agentes vinculados à thread para a sessão atual.
|
||||
- `/kill <id|#|all>` interrompe um ou todos os subagentes em execução.
|
||||
- `/steer <id|#> <message>` envia direcionamento para um subagente em execução. Alias: `/tell`.
|
||||
- `/config show|get|set|unset` lê ou grava `openclaw.json`. Somente owner. Exige `commands.config: true`.
|
||||
- `/mcp show|get|set|unset` lê ou grava a configuração de servidor MCP gerenciada pelo OpenClaw em `mcp.servers`. Somente owner. Exige `commands.mcp: true`.
|
||||
- `/plugins list|inspect|show|get|install|enable|disable` inspeciona ou altera o estado do Plugin. `/plugin` é um alias. Somente owner para gravações. Exige `commands.plugins: true`.
|
||||
- `/debug show|set|unset|reset` gerencia substituições de configuração somente de runtime. Somente owner. Exige `commands.debug: true`.
|
||||
- `/config show|get|set|unset` lê ou grava `openclaw.json`. Somente proprietário. Requer `commands.config: true`.
|
||||
- `/mcp show|get|set|unset` lê ou grava a configuração do servidor MCP gerenciada pelo OpenClaw em `mcp.servers`. Somente proprietário. Requer `commands.mcp: true`.
|
||||
- `/plugins list|inspect|show|get|install|enable|disable` inspeciona ou altera o estado do plugin. `/plugin` é um alias. Somente proprietário para gravações. Requer `commands.plugins: true`.
|
||||
- `/debug show|set|unset|reset` gerencia substituições de configuração somente de runtime. Somente proprietário. Requer `commands.debug: true`.
|
||||
- `/usage off|tokens|full|cost` controla o rodapé de uso por resposta ou imprime um resumo local de custo.
|
||||
- `/tts on|off|status|provider|limit|summary|audio|help` controla TTS. Consulte [/tools/tts](/pt-BR/tools/tts).
|
||||
- `/restart` reinicia o OpenClaw quando habilitado. Padrão: habilitado; defina `commands.restart: false` para desabilitá-lo.
|
||||
- `/activation mention|always` define o modo de ativação de grupo.
|
||||
- `/send on|off|inherit` define a política de envio. Somente owner.
|
||||
- `/bash <command>` executa um comando de shell no host. Somente texto. Alias: `! <command>`. Exige `commands.bash: true` mais listas de permissões de `tools.elevated`.
|
||||
- `/tts on|off|status|provider|limit|summary|audio|help` controla TTS. Veja [/tools/tts](/pt-BR/tools/tts).
|
||||
- `/restart` reinicia o OpenClaw quando ativado. Padrão: ativado; defina `commands.restart: false` para desativá-lo.
|
||||
- `/activation mention|always` define o modo de ativação em grupo.
|
||||
- `/send on|off|inherit` define a política de envio. Somente proprietário.
|
||||
- `/bash <command>` executa um comando do shell do host. Somente texto. Alias: `! <command>`. Requer `commands.bash: true` mais allowlists de `tools.elevated`.
|
||||
- `!poll [sessionId]` verifica um trabalho bash em segundo plano.
|
||||
- `!stop [sessionId]` interrompe um trabalho bash em segundo plano.
|
||||
|
||||
### Comandos dock gerados
|
||||
|
||||
Comandos dock são gerados a partir de Plugins de canal com suporte a comando nativo. Conjunto incluído atual:
|
||||
Os comandos dock são gerados a partir de plugins de canal com suporte a comandos nativos. Conjunto empacotado atual:
|
||||
|
||||
- `/dock-discord` (alias: `/dock_discord`)
|
||||
- `/dock-mattermost` (alias: `/dock_mattermost`)
|
||||
- `/dock-slack` (alias: `/dock_slack`)
|
||||
- `/dock-telegram` (alias: `/dock_telegram`)
|
||||
|
||||
### Comandos de Plugin incluídos
|
||||
### Comandos de plugins empacotados
|
||||
|
||||
Plugins incluídos podem adicionar mais comandos slash. Comandos incluídos atuais neste repositório:
|
||||
Os plugins empacotados podem adicionar mais slash commands. Comandos empacotados atuais neste repositório:
|
||||
|
||||
- `/dreaming [on|off|status|help]` alterna Dreaming de memória. Consulte [Dreaming](/pt-BR/concepts/dreaming).
|
||||
- `/pair [qr|status|pending|approve|cleanup|notify]` gerencia o fluxo de pareamento/configuração de dispositivo. Consulte [Pairing](/pt-BR/channels/pairing).
|
||||
- `/phone status|arm <camera|screen|writes|all> [duration]|disarm` arma temporariamente comandos de alto risco do node de telefone.
|
||||
- `/dreaming [on|off|status|help]` alterna o dreaming de memória. Veja [Dreaming](/pt-BR/concepts/dreaming).
|
||||
- `/pair [qr|status|pending|approve|cleanup|notify]` gerencia o fluxo de emparelhamento/configuração do dispositivo. Veja [Pairing](/pt-BR/channels/pairing).
|
||||
- `/phone status|arm <camera|screen|writes|all> [duration]|disarm` arma temporariamente comandos de Node do telefone de alto risco.
|
||||
- `/voice status|list [limit]|set <voiceId|name>` gerencia a configuração de voz do Talk. No Discord, o nome do comando nativo é `/talkvoice`.
|
||||
- `/card ...` envia presets de rich card do LINE. Consulte [LINE](/pt-BR/channels/line).
|
||||
- `/codex status|models|threads|resume|compact|review|account|mcp|skills` inspeciona e controla o harness do app-server Codex incluído. Consulte [Codex Harness](/pt-BR/plugins/codex-harness).
|
||||
- Comandos somente de QQBot:
|
||||
- `/card ...` envia predefinições de rich card do LINE. Veja [LINE](/pt-BR/channels/line).
|
||||
- `/codex status|models|threads|resume|compact|review|account|mcp|skills` inspeciona e controla o harness app-server Codex empacotado. Veja [Codex Harness](/pt-BR/plugins/codex-harness).
|
||||
- Comandos somente do QQBot:
|
||||
- `/bot-ping`
|
||||
- `/bot-version`
|
||||
- `/bot-help`
|
||||
@ -170,71 +171,71 @@ Plugins incluídos podem adicionar mais comandos slash. Comandos incluídos atua
|
||||
|
||||
### Comandos dinâmicos de skill
|
||||
|
||||
Skills invocáveis por usuário também são expostas como comandos slash:
|
||||
As skills invocáveis pelo usuário também são expostas como slash commands:
|
||||
|
||||
- `/skill <name> [input]` sempre funciona como ponto de entrada genérico.
|
||||
- skills também podem aparecer como comandos diretos como `/prose` quando a skill/Plugin os registra.
|
||||
- `/skill <name> [input]` sempre funciona como o ponto de entrada genérico.
|
||||
- as skills também podem aparecer como comandos diretos como `/prose` quando a skill/o plugin os registra.
|
||||
- o registro nativo de comandos de skill é controlado por `commands.nativeSkills` e `channels.<provider>.commands.nativeSkills`.
|
||||
|
||||
Observações:
|
||||
Notas:
|
||||
|
||||
- Os comandos aceitam um `:` opcional entre o comando e os argumentos (ex.: `/think: high`, `/send: on`, `/help:`).
|
||||
- `/new <model>` aceita um alias de modelo, `provider/model` ou um nome de provedor (correspondência aproximada); se não houver correspondência, o texto será tratado como corpo da mensagem.
|
||||
- Para a divisão completa de uso por provedor, use `openclaw status --usage`.
|
||||
- `/allowlist add|remove` exige `commands.config=true` e respeita `configWrites` do canal.
|
||||
- Em canais com múltiplas contas, `/allowlist --account <id>` direcionado à configuração e `/config set channels.<provider>.accounts.<id>...` também respeitam `configWrites` da conta de destino.
|
||||
- Os comandos aceitam um `:` opcional entre o comando e os args (por exemplo, `/think: high`, `/send: on`, `/help:`).
|
||||
- `/new <model>` aceita um alias de modelo, `provider/model` ou um nome de provedor (correspondência difusa); se não houver correspondência, o texto é tratado como o corpo da mensagem.
|
||||
- Para o detalhamento completo de uso por provedor, use `openclaw status --usage`.
|
||||
- `/allowlist add|remove` requer `commands.config=true` e respeita `configWrites` do canal.
|
||||
- Em canais com várias contas, `/allowlist --account <id>` direcionado à configuração e `/config set channels.<provider>.accounts.<id>...` também respeitam `configWrites` da conta de destino.
|
||||
- `/usage` controla o rodapé de uso por resposta; `/usage cost` imprime um resumo local de custo a partir dos logs de sessão do OpenClaw.
|
||||
- `/restart` vem habilitado por padrão; defina `commands.restart: false` para desabilitá-lo.
|
||||
- `/plugins install <spec>` aceita as mesmas especificações de Plugin que `openclaw plugins install`: caminho/arquivo local, pacote npm ou `clawhub:<pkg>`.
|
||||
- `/plugins enable|disable` atualiza a configuração do Plugin e pode solicitar uma reinicialização.
|
||||
- Comando nativo somente do Discord: `/vc join|leave|status` controla canais de voz (exige `channels.discord.voice` e comandos nativos; não disponível como texto).
|
||||
- Comandos de vínculo de thread do Discord (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`) exigem que vínculos de thread efetivos estejam habilitados (`session.threadBindings.enabled` e/ou `channels.discord.threadBindings.enabled`).
|
||||
- Referência de comando ACP e comportamento de runtime: [Agentes ACP](/pt-BR/tools/acp-agents).
|
||||
- `/verbose` é voltado para depuração e visibilidade extra; mantenha-o **desligado** no uso normal.
|
||||
- `/trace` é mais restrito que `/verbose`: ele revela apenas linhas de trace/debug do Plugin e mantém desativado o chatter normal e detalhado de ferramentas.
|
||||
- `/fast on|off` persiste uma substituição de sessão. Use a opção `inherit` da UI de Sessions para limpá-la e voltar aos padrões da configuração.
|
||||
- `/fast` é específico do provedor: OpenAI/OpenAI Codex o mapeiam para `service_tier=priority` em endpoints nativos de Responses, enquanto solicitações Anthropic públicas diretas, incluindo tráfego autenticado por OAuth enviado a `api.anthropic.com`, o mapeiam para `service_tier=auto` ou `standard_only`. Consulte [OpenAI](/pt-BR/providers/openai) e [Anthropic](/pt-BR/providers/anthropic).
|
||||
- Resumos de falha de ferramenta continuam sendo mostrados quando relevantes, mas o texto detalhado da falha só é incluído quando `/verbose` está `on` ou `full`.
|
||||
- `/reasoning`, `/verbose` e `/trace` são arriscados em configurações de grupo: podem revelar reasoning interno, saída de ferramenta ou diagnósticos de Plugin que você não pretendia expor. Prefira mantê-los desligados, especialmente em chats em grupo.
|
||||
- `/restart` é ativado por padrão; defina `commands.restart: false` para desativá-lo.
|
||||
- `/plugins install <spec>` aceita as mesmas especificações de plugin que `openclaw plugins install`: caminho/arquivo local, pacote npm ou `clawhub:<pkg>`.
|
||||
- `/plugins enable|disable` atualiza a configuração do plugin e pode solicitar um reinício.
|
||||
- Comando nativo somente do Discord: `/vc join|leave|status` controla canais de voz (requer `channels.discord.voice` e comandos nativos; não disponível como texto).
|
||||
- Os comandos de vínculo de thread do Discord (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`) exigem que os vínculos de thread efetivos estejam ativados (`session.threadBindings.enabled` e/ou `channels.discord.threadBindings.enabled`).
|
||||
- Referência do comando ACP e comportamento de runtime: [ACP Agents](/pt-BR/tools/acp-agents).
|
||||
- `/verbose` é destinado a depuração e visibilidade extra; mantenha-o **desativado** no uso normal.
|
||||
- `/trace` é mais restrito que `/verbose`: ele apenas revela linhas de rastreamento/depuração pertencentes ao plugin e mantém desativado o chatter normal detalhado de ferramentas.
|
||||
- `/fast on|off` persiste uma substituição da sessão. Use a opção `inherit` da UI de Sessões para limpá-la e voltar aos padrões da configuração.
|
||||
- `/fast` é específico por provedor: OpenAI/OpenAI Codex o mapeiam para `service_tier=priority` em endpoints nativos Responses, enquanto solicitações públicas diretas para Anthropic, incluindo tráfego autenticado por OAuth enviado para `api.anthropic.com`, o mapeiam para `service_tier=auto` ou `standard_only`. Veja [OpenAI](/pt-BR/providers/openai) e [Anthropic](/pt-BR/providers/anthropic).
|
||||
- Resumos de falha de ferramenta ainda são mostrados quando relevantes, mas o texto detalhado da falha só é incluído quando `/verbose` está `on` ou `full`.
|
||||
- `/reasoning`, `/verbose` e `/trace` são arriscados em ambientes de grupo: podem revelar raciocínio interno, saída de ferramenta ou diagnósticos de plugin que você não pretendia expor. Prefira deixá-los desativados, especialmente em chats de grupo.
|
||||
- `/model` persiste imediatamente o novo modelo da sessão.
|
||||
- Se o agente estiver ocioso, a próxima execução o usará imediatamente.
|
||||
- Se uma execução já estiver ativa, o OpenClaw marca uma troca ao vivo como pendente e só reinicia com o novo modelo em um ponto limpo de nova tentativa.
|
||||
- Se a atividade de ferramenta ou a saída de resposta já tiver começado, a troca pendente pode permanecer em fila até uma oportunidade posterior de nova tentativa ou até o próximo turno do usuário.
|
||||
- **Caminho rápido:** mensagens somente-comando de remetentes em lista de permissões são tratadas imediatamente (ignorando fila + modelo).
|
||||
- **Bloqueio por menção em grupo:** mensagens somente-comando de remetentes em lista de permissões ignoram exigências de menção.
|
||||
- **Atalhos inline (somente remetentes em lista de permissões):** certos comandos também funcionam quando embutidos em uma mensagem normal e são removidos antes que o modelo veja o texto restante.
|
||||
- Se a atividade de ferramenta ou a saída da resposta já tiver começado, a troca pendente pode permanecer na fila até uma oportunidade posterior de nova tentativa ou o próximo turno do usuário.
|
||||
- **Caminho rápido:** mensagens somente com comandos de remetentes na allowlist são tratadas imediatamente (ignorando fila + modelo).
|
||||
- **Bloqueio por menção em grupo:** mensagens somente com comandos de remetentes na allowlist ignoram requisitos de menção.
|
||||
- **Atalhos inline (somente remetentes na allowlist):** certos comandos também funcionam quando incorporados em uma mensagem normal e são removidos antes que o modelo veja o restante do texto.
|
||||
- Exemplo: `hey /status` aciona uma resposta de status, e o texto restante continua pelo fluxo normal.
|
||||
- Atualmente: `/help`, `/commands`, `/status`, `/whoami` (`/id`).
|
||||
- Mensagens somente-comando não autorizadas são ignoradas silenciosamente, e tokens inline `/...` são tratados como texto simples.
|
||||
- **Comandos de skill:** Skills `user-invocable` são expostas como comandos slash. Os nomes são sanitizados para `a-z0-9_` (máx. 32 caracteres); colisões recebem sufixos numéricos (ex.: `_2`).
|
||||
- `/skill <name> [input]` executa uma skill pelo nome (útil quando limites de comando nativo impedem comandos por skill).
|
||||
- Mensagens somente com comandos não autorizadas são ignoradas silenciosamente, e tokens inline `/...` são tratados como texto simples.
|
||||
- **Comandos de skill:** skills `user-invocable` são expostas como slash commands. Os nomes são sanitizados para `a-z0-9_` (máx. 32 caracteres); colisões recebem sufixos numéricos (por exemplo, `_2`).
|
||||
- `/skill <name> [input]` executa uma skill pelo nome (útil quando limites de comandos nativos impedem comandos por skill).
|
||||
- Por padrão, comandos de skill são encaminhados ao modelo como uma solicitação normal.
|
||||
- Skills podem opcionalmente declarar `command-dispatch: tool` para rotear o comando diretamente para uma ferramenta (determinístico, sem modelo).
|
||||
- Exemplo: `/prose` (Plugin OpenProse) — consulte [OpenProse](/pt-BR/prose).
|
||||
- **Argumentos de comando nativo:** o Discord usa autocomplete para opções dinâmicas (e menus de botão quando você omite argumentos obrigatórios). Telegram e Slack mostram um menu de botões quando um comando oferece opções e você omite o argumento.
|
||||
- As skills podem opcionalmente declarar `command-dispatch: tool` para encaminhar o comando diretamente para uma ferramenta (determinístico, sem modelo).
|
||||
- Exemplo: `/prose` (plugin OpenProse) — veja [OpenProse](/pt-BR/prose).
|
||||
- **Argumentos de comando nativo:** o Discord usa autocomplete para opções dinâmicas (e menus de botão quando você omite args obrigatórios). Telegram e Slack mostram um menu de botões quando um comando oferece escolhas e você omite o arg.
|
||||
|
||||
## `/tools`
|
||||
|
||||
`/tools` responde a uma pergunta de runtime, não a uma pergunta de configuração: **o que este agente pode usar agora
|
||||
nesta conversa**.
|
||||
|
||||
- O `/tools` padrão é compacto e otimizado para leitura rápida.
|
||||
- O padrão de `/tools` é compacto e otimizado para leitura rápida.
|
||||
- `/tools verbose` adiciona descrições curtas.
|
||||
- Superfícies de comando nativo com suporte a argumentos expõem a mesma troca de modo `compact|verbose`.
|
||||
- Superfícies com comandos nativos que oferecem suporte a argumentos expõem a mesma troca de modo como `compact|verbose`.
|
||||
- Os resultados têm escopo de sessão, então mudar agente, canal, thread, autorização do remetente ou modelo pode
|
||||
alterar a saída.
|
||||
- `/tools` inclui ferramentas realmente acessíveis em runtime, incluindo ferramentas do núcleo, ferramentas de
|
||||
Plugin conectadas e ferramentas controladas pelo canal.
|
||||
plugins conectados e ferramentas pertencentes ao canal.
|
||||
|
||||
Para editar perfis e substituições, use o painel Tools da UI de controle ou superfícies de configuração/catálogo em vez
|
||||
Para editar perfis e substituições, use o painel Tools da UI de Controle ou as superfícies de config/catálogo em vez
|
||||
de tratar `/tools` como um catálogo estático.
|
||||
|
||||
## Superfícies de uso (o que aparece onde)
|
||||
|
||||
- **Uso/quota do provedor** (exemplo: “Claude 80% restante”) aparece em `/status` para o provedor do modelo atual quando o rastreamento de uso está habilitado. O OpenClaw normaliza janelas de provedor para `% restante`; para MiniMax, campos de porcentagem somente-restante são invertidos antes da exibição, e respostas `model_remains` preferem a entrada do modelo de chat mais um rótulo de plano com tag do modelo.
|
||||
- **Linhas de token/cache** em `/status` podem usar como fallback a entrada de uso mais recente da transcrição quando o snapshot ao vivo da sessão é escasso. Valores ao vivo existentes diferentes de zero ainda prevalecem, e o fallback da transcrição também pode recuperar o rótulo do modelo de runtime ativo mais um total maior orientado a prompt quando os totais armazenados estão ausentes ou são menores.
|
||||
- **Uso/cota do provedor** (exemplo: “Claude 80% restante”) aparece em `/status` para o provedor do modelo atual quando o rastreamento de uso está ativado. O OpenClaw normaliza janelas de provedor para `% restante`; no MiniMax, campos de percentual apenas-restante são invertidos antes da exibição, e respostas `model_remains` preferem a entrada do modelo de chat mais um rótulo de plano com tag do modelo.
|
||||
- **Linhas de tokens/cache** em `/status` podem recorrer à entrada de uso mais recente da transcrição quando o snapshot da sessão ao vivo é escasso. Valores ativos existentes diferentes de zero ainda prevalecem, e o fallback da transcrição também pode recuperar o rótulo do modelo de runtime ativo mais um total maior orientado ao prompt quando os totais armazenados estiverem ausentes ou forem menores.
|
||||
- **Tokens/custo por resposta** é controlado por `/usage off|tokens|full` (anexado às respostas normais).
|
||||
- `/model status` trata de **modelos/autenticação/endpoints**, não de uso.
|
||||
- `/model status` trata de **modelos/auth/endpoints**, não de uso.
|
||||
|
||||
## Seleção de modelo (`/model`)
|
||||
|
||||
@ -251,16 +252,16 @@ Exemplos:
|
||||
/model status
|
||||
```
|
||||
|
||||
Observações:
|
||||
Notas:
|
||||
|
||||
- `/model` e `/model list` mostram um seletor compacto numerado (família do modelo + provedores disponíveis).
|
||||
- No Discord, `/model` e `/models` abrem um seletor interativo com dropdowns de provedor e modelo mais uma etapa de envio.
|
||||
- No Discord, `/model` e `/models` abrem um seletor interativo com menus suspensos de provedor e modelo mais uma etapa de envio.
|
||||
- `/model <#>` seleciona a partir desse seletor (e prefere o provedor atual quando possível).
|
||||
- `/model status` mostra a visualização detalhada, incluindo o endpoint do provedor configurado (`baseUrl`) e o modo de API (`api`) quando disponíveis.
|
||||
- `/model status` mostra a visualização detalhada, incluindo o endpoint configurado do provedor (`baseUrl`) e o modo de API (`api`) quando disponíveis.
|
||||
|
||||
## Substituições de debug
|
||||
## Substituições de depuração
|
||||
|
||||
`/debug` permite definir substituições de configuração **somente de runtime** (memória, não disco). Somente owner. Desabilitado por padrão; habilite com `commands.debug: true`.
|
||||
`/debug` permite definir substituições de configuração **somente de runtime** (memória, não disco). Somente proprietário. Desativado por padrão; ative com `commands.debug: true`.
|
||||
|
||||
Exemplos:
|
||||
|
||||
@ -272,14 +273,14 @@ Exemplos:
|
||||
/debug reset
|
||||
```
|
||||
|
||||
Observações:
|
||||
Notas:
|
||||
|
||||
- As substituições se aplicam imediatamente a novas leituras de configuração, mas **não** gravam em `openclaw.json`.
|
||||
- As substituições são aplicadas imediatamente a novas leituras de configuração, mas **não** gravam em `openclaw.json`.
|
||||
- Use `/debug reset` para limpar todas as substituições e voltar à configuração em disco.
|
||||
|
||||
## Saída de trace de Plugin
|
||||
## Saída de rastreamento de plugin
|
||||
|
||||
`/trace` permite alternar **linhas de trace/debug de Plugin com escopo de sessão** sem ativar o modo verbose completo.
|
||||
`/trace` permite alternar **linhas de rastreamento/depuração de plugin com escopo de sessão** sem ativar o modo detalhado completo.
|
||||
|
||||
Exemplos:
|
||||
|
||||
@ -289,18 +290,18 @@ Exemplos:
|
||||
/trace off
|
||||
```
|
||||
|
||||
Observações:
|
||||
Notas:
|
||||
|
||||
- `/trace` sem argumento mostra o estado atual de trace da sessão.
|
||||
- `/trace on` habilita linhas de trace de Plugin para a sessão atual.
|
||||
- `/trace off` desabilita essas linhas novamente.
|
||||
- Linhas de trace de Plugin podem aparecer em `/status` e como uma mensagem diagnóstica de acompanhamento após a resposta normal do assistente.
|
||||
- `/trace` sem argumento mostra o estado atual de rastreamento da sessão.
|
||||
- `/trace on` ativa linhas de rastreamento de plugin para a sessão atual.
|
||||
- `/trace off` as desativa novamente.
|
||||
- Linhas de rastreamento de plugin podem aparecer em `/status` e como uma mensagem diagnóstica de acompanhamento após a resposta normal do assistente.
|
||||
- `/trace` não substitui `/debug`; `/debug` continua gerenciando substituições de configuração somente de runtime.
|
||||
- `/trace` não substitui `/verbose`; a saída normal detalhada de ferramenta/status ainda pertence a `/verbose`.
|
||||
- `/trace` não substitui `/verbose`; a saída normal detalhada de ferramentas/status continua pertencendo a `/verbose`.
|
||||
|
||||
## Atualizações de configuração
|
||||
|
||||
`/config` grava na sua configuração em disco (`openclaw.json`). Somente owner. Desabilitado por padrão; habilite com `commands.config: true`.
|
||||
`/config` grava na sua configuração em disco (`openclaw.json`). Somente proprietário. Desativado por padrão; ative com `commands.config: true`.
|
||||
|
||||
Exemplos:
|
||||
|
||||
@ -312,14 +313,14 @@ Exemplos:
|
||||
/config unset messages.responsePrefix
|
||||
```
|
||||
|
||||
Observações:
|
||||
Notas:
|
||||
|
||||
- A configuração é validada antes da gravação; alterações inválidas são rejeitadas.
|
||||
- Atualizações de `/config` persistem após reinicializações.
|
||||
- As atualizações de `/config` persistem após reinicializações.
|
||||
|
||||
## Atualizações de MCP
|
||||
|
||||
`/mcp` grava definições de servidor MCP gerenciadas pelo OpenClaw em `mcp.servers`. Somente owner. Desabilitado por padrão; habilite com `commands.mcp: true`.
|
||||
`/mcp` grava definições de servidor MCP gerenciadas pelo OpenClaw em `mcp.servers`. Somente proprietário. Desativado por padrão; ative com `commands.mcp: true`.
|
||||
|
||||
Exemplos:
|
||||
|
||||
@ -330,14 +331,14 @@ Exemplos:
|
||||
/mcp unset context7
|
||||
```
|
||||
|
||||
Observações:
|
||||
Notas:
|
||||
|
||||
- `/mcp` armazena a configuração na configuração do OpenClaw, não em configurações de projeto controladas pelo Pi.
|
||||
- `/mcp` armazena configuração na config do OpenClaw, não em configurações de projeto de propriedade do Pi.
|
||||
- Adaptadores de runtime decidem quais transportes são realmente executáveis.
|
||||
|
||||
## Atualizações de Plugin
|
||||
## Atualizações de plugins
|
||||
|
||||
`/plugins` permite que operadores inspecionem Plugins descobertos e alternem a habilitação na configuração. Fluxos somente leitura podem usar `/plugin` como alias. Desabilitado por padrão; habilite com `commands.plugins: true`.
|
||||
`/plugins` permite que operadores inspecionem plugins descobertos e alternem a ativação na configuração. Fluxos somente leitura podem usar `/plugin` como alias. Desativado por padrão; ative com `commands.plugins: true`.
|
||||
|
||||
Exemplos:
|
||||
|
||||
@ -349,36 +350,36 @@ Exemplos:
|
||||
/plugins disable context7
|
||||
```
|
||||
|
||||
Observações:
|
||||
Notas:
|
||||
|
||||
- `/plugins list` e `/plugins show` usam descoberta real de Plugin no workspace atual mais a configuração em disco.
|
||||
- `/plugins enable|disable` atualiza apenas a configuração do Plugin; não instala nem desinstala Plugins.
|
||||
- Após alterações de habilitar/desabilitar, reinicie o Gateway para aplicá-las.
|
||||
- `/plugins list` e `/plugins show` usam descoberta real de plugins com base no workspace atual mais a configuração em disco.
|
||||
- `/plugins enable|disable` atualiza apenas a configuração do plugin; não instala nem desinstala plugins.
|
||||
- Após alterações de ativação/desativação, reinicie o gateway para aplicá-las.
|
||||
|
||||
## Observações de superfície
|
||||
## Notas de superfície
|
||||
|
||||
- **Comandos de texto** são executados na sessão normal de chat (DMs compartilham `main`, grupos têm sua própria sessão).
|
||||
- **Comandos nativos** usam sessões isoladas:
|
||||
- Discord: `agent:<agentId>:discord:slash:<userId>`
|
||||
- Slack: `agent:<agentId>:slack:slash:<userId>` (prefixo configurável via `channels.slack.slashCommand.sessionPrefix`)
|
||||
- Telegram: `telegram:slash:<userId>` (aponta para a sessão do chat via `CommandTargetSessionKey`)
|
||||
- **`/stop`** aponta para a sessão de chat ativa para poder abortar a execução atual.
|
||||
- **Slack:** `channels.slack.slashCommand` ainda é compatível para um único comando no estilo `/openclaw`. Se você habilitar `commands.native`, deverá criar um comando slash do Slack por comando embutido (os mesmos nomes de `/help`). Menus de argumento de comando para o Slack são entregues como botões efêmeros do Block Kit.
|
||||
- Telegram: `telegram:slash:<userId>` (direciona para a sessão do chat via `CommandTargetSessionKey`)
|
||||
- **`/stop`** mira a sessão de chat ativa para que possa interromper a execução atual.
|
||||
- **Slack:** `channels.slack.slashCommand` ainda é compatível para um único comando no estilo `/openclaw`. Se você ativar `commands.native`, deverá criar um slash command do Slack por comando embutido (com os mesmos nomes de `/help`). Menus de argumentos de comando para o Slack são entregues como botões efêmeros do Block Kit.
|
||||
- Exceção nativa do Slack: registre `/agentstatus` (não `/status`) porque o Slack reserva `/status`. O `/status` em texto ainda funciona em mensagens do Slack.
|
||||
|
||||
## Perguntas laterais BTW
|
||||
## Perguntas paralelas BTW
|
||||
|
||||
`/btw` é uma **pergunta lateral** rápida sobre a sessão atual.
|
||||
`/btw` é uma **pergunta paralela** rápida sobre a sessão atual.
|
||||
|
||||
Diferentemente do chat normal:
|
||||
|
||||
- ele usa a sessão atual como contexto de fundo,
|
||||
- ele é executado como uma chamada avulsa separada **sem ferramentas**,
|
||||
- ele é executado como uma chamada única separada **sem ferramentas**,
|
||||
- ele não altera o contexto futuro da sessão,
|
||||
- ele não é gravado no histórico da transcrição,
|
||||
- ele é entregue como um resultado lateral ao vivo em vez de uma mensagem normal do assistente.
|
||||
- ele é entregue como um resultado paralelo ao vivo em vez de uma mensagem normal do assistente.
|
||||
|
||||
Isso torna `/btw` útil quando você quer um esclarecimento temporário enquanto a
|
||||
Isso faz de `/btw` algo útil quando você quer um esclarecimento temporário enquanto a
|
||||
tarefa principal continua.
|
||||
|
||||
Exemplo:
|
||||
@ -387,5 +388,5 @@ Exemplo:
|
||||
/btw o que estamos fazendo agora?
|
||||
```
|
||||
|
||||
Consulte [BTW Side Questions](/pt-BR/tools/btw) para o comportamento completo e os detalhes
|
||||
da UX do cliente.
|
||||
Veja [BTW Side Questions](/pt-BR/tools/btw) para o comportamento completo e os
|
||||
detalhes de UX do cliente.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user