chore(i18n): refresh pt-BR translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
c3143e7df0
commit
81a4b42d69
@ -5,32 +5,32 @@ read_when:
|
||||
summary: Status do suporte ao Matrix, configuração inicial e exemplos de configuração
|
||||
title: Matrix
|
||||
x-i18n:
|
||||
generated_at: "2026-04-15T05:33:50Z"
|
||||
generated_at: "2026-04-15T19:41:33Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 631f6fdcfebc23136c1a66b04851a25c047535d13cceba5650b8b421bc3afcf8
|
||||
source_hash: bd730bb9d0c8a548ee48b20931b3222e9aa1e6e95f1390b0c236645e03f3576d
|
||||
source_path: channels/matrix.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Matrix
|
||||
|
||||
Matrix é um Plugin de canal incluído no OpenClaw.
|
||||
Matrix é um Plugin de canal empacotado para o OpenClaw.
|
||||
Ele usa o `matrix-js-sdk` oficial e oferece suporte a DMs, salas, threads, mídia, reações, enquetes, localização e E2EE.
|
||||
|
||||
## Plugin incluído
|
||||
## Plugin empacotado
|
||||
|
||||
O Matrix é distribuído como um Plugin incluído nas versões atuais do OpenClaw, então compilações empacotadas normais não precisam de uma instalação separada.
|
||||
O Matrix é distribuído como um Plugin empacotado nas versões atuais do OpenClaw, então compilações empacotadas normais não precisam de uma instalação separada.
|
||||
|
||||
Se você estiver em uma compilação mais antiga ou em uma instalação personalizada que exclua o Matrix, instale-o manualmente:
|
||||
Se você estiver em uma compilação mais antiga ou em uma instalação personalizada que exclui o Matrix, instale-o manualmente:
|
||||
|
||||
Instale pelo npm:
|
||||
Instalar a partir do npm:
|
||||
|
||||
```bash
|
||||
openclaw plugins install @openclaw/matrix
|
||||
```
|
||||
|
||||
Instale a partir de um checkout local:
|
||||
Instalar a partir de um checkout local:
|
||||
|
||||
```bash
|
||||
openclaw plugins install ./path/to/local/matrix-plugin
|
||||
@ -40,7 +40,7 @@ Consulte [Plugins](/pt-BR/tools/plugin) para ver o comportamento dos plugins e a
|
||||
|
||||
## Configuração inicial
|
||||
|
||||
1. Verifique se o Plugin Matrix está disponível.
|
||||
1. Certifique-se de que o Plugin Matrix esteja disponível.
|
||||
- As versões empacotadas atuais do OpenClaw já o incluem.
|
||||
- Instalações antigas/personalizadas podem adicioná-lo manualmente com os comandos acima.
|
||||
2. Crie uma conta Matrix no seu homeserver.
|
||||
@ -63,30 +63,30 @@ O assistente do Matrix solicita:
|
||||
- URL do homeserver
|
||||
- método de autenticação: token de acesso ou senha
|
||||
- ID do usuário (somente autenticação por senha)
|
||||
- nome do dispositivo opcional
|
||||
- nome opcional do dispositivo
|
||||
- se deve ativar E2EE
|
||||
- se deve configurar acesso a salas e entrada automática por convite
|
||||
- se deve configurar acesso à sala e entrada automática em convites
|
||||
|
||||
Comportamentos principais do assistente:
|
||||
Principais comportamentos do assistente:
|
||||
|
||||
- Se as variáveis de ambiente de autenticação do Matrix já existirem e essa conta ainda não tiver autenticação salva na configuração, o assistente oferece um atalho de ambiente para manter a autenticação em variáveis de ambiente.
|
||||
- Se as variáveis de ambiente de autenticação do Matrix já existirem e essa conta ainda não tiver autenticação salva na configuração, o assistente oferece um atalho de env para manter a autenticação nas variáveis de ambiente.
|
||||
- Os nomes das contas são normalizados para o ID da conta. Por exemplo, `Ops Bot` se torna `ops-bot`.
|
||||
- Entradas de lista de permissões de DM aceitam `@user:server` diretamente; nomes de exibição só funcionam quando a busca em diretório ao vivo encontra uma correspondência exata.
|
||||
- Entradas de lista de permissões de sala aceitam IDs de sala e aliases diretamente. Prefira `!room:server` ou `#alias:server`; nomes não resolvidos são ignorados em tempo de execução pela resolução da lista de permissões.
|
||||
- No modo de lista de permissões para entrada automática por convite, use apenas destinos de convite estáveis: `!roomId:server`, `#alias:server` ou `*`. Nomes simples de salas são rejeitados.
|
||||
- Para resolver nomes de salas antes de salvar, use `openclaw channels resolve --channel matrix "Project Room"`.
|
||||
- Entradas da allowlist de DM aceitam `@user:server` diretamente; nomes de exibição só funcionam quando a busca ao vivo no diretório encontra uma correspondência exata.
|
||||
- Entradas da allowlist de sala aceitam IDs e aliases de sala diretamente. Prefira `!room:server` ou `#alias:server`; nomes não resolvidos são ignorados em tempo de execução pela resolução da allowlist.
|
||||
- No modo de allowlist para entrada automática em convites, use apenas destinos de convite estáveis: `!roomId:server`, `#alias:server` ou `*`. Nomes simples de sala são rejeitados.
|
||||
- Para resolver nomes de sala antes de salvar, use `openclaw channels resolve --channel matrix "Project Room"`.
|
||||
|
||||
<Warning>
|
||||
`channels.matrix.autoJoin` tem o padrão `off`.
|
||||
`channels.matrix.autoJoin` tem como padrão `off`.
|
||||
|
||||
Se você deixá-lo sem definir, o bot não entrará em salas convidadas nem em convites novos no estilo DM, então ele não aparecerá em novos grupos nem em DMs por convite, a menos que você entre manualmente primeiro.
|
||||
Se você deixá-lo sem definir, o bot não entrará em salas convidadas nem em convites novos no estilo DM, então ele não aparecerá em novos grupos ou DMs convidadas, a menos que você entre manualmente primeiro.
|
||||
|
||||
Defina `autoJoin: "allowlist"` junto com `autoJoinAllowlist` para restringir quais convites ele aceita, ou defina `autoJoin: "always"` se quiser que ele entre em todos os convites.
|
||||
|
||||
No modo `allowlist`, `autoJoinAllowlist` aceita apenas `!roomId:server`, `#alias:server` ou `*`.
|
||||
</Warning>
|
||||
|
||||
Exemplo de lista de permissões:
|
||||
Exemplo de allowlist:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -149,7 +149,7 @@ Configuração baseada em senha (o token é armazenado em cache após o login):
|
||||
|
||||
O Matrix armazena credenciais em cache em `~/.openclaw/credentials/matrix/`.
|
||||
A conta padrão usa `credentials.json`; contas nomeadas usam `credentials-<account>.json`.
|
||||
Quando existem credenciais em cache nesse local, o OpenClaw trata o Matrix como configurado para configuração inicial, doctor e detecção de status do canal, mesmo que a autenticação atual não esteja definida diretamente na configuração.
|
||||
Quando existem credenciais em cache ali, o OpenClaw trata o Matrix como configurado para configuração inicial, doctor e descoberta de status do canal, mesmo que a autenticação atual não esteja definida diretamente na configuração.
|
||||
|
||||
Equivalentes em variáveis de ambiente (usados quando a chave de configuração não está definida):
|
||||
|
||||
@ -160,7 +160,7 @@ Equivalentes em variáveis de ambiente (usados quando a chave de configuração
|
||||
- `MATRIX_DEVICE_ID`
|
||||
- `MATRIX_DEVICE_NAME`
|
||||
|
||||
Para contas não padrão, use variáveis de ambiente com escopo por conta:
|
||||
Para contas não padrão, use variáveis de ambiente com escopo de conta:
|
||||
|
||||
- `MATRIX_<ACCOUNT_ID>_HOMESERVER`
|
||||
- `MATRIX_<ACCOUNT_ID>_ACCESS_TOKEN`
|
||||
@ -179,14 +179,14 @@ Para o ID de conta normalizado `ops-bot`, use:
|
||||
- `MATRIX_OPS_X2D_BOT_HOMESERVER`
|
||||
- `MATRIX_OPS_X2D_BOT_ACCESS_TOKEN`
|
||||
|
||||
O Matrix escapa a pontuação nos IDs de conta para manter as variáveis de ambiente com escopo livres de colisão.
|
||||
Por exemplo, `-` se torna `_X2D_`, então `ops-prod` é mapeado para `MATRIX_OPS_X2D_PROD_*`.
|
||||
O Matrix escapa a pontuação nos IDs de conta para manter variáveis de ambiente com escopo sem colisões.
|
||||
Por exemplo, `-` se torna `_X2D_`, então `ops-prod` mapeia para `MATRIX_OPS_X2D_PROD_*`.
|
||||
|
||||
O assistente interativo só oferece o atalho de variável de ambiente quando essas variáveis de autenticação já estão presentes e a conta selecionada ainda não tem autenticação do Matrix salva na configuração.
|
||||
|
||||
## Exemplo de configuração
|
||||
|
||||
Esta é uma configuração base prática com pareamento de DM, lista de permissões de sala e E2EE ativado:
|
||||
Esta é uma configuração base prática com emparelhamento de DM, allowlist de sala e E2EE ativado:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -225,9 +225,9 @@ Esta é uma configuração base prática com pareamento de DM, lista de permiss
|
||||
|
||||
## Prévias de streaming
|
||||
|
||||
O streaming de respostas do Matrix é opcional.
|
||||
O streaming de respostas do Matrix é opt-in.
|
||||
|
||||
Defina `channels.matrix.streaming` como `"partial"` quando quiser que o OpenClaw envie uma única resposta de prévia ao vivo, edite essa prévia no mesmo lugar enquanto o modelo gera texto e depois a finalize quando a resposta terminar:
|
||||
Defina `channels.matrix.streaming` como `"partial"` quando quiser que o OpenClaw envie uma única resposta de prévia ao vivo, edite essa prévia no mesmo lugar enquanto o modelo gera texto e depois a finalize quando a resposta estiver pronta:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -240,34 +240,34 @@ Defina `channels.matrix.streaming` como `"partial"` quando quiser que o OpenClaw
|
||||
```
|
||||
|
||||
- `streaming: "off"` é o padrão. O OpenClaw espera a resposta final e a envia uma única vez.
|
||||
- `streaming: "partial"` cria uma mensagem de prévia editável para o bloco atual do assistente usando mensagens de texto normais do Matrix. Isso preserva o comportamento legado de notificação baseado na primeira prévia do Matrix, então clientes padrão podem notificar com o primeiro texto transmitido em streaming em vez do bloco concluído.
|
||||
- `streaming: "quiet"` cria uma prévia silenciosa editável para o bloco atual do assistente. Use isso apenas quando você também configurar regras de push do destinatário para edições de prévia finalizadas.
|
||||
- `blockStreaming: true` ativa mensagens de progresso separadas do Matrix. Com o streaming de prévia ativado, o Matrix mantém o rascunho ao vivo do bloco atual e preserva os blocos concluídos como mensagens separadas.
|
||||
- `streaming: "partial"` cria uma mensagem de prévia editável para o bloco atual do assistente usando mensagens de texto normais do Matrix. Isso preserva o comportamento legado do Matrix de notificação na primeira prévia, então clientes padrão podem notificar com base no primeiro texto transmitido em streaming em vez do bloco concluído.
|
||||
- `streaming: "quiet"` cria uma prévia editável silenciosa para o bloco atual do assistente. Use isso apenas quando você também configurar regras de push do destinatário para edições de prévia finalizadas.
|
||||
- `blockStreaming: true` ativa mensagens separadas de progresso do Matrix. Com o streaming de prévia ativado, o Matrix mantém o rascunho ao vivo para o bloco atual e preserva blocos concluídos como mensagens separadas.
|
||||
- Quando o streaming de prévia está ativado e `blockStreaming` está desativado, o Matrix edita o rascunho ao vivo no mesmo lugar e finaliza esse mesmo evento quando o bloco ou o turno termina.
|
||||
- Se a prévia não couber mais em um único evento do Matrix, o OpenClaw interrompe o streaming de prévia e volta à entrega final normal.
|
||||
- Respostas com mídia ainda enviam anexos normalmente. Se uma prévia antiga não puder mais ser reutilizada com segurança, o OpenClaw a remove antes de enviar a resposta final com mídia.
|
||||
- Se a prévia não couber mais em um único evento do Matrix, o OpenClaw interrompe o streaming de prévia e volta para a entrega final normal.
|
||||
- Respostas com mídia ainda enviam anexos normalmente. Se uma prévia antiga não puder mais ser reutilizada com segurança, o OpenClaw a redige antes de enviar a resposta final com mídia.
|
||||
- Edições de prévia geram chamadas extras à API do Matrix. Deixe o streaming desativado se quiser o comportamento mais conservador em relação a limite de taxa.
|
||||
|
||||
`blockStreaming` não ativa prévias em rascunho por si só.
|
||||
Use `streaming: "partial"` ou `streaming: "quiet"` para edições de prévia; depois adicione `blockStreaming: true` somente se você também quiser que os blocos concluídos do assistente permaneçam visíveis como mensagens de progresso separadas.
|
||||
Use `streaming: "partial"` ou `streaming: "quiet"` para edições de prévia; depois adicione `blockStreaming: true` apenas se também quiser que os blocos concluídos do assistente permaneçam visíveis como mensagens de progresso separadas.
|
||||
|
||||
Se você precisar de notificações padrão do Matrix sem regras de push personalizadas, use `streaming: "partial"` para o comportamento baseado na primeira prévia ou deixe `streaming` desativado para entrega somente final. Com `streaming: "off"`:
|
||||
Se você precisar de notificações padrão do Matrix sem regras de push personalizadas, use `streaming: "partial"` para o comportamento de prévia primeiro ou deixe `streaming` desativado para entrega somente final. Com `streaming: "off"`:
|
||||
|
||||
- `blockStreaming: true` envia cada bloco concluído como uma mensagem normal notificável do Matrix.
|
||||
- `blockStreaming: false` envia apenas a resposta final concluída como uma mensagem normal notificável do Matrix.
|
||||
- `blockStreaming: true` envia cada bloco concluído como uma mensagem normal do Matrix com notificação.
|
||||
- `blockStreaming: false` envia apenas a resposta final concluída como uma mensagem normal do Matrix com notificação.
|
||||
|
||||
### Regras de push auto-hospedadas para prévias silenciosas finalizadas
|
||||
|
||||
Se você executa sua própria infraestrutura Matrix e quer que prévias silenciosas notifiquem apenas quando um bloco ou resposta final for concluído, defina `streaming: "quiet"` e adicione uma regra de push por usuário para edições de prévia finalizadas.
|
||||
Se você executa sua própria infraestrutura Matrix e quer que prévias silenciosas notifiquem apenas quando um bloco ou a resposta final estiver concluída, defina `streaming: "quiet"` e adicione uma regra de push por usuário para edições de prévia finalizadas.
|
||||
|
||||
Normalmente isso é uma configuração do usuário destinatário, não uma alteração de configuração global do homeserver:
|
||||
Normalmente isso é uma configuração do usuário destinatário, não uma alteração global de configuração do homeserver:
|
||||
|
||||
Mapa rápido antes de começar:
|
||||
|
||||
- usuário destinatário = a pessoa que deve receber a notificação
|
||||
- usuário bot = a conta Matrix do OpenClaw que envia a resposta
|
||||
- use o token de acesso do usuário destinatário nas chamadas de API abaixo
|
||||
- faça a correspondência de `sender` na regra de push com o MXID completo do usuário bot
|
||||
- usuário do bot = a conta Matrix do OpenClaw que envia a resposta
|
||||
- use o token de acesso do usuário destinatário para as chamadas de API abaixo
|
||||
- faça `sender` na regra de push corresponder ao MXID completo do usuário do bot
|
||||
|
||||
1. Configure o OpenClaw para usar prévias silenciosas:
|
||||
|
||||
@ -281,12 +281,12 @@ Mapa rápido antes de começar:
|
||||
}
|
||||
```
|
||||
|
||||
2. Certifique-se de que a conta destinatária já recebe notificações push normais do Matrix. As regras de prévia silenciosa só funcionam se esse usuário já tiver pushers/dispositivos funcionando.
|
||||
2. Certifique-se de que a conta destinatária já receba notificações push normais do Matrix. Regras de prévia silenciosa só funcionam se esse usuário já tiver pushers/dispositivos funcionando.
|
||||
|
||||
3. Obtenha o token de acesso do usuário destinatário.
|
||||
- Use o token do usuário que recebe, não o token do bot.
|
||||
- Reutilizar um token de sessão de cliente existente geralmente é a opção mais fácil.
|
||||
- Se você precisar gerar um token novo, pode fazer login pela API Client-Server padrão do Matrix:
|
||||
- Reutilizar um token de sessão de cliente existente geralmente é o mais fácil.
|
||||
- Se precisar gerar um token novo, você pode fazer login pela API Client-Server padrão do Matrix:
|
||||
|
||||
```bash
|
||||
curl -sS -X POST \
|
||||
@ -310,7 +310,7 @@ curl -sS \
|
||||
"https://matrix.example.org/_matrix/client/v3/pushers"
|
||||
```
|
||||
|
||||
Se isso retornar zero pushers/dispositivos ativos, corrija primeiro as notificações normais do Matrix antes de adicionar a regra do OpenClaw abaixo.
|
||||
Se isso retornar sem pushers/dispositivos ativos, corrija primeiro as notificações normais do Matrix antes de adicionar a regra do OpenClaw abaixo.
|
||||
|
||||
O OpenClaw marca edições finalizadas de prévia somente de texto com:
|
||||
|
||||
@ -352,21 +352,21 @@ curl -sS -X PUT \
|
||||
|
||||
Substitua estes valores antes de executar o comando:
|
||||
|
||||
- `https://matrix.example.org`: a URL base do seu homeserver
|
||||
- `$USER_ACCESS_TOKEN`: o token de acesso do usuário que recebe
|
||||
- `openclaw-finalized-preview-botname`: um ID de regra único para este bot para este usuário que recebe
|
||||
- `https://matrix.example.org`: URL base do seu homeserver
|
||||
- `$USER_ACCESS_TOKEN`: token de acesso do usuário que recebe
|
||||
- `openclaw-finalized-preview-botname`: um ID de regra exclusivo para este bot para este usuário que recebe
|
||||
- `@bot:example.org`: o MXID do seu bot Matrix do OpenClaw, não o MXID do usuário que recebe
|
||||
|
||||
Importante para configurações com vários bots:
|
||||
|
||||
- As regras de push são indexadas por `ruleId`. Executar `PUT` novamente no mesmo ID de regra atualiza essa única regra.
|
||||
- Se um mesmo usuário destinatário deve receber notificações de várias contas de bot Matrix do OpenClaw, crie uma regra por bot com um ID de regra único para cada correspondência de remetente.
|
||||
- Se um usuário destinatário precisar notificar para várias contas de bot Matrix do OpenClaw, crie uma regra por bot com um ID de regra exclusivo para cada correspondência de remetente.
|
||||
- Um padrão simples é `openclaw-finalized-preview-<botname>`, como `openclaw-finalized-preview-ops` ou `openclaw-finalized-preview-support`.
|
||||
|
||||
A regra é avaliada com base no remetente do evento:
|
||||
A regra é avaliada em relação ao remetente do evento:
|
||||
|
||||
- autentique com o token do usuário destinatário
|
||||
- faça a correspondência de `sender` com o MXID do bot OpenClaw
|
||||
- faça `sender` corresponder ao MXID do bot OpenClaw
|
||||
|
||||
6. Verifique se a regra existe:
|
||||
|
||||
@ -376,7 +376,7 @@ curl -sS \
|
||||
"https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname"
|
||||
```
|
||||
|
||||
7. Teste uma resposta em streaming. No modo silencioso, a sala deve mostrar uma prévia de rascunho silenciosa, e a edição final no mesmo lugar deve enviar uma notificação quando o bloco ou turno terminar.
|
||||
7. Teste uma resposta em streaming. No modo silencioso, a sala deve mostrar uma prévia de rascunho silenciosa e a edição final no mesmo lugar deve notificar quando o bloco ou turno terminar.
|
||||
|
||||
Se você precisar remover a regra depois, exclua esse mesmo ID de regra com o token do usuário destinatário:
|
||||
|
||||
@ -389,8 +389,8 @@ curl -sS -X DELETE \
|
||||
Observações:
|
||||
|
||||
- Crie a regra com o token de acesso do usuário destinatário, não com o token do bot.
|
||||
- Novas regras `override` definidas pelo usuário são inseridas antes das regras padrão de supressão, então nenhum parâmetro extra de ordenação é necessário.
|
||||
- Isso afeta apenas edições de prévia somente de texto que o OpenClaw pode finalizar com segurança no mesmo lugar. Fallbacks de mídia e fallbacks de prévia obsoleta ainda usam a entrega normal do Matrix.
|
||||
- Novas regras `override` definidas pelo usuário são inseridas antes das regras de supressão padrão, então nenhum parâmetro extra de ordenação é necessário.
|
||||
- Isso afeta apenas edições de prévia somente de texto que o OpenClaw consegue finalizar com segurança no mesmo lugar. Fallbacks de mídia e fallbacks de prévia antiga ainda usam a entrega normal do Matrix.
|
||||
- Se `GET /_matrix/client/v3/pushers` não mostrar pushers, o usuário ainda não tem entrega de push do Matrix funcionando para essa conta/dispositivo.
|
||||
|
||||
#### Synapse
|
||||
@ -399,22 +399,22 @@ Para o Synapse, a configuração acima normalmente já é suficiente por si só:
|
||||
|
||||
- Nenhuma alteração especial em `homeserver.yaml` é necessária para notificações de prévia finalizada do OpenClaw.
|
||||
- Se sua implantação do Synapse já envia notificações push normais do Matrix, o token do usuário + a chamada `pushrules` acima são a principal etapa de configuração.
|
||||
- Se você executa o Synapse atrás de um proxy reverso ou workers, verifique se `/_matrix/client/.../pushrules/` chega corretamente ao Synapse.
|
||||
- Se você executa workers do Synapse, verifique se os pushers estão saudáveis. A entrega de push é tratada pelo processo principal ou por `synapse.app.pusher` / workers de pusher configurados.
|
||||
- Se você executa o Synapse atrás de um proxy reverso ou workers, certifique-se de que `/_matrix/client/.../pushrules/` chegue corretamente ao Synapse.
|
||||
- Se você executa workers do Synapse, certifique-se de que os pushers estejam íntegros. A entrega de push é tratada pelo processo principal ou por `synapse.app.pusher` / workers de pusher configurados.
|
||||
|
||||
#### Tuwunel
|
||||
|
||||
Para o Tuwunel, use o mesmo fluxo de configuração e a chamada de API `pushrules` mostrados acima:
|
||||
Para o Tuwunel, use o mesmo fluxo de configuração e a mesma chamada de API `pushrules` mostrados acima:
|
||||
|
||||
- Nenhuma configuração específica do Tuwunel é necessária para o próprio marcador de prévia finalizada.
|
||||
- Se as notificações normais do Matrix já funcionam para esse usuário, o token do usuário + a chamada `pushrules` acima são a principal etapa de configuração.
|
||||
- Se as notificações parecerem desaparecer enquanto o usuário está ativo em outro dispositivo, verifique se `suppress_push_when_active` está ativado. O Tuwunel adicionou essa opção no Tuwunel 1.4.2 em 12 de setembro de 2025, e ela pode suprimir intencionalmente pushes para outros dispositivos enquanto um dispositivo está ativo.
|
||||
- Se as notificações parecerem desaparecer enquanto o usuário estiver ativo em outro dispositivo, verifique se `suppress_push_when_active` está ativado. O Tuwunel adicionou essa opção no Tuwunel 1.4.2 em 12 de setembro de 2025, e ela pode suprimir intencionalmente pushes para outros dispositivos enquanto um dispositivo estiver ativo.
|
||||
|
||||
## Salas bot para bot
|
||||
|
||||
Por padrão, mensagens do Matrix vindas de outras contas Matrix do OpenClaw configuradas são ignoradas.
|
||||
Por padrão, mensagens Matrix de outras contas Matrix configuradas do OpenClaw são ignoradas.
|
||||
|
||||
Use `allowBots` quando você quiser intencionalmente tráfego Matrix entre agentes:
|
||||
Use `allowBots` quando você intencionalmente quiser tráfego Matrix entre agentes:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -432,18 +432,18 @@ Use `allowBots` quando você quiser intencionalmente tráfego Matrix entre agent
|
||||
```
|
||||
|
||||
- `allowBots: true` aceita mensagens de outras contas de bot Matrix configuradas em salas e DMs permitidas.
|
||||
- `allowBots: "mentions"` aceita essas mensagens apenas quando elas mencionam visivelmente este bot nas salas. DMs continuam permitidas.
|
||||
- `allowBots: "mentions"` aceita essas mensagens apenas quando elas mencionam visivelmente este bot nas salas. DMs ainda são permitidas.
|
||||
- `groups.<room>.allowBots` substitui a configuração no nível da conta para uma sala.
|
||||
- O OpenClaw ainda ignora mensagens do mesmo ID de usuário Matrix para evitar loops de autorresposta.
|
||||
- O OpenClaw ainda ignora mensagens do mesmo ID de usuário Matrix para evitar loops de resposta a si mesmo.
|
||||
- O Matrix não expõe aqui um sinalizador nativo de bot; o OpenClaw trata "de autoria de bot" como "enviado por outra conta Matrix configurada neste Gateway OpenClaw".
|
||||
|
||||
Use listas de permissões de sala estritas e exigências de menção ao ativar tráfego bot para bot em salas compartilhadas.
|
||||
Use allowlists rigorosas de sala e exigências de menção ao ativar tráfego bot para bot em salas compartilhadas.
|
||||
|
||||
## Criptografia e verificação
|
||||
|
||||
Em salas criptografadas (E2EE), eventos de imagem de saída usam `thumbnail_file` para que as prévias de imagem sejam criptografadas junto com o anexo completo. Salas não criptografadas continuam usando `thumbnail_url` simples. Nenhuma configuração é necessária — o Plugin detecta automaticamente o estado de E2EE.
|
||||
Em salas criptografadas (E2EE), eventos de imagem de saída usam `thumbnail_file`, para que as prévias de imagem sejam criptografadas junto com o anexo completo. Salas não criptografadas ainda usam `thumbnail_url` simples. Nenhuma configuração é necessária — o Plugin detecta automaticamente o estado de E2EE.
|
||||
|
||||
Ativar criptografia:
|
||||
Ative a criptografia:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -459,43 +459,43 @@ Ativar criptografia:
|
||||
}
|
||||
```
|
||||
|
||||
Verificar o status da verificação:
|
||||
Verifique o status da verificação:
|
||||
|
||||
```bash
|
||||
openclaw matrix verify status
|
||||
```
|
||||
|
||||
Status detalhado (diagnósticos completos):
|
||||
Status detalhado (diagnóstico completo):
|
||||
|
||||
```bash
|
||||
openclaw matrix verify status --verbose
|
||||
```
|
||||
|
||||
Incluir a chave de recuperação armazenada na saída legível por máquina:
|
||||
Inclua a chave de recuperação armazenada na saída legível por máquina:
|
||||
|
||||
```bash
|
||||
openclaw matrix verify status --include-recovery-key --json
|
||||
```
|
||||
|
||||
Inicializar o estado de cross-signing e verificação:
|
||||
Inicialize o estado de assinatura cruzada e verificação:
|
||||
|
||||
```bash
|
||||
openclaw matrix verify bootstrap
|
||||
```
|
||||
|
||||
Diagnósticos detalhados de bootstrap:
|
||||
Diagnóstico detalhado da inicialização:
|
||||
|
||||
```bash
|
||||
openclaw matrix verify bootstrap --verbose
|
||||
```
|
||||
|
||||
Forçar uma redefinição nova da identidade de cross-signing antes do bootstrap:
|
||||
Force uma redefinição nova da identidade de assinatura cruzada antes da inicialização:
|
||||
|
||||
```bash
|
||||
openclaw matrix verify bootstrap --force-reset-cross-signing
|
||||
```
|
||||
|
||||
Verificar este dispositivo com uma chave de recuperação:
|
||||
Verifique este dispositivo com uma chave de recuperação:
|
||||
|
||||
```bash
|
||||
openclaw matrix verify device "<your-recovery-key>"
|
||||
@ -507,41 +507,41 @@ Detalhes detalhados da verificação do dispositivo:
|
||||
openclaw matrix verify device "<your-recovery-key>" --verbose
|
||||
```
|
||||
|
||||
Verificar a integridade do backup de chaves de sala:
|
||||
Verifique a integridade do backup de chaves de sala:
|
||||
|
||||
```bash
|
||||
openclaw matrix verify backup status
|
||||
```
|
||||
|
||||
Diagnósticos detalhados da integridade do backup:
|
||||
Diagnóstico detalhado da integridade do backup:
|
||||
|
||||
```bash
|
||||
openclaw matrix verify backup status --verbose
|
||||
```
|
||||
|
||||
Restaurar chaves de sala do backup no servidor:
|
||||
Restaure chaves de sala do backup do servidor:
|
||||
|
||||
```bash
|
||||
openclaw matrix verify backup restore
|
||||
```
|
||||
|
||||
Diagnósticos detalhados da restauração:
|
||||
Diagnóstico detalhado da restauração:
|
||||
|
||||
```bash
|
||||
openclaw matrix verify backup restore --verbose
|
||||
```
|
||||
|
||||
Excluir o backup atual do servidor e criar uma nova base de backup. Se a chave de backup armazenada não puder ser carregada corretamente, essa redefinição também poderá recriar o armazenamento de segredos para que futuras inicializações a frio consigam carregar a nova chave de backup:
|
||||
Exclua o backup atual do servidor e crie uma nova base de backup. Se a chave de backup armazenada não puder ser carregada corretamente, essa redefinição também pode recriar o armazenamento secreto para que futuras inicializações a frio consigam carregar a nova chave de backup:
|
||||
|
||||
```bash
|
||||
openclaw matrix verify backup reset --yes
|
||||
```
|
||||
|
||||
Todos os comandos `verify` são concisos por padrão (incluindo logs internos silenciosos do SDK) e só mostram diagnósticos detalhados com `--verbose`.
|
||||
Todos os comandos `verify` são concisos por padrão (incluindo logging interno silencioso do SDK) e mostram diagnósticos detalhados apenas com `--verbose`.
|
||||
Use `--json` para saída completa legível por máquina ao criar scripts.
|
||||
|
||||
Em configurações com várias contas, os comandos CLI do Matrix usam a conta padrão implícita do Matrix, a menos que você passe `--account <id>`.
|
||||
Se você configurar várias contas nomeadas, defina primeiro `channels.matrix.defaultAccount`, ou essas operações implícitas da CLI vão parar e pedir que você escolha uma conta explicitamente.
|
||||
Em configurações com várias contas, os comandos Matrix da CLI usam a conta padrão implícita do Matrix, a menos que você passe `--account <id>`.
|
||||
Se você configurar várias contas nomeadas, defina primeiro `channels.matrix.defaultAccount` ou essas operações implícitas da CLI irão parar e pedir que você escolha uma conta explicitamente.
|
||||
Use `--account` sempre que quiser que operações de verificação ou de dispositivo tenham como alvo explicitamente uma conta nomeada:
|
||||
|
||||
```bash
|
||||
@ -550,40 +550,40 @@ openclaw matrix verify backup restore --account assistant
|
||||
openclaw matrix devices list --account assistant
|
||||
```
|
||||
|
||||
Quando a criptografia está desativada ou indisponível para uma conta nomeada, avisos do Matrix e erros de verificação apontam para a chave de configuração dessa conta, por exemplo `channels.matrix.accounts.assistant.encryption`.
|
||||
Quando a criptografia estiver desativada ou indisponível para uma conta nomeada, avisos do Matrix e erros de verificação apontam para a chave de configuração dessa conta, por exemplo `channels.matrix.accounts.assistant.encryption`.
|
||||
|
||||
### O que "verificado" significa
|
||||
|
||||
O OpenClaw trata este dispositivo Matrix como verificado apenas quando ele é verificado pela sua própria identidade de cross-signing.
|
||||
O OpenClaw trata este dispositivo Matrix como verificado somente quando ele é verificado pela sua própria identidade de assinatura cruzada.
|
||||
Na prática, `openclaw matrix verify status --verbose` expõe três sinais de confiança:
|
||||
|
||||
- `Locally trusted`: este dispositivo é confiável apenas pelo cliente atual
|
||||
- `Cross-signing verified`: o SDK informa que o dispositivo está verificado por cross-signing
|
||||
- `Signed by owner`: o dispositivo é assinado pela sua própria chave de self-signing
|
||||
- `Cross-signing verified`: o SDK informa o dispositivo como verificado por assinatura cruzada
|
||||
- `Signed by owner`: o dispositivo é assinado pela sua própria chave de autoassinatura
|
||||
|
||||
`Verified by owner` só se torna `yes` quando há verificação por cross-signing ou assinatura pelo proprietário.
|
||||
A confiança local, por si só, não é suficiente para o OpenClaw tratar o dispositivo como totalmente verificado.
|
||||
`Verified by owner` passa a ser `yes` somente quando há verificação por assinatura cruzada ou assinatura do proprietário.
|
||||
A confiança local por si só não basta para que o OpenClaw trate o dispositivo como totalmente verificado.
|
||||
|
||||
### O que o bootstrap faz
|
||||
### O que a inicialização faz
|
||||
|
||||
`openclaw matrix verify bootstrap` é o comando de reparo e configuração para contas Matrix criptografadas.
|
||||
Ele faz tudo o seguinte, nesta ordem:
|
||||
Ele faz tudo o que segue, nesta ordem:
|
||||
|
||||
- inicializa o armazenamento de segredos, reutilizando uma chave de recuperação existente quando possível
|
||||
- inicializa o cross-signing e envia as chaves públicas de cross-signing ausentes
|
||||
- tenta marcar e assinar por cross-signing o dispositivo atual
|
||||
- cria um novo backup de chaves de sala no lado do servidor, se ainda não existir um
|
||||
- inicializa o armazenamento secreto, reutilizando uma chave de recuperação existente quando possível
|
||||
- inicializa a assinatura cruzada e envia chaves públicas de assinatura cruzada ausentes
|
||||
- tenta marcar e assinar de forma cruzada o dispositivo atual
|
||||
- cria um novo backup de chaves de sala no servidor se ainda não existir um
|
||||
|
||||
Se o homeserver exigir autenticação interativa para enviar chaves de cross-signing, o OpenClaw tenta o envio primeiro sem autenticação, depois com `m.login.dummy`, e depois com `m.login.password` quando `channels.matrix.password` está configurado.
|
||||
Se o homeserver exigir autenticação interativa para enviar chaves de assinatura cruzada, o OpenClaw tenta o envio primeiro sem autenticação, depois com `m.login.dummy` e depois com `m.login.password` quando `channels.matrix.password` está configurado.
|
||||
|
||||
Use `--force-reset-cross-signing` apenas quando você quiser intencionalmente descartar a identidade atual de cross-signing e criar uma nova.
|
||||
Use `--force-reset-cross-signing` somente quando você intencionalmente quiser descartar a identidade atual de assinatura cruzada e criar uma nova.
|
||||
|
||||
Se você quiser intencionalmente descartar o backup atual de chaves de sala e iniciar uma nova base de backup para mensagens futuras, use `openclaw matrix verify backup reset --yes`.
|
||||
Faça isso apenas se aceitar que o histórico criptografado antigo irrecuperável continuará indisponível e que o OpenClaw pode recriar o armazenamento de segredos se o segredo atual de backup não puder ser carregado com segurança.
|
||||
Se você intencionalmente quiser descartar o backup atual de chaves de sala e iniciar uma nova base de backup para mensagens futuras, use `openclaw matrix verify backup reset --yes`.
|
||||
Faça isso apenas se aceitar que o histórico criptografado antigo irrecuperável continuará indisponível e que o OpenClaw pode recriar o armazenamento secreto se o segredo de backup atual não puder ser carregado com segurança.
|
||||
|
||||
### Nova base de backup
|
||||
|
||||
Se você quiser manter o funcionamento das futuras mensagens criptografadas e aceitar perder o histórico antigo irrecuperável, execute estes comandos em ordem:
|
||||
Se você quiser manter o funcionamento de futuras mensagens criptografadas e aceitar perder histórico antigo irrecuperável, execute estes comandos na ordem:
|
||||
|
||||
```bash
|
||||
openclaw matrix verify backup reset --yes
|
||||
@ -591,20 +591,21 @@ openclaw matrix verify backup status --verbose
|
||||
openclaw matrix verify status
|
||||
```
|
||||
|
||||
Adicione `--account <id>` a cada comando quando quiser direcionar explicitamente uma conta Matrix nomeada.
|
||||
Adicione `--account <id>` a cada comando quando quiser ter como alvo explicitamente uma conta Matrix nomeada.
|
||||
|
||||
### Comportamento na inicialização
|
||||
|
||||
Quando `encryption: true`, o Matrix define `startupVerification` como `"if-unverified"` por padrão.
|
||||
Na inicialização, se este dispositivo ainda não estiver verificado, o Matrix solicitará autoverificação em outro cliente Matrix, ignorará solicitações duplicadas enquanto uma já estiver pendente e aplicará um cooldown local antes de tentar novamente após reinicializações.
|
||||
Tentativas de solicitação com falha tentam novamente mais cedo do que a criação bem-sucedida da solicitação por padrão.
|
||||
Defina `startupVerification: "off"` para desativar solicitações automáticas na inicialização, ou ajuste `startupVerificationCooldownHours` se quiser uma janela de nova tentativa mais curta ou mais longa.
|
||||
Tentativas de solicitação com falha são repetidas mais cedo do que a criação bem-sucedida de solicitações por padrão.
|
||||
Defina `startupVerification: "off"` para desativar solicitações automáticas na inicialização ou ajuste `startupVerificationCooldownHours` se quiser uma janela de nova tentativa menor ou maior.
|
||||
|
||||
A inicialização também executa automaticamente uma passagem conservadora de bootstrap de criptografia.
|
||||
Essa passagem tenta reutilizar primeiro o armazenamento de segredos e a identidade de cross-signing atuais, e evita redefinir o cross-signing, a menos que você execute um fluxo explícito de reparo de bootstrap.
|
||||
Essa passagem tenta reutilizar primeiro o armazenamento secreto atual e a identidade atual de assinatura cruzada, e evita redefinir a assinatura cruzada a menos que você execute um fluxo explícito de reparo de bootstrap.
|
||||
|
||||
Se a inicialização encontrar um estado de bootstrap quebrado e `channels.matrix.password` estiver configurado, o OpenClaw poderá tentar um caminho de reparo mais rigoroso.
|
||||
Se o dispositivo atual já estiver assinado pelo proprietário, o OpenClaw preservará essa identidade em vez de redefini-la automaticamente.
|
||||
Se a inicialização ainda encontrar um estado de bootstrap corrompido, o OpenClaw poderá tentar um caminho de reparo protegido mesmo quando `channels.matrix.password` não estiver configurado.
|
||||
Se o homeserver exigir UIA baseada em senha para esse reparo, o OpenClaw registra um aviso e mantém a inicialização não fatal em vez de abortar o bot.
|
||||
Se o dispositivo atual já estiver assinado pelo proprietário, o OpenClaw preserva essa identidade em vez de redefini-la automaticamente.
|
||||
|
||||
Consulte [migração do Matrix](/pt-BR/install/migrating-matrix) para ver o fluxo completo de upgrade, limites, comandos de recuperação e mensagens comuns de migração.
|
||||
|
||||
@ -614,18 +615,18 @@ O Matrix publica avisos do ciclo de vida da verificação diretamente na DM estr
|
||||
Isso inclui:
|
||||
|
||||
- avisos de solicitação de verificação
|
||||
- avisos de verificação pronta (com orientação explícita "Verifique por emoji")
|
||||
- avisos de verificação pronta (com orientação explícita "Verificar por emoji")
|
||||
- avisos de início e conclusão da verificação
|
||||
- detalhes SAS (emoji e decimal), quando disponíveis
|
||||
- detalhes de SAS (emoji e decimal) quando disponíveis
|
||||
|
||||
Solicitações de verificação recebidas de outro cliente Matrix são rastreadas e aceitas automaticamente pelo OpenClaw.
|
||||
Para fluxos de autoverificação, o OpenClaw também inicia automaticamente o fluxo SAS quando a verificação por emoji fica disponível e confirma o próprio lado.
|
||||
Para fluxos de autoverificação, o OpenClaw também inicia automaticamente o fluxo SAS quando a verificação por emoji se torna disponível e confirma seu próprio lado.
|
||||
Para solicitações de verificação de outro usuário/dispositivo Matrix, o OpenClaw aceita automaticamente a solicitação e então espera que o fluxo SAS prossiga normalmente.
|
||||
Ainda assim, você precisa comparar o SAS em emoji ou decimal no seu cliente Matrix e confirmar "They match" lá para concluir a verificação.
|
||||
Você ainda precisa comparar o SAS em emoji ou decimal no seu cliente Matrix e confirmar "They match" lá para concluir a verificação.
|
||||
|
||||
O OpenClaw não aceita automaticamente de forma cega fluxos duplicados iniciados por ele mesmo. Na inicialização, ele não cria uma nova solicitação quando uma solicitação de autoverificação já está pendente.
|
||||
O OpenClaw não aceita automaticamente fluxos duplicados iniciados por ele mesmo às cegas. A inicialização ignora a criação de uma nova solicitação quando uma solicitação de autoverificação já está pendente.
|
||||
|
||||
Avisos de protocolo/sistema de verificação não são encaminhados para o pipeline de chat do agente, então eles não produzem `NO_REPLY`.
|
||||
Avisos de verificação de protocolo/sistema não são encaminhados para o pipeline de chat do agente, então eles não produzem `NO_REPLY`.
|
||||
|
||||
### Higiene de dispositivos
|
||||
|
||||
@ -642,18 +643,18 @@ Remova dispositivos antigos gerenciados pelo OpenClaw com:
|
||||
openclaw matrix devices prune-stale
|
||||
```
|
||||
|
||||
### Armazenamento criptográfico
|
||||
### Armazenamento de criptografia
|
||||
|
||||
O E2EE do Matrix usa o caminho de criptografia Rust oficial do `matrix-js-sdk` no Node, com `fake-indexeddb` como shim do IndexedDB. O estado criptográfico é persistido em um arquivo de snapshot (`crypto-idb-snapshot.json`) e restaurado na inicialização. O arquivo de snapshot é um estado de execução sensível armazenado com permissões restritivas de arquivo.
|
||||
A E2EE do Matrix usa o caminho de criptografia Rust oficial do `matrix-js-sdk` no Node, com `fake-indexeddb` como shim de IndexedDB. O estado criptográfico é persistido em um arquivo de snapshot (`crypto-idb-snapshot.json`) e restaurado na inicialização. O arquivo de snapshot é um estado de runtime sensível armazenado com permissões restritivas de arquivo.
|
||||
|
||||
O estado criptografado em execução fica em raízes por conta, por usuário e por hash de token em
|
||||
O estado criptografado de runtime fica em raízes por conta, por usuário e por hash de token em
|
||||
`~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/`.
|
||||
Esse diretório contém o armazenamento de sincronização (`bot-storage.json`), armazenamento criptográfico (`crypto/`),
|
||||
Esse diretório contém o armazenamento de sincronização (`bot-storage.json`), armazenamento de criptografia (`crypto/`),
|
||||
arquivo de chave de recuperação (`recovery-key.json`), snapshot do IndexedDB (`crypto-idb-snapshot.json`),
|
||||
vínculos de thread (`thread-bindings.json`) e estado de verificação na inicialização (`startup-verification.json`).
|
||||
bindings de thread (`thread-bindings.json`) e estado de verificação na inicialização (`startup-verification.json`).
|
||||
Quando o token muda, mas a identidade da conta permanece a mesma, o OpenClaw reutiliza a melhor raiz existente
|
||||
para essa tupla conta/homeserver/usuário para que o estado anterior de sincronização, estado criptográfico, vínculos de thread
|
||||
e estado de verificação na inicialização continuem visíveis.
|
||||
para essa tupla de conta/homeserver/usuário, para que o estado anterior de sincronização, o estado criptográfico, os bindings de thread
|
||||
e o estado de verificação na inicialização permaneçam visíveis.
|
||||
|
||||
## Gerenciamento de perfil
|
||||
|
||||
@ -664,47 +665,47 @@ openclaw matrix profile set --name "OpenClaw Assistant"
|
||||
openclaw matrix profile set --avatar-url https://cdn.example.org/avatar.png
|
||||
```
|
||||
|
||||
Adicione `--account <id>` quando quiser direcionar explicitamente uma conta Matrix nomeada.
|
||||
Adicione `--account <id>` quando quiser ter como alvo explicitamente uma conta Matrix nomeada.
|
||||
|
||||
O Matrix aceita URLs de avatar `mxc://` diretamente. Quando você passa uma URL de avatar `http://` ou `https://`, o OpenClaw primeiro a envia para o Matrix e armazena a URL `mxc://` resolvida de volta em `channels.matrix.avatarUrl` (ou na substituição da conta selecionada).
|
||||
O Matrix aceita URLs de avatar `mxc://` diretamente. Quando você passa uma URL de avatar `http://` ou `https://`, o OpenClaw primeiro faz upload dela para o Matrix e armazena a URL `mxc://` resolvida de volta em `channels.matrix.avatarUrl` (ou na substituição da conta selecionada).
|
||||
|
||||
## Threads
|
||||
|
||||
O Matrix oferece suporte a threads nativas do Matrix tanto para respostas automáticas quanto para envios da ferramenta de mensagem.
|
||||
O Matrix oferece suporte a threads nativas do Matrix tanto para respostas automáticas quanto para envios da ferramenta de mensagens.
|
||||
|
||||
- `dm.sessionScope: "per-user"` (padrão) mantém o roteamento de DM do Matrix com escopo por remetente, para que várias salas de DM possam compartilhar uma sessão quando forem resolvidas para o mesmo par.
|
||||
- `dm.sessionScope: "per-room"` isola cada sala de DM do Matrix em sua própria chave de sessão, ainda usando autenticação e verificações de lista de permissões normais de DM.
|
||||
- Vínculos explícitos de conversa do Matrix ainda têm precedência sobre `dm.sessionScope`, então salas e threads vinculadas mantêm a sessão de destino escolhida.
|
||||
- `threadReplies: "off"` mantém as respostas no nível superior e mantém as mensagens encadeadas de entrada na sessão pai.
|
||||
- `dm.sessionScope: "per-user"` (padrão) mantém o roteamento de DM do Matrix com escopo por remetente, então várias salas de DM podem compartilhar uma sessão quando são resolvidas para o mesmo par.
|
||||
- `dm.sessionScope: "per-room"` isola cada sala de DM do Matrix em sua própria chave de sessão enquanto ainda usa verificações normais de autenticação e allowlist de DM.
|
||||
- Bindings explícitos de conversa do Matrix ainda têm prioridade sobre `dm.sessionScope`, então salas e threads vinculadas mantêm a sessão de destino escolhida.
|
||||
- `threadReplies: "off"` mantém respostas no nível superior e mantém mensagens de thread recebidas na sessão pai.
|
||||
- `threadReplies: "inbound"` responde dentro de uma thread apenas quando a mensagem recebida já estava nessa thread.
|
||||
- `threadReplies: "always"` mantém respostas de sala em uma thread enraizada na mensagem que acionou a resposta e roteia essa conversa pela sessão com escopo de thread correspondente a partir da primeira mensagem acionadora.
|
||||
- `dm.threadReplies` substitui a configuração de nível superior apenas para DMs. Por exemplo, você pode manter threads de sala isoladas enquanto mantém DMs sem threads.
|
||||
- Mensagens encadeadas recebidas incluem a mensagem raiz da thread como contexto extra do agente.
|
||||
- Envios da ferramenta de mensagem herdam automaticamente a thread atual do Matrix quando o destino é a mesma sala, ou o mesmo destino de usuário em DM, a menos que um `threadId` explícito seja fornecido.
|
||||
- A reutilização do mesmo destino de usuário em DM na mesma sessão só entra em ação quando os metadados da sessão atual comprovam o mesmo par de DM na mesma conta Matrix; caso contrário, o OpenClaw recorre ao roteamento normal com escopo por usuário.
|
||||
- Quando o OpenClaw detecta que uma sala de DM do Matrix colide com outra sala de DM na mesma sessão compartilhada de DM do Matrix, ele publica um único `m.notice` nessa sala com a rota de escape `/focus` quando os vínculos de thread estão ativados e a dica `dm.sessionScope`.
|
||||
- Vínculos de thread em execução são suportados para o Matrix. `/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` e `/acp spawn` vinculado a thread funcionam em salas e DMs do Matrix.
|
||||
- `/focus` no nível superior de sala/DM do Matrix cria uma nova thread do Matrix e a vincula à sessão de destino quando `threadBindings.spawnSubagentSessions=true`.
|
||||
- Executar `/focus` ou `/acp spawn --thread here` dentro de uma thread existente do Matrix vincula essa thread atual no lugar.
|
||||
- `threadReplies: "always"` mantém respostas de sala em uma thread enraizada na mensagem que disparou e roteia essa conversa pela sessão com escopo de thread correspondente desde a primeira mensagem disparadora.
|
||||
- `dm.threadReplies` substitui a configuração de nível superior apenas para DMs. Por exemplo, você pode manter threads de sala isoladas enquanto mantém DMs sem thread.
|
||||
- Mensagens de thread recebidas incluem a mensagem raiz da thread como contexto adicional do agente.
|
||||
- Envios da ferramenta de mensagens herdam automaticamente a thread atual do Matrix quando o destino é a mesma sala ou o mesmo destino de usuário de DM, a menos que um `threadId` explícito seja fornecido.
|
||||
- A reutilização do destino de usuário de DM da mesma sessão só entra em ação quando os metadados da sessão atual comprovam o mesmo par de DM na mesma conta Matrix; caso contrário, o OpenClaw volta ao roteamento normal com escopo por usuário.
|
||||
- Quando o OpenClaw detecta que uma sala de DM do Matrix colide com outra sala de DM na mesma sessão compartilhada de DM do Matrix, ele publica um `m.notice` único nessa sala com a rota de escape `/focus` quando bindings de thread estão ativados e com a dica `dm.sessionScope`.
|
||||
- Bindings de thread em runtime são compatíveis com Matrix. `/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` e `/acp spawn` vinculado a thread funcionam em salas e DMs do Matrix.
|
||||
- `/focus` de sala/DM do Matrix no nível superior cria uma nova thread do Matrix e a vincula à sessão de destino quando `threadBindings.spawnSubagentSessions=true`.
|
||||
- Executar `/focus` ou `/acp spawn --thread here` dentro de uma thread existente do Matrix vincula essa thread atual em vez disso.
|
||||
|
||||
## Vínculos de conversa ACP
|
||||
## Bindings de conversa ACP
|
||||
|
||||
Salas, DMs e threads existentes do Matrix podem ser transformadas em espaços de trabalho ACP duráveis sem mudar a superfície do chat.
|
||||
Salas, DMs e threads Matrix existentes podem ser transformadas em workspaces ACP duráveis sem mudar a superfície de chat.
|
||||
|
||||
Fluxo rápido para operador:
|
||||
Fluxo rápido do operador:
|
||||
|
||||
- Execute `/acp spawn codex --bind here` dentro da DM, sala ou thread existente do Matrix que você quer continuar usando.
|
||||
- Em uma DM ou sala Matrix de nível superior, a DM/sala atual continua sendo a superfície do chat e as mensagens futuras são roteadas para a sessão ACP criada.
|
||||
- Dentro de uma thread existente do Matrix, `--bind here` vincula essa thread atual no lugar.
|
||||
- `/new` e `/reset` redefinem a mesma sessão ACP vinculada no lugar.
|
||||
- `/acp close` fecha a sessão ACP e remove o vínculo.
|
||||
- Em uma DM ou sala Matrix de nível superior, a DM/sala atual continua sendo a superfície de chat e mensagens futuras são roteadas para a sessão ACP criada.
|
||||
- Dentro de uma thread Matrix existente, `--bind here` vincula essa thread atual no mesmo lugar.
|
||||
- `/new` e `/reset` redefinem a mesma sessão ACP vinculada no mesmo lugar.
|
||||
- `/acp close` fecha a sessão ACP e remove o binding.
|
||||
|
||||
Observações:
|
||||
|
||||
- `--bind here` não cria uma thread filha do Matrix.
|
||||
- `threadBindings.spawnAcpSessions` só é necessário para `/acp spawn --thread auto|here`, quando o OpenClaw precisa criar ou vincular uma thread filha do Matrix.
|
||||
|
||||
### Configuração de vínculo de thread
|
||||
### Configuração de binding de thread
|
||||
|
||||
O Matrix herda padrões globais de `session.threadBindings` e também oferece suporte a substituições por canal:
|
||||
|
||||
@ -714,29 +715,29 @@ O Matrix herda padrões globais de `session.threadBindings` e também oferece su
|
||||
- `threadBindings.spawnSubagentSessions`
|
||||
- `threadBindings.spawnAcpSessions`
|
||||
|
||||
Os sinalizadores de criação vinculada a thread do Matrix são opt-in:
|
||||
Sinalizadores de criação vinculada a thread do Matrix são opt-in:
|
||||
|
||||
- Defina `threadBindings.spawnSubagentSessions: true` para permitir que `/focus` no nível superior crie e vincule novas threads do Matrix.
|
||||
- Defina `threadBindings.spawnSubagentSessions: true` para permitir que `/focus` de nível superior crie e vincule novas threads do Matrix.
|
||||
- Defina `threadBindings.spawnAcpSessions: true` para permitir que `/acp spawn --thread auto|here` vincule sessões ACP a threads do Matrix.
|
||||
|
||||
## Reações
|
||||
|
||||
O Matrix oferece suporte a ações de reação de saída, notificações de reação de entrada e reações de confirmação de entrada.
|
||||
|
||||
- A ferramenta de reação de saída é controlada por `channels["matrix"].actions.reactions`.
|
||||
- O ferramental de reação de saída é controlado por `channels["matrix"].actions.reactions`.
|
||||
- `react` adiciona uma reação a um evento específico do Matrix.
|
||||
- `reactions` lista o resumo atual de reações de um evento específico do Matrix.
|
||||
- `reactions` lista o resumo atual de reações para um evento específico do Matrix.
|
||||
- `emoji=""` remove as próprias reações da conta do bot nesse evento.
|
||||
- `remove: true` remove apenas a reação de emoji especificada da conta do bot.
|
||||
|
||||
O escopo das reações de confirmação é resolvido nesta ordem:
|
||||
O escopo de reação de confirmação é resolvido nesta ordem padrão do OpenClaw:
|
||||
|
||||
- `channels["matrix"].accounts.<accountId>.ackReaction`
|
||||
- `channels["matrix"].ackReaction`
|
||||
- `messages.ackReaction`
|
||||
- fallback para o emoji de identidade do agente
|
||||
- fallback para emoji da identidade do agente
|
||||
|
||||
O escopo da reação de confirmação é resolvido nesta ordem:
|
||||
O escopo de reação de confirmação é resolvido nesta ordem:
|
||||
|
||||
- `channels["matrix"].accounts.<accountId>.ackReactionScope`
|
||||
- `channels["matrix"].ackReactionScope`
|
||||
@ -752,25 +753,25 @@ Comportamento:
|
||||
|
||||
- `reactionNotifications: "own"` encaminha eventos `m.reaction` adicionados quando eles têm como alvo mensagens Matrix de autoria do bot.
|
||||
- `reactionNotifications: "off"` desativa eventos de sistema de reação.
|
||||
- Remoções de reação não são sintetizadas em eventos de sistema porque o Matrix as expõe como redações, não como remoções autônomas de `m.reaction`.
|
||||
- Remoções de reação não são sintetizadas em eventos de sistema porque o Matrix as expõe como redações, não como remoções independentes de `m.reaction`.
|
||||
|
||||
## Contexto de histórico
|
||||
## Contexto do histórico
|
||||
|
||||
- `channels.matrix.historyLimit` controla quantas mensagens recentes da sala são incluídas como `InboundHistory` quando uma mensagem de sala do Matrix aciona o agente. Usa como fallback `messages.groupChat.historyLimit`; se ambos não estiverem definidos, o padrão efetivo é `0`. Defina `0` para desativar.
|
||||
- `channels.matrix.historyLimit` controla quantas mensagens recentes da sala são incluídas como `InboundHistory` quando uma mensagem de sala do Matrix dispara o agente. Usa fallback para `messages.groupChat.historyLimit`; se ambos não estiverem definidos, o padrão efetivo é `0`. Defina `0` para desativar.
|
||||
- O histórico de sala do Matrix é somente da sala. DMs continuam usando o histórico normal da sessão.
|
||||
- O histórico de sala do Matrix é apenas pendente: o OpenClaw armazena em buffer mensagens da sala que ainda não acionaram uma resposta e então captura esse intervalo quando uma menção ou outro gatilho chega.
|
||||
- A mensagem gatilho atual não é incluída em `InboundHistory`; ela permanece no corpo principal de entrada daquele turno.
|
||||
- Novas tentativas do mesmo evento do Matrix reutilizam o snapshot original do histórico em vez de avançar para mensagens mais recentes da sala.
|
||||
- O histórico de sala do Matrix é somente pendente: o OpenClaw faz buffer de mensagens da sala que ainda não dispararam uma resposta e depois captura esse intervalo quando uma menção ou outro gatilho chega.
|
||||
- A mensagem de gatilho atual não é incluída em `InboundHistory`; ela permanece no corpo principal de entrada para esse turno.
|
||||
- Novas tentativas do mesmo evento Matrix reutilizam o snapshot do histórico original em vez de avançar para mensagens mais novas da sala.
|
||||
|
||||
## Visibilidade de contexto
|
||||
|
||||
O Matrix oferece suporte ao controle compartilhado `contextVisibility` para contexto suplementar de sala, como texto de resposta buscado, raízes de thread e histórico pendente.
|
||||
O Matrix oferece suporte ao controle compartilhado `contextVisibility` para contexto complementar da sala, como texto de resposta buscado, raízes de thread e histórico pendente.
|
||||
|
||||
- `contextVisibility: "all"` é o padrão. O contexto suplementar é mantido como recebido.
|
||||
- `contextVisibility: "allowlist"` filtra o contexto suplementar para remetentes permitidos pelas verificações ativas de lista de permissões de sala/usuário.
|
||||
- `contextVisibility: "all"` é o padrão. O contexto complementar é mantido como recebido.
|
||||
- `contextVisibility: "allowlist"` filtra o contexto complementar para remetentes permitidos pelas verificações ativas de allowlist de sala/usuário.
|
||||
- `contextVisibility: "allowlist_quote"` se comporta como `allowlist`, mas ainda mantém uma resposta citada explícita.
|
||||
|
||||
Essa configuração afeta a visibilidade do contexto suplementar, não se a própria mensagem de entrada pode acionar uma resposta.
|
||||
Essa configuração afeta a visibilidade do contexto complementar, não se a própria mensagem de entrada pode disparar uma resposta.
|
||||
A autorização do gatilho ainda vem de `groupPolicy`, `groups`, `groupAllowFrom` e das configurações de política de DM.
|
||||
|
||||
## Política de DM e sala
|
||||
@ -796,28 +797,28 @@ A autorização do gatilho ainda vem de `groupPolicy`, `groups`, `groupAllowFrom
|
||||
}
|
||||
```
|
||||
|
||||
Consulte [Groups](/pt-BR/channels/groups) para ver o comportamento de exigência de menção e lista de permissões.
|
||||
Consulte [Groups](/pt-BR/channels/groups) para ver o comportamento de bloqueio por menção e allowlist.
|
||||
|
||||
Exemplo de pareamento para DMs do Matrix:
|
||||
Exemplo de emparelhamento para DMs do Matrix:
|
||||
|
||||
```bash
|
||||
openclaw pairing list matrix
|
||||
openclaw pairing approve matrix <CODE>
|
||||
```
|
||||
|
||||
Se um usuário Matrix não aprovado continuar enviando mensagens antes da aprovação, o OpenClaw reutiliza o mesmo código de pareamento pendente e pode enviar uma resposta de lembrete novamente após um curto cooldown em vez de gerar um novo código.
|
||||
Se um usuário Matrix não aprovado continuar enviando mensagens antes da aprovação, o OpenClaw reutiliza o mesmo código de emparelhamento pendente e pode enviar uma resposta de lembrete novamente após um curto cooldown em vez de gerar um novo código.
|
||||
|
||||
Consulte [Pairing](/pt-BR/channels/pairing) para ver o fluxo compartilhado de pareamento de DM e o layout de armazenamento.
|
||||
Consulte [Pairing](/pt-BR/channels/pairing) para ver o fluxo compartilhado de emparelhamento de DM e o layout de armazenamento.
|
||||
|
||||
## Reparo direto de sala
|
||||
|
||||
Se o estado de mensagem direta sair de sincronia, o OpenClaw pode acabar com mapeamentos `m.direct` obsoletos que apontam para salas individuais antigas em vez da DM ativa. Inspecione o mapeamento atual de um par com:
|
||||
Se o estado de mensagem direta ficar dessincronizado, o OpenClaw pode acabar com mapeamentos `m.direct` antigos que apontam para salas individuais antigas em vez da DM ativa. Inspecione o mapeamento atual para um par com:
|
||||
|
||||
```bash
|
||||
openclaw matrix direct inspect --user-id @alice:example.org
|
||||
```
|
||||
|
||||
Repare-o com:
|
||||
Repare com:
|
||||
|
||||
```bash
|
||||
openclaw matrix direct repair --user-id @alice:example.org
|
||||
@ -826,52 +827,52 @@ openclaw matrix direct repair --user-id @alice:example.org
|
||||
O fluxo de reparo:
|
||||
|
||||
- prefere uma DM estrita 1:1 que já esteja mapeada em `m.direct`
|
||||
- recorre a qualquer DM estrita 1:1 atualmente ingressada com esse usuário
|
||||
- cria uma nova sala direta e reescreve `m.direct` se não existir uma DM saudável
|
||||
- usa fallback para qualquer DM estrita 1:1 atualmente ingressada com esse usuário
|
||||
- cria uma nova sala direta e reescreve `m.direct` se não existir uma DM íntegra
|
||||
|
||||
O fluxo de reparo não exclui automaticamente salas antigas. Ele apenas escolhe a DM saudável e atualiza o mapeamento para que novos envios do Matrix, avisos de verificação e outros fluxos de mensagem direta voltem a apontar para a sala correta.
|
||||
O fluxo de reparo não exclui salas antigas automaticamente. Ele apenas escolhe a DM íntegra e atualiza o mapeamento para que novos envios Matrix, avisos de verificação e outros fluxos de mensagem direta voltem a ter como alvo a sala correta.
|
||||
|
||||
## Aprovações de execução
|
||||
## Aprovações de exec
|
||||
|
||||
O Matrix pode atuar como um cliente nativo de aprovação para uma conta Matrix. Os controles nativos
|
||||
de roteamento de DM/canal ainda ficam sob a configuração de aprovação de execução:
|
||||
de roteamento de DM/canal ainda ficam na configuração de aprovação de exec:
|
||||
|
||||
- `channels.matrix.execApprovals.enabled`
|
||||
- `channels.matrix.execApprovals.approvers` (opcional; usa como fallback `channels.matrix.dm.allowFrom`)
|
||||
- `channels.matrix.execApprovals.approvers` (opcional; usa fallback para `channels.matrix.dm.allowFrom`)
|
||||
- `channels.matrix.execApprovals.target` (`dm` | `channel` | `both`, padrão: `dm`)
|
||||
- `channels.matrix.execApprovals.agentFilter`
|
||||
- `channels.matrix.execApprovals.sessionFilter`
|
||||
|
||||
Os aprovadores devem ser IDs de usuário Matrix, como `@owner:example.org`. O Matrix ativa automaticamente aprovações nativas quando `enabled` não está definido ou é `"auto"` e pelo menos um aprovador pode ser resolvido. Aprovações de execução usam primeiro `execApprovals.approvers` e podem usar como fallback `channels.matrix.dm.allowFrom`. Aprovações de Plugin autorizam por meio de `channels.matrix.dm.allowFrom`. Defina `enabled: false` para desativar explicitamente o Matrix como cliente nativo de aprovação. Caso contrário, solicitações de aprovação recorrem a outras rotas de aprovação configuradas ou à política de fallback de aprovação.
|
||||
Os aprovadores devem ser IDs de usuário Matrix como `@owner:example.org`. O Matrix ativa automaticamente aprovações nativas quando `enabled` não está definido ou é `"auto"` e pelo menos um aprovador pode ser resolvido. Aprovações de exec usam primeiro `execApprovals.approvers` e podem usar fallback para `channels.matrix.dm.allowFrom`. Aprovações de Plugin autorizam por meio de `channels.matrix.dm.allowFrom`. Defina `enabled: false` para desativar explicitamente o Matrix 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.
|
||||
|
||||
O roteamento nativo do Matrix oferece suporte a ambos os tipos de aprovação:
|
||||
|
||||
- `channels.matrix.execApprovals.*` controla o modo nativo de fanout por DM/canal para prompts de aprovação do Matrix.
|
||||
- Aprovações de execução usam o conjunto de aprovadores de execução de `execApprovals.approvers` ou `channels.matrix.dm.allowFrom`.
|
||||
- Aprovações de Plugin usam a lista de permissões de DM do Matrix em `channels.matrix.dm.allowFrom`.
|
||||
- Atalhos de reação e atualizações de mensagem do Matrix se aplicam tanto a aprovações de execução quanto a aprovações de Plugin.
|
||||
- `channels.matrix.execApprovals.*` controla o modo nativo de fanout em DM/canal para prompts de aprovação do Matrix.
|
||||
- Aprovações de exec usam o conjunto de aprovadores de exec de `execApprovals.approvers` ou `channels.matrix.dm.allowFrom`.
|
||||
- Aprovações de Plugin usam a allowlist de DM do Matrix de `channels.matrix.dm.allowFrom`.
|
||||
- Atalhos de reação do Matrix e atualizações de mensagem se aplicam tanto a aprovações de exec quanto de Plugin.
|
||||
|
||||
Regras de entrega:
|
||||
|
||||
- `target: "dm"` envia prompts de aprovação para as DMs dos aprovadores
|
||||
- `target: "dm"` envia prompts de aprovação para DMs dos aprovadores
|
||||
- `target: "channel"` envia o prompt de volta para a sala ou DM Matrix de origem
|
||||
- `target: "both"` envia para as DMs dos aprovadores e para a sala ou DM Matrix de origem
|
||||
- `target: "both"` envia para DMs dos aprovadores e para a sala ou DM Matrix de origem
|
||||
|
||||
Os prompts de aprovação do Matrix semeiam atalhos de reação na mensagem principal de aprovação:
|
||||
Prompts de aprovação do Matrix semeiam atalhos de reação na mensagem principal de aprovação:
|
||||
|
||||
- `✅` = permitir uma vez
|
||||
- `❌` = negar
|
||||
- `♾️` = permitir sempre quando essa decisão for permitida pela política efetiva de execução
|
||||
- `♾️` = permitir sempre quando essa decisão for permitida pela política de exec efetiva
|
||||
|
||||
Os aprovadores podem reagir nessa mensagem ou usar os comandos slash de fallback: `/approve <id> allow-once`, `/approve <id> allow-always` ou `/approve <id> deny`.
|
||||
|
||||
Somente aprovadores resolvidos podem aprovar ou negar. Para aprovações de execução, a entrega por canal inclui o texto do comando, então só ative `channel` ou `both` em salas confiáveis.
|
||||
Somente aprovadores resolvidos podem aprovar ou negar. Para aprovações de exec, a entrega por canal inclui o texto do comando, então ative `channel` ou `both` apenas em salas confiáveis.
|
||||
|
||||
Substituição por conta:
|
||||
|
||||
- `channels.matrix.accounts.<account>.execApprovals`
|
||||
|
||||
Documentação relacionada: [Aprovações de execução](/pt-BR/tools/exec-approvals)
|
||||
Documentação relacionada: [Aprovações de exec](/pt-BR/tools/exec-approvals)
|
||||
|
||||
## Várias contas
|
||||
|
||||
@ -904,13 +905,13 @@ Documentação relacionada: [Aprovações de execução](/pt-BR/tools/exec-appro
|
||||
```
|
||||
|
||||
Os valores de nível superior em `channels.matrix` atuam como padrões para contas nomeadas, a menos que uma conta os substitua.
|
||||
Você pode restringir entradas de sala herdadas a uma conta Matrix com `groups.<room>.account`.
|
||||
Entradas sem `account` permanecem compartilhadas entre todas as contas Matrix, e entradas com `account: "default"` continuam funcionando quando a conta padrão é configurada diretamente no nível superior em `channels.matrix.*`.
|
||||
Padrões parciais compartilhados de autenticação não criam, por si só, uma conta padrão implícita separada. O OpenClaw só sintetiza a conta `default` de nível superior quando esse padrão tem autenticação nova (`homeserver` mais `accessToken`, ou `homeserver` mais `userId` e `password`); contas nomeadas ainda podem continuar detectáveis a partir de `homeserver` mais `userId` quando credenciais em cache satisfazem a autenticação mais tarde.
|
||||
Se o Matrix já tiver exatamente uma conta nomeada, ou `defaultAccount` apontar para uma chave existente de conta nomeada, a promoção de reparo/configuração de conta única para várias contas preserva essa conta em vez de criar uma nova entrada `accounts.default`. Somente chaves de autenticação/bootstrap do Matrix são movidas para essa conta promovida; chaves compartilhadas de política de entrega permanecem no nível superior.
|
||||
Defina `defaultAccount` quando quiser que o OpenClaw prefira uma conta Matrix nomeada para roteamento implícito, sondagem e operações da CLI.
|
||||
Você pode limitar entradas de sala herdadas a uma conta Matrix com `groups.<room>.account`.
|
||||
Entradas sem `account` permanecem compartilhadas entre todas as contas Matrix, e entradas com `account: "default"` ainda funcionam quando a conta padrão é configurada diretamente no nível superior em `channels.matrix.*`.
|
||||
Padrões parciais compartilhados de autenticação não criam por si só uma conta padrão implícita separada. O OpenClaw só sintetiza a conta `default` de nível superior quando esse padrão tem autenticação nova (`homeserver` mais `accessToken`, ou `homeserver` mais `userId` e `password`); contas nomeadas ainda podem continuar detectáveis a partir de `homeserver` mais `userId` quando credenciais em cache satisfizerem a autenticação depois.
|
||||
Se o Matrix já tiver exatamente uma conta nomeada, ou `defaultAccount` apontar para uma chave de conta nomeada existente, a promoção de reparo/configuração de conta única para várias contas preserva essa conta em vez de criar uma nova entrada `accounts.default`. Apenas chaves de autenticação/bootstrap do Matrix são movidas para essa conta promovida; chaves compartilhadas de política de entrega permanecem no nível superior.
|
||||
Defina `defaultAccount` quando quiser que o OpenClaw prefira uma conta Matrix nomeada para roteamento implícito, sondagem e operações de CLI.
|
||||
Se várias contas Matrix estiverem configuradas e um ID de conta for `default`, o OpenClaw usa essa conta implicitamente mesmo quando `defaultAccount` não está definido.
|
||||
Se você configurar várias contas nomeadas, defina `defaultAccount` ou passe `--account <id>` para comandos da CLI que dependem de seleção implícita de conta.
|
||||
Se você configurar várias contas nomeadas, defina `defaultAccount` ou passe `--account <id>` para comandos de CLI que dependem da seleção implícita de conta.
|
||||
Passe `--account <id>` para `openclaw matrix verify ...` e `openclaw matrix devices ...` quando quiser substituir essa seleção implícita para um comando.
|
||||
|
||||
Consulte [Referência de configuração](/pt-BR/gateway/configuration-reference#multi-account-all-channels) para ver o padrão compartilhado de várias contas.
|
||||
@ -918,9 +919,9 @@ Consulte [Referência de configuração](/pt-BR/gateway/configuration-reference#
|
||||
## Homeservers privados/LAN
|
||||
|
||||
Por padrão, o OpenClaw bloqueia homeservers Matrix privados/internos para proteção contra SSRF, a menos que você
|
||||
ative explicitamente essa permissão por conta.
|
||||
ative isso explicitamente por conta.
|
||||
|
||||
Se seu homeserver estiver em localhost, em um IP de LAN/Tailscale ou em um nome de host interno, ative
|
||||
Se seu homeserver roda em localhost, em um IP de LAN/Tailscale ou em um hostname interno, ative
|
||||
`network.dangerouslyAllowPrivateNetwork` para essa conta Matrix:
|
||||
|
||||
```json5
|
||||
@ -947,8 +948,8 @@ openclaw matrix account add \
|
||||
--access-token syt_ops_xxx
|
||||
```
|
||||
|
||||
Essa permissão explícita permite apenas destinos privados/internos confiáveis. Homeservers públicos em texto simples, como
|
||||
`http://matrix.example.org:8008`, continuam bloqueados. Prefira `https://` sempre que possível.
|
||||
Esse opt-in permite apenas destinos privados/internos confiáveis. Homeservers públicos em texto simples como
|
||||
`http://matrix.example.org:8008` continuam bloqueados. Prefira `https://` sempre que possível.
|
||||
|
||||
## Uso de proxy para tráfego Matrix
|
||||
|
||||
@ -967,85 +968,85 @@ Se sua implantação Matrix precisar de um proxy HTTP(S) de saída explícito, d
|
||||
```
|
||||
|
||||
Contas nomeadas podem substituir o padrão de nível superior com `channels.matrix.accounts.<id>.proxy`.
|
||||
O OpenClaw usa a mesma configuração de proxy para tráfego Matrix em execução e para sondas de status da conta.
|
||||
O OpenClaw usa a mesma configuração de proxy para tráfego Matrix em runtime e para sondagens de status da conta.
|
||||
|
||||
## Resolução de destino
|
||||
|
||||
O Matrix aceita estes formatos de destino em qualquer lugar onde o OpenClaw pedir um destino de sala ou usuário:
|
||||
O Matrix aceita estes formatos de destino em qualquer lugar onde o OpenClaw pedir um alvo de sala ou usuário:
|
||||
|
||||
- Usuários: `@user:server`, `user:@user:server` ou `matrix:user:@user:server`
|
||||
- Salas: `!room:server`, `room:!room:server` ou `matrix:room:!room:server`
|
||||
- Aliases: `#alias:server`, `channel:#alias:server` ou `matrix:channel:#alias:server`
|
||||
|
||||
A busca ao vivo em diretório usa a conta Matrix autenticada:
|
||||
A busca ao vivo no diretório usa a conta Matrix autenticada:
|
||||
|
||||
- Buscas de usuário consultam o diretório de usuários Matrix nesse homeserver.
|
||||
- Buscas de sala aceitam diretamente IDs e aliases explícitos de sala e depois recorrem à busca por nomes de salas ingressadas para essa conta.
|
||||
- A busca por nome de sala ingressada é feita em regime de melhor esforço. Se o nome de uma sala não puder ser resolvido para um ID ou alias, ele será ignorado pela resolução da lista de permissões em tempo de execução.
|
||||
- Buscas de usuário consultam o diretório de usuários do Matrix nesse homeserver.
|
||||
- Buscas de sala aceitam diretamente IDs e aliases explícitos de sala e depois usam fallback para pesquisar nomes de salas ingressadas para essa conta.
|
||||
- A busca por nome de sala ingressada é best-effort. Se um nome de sala não puder ser resolvido para um ID ou alias, ele será ignorado pela resolução da allowlist em runtime.
|
||||
|
||||
## Referência de configuração
|
||||
|
||||
- `enabled`: ativa ou desativa o canal.
|
||||
- `name`: rótulo opcional para a conta.
|
||||
- `defaultAccount`: ID de conta preferido quando várias contas Matrix estiverem configuradas.
|
||||
- `defaultAccount`: ID de conta preferido quando várias contas Matrix estão configuradas.
|
||||
- `homeserver`: URL do homeserver, por exemplo `https://matrix.example.org`.
|
||||
- `network.dangerouslyAllowPrivateNetwork`: permite que esta conta Matrix se conecte a homeservers privados/internos. Ative isso quando o homeserver for resolvido para `localhost`, um IP de LAN/Tailscale ou um host interno como `matrix-synapse`.
|
||||
- `proxy`: URL opcional de proxy HTTP(S) para tráfego Matrix. Contas nomeadas podem substituir o padrão de nível superior com seu próprio `proxy`.
|
||||
- `userId`: ID completo do usuário Matrix, por exemplo `@bot:example.org`.
|
||||
- `accessToken`: token de acesso para autenticação baseada em token. Valores em texto simples e valores SecretRef são compatíveis com `channels.matrix.accessToken` e `channels.matrix.accounts.<id>.accessToken` nos provedores env/file/exec. Consulte [Gerenciamento de segredos](/pt-BR/gateway/secrets).
|
||||
- `accessToken`: token de acesso para autenticação baseada em token. Valores em texto simples e valores SecretRef são compatíveis com `channels.matrix.accessToken` e `channels.matrix.accounts.<id>.accessToken` em provedores env/file/exec. Consulte [Gerenciamento de segredos](/pt-BR/gateway/secrets).
|
||||
- `password`: senha para login baseado em senha. Valores em texto simples e valores SecretRef são compatíveis.
|
||||
- `deviceId`: ID explícito do dispositivo Matrix.
|
||||
- `deviceName`: nome de exibição do dispositivo para login por senha.
|
||||
- `avatarUrl`: URL armazenada do próprio avatar para sincronização de perfil e atualizações de `profile set`.
|
||||
- `avatarUrl`: URL do próprio avatar armazenada para sincronização de perfil e atualizações de `profile set`.
|
||||
- `initialSyncLimit`: número máximo de eventos buscados durante a sincronização de inicialização.
|
||||
- `encryption`: ativa E2EE.
|
||||
- `allowlistOnly`: quando `true`, atualiza a política de sala `open` para `allowlist` e força todas as políticas ativas de DM, exceto `disabled` (incluindo `pairing` e `open`), para `allowlist`. Não afeta políticas `disabled`.
|
||||
- `allowBots`: permite mensagens de outras contas Matrix do OpenClaw configuradas (`true` ou `"mentions"`).
|
||||
- `allowlistOnly`: quando `true`, faz upgrade da política de sala `open` para `allowlist` e força todas as políticas ativas de DM, exceto `disabled` (incluindo `pairing` e `open`), para `allowlist`. Não afeta políticas `disabled`.
|
||||
- `allowBots`: permite mensagens de outras contas Matrix configuradas do OpenClaw (`true` ou `"mentions"`).
|
||||
- `groupPolicy`: `open`, `allowlist` ou `disabled`.
|
||||
- `contextVisibility`: modo de visibilidade de contexto suplementar de sala (`all`, `allowlist`, `allowlist_quote`).
|
||||
- `groupAllowFrom`: lista de permissões de IDs de usuário para tráfego de sala. As entradas devem ser IDs completos de usuário Matrix; nomes não resolvidos são ignorados em tempo de execução.
|
||||
- `historyLimit`: número máximo de mensagens da sala a incluir como contexto de histórico de grupo. Usa como fallback `messages.groupChat.historyLimit`; se ambos não estiverem definidos, o padrão efetivo é `0`. Defina `0` para desativar.
|
||||
- `contextVisibility`: modo de visibilidade de contexto complementar da sala (`all`, `allowlist`, `allowlist_quote`).
|
||||
- `groupAllowFrom`: allowlist de IDs de usuário para tráfego de sala. As entradas devem ser IDs completos de usuário Matrix; nomes não resolvidos são ignorados em runtime.
|
||||
- `historyLimit`: máximo de mensagens de sala a incluir como contexto de histórico de grupo. Usa fallback para `messages.groupChat.historyLimit`; se ambos não estiverem definidos, o padrão efetivo é `0`. Defina `0` para desativar.
|
||||
- `replyToMode`: `off`, `first`, `all` ou `batched`.
|
||||
- `markdown`: configuração opcional de renderização de Markdown para texto Matrix de saída.
|
||||
- `markdown`: configuração opcional de renderização Markdown para texto Matrix de saída.
|
||||
- `streaming`: `off` (padrão), `"partial"`, `"quiet"`, `true` ou `false`. `"partial"` e `true` ativam atualizações de rascunho com prévia primeiro usando mensagens de texto normais do Matrix. `"quiet"` usa avisos de prévia sem notificação para configurações auto-hospedadas com regras de push. `false` é equivalente a `"off"`.
|
||||
- `blockStreaming`: `true` ativa mensagens de progresso separadas para blocos concluídos do assistente enquanto o streaming de prévia em rascunho está ativo.
|
||||
- `blockStreaming`: `true` ativa mensagens de progresso separadas para blocos concluídos do assistente enquanto o streaming de prévia de rascunho está ativo.
|
||||
- `threadReplies`: `off`, `inbound` ou `always`.
|
||||
- `threadBindings`: substituições por canal para roteamento e ciclo de vida de sessão vinculados a thread.
|
||||
- `threadBindings`: substituições por canal para roteamento e ciclo de vida de sessão vinculada a thread.
|
||||
- `startupVerification`: modo automático de solicitação de autoverificação na inicialização (`if-unverified`, `off`).
|
||||
- `startupVerificationCooldownHours`: cooldown antes de tentar novamente solicitações automáticas de verificação na inicialização.
|
||||
- `textChunkLimit`: tamanho de fragmento da mensagem de saída em caracteres (aplica-se quando `chunkMode` é `length`).
|
||||
- `textChunkLimit`: tamanho do bloco de mensagem de saída em caracteres (aplica-se quando `chunkMode` é `length`).
|
||||
- `chunkMode`: `length` divide mensagens por contagem de caracteres; `newline` divide em limites de linha.
|
||||
- `responsePrefix`: string opcional adicionada ao início de todas as respostas de saída deste canal.
|
||||
- `ackReaction`: substituição opcional da reação de confirmação para este canal/conta.
|
||||
- `ackReactionScope`: substituição opcional do escopo da reação de confirmação (`group-mentions`, `group-all`, `direct`, `all`, `none`, `off`).
|
||||
- `responsePrefix`: string opcional adicionada no início de todas as respostas de saída deste canal.
|
||||
- `ackReaction`: substituição opcional de reação de confirmação para este canal/conta.
|
||||
- `ackReactionScope`: substituição opcional do escopo de reação de confirmação (`group-mentions`, `group-all`, `direct`, `all`, `none`, `off`).
|
||||
- `reactionNotifications`: modo de notificação de reação de entrada (`own`, `off`).
|
||||
- `mediaMaxMb`: limite de tamanho de mídia em MB para envios de saída e processamento de mídia de entrada.
|
||||
- `autoJoin`: política de entrada automática por convite (`always`, `allowlist`, `off`). Padrão: `off`. Aplica-se a todos os convites do Matrix, incluindo convites no estilo DM.
|
||||
- `autoJoin`: política de entrada automática por convite (`always`, `allowlist`, `off`). Padrão: `off`. Aplica-se a todos os convites Matrix, incluindo convites no estilo DM.
|
||||
- `autoJoinAllowlist`: salas/aliases permitidos quando `autoJoin` é `allowlist`. Entradas de alias são resolvidas para IDs de sala durante o tratamento do convite; o OpenClaw não confia no estado de alias declarado pela sala convidada.
|
||||
- `dm`: bloco de política de DM (`enabled`, `policy`, `allowFrom`, `sessionScope`, `threadReplies`).
|
||||
- `dm.policy`: controla o acesso à DM depois que o OpenClaw entra na sala e a classifica como DM. Isso não altera se um convite é aceito automaticamente.
|
||||
- `dm.allowFrom`: as entradas devem ser IDs completos de usuário Matrix, a menos que você já as tenha resolvido por meio de busca ao vivo em diretório.
|
||||
- `dm.policy`: controla o acesso à DM depois que o OpenClaw entra na sala e a classifica como uma DM. Isso não altera se um convite é aceito automaticamente.
|
||||
- `dm.allowFrom`: as entradas devem ser IDs completos de usuário Matrix, a menos que você já os tenha resolvido por meio da busca ao vivo no diretório.
|
||||
- `dm.sessionScope`: `per-user` (padrão) ou `per-room`. Use `per-room` quando quiser que cada sala de DM do Matrix mantenha contexto separado mesmo que o par seja o mesmo.
|
||||
- `dm.threadReplies`: substituição da política de thread apenas para DM (`off`, `inbound`, `always`). Ela substitui a configuração de nível superior `threadReplies` tanto para o posicionamento da resposta quanto para o isolamento de sessão em DMs.
|
||||
- `execApprovals`: entrega nativa de aprovações de execução do Matrix (`enabled`, `approvers`, `target`, `agentFilter`, `sessionFilter`).
|
||||
- `execApprovals.approvers`: IDs de usuário Matrix autorizados a aprovar solicitações de execução. Opcional quando `dm.allowFrom` já identifica os aprovadores.
|
||||
- `dm.threadReplies`: substituição de política de thread somente para DM (`off`, `inbound`, `always`). Ela substitui a configuração `threadReplies` de nível superior tanto para posicionamento de resposta quanto para isolamento de sessão em DMs.
|
||||
- `execApprovals`: entrega nativa de aprovação de exec do Matrix (`enabled`, `approvers`, `target`, `agentFilter`, `sessionFilter`).
|
||||
- `execApprovals.approvers`: IDs de usuário Matrix autorizados a aprovar solicitações de exec. Opcional quando `dm.allowFrom` já identifica os aprovadores.
|
||||
- `execApprovals.target`: `dm | channel | both` (padrão: `dm`).
|
||||
- `accounts`: substituições nomeadas por conta. Os valores de nível superior de `channels.matrix` atuam como padrões para essas entradas.
|
||||
- `groups`: mapa de políticas por sala. Prefira IDs ou aliases de sala; nomes de sala não resolvidos são ignorados em tempo de execução. A identidade da sessão/do grupo usa o ID estável da sala após a resolução.
|
||||
- `groups`: mapa de política por sala. Prefira IDs de sala ou aliases; nomes de sala não resolvidos são ignorados em runtime. A identidade de sessão/grupo usa o ID estável da sala após a resolução.
|
||||
- `groups.<room>.account`: restringe uma entrada de sala herdada a uma conta Matrix específica em configurações com várias contas.
|
||||
- `groups.<room>.allowBots`: substituição no nível da sala para remetentes de bots configurados (`true` ou `"mentions"`).
|
||||
- `groups.<room>.users`: lista de permissões de remetentes por sala.
|
||||
- `groups.<room>.users`: allowlist de remetentes por sala.
|
||||
- `groups.<room>.tools`: substituições por sala para permitir/negar ferramentas.
|
||||
- `groups.<room>.autoReply`: substituição no nível da sala para exigência de menção. `true` desativa a exigência de menção para essa sala; `false` a força de volta.
|
||||
- `groups.<room>.skills`: filtro opcional de Skills por sala.
|
||||
- `groups.<room>.systemPrompt`: trecho opcional de prompt de sistema por sala.
|
||||
- `groups.<room>.autoReply`: substituição no nível da sala para bloqueio por menção. `true` desativa exigências de menção para essa sala; `false` volta a forçá-las.
|
||||
- `groups.<room>.skills`: filtro opcional de Skills no nível da sala.
|
||||
- `groups.<room>.systemPrompt`: trecho opcional de system prompt no nível da sala.
|
||||
- `rooms`: alias legado para `groups`.
|
||||
- `actions`: controle por ação de ferramentas (`messages`, `reactions`, `pins`, `profile`, `memberInfo`, `channelInfo`, `verification`).
|
||||
|
||||
## Relacionado
|
||||
## Relacionados
|
||||
|
||||
- [Visão geral dos canais](/pt-BR/channels) — todos os canais compatíveis
|
||||
- [Pairing](/pt-BR/channels/pairing) — autenticação de DM e fluxo de pareamento
|
||||
- [Groups](/pt-BR/channels/groups) — comportamento de chat em grupo e exigência de menção
|
||||
- [Roteamento de canais](/pt-BR/channels/channel-routing) — roteamento de sessão para mensagens
|
||||
- [Segurança](/pt-BR/gateway/security) — modelo de acesso e reforço de segurança
|
||||
- [Pairing](/pt-BR/channels/pairing) — autenticação de DM e fluxo de emparelhamento
|
||||
- [Groups](/pt-BR/channels/groups) — comportamento de chat em grupo e bloqueio por menção
|
||||
- [Roteamento de canal](/pt-BR/channels/channel-routing) — roteamento de sessão para mensagens
|
||||
- [Segurança](/pt-BR/gateway/security) — modelo de acesso e proteção
|
||||
|
||||
@ -1,98 +1,98 @@
|
||||
---
|
||||
read_when:
|
||||
- Editar o texto do prompt do sistema, a lista de ferramentas ou as seções de hora/heartbeat
|
||||
- Alterar o comportamento de bootstrap do workspace ou da injeção de Skills
|
||||
summary: O que o prompt do sistema do OpenClaw contém e como ele é montado
|
||||
title: Prompt do sistema
|
||||
- Editando o texto do prompt de sistema, a lista de ferramentas ou as seções de hora/Heartbeat
|
||||
- Alterando o bootstrap do workspace ou o comportamento de injeção de Skills
|
||||
summary: O que o prompt de sistema do OpenClaw contém e como ele é montado
|
||||
title: Prompt de sistema
|
||||
x-i18n:
|
||||
generated_at: "2026-04-12T05:33:09Z"
|
||||
generated_at: "2026-04-15T19:41:35Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 057f01aac51f7737b5223f61f5d55e552d9011232aebb130426e269d8f6c257f
|
||||
source_hash: c740e4646bc4980567338237bfb55126af0df72499ca00a48e4848d9a3608ab4
|
||||
source_path: concepts/system-prompt.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Prompt do sistema
|
||||
# Prompt de sistema
|
||||
|
||||
O OpenClaw cria um prompt do sistema personalizado para cada execução de agente. O prompt é **de propriedade do OpenClaw** e não usa o prompt padrão do pi-coding-agent.
|
||||
O OpenClaw monta um prompt de sistema personalizado para cada execução de agente. O prompt é **de propriedade do OpenClaw** e não usa o prompt padrão do pi-coding-agent.
|
||||
|
||||
O prompt é montado pelo OpenClaw e injetado em cada execução de agente.
|
||||
|
||||
Plugins de provedor podem contribuir com orientações de prompt compatíveis com cache sem substituir o prompt completo de propriedade do OpenClaw. O runtime do provedor pode:
|
||||
Plugins de provedor podem contribuir com orientações de prompt com reconhecimento de cache sem substituir todo o prompt de propriedade do OpenClaw. O runtime do provedor pode:
|
||||
|
||||
- substituir um pequeno conjunto de seções centrais nomeadas (`interaction_style`,
|
||||
`tool_call_style`, `execution_bias`)
|
||||
- injetar um **prefixo estável** acima do limite de cache do prompt
|
||||
- injetar um **sufixo dinâmico** abaixo do limite de cache do prompt
|
||||
|
||||
Use contribuições de propriedade do provedor para ajustes específicos de famílias de modelos. Mantenha a mutação legada de prompt `before_prompt_build` para compatibilidade ou para mudanças de prompt realmente globais, não para o comportamento normal do provedor.
|
||||
Use contribuições de propriedade do provedor para ajustes específicos de famílias de modelos. Mantenha a mutação legada de prompt `before_prompt_build` para compatibilidade ou mudanças de prompt realmente globais, não para o comportamento normal do provedor.
|
||||
|
||||
## Estrutura
|
||||
|
||||
O prompt é intencionalmente compacto e usa seções fixas:
|
||||
|
||||
- **Ferramentas**: lembrete da fonte da verdade de ferramentas estruturadas mais orientações de runtime para uso de ferramentas.
|
||||
- **Segurança**: lembrete curto de proteção para evitar comportamento de busca por poder ou de contorno de supervisão.
|
||||
- **Ferramentas**: lembrete da fonte da verdade de ferramentas estruturadas, além de orientações de uso de ferramentas em runtime.
|
||||
- **Segurança**: lembrete curto de proteção para evitar comportamento de busca de poder ou desvio de supervisão.
|
||||
- **Skills** (quando disponíveis): informa ao modelo como carregar instruções de skill sob demanda.
|
||||
- **Autoatualização do OpenClaw**: como inspecionar a configuração com segurança usando
|
||||
`config.schema.lookup`, aplicar patch na configuração com `config.patch`, substituir a configuração completa com `config.apply` e executar `update.run` apenas mediante solicitação explícita do usuário. A ferramenta `gateway`, exclusiva do proprietário, também se recusa a reescrever
|
||||
`config.schema.lookup`, aplicar patch na configuração com `config.patch`, substituir toda a
|
||||
configuração com `config.apply` e executar `update.run` somente mediante solicitação explícita do usuário. A ferramenta `gateway`, restrita ao proprietário, também se recusa a reescrever
|
||||
`tools.exec.ask` / `tools.exec.security`, incluindo aliases legados `tools.bash.*`
|
||||
que são normalizados para esses caminhos de exec protegidos.
|
||||
que são normalizados para esses caminhos protegidos de exec.
|
||||
- **Workspace**: diretório de trabalho (`agents.defaults.workspace`).
|
||||
- **Documentação**: caminho local para a documentação do OpenClaw (repositório ou pacote npm) e quando lê-la.
|
||||
- **Arquivos do workspace (injetados)**: indica que os arquivos de bootstrap estão incluídos abaixo.
|
||||
- **Sandbox** (quando habilitado): indica runtime em sandbox, caminhos do sandbox e se exec com privilégios elevados está disponível.
|
||||
- **Arquivos do Workspace (injetados)**: indica que os arquivos de bootstrap estão incluídos abaixo.
|
||||
- **Sandbox** (quando habilitado): indica runtime em sandbox, caminhos do sandbox e se exec elevado está disponível.
|
||||
- **Data e hora atuais**: hora local do usuário, fuso horário e formato de hora.
|
||||
- **Tags de resposta**: sintaxe opcional de tags de resposta para provedores compatíveis.
|
||||
- **Heartbeats**: prompt de heartbeat e comportamento de confirmação, quando heartbeats estão habilitados para o agente padrão.
|
||||
- **Runtime**: host, SO, node, raiz do repositório (quando detectada), nível de raciocínio (uma linha).
|
||||
- **Raciocínio**: nível atual de visibilidade + dica do toggle `/reasoning`.
|
||||
- **Raciocínio**: nível atual de visibilidade + dica de alternância com /reasoning.
|
||||
|
||||
A seção Ferramentas também inclui orientações de runtime para trabalhos de longa duração:
|
||||
|
||||
- use cron para acompanhamento futuro (`check back later`, lembretes, trabalho recorrente)
|
||||
em vez de loops de sleep com `exec`, truques de atraso com `yieldMs` ou polling repetido de `process`
|
||||
- use `exec` / `process` apenas para comandos que começam agora e continuam em execução
|
||||
- use Cron para acompanhamento futuro (`check back later`, lembretes, trabalho recorrente)
|
||||
em vez de loops de `exec` com sleep, truques de atraso com `yieldMs` ou polling repetido de `process`
|
||||
- use `exec` / `process` apenas para comandos que começam agora e continuam rodando
|
||||
em segundo plano
|
||||
- quando o wake automático por conclusão estiver habilitado, inicie o comando uma vez e confie
|
||||
no caminho de wake baseado em push quando ele emitir saída ou falhar
|
||||
- quando o despertar automático na conclusão estiver habilitado, inicie o comando uma vez e confie no caminho de despertar baseado em push quando ele emitir saída ou falhar
|
||||
- use `process` para logs, status, entrada ou intervenção quando precisar
|
||||
inspecionar um comando em execução
|
||||
- se a tarefa for maior, prefira `sessions_spawn`; a conclusão de subagentes é
|
||||
baseada em push e é anunciada automaticamente de volta ao solicitante
|
||||
- não faça polling de `subagents list` / `sessions_list` em loop apenas para aguardar
|
||||
baseada em push e anunciada automaticamente de volta ao solicitante
|
||||
- não faça polling de `subagents list` / `sessions_list` em loop apenas para esperar
|
||||
a conclusão
|
||||
|
||||
Quando a ferramenta experimental `update_plan` está habilitada, Ferramentas também informa ao
|
||||
modelo para usá-la apenas em trabalhos não triviais com múltiplas etapas, manter exatamente uma
|
||||
modelo para usá-la apenas em trabalhos não triviais de várias etapas, manter exatamente uma
|
||||
etapa `in_progress` e evitar repetir o plano inteiro após cada atualização.
|
||||
|
||||
As proteções de segurança no prompt do sistema são consultivas. Elas orientam o comportamento do modelo, mas não impõem política. Use política de ferramentas, aprovações de exec, sandboxing e listas de permissões de canais para imposição rígida; operadores podem desativá-las por design.
|
||||
As proteções de segurança no prompt de sistema são orientativas. Elas orientam o comportamento do modelo, mas não impõem política. Use política de ferramentas, aprovações de exec, sandboxing e allowlists de canais para imposição rígida; operadores podem desabilitar isso por design.
|
||||
|
||||
Em canais com cartões/botões de aprovação nativos, o prompt de runtime agora informa ao
|
||||
agente para depender primeiro dessa UI de aprovação nativa. Ele só deve incluir um comando manual
|
||||
`/approve` 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.
|
||||
Em canais com cartões/botões de aprovação nativos, o prompt de runtime agora instrui o
|
||||
agente a confiar primeiro nessa interface nativa de aprovação. Ele só deve incluir um comando manual
|
||||
`/approve` quando o resultado da ferramenta informar que aprovações no chat não estão disponíveis ou
|
||||
que aprovação manual é o único caminho.
|
||||
|
||||
## Modos de prompt
|
||||
|
||||
O OpenClaw pode renderizar prompts do sistema menores para subagentes. O runtime define um
|
||||
O OpenClaw pode renderizar prompts de sistema menores para subagentes. O runtime define um
|
||||
`promptMode` para cada execução (não é uma configuração voltada ao usuário):
|
||||
|
||||
- `full` (padrão): inclui todas as seções acima.
|
||||
- `minimal`: usado para subagentes; omite **Skills**, **Recuperação de memória**, **Autoatualização do OpenClaw**, **Aliases de modelo**, **Identidade do usuário**, **Tags de resposta**,
|
||||
**Mensagens**, **Respostas silenciosas** e **Heartbeats**. Ferramentas, **Segurança**,
|
||||
- `minimal`: usado para subagentes; omite **Skills**, **Recordação de Memória**, **Autoatualização do OpenClaw**, **Aliases de modelos**, **Identidade do usuário**, **Tags de resposta**,
|
||||
**Mensageria**, **Respostas silenciosas** e **Heartbeats**. Ferramentas, **Segurança**,
|
||||
Workspace, Sandbox, Data e hora atuais (quando conhecidas), Runtime e contexto
|
||||
injetado continuam disponíveis.
|
||||
- `none`: retorna apenas a linha de identidade base.
|
||||
- `none`: retorna apenas a linha base de identidade.
|
||||
|
||||
Quando `promptMode=minimal`, prompts extras injetados são rotulados como **Contexto do subagente**
|
||||
em vez de **Contexto do chat em grupo**.
|
||||
em vez de **Contexto de chat em grupo**.
|
||||
|
||||
## Injeção de bootstrap do workspace
|
||||
|
||||
Os arquivos de bootstrap são aparados e anexados em **Contexto do projeto** para que o modelo veja o contexto de identidade e perfil sem precisar fazer leituras explícitas:
|
||||
Os arquivos de bootstrap são recortados e anexados em **Contexto do projeto** para que o modelo veja o contexto de identidade e perfil sem precisar de leituras explícitas:
|
||||
|
||||
- `AGENTS.md`
|
||||
- `SOUL.md`
|
||||
@ -100,49 +100,49 @@ Os arquivos de bootstrap são aparados e anexados em **Contexto do projeto** par
|
||||
- `IDENTITY.md`
|
||||
- `USER.md`
|
||||
- `HEARTBEAT.md`
|
||||
- `BOOTSTRAP.md` (apenas em workspaces totalmente novos)
|
||||
- `BOOTSTRAP.md` (somente em workspaces totalmente novos)
|
||||
- `MEMORY.md` quando presente, caso contrário `memory.md` como fallback em minúsculas
|
||||
|
||||
Todos esses arquivos são **injetados na janela de contexto** em cada turno, a menos que
|
||||
se aplique um gate específico do arquivo. `HEARTBEAT.md` é omitido em execuções normais quando
|
||||
heartbeats estão desabilitados para o agente padrão ou quando
|
||||
`agents.defaults.heartbeat.includeSystemPromptSection` é false. Mantenha os arquivos injetados concisos — especialmente `MEMORY.md`, que pode crescer com o tempo e levar a uso de contexto inesperadamente alto e compactação mais frequente.
|
||||
Todos esses arquivos são **injetados na janela de contexto** em toda rodada, a menos que
|
||||
se aplique um bloqueio específico do arquivo. `HEARTBEAT.md` é omitido em execuções normais quando
|
||||
heartbeats estão desabilitados para o agente padrão ou
|
||||
`agents.defaults.heartbeat.includeSystemPromptSection` é false. Mantenha os arquivos injetados concisos — especialmente `MEMORY.md`, que pode crescer com o tempo e levar a uso de contexto inesperadamente alto e compaction mais frequente.
|
||||
|
||||
> **Observação:** arquivos diários `memory/*.md` **não** fazem parte do bootstrap normal de
|
||||
> Contexto do projeto. Em turnos comuns, eles são acessados sob demanda por meio das
|
||||
> ferramentas `memory_search` e `memory_get`, portanto não contam contra a janela de
|
||||
> contexto, a menos que o modelo os leia explicitamente. Turnos simples de `/new` e
|
||||
> `/reset` são a exceção: o runtime pode prependar memória diária recente
|
||||
> como um bloco único de contexto de inicialização para esse primeiro turno.
|
||||
> **Observação:** arquivos diários `memory/*.md` **não** fazem parte do Contexto do projeto
|
||||
> normal do bootstrap. Em rodadas comuns, eles são acessados sob demanda por meio das
|
||||
> ferramentas `memory_search` e `memory_get`, portanto não contam contra a
|
||||
> janela de contexto, a menos que o modelo os leia explicitamente. Rodadas simples de `/new` e
|
||||
> `/reset` são a exceção: o runtime pode antepor memória diária recente
|
||||
> como um bloco único de contexto inicial para essa primeira rodada.
|
||||
|
||||
Arquivos grandes são truncados com um marcador. O tamanho máximo por arquivo é controlado por
|
||||
`agents.defaults.bootstrapMaxChars` (padrão: 20000). O conteúdo total de bootstrap injetado
|
||||
entre os arquivos é limitado por `agents.defaults.bootstrapTotalMaxChars`
|
||||
entre arquivos é limitado por `agents.defaults.bootstrapTotalMaxChars`
|
||||
(padrão: 150000). Arquivos ausentes injetam um marcador curto de arquivo ausente. Quando ocorre truncamento,
|
||||
o OpenClaw pode injetar um bloco de aviso em Contexto do projeto; controle isso com
|
||||
`agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always`;
|
||||
padrão: `once`).
|
||||
|
||||
Sessões de subagente injetam apenas `AGENTS.md` e `TOOLS.md` (os outros arquivos de bootstrap
|
||||
Sessões de subagentes injetam apenas `AGENTS.md` e `TOOLS.md` (outros arquivos de bootstrap
|
||||
são filtrados para manter pequeno o contexto do subagente).
|
||||
|
||||
Hooks internos podem interceptar esta etapa via `agent:bootstrap` para modificar ou substituir
|
||||
Hooks internos podem interceptar esta etapa por meio de `agent:bootstrap` para mutar ou substituir
|
||||
os arquivos de bootstrap injetados (por exemplo, trocando `SOUL.md` por uma persona alternativa).
|
||||
|
||||
Se você quiser fazer o agente soar menos genérico, comece com
|
||||
[Guia de personalidade do SOUL.md](/pt-BR/concepts/soul).
|
||||
|
||||
Para inspecionar quanto cada arquivo injetado contribui (bruto vs. injetado, truncamento, além da sobrecarga do schema de ferramentas), use `/context list` ou `/context detail`. Veja [Contexto](/pt-BR/concepts/context).
|
||||
Para inspecionar quanto cada arquivo injetado contribui (bruto vs injetado, truncamento, além da sobrecarga do schema da ferramenta), use `/context list` ou `/context detail`. Veja [Contexto](/pt-BR/concepts/context).
|
||||
|
||||
## Tratamento de tempo
|
||||
## Tratamento de hora
|
||||
|
||||
O prompt do sistema inclui uma seção dedicada **Data e hora atuais** quando o
|
||||
fuso horário do usuário é conhecido. Para manter o cache do prompt estável, agora ele inclui apenas o
|
||||
O prompt de sistema inclui uma seção dedicada **Data e hora atuais** quando o
|
||||
fuso horário do usuário é conhecido. Para manter o cache do prompt estável, agora ela inclui apenas o
|
||||
**fuso horário** (sem relógio dinâmico nem formato de hora).
|
||||
|
||||
Use `session_status` quando o agente precisar da hora atual; o cartão de status
|
||||
inclui uma linha de timestamp. A mesma ferramenta também pode opcionalmente definir uma substituição
|
||||
de modelo por sessão (`model=default` a limpa).
|
||||
de modelo por sessão (`model=default` a remove).
|
||||
|
||||
Configure com:
|
||||
|
||||
@ -156,10 +156,10 @@ Veja [Data e hora](/pt-BR/date-time) para detalhes completos do comportamento.
|
||||
Quando existem skills elegíveis, o OpenClaw injeta uma **lista compacta de skills disponíveis**
|
||||
(`formatSkillsForPrompt`) que inclui o **caminho do arquivo** de cada skill. O
|
||||
prompt instrui o modelo a usar `read` para carregar o SKILL.md no local listado
|
||||
(workspace, gerenciado ou empacotado). Se não houver skills elegíveis, a seção
|
||||
Skills é omitida.
|
||||
(workspace, gerenciado ou empacotado). Se não houver skills elegíveis, a
|
||||
seção Skills é omitida.
|
||||
|
||||
A elegibilidade inclui gates de metadados da skill, verificações de ambiente/configuração de runtime
|
||||
A elegibilidade inclui bloqueios de metadados da skill, verificações de ambiente/configuração de runtime
|
||||
e a allowlist efetiva de skills do agente quando `agents.defaults.skills` ou
|
||||
`agents.list[].skills` está configurado.
|
||||
|
||||
@ -173,13 +173,26 @@ e a allowlist efetiva de skills do agente quando `agents.defaults.skills` ou
|
||||
</available_skills>
|
||||
```
|
||||
|
||||
Isso mantém o prompt base pequeno, ao mesmo tempo que ainda permite uso direcionado de skills.
|
||||
Isso mantém o prompt base pequeno enquanto ainda permite uso direcionado de skills.
|
||||
|
||||
O orçamento da lista de skills pertence ao subsistema de skills:
|
||||
|
||||
- Padrão global: `skills.limits.maxSkillsPromptChars`
|
||||
- Sobrescrita por agente: `agents.list[].skillsLimits.maxSkillsPromptChars`
|
||||
|
||||
Trechos genéricos limitados de runtime usam uma superfície diferente:
|
||||
|
||||
- `agents.defaults.contextLimits.*`
|
||||
- `agents.list[].contextLimits.*`
|
||||
|
||||
Essa separação mantém o dimensionamento de skills separado do dimensionamento de leitura/injeção de runtime, como
|
||||
`memory_get`, resultados de ferramentas ao vivo e atualizações de `AGENTS.md` após compaction.
|
||||
|
||||
## Documentação
|
||||
|
||||
Quando disponível, o prompt do sistema inclui uma seção **Documentação** que aponta para o
|
||||
Quando disponível, o prompt de sistema inclui uma seção **Documentação** que aponta para o
|
||||
diretório local da documentação do OpenClaw (seja `docs/` no workspace do repositório ou a documentação do
|
||||
pacote npm empacotado) e também menciona o espelho público, o repositório de origem, o Discord da comunidade e o
|
||||
ClawHub ([https://clawhub.ai](https://clawhub.ai)) para descoberta de skills. O prompt instrui o modelo a consultar primeiro a documentação local
|
||||
para comportamento, comandos, configuração ou arquitetura do OpenClaw e a executar
|
||||
para comportamento, comandos, configuração ou arquitetura do OpenClaw, e a executar
|
||||
`openclaw status` por conta própria quando possível (pedindo ao usuário apenas quando não tiver acesso).
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -7,19 +7,19 @@ sidebarTitle: Channel Plugins
|
||||
summary: Guia passo a passo para criar um Plugin de canal de mensagens para OpenClaw
|
||||
title: Criando Plugins de canal
|
||||
x-i18n:
|
||||
generated_at: "2026-04-15T05:33:50Z"
|
||||
generated_at: "2026-04-15T19:41:41Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: a7f4c746fe3163a8880e14c433f4db4a1475535d91716a53fb879551d8d62f65
|
||||
source_hash: 80e47e61d1e47738361692522b79aff276544446c58a7b41afe5296635dfad4b
|
||||
source_path: plugins/sdk-channel-plugins.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Criando Plugins de canal
|
||||
|
||||
Este guia apresenta a criação de um Plugin de canal que conecta o OpenClaw a uma
|
||||
Este guia mostra como criar um Plugin de canal que conecta o OpenClaw a uma
|
||||
plataforma de mensagens. Ao final, você terá um canal funcional com segurança em DM,
|
||||
pareamento, encadeamento de respostas e mensagens de saída.
|
||||
emparelhamento, encadeamento de respostas e mensagens de saída.
|
||||
|
||||
<Info>
|
||||
Se você ainda não criou nenhum Plugin do OpenClaw antes, leia
|
||||
@ -29,86 +29,86 @@ pareamento, encadeamento de respostas e mensagens de saída.
|
||||
|
||||
## Como os Plugins de canal funcionam
|
||||
|
||||
Plugins de canal não precisam de suas próprias ferramentas de enviar/editar/reagir. O OpenClaw mantém uma
|
||||
Os Plugins de canal não precisam de suas próprias ferramentas de enviar/editar/reagir. O OpenClaw mantém uma
|
||||
ferramenta `message` compartilhada no core. Seu Plugin é responsável por:
|
||||
|
||||
- **Configuração** — resolução de conta e assistente de configuração
|
||||
- **Segurança** — política de DM e listas de permissão
|
||||
- **Pareamento** — fluxo de aprovação de DM
|
||||
- **Gramática de sessão** — como IDs de conversa específicos do provedor são mapeados para chats base, IDs de thread e fallbacks de pai
|
||||
- **Emparelhamento** — fluxo de aprovação de DM
|
||||
- **Gramática de sessão** — como ids de conversa específicos do provedor são mapeados para chats base, ids de thread e fallbacks de pai
|
||||
- **Saída** — envio de texto, mídia e enquetes para a plataforma
|
||||
- **Encadeamento** — como as respostas são encadeadas
|
||||
|
||||
O core é responsável pela ferramenta `message` compartilhada, pelo encadeamento de prompts, pelo formato externo da chave de sessão,
|
||||
pela contabilidade genérica de `:thread:` e pelo dispatch.
|
||||
O core é responsável pela ferramenta de mensagem compartilhada, pela integração com o prompt, pelo formato externo da chave de sessão,
|
||||
pela lógica genérica de `:thread:`, e pelo despacho.
|
||||
|
||||
Se o seu canal adicionar parâmetros à ferramenta de mensagem que transportam origens de mídia, exponha esses
|
||||
nomes de parâmetros por meio de `describeMessageTool(...).mediaSourceParams`. O core usa
|
||||
essa lista explícita para normalização de caminho no sandbox e política de acesso a mídia de saída,
|
||||
então Plugins não precisam de casos especiais no core compartilhado para parâmetros específicos do provedor
|
||||
Se o seu canal adicionar parâmetros da ferramenta de mensagem que carregam fontes de mídia, exponha esses
|
||||
nomes de parâmetro por meio de `describeMessageTool(...).mediaSourceParams`. O core usa
|
||||
essa lista explícita para normalização de caminho em sandbox e política de acesso
|
||||
a mídia de saída, para que os Plugins não precisem de casos especiais no core compartilhado para parâmetros específicos do provedor,
|
||||
como avatar, anexo ou imagem de capa.
|
||||
Prefira retornar um mapa indexado por ação, como
|
||||
`{ "set-profile": ["avatarUrl", "avatarPath"] }`, para que ações não relacionadas não
|
||||
herdem os argumentos de mídia de outra ação. Um array simples ainda funciona para parâmetros que
|
||||
são intencionalmente compartilhados entre todas as ações expostas.
|
||||
|
||||
Se a sua plataforma armazena escopo extra dentro de IDs de conversa, mantenha essa análise
|
||||
no Plugin com `messaging.resolveSessionConversation(...)`. Esse é o hook canônico
|
||||
para mapear `rawId` para o ID base da conversa, ID opcional de thread,
|
||||
Se a sua plataforma armazenar escopo extra dentro dos ids de conversa, mantenha essa lógica de parsing
|
||||
no Plugin com `messaging.resolveSessionConversation(...)`. Esse é o hook canônico para mapear
|
||||
`rawId` para o id da conversa base, id opcional de thread,
|
||||
`baseConversationId` explícito e quaisquer `parentConversationCandidates`.
|
||||
Ao retornar `parentConversationCandidates`, mantenha-os ordenados do
|
||||
pai mais específico para a conversa pai mais ampla/base.
|
||||
Quando você retornar `parentConversationCandidates`, mantenha-os ordenados do
|
||||
pai mais específico para a conversa base/mais ampla.
|
||||
|
||||
Plugins empacotados que precisam da mesma análise antes que o registro de canal seja inicializado
|
||||
também podem expor um arquivo `session-key-api.ts` de nível superior com uma exportação
|
||||
correspondente `resolveSessionConversation(...)`. O core usa essa superfície segura para bootstrap
|
||||
Plugins empacotados que precisam do mesmo parsing antes de o registro de canais ser inicializado
|
||||
também podem expor um arquivo de nível superior `session-key-api.ts` com uma exportação
|
||||
`resolveSessionConversation(...)` correspondente. O core usa essa superfície segura para bootstrap
|
||||
apenas quando o registro de Plugins em runtime ainda não está disponível.
|
||||
|
||||
`messaging.resolveParentConversationCandidates(...)` continua disponível como um
|
||||
fallback legado de compatibilidade quando um Plugin só precisa de fallbacks de pai além
|
||||
do ID genérico/bruto. Se ambos os hooks existirem, o core usa primeiro
|
||||
`resolveSessionConversation(...).parentConversationCandidates` e só então
|
||||
`messaging.resolveParentConversationCandidates(...)` continua disponível como
|
||||
fallback legado de compatibilidade quando um Plugin só precisa de fallbacks de pai
|
||||
sobre o id genérico/raw. Se ambos os hooks existirem, o core usa
|
||||
`resolveSessionConversation(...).parentConversationCandidates` primeiro e só
|
||||
recorre a `resolveParentConversationCandidates(...)` quando o hook canônico
|
||||
não os inclui.
|
||||
os omite.
|
||||
|
||||
## Aprovações e capacidades do canal
|
||||
|
||||
A maioria dos Plugins de canal não precisa de código específico para aprovação.
|
||||
A maioria dos Plugins de canal não precisa de código específico para aprovações.
|
||||
|
||||
- O core é responsável por `/approve` no mesmo chat, payloads compartilhados de botão de aprovação e entrega genérica de fallback.
|
||||
- Prefira um único objeto `approvalCapability` no Plugin de canal quando o canal precisar de comportamento específico de aprovação.
|
||||
- `ChannelPlugin.approvals` foi removido. Coloque fatos de entrega/renderização/autenticação/aprovação nativa em `approvalCapability`.
|
||||
- `plugin.auth` é apenas para login/logout; o core não lê mais hooks de autenticação de aprovação desse objeto.
|
||||
- `approvalCapability.authorizeActorAction` e `approvalCapability.getActionAvailabilityState` são a interface canônica de autenticação de aprovação.
|
||||
- Use `approvalCapability.getActionAvailabilityState` para disponibilidade de autenticação de aprovação no mesmo chat.
|
||||
- Se o seu canal expõe aprovações nativas de execução, use `approvalCapability.getExecInitiatingSurfaceState` para o estado da superfície iniciadora/cliente nativo quando ele diferir da autenticação de aprovação no mesmo chat. O core usa esse hook específico de execução para distinguir `enabled` de `disabled`, decidir se o canal iniciador oferece suporte a aprovações nativas de execução e incluir o canal nas orientações de fallback de cliente nativo. `createApproverRestrictedNativeApprovalCapability(...)` preenche isso para o caso comum.
|
||||
- Use `outbound.shouldSuppressLocalPayloadPrompt` ou `outbound.beforeDeliverPayload` para comportamento específico do canal no ciclo de vida do payload, como ocultar prompts locais de aprovação duplicados ou enviar indicadores de digitação antes da entrega.
|
||||
- Use `approvalCapability.delivery` apenas para roteamento de aprovação nativa ou supressão de fallback.
|
||||
- Use `approvalCapability.nativeRuntime` para fatos de aprovação nativa pertencentes ao canal. Mantenha isso lazy em entrypoints quentes do canal com `createLazyChannelApprovalNativeRuntimeAdapter(...)`, que pode importar seu módulo de runtime sob demanda enquanto ainda permite que o core monte o ciclo de vida de aprovação.
|
||||
- Prefira um único objeto `approvalCapability` no Plugin de canal quando o canal precisar de comportamento específico para aprovações.
|
||||
- `ChannelPlugin.approvals` foi removido. Coloque fatos de entrega/renderização/autorização nativa de aprovação em `approvalCapability`.
|
||||
- `plugin.auth` é apenas para login/logout; o core não lê mais hooks de autorização de aprovação desse objeto.
|
||||
- `approvalCapability.authorizeActorAction` e `approvalCapability.getActionAvailabilityState` são a superfície canônica para autorização de aprovação.
|
||||
- Use `approvalCapability.getActionAvailabilityState` para disponibilidade de autorização de aprovação no mesmo chat.
|
||||
- Se o seu canal expuser aprovações nativas de execução, use `approvalCapability.getExecInitiatingSurfaceState` para o estado da superfície iniciadora/cliente nativo quando ele diferir da autorização de aprovação no mesmo chat. O core usa esse hook específico de execução para distinguir `enabled` de `disabled`, decidir se o canal iniciador oferece suporte a aprovações nativas de execução e incluir o canal na orientação de fallback do cliente nativo. `createApproverRestrictedNativeApprovalCapability(...)` preenche isso para o caso comum.
|
||||
- Use `outbound.shouldSuppressLocalPayloadPrompt` ou `outbound.beforeDeliverPayload` para comportamento específico do canal no ciclo de vida do payload, como ocultar prompts locais duplicados de aprovação ou enviar indicadores de digitação antes da entrega.
|
||||
- Use `approvalCapability.delivery` apenas para roteamento nativo de aprovação ou supressão de fallback.
|
||||
- Use `approvalCapability.nativeRuntime` para fatos de aprovação nativa controlados pelo canal. Mantenha-o lazy em pontos de entrada críticos do canal com `createLazyChannelApprovalNativeRuntimeAdapter(...)`, que pode importar seu módulo de runtime sob demanda e ainda permitir que o core monte o ciclo de vida da aprovação.
|
||||
- Use `approvalCapability.render` apenas quando um canal realmente precisar de payloads de aprovação personalizados em vez do renderizador compartilhado.
|
||||
- Use `approvalCapability.describeExecApprovalSetup` quando o canal quiser que a resposta do caminho desabilitado explique exatamente quais controles de configuração são necessários para habilitar aprovações nativas de execução. O hook recebe `{ channel, channelLabel, accountId }`; canais com contas nomeadas devem renderizar caminhos com escopo por conta, como `channels.<channel>.accounts.<id>.execApprovals.*`, em vez de padrões no nível superior.
|
||||
- Se um canal puder inferir identidades estáveis de DM semelhantes a proprietário a partir da configuração existente, use `createResolvedApproverActionAuthAdapter` de `openclaw/plugin-sdk/approval-runtime` para restringir `/approve` no mesmo chat sem adicionar lógica específica de aprovação ao core.
|
||||
- Se um canal precisar de entrega de aprovação nativa, mantenha o código do canal focado em normalização de destino e fatos de transporte/apresentação. Use `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver` e `createApproverRestrictedNativeApprovalCapability` de `openclaw/plugin-sdk/approval-runtime`. Coloque os fatos específicos do canal atrás de `approvalCapability.nativeRuntime`, idealmente por meio de `createChannelApprovalNativeRuntimeAdapter(...)` ou `createLazyChannelApprovalNativeRuntimeAdapter(...)`, para que o core possa montar o handler e controlar filtragem de requisições, roteamento, deduplicação, expiração, assinatura do Gateway e avisos de redirecionamento. `nativeRuntime` é dividido em algumas interfaces menores:
|
||||
- `availability` — se a conta está configurada e se uma requisição deve ser tratada
|
||||
- `presentation` — mapeia o modelo de visualização de aprovação compartilhado para payloads nativos pendentes/resolvidos/expirados ou ações finais
|
||||
- `transport` — prepara destinos e envia/atualiza/remove mensagens nativas de aprovação
|
||||
- `interactions` — hooks opcionais de bind/unbind/clear-action para botões ou reações nativas
|
||||
- Use `approvalCapability.describeExecApprovalSetup` quando o canal quiser que a resposta do caminho desabilitado explique exatamente quais opções de configuração são necessárias para habilitar aprovações nativas de execução. O hook recebe `{ channel, channelLabel, accountId }`; canais com contas nomeadas devem renderizar caminhos com escopo de conta, como `channels.<channel>.accounts.<id>.execApprovals.*`, em vez de padrões de nível superior.
|
||||
- Se um canal puder inferir identidades estáveis semelhantes a proprietário em DM a partir da configuração existente, use `createResolvedApproverActionAuthAdapter` de `openclaw/plugin-sdk/approval-runtime` para restringir `/approve` no mesmo chat sem adicionar lógica específica de aprovação ao core.
|
||||
- Se um canal precisar de entrega nativa de aprovação, mantenha o código do canal focado em normalização de alvo mais fatos de transporte/apresentação. Use `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver` e `createApproverRestrictedNativeApprovalCapability` de `openclaw/plugin-sdk/approval-runtime`. Coloque os fatos específicos do canal atrás de `approvalCapability.nativeRuntime`, idealmente por meio de `createChannelApprovalNativeRuntimeAdapter(...)` ou `createLazyChannelApprovalNativeRuntimeAdapter(...)`, para que o core possa montar o handler e controlar filtragem de solicitações, roteamento, eliminação de duplicatas, expiração, assinatura do Gateway e avisos de roteamento para outro local. `nativeRuntime` é dividido em algumas superfícies menores:
|
||||
- `availability` — se a conta está configurada e se uma solicitação deve ser tratada
|
||||
- `presentation` — mapeia o modelo de visualização compartilhado de aprovação em payloads nativos pendentes/resolvidos/expirados ou ações finais
|
||||
- `transport` — prepara alvos e envia/atualiza/remove mensagens nativas de aprovação
|
||||
- `interactions` — hooks opcionais de bind/unbind/clear-action para botões nativos ou reações
|
||||
- `observe` — hooks opcionais de diagnóstico de entrega
|
||||
- Se o canal precisar de objetos pertencentes ao runtime, como cliente, token, app Bolt ou receptor de Webhook, registre-os por meio de `openclaw/plugin-sdk/channel-runtime-context`. O registro genérico de contexto de runtime permite que o core inicialize handlers orientados por capacidade a partir do estado de inicialização do canal sem adicionar cola específica de aprovação.
|
||||
- Recorra a `createChannelApprovalHandler` ou `createChannelNativeApprovalRuntime` de nível mais baixo apenas quando a interface orientada por capacidade ainda não for expressiva o suficiente.
|
||||
- Canais de aprovação nativa devem rotear tanto `accountId` quanto `approvalKind` por meio desses helpers. `accountId` mantém a política de aprovação multiconta limitada à conta de bot correta, e `approvalKind` mantém o comportamento de aprovação de execução vs Plugin disponível para o canal sem ramificações codificadas no core.
|
||||
- O core agora também é responsável pelos avisos de redirecionamento de aprovação. Plugins de canal não devem enviar suas próprias mensagens de acompanhamento do tipo "a aprovação foi para DMs / outro canal" a partir de `createChannelNativeApprovalRuntime`; em vez disso, exponha roteamento preciso de origem + DM do aprovador por meio dos helpers compartilhados de capacidade de aprovação e deixe o core agregar as entregas reais antes de publicar qualquer aviso de volta no chat iniciador.
|
||||
- Preserve o tipo do ID de aprovação entregue de ponta a ponta. Clientes nativos não devem
|
||||
adivinhar nem reescrever o roteamento de aprovação de execução vs Plugin com base no estado local do canal.
|
||||
- Se o canal precisar de objetos controlados pelo runtime, como um cliente, token, app Bolt ou receptor de Webhook, registre-os por meio de `openclaw/plugin-sdk/channel-runtime-context`. O registro genérico de contexto de runtime permite que o core inicialize handlers orientados por capacidade a partir do estado de inicialização do canal sem adicionar glue de wrapper específico para aprovação.
|
||||
- Recorra a `createChannelApprovalHandler` ou `createChannelNativeApprovalRuntime` de nível mais baixo apenas quando a superfície orientada por capacidade ainda não for expressiva o suficiente.
|
||||
- Canais com aprovação nativa devem rotear `accountId` e `approvalKind` por esses helpers. `accountId` mantém a política de aprovação multiconta restrita à conta de bot correta, e `approvalKind` mantém o comportamento de aprovação de execução vs Plugin disponível para o canal sem ramificações codificadas no core.
|
||||
- O core agora também é responsável por avisos de redirecionamento de aprovação. Plugins de canal não devem enviar suas próprias mensagens de acompanhamento do tipo "a aprovação foi para DMs / outro canal" a partir de `createChannelNativeApprovalRuntime`; em vez disso, exponha roteamento preciso de origem + DM do aprovador por meio dos helpers compartilhados de capacidade de aprovação e deixe o core agregar as entregas reais antes de publicar qualquer aviso de volta no chat iniciador.
|
||||
- Preserve a categoria do id de aprovação entregue de ponta a ponta. Clientes nativos não devem
|
||||
inferir nem reescrever o roteamento de aprovação de execução vs Plugin com base no estado local do canal.
|
||||
- Diferentes tipos de aprovação podem expor intencionalmente diferentes superfícies nativas.
|
||||
Exemplos empacotados atuais:
|
||||
- O Slack mantém o roteamento nativo de aprovação disponível tanto para IDs de execução quanto de Plugin.
|
||||
- O Matrix mantém o mesmo roteamento nativo de DM/canal e a mesma UX de reação para aprovações de execução
|
||||
e de Plugin, ao mesmo tempo que ainda permite que a autenticação varie por tipo de aprovação.
|
||||
- `createApproverRestrictedNativeApprovalAdapter` ainda existe como wrapper de compatibilidade, mas novos códigos devem preferir o builder de capacidade e expor `approvalCapability` no Plugin.
|
||||
Exemplos atuais empacotados:
|
||||
- O Slack mantém o roteamento nativo de aprovação disponível tanto para ids de execução quanto de Plugin.
|
||||
- O Matrix mantém o mesmo roteamento nativo por DM/canal e a mesma UX de reação para aprovações de execução
|
||||
e de Plugin, ao mesmo tempo em que ainda permite que a autorização difira por tipo de aprovação.
|
||||
- `createApproverRestrictedNativeApprovalAdapter` ainda existe como wrapper de compatibilidade, mas código novo deve preferir o builder de capacidade e expor `approvalCapability` no Plugin.
|
||||
|
||||
Para entrypoints quentes do canal, prefira os subcaminhos de runtime mais específicos quando você
|
||||
precisar de apenas uma parte dessa família:
|
||||
Para pontos de entrada críticos do canal, prefira os subcaminhos de runtime mais específicos quando você só
|
||||
precisar de uma parte dessa família:
|
||||
|
||||
- `openclaw/plugin-sdk/approval-auth-runtime`
|
||||
- `openclaw/plugin-sdk/approval-client-runtime`
|
||||
@ -136,29 +136,31 @@ Especificamente para setup:
|
||||
`createSetupInputPresenceValidator`), saída de nota de consulta,
|
||||
`promptResolvedAllowFrom`, `splitSetupEntries` e os builders
|
||||
delegados de proxy de setup
|
||||
- `openclaw/plugin-sdk/setup-adapter-runtime` é a interface estreita sensível a ambiente
|
||||
- `openclaw/plugin-sdk/setup-adapter-runtime` é a superfície estreita de adaptador com reconhecimento de env
|
||||
para `createEnvPatchedAccountSetupAdapter`
|
||||
- `openclaw/plugin-sdk/channel-setup` cobre os builders de setup de instalação opcional
|
||||
além de alguns primitivos seguros para setup:
|
||||
- `openclaw/plugin-sdk/channel-setup` cobre os builders de setup com instalação opcional
|
||||
além de algumas primitivas seguras para setup:
|
||||
`createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`,
|
||||
|
||||
Se o seu canal oferece suporte a setup ou autenticação orientados por variáveis de ambiente e fluxos genéricos de inicialização/configuração
|
||||
devem conhecer esses nomes de variáveis antes do carregamento em runtime, declare-os no
|
||||
manifesto do Plugin com `channelEnvVars`. Mantenha `envVars` do runtime do canal ou constantes locais apenas para cópia voltada ao operador.
|
||||
Se o seu canal oferecer suporte a setup ou auth orientados por env e os fluxos genéricos de inicialização/configuração
|
||||
precisarem conhecer esses nomes de env antes de o runtime ser carregado, declare-os no
|
||||
manifesto do Plugin com `channelEnvVars`. Mantenha `envVars` do runtime do canal ou constantes locais apenas
|
||||
para cópia voltada ao operador.
|
||||
`createOptionalChannelSetupWizard`, `DEFAULT_ACCOUNT_ID`,
|
||||
`createTopLevelChannelDmPolicy`, `setSetupChannelEnabled` e
|
||||
`splitSetupEntries`
|
||||
|
||||
- use a interface mais ampla `openclaw/plugin-sdk/setup` apenas quando também precisar dos
|
||||
- use a superfície mais ampla `openclaw/plugin-sdk/setup` apenas quando você também precisar dos
|
||||
helpers compartilhados mais pesados de setup/configuração, como
|
||||
`moveSingleAccountChannelSectionToDefaultAccount(...)`
|
||||
|
||||
Se o seu canal só quiser anunciar "instale este Plugin primeiro" em superfícies
|
||||
de setup, prefira `createOptionalChannelSetupSurface(...)`. O
|
||||
adaptador/assistente gerado falha de forma fechada em gravações de configuração e finalização, e reutiliza
|
||||
a mesma mensagem de instalação obrigatória em validação, finalização e texto de link da documentação.
|
||||
adaptador/assistente gerado falha em modo fechado em gravações de configuração e finalização, e reutiliza
|
||||
a mesma mensagem de instalação obrigatória em validação, finalização e cópia
|
||||
de link da documentação.
|
||||
|
||||
Para outros caminhos quentes do canal, prefira os helpers estreitos em vez de superfícies
|
||||
Para outros caminhos críticos do canal, prefira os helpers específicos em vez de superfícies
|
||||
legadas mais amplas:
|
||||
|
||||
- `openclaw/plugin-sdk/account-core`,
|
||||
@ -167,38 +169,38 @@ legadas mais amplas:
|
||||
`openclaw/plugin-sdk/account-helpers` para configuração multiconta e
|
||||
fallback de conta padrão
|
||||
- `openclaw/plugin-sdk/inbound-envelope` e
|
||||
`openclaw/plugin-sdk/inbound-reply-dispatch` para encadeamento de rota/envelope de entrada e
|
||||
record-and-dispatch
|
||||
- `openclaw/plugin-sdk/messaging-targets` para análise e correspondência de destino
|
||||
`openclaw/plugin-sdk/inbound-reply-dispatch` para rota/envelope de entrada e
|
||||
integração de registro e despacho
|
||||
- `openclaw/plugin-sdk/messaging-targets` para parsing/correspondência de alvos
|
||||
- `openclaw/plugin-sdk/outbound-media` e
|
||||
`openclaw/plugin-sdk/outbound-runtime` para carregamento de mídia e delegates de
|
||||
identidade/envio de saída
|
||||
- `openclaw/plugin-sdk/thread-bindings-runtime` para ciclo de vida de vínculo de thread
|
||||
e registro de adaptador
|
||||
- `openclaw/plugin-sdk/agent-media-payload` apenas quando um layout legado de campo
|
||||
de payload de agente/mídia ainda for necessário
|
||||
- `openclaw/plugin-sdk/telegram-command-config` para normalização de comandos personalizados do Telegram, validação de duplicidade/conflito e um contrato de configuração de comando estável para fallback
|
||||
`openclaw/plugin-sdk/outbound-runtime` para carregamento de mídia mais delegados
|
||||
de identidade/envio de saída
|
||||
- `openclaw/plugin-sdk/thread-bindings-runtime` para ciclo de vida de vinculação de thread
|
||||
e registro de adaptadores
|
||||
- `openclaw/plugin-sdk/agent-media-payload` apenas quando um layout de campo legado de payload de agente/mídia
|
||||
ainda for necessário
|
||||
- `openclaw/plugin-sdk/telegram-command-config` para normalização de comandos personalizados do Telegram, validação de duplicatas/conflitos e um contrato de configuração de comando estável em fallback
|
||||
|
||||
Canais somente com autenticação geralmente podem parar no caminho padrão: o core lida com aprovações e o Plugin apenas expõe capacidades de saída/autenticação. Canais de aprovação nativa, como Matrix, Slack, Telegram e transportes de chat personalizados, devem usar os helpers nativos compartilhados em vez de implementar seu próprio ciclo de vida de aprovação.
|
||||
Canais somente com auth normalmente podem ficar no caminho padrão: o core trata as aprovações e o Plugin apenas expõe capacidades de saída/auth. Canais com aprovação nativa, como Matrix, Slack, Telegram e transportes de chat personalizados, devem usar os helpers nativos compartilhados em vez de implementar seu próprio ciclo de vida de aprovação.
|
||||
|
||||
## Política de menção de entrada
|
||||
|
||||
Mantenha o tratamento de menções de entrada dividido em duas camadas:
|
||||
|
||||
- coleta de evidências pertencente ao Plugin
|
||||
- coleta de evidências controlada pelo Plugin
|
||||
- avaliação de política compartilhada
|
||||
|
||||
Use `openclaw/plugin-sdk/channel-inbound` para a camada compartilhada.
|
||||
|
||||
Bom ajuste para lógica local do Plugin:
|
||||
Bom encaixe para lógica local do Plugin:
|
||||
|
||||
- detecção de resposta ao bot
|
||||
- detecção de citação do bot
|
||||
- verificações de participação na thread
|
||||
- verificações de participação em thread
|
||||
- exclusões de mensagens de serviço/sistema
|
||||
- caches nativos da plataforma necessários para comprovar a participação do bot
|
||||
|
||||
Bom ajuste para o helper compartilhado:
|
||||
Bom encaixe para o helper compartilhado:
|
||||
|
||||
- `requireMention`
|
||||
- resultado explícito de menção
|
||||
@ -259,8 +261,8 @@ Plugins de canal empacotados que já dependem de injeção em runtime:
|
||||
- `resolveInboundMentionDecision`
|
||||
|
||||
Os helpers mais antigos `resolveMentionGating*` permanecem em
|
||||
`openclaw/plugin-sdk/channel-inbound` apenas como exportações de compatibilidade. Novos códigos
|
||||
devem usar `resolveInboundMentionDecision({ facts, policy })`.
|
||||
`openclaw/plugin-sdk/channel-inbound` apenas como exports de compatibilidade. Código novo
|
||||
deve usar `resolveInboundMentionDecision({ facts, policy })`.
|
||||
|
||||
## Passo a passo
|
||||
|
||||
@ -269,7 +271,7 @@ devem usar `resolveInboundMentionDecision({ facts, policy })`.
|
||||
<Step title="Pacote e manifesto">
|
||||
Crie os arquivos padrão do Plugin. O campo `channel` em `package.json` é
|
||||
o que torna este um Plugin de canal. Para a superfície completa de metadados do pacote,
|
||||
consulte [Configuração e Setup de Plugin](/pt-BR/plugins/sdk-setup#openclaw-channel):
|
||||
veja [Setup e Configuração do Plugin](/pt-BR/plugins/sdk-setup#openclaw-channel):
|
||||
|
||||
<CodeGroup>
|
||||
```json package.json
|
||||
@ -283,7 +285,7 @@ devem usar `resolveInboundMentionDecision({ facts, policy })`.
|
||||
"channel": {
|
||||
"id": "acme-chat",
|
||||
"label": "Acme Chat",
|
||||
"blurb": "Connect OpenClaw to Acme Chat."
|
||||
"blurb": "Conecte o OpenClaw ao Acme Chat."
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -295,7 +297,7 @@ devem usar `resolveInboundMentionDecision({ facts, policy })`.
|
||||
"kind": "channel",
|
||||
"channels": ["acme-chat"],
|
||||
"name": "Acme Chat",
|
||||
"description": "Acme Chat channel plugin",
|
||||
"description": "Plugin de canal do Acme Chat",
|
||||
"configSchema": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
@ -319,7 +321,7 @@ devem usar `resolveInboundMentionDecision({ facts, policy })`.
|
||||
</Step>
|
||||
|
||||
<Step title="Crie o objeto do Plugin de canal">
|
||||
A interface `ChannelPlugin` tem muitas superfícies opcionais de adaptador. Comece com
|
||||
A interface `ChannelPlugin` tem muitas superfícies de adaptador opcionais. Comece com
|
||||
o mínimo — `id` e `setup` — e adicione adaptadores conforme necessário.
|
||||
|
||||
Crie `src/channel.ts`:
|
||||
@ -416,17 +418,17 @@ devem usar `resolveInboundMentionDecision({ facts, policy })`.
|
||||
```
|
||||
|
||||
<Accordion title="O que `createChatChannelPlugin` faz por você">
|
||||
Em vez de implementar interfaces de adaptador de baixo nível manualmente, você passa
|
||||
Em vez de implementar manualmente interfaces de adaptador de baixo nível, você passa
|
||||
opções declarativas e o builder as compõe:
|
||||
|
||||
| Opção | O que ela conecta |
|
||||
| --- | --- |
|
||||
| `security.dm` | Resolver de segurança de DM com escopo a partir de campos de configuração |
|
||||
| `pairing.text` | Fluxo de pareamento de DM baseado em texto com troca de código |
|
||||
| `threading` | Resolver de modo reply-to (fixo, com escopo por conta ou personalizado) |
|
||||
| `outbound.attachedResults` | Funções de envio que retornam metadados de resultado (IDs de mensagem) |
|
||||
| `security.dm` | Resolvedor de segurança de DM com escopo a partir dos campos de configuração |
|
||||
| `pairing.text` | Fluxo de emparelhamento por DM baseado em texto com troca de código |
|
||||
| `threading` | Resolvedor de modo reply-to (fixo, com escopo de conta ou personalizado) |
|
||||
| `outbound.attachedResults` | Funções de envio que retornam metadados do resultado (ids de mensagem) |
|
||||
|
||||
Você também pode passar objetos brutos de adaptador em vez de opções declarativas
|
||||
Você também pode passar objetos de adaptador brutos em vez das opções declarativas
|
||||
se precisar de controle total.
|
||||
</Accordion>
|
||||
|
||||
@ -468,15 +470,15 @@ devem usar `resolveInboundMentionDecision({ facts, policy })`.
|
||||
});
|
||||
```
|
||||
|
||||
Coloque descritores de CLI pertencentes ao canal em `registerCliMetadata(...)` para que o OpenClaw
|
||||
Coloque descritores de CLI controlados pelo canal em `registerCliMetadata(...)` para que o OpenClaw
|
||||
possa mostrá-los na ajuda raiz sem ativar o runtime completo do canal,
|
||||
enquanto carregamentos completos normais ainda capturam os mesmos descritores para o registro
|
||||
real dos comandos. Mantenha `registerFull(...)` para trabalho exclusivo de runtime.
|
||||
real de comandos. Mantenha `registerFull(...)` para trabalho somente de runtime.
|
||||
Se `registerFull(...)` registrar métodos RPC do Gateway, use um
|
||||
prefixo específico do Plugin. Namespaces administrativos do core (`config.*`,
|
||||
`exec.approvals.*`, `wizard.*`, `update.*`) permanecem reservados e sempre
|
||||
resolvem para `operator.admin`.
|
||||
`defineChannelPluginEntry` lida automaticamente com a divisão de modo de registro. Consulte
|
||||
`defineChannelPluginEntry` trata automaticamente a divisão de modo de registro. Veja
|
||||
[Pontos de entrada](/pt-BR/plugins/sdk-entrypoints#definechannelpluginentry) para todas as
|
||||
opções.
|
||||
|
||||
@ -494,13 +496,18 @@ devem usar `resolveInboundMentionDecision({ facts, policy })`.
|
||||
|
||||
O OpenClaw carrega isso em vez da entrada completa quando o canal está desabilitado
|
||||
ou não configurado. Isso evita puxar código pesado de runtime durante fluxos de setup.
|
||||
Consulte [Setup e Configuração](/pt-BR/plugins/sdk-setup#setup-entry) para detalhes.
|
||||
Veja [Setup e Configuração](/pt-BR/plugins/sdk-setup#setup-entry) para detalhes.
|
||||
|
||||
Canais empacotados do workspace que dividem exports seguras para setup em módulos
|
||||
auxiliares podem usar `defineBundledChannelSetupEntry(...)` de
|
||||
`openclaw/plugin-sdk/channel-entry-contract` quando também precisarem de um
|
||||
setter explícito de runtime em tempo de setup.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Trate mensagens de entrada">
|
||||
Seu Plugin precisa receber mensagens da plataforma e encaminhá-las ao
|
||||
OpenClaw. O padrão típico é um Webhook que verifica a requisição e
|
||||
Seu Plugin precisa receber mensagens da plataforma e encaminhá-las para o
|
||||
OpenClaw. O padrão típico é um Webhook que verifica a solicitação e
|
||||
a despacha por meio do handler de entrada do seu canal:
|
||||
|
||||
```typescript
|
||||
@ -534,7 +541,7 @@ devem usar `resolveInboundMentionDecision({ facts, policy })`.
|
||||
|
||||
<a id="step-6-test"></a>
|
||||
<Step title="Teste">
|
||||
Escreva testes colocados ao lado do código em `src/channel.test.ts`:
|
||||
Escreva testes colocados lado a lado em `src/channel.test.ts`:
|
||||
|
||||
```typescript src/channel.test.ts
|
||||
import { describe, it, expect } from "vitest";
|
||||
@ -572,7 +579,7 @@ Escreva testes colocados ao lado do código em `src/channel.test.ts`:
|
||||
pnpm test -- <bundled-plugin-root>/acme-chat/
|
||||
```
|
||||
|
||||
Para helpers de teste compartilhados, consulte [Testes](/pt-BR/plugins/sdk-testing).
|
||||
Para helpers de teste compartilhados, veja [Testes](/pt-BR/plugins/sdk-testing).
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
@ -581,12 +588,12 @@ Escreva testes colocados ao lado do código em `src/channel.test.ts`:
|
||||
|
||||
```
|
||||
<bundled-plugin-root>/acme-chat/
|
||||
├── package.json # metadados de openclaw.channel
|
||||
├── package.json # metadados openclaw.channel
|
||||
├── openclaw.plugin.json # Manifesto com schema de configuração
|
||||
├── index.ts # defineChannelPluginEntry
|
||||
├── setup-entry.ts # defineSetupPluginEntry
|
||||
├── api.ts # Exportações públicas (opcional)
|
||||
├── runtime-api.ts # Exportações internas de runtime (opcional)
|
||||
├── api.ts # Exports públicos (opcional)
|
||||
├── runtime-api.ts # Exports internos de runtime (opcional)
|
||||
└── src/
|
||||
├── channel.ts # ChannelPlugin via createChatChannelPlugin
|
||||
├── channel.test.ts # Testes
|
||||
@ -598,12 +605,12 @@ Escreva testes colocados ao lado do código em `src/channel.test.ts`:
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Opções de encadeamento" icon="git-branch" href="/pt-BR/plugins/sdk-entrypoints#registration-mode">
|
||||
Modos de resposta fixos, com escopo por conta ou personalizados
|
||||
Modos de resposta fixos, com escopo de conta ou personalizados
|
||||
</Card>
|
||||
<Card title="Integração com a ferramenta de mensagem" icon="puzzle" href="/pt-BR/plugins/architecture#channel-plugins-and-the-shared-message-tool">
|
||||
describeMessageTool e descoberta de ações
|
||||
</Card>
|
||||
<Card title="Resolução de destino" icon="crosshair" href="/pt-BR/plugins/architecture#channel-target-resolution">
|
||||
<Card title="Resolução de alvo" icon="crosshair" href="/pt-BR/plugins/architecture#channel-target-resolution">
|
||||
inferTargetChatType, looksLikeId, resolveTarget
|
||||
</Card>
|
||||
<Card title="Helpers de runtime" icon="settings" href="/pt-BR/plugins/sdk-runtime">
|
||||
@ -612,15 +619,15 @@ Escreva testes colocados ao lado do código em `src/channel.test.ts`:
|
||||
</CardGroup>
|
||||
|
||||
<Note>
|
||||
Algumas interfaces auxiliares empacotadas ainda existem para manutenção e
|
||||
compatibilidade de Plugins empacotados. Elas não são o padrão recomendado para novos Plugins de canal;
|
||||
prefira os subcaminhos genéricos de canal/setup/resposta/runtime da superfície
|
||||
comum do SDK, a menos que você esteja mantendo diretamente essa família de Plugins empacotados.
|
||||
Algumas superfícies auxiliares de Plugins empacotados ainda existem para manutenção de Plugins empacotados e
|
||||
compatibilidade. Elas não são o padrão recomendado para novos Plugins de canal;
|
||||
prefira os subcaminhos genéricos de canal/setup/resposta/runtime da superfície comum do SDK,
|
||||
a menos que você esteja mantendo diretamente essa família de Plugins empacotados.
|
||||
</Note>
|
||||
|
||||
## Próximos passos
|
||||
|
||||
- [Plugins de provedor](/pt-BR/plugins/sdk-provider-plugins) — se o seu Plugin também fornece modelos
|
||||
- [Visão geral do SDK](/pt-BR/plugins/sdk-overview) — referência completa de importação de subcaminhos
|
||||
- [Visão geral do SDK](/pt-BR/plugins/sdk-overview) — referência completa de imports por subcaminho
|
||||
- [Testes do SDK](/pt-BR/plugins/sdk-testing) — utilitários de teste e testes de contrato
|
||||
- [Manifesto de Plugin](/pt-BR/plugins/manifest) — schema completo do manifesto
|
||||
- [Manifesto do Plugin](/pt-BR/plugins/manifest) — schema completo do manifesto
|
||||
|
||||
@ -1,36 +1,36 @@
|
||||
---
|
||||
read_when:
|
||||
- Você precisa da assinatura de tipo exata de definePluginEntry ou defineChannelPluginEntry
|
||||
- Você quer entender o modo de registro (completo vs setup vs metadados de CLI)
|
||||
- Você está consultando as opções de ponto de entrada
|
||||
- Você precisa da assinatura de tipo exata de `definePluginEntry` ou `defineChannelPluginEntry`
|
||||
- Você quer entender o modo de registro (completo vs configuração vs metadados da CLI)
|
||||
- Você está procurando opções de ponto de entrada
|
||||
sidebarTitle: Entry Points
|
||||
summary: Referência para definePluginEntry, defineChannelPluginEntry e defineSetupPluginEntry
|
||||
title: Pontos de entrada de plugin
|
||||
summary: Referência para `definePluginEntry`, `defineChannelPluginEntry` e `defineSetupPluginEntry`
|
||||
title: Pontos de entrada do Plugin
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T12:49:09Z"
|
||||
generated_at: "2026-04-15T19:41:37Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 799dbfe71e681dd8ba929a7a631dfe745c3c5c69530126fea2f9c137b120f51f
|
||||
source_hash: aabca25bc9b8ff1b5bb4852bafe83640ffeba006ea6b6a8eff4e2c37a10f1fe4
|
||||
source_path: plugins/sdk-entrypoints.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Pontos de entrada de plugin
|
||||
# Pontos de entrada do Plugin
|
||||
|
||||
Todo plugin exporta um objeto de entrada padrão. O SDK fornece três helpers para
|
||||
Todo Plugin exporta um objeto de entrada padrão. O SDK fornece três helpers para
|
||||
criá-los.
|
||||
|
||||
<Tip>
|
||||
**Procurando um passo a passo?** Consulte [Plugins de canal](/plugins/sdk-channel-plugins)
|
||||
ou [Plugins de provedor](/plugins/sdk-provider-plugins) para guias passo a passo.
|
||||
**Procurando um passo a passo?** Veja [Plugins de canal](/pt-BR/plugins/sdk-channel-plugins)
|
||||
ou [Plugins de provedor](/pt-BR/plugins/sdk-provider-plugins) para guias passo a passo.
|
||||
</Tip>
|
||||
|
||||
## `definePluginEntry`
|
||||
|
||||
**Importação:** `openclaw/plugin-sdk/plugin-entry`
|
||||
|
||||
Para plugins de provedor, plugins de ferramenta, plugins de hook e tudo o que **não**
|
||||
for um canal de mensagens.
|
||||
Para plugins de provedor, plugins de ferramenta, plugins de hook e qualquer coisa que **não**
|
||||
seja um canal de mensagens.
|
||||
|
||||
```typescript
|
||||
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
|
||||
@ -56,22 +56,22 @@ export default definePluginEntry({
|
||||
| `name` | `string` | Sim | — |
|
||||
| `description` | `string` | Sim | — |
|
||||
| `kind` | `string` | Não | — |
|
||||
| `configSchema` | `OpenClawPluginConfigSchema \| () => OpenClawPluginConfigSchema` | Não | Schema de objeto vazio |
|
||||
| `configSchema` | `OpenClawPluginConfigSchema \| () => OpenClawPluginConfigSchema` | Não | Esquema de objeto vazio |
|
||||
| `register` | `(api: OpenClawPluginApi) => void` | Sim | — |
|
||||
|
||||
- `id` deve corresponder ao seu manifesto `openclaw.plugin.json`.
|
||||
- `kind` é para slots exclusivos: `"memory"` ou `"context-engine"`.
|
||||
- `configSchema` pode ser uma função para avaliação preguiçosa.
|
||||
- O OpenClaw resolve e memoiza esse schema no primeiro acesso, portanto builders de schema
|
||||
caros são executados apenas uma vez.
|
||||
- O OpenClaw resolve e memoriza esse esquema no primeiro acesso, então builders de esquema
|
||||
custosos são executados apenas uma vez.
|
||||
|
||||
## `defineChannelPluginEntry`
|
||||
|
||||
**Importação:** `openclaw/plugin-sdk/channel-core`
|
||||
|
||||
Encapsula `definePluginEntry` com a infraestrutura específica de canal. Chama automaticamente
|
||||
`api.registerChannel({ plugin })`, expõe uma seam opcional de metadados de CLI para ajuda na raiz
|
||||
e controla `registerFull` de acordo com o modo de registro.
|
||||
Encapsula `definePluginEntry` com a integração específica de canal. Chama
|
||||
automaticamente `api.registerChannel({ plugin })`, expõe uma costura opcional de metadados
|
||||
da CLI de ajuda raiz e controla `registerFull` com base no modo de registro.
|
||||
|
||||
```typescript
|
||||
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
|
||||
@ -97,29 +97,29 @@ export default defineChannelPluginEntry({
|
||||
| `name` | `string` | Sim | — |
|
||||
| `description` | `string` | Sim | — |
|
||||
| `plugin` | `ChannelPlugin` | Sim | — |
|
||||
| `configSchema` | `OpenClawPluginConfigSchema \| () => OpenClawPluginConfigSchema` | Não | Schema de objeto vazio |
|
||||
| `configSchema` | `OpenClawPluginConfigSchema \| () => OpenClawPluginConfigSchema` | Não | Esquema de objeto vazio |
|
||||
| `setRuntime` | `(runtime: PluginRuntime) => void` | Não | — |
|
||||
| `registerCliMetadata` | `(api: OpenClawPluginApi) => void` | Não | — |
|
||||
| `registerFull` | `(api: OpenClawPluginApi) => void` | Não | — |
|
||||
|
||||
- `setRuntime` é chamado durante o registro para que você possa armazenar a referência de runtime
|
||||
(normalmente por meio de `createPluginRuntimeStore`). Ele é ignorado durante a captura
|
||||
de metadados de CLI.
|
||||
(normalmente via `createPluginRuntimeStore`). Ele é ignorado durante a captura
|
||||
de metadados da CLI.
|
||||
- `registerCliMetadata` é executado tanto durante `api.registrationMode === "cli-metadata"`
|
||||
quanto durante `api.registrationMode === "full"`.
|
||||
Use-o como o local canônico para descritores de CLI pertencentes ao canal, para que a ajuda
|
||||
na raiz permaneça sem ativação, enquanto o registro normal de comandos da CLI continua compatível
|
||||
com carregamentos completos de plugin.
|
||||
- `registerFull` é executado apenas quando `api.registrationMode === "full"`. Ele é ignorado
|
||||
durante o carregamento somente de setup.
|
||||
- Assim como `definePluginEntry`, `configSchema` pode ser uma factory preguiçosa e o OpenClaw
|
||||
memoiza o schema resolvido no primeiro acesso.
|
||||
- Para comandos de CLI na raiz pertencentes ao plugin, prefira `api.registerCli(..., { descriptors: [...] })`
|
||||
quando quiser que o comando permaneça com lazy-loading sem desaparecer da árvore de parsing
|
||||
da CLI na raiz. Para plugins de canal, prefira registrar esses descritores
|
||||
em `registerCliMetadata(...)` e manter `registerFull(...)` focado em trabalho somente de runtime.
|
||||
- Se `registerFull(...)` também registrar métodos RPC de gateway, mantenha-os em um
|
||||
prefixo específico do plugin. Namespaces administrativos principais reservados (`config.*`,
|
||||
Use-o como o lugar canônico para descritores de CLI pertencentes ao canal, para que a ajuda
|
||||
raiz não ative o carregamento enquanto o registro normal de comandos da CLI continua compatível
|
||||
com carregamentos completos do Plugin.
|
||||
- `registerFull` só é executado quando `api.registrationMode === "full"`. Ele é ignorado
|
||||
durante o carregamento somente de configuração.
|
||||
- Assim como `definePluginEntry`, `configSchema` pode ser uma fábrica preguiçosa e o OpenClaw
|
||||
memoriza o esquema resolvido no primeiro acesso.
|
||||
- Para comandos raiz da CLI pertencentes ao Plugin, prefira `api.registerCli(..., { descriptors: [...] })`
|
||||
quando você quiser que o comando permaneça com carregamento preguiçoso sem desaparecer da
|
||||
árvore de parsing da CLI raiz. Para plugins de canal, prefira registrar esses descritores
|
||||
em `registerCliMetadata(...)` e mantenha `registerFull(...)` focado em trabalho somente de runtime.
|
||||
- Se `registerFull(...)` também registrar métodos RPC do Gateway, mantenha-os em um
|
||||
prefixo específico do Plugin. Namespaces administrativos centrais reservados (`config.*`,
|
||||
`exec.approvals.*`, `wizard.*`, `update.*`) são sempre forçados para
|
||||
`operator.admin`.
|
||||
|
||||
@ -128,7 +128,7 @@ export default defineChannelPluginEntry({
|
||||
**Importação:** `openclaw/plugin-sdk/channel-core`
|
||||
|
||||
Para o arquivo leve `setup-entry.ts`. Retorna apenas `{ plugin }`, sem
|
||||
infraestrutura de runtime ou de CLI.
|
||||
integração de runtime nem de CLI.
|
||||
|
||||
```typescript
|
||||
import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";
|
||||
@ -136,33 +136,58 @@ import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";
|
||||
export default defineSetupPluginEntry(myChannelPlugin);
|
||||
```
|
||||
|
||||
O OpenClaw carrega isso em vez da entrada completa quando um canal está desativado,
|
||||
não configurado ou quando o carregamento adiado está ativado. Consulte
|
||||
[Setup e config](/plugins/sdk-setup#setup-entry) para saber quando isso importa.
|
||||
O OpenClaw carrega isso em vez da entrada completa quando um canal está desabilitado,
|
||||
não configurado ou quando o carregamento adiado está ativado. Veja
|
||||
[Configuração e setup](/pt-BR/plugins/sdk-setup#setup-entry) para saber quando isso importa.
|
||||
|
||||
Na prática, combine `defineSetupPluginEntry(...)` com as famílias restritas de helpers de setup:
|
||||
Na prática, combine `defineSetupPluginEntry(...)` com as famílias estreitas de helpers de setup:
|
||||
|
||||
- `openclaw/plugin-sdk/setup-runtime` para helpers de setup seguros para runtime, como
|
||||
adaptadores de patch de setup seguros para importação, saída de nota de consulta,
|
||||
`promptResolvedAllowFrom`, `splitSetupEntries` e proxies de setup delegados
|
||||
- `openclaw/plugin-sdk/channel-setup` para superfícies de setup de instalação opcional
|
||||
- `openclaw/plugin-sdk/setup-tools` para helpers de CLI/arquivo/docs de setup/instalação
|
||||
- `openclaw/plugin-sdk/setup-tools` para helpers de setup/instalação de CLI/arquivo/docs
|
||||
|
||||
Mantenha SDKs pesados, registro de CLI e serviços de runtime de longa duração na
|
||||
entrada completa.
|
||||
|
||||
Canais empacotados do workspace que dividem superfícies de setup e runtime podem usar
|
||||
`defineBundledChannelSetupEntry(...)` de
|
||||
`openclaw/plugin-sdk/channel-entry-contract` em vez disso. Esse contrato permite que a
|
||||
entrada de setup mantenha exportações de plugin/secrets seguras para setup enquanto ainda expõe
|
||||
um setter de runtime:
|
||||
|
||||
```typescript
|
||||
import { defineBundledChannelSetupEntry } from "openclaw/plugin-sdk/channel-entry-contract";
|
||||
|
||||
export default defineBundledChannelSetupEntry({
|
||||
importMetaUrl: import.meta.url,
|
||||
plugin: {
|
||||
specifier: "./channel-plugin-api.js",
|
||||
exportName: "myChannelPlugin",
|
||||
},
|
||||
runtime: {
|
||||
specifier: "./runtime-api.js",
|
||||
exportName: "setMyChannelRuntime",
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
Use esse contrato empacotado apenas quando os fluxos de setup realmente precisarem de um setter
|
||||
de runtime leve antes que a entrada completa do canal seja carregada.
|
||||
|
||||
## Modo de registro
|
||||
|
||||
`api.registrationMode` informa ao seu plugin como ele foi carregado:
|
||||
`api.registrationMode` informa ao seu Plugin como ele foi carregado:
|
||||
|
||||
| Modo | Quando | O que registrar |
|
||||
| ----------------- | -------------------------------- | ---------------------------------------------------------------------------------------- |
|
||||
| `"full"` | Inicialização normal do gateway | Tudo |
|
||||
| `"setup-only"` | Canal desativado/não configurado | Apenas registro de canal |
|
||||
| `"setup-runtime"` | Fluxo de setup com runtime disponível | Registro de canal mais apenas o runtime leve necessário antes de a entrada completa carregar |
|
||||
| `"cli-metadata"` | Ajuda na raiz / captura de metadados de CLI | Apenas descritores de CLI |
|
||||
| Modo | Quando | O que registrar |
|
||||
| ----------------- | --------------------------------- | --------------------------------------------------------------------------------------- |
|
||||
| `"full"` | Inicialização normal do Gateway | Tudo |
|
||||
| `"setup-only"` | Canal desabilitado/não configurado | Apenas registro de canal |
|
||||
| `"setup-runtime"` | Fluxo de setup com runtime disponível | Registro de canal mais apenas o runtime leve necessário antes do carregamento da entrada completa |
|
||||
| `"cli-metadata"` | Ajuda raiz / captura de metadados da CLI | Apenas descritores de CLI |
|
||||
|
||||
`defineChannelPluginEntry` lida automaticamente com essa divisão. Se você usar
|
||||
`defineChannelPluginEntry` lida com essa divisão automaticamente. Se você usar
|
||||
`definePluginEntry` diretamente para um canal, verifique o modo por conta própria:
|
||||
|
||||
```typescript
|
||||
@ -181,36 +206,36 @@ register(api) {
|
||||
```
|
||||
|
||||
Trate `"setup-runtime"` como a janela em que superfícies de inicialização somente de setup devem
|
||||
existir sem reentrar no runtime completo do canal empacotado. Bons encaixes são
|
||||
registro de canal, rotas HTTP seguras para setup, métodos de gateway seguros para setup e
|
||||
existir sem reentrar no runtime completo do canal empacotado. Bons usos incluem
|
||||
registro de canal, rotas HTTP seguras para setup, métodos do Gateway seguros para setup e
|
||||
helpers de setup delegados. Serviços pesados em segundo plano, registradores de CLI e
|
||||
bootstraps de SDK de provedor/cliente ainda pertencem a `"full"`.
|
||||
bootstraps de SDKs de provedor/cliente ainda pertencem a `"full"`.
|
||||
|
||||
Especificamente para registradores de CLI:
|
||||
|
||||
- use `descriptors` quando o registrador possuir um ou mais comandos na raiz e você
|
||||
quiser que o OpenClaw faça lazy-load do módulo real da CLI na primeira invocação
|
||||
- garanta que esses descritores cubram todos os comandos de nível superior expostos pelo
|
||||
- use `descriptors` quando o registrador possuir um ou mais comandos raiz e você
|
||||
quiser que o OpenClaw carregue o módulo real da CLI de forma preguiçosa na primeira invocação
|
||||
- certifique-se de que esses descritores cubram todos os comandos raiz de nível superior expostos pelo
|
||||
registrador
|
||||
- use apenas `commands` para caminhos de compatibilidade eager
|
||||
- use apenas `commands` somente para caminhos de compatibilidade ansiosos
|
||||
|
||||
## Formatos de plugin
|
||||
## Formatos de Plugin
|
||||
|
||||
O OpenClaw classifica plugins carregados de acordo com seu comportamento de registro:
|
||||
O OpenClaw classifica Plugins carregados pelo comportamento de registro deles:
|
||||
|
||||
| Formato | Descrição |
|
||||
| --------------------- | ------------------------------------------------- |
|
||||
| **plain-capability** | Um tipo de capacidade (por exemplo, apenas provedor) |
|
||||
| Formato | Descrição |
|
||||
| -------------------- | ------------------------------------------------- |
|
||||
| **plain-capability** | Um tipo de capacidade (por exemplo, somente provedor) |
|
||||
| **hybrid-capability** | Vários tipos de capacidade (por exemplo, provedor + fala) |
|
||||
| **hook-only** | Apenas hooks, sem capacidades |
|
||||
| **hook-only** | Apenas hooks, sem capacidades |
|
||||
| **non-capability** | Ferramentas/comandos/serviços, mas sem capacidades |
|
||||
|
||||
Use `openclaw plugins inspect <id>` para ver o formato de um plugin.
|
||||
Use `openclaw plugins inspect <id>` para ver o formato de um Plugin.
|
||||
|
||||
## Relacionado
|
||||
|
||||
- [Visão geral do SDK](/plugins/sdk-overview) — API de registro e referência de subcaminhos
|
||||
- [Helpers de runtime](/plugins/sdk-runtime) — `api.runtime` e `createPluginRuntimeStore`
|
||||
- [Setup e config](/plugins/sdk-setup) — manifesto, entrada de setup, carregamento adiado
|
||||
- [Plugins de canal](/plugins/sdk-channel-plugins) — como criar o objeto `ChannelPlugin`
|
||||
- [Plugins de provedor](/plugins/sdk-provider-plugins) — registro de provedor e hooks
|
||||
- [Visão geral do SDK](/pt-BR/plugins/sdk-overview) — API de registro e referência de subpaths
|
||||
- [Helpers de runtime](/pt-BR/plugins/sdk-runtime) — `api.runtime` e `createPluginRuntimeStore`
|
||||
- [Setup e configuração](/pt-BR/plugins/sdk-setup) — manifesto, entrada de setup, carregamento adiado
|
||||
- [Plugins de canal](/pt-BR/plugins/sdk-channel-plugins) — criando o objeto `ChannelPlugin`
|
||||
- [Plugins de provedor](/pt-BR/plugins/sdk-provider-plugins) — registro de provedor e hooks
|
||||
|
||||
@ -1,28 +1,28 @@
|
||||
---
|
||||
read_when:
|
||||
- Você precisa chamar auxiliares do núcleo a partir de um plugin (TTS, STT, geração de imagem, busca na web, subagent)
|
||||
- Você precisa chamar auxiliares do núcleo a partir de um plugin (TTS, STT, geração de imagem, busca na web, subagente)
|
||||
- Você quer entender o que `api.runtime` expõe
|
||||
- Você está acessando auxiliares de configuração, agente ou mídia a partir do código do plugin
|
||||
- Você está acessando auxiliares de config, agente ou mídia a partir do código do plugin
|
||||
sidebarTitle: Runtime Helpers
|
||||
summary: api.runtime -- os auxiliares de runtime injetados disponíveis para plugins
|
||||
title: Auxiliares de runtime de plugin
|
||||
summary: api.runtime -- os auxiliares de tempo de execução injetados disponíveis para plugins
|
||||
title: Auxiliares de tempo de execução do Plugin
|
||||
x-i18n:
|
||||
generated_at: "2026-04-11T02:46:37Z"
|
||||
generated_at: "2026-04-15T19:41:36Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: fbf8a6ecd970300f784b8aca20eed40ba12c83107abd27385bfdc3347d2544be
|
||||
source_hash: c77a6e9cd48c84affa17dce684bbd0e072c8b63485e4a5d569f3793a4ea4f9c8
|
||||
source_path: plugins/sdk-runtime.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Auxiliares de runtime de plugin
|
||||
# Auxiliares de tempo de execução do Plugin
|
||||
|
||||
Referência para o objeto `api.runtime` injetado em todo plugin durante o
|
||||
registro. Use estes auxiliares em vez de importar diretamente internos do host.
|
||||
registro. Use esses auxiliares em vez de importar diretamente internos do host.
|
||||
|
||||
<Tip>
|
||||
**Está procurando um guia passo a passo?** Consulte [Channel Plugins](/pt-BR/plugins/sdk-channel-plugins)
|
||||
ou [Provider Plugins](/pt-BR/plugins/sdk-provider-plugins) para guias passo a passo
|
||||
**Está procurando um passo a passo?** Consulte [Plugins de canal](/pt-BR/plugins/sdk-channel-plugins)
|
||||
ou [Plugins de provedor](/pt-BR/plugins/sdk-provider-plugins) para guias passo a passo
|
||||
que mostram esses auxiliares em contexto.
|
||||
</Tip>
|
||||
|
||||
@ -32,50 +32,51 @@ register(api) {
|
||||
}
|
||||
```
|
||||
|
||||
## Namespaces de runtime
|
||||
## Namespaces de tempo de execução
|
||||
|
||||
### `api.runtime.agent`
|
||||
|
||||
Identidade do agente, diretórios e gerenciamento de sessão.
|
||||
|
||||
```typescript
|
||||
// Resolver o diretório de trabalho do agente
|
||||
// Resolve the agent's working directory
|
||||
const agentDir = api.runtime.agent.resolveAgentDir(cfg);
|
||||
|
||||
// Resolver o workspace do agente
|
||||
// Resolve agent workspace
|
||||
const workspaceDir = api.runtime.agent.resolveAgentWorkspaceDir(cfg);
|
||||
|
||||
// Obter a identidade do agente
|
||||
// Get agent identity
|
||||
const identity = api.runtime.agent.resolveAgentIdentity(cfg);
|
||||
|
||||
// Obter o nível de thinking padrão
|
||||
// Get default thinking level
|
||||
const thinking = api.runtime.agent.resolveThinkingDefault(cfg, provider, model);
|
||||
|
||||
// Obter o tempo limite do agente
|
||||
// Get agent timeout
|
||||
const timeoutMs = api.runtime.agent.resolveAgentTimeoutMs(cfg);
|
||||
|
||||
// Garantir que o workspace exista
|
||||
// Ensure workspace exists
|
||||
await api.runtime.agent.ensureAgentWorkspace(cfg);
|
||||
|
||||
// Executar um turno de agente embutido
|
||||
// Run an embedded agent turn
|
||||
const agentDir = api.runtime.agent.resolveAgentDir(cfg);
|
||||
const result = await api.runtime.agent.runEmbeddedAgent({
|
||||
sessionId: "my-plugin:task-1",
|
||||
runId: crypto.randomUUID(),
|
||||
sessionFile: path.join(agentDir, "sessions", "my-plugin-task-1.jsonl"),
|
||||
workspaceDir: api.runtime.agent.resolveAgentWorkspaceDir(cfg),
|
||||
prompt: "Resuma as alterações mais recentes",
|
||||
prompt: "Summarize the latest changes",
|
||||
timeoutMs: api.runtime.agent.resolveAgentTimeoutMs(cfg),
|
||||
});
|
||||
```
|
||||
|
||||
`runEmbeddedAgent(...)` é o auxiliar neutro para iniciar um turno normal de
|
||||
agente OpenClaw a partir do código do plugin. Ele usa a mesma resolução de
|
||||
provedor/modelo e a mesma seleção de harness de agente que respostas acionadas por canal.
|
||||
agente do OpenClaw a partir do código do plugin. Ele usa a mesma resolução de
|
||||
provedor/modelo e a mesma seleção de harness de agente que as respostas
|
||||
acionadas por canais.
|
||||
|
||||
`runEmbeddedPiAgent(...)` continua disponível como alias de compatibilidade.
|
||||
`runEmbeddedPiAgent(...)` permanece como um alias de compatibilidade.
|
||||
|
||||
**Os auxiliares do armazenamento de sessão** ficam em `api.runtime.agent.session`:
|
||||
**Os auxiliares de armazenamento de sessão** ficam em `api.runtime.agent.session`:
|
||||
|
||||
```typescript
|
||||
const storePath = api.runtime.agent.session.resolveStorePath(cfg);
|
||||
@ -89,63 +90,65 @@ const filePath = api.runtime.agent.session.resolveSessionFilePath(cfg, sessionId
|
||||
Constantes padrão de modelo e provedor:
|
||||
|
||||
```typescript
|
||||
const model = api.runtime.agent.defaults.model; // por exemplo "anthropic/claude-sonnet-4-6"
|
||||
const provider = api.runtime.agent.defaults.provider; // por exemplo "anthropic"
|
||||
const model = api.runtime.agent.defaults.model; // e.g. "anthropic/claude-sonnet-4-6"
|
||||
const provider = api.runtime.agent.defaults.provider; // e.g. "anthropic"
|
||||
```
|
||||
|
||||
### `api.runtime.subagent`
|
||||
|
||||
Inicie e gerencie execuções de subagent em segundo plano.
|
||||
Inicie e gerencie execuções de subagente em segundo plano.
|
||||
|
||||
```typescript
|
||||
// Iniciar uma execução de subagent
|
||||
// Start a subagent run
|
||||
const { runId } = await api.runtime.subagent.run({
|
||||
sessionKey: "agent:main:subagent:search-helper",
|
||||
message: "Expanda esta consulta em buscas de acompanhamento mais focadas.",
|
||||
provider: "openai", // substituição opcional
|
||||
model: "gpt-4.1-mini", // substituição opcional
|
||||
message: "Expand this query into focused follow-up searches.",
|
||||
provider: "openai", // optional override
|
||||
model: "gpt-4.1-mini", // optional override
|
||||
deliver: false,
|
||||
});
|
||||
|
||||
// Aguardar a conclusão
|
||||
// Wait for completion
|
||||
const result = await api.runtime.subagent.waitForRun({ runId, timeoutMs: 30000 });
|
||||
|
||||
// Ler mensagens da sessão
|
||||
// Read session messages
|
||||
const { messages } = await api.runtime.subagent.getSessionMessages({
|
||||
sessionKey: "agent:main:subagent:search-helper",
|
||||
limit: 10,
|
||||
});
|
||||
|
||||
// Excluir uma sessão
|
||||
// Delete a session
|
||||
await api.runtime.subagent.deleteSession({
|
||||
sessionKey: "agent:main:subagent:search-helper",
|
||||
});
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Substituições de modelo (`provider`/`model`) exigem ativação pelo operador via
|
||||
`plugins.entries.<id>.subagent.allowModelOverride: true` na configuração.
|
||||
Plugins não confiáveis ainda podem executar subagentes, mas solicitações de substituição são rejeitadas.
|
||||
Substituições de modelo (`provider`/`model`) exigem opt-in do operador via
|
||||
`plugins.entries.<id>.subagent.allowModelOverride: true` na config.
|
||||
Plugins não confiáveis ainda podem executar subagentes, mas solicitações de
|
||||
substituição são rejeitadas.
|
||||
</Warning>
|
||||
|
||||
### `api.runtime.taskFlow`
|
||||
|
||||
Vincule um runtime de Task Flow a uma chave de sessão OpenClaw existente ou a um
|
||||
contexto de ferramenta confiável e, em seguida, crie e gerencie Task Flows sem passar um proprietário em cada chamada.
|
||||
Vincule um tempo de execução do TaskFlow a uma chave de sessão OpenClaw existente ou a um
|
||||
contexto de ferramenta confiável, e então crie e gerencie TaskFlows sem passar um owner em
|
||||
cada chamada.
|
||||
|
||||
```typescript
|
||||
const taskFlow = api.runtime.taskFlow.fromToolContext(ctx);
|
||||
|
||||
const created = taskFlow.createManaged({
|
||||
controllerId: "my-plugin/review-batch",
|
||||
goal: "Revisar novos pull requests",
|
||||
goal: "Review new pull requests",
|
||||
});
|
||||
|
||||
const child = taskFlow.runTask({
|
||||
flowId: created.flowId,
|
||||
runtime: "acp",
|
||||
childSessionKey: "agent:main:subagent:reviewer",
|
||||
task: "Revisar PR #123",
|
||||
task: "Review PR #123",
|
||||
status: "running",
|
||||
startedAt: Date.now(),
|
||||
});
|
||||
@ -159,27 +162,27 @@ const waiting = taskFlow.setWaiting({
|
||||
```
|
||||
|
||||
Use `bindSession({ sessionKey, requesterOrigin })` quando você já tiver uma
|
||||
chave de sessão OpenClaw confiável da sua própria camada de vínculo. Não vincule a partir de entrada bruta do
|
||||
usuário.
|
||||
chave de sessão OpenClaw confiável da sua própria camada de vinculação. Não faça vinculação a partir de
|
||||
entrada bruta do usuário.
|
||||
|
||||
### `api.runtime.tts`
|
||||
|
||||
Síntese de texto para fala.
|
||||
|
||||
```typescript
|
||||
// TTS padrão
|
||||
// Standard TTS
|
||||
const clip = await api.runtime.tts.textToSpeech({
|
||||
text: "Olá do OpenClaw",
|
||||
text: "Hello from OpenClaw",
|
||||
cfg: api.config,
|
||||
});
|
||||
|
||||
// TTS otimizado para telefonia
|
||||
// Telephony-optimized TTS
|
||||
const telephonyClip = await api.runtime.tts.textToSpeechTelephony({
|
||||
text: "Olá do OpenClaw",
|
||||
text: "Hello from OpenClaw",
|
||||
cfg: api.config,
|
||||
});
|
||||
|
||||
// Listar vozes disponíveis
|
||||
// List available voices
|
||||
const voices = await api.runtime.tts.listVoices({
|
||||
provider: "elevenlabs",
|
||||
cfg: api.config,
|
||||
@ -194,27 +197,27 @@ de áudio PCM + taxa de amostragem.
|
||||
Análise de imagem, áudio e vídeo.
|
||||
|
||||
```typescript
|
||||
// Descrever uma imagem
|
||||
// Describe an image
|
||||
const image = await api.runtime.mediaUnderstanding.describeImageFile({
|
||||
filePath: "/tmp/inbound-photo.jpg",
|
||||
cfg: api.config,
|
||||
agentDir: "/tmp/agent",
|
||||
});
|
||||
|
||||
// Transcrever áudio
|
||||
// Transcribe audio
|
||||
const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({
|
||||
filePath: "/tmp/inbound-audio.ogg",
|
||||
cfg: api.config,
|
||||
mime: "audio/ogg", // opcional, para quando o MIME não puder ser inferido
|
||||
mime: "audio/ogg", // optional, for when MIME cannot be inferred
|
||||
});
|
||||
|
||||
// Descrever um vídeo
|
||||
// Describe a video
|
||||
const video = await api.runtime.mediaUnderstanding.describeVideoFile({
|
||||
filePath: "/tmp/inbound-video.mp4",
|
||||
cfg: api.config,
|
||||
});
|
||||
|
||||
// Análise genérica de arquivo
|
||||
// Generic file analysis
|
||||
const result = await api.runtime.mediaUnderstanding.runFile({
|
||||
filePath: "/tmp/inbound-file.pdf",
|
||||
cfg: api.config,
|
||||
@ -224,7 +227,7 @@ const result = await api.runtime.mediaUnderstanding.runFile({
|
||||
Retorna `{ text: undefined }` quando nenhuma saída é produzida (por exemplo, entrada ignorada).
|
||||
|
||||
<Info>
|
||||
`api.runtime.stt.transcribeAudioFile(...)` continua disponível como alias de compatibilidade
|
||||
`api.runtime.stt.transcribeAudioFile(...)` permanece como um alias de compatibilidade
|
||||
para `api.runtime.mediaUnderstanding.transcribeAudioFile(...)`.
|
||||
</Info>
|
||||
|
||||
@ -234,7 +237,7 @@ Geração de imagem.
|
||||
|
||||
```typescript
|
||||
const result = await api.runtime.imageGeneration.generate({
|
||||
prompt: "Um robô pintando um pôr do sol",
|
||||
prompt: "A robot painting a sunset",
|
||||
cfg: api.config,
|
||||
});
|
||||
|
||||
@ -250,7 +253,7 @@ const providers = api.runtime.webSearch.listProviders({ config: api.config });
|
||||
|
||||
const result = await api.runtime.webSearch.search({
|
||||
config: api.config,
|
||||
args: { query: "SDK de plugins do OpenClaw", count: 5 },
|
||||
args: { query: "OpenClaw plugin SDK", count: 5 },
|
||||
});
|
||||
```
|
||||
|
||||
@ -269,7 +272,7 @@ const resized = await api.runtime.media.resizeToJpeg(buffer, { maxWidth: 800 });
|
||||
|
||||
### `api.runtime.config`
|
||||
|
||||
Carregamento e gravação de configuração.
|
||||
Carregamento e escrita de config.
|
||||
|
||||
```typescript
|
||||
const cfg = await api.runtime.config.loadConfig();
|
||||
@ -278,7 +281,7 @@ await api.runtime.config.writeConfigFile(cfg);
|
||||
|
||||
### `api.runtime.system`
|
||||
|
||||
Utilitários em nível de sistema.
|
||||
Utilitários de nível de sistema.
|
||||
|
||||
```typescript
|
||||
await api.runtime.system.enqueueSystemEvent(event);
|
||||
@ -302,7 +305,7 @@ api.runtime.events.onSessionTranscriptUpdate((update) => {
|
||||
|
||||
### `api.runtime.logging`
|
||||
|
||||
Logs.
|
||||
Logging.
|
||||
|
||||
```typescript
|
||||
const verbose = api.runtime.logging.shouldLogVerbose();
|
||||
@ -331,7 +334,7 @@ const stateDir = api.runtime.state.resolveStateDir();
|
||||
|
||||
### `api.runtime.tools`
|
||||
|
||||
Fábricas de ferramentas de memória e CLI.
|
||||
Factories de ferramenta de memória e CLI.
|
||||
|
||||
```typescript
|
||||
const getTool = api.runtime.tools.createMemoryGetTool(/* ... */);
|
||||
@ -341,10 +344,10 @@ api.runtime.tools.registerMemoryCli(/* ... */);
|
||||
|
||||
### `api.runtime.channel`
|
||||
|
||||
Auxiliares de runtime específicos de canal (disponíveis quando um plugin de canal é carregado).
|
||||
Auxiliares de tempo de execução específicos do canal (disponíveis quando um Plugin de canal é carregado).
|
||||
|
||||
`api.runtime.channel.mentions` é a superfície compartilhada de política de menções de entrada para
|
||||
plugins de canal incluídos que usam injeção de runtime:
|
||||
`api.runtime.channel.mentions` é a superfície compartilhada de política de menção de entrada para
|
||||
Plugins de canal empacotados que usam injeção de tempo de execução:
|
||||
|
||||
```typescript
|
||||
const mentionMatch = api.runtime.channel.mentions.matchesMentionWithExplicit(text, {
|
||||
@ -379,56 +382,62 @@ Auxiliares de menção disponíveis:
|
||||
- `implicitMentionKindWhen`
|
||||
- `resolveInboundMentionDecision`
|
||||
|
||||
`api.runtime.channel.mentions` intencionalmente não expõe os auxiliares legados de compatibilidade
|
||||
`resolveMentionGating*`. Prefira o caminho normalizado
|
||||
`api.runtime.channel.mentions` intencionalmente não expõe os auxiliares de compatibilidade
|
||||
antigos `resolveMentionGating*`. Prefira o caminho normalizado
|
||||
`{ facts, policy }`.
|
||||
|
||||
## Armazenando referências de runtime
|
||||
## Armazenando referências de tempo de execução
|
||||
|
||||
Use `createPluginRuntimeStore` para armazenar a referência de runtime para uso fora
|
||||
Use `createPluginRuntimeStore` para armazenar a referência de tempo de execução para uso fora
|
||||
do callback `register`:
|
||||
|
||||
```typescript
|
||||
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
|
||||
import type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store";
|
||||
|
||||
const store = createPluginRuntimeStore<PluginRuntime>("runtime de my-plugin não inicializado");
|
||||
const store = createPluginRuntimeStore<PluginRuntime>({
|
||||
pluginId: "my-plugin",
|
||||
errorMessage: "my-plugin runtime not initialized",
|
||||
});
|
||||
|
||||
// No seu ponto de entrada
|
||||
// In your entry point
|
||||
export default defineChannelPluginEntry({
|
||||
id: "my-plugin",
|
||||
name: "My Plugin",
|
||||
description: "Exemplo",
|
||||
description: "Example",
|
||||
plugin: myPlugin,
|
||||
setRuntime: store.setRuntime,
|
||||
});
|
||||
|
||||
// Em outros arquivos
|
||||
// In other files
|
||||
export function getRuntime() {
|
||||
return store.getRuntime(); // lança erro se não estiver inicializado
|
||||
return store.getRuntime(); // throws if not initialized
|
||||
}
|
||||
|
||||
export function tryGetRuntime() {
|
||||
return store.tryGetRuntime(); // retorna null se não estiver inicializado
|
||||
return store.tryGetRuntime(); // returns null if not initialized
|
||||
}
|
||||
```
|
||||
|
||||
Prefira `pluginId` para a identidade do runtime-store. A forma de nível mais baixo `key` é
|
||||
para casos incomuns em que um plugin intencionalmente precisa de mais de um slot de tempo de execução.
|
||||
|
||||
## Outros campos de nível superior de `api`
|
||||
|
||||
Além de `api.runtime`, o objeto API também fornece:
|
||||
|
||||
| Campo | Tipo | Descrição |
|
||||
| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- |
|
||||
| `api.id` | `string` | ID do plugin |
|
||||
| `api.name` | `string` | Nome de exibição do plugin |
|
||||
| `api.config` | `OpenClawConfig` | Snapshot atual da configuração (snapshot ativo em memória do runtime quando disponível) |
|
||||
| `api.pluginConfig` | `Record<string, unknown>` | Configuração específica do plugin em `plugins.entries.<id>.config` |
|
||||
| `api.id` | `string` | ID do Plugin |
|
||||
| `api.name` | `string` | Nome de exibição do Plugin |
|
||||
| `api.config` | `OpenClawConfig` | Snapshot atual da config (snapshot ativo em memória do tempo de execução quando disponível) |
|
||||
| `api.pluginConfig` | `Record<string, unknown>` | Config específica do Plugin em `plugins.entries.<id>.config` |
|
||||
| `api.logger` | `PluginLogger` | Logger com escopo (`debug`, `info`, `warn`, `error`) |
|
||||
| `api.registrationMode` | `PluginRegistrationMode` | Modo de carregamento atual; `"setup-runtime"` é a janela leve de inicialização/configuração antes da entrada completa |
|
||||
| `api.resolvePath(input)` | `(string) => string` | Resolve um caminho relativo à raiz do plugin |
|
||||
| `api.resolvePath(input)` | `(string) => string` | Resolve um caminho relativo à raiz do Plugin |
|
||||
|
||||
## Relacionado
|
||||
|
||||
- [SDK Overview](/pt-BR/plugins/sdk-overview) -- referência de subcaminhos
|
||||
- [SDK Entry Points](/pt-BR/plugins/sdk-entrypoints) -- opções de `definePluginEntry`
|
||||
- [Plugin Internals](/pt-BR/plugins/architecture) -- modelo de capacidades e registro
|
||||
- [Visão geral do SDK](/pt-BR/plugins/sdk-overview) -- referência de subpath
|
||||
- [Pontos de entrada do SDK](/pt-BR/plugins/sdk-entrypoints) -- opções de `definePluginEntry`
|
||||
- [Internos do Plugin](/pt-BR/plugins/architecture) -- modelo de capacidades e registro
|
||||
|
||||
@ -1,35 +1,35 @@
|
||||
---
|
||||
read_when:
|
||||
- Você está adicionando um assistente de setup a um plugin
|
||||
- Você precisa entender setup-entry.ts versus index.ts
|
||||
- Você está definindo schemas de configuração de plugin ou metadados openclaw no package.json
|
||||
- Você está adicionando um assistente de configuração a um Plugin
|
||||
- Você precisa entender `setup-entry.ts` versus `index.ts`
|
||||
- Você está definindo esquemas de config do Plugin ou metadados `openclaw` no `package.json`
|
||||
sidebarTitle: Setup and Config
|
||||
summary: Assistentes de setup, setup-entry.ts, schemas de configuração e metadados do package.json
|
||||
title: Setup e configuração de plugins
|
||||
summary: Assistentes de configuração, setup-entry.ts, esquemas de configuração e metadados do package.json
|
||||
title: Configuração e Config do Plugin
|
||||
x-i18n:
|
||||
generated_at: "2026-04-06T03:10:35Z"
|
||||
generated_at: "2026-04-15T19:41:37Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: eac2586516d27bcd94cc4c259fe6274c792b3f9938c7ddd6dbf04a6dbb988dc9
|
||||
source_hash: ddf28e25e381a4a38ac478e531586f59612e1a278732597375f87c2eeefc521b
|
||||
source_path: plugins/sdk-setup.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Setup e configuração de plugins
|
||||
# Configuração e Config do Plugin
|
||||
|
||||
Referência para empacotamento de plugin (metadados de `package.json`), manifestos
|
||||
(`openclaw.plugin.json`), entradas de setup e schemas de configuração.
|
||||
Referência para empacotamento de Plugin (metadados do `package.json`), manifestos
|
||||
(`openclaw.plugin.json`), entradas de configuração e esquemas de config.
|
||||
|
||||
<Tip>
|
||||
**Está procurando um passo a passo?** Os guias práticos cobrem o empacotamento em contexto:
|
||||
[Channel Plugins](/pt-BR/plugins/sdk-channel-plugins#step-1-package-and-manifest) e
|
||||
[Provider Plugins](/pt-BR/plugins/sdk-provider-plugins#step-1-package-and-manifest).
|
||||
[Plugins de Canal](/pt-BR/plugins/sdk-channel-plugins#step-1-package-and-manifest) e
|
||||
[Plugins de Provedor](/pt-BR/plugins/sdk-provider-plugins#step-1-package-and-manifest).
|
||||
</Tip>
|
||||
|
||||
## Metadados do pacote
|
||||
|
||||
Seu `package.json` precisa de um campo `openclaw` que informe ao sistema de plugins o que
|
||||
seu plugin fornece:
|
||||
seu Plugin fornece:
|
||||
|
||||
**Plugin de canal:**
|
||||
|
||||
@ -50,7 +50,7 @@ seu plugin fornece:
|
||||
}
|
||||
```
|
||||
|
||||
**Plugin de provedor / baseline de publicação no ClawHub:**
|
||||
**Plugin de provedor / linha de base de publicação do ClawHub:**
|
||||
|
||||
```json openclaw-clawhub-package.json
|
||||
{
|
||||
@ -71,47 +71,47 @@ seu plugin fornece:
|
||||
}
|
||||
```
|
||||
|
||||
Se você publicar o plugin externamente no ClawHub, esses campos `compat` e `build`
|
||||
Se você publicar o Plugin externamente no ClawHub, esses campos `compat` e `build`
|
||||
serão obrigatórios. Os snippets canônicos de publicação ficam em
|
||||
`docs/snippets/plugin-publish/`.
|
||||
|
||||
### Campos `openclaw`
|
||||
|
||||
| Campo | Tipo | Descrição |
|
||||
| ------------ | ---------- | --------------------------------------------------------------------------------------------------------- |
|
||||
| `extensions` | `string[]` | Arquivos de ponto de entrada (relativos à raiz do pacote) |
|
||||
| `setupEntry` | `string` | Entrada leve apenas para setup (opcional) |
|
||||
| `channel` | `object` | Metadados do catálogo de canais para superfícies de setup, seletor, quickstart e status |
|
||||
| `providers` | `string[]` | IDs de provedor registrados por este plugin |
|
||||
| Campo | Tipo | Descrição |
|
||||
| ------------ | ---------- | ----------------------------------------------------------------------------------------------------- |
|
||||
| `extensions` | `string[]` | Arquivos de ponto de entrada (relativos à raiz do pacote) |
|
||||
| `setupEntry` | `string` | Entrada leve apenas para configuração (opcional) |
|
||||
| `channel` | `object` | Metadados do catálogo de canais para configuração, seletor, início rápido e superfícies de status |
|
||||
| `providers` | `string[]` | IDs de provedores registrados por este Plugin |
|
||||
| `install` | `object` | Dicas de instalação: `npmSpec`, `localPath`, `defaultChoice`, `minHostVersion`, `allowInvalidConfigRecovery` |
|
||||
| `startup` | `object` | Flags de comportamento de inicialização |
|
||||
| `startup` | `object` | Flags de comportamento de inicialização |
|
||||
|
||||
### `openclaw.channel`
|
||||
|
||||
`openclaw.channel` são metadados leves de pacote para descoberta de canal e superfícies de setup
|
||||
antes do carregamento do runtime.
|
||||
`openclaw.channel` é um metadado barato de pacote para descoberta de canais e
|
||||
superfícies de configuração antes que o runtime seja carregado.
|
||||
|
||||
| Campo | Tipo | O que significa |
|
||||
| -------------------------------------- | ---------- | ------------------------------------------------------------------------------ |
|
||||
| `id` | `string` | ID canônico do canal. |
|
||||
| `label` | `string` | Rótulo principal do canal. |
|
||||
| `selectionLabel` | `string` | Rótulo de seletor/setup quando deve diferir de `label`. |
|
||||
| `detailLabel` | `string` | Rótulo de detalhe secundário para catálogos de canal e superfícies de status mais ricos. |
|
||||
| `docsPath` | `string` | Caminho da documentação para links de setup e seleção. |
|
||||
| `docsLabel` | `string` | Rótulo substituto usado para links de documentação quando deve diferir do id do canal. |
|
||||
| `blurb` | `string` | Descrição curta de onboarding/catálogo. |
|
||||
| `order` | `number` | Ordem de classificação em catálogos de canal. |
|
||||
| `aliases` | `string[]` | Aliases extras de lookup para seleção de canal. |
|
||||
| `preferOver` | `string[]` | IDs de plugin/canal de prioridade mais baixa sobre os quais este canal deve prevalecer. |
|
||||
| `systemImage` | `string` | Nome opcional de ícone/system-image para catálogos de UI de canal. |
|
||||
| `selectionDocsPrefix` | `string` | Texto de prefixo antes dos links de documentação em superfícies de seleção. |
|
||||
| `selectionDocsOmitLabel` | `boolean` | Mostra o caminho da documentação diretamente em vez de um link rotulado nas cópias de seleção. |
|
||||
| `selectionExtras` | `string[]` | Strings curtas extras anexadas na cópia de seleção. |
|
||||
| Campo | Tipo | O que significa |
|
||||
| -------------------------------------- | ---------- | ----------------------------------------------------------------------------- |
|
||||
| `id` | `string` | ID canônico do canal. |
|
||||
| `label` | `string` | Rótulo principal do canal. |
|
||||
| `selectionLabel` | `string` | Rótulo do seletor/configuração quando deve ser diferente de `label`. |
|
||||
| `detailLabel` | `string` | Rótulo de detalhe secundário para catálogos de canais e superfícies de status mais ricos. |
|
||||
| `docsPath` | `string` | Caminho da documentação para links de configuração e seleção. |
|
||||
| `docsLabel` | `string` | Rótulo substituto usado para links de documentação quando deve ser diferente do ID do canal. |
|
||||
| `blurb` | `string` | Descrição curta para onboarding/catálogo. |
|
||||
| `order` | `number` | Ordem de classificação em catálogos de canais. |
|
||||
| `aliases` | `string[]` | Aliases extras de busca para seleção de canal. |
|
||||
| `preferOver` | `string[]` | IDs de Plugin/canal de prioridade inferior que este canal deve superar. |
|
||||
| `systemImage` | `string` | Nome opcional de ícone/imagem do sistema para catálogos de UI de canais. |
|
||||
| `selectionDocsPrefix` | `string` | Texto de prefixo antes dos links de documentação nas superfícies de seleção. |
|
||||
| `selectionDocsOmitLabel` | `boolean` | Mostra o caminho da documentação diretamente em vez de um link rotulado na cópia de seleção. |
|
||||
| `selectionExtras` | `string[]` | Strings curtas extras anexadas na cópia de seleção. |
|
||||
| `markdownCapable` | `boolean` | Marca o canal como compatível com Markdown para decisões de formatação de saída. |
|
||||
| `exposure` | `object` | Controles de visibilidade do canal para superfícies de setup, listas configuradas e documentação. |
|
||||
| `quickstartAllowFrom` | `boolean` | Inclui este canal no fluxo padrão de setup `allowFrom` do quickstart. |
|
||||
| `forceAccountBinding` | `boolean` | Exige vinculação explícita de conta mesmo quando existe apenas uma conta. |
|
||||
| `preferSessionLookupForAnnounceTarget` | `boolean` | Prefere lookup de sessão ao resolver destinos de anúncio para este canal. |
|
||||
| `exposure` | `object` | Controles de visibilidade do canal para configuração, listas configuradas e superfícies de documentação. |
|
||||
| `quickstartAllowFrom` | `boolean` | Inclui este canal no fluxo padrão de configuração `allowFrom` de início rápido. |
|
||||
| `forceAccountBinding` | `boolean` | Exige vínculo explícito de conta mesmo quando existe apenas uma conta. |
|
||||
| `preferSessionLookupForAnnounceTarget` | `boolean` | Prefere busca de sessão ao resolver destinos de anúncio para este canal. |
|
||||
|
||||
Exemplo:
|
||||
|
||||
@ -145,35 +145,35 @@ Exemplo:
|
||||
|
||||
`exposure` oferece suporte a:
|
||||
|
||||
- `configured`: inclui o canal em superfícies de listagem configurada/estilo status
|
||||
- `setup`: inclui o canal em seletores interativos de setup/configuração
|
||||
- `docs`: marca o canal como público em superfícies de documentação/navegação
|
||||
- `configured`: incluir o canal em superfícies de listagem no estilo configurado/status
|
||||
- `setup`: incluir o canal em seletores interativos de configuração/configurar
|
||||
- `docs`: marcar o canal como voltado ao público em superfícies de documentação/navegação
|
||||
|
||||
`showConfigured` e `showInSetup` continuam aceitos como aliases legados. Prefira
|
||||
`showConfigured` e `showInSetup` continuam com suporte como aliases legados. Prefira
|
||||
`exposure`.
|
||||
|
||||
### `openclaw.install`
|
||||
|
||||
`openclaw.install` é metadado de pacote, não metadado de manifesto.
|
||||
`openclaw.install` é um metadado de pacote, não um metadado de manifesto.
|
||||
|
||||
| Campo | Tipo | O que significa |
|
||||
| ---------------------------- | -------------------- | --------------------------------------------------------------------------------- |
|
||||
| ---------------------------- | -------------------- | -------------------------------------------------------------------------------- |
|
||||
| `npmSpec` | `string` | Especificação npm canônica para fluxos de instalação/atualização. |
|
||||
| `localPath` | `string` | Caminho de instalação local de desenvolvimento ou empacotada. |
|
||||
| `defaultChoice` | `"npm"` \| `"local"` | Origem de instalação preferida quando ambas estão disponíveis. |
|
||||
| `minHostVersion` | `string` | Versão mínima compatível do OpenClaw no formato `>=x.y.z`. |
|
||||
| `allowInvalidConfigRecovery` | `boolean` | Permite que fluxos de reinstalação de plugin empacotado recuperem falhas específicas de configuração obsoleta. |
|
||||
| `localPath` | `string` | Caminho local de desenvolvimento ou instalação empacotada. |
|
||||
| `defaultChoice` | `"npm"` \| `"local"` | Fonte de instalação preferida quando ambas estiverem disponíveis. |
|
||||
| `minHostVersion` | `string` | Versão mínima suportada do OpenClaw no formato `>=x.y.z`. |
|
||||
| `allowInvalidConfigRecovery` | `boolean` | Permite que fluxos de reinstalação de Plugin empacotado recuperem falhas específicas de config obsoleta. |
|
||||
|
||||
Se `minHostVersion` estiver definido, tanto a instalação quanto o carregamento do registro de manifestos
|
||||
o aplicarão. Hosts mais antigos ignoram o plugin; strings de versão inválidas são rejeitadas.
|
||||
Se `minHostVersion` estiver definido, tanto a instalação quanto o carregamento do registro de manifesto o aplicarão.
|
||||
Hosts mais antigos ignoram o Plugin; strings de versão inválidas são rejeitadas.
|
||||
|
||||
`allowInvalidConfigRecovery` não é um bypass geral para configurações quebradas. Ele existe
|
||||
apenas para recuperação restrita de plugins empacotados, para que reinstalação/setup possa reparar sobras
|
||||
conhecidas de upgrades, como um caminho ausente de plugin empacotado ou uma entrada obsoleta `channels.<id>`
|
||||
para esse mesmo plugin. Se a configuração estiver quebrada por motivos não relacionados, a instalação
|
||||
ainda falha de forma fechada e orienta o operador a executar `openclaw doctor --fix`.
|
||||
`allowInvalidConfigRecovery` não é um bypass geral para configs quebradas. É
|
||||
para recuperação restrita apenas de Plugin empacotado, de modo que reinstalação/configuração possa reparar sobras conhecidas
|
||||
de upgrade, como um caminho ausente de Plugin empacotado ou uma entrada obsoleta `channels.<id>`
|
||||
desse mesmo Plugin. Se a config estiver quebrada por motivos não relacionados, a instalação
|
||||
ainda falhará de forma fechada e informará ao operador para executar `openclaw doctor --fix`.
|
||||
|
||||
### Carregamento completo adiado
|
||||
### Adiamento do carregamento completo
|
||||
|
||||
Plugins de canal podem optar por carregamento adiado com:
|
||||
|
||||
@ -189,26 +189,26 @@ Plugins de canal podem optar por carregamento adiado com:
|
||||
}
|
||||
```
|
||||
|
||||
Quando ativado, o OpenClaw carrega apenas `setupEntry` durante a fase de inicialização
|
||||
pré-listen, mesmo para canais já configurados. A entrada completa carrega depois que o
|
||||
gateway começa a escutar.
|
||||
Quando ativado, o OpenClaw carrega apenas `setupEntry` durante a fase de
|
||||
inicialização anterior ao listen, mesmo para canais já configurados. A entrada completa é carregada após o
|
||||
gateway começar a escutar.
|
||||
|
||||
<Warning>
|
||||
Ative o carregamento adiado apenas quando seu `setupEntry` registrar tudo de que o
|
||||
Ative o carregamento adiado apenas quando seu `setupEntry` registrar tudo o que o
|
||||
gateway precisa antes de começar a escutar (registro de canal, rotas HTTP,
|
||||
métodos do gateway). Se a entrada completa controlar capacidades obrigatórias de inicialização, mantenha
|
||||
métodos do gateway). Se a entrada completa possuir recursos de inicialização obrigatórios, mantenha
|
||||
o comportamento padrão.
|
||||
</Warning>
|
||||
|
||||
Se sua entrada de setup/completa registrar métodos RPC do gateway, mantenha-os em um
|
||||
prefixo específico do plugin. Os namespaces administrativos reservados do core (`config.*`,
|
||||
`exec.approvals.*`, `wizard.*`, `update.*`) continuam pertencendo ao core e sempre são resolvidos
|
||||
Se sua entrada de configuração/completa registrar métodos RPC do gateway, mantenha-os em um
|
||||
prefixo específico do Plugin. Namespaces administrativos reservados do core (`config.*`,
|
||||
`exec.approvals.*`, `wizard.*`, `update.*`) continuam pertencendo ao core e sempre serão resolvidos
|
||||
para `operator.admin`.
|
||||
|
||||
## Manifesto do plugin
|
||||
## Manifesto do Plugin
|
||||
|
||||
Todo plugin nativo deve incluir um `openclaw.plugin.json` na raiz do pacote.
|
||||
O OpenClaw usa isso para validar a configuração sem executar o código do plugin.
|
||||
Todo Plugin nativo deve incluir um `openclaw.plugin.json` na raiz do pacote.
|
||||
O OpenClaw usa isso para validar a config sem executar código do Plugin.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -228,7 +228,7 @@ O OpenClaw usa isso para validar a configuração sem executar o código do plug
|
||||
}
|
||||
```
|
||||
|
||||
Para plugins de canal, adicione `kind` e `channels`:
|
||||
Para Plugins de canal, adicione `kind` e `channels`:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -243,7 +243,7 @@ Para plugins de canal, adicione `kind` e `channels`:
|
||||
}
|
||||
```
|
||||
|
||||
Mesmo plugins sem configuração devem incluir um schema. Um schema vazio é válido:
|
||||
Mesmo Plugins sem config devem incluir um esquema. Um esquema vazio é válido:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -255,25 +255,25 @@ Mesmo plugins sem configuração devem incluir um schema. Um schema vazio é vá
|
||||
}
|
||||
```
|
||||
|
||||
Consulte [Plugin Manifest](/pt-BR/plugins/manifest) para a referência completa do schema.
|
||||
Consulte [Manifesto do Plugin](/pt-BR/plugins/manifest) para a referência completa do esquema.
|
||||
|
||||
## Publicação no ClawHub
|
||||
|
||||
Para pacotes de plugin, use o comando do ClawHub específico para pacote:
|
||||
Para pacotes de Plugin, use o comando do ClawHub específico para pacotes:
|
||||
|
||||
```bash
|
||||
clawhub package publish your-org/your-plugin --dry-run
|
||||
clawhub package publish your-org/your-plugin
|
||||
```
|
||||
|
||||
O alias legado de publicação apenas para skill é para Skills. Pacotes de plugin devem
|
||||
O alias legado de publicação apenas para Skills é para Skills. Pacotes de Plugin devem
|
||||
sempre usar `clawhub package publish`.
|
||||
|
||||
## Entrada de setup
|
||||
## Entrada de configuração
|
||||
|
||||
O arquivo `setup-entry.ts` é uma alternativa leve ao `index.ts` que o
|
||||
OpenClaw carrega quando precisa apenas das superfícies de setup (onboarding, reparo de configuração,
|
||||
inspeção de canal desativado).
|
||||
O arquivo `setup-entry.ts` é uma alternativa leve a `index.ts` que
|
||||
o OpenClaw carrega quando precisa apenas das superfícies de configuração (onboarding, reparo
|
||||
de config, inspeção de canal desativado).
|
||||
|
||||
```typescript
|
||||
// setup-entry.ts
|
||||
@ -283,20 +283,26 @@ import { myChannelPlugin } from "./src/channel.js";
|
||||
export default defineSetupPluginEntry(myChannelPlugin);
|
||||
```
|
||||
|
||||
Isso evita carregar código pesado de runtime (bibliotecas de criptografia, registros de CLI,
|
||||
serviços em segundo plano) durante os fluxos de setup.
|
||||
Isso evita carregar código pesado de runtime (bibliotecas de criptografia, registros
|
||||
de CLI, serviços em segundo plano) durante fluxos de configuração.
|
||||
|
||||
Canais empacotados do workspace que mantêm exportações seguras para configuração em módulos sidecar podem
|
||||
usar `defineBundledChannelSetupEntry(...)` de
|
||||
`openclaw/plugin-sdk/channel-entry-contract` em vez de
|
||||
`defineSetupPluginEntry(...)`. Esse contrato empacotado também oferece suporte a uma exportação opcional
|
||||
`runtime`, para que o wiring de runtime em tempo de configuração permaneça leve e explícito.
|
||||
|
||||
**Quando o OpenClaw usa `setupEntry` em vez da entrada completa:**
|
||||
|
||||
- O canal está desativado, mas precisa de superfícies de setup/onboarding
|
||||
- O canal está desativado, mas precisa de superfícies de configuração/onboarding
|
||||
- O canal está ativado, mas não configurado
|
||||
- O carregamento adiado está ativado (`deferConfiguredChannelFullLoadUntilAfterListen`)
|
||||
|
||||
**O que `setupEntry` deve registrar:**
|
||||
|
||||
- O objeto do plugin de canal (via `defineSetupPluginEntry`)
|
||||
- Quaisquer rotas HTTP necessárias antes do gateway escutar
|
||||
- Quaisquer métodos de gateway necessários durante a inicialização
|
||||
- O objeto do Plugin de canal (via `defineSetupPluginEntry`)
|
||||
- Quaisquer rotas HTTP necessárias antes de o gateway entrar em listen
|
||||
- Quaisquer métodos do gateway necessários durante a inicialização
|
||||
|
||||
Esses métodos de gateway de inicialização ainda devem evitar namespaces administrativos reservados do core
|
||||
como `config.*` ou `update.*`.
|
||||
@ -306,53 +312,53 @@ como `config.*` ou `update.*`.
|
||||
- Registros de CLI
|
||||
- Serviços em segundo plano
|
||||
- Imports pesados de runtime (crypto, SDKs)
|
||||
- Métodos de gateway necessários apenas após a inicialização
|
||||
- Métodos do gateway necessários apenas após a inicialização
|
||||
|
||||
### Imports restritos de helpers de setup
|
||||
### Imports restritos de helpers de configuração
|
||||
|
||||
Para caminhos quentes apenas de setup, prefira as interfaces restritas de helper de setup em vez da
|
||||
interface guarda-chuva mais ampla `plugin-sdk/setup` quando precisar apenas de parte da superfície de setup:
|
||||
Para caminhos quentes apenas de configuração, prefira os seams restritos de helper de configuração em vez do umbrella mais amplo
|
||||
`plugin-sdk/setup` quando você precisar apenas de parte da superfície de configuração:
|
||||
|
||||
| Caminho de importação | Use para | Exportações principais |
|
||||
| ------------------------------------ | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `plugin-sdk/setup-runtime` | helpers de runtime em tempo de setup que permanecem disponíveis em `setupEntry` / inicialização adiada de canal | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
|
||||
| `plugin-sdk/setup-adapter-runtime` | adaptadores de setup de conta com reconhecimento de ambiente | `createEnvPatchedAccountSetupAdapter` |
|
||||
| `plugin-sdk/setup-tools` | helpers de CLI/arquivo/documentação de setup/instalação | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
|
||||
| Caminho de importação | Use para | Exportações principais |
|
||||
| ----------------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `plugin-sdk/setup-runtime` | helpers de runtime em tempo de configuração que permanecem disponíveis em `setupEntry` / inicialização adiada de canal | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
|
||||
| `plugin-sdk/setup-adapter-runtime` | adaptadores de configuração de conta com reconhecimento de ambiente | `createEnvPatchedAccountSetupAdapter` |
|
||||
| `plugin-sdk/setup-tools` | helpers de CLI/arquivo/documentação para configuração/instalação | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
|
||||
|
||||
Use a interface mais ampla `plugin-sdk/setup` quando quiser a caixa de ferramentas completa e compartilhada de setup,
|
||||
incluindo helpers de patch de configuração, como
|
||||
Use o seam mais amplo `plugin-sdk/setup` quando quiser a caixa de ferramentas completa e compartilhada de configuração,
|
||||
incluindo helpers de patch de config como
|
||||
`moveSingleAccountChannelSectionToDefaultAccount(...)`.
|
||||
|
||||
Os adaptadores de patch de setup continuam seguros para importação em caminhos quentes. O lookup preguiçoso
|
||||
da superfície de contrato empacotada para promoção de conta única significa que importar
|
||||
Os adaptadores de patch de configuração continuam seguros para importação em caminhos quentes. A busca da superfície de contrato empacotada
|
||||
para promoção de conta única é lazy, portanto importar
|
||||
`plugin-sdk/setup-runtime` não carrega antecipadamente a descoberta da superfície de contrato empacotada
|
||||
antes de o adaptador ser realmente usado.
|
||||
antes de o adaptador realmente ser usado.
|
||||
|
||||
### Promoção de conta única controlada pelo canal
|
||||
|
||||
Quando um canal é atualizado de uma configuração de nível superior de conta única para
|
||||
`channels.<id>.accounts.*`, o comportamento compartilhado padrão é mover valores promovidos
|
||||
com escopo de conta para `accounts.default`.
|
||||
Quando um canal é atualizado de uma config de nível superior de conta única para
|
||||
`channels.<id>.accounts.*`, o comportamento compartilhado padrão é mover valores
|
||||
promovidos com escopo de conta para `accounts.default`.
|
||||
|
||||
Canais empacotados podem restringir ou substituir essa promoção por meio da sua
|
||||
superfície de contrato de setup:
|
||||
Canais empacotados podem restringir ou substituir essa promoção por meio de sua
|
||||
superfície de contrato de configuração:
|
||||
|
||||
- `singleAccountKeysToMove`: chaves extras de nível superior que devem ser movidas para a
|
||||
conta promovida
|
||||
- `namedAccountPromotionKeys`: quando contas nomeadas já existem, apenas essas
|
||||
chaves são movidas para a conta promovida; chaves compartilhadas de política/entrega permanecem na
|
||||
raiz do canal
|
||||
- `namedAccountPromotionKeys`: quando contas nomeadas já existem, apenas estas
|
||||
chaves são movidas para a conta promovida; chaves compartilhadas de política/entrega permanecem na raiz
|
||||
do canal
|
||||
- `resolveSingleAccountPromotionTarget(...)`: escolhe qual conta existente
|
||||
recebe os valores promovidos
|
||||
|
||||
Matrix é o exemplo empacotado atual. Se já existir exatamente uma conta Matrix nomeada,
|
||||
ou se `defaultAccount` apontar para uma chave não canônica existente, como `Ops`,
|
||||
a promoção preservará essa conta em vez de criar uma nova entrada
|
||||
`accounts.default`.
|
||||
Matrix é o exemplo empacotado atual. Se exatamente uma conta Matrix nomeada
|
||||
já existir, ou se `defaultAccount` apontar para uma chave não canônica existente
|
||||
como `Ops`, a promoção preserva essa conta em vez de criar uma nova
|
||||
entrada `accounts.default`.
|
||||
|
||||
## Schema de configuração
|
||||
## Esquema de config
|
||||
|
||||
A configuração do plugin é validada em relação ao JSON Schema no seu manifesto. Usuários
|
||||
A config do Plugin é validada em relação ao JSON Schema no seu manifesto. Os usuários
|
||||
configuram plugins por meio de:
|
||||
|
||||
```json5
|
||||
@ -369,9 +375,9 @@ configuram plugins por meio de:
|
||||
}
|
||||
```
|
||||
|
||||
Seu plugin recebe essa configuração como `api.pluginConfig` durante o registro.
|
||||
Seu Plugin recebe essa config como `api.pluginConfig` durante o registro.
|
||||
|
||||
Para configuração específica de canal, use a seção de configuração do canal:
|
||||
Para config específica de canal, use a seção de config do canal:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -384,10 +390,10 @@ Para configuração específica de canal, use a seção de configuração do can
|
||||
}
|
||||
```
|
||||
|
||||
### Criando schemas de configuração de canal
|
||||
### Criando esquemas de config de canal
|
||||
|
||||
Use `buildChannelConfigSchema` de `openclaw/plugin-sdk/core` para converter um
|
||||
schema Zod no wrapper `ChannelConfigSchema` que o OpenClaw valida:
|
||||
esquema Zod no wrapper `ChannelConfigSchema` que o OpenClaw valida:
|
||||
|
||||
```typescript
|
||||
import { z } from "zod";
|
||||
@ -403,9 +409,9 @@ const accountSchema = z.object({
|
||||
const configSchema = buildChannelConfigSchema(accountSchema);
|
||||
```
|
||||
|
||||
## Assistentes de setup
|
||||
## Assistentes de configuração
|
||||
|
||||
Plugins de canal podem fornecer assistentes interativos de setup para `openclaw onboard`.
|
||||
Plugins de canal podem fornecer assistentes interativos de configuração para `openclaw onboard`.
|
||||
O assistente é um objeto `ChannelSetupWizard` no `ChannelPlugin`:
|
||||
|
||||
```typescript
|
||||
@ -441,21 +447,21 @@ const setupWizard: ChannelSetupWizard = {
|
||||
|
||||
O tipo `ChannelSetupWizard` oferece suporte a `credentials`, `textInputs`,
|
||||
`dmPolicy`, `allowFrom`, `groupAccess`, `prepare`, `finalize` e mais.
|
||||
Consulte pacotes de plugins empacotados (por exemplo o plugin Discord em `src/channel.setup.ts`) para
|
||||
Consulte os pacotes de Plugin empacotados (por exemplo, o Plugin do Discord em `src/channel.setup.ts`) para
|
||||
exemplos completos.
|
||||
|
||||
Para prompts de allowlist de DM que precisam apenas do fluxo padrão
|
||||
`note -> prompt -> parse -> merge -> patch`, prefira os helpers compartilhados de setup
|
||||
`note -> prompt -> parse -> merge -> patch`, prefira os helpers compartilhados de configuração
|
||||
de `openclaw/plugin-sdk/setup`: `createPromptParsedAllowFromForAccount(...)`,
|
||||
`createTopLevelChannelParsedAllowFromPrompt(...)` e
|
||||
`createNestedChannelParsedAllowFromPrompt(...)`.
|
||||
|
||||
Para blocos de status de setup de canal que variam apenas em rótulos, pontuações e linhas extras opcionais,
|
||||
Para blocos de status de configuração de canal que variam apenas por rótulos, pontuações e linhas extras opcionais,
|
||||
prefira `createStandardChannelSetupStatus(...)` de
|
||||
`openclaw/plugin-sdk/setup` em vez de criar manualmente o mesmo objeto `status` em
|
||||
cada plugin.
|
||||
`openclaw/plugin-sdk/setup` em vez de montar manualmente o mesmo objeto `status` em
|
||||
cada Plugin.
|
||||
|
||||
Para superfícies de setup opcionais que devem aparecer apenas em certos contextos, use
|
||||
Para superfícies opcionais de configuração que devem aparecer apenas em certos contextos, use
|
||||
`createOptionalChannelSetupSurface` de `openclaw/plugin-sdk/channel-setup`:
|
||||
|
||||
```typescript
|
||||
@ -470,17 +476,17 @@ const setupSurface = createOptionalChannelSetupSurface({
|
||||
// Returns { setupAdapter, setupWizard }
|
||||
```
|
||||
|
||||
`plugin-sdk/channel-setup` também expõe os builders de nível inferior
|
||||
`plugin-sdk/channel-setup` também expõe os builders de nível mais baixo
|
||||
`createOptionalChannelSetupAdapter(...)` e
|
||||
`createOptionalChannelSetupWizard(...)` quando você precisar apenas de metade
|
||||
`createOptionalChannelSetupWizard(...)` quando você precisa apenas de uma metade
|
||||
dessa superfície de instalação opcional.
|
||||
|
||||
O adaptador/assistente opcional gerado falha de forma fechada em gravações reais de configuração. Eles
|
||||
O adaptador/assistente opcional gerado falha de forma fechada em gravações reais de config. Eles
|
||||
reutilizam uma única mensagem de instalação obrigatória em `validateInput`,
|
||||
`applyAccountConfig` e `finalize`, e acrescentam um link de documentação quando `docsPath` estiver
|
||||
`applyAccountConfig` e `finalize`, e acrescentam um link de documentação quando `docsPath` está
|
||||
definido.
|
||||
|
||||
Para UIs de setup baseadas em binário, prefira os helpers delegados compartilhados em vez de
|
||||
Para UIs de configuração baseadas em binário, prefira os helpers delegados compartilhados em vez de
|
||||
copiar a mesma cola de binário/status em cada canal:
|
||||
|
||||
- `createDetectedBinaryStatus(...)` para blocos de status que variam apenas por rótulos,
|
||||
@ -488,35 +494,35 @@ copiar a mesma cola de binário/status em cada canal:
|
||||
- `createCliPathTextInput(...)` para entradas de texto baseadas em caminho
|
||||
- `createDelegatedSetupWizardStatusResolvers(...)`,
|
||||
`createDelegatedPrepare(...)`, `createDelegatedFinalize(...)` e
|
||||
`createDelegatedResolveConfigured(...)` quando `setupEntry` precisar encaminhar preguiçosamente para
|
||||
um assistente completo mais pesado
|
||||
- `createDelegatedTextInputShouldPrompt(...)` quando `setupEntry` só precisar
|
||||
delegar uma decisão de `textInputs[*].shouldPrompt`
|
||||
`createDelegatedResolveConfigured(...)` quando `setupEntry` precisa encaminhar para
|
||||
um assistente completo mais pesado de forma lazy
|
||||
- `createDelegatedTextInputShouldPrompt(...)` quando `setupEntry` precisa apenas
|
||||
delegar uma decisão `textInputs[*].shouldPrompt`
|
||||
|
||||
## Publicação e instalação
|
||||
|
||||
**Plugins externos:** publique no [ClawHub](/pt-BR/tools/clawhub) ou npm e depois instale:
|
||||
**Plugins externos:** publique no [ClawHub](/pt-BR/tools/clawhub) ou no npm e depois instale:
|
||||
|
||||
```bash
|
||||
openclaw plugins install @myorg/openclaw-my-plugin
|
||||
```
|
||||
|
||||
O OpenClaw tenta primeiro o ClawHub e recorre automaticamente ao npm. Você também pode
|
||||
forçar o ClawHub explicitamente:
|
||||
forçar explicitamente o ClawHub:
|
||||
|
||||
```bash
|
||||
openclaw plugins install clawhub:@myorg/openclaw-my-plugin # somente ClawHub
|
||||
```
|
||||
|
||||
Não existe um override correspondente `npm:`. Use a especificação normal de pacote npm quando
|
||||
Não existe uma substituição correspondente `npm:`. Use a especificação normal de pacote npm quando
|
||||
quiser o caminho npm após o fallback do ClawHub:
|
||||
|
||||
```bash
|
||||
openclaw plugins install @myorg/openclaw-my-plugin
|
||||
```
|
||||
|
||||
**Plugins no repositório:** coloque-os sob a árvore de workspace de plugins empacotados e eles serão
|
||||
descobertos automaticamente durante a build.
|
||||
**Plugins no repositório:** coloque-os na árvore de workspace de plugins empacotados e eles serão automaticamente
|
||||
descobertos durante o build.
|
||||
|
||||
**Os usuários podem instalar:**
|
||||
|
||||
@ -525,13 +531,13 @@ openclaw plugins install <package-name>
|
||||
```
|
||||
|
||||
<Info>
|
||||
Para instalações obtidas do npm, `openclaw plugins install` executa
|
||||
`npm install --ignore-scripts` (sem scripts de ciclo de vida). Mantenha as árvores de dependência
|
||||
de plugin em JS/TS puro e evite pacotes que exijam builds em `postinstall`.
|
||||
Para instalações vindas do npm, `openclaw plugins install` executa
|
||||
`npm install --ignore-scripts` (sem scripts de ciclo de vida). Mantenha as árvores
|
||||
de dependências do Plugin em JS/TS puro e evite pacotes que exijam builds em `postinstall`.
|
||||
</Info>
|
||||
|
||||
## Relacionado
|
||||
|
||||
- [SDK Entry Points](/pt-BR/plugins/sdk-entrypoints) -- `definePluginEntry` e `defineChannelPluginEntry`
|
||||
- [Plugin Manifest](/pt-BR/plugins/manifest) -- referência completa do schema de manifesto
|
||||
- [Building Plugins](/pt-BR/plugins/building-plugins) -- guia passo a passo de primeiros passos
|
||||
- [Pontos de entrada do SDK](/pt-BR/plugins/sdk-entrypoints) -- `definePluginEntry` e `defineChannelPluginEntry`
|
||||
- [Manifesto do Plugin](/pt-BR/plugins/manifest) -- referência completa do esquema do manifesto
|
||||
- [Criando Plugins](/pt-BR/plugins/building-plugins) -- guia passo a passo para começar
|
||||
|
||||
@ -1,29 +1,28 @@
|
||||
---
|
||||
read_when:
|
||||
- Você está escrevendo testes para um plugin
|
||||
- Você precisa de utilitários de teste do SDK de plugin
|
||||
- Você quer entender testes de contrato para plugins empacotados
|
||||
- Você está escrevendo testes para um Plugin
|
||||
- Você precisa de utilitários de teste do SDK de Plugin
|
||||
- Você quer entender os testes de contrato para plugins empacotados
|
||||
sidebarTitle: Testing
|
||||
summary: Utilitários e padrões de teste para plugins do OpenClaw
|
||||
title: Testes de Plugin
|
||||
title: Teste de Plugin
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T12:49:56Z"
|
||||
generated_at: "2026-04-15T19:41:42Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 2e95ed58ed180feadad17bb5138bd09e3b45f1f3ecdff4e2fba4874bb80099fe
|
||||
source_hash: 2f75bd3f3b5ba34b05786e0dd96d493c36db73a1d258998bf589e27e45c0bd09
|
||||
source_path: plugins/sdk-testing.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Testes de Plugin
|
||||
# Teste de Plugin
|
||||
|
||||
Referência para utilitários de teste, padrões e aplicação de lint para
|
||||
plugins do OpenClaw.
|
||||
Referência para utilitários de teste, padrões e aplicação de lint para plugins do OpenClaw.
|
||||
|
||||
<Tip>
|
||||
**Procurando exemplos de teste?** Os guias práticos incluem exemplos de teste completos:
|
||||
[Testes de plugin de canal](/plugins/sdk-channel-plugins#step-6-test) e
|
||||
[Testes de plugin de provedor](/plugins/sdk-provider-plugins#step-6-test).
|
||||
[Testes de Plugin de canal](/pt-BR/plugins/sdk-channel-plugins#step-6-test) e
|
||||
[Testes de Plugin de provedor](/pt-BR/plugins/sdk-provider-plugins#step-6-test).
|
||||
</Tip>
|
||||
|
||||
## Utilitários de teste
|
||||
@ -42,11 +41,11 @@ import {
|
||||
|
||||
### Exportações disponíveis
|
||||
|
||||
| Exportação | Finalidade |
|
||||
| ------------------------------------- | ------------------------------------------------------ |
|
||||
| `installCommonResolveTargetErrorCases` | Casos de teste compartilhados para tratamento de erros de resolução de destino |
|
||||
| `shouldAckReaction` | Verifica se um canal deve adicionar uma reação de ack |
|
||||
| `removeAckReactionAfterReply` | Remove a reação de ack após a entrega da resposta |
|
||||
| Export | Propósito |
|
||||
| -------------------------------------- | -------------------------------------------------------- |
|
||||
| `installCommonResolveTargetErrorCases` | Casos de teste compartilhados para tratamento de erros de resolução de alvo |
|
||||
| `shouldAckReaction` | Verifica se um canal deve adicionar uma reação de confirmação |
|
||||
| `removeAckReactionAfterReply` | Remove a reação de confirmação após a entrega da resposta |
|
||||
|
||||
### Tipos
|
||||
|
||||
@ -63,10 +62,9 @@ import type {
|
||||
} from "openclaw/plugin-sdk/testing";
|
||||
```
|
||||
|
||||
## Testando a resolução de destino
|
||||
## Testando a resolução de alvo
|
||||
|
||||
Use `installCommonResolveTargetErrorCases` para adicionar casos de erro padrão para
|
||||
resolução de destino de canal:
|
||||
Use `installCommonResolveTargetErrorCases` para adicionar casos de erro padrão para resolução de alvo do canal:
|
||||
|
||||
```typescript
|
||||
import { describe } from "vitest";
|
||||
@ -90,7 +88,7 @@ describe("my-channel target resolution", () => {
|
||||
|
||||
## Padrões de teste
|
||||
|
||||
### Testando unitariamente um plugin de canal
|
||||
### Teste unitário de um Plugin de canal
|
||||
|
||||
```typescript
|
||||
import { describe, it, expect, vi } from "vitest";
|
||||
@ -126,7 +124,7 @@ describe("my-channel plugin", () => {
|
||||
});
|
||||
```
|
||||
|
||||
### Testando unitariamente um plugin de provedor
|
||||
### Teste unitário de um Plugin de provedor
|
||||
|
||||
```typescript
|
||||
import { describe, it, expect } from "vitest";
|
||||
@ -154,15 +152,18 @@ describe("my-provider plugin", () => {
|
||||
});
|
||||
```
|
||||
|
||||
### Simulando o runtime do plugin
|
||||
### Mockando o runtime do Plugin
|
||||
|
||||
Para código que usa `createPluginRuntimeStore`, simule o runtime nos testes:
|
||||
Para código que usa `createPluginRuntimeStore`, faça mock do runtime nos testes:
|
||||
|
||||
```typescript
|
||||
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
|
||||
import type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store";
|
||||
|
||||
const store = createPluginRuntimeStore<PluginRuntime>("test runtime not set");
|
||||
const store = createPluginRuntimeStore<PluginRuntime>({
|
||||
pluginId: "test-plugin",
|
||||
errorMessage: "test runtime not set",
|
||||
});
|
||||
|
||||
// In test setup
|
||||
const mockRuntime = {
|
||||
@ -198,7 +199,7 @@ client.sendMessage = vi.fn().mockResolvedValue({ id: "msg-1" });
|
||||
|
||||
## Testes de contrato (plugins no repositório)
|
||||
|
||||
Plugins empacotados têm testes de contrato que verificam a propriedade de registro:
|
||||
Plugins empacotados têm testes de contrato que verificam a propriedade do registro:
|
||||
|
||||
```bash
|
||||
pnpm test -- src/plugins/contracts/
|
||||
@ -213,13 +214,13 @@ Esses testes verificam:
|
||||
|
||||
### Executando testes com escopo
|
||||
|
||||
Para um plugin específico:
|
||||
Para um Plugin específico:
|
||||
|
||||
```bash
|
||||
pnpm test -- <bundled-plugin-root>/my-channel/
|
||||
```
|
||||
|
||||
Apenas para testes de contrato:
|
||||
Somente para testes de contrato:
|
||||
|
||||
```bash
|
||||
pnpm test -- src/plugins/contracts/shape.contract.test.ts
|
||||
@ -235,12 +236,11 @@ Três regras são aplicadas por `pnpm check` para plugins no repositório:
|
||||
2. **Sem importações diretas de `src/`** -- plugins não podem importar `../../src/` diretamente
|
||||
3. **Sem autoimportações** -- plugins não podem importar seu próprio subcaminho `plugin-sdk/<name>`
|
||||
|
||||
Plugins externos não estão sujeitos a essas regras de lint, mas seguir os mesmos
|
||||
padrões é recomendado.
|
||||
Plugins externos não estão sujeitos a essas regras de lint, mas seguir os mesmos padrões é recomendado.
|
||||
|
||||
## Configuração de teste
|
||||
|
||||
O OpenClaw usa Vitest com limites de cobertura V8. Para testes de plugin:
|
||||
O OpenClaw usa Vitest com limites de cobertura do V8. Para testes de Plugin:
|
||||
|
||||
```bash
|
||||
# Run all tests
|
||||
@ -262,9 +262,9 @@ Se as execuções locais causarem pressão de memória:
|
||||
OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test
|
||||
```
|
||||
|
||||
## Relacionado
|
||||
## Relacionados
|
||||
|
||||
- [Visão geral do SDK](/plugins/sdk-overview) -- convenções de importação
|
||||
- [SDK Channel Plugins](/plugins/sdk-channel-plugins) -- interface de plugin de canal
|
||||
- [SDK Provider Plugins](/plugins/sdk-provider-plugins) -- hooks de plugin de provedor
|
||||
- [Criando Plugins](/plugins/building-plugins) -- guia de introdução
|
||||
- [Visão geral do SDK](/pt-BR/plugins/sdk-overview) -- convenções de importação
|
||||
- [SDK de Plugins de canal](/pt-BR/plugins/sdk-channel-plugins) -- interface de Plugin de canal
|
||||
- [SDK de Plugins de provedor](/pt-BR/plugins/sdk-provider-plugins) -- hooks de Plugin de provedor
|
||||
- [Criando Plugins](/pt-BR/plugins/building-plugins) -- guia de introdução
|
||||
|
||||
@ -1,53 +1,67 @@
|
||||
---
|
||||
read_when:
|
||||
- Explicando o uso de tokens, custos ou janelas de contexto
|
||||
- Depurando o crescimento do contexto ou o comportamento de compactação
|
||||
summary: Como o OpenClaw monta o contexto do prompt e informa o uso de tokens + custos
|
||||
title: Uso de tokens e custos
|
||||
- Depurando o crescimento do contexto ou o comportamento de Compaction
|
||||
summary: Como o OpenClaw constrói o contexto do prompt e informa o uso de tokens + custos
|
||||
title: Uso de Tokens e Custos
|
||||
x-i18n:
|
||||
generated_at: "2026-04-12T05:33:21Z"
|
||||
generated_at: "2026-04-15T19:42:06Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: f8c856549cd28b8364a640e6fa9ec26aa736895c7a993e96cbe85838e7df2dfb
|
||||
source_hash: 9a706d3df8b2ea1136b3535d216c6b358e43aee2a31a4759824385e1345e6fe5
|
||||
source_path: reference/token-use.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Uso de tokens e custos
|
||||
|
||||
O OpenClaw rastreia **tokens**, não caracteres. Os tokens são específicos de cada modelo, mas a maioria dos
|
||||
modelos no estilo OpenAI tem uma média de ~4 caracteres por token em texto em inglês.
|
||||
O OpenClaw rastreia **tokens**, não caracteres. Os tokens são específicos de cada modelo, mas a maioria dos modelos no estilo OpenAI tem média de ~4 caracteres por token para texto em inglês.
|
||||
|
||||
## Como o prompt do sistema é montado
|
||||
## Como o prompt do sistema é construído
|
||||
|
||||
O OpenClaw monta seu próprio prompt do sistema em cada execução. Ele inclui:
|
||||
|
||||
- Lista de ferramentas + descrições curtas
|
||||
- Lista de Skills (somente metadados; as instruções são carregadas sob demanda com `read`)
|
||||
- Lista de Skills (somente metadados; as instruções são carregadas sob demanda com `read`).
|
||||
O bloco compacto de Skills é limitado por `skills.limits.maxSkillsPromptChars`,
|
||||
com substituição opcional por agente em
|
||||
`agents.list[].skillsLimits.maxSkillsPromptChars`.
|
||||
- Instruções de autoatualização
|
||||
- Arquivos de workspace + bootstrap (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md` quando novo, além de `MEMORY.md` quando presente ou `memory.md` como fallback em minúsculas). Arquivos grandes são truncados por `agents.defaults.bootstrapMaxChars` (padrão: 20000), e a injeção total de bootstrap é limitada por `agents.defaults.bootstrapTotalMaxChars` (padrão: 150000). Arquivos diários `memory/*.md` não fazem parte do prompt bootstrap normal; eles permanecem sob demanda por meio de ferramentas de memória em turnos comuns, mas `/new` e `/reset` sem nenhum argumento podem prefixar um bloco único de contexto de inicialização com memória diária recente para esse primeiro turno. Esse prelúdio de inicialização é controlado por `agents.defaults.startupContext`.
|
||||
- Arquivos do workspace + bootstrap (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md` quando novo, além de `MEMORY.md` quando presente ou `memory.md` como alternativa em minúsculas). Arquivos grandes são truncados por `agents.defaults.bootstrapMaxChars` (padrão: 12000), e a injeção total de bootstrap é limitada por `agents.defaults.bootstrapTotalMaxChars` (padrão: 60000). Arquivos diários `memory/*.md` não fazem parte do prompt de bootstrap normal; eles permanecem sob demanda via ferramentas de memória em turnos comuns, mas `/new` e `/reset` sem argumentos podem prefixar um bloco único de contexto de inicialização com memória diária recente para esse primeiro turno. Esse prelúdio de inicialização é controlado por `agents.defaults.startupContext`.
|
||||
- Hora (UTC + fuso horário do usuário)
|
||||
- Tags de resposta + comportamento de heartbeat
|
||||
- Tags de resposta + comportamento de Heartbeat
|
||||
- Metadados de runtime (host/OS/model/thinking)
|
||||
|
||||
Veja o detalhamento completo em [Prompt do sistema](/pt-BR/concepts/system-prompt).
|
||||
Veja a análise completa em [Prompt do sistema](/pt-BR/concepts/system-prompt).
|
||||
|
||||
## O que conta na janela de contexto
|
||||
|
||||
Tudo o que o modelo recebe conta para o limite de contexto:
|
||||
|
||||
- Prompt do sistema (todas as seções listadas acima)
|
||||
- Histórico da conversa (mensagens do usuário + assistente)
|
||||
- Chamadas de ferramentas e resultados de ferramentas
|
||||
- Histórico da conversa (mensagens do usuário + do assistente)
|
||||
- Chamadas de ferramenta e resultados de ferramenta
|
||||
- Anexos/transcrições (imagens, áudio, arquivos)
|
||||
- Resumos de compactação e artefatos de poda
|
||||
- Resumos de Compaction e artefatos de poda
|
||||
- Wrappers do provedor ou cabeçalhos de segurança (não visíveis, mas ainda contabilizados)
|
||||
|
||||
Para imagens, o OpenClaw reduz a escala das cargas de imagens de transcrição/ferramentas antes das chamadas ao provedor.
|
||||
Algumas superfícies pesadas de runtime têm seus próprios limites explícitos:
|
||||
|
||||
- `agents.defaults.contextLimits.memoryGetMaxChars`
|
||||
- `agents.defaults.contextLimits.memoryGetDefaultLines`
|
||||
- `agents.defaults.contextLimits.toolResultMaxChars`
|
||||
- `agents.defaults.contextLimits.postCompactionMaxChars`
|
||||
|
||||
As substituições por agente ficam em `agents.list[].contextLimits`. Esses ajustes são
|
||||
para trechos limitados de runtime e blocos injetados de propriedade do runtime. Eles são
|
||||
separados dos limites de bootstrap, dos limites de contexto de inicialização e dos
|
||||
limites do prompt de Skills.
|
||||
|
||||
Para imagens, o OpenClaw reduz a escala de cargas de imagem de transcrição/ferramenta antes das chamadas ao provedor.
|
||||
Use `agents.defaults.imageMaxDimensionPx` (padrão: `1200`) para ajustar isso:
|
||||
|
||||
- Valores menores geralmente reduzem o uso de vision tokens e o tamanho da carga.
|
||||
- Valores maiores preservam mais detalhes visuais para OCR/capturas de tela com muita interface.
|
||||
- Valores menores normalmente reduzem o uso de vision tokens e o tamanho da carga.
|
||||
- Valores maiores preservam mais detalhes visuais para capturas de tela com muito OCR/UI.
|
||||
|
||||
Para uma análise prática (por arquivo injetado, ferramentas, Skills e tamanho do prompt do sistema), use `/context list` ou `/context detail`. Veja [Contexto](/pt-BR/concepts/context).
|
||||
|
||||
@ -55,9 +69,9 @@ Para uma análise prática (por arquivo injetado, ferramentas, Skills e tamanho
|
||||
|
||||
Use estes comandos no chat:
|
||||
|
||||
- `/status` → **cartão de status rico em emojis** com o modelo da sessão, uso de contexto,
|
||||
- `/status` → **cartão de status rico em emoji** com o modelo da sessão, uso de contexto,
|
||||
tokens de entrada/saída da última resposta e **custo estimado** (somente chave de API).
|
||||
- `/usage off|tokens|full` → adiciona um **rodapé de uso por resposta** a cada resposta.
|
||||
- `/usage off|tokens|full` → acrescenta um **rodapé de uso por resposta** a cada resposta.
|
||||
- Persiste por sessão (armazenado como `responseUsage`).
|
||||
- Autenticação OAuth **oculta o custo** (somente tokens).
|
||||
- `/usage cost` → mostra um resumo local de custos a partir dos logs de sessão do OpenClaw.
|
||||
@ -66,67 +80,64 @@ Outras superfícies:
|
||||
|
||||
- **TUI/Web TUI:** `/status` + `/usage` são compatíveis.
|
||||
- **CLI:** `openclaw status --usage` e `openclaw channels list` mostram
|
||||
janelas de cota normalizadas do provedor (`X% restantes`, não custos por resposta).
|
||||
janelas de cota normalizadas do provedor (`X% restante`, não custos por resposta).
|
||||
Provedores atuais com janela de uso: Anthropic, GitHub Copilot, Gemini CLI,
|
||||
OpenAI Codex, MiniMax, Xiaomi e z.ai.
|
||||
|
||||
As superfícies de uso normalizam aliases comuns de campos nativos do provedor antes da exibição.
|
||||
Para tráfego OpenAI-family Responses, isso inclui tanto `input_tokens` /
|
||||
`output_tokens` quanto `prompt_tokens` / `completion_tokens`, para que nomes de campos
|
||||
específicos do transporte não alterem `/status`, `/usage` ou resumos de sessão.
|
||||
O uso de JSON do Gemini CLI também é normalizado: o texto da resposta vem de `response`, e
|
||||
As superfícies de uso normalizam aliases comuns de campos nativos de provedores antes da exibição.
|
||||
Para tráfego Responses da família OpenAI, isso inclui tanto `input_tokens` /
|
||||
`output_tokens` quanto `prompt_tokens` / `completion_tokens`, de forma que nomes de campos específicos do transporte
|
||||
não alterem `/status`, `/usage` ou os resumos da sessão.
|
||||
O uso JSON do Gemini CLI também é normalizado: o texto da resposta vem de `response`, e
|
||||
`stats.cached` é mapeado para `cacheRead`, com `stats.input_tokens - stats.cached`
|
||||
usado quando a CLI omite um campo explícito `stats.input`.
|
||||
Para tráfego nativo OpenAI-family Responses, aliases de uso em WebSocket/SSE são
|
||||
normalizados da mesma forma, e os totais usam como fallback entrada + saída normalizadas quando
|
||||
usado quando a CLI omite um campo `stats.input` explícito.
|
||||
Para tráfego Responses nativo da família OpenAI, aliases de uso de WebSocket/SSE são
|
||||
normalizados da mesma forma, e os totais recorrem a entrada + saída normalizadas quando
|
||||
`total_tokens` está ausente ou é `0`.
|
||||
Quando o snapshot da sessão atual é esparso, `/status` e `session_status` também podem
|
||||
recuperar contadores de tokens/cache e o rótulo do modelo de runtime ativo do log de uso
|
||||
da transcrição mais recente. Valores ativos não zero existentes ainda têm precedência sobre
|
||||
valores de fallback da transcrição, e totais maiores da transcrição orientados a prompt
|
||||
recuperar contadores de tokens/cache e o rótulo do modelo de runtime ativo do log de uso da transcrição mais recente. Valores ativos diferentes de zero ainda têm precedência sobre valores de fallback da transcrição, e totais de transcrição maiores orientados a prompt
|
||||
podem prevalecer quando os totais armazenados estão ausentes ou são menores.
|
||||
A autenticação de uso para janelas de cota do provedor vem de hooks específicos do provedor quando
|
||||
disponíveis; caso contrário, o OpenClaw usa como fallback a correspondência de credenciais OAuth/chave de API
|
||||
disponíveis; caso contrário, o OpenClaw recorre à correspondência de credenciais OAuth/chave de API
|
||||
de perfis de autenticação, env ou config.
|
||||
|
||||
## Estimativa de custo (quando exibida)
|
||||
|
||||
Os custos são estimados a partir da configuração de preços do seu modelo:
|
||||
Os custos são estimados com base na sua configuração de preços do modelo:
|
||||
|
||||
```
|
||||
models.providers.<provider>.models[].cost
|
||||
```
|
||||
|
||||
Esses valores são **USD por 1M de tokens** para `input`, `output`, `cacheRead` e
|
||||
`cacheWrite`. Se o preço estiver ausente, o OpenClaw mostrará apenas os tokens. Tokens OAuth
|
||||
nunca mostram custo em dólar.
|
||||
`cacheWrite`. Se o preço estiver ausente, o OpenClaw mostrará apenas tokens. Tokens OAuth
|
||||
nunca mostram custo em dólares.
|
||||
|
||||
## Impacto de TTL de cache e poda
|
||||
## Impacto do TTL de cache e da poda
|
||||
|
||||
O cache de prompt do provedor só se aplica dentro da janela de TTL do cache. O OpenClaw pode
|
||||
executar opcionalmente a **poda por cache-ttl**: ele poda a sessão assim que o TTL do cache
|
||||
expira e, em seguida, redefine a janela de cache para que solicitações subsequentes possam reutilizar o
|
||||
contexto recém-cacheado em vez de colocar todo o histórico em cache novamente. Isso mantém os custos
|
||||
de escrita em cache mais baixos quando uma sessão fica ociosa além do TTL.
|
||||
executar opcionalmente **cache-ttl pruning**: ele faz a poda da sessão quando o TTL do cache
|
||||
expira e então redefine a janela de cache para que solicitações subsequentes possam reutilizar
|
||||
o contexto recém-cacheado em vez de recachear o histórico completo. Isso mantém os custos de
|
||||
gravação em cache mais baixos quando uma sessão fica ociosa além do TTL.
|
||||
|
||||
Configure isso em [Configuração do Gateway](/pt-BR/gateway/configuration) e veja os
|
||||
detalhes do comportamento em [Poda de sessão](/pt-BR/concepts/session-pruning).
|
||||
|
||||
Heartbeat pode manter o cache **aquecido** durante intervalos de inatividade. Se o TTL do cache
|
||||
do seu modelo for `1h`, definir o intervalo de heartbeat logo abaixo disso (por exemplo, `55m`) pode evitar
|
||||
recolocar todo o prompt em cache, reduzindo os custos de escrita em cache.
|
||||
O Heartbeat pode manter o cache **aquecido** durante períodos de inatividade. Se o TTL de cache
|
||||
do seu modelo for `1h`, definir o intervalo de Heartbeat um pouco abaixo disso (por exemplo, `55m`) pode evitar
|
||||
o recacheamento do prompt completo, reduzindo os custos de gravação em cache.
|
||||
|
||||
Em configurações multiagente, você pode manter uma configuração de modelo compartilhada e ajustar o comportamento
|
||||
de cache por agente com `agents.list[].params.cacheRetention`.
|
||||
Em configurações com vários agentes, você pode manter uma configuração de modelo compartilhada e ajustar o comportamento do cache
|
||||
por agente com `agents.list[].params.cacheRetention`.
|
||||
|
||||
Para um guia completo de cada ajuste, veja [Prompt Caching](/pt-BR/reference/prompt-caching).
|
||||
Para um guia completo parâmetro por parâmetro, veja [Prompt Caching](/pt-BR/reference/prompt-caching).
|
||||
|
||||
Para preços da API Anthropic, leituras de cache são significativamente mais baratas do que
|
||||
tokens de entrada, enquanto gravações em cache são cobradas com um multiplicador maior. Veja os preços
|
||||
de prompt caching da Anthropic para as taxas e multiplicadores de TTL mais recentes:
|
||||
Para preços da API Anthropic, leituras de cache são significativamente mais baratas que
|
||||
tokens de entrada, enquanto gravações em cache são cobradas com um multiplicador maior. Veja os preços de prompt caching da Anthropic para as tarifas e multiplicadores de TTL mais recentes:
|
||||
[https://docs.anthropic.com/docs/build-with-claude/prompt-caching](https://docs.anthropic.com/docs/build-with-claude/prompt-caching)
|
||||
|
||||
### Exemplo: manter cache de 1h aquecido com heartbeat
|
||||
### Exemplo: manter o cache de 1h aquecido com Heartbeat
|
||||
|
||||
```yaml
|
||||
agents:
|
||||
@ -151,7 +162,7 @@ agents:
|
||||
models:
|
||||
"anthropic/claude-opus-4-6":
|
||||
params:
|
||||
cacheRetention: "long" # linha de base padrão para a maioria dos agentes
|
||||
cacheRetention: "long" # baseline padrão para a maioria dos agentes
|
||||
list:
|
||||
- id: "research"
|
||||
default: true
|
||||
@ -162,13 +173,13 @@ agents:
|
||||
cacheRetention: "none" # evita gravações em cache para notificações intermitentes
|
||||
```
|
||||
|
||||
`agents.list[].params` é mesclado sobre `params` do modelo selecionado, então você pode
|
||||
`agents.list[].params` é mesclado sobre os `params` do modelo selecionado, então você pode
|
||||
substituir apenas `cacheRetention` e herdar os outros padrões do modelo sem alterações.
|
||||
|
||||
### Exemplo: habilitar o cabeçalho beta de contexto 1M da Anthropic
|
||||
### Exemplo: ativar o cabeçalho beta de contexto 1M da Anthropic
|
||||
|
||||
A janela de contexto de 1M da Anthropic atualmente é controlada por beta. O OpenClaw pode injetar o
|
||||
valor `anthropic-beta` necessário quando você habilita `context1m` em modelos Opus
|
||||
valor `anthropic-beta` necessário quando você ativa `context1m` em modelos Opus
|
||||
ou Sonnet compatíveis.
|
||||
|
||||
```yaml
|
||||
@ -182,7 +193,7 @@ agents:
|
||||
|
||||
Isso é mapeado para o cabeçalho beta `context-1m-2025-08-07` da Anthropic.
|
||||
|
||||
Isso só se aplica quando `context1m: true` está definido nessa entrada de modelo.
|
||||
Isso só se aplica quando `context1m: true` está definido nessa entrada do modelo.
|
||||
|
||||
Requisito: a credencial deve ser elegível para uso de contexto longo. Caso contrário,
|
||||
a Anthropic responde com um erro de limite de taxa do lado do provedor para essa solicitação.
|
||||
@ -194,9 +205,9 @@ rejeita essa combinação com HTTP 401.
|
||||
## Dicas para reduzir a pressão de tokens
|
||||
|
||||
- Use `/compact` para resumir sessões longas.
|
||||
- Corte saídas grandes de ferramentas nos seus fluxos de trabalho.
|
||||
- Reduza `agents.defaults.imageMaxDimensionPx` para sessões com muitas capturas de tela.
|
||||
- Reduza grandes saídas de ferramentas nos seus fluxos de trabalho.
|
||||
- Diminua `agents.defaults.imageMaxDimensionPx` para sessões com muitas capturas de tela.
|
||||
- Mantenha descrições de Skills curtas (a lista de Skills é injetada no prompt).
|
||||
- Prefira modelos menores para trabalho exploratório e verboso.
|
||||
|
||||
Veja [Skills](/pt-BR/tools/skills) para a fórmula exata de overhead da lista de Skills.
|
||||
Veja [Skills](/pt-BR/tools/skills) para a fórmula exata de sobrecarga da lista de Skills.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user