From a491ec7f19bf31635d0290d0b805fe34d365ceaa Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sun, 12 Apr 2026 05:36:48 +0000 Subject: [PATCH] chore(i18n): refresh pt-BR translations --- docs/pt-BR/automation/cron-jobs.md | 168 ++-- docs/pt-BR/concepts/active-memory.md | 248 ++--- docs/pt-BR/concepts/system-prompt.md | 108 ++- docs/pt-BR/plugins/architecture.md | 1056 +++++++++++----------- docs/pt-BR/plugins/manifest.md | 395 ++++---- docs/pt-BR/reference/templates/AGENTS.md | 137 +-- docs/pt-BR/reference/token-use.md | 122 +-- 7 files changed, 1163 insertions(+), 1071 deletions(-) diff --git a/docs/pt-BR/automation/cron-jobs.md b/docs/pt-BR/automation/cron-jobs.md index 9feea645c..b6d56a1b2 100644 --- a/docs/pt-BR/automation/cron-jobs.md +++ b/docs/pt-BR/automation/cron-jobs.md @@ -6,10 +6,10 @@ read_when: summary: Tarefas agendadas, webhooks e gatilhos do Gmail PubSub para o agendador do Gateway title: Tarefas agendadas x-i18n: - generated_at: "2026-04-11T02:44:19Z" + generated_at: "2026-04-12T05:33:09Z" model: gpt-5.4 provider: openai - source_hash: 04d94baa152de17d78515f7d545f099fe4810363ab67e06b465e489737f54665 + source_hash: f42bcaeedd0595d025728d7f236a724a0ebc67b6813c57233f4d739b3088317f source_path: automation/cron-jobs.md workflow: 15 --- @@ -21,7 +21,7 @@ Cron é o agendador integrado do Gateway. Ele persiste tarefas, ativa o agente n ## Início rápido ```bash -# Add a one-shot reminder +# Adicione um lembrete de execução única openclaw cron add \ --name "Reminder" \ --at "2026-02-01T16:00:00Z" \ @@ -30,94 +30,106 @@ openclaw cron add \ --wake now \ --delete-after-run -# Check your jobs +# Verifique suas tarefas openclaw cron list -# See run history +# Veja o histórico de execuções openclaw cron runs --id ``` ## Como o cron funciona -- O cron é executado **dentro do processo do Gateway** (não dentro do modelo). -- As tarefas persistem em `~/.openclaw/cron/jobs.json`, para que reinicializações não percam os agendamentos. +- O cron é executado **dentro do processo Gateway** (não dentro do modelo). +- As tarefas persistem em `~/.openclaw/cron/jobs.json`, então reinicializações não fazem os agendamentos se perderem. - Todas as execuções do cron criam registros de [tarefa em segundo plano](/pt-BR/automation/tasks). - Tarefas de execução única (`--at`) são excluídas automaticamente após sucesso por padrão. -- Execuções isoladas do cron fecham, em regime best-effort, abas/processos de navegador rastreados para a sessão `cron:` quando a execução é concluída, para que a automação de navegador destacada não deixe processos órfãos para trás. -- Execuções isoladas do cron também protegem contra respostas de confirmação obsoletas. Se o primeiro resultado for apenas uma atualização de status provisória (`on it`, `pulling everything together` e indicações semelhantes) e nenhuma execução descendente de subagente ainda for responsável pela resposta final, o OpenClaw faz um novo prompt uma vez para obter o resultado real antes da entrega. +- Execuções isoladas de cron fazem, em caráter best-effort, o fechamento de abas/processos de navegador rastreados para a sessão `cron:` quando a execução é concluída, para que automações de navegador destacadas não deixem processos órfãos. +- Execuções isoladas de cron também se protegem contra respostas de confirmação obsoletas. Se o primeiro resultado for apenas uma atualização de status intermediária (`on it`, `pulling everything together` e dicas semelhantes) e nenhuma execução descendente de subagente ainda for responsável pela resposta final, o OpenClaw faz um novo prompt uma vez para obter o resultado real antes da entrega. -A reconciliação de tarefas para o cron é de propriedade do runtime: uma tarefa ativa de cron permanece ativa enquanto o runtime do cron ainda rastrear essa tarefa como em execução, mesmo que uma linha antiga de sessão filha ainda exista. -Quando o runtime deixa de ser responsável pela tarefa e a janela de tolerância de 5 minutos expira, a manutenção pode marcar a tarefa como `lost`. +A reconciliação de tarefas para o cron pertence ao runtime: uma tarefa ativa de cron permanece ativa enquanto o runtime do cron ainda rastrear essa tarefa como em execução, mesmo que uma linha antiga de sessão filha ainda exista. +Assim que o runtime deixar de ser responsável pela tarefa e a janela de tolerância de 5 minutos expirar, a manutenção poderá marcar a tarefa como `lost`. ## Tipos de agendamento -| Tipo | Flag da CLI | Descrição | -| ------- | ----------- | ------------------------------------------------------------- | +| Tipo | Flag da CLI | Descrição | +| ------- | ----------- | ---------------------------------------------------------- | | `at` | `--at` | Timestamp de execução única (ISO 8601 ou relativo como `20m`) | -| `every` | `--every` | Intervalo fixo | -| `cron` | `--cron` | Expressão cron de 5 ou 6 campos com `--tz` opcional | +| `every` | `--every` | Intervalo fixo | +| `cron` | `--cron` | Expressão cron de 5 campos ou 6 campos com `--tz` opcional | -Timestamps sem fuso horário são tratados como UTC. Adicione `--tz America/New_York` para agendamento em horário local. +Timestamps sem fuso horário são tratados como UTC. Adicione `--tz America/New_York` para agendamento por horário local. Expressões recorrentes no início da hora são automaticamente escalonadas em até 5 minutos para reduzir picos de carga. Use `--exact` para forçar temporização precisa ou `--stagger 30s` para uma janela explícita. +### Dia do mês e dia da semana usam lógica OR + +As expressões cron são analisadas pelo [croner](https://github.com/Hexagon/croner). Quando os campos de dia do mês e dia da semana não são curingas, o croner faz correspondência quando **qualquer um** dos campos corresponde — não ambos. Esse é o comportamento padrão do Vixie cron. + +``` +# Pretendido: "9h da manhã no dia 15, apenas se for uma segunda-feira" +# Real: "9h da manhã em todo dia 15, E 9h da manhã em toda segunda-feira" +0 9 15 * 1 +``` + +Isso dispara ~5–6 vezes por mês em vez de 0–1 vez por mês. O OpenClaw usa aqui o comportamento OR padrão do Croner. Para exigir ambas as condições, use o modificador `+` de dia da semana do Croner (`0 9 15 * +1`) ou agende com base em um campo e valide o outro no prompt ou comando da sua tarefa. + ## Estilos de execução -| Estilo | Valor de `--session` | Executa em | Melhor para | -| --------------- | -------------------- | ------------------------ | ------------------------------ | +| Estilo | Valor de `--session` | Executa em | Melhor para | +| --------------- | -------------------- | ------------------------ | ------------------------------- | | Sessão principal | `main` | Próximo turno de heartbeat | Lembretes, eventos do sistema | -| Isolado | `isolated` | `cron:` dedicado | Relatórios, tarefas em segundo plano | -| Sessão atual | `current` | Vinculada no momento da criação | Trabalho recorrente com contexto | -| Sessão personalizada | `session:custom-id` | Sessão nomeada persistente | Fluxos de trabalho que constroem sobre o histórico | +| Isolada | `isolated` | `cron:` dedicado | Relatórios, tarefas em segundo plano | +| Sessão atual | `current` | Vinculada na criação | Trabalho recorrente com contexto | +| Sessão personalizada | `session:custom-id` | Sessão nomeada persistente | Fluxos que se baseiam no histórico | -Tarefas da **sessão principal** enfileiram um evento do sistema e opcionalmente ativam o heartbeat (`--wake now` ou `--wake next-heartbeat`). Tarefas **isoladas** executam um turno dedicado do agente com uma sessão nova. **Sessões personalizadas** (`session:xxx`) persistem o contexto entre execuções, permitindo fluxos de trabalho como resumos diários que se baseiam em resumos anteriores. +Tarefas da **sessão principal** enfileiram um evento do sistema e opcionalmente ativam o heartbeat (`--wake now` ou `--wake next-heartbeat`). Tarefas **isoladas** executam um turno dedicado do agente com uma sessão nova. **Sessões personalizadas** (`session:xxx`) persistem contexto entre execuções, permitindo fluxos como reuniões diárias que se baseiam em resumos anteriores. -Para tarefas isoladas, o encerramento do runtime agora inclui limpeza de navegador em regime best-effort para essa sessão de cron. Falhas de limpeza são ignoradas para que o resultado real do cron continue prevalecendo. +Para tarefas isoladas, o encerramento do runtime agora inclui limpeza best-effort do navegador para essa sessão de cron. Falhas de limpeza são ignoradas para que o resultado real do cron ainda prevaleça. -Quando execuções isoladas do cron orquestram subagentes, a entrega também prefere a saída final descendente em vez de texto provisório obsoleto do pai. Se os descendentes ainda estiverem em execução, o OpenClaw suprime essa atualização parcial do pai em vez de anunciá-la. +Quando execuções isoladas de cron orquestram subagentes, a entrega também prefere a saída final descendente em vez de texto intermediário obsoleto do pai. Se descendentes ainda estiverem em execução, o OpenClaw suprime essa atualização parcial do pai em vez de anunciá-la. ### Opções de payload para tarefas isoladas -- `--message`: texto do prompt (obrigatório para isolado) -- `--model` / `--thinking`: substituições de modelo e nível de raciocínio -- `--light-context`: pula a injeção de arquivos de bootstrap do workspace +- `--message`: texto do prompt (obrigatório para isolada) +- `--model` / `--thinking`: substituições de modelo e nível de thinking +- `--light-context`: ignora a injeção do arquivo de bootstrap do workspace - `--tools exec,read`: restringe quais ferramentas a tarefa pode usar -`--model` usa o modelo permitido selecionado para essa tarefa. Se o modelo solicitado não for permitido, o cron registra um aviso e volta para a seleção de modelo do agente/padrão da tarefa. Cadeias de fallback configuradas ainda se aplicam, mas uma substituição simples de modelo sem lista explícita de fallback por tarefa não acrescenta mais o modelo primário do agente como um destino extra oculto de nova tentativa. +`--model` usa o modelo permitido selecionado para essa tarefa. Se o modelo solicitado não for permitido, o cron registra um aviso e volta para a seleção de modelo padrão/do agente dessa tarefa. Cadeias de fallback configuradas ainda se aplicam, mas uma substituição simples de modelo sem uma lista explícita de fallback por tarefa não acrescenta mais o primário do agente como um alvo extra oculto de nova tentativa. A precedência de seleção de modelo para tarefas isoladas é: 1. Substituição de modelo do hook do Gmail (quando a execução veio do Gmail e essa substituição é permitida) 2. `model` do payload por tarefa -3. Substituição de modelo da sessão de cron armazenada -4. Seleção de modelo do agente/padrão +3. Substituição de modelo da sessão cron armazenada +4. Seleção de modelo padrão/do agente -O modo rápido também segue a seleção ativa resolvida. Se a configuração do modelo selecionado tiver `params.fastMode`, o cron isolado usará isso por padrão. Uma substituição armazenada de `fastMode` da sessão ainda prevalece sobre a configuração em qualquer direção. +O modo rápido também segue a seleção ativa resolvida. Se a configuração do modelo selecionado tiver `params.fastMode`, o cron isolado usa isso por padrão. Uma substituição armazenada de `fastMode` da sessão ainda prevalece sobre a configuração em qualquer direção. -Se uma execução isolada atingir uma transferência ativa de troca de modelo, o cron tenta novamente com o provedor/modelo alterado e persiste essa seleção ativa antes de tentar novamente. Quando a troca também traz um novo perfil de autenticação, o cron persiste essa substituição de perfil de autenticação também. As novas tentativas são limitadas: após a tentativa inicial mais 2 novas tentativas de troca, o cron aborta em vez de entrar em loop infinito. +Se uma execução isolada atingir uma transferência ativa de troca de modelo, o cron tenta novamente com o provedor/modelo trocado e persiste essa seleção ativa antes da nova tentativa. Quando a troca também traz um novo perfil de autenticação, o cron também persiste essa substituição de perfil de autenticação. As novas tentativas são limitadas: após a tentativa inicial mais 2 novas tentativas de troca, o cron aborta em vez de entrar em loop infinito. ## Entrega e saída -| Modo | O que acontece | -| --------- | ---------------------------------------------------------- | -| `announce` | Entrega o resumo ao canal de destino (padrão para isolado) | -| `webhook` | Faz POST do payload do evento concluído para uma URL | -| `none` | Apenas interno, sem entrega | +| Modo | O que acontece | +| --------- | -------------------------------------------------------- | +| `announce` | Entrega o resumo ao canal de destino (padrão para isolada) | +| `webhook` | Envia payload do evento concluído por POST para uma URL | +| `none` | Apenas interno, sem entrega | -Use `--announce --channel telegram --to "-1001234567890"` para entrega em canal. Para tópicos de fórum do Telegram, use `-1001234567890:topic:123`. Destinos do Slack/Discord/Mattermost devem usar prefixos explícitos (`channel:`, `user:`). +Use `--announce --channel telegram --to "-1001234567890"` para entrega em canal. Para tópicos de fórum do Telegram, use `-1001234567890:topic:123`. Destinos de Slack/Discord/Mattermost devem usar prefixos explícitos (`channel:`, `user:`). -Para tarefas isoladas de propriedade do cron, o executor é responsável pelo caminho final de entrega. O agente recebe um prompt para retornar um resumo em texto simples, e esse resumo é então enviado por `announce`, `webhook` ou mantido interno para `none`. `--no-deliver` não devolve a entrega ao agente; ele mantém a execução interna. +Para tarefas isoladas sob responsabilidade do cron, o executor é responsável pelo caminho final de entrega. O agente recebe um prompt para retornar um resumo em texto simples, e esse resumo é então enviado por `announce`, `webhook` ou mantido internamente para `none`. `--no-deliver` não devolve a entrega ao agente; ele mantém a execução interna. -Se a tarefa original disser explicitamente para enviar mensagem a algum destinatário externo, o agente deve informar em sua saída quem/onde essa mensagem deve ir, em vez de tentar enviá-la diretamente. +Se a tarefa original disser explicitamente para enviar mensagem a algum destinatário externo, o agente deve indicar em sua saída quem/onde essa mensagem deve ir em vez de tentar enviá-la diretamente. As notificações de falha seguem um caminho de destino separado: - `cron.failureDestination` define um padrão global para notificações de falha. - `job.delivery.failureDestination` substitui isso por tarefa. -- Se nenhum dos dois estiver definido e a tarefa já fizer entrega por `announce`, as notificações de falha agora usam como fallback esse destino principal de anúncio. -- `delivery.failureDestination` é compatível apenas com tarefas `sessionTarget="isolated"`, a menos que o modo principal de entrega seja `webhook`. +- Se nenhum dos dois estiver definido e a tarefa já entregar via `announce`, as notificações de falha agora usam esse destino principal de anúncio como fallback. +- `delivery.failureDestination` só é compatível com tarefas `sessionTarget="isolated"` a menos que o modo principal de entrega seja `webhook`. ## Exemplos de CLI @@ -146,7 +158,7 @@ openclaw cron add \ --to "channel:C1234567890" ``` -Tarefa isolada com substituição de modelo e raciocínio: +Tarefa isolada com substituição de modelo e thinking: ```bash openclaw cron add \ @@ -162,7 +174,7 @@ openclaw cron add \ ## Webhooks -O Gateway pode expor endpoints HTTP de webhook para gatilhos externos. Habilite na configuração: +O Gateway pode expor endpoints HTTP de webhook para gatilhos externos. Ative na configuração: ```json5 { @@ -185,7 +197,7 @@ Tokens na query string são rejeitados. ### POST /hooks/wake -Enfileira um evento do sistema para a sessão principal: +Enfileire um evento do sistema para a sessão principal: ```bash curl -X POST http://127.0.0.1:18789/hooks/wake \ @@ -199,7 +211,7 @@ curl -X POST http://127.0.0.1:18789/hooks/wake \ ### POST /hooks/agent -Executa um turno isolado do agente: +Execute um turno isolado do agente: ```bash curl -X POST http://127.0.0.1:18789/hooks/agent \ @@ -219,32 +231,32 @@ Nomes de hook personalizados são resolvidos por `hooks.mappings` na configuraç - Mantenha os endpoints de hook atrás de loopback, tailnet ou proxy reverso confiável. - Use um token dedicado para hooks; não reutilize tokens de autenticação do gateway. - Mantenha `hooks.path` em um subcaminho dedicado; `/` é rejeitado. -- Defina `hooks.allowedAgentIds` para limitar o roteamento explícito por `agentId`. +- Defina `hooks.allowedAgentIds` para limitar o roteamento explícito de `agentId`. - Mantenha `hooks.allowRequestSessionKey=false`, a menos que você precise de sessões selecionadas pelo chamador. -- Se você habilitar `hooks.allowRequestSessionKey`, também defina `hooks.allowedSessionKeyPrefixes` para restringir os formatos permitidos de chave de sessão. -- Os payloads de hook são encapsulados com limites de segurança por padrão. +- Se você ativar `hooks.allowRequestSessionKey`, também defina `hooks.allowedSessionKeyPrefixes` para restringir os formatos permitidos de chave de sessão. +- Payloads de hook são encapsulados com limites de segurança por padrão. ## Integração com Gmail PubSub Conecte gatilhos da caixa de entrada do Gmail ao OpenClaw via Google PubSub. -**Pré-requisitos**: CLI `gcloud`, `gog` (gogcli), hooks do OpenClaw habilitados, Tailscale para o endpoint HTTPS público. +**Pré-requisitos**: CLI `gcloud`, `gog` (gogcli), hooks do OpenClaw ativados, Tailscale para o endpoint HTTPS público. -### Configuração com assistente (recomendado) +### Configuração pelo assistente (recomendado) ```bash openclaw webhooks gmail setup --account openclaw@gmail.com ``` -Isso grava a configuração `hooks.gmail`, habilita o preset do Gmail e usa o Tailscale Funnel para o endpoint de push. +Isso grava a configuração `hooks.gmail`, ativa a predefinição do Gmail e usa Tailscale Funnel para o endpoint de push. ### Inicialização automática do Gateway -Quando `hooks.enabled=true` e `hooks.gmail.account` estiver definido, o Gateway inicia `gog gmail watch serve` na inicialização e renova automaticamente o watch. Defina `OPENCLAW_SKIP_GMAIL_WATCHER=1` para desativar isso. +Quando `hooks.enabled=true` e `hooks.gmail.account` está definido, o Gateway inicia `gog gmail watch serve` na inicialização e renova automaticamente o watch. Defina `OPENCLAW_SKIP_GMAIL_WATCHER=1` para desativar isso. ### Configuração manual única -1. Selecione o projeto do GCP que é dono do cliente OAuth usado por `gog`: +1. Selecione o projeto do GCP que possui o cliente OAuth usado por `gog`: ```bash gcloud auth login @@ -252,7 +264,7 @@ gcloud config set project gcloud services enable gmail.googleapis.com pubsub.googleapis.com ``` -2. Crie o tópico e conceda ao Gmail acesso de push: +2. Crie o tópico e conceda acesso de push do Gmail: ```bash gcloud pubsub topics create gog-gmail-watch @@ -283,28 +295,28 @@ gog gmail watch start \ } ``` -## Gerenciamento de tarefas +## Gerenciando tarefas ```bash -# List all jobs +# Liste todas as tarefas openclaw cron list -# Edit a job +# Edite uma tarefa openclaw cron edit --message "Updated prompt" --model "opus" -# Force run a job now +# Force a execução de uma tarefa agora openclaw cron run -# Run only if due +# Execute apenas se estiver vencida openclaw cron run --due -# View run history +# Veja o histórico de execuções openclaw cron runs --id --limit 50 -# Delete a job +# Exclua uma tarefa openclaw cron remove -# Agent selection (multi-agent setups) +# Seleção de agente (configurações com múltiplos agentes) openclaw cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --message "Check ops queue" --agent ops openclaw cron edit --clear-agent ``` @@ -312,9 +324,9 @@ openclaw cron edit --clear-agent Observação sobre substituição de modelo: - `openclaw cron add|edit --model ...` altera o modelo selecionado da tarefa. -- Se o modelo for permitido, exatamente esse provedor/modelo chega à execução isolada do agente. -- Se não for permitido, o cron emite um aviso e volta para a seleção de modelo do agente/padrão da tarefa. -- Cadeias de fallback configuradas ainda se aplicam, mas uma substituição simples com `--model` sem lista explícita de fallback por tarefa não recai mais para o primário do agente como um destino extra silencioso de nova tentativa. +- Se o modelo for permitido, exatamente esse provedor/modelo chega à execução do agente isolado. +- Se não for permitido, o cron emite um aviso e retorna para a seleção de modelo padrão/do agente da tarefa. +- Cadeias de fallback configuradas ainda se aplicam, mas uma substituição simples com `--model` sem uma lista explícita de fallback por tarefa não recai mais para o modelo primário do agente como um alvo extra silencioso de nova tentativa. ## Configuração @@ -329,7 +341,7 @@ Observação sobre substituição de modelo: backoffMs: [60000, 120000, 300000], retryOn: ["rate_limit", "overloaded", "network", "server_error"], }, - webhookToken: "substitua-por-um-token-dedicado-para-webhook", + webhookToken: "replace-with-dedicated-webhook-token", sessionRetention: "24h", runLog: { maxBytes: "2mb", keepLines: 2000 }, }, @@ -338,15 +350,15 @@ Observação sobre substituição de modelo: Desative o cron: `cron.enabled: false` ou `OPENCLAW_SKIP_CRON=1`. -**Nova tentativa para execução única**: erros transitórios (limite de taxa, sobrecarga, rede, erro de servidor) tentam novamente até 3 vezes com backoff exponencial. Erros permanentes desativam imediatamente. +**Nova tentativa de execução única**: erros transitórios (limite de taxa, sobrecarga, rede, erro de servidor) tentam novamente até 3 vezes com backoff exponencial. Erros permanentes desativam imediatamente. **Nova tentativa recorrente**: backoff exponencial (30s a 60m) entre novas tentativas. O backoff é redefinido após a próxima execução bem-sucedida. -**Manutenção**: `cron.sessionRetention` (padrão `24h`) remove entradas de sessão de execuções isoladas. `cron.runLog.maxBytes` / `cron.runLog.keepLines` removem automaticamente arquivos de log de execução. +**Manutenção**: `cron.sessionRetention` (padrão `24h`) remove entradas de sessão de execuções isoladas. `cron.runLog.maxBytes` / `cron.runLog.keepLines` fazem poda automática dos arquivos de log de execução. ## Solução de problemas -### Escada de comandos +### Sequência de comandos ```bash openclaw status @@ -362,19 +374,19 @@ openclaw doctor ### O cron não dispara - Verifique `cron.enabled` e a variável de ambiente `OPENCLAW_SKIP_CRON`. -- Confirme que o Gateway está em execução contínua. -- Para agendamentos `cron`, verifique o fuso horário (`--tz`) em relação ao fuso do host. -- `reason: not-due` na saída da execução significa que a execução manual foi verificada com `openclaw cron run --due` e que a tarefa ainda não estava vencida. +- Confirme se o Gateway está em execução contínua. +- Para agendamentos `cron`, verifique o fuso horário (`--tz`) em relação ao fuso horário do host. +- `reason: not-due` na saída da execução significa que a execução manual foi verificada com `openclaw cron run --due` e a tarefa ainda não estava vencida. ### O cron disparou, mas não houve entrega - Modo de entrega `none` significa que nenhuma mensagem externa é esperada. - Destino de entrega ausente/inválido (`channel`/`to`) significa que a saída foi ignorada. - Erros de autenticação do canal (`unauthorized`, `Forbidden`) significam que a entrega foi bloqueada pelas credenciais. -- Se a execução isolada retornar apenas o token silencioso (`NO_REPLY` / `no_reply`), o OpenClaw suprime a entrega de saída direta e também suprime o caminho de fallback de resumo enfileirado, portanto nada é publicado de volta no chat. -- Para tarefas isoladas de propriedade do cron, não espere que o agente use a ferramenta de mensagem como fallback. O executor é responsável pela entrega final; `--no-deliver` a mantém interna em vez de permitir um envio direto. +- Se a execução isolada retornar apenas o token silencioso (`NO_REPLY` / `no_reply`), o OpenClaw suprime a entrega direta para saída externa e também suprime o caminho de fallback do resumo enfileirado, então nada é publicado de volta no chat. +- Para tarefas isoladas controladas pelo cron, não espere que o agente use a ferramenta de mensagem como fallback. O executor é responsável pela entrega final; `--no-deliver` a mantém interna em vez de permitir um envio direto. -### Armadilhas com fuso horário +### Cuidados com fuso horário - Cron sem `--tz` usa o fuso horário do host do gateway. - Agendamentos `at` sem fuso horário são tratados como UTC. @@ -382,7 +394,7 @@ openclaw doctor ## Relacionado -- [Automação e tarefas](/pt-BR/automation) — visão geral de todos os mecanismos de automação -- [Tarefas em segundo plano](/pt-BR/automation/tasks) — registro de tarefas para execuções do cron +- [Automação e tarefas](/pt-BR/automation) — todos os mecanismos de automação em um só lugar +- [Tarefas em segundo plano](/pt-BR/automation/tasks) — registro de tarefas para execuções de cron - [Heartbeat](/pt-BR/gateway/heartbeat) — turnos periódicos da sessão principal - [Fuso horário](/pt-BR/concepts/timezone) — configuração de fuso horário diff --git a/docs/pt-BR/concepts/active-memory.md b/docs/pt-BR/concepts/active-memory.md index a4f2ec64c..7d6b62dd8 100644 --- a/docs/pt-BR/concepts/active-memory.md +++ b/docs/pt-BR/concepts/active-memory.md @@ -3,28 +3,34 @@ read_when: - Você quer entender para que serve a memória ativa - Você quer ativar a memória ativa para um agente conversacional - Você quer ajustar o comportamento da memória ativa sem ativá-la em todos os lugares -summary: Um subagente de memória com bloqueio controlado pelo plugin que injeta memória relevante em sessões de chat interativas +summary: Um subagente de memória de bloqueio controlado pelo plugin que injeta memória relevante em sessões de chat interativas title: Memória ativa x-i18n: - generated_at: "2026-04-11T05:18:06Z" + generated_at: "2026-04-12T05:33:10Z" model: gpt-5.4 provider: openai - source_hash: e8b0e6539e09678e9e8def68795f8bcb992f98509423da3da3123eda88ec1dd5 + source_hash: 59456805c28daaab394ba2a7f87e1104a1334a5cf32dbb961d5d232d9c471d84 source_path: concepts/active-memory.md workflow: 15 --- # Memória ativa -A memória ativa é um subagente de memória opcional, com bloqueio e controlado por plugin, que é executado antes da resposta principal em sessões conversacionais qualificadas. +A memória ativa é um subagente opcional de memória de bloqueio controlado pelo plugin que é executado +antes da resposta principal em sessões conversacionais elegíveis. -Ela existe porque a maioria dos sistemas de memória é capaz, mas reativa. Eles dependem do agente principal para decidir quando pesquisar a memória, ou do usuário para dizer coisas como "lembre-se disso" ou "pesquise na memória". Nessa altura, o momento em que a memória teria tornado a resposta mais natural já passou. +Ela existe porque a maioria dos sistemas de memória é capaz, mas reativa. Eles dependem de +o agente principal decidir quando pesquisar a memória, ou de o usuário dizer coisas +como "lembre-se disso" ou "pesquise na memória". Quando isso acontece, o momento em que a memória +teria feito a resposta parecer natural já passou. -A memória ativa dá ao sistema uma chance limitada de trazer à tona memória relevante antes que a resposta principal seja gerada. +A memória ativa dá ao sistema uma chance limitada de trazer memória relevante +antes que a resposta principal seja gerada. ## Cole isto no seu agente -Cole isto no seu agente se quiser ativar a Memória ativa com uma configuração autônoma e segura por padrão: +Cole isto no seu agente se quiser habilitar a Memória ativa com uma +configuração autocontida e segura por padrão: ```json5 { @@ -36,7 +42,7 @@ Cole isto no seu agente se quiser ativar a Memória ativa com uma configuração enabled: true, agents: ["main"], allowedChatTypes: ["direct"], - modelFallbackPolicy: "default-remote", + modelFallback: "google/gemini-3-flash", queryMode: "recent", promptStyle: "balanced", timeoutMs: 15000, @@ -50,7 +56,9 @@ Cole isto no seu agente se quiser ativar a Memória ativa com uma configuração } ``` -Isso ativa o plugin para o agente `main`, mantém seu uso limitado a sessões no estilo de mensagem direta por padrão, permite que ele herde primeiro o modelo da sessão atual e ainda permite o fallback remoto integrado caso nenhum modelo explícito ou herdado esteja disponível. +Isso ativa o plugin para o agente `main`, o mantém limitado a sessões +no estilo de mensagem direta por padrão, permite que ele herde primeiro o modelo da sessão atual +e usa o modelo de fallback configurado apenas se nenhum modelo explícito ou herdado estiver disponível. Depois disso, reinicie o gateway: @@ -58,19 +66,19 @@ Depois disso, reinicie o gateway: openclaw gateway ``` -Para inspecioná-la ao vivo em uma conversa: +Para inspecioná-lo ao vivo em uma conversa: ```text /verbose on ``` -## Ativar a memória ativa +## Ative a memória ativa A configuração mais segura é: -1. ativar o plugin +1. habilitar o plugin 2. direcioná-lo para um agente conversacional -3. manter o logging ativado apenas durante o ajuste +3. manter o registro ativado apenas durante o ajuste Comece com isto em `openclaw.json`: @@ -83,7 +91,7 @@ Comece com isto em `openclaw.json`: config: { agents: ["main"], allowedChatTypes: ["direct"], - modelFallbackPolicy: "default-remote", + modelFallback: "google/gemini-3-flash", queryMode: "recent", promptStyle: "balanced", timeoutMs: 15000, @@ -97,7 +105,7 @@ Comece com isto em `openclaw.json`: } ``` -Em seguida, reinicie o gateway: +Depois reinicie o gateway: ```bash openclaw gateway @@ -106,20 +114,22 @@ openclaw gateway O que isso significa: - `plugins.entries.active-memory.enabled: true` ativa o plugin -- `config.agents: ["main"]` habilita a memória ativa apenas para o agente `main` -- `config.allowedChatTypes: ["direct"]` mantém a memória ativa habilitada por padrão apenas para sessões no estilo de mensagem direta -- se `config.model` não estiver definido, a memória ativa primeiro herda o modelo da sessão atual -- `config.modelFallbackPolicy: "default-remote"` mantém o fallback remoto integrado como padrão quando nenhum modelo explícito ou herdado está disponível +- `config.agents: ["main"]` habilita memória ativa apenas para o agente `main` +- `config.allowedChatTypes: ["direct"]` mantém a memória ativa habilitada apenas para sessões no estilo de mensagem direta por padrão +- se `config.model` não estiver definido, a memória ativa herda primeiro o modelo da sessão atual +- `config.modelFallback` opcionalmente fornece seu próprio provedor/modelo de fallback para recuperação - `config.promptStyle: "balanced"` usa o estilo de prompt padrão de uso geral para o modo `recent` -- a memória ativa ainda é executada apenas em sessões de chat persistentes e interativas qualificadas +- a memória ativa ainda é executada apenas em sessões de chat interativas persistentes elegíveis ## Como vê-la -A memória ativa injeta contexto oculto de sistema para o modelo. Ela não expõe tags brutas `...` ao cliente. +A memória ativa injeta contexto de sistema oculto para o modelo. Ela não expõe +tags brutas `...` ao cliente. ## Alternância por sessão -Use o comando do plugin quando quiser pausar ou retomar a memória ativa para a sessão de chat atual sem editar a configuração: +Use o comando do plugin quando quiser pausar ou retomar a memória ativa para a +sessão de chat atual sem editar a configuração: ```text /active-memory status @@ -127,9 +137,9 @@ Use o comando do plugin quando quiser pausar ou retomar a memória ativa para a /active-memory on ``` -Isso vale apenas para a sessão. Não altera -`plugins.entries.active-memory.enabled`, o direcionamento por agente nem outras -configurações globais. +Isso é restrito à sessão. Não altera +`plugins.entries.active-memory.enabled`, o direcionamento do agente nem outra +configuração global. Se quiser que o comando grave a configuração e pause ou retome a memória ativa para todas as sessões, use a forma global explícita: @@ -142,7 +152,7 @@ todas as sessões, use a forma global explícita: A forma global grava `plugins.entries.active-memory.config.enabled`. Ela mantém `plugins.entries.active-memory.enabled` ativado para que o comando continue disponível para -reativar a memória ativa mais tarde. +reativar a memória ativa depois. Se quiser ver o que a memória ativa está fazendo em uma sessão ao vivo, ative o modo verbose para essa sessão: @@ -156,11 +166,11 @@ Com o verbose ativado, o OpenClaw pode mostrar: - uma linha de status da memória ativa, como `Active Memory: ok 842ms recent 34 chars` - um resumo de depuração legível, como `Active Memory Debug: Lemon pepper wings with blue cheese.` -Essas linhas são derivadas da mesma execução da memória ativa que alimenta o contexto +Essas linhas são derivadas da mesma passagem de memória ativa que alimenta o contexto oculto do sistema, mas são formatadas para humanos em vez de expor marcação bruta do prompt. -Por padrão, a transcrição do subagente de memória com bloqueio é temporária e excluída -após a conclusão da execução. +Por padrão, a transcrição do subagente de memória de bloqueio é temporária e é excluída +depois que a execução é concluída. Fluxo de exemplo: @@ -180,13 +190,14 @@ Formato de resposta visível esperado: ## Quando ela é executada -A memória ativa usa duas barreiras: +A memória ativa usa dois critérios: -1. **Opt-in de configuração** - O plugin deve estar ativado, e o id do agente atual deve aparecer em +1. **Adesão via configuração** + O plugin deve estar habilitado, e o id do agente atual deve aparecer em `plugins.entries.active-memory.config.agents`. -2. **Qualificação estrita em tempo de execução** - Mesmo quando ativada e direcionada, a memória ativa só é executada em sessões de chat persistentes e interativas qualificadas. +2. **Elegibilidade estrita em tempo de execução** + Mesmo quando habilitada e direcionada, a memória ativa é executada apenas em + sessões de chat interativas persistentes elegíveis. A regra real é: @@ -202,12 +213,11 @@ eligible interactive persistent chat session active memory runs ``` -Se qualquer uma dessas condições falhar, a memória ativa não será executada. +Se qualquer um desses falhar, a memória ativa não será executada. ## Tipos de sessão -`config.allowedChatTypes` controla quais tipos de conversa podem executar a Memória -ativa. +`config.allowedChatTypes` controla em que tipos de conversa a Memória ativa pode ser executada. O padrão é: @@ -215,8 +225,8 @@ O padrão é: allowedChatTypes: ["direct"] ``` -Isso significa que a Memória ativa é executada por padrão em sessões no estilo de -mensagem direta, mas não em sessões de grupo ou canal, a menos que você as habilite explicitamente. +Isso significa que a Memória ativa é executada por padrão em sessões no estilo de mensagem direta, mas +não em sessões de grupo ou canal, a menos que você as habilite explicitamente. Exemplos: @@ -235,16 +245,16 @@ allowedChatTypes: ["direct", "group", "channel"] ## Onde ela é executada A memória ativa é um recurso de enriquecimento conversacional, não um recurso de -inferência para toda a plataforma. +inferência em toda a plataforma. | Superfície | Executa memória ativa? | | ------------------------------------------------------------------- | ------------------------------------------------------- | -| Control UI / sessões persistentes do chat na web | Sim, se o plugin estiver ativado e o agente for direcionado | -| Outras sessões interativas de canal no mesmo caminho de chat persistente | Sim, se o plugin estiver ativado e o agente for direcionado | -| Execuções headless de uso único | Não | -| Execuções de heartbeat/em segundo plano | Não | +| Sessões persistentes da Control UI / chat web | Sim, se o plugin estiver habilitado e o agente for direcionado | +| Outras sessões de canal interativas no mesmo caminho de chat persistente | Sim, se o plugin estiver habilitado e o agente for direcionado | +| Execuções avulsas sem interface | Não | +| Execuções de heartbeat/background | Não | | Caminhos internos genéricos de `agent-command` | Não | -| Execução de subagente/helper interno | Não | +| Execução de subagente/auxiliar interno | Não | ## Por que usá-la @@ -260,14 +270,14 @@ Ela funciona especialmente bem para: - hábitos recorrentes - contexto de longo prazo do usuário que deve surgir naturalmente -Ela é pouco adequada para: +Ela é uma escolha ruim para: - automação - workers internos -- tarefas de API de uso único +- tarefas de API avulsas - lugares em que personalização oculta seria surpreendente -## Como ela funciona +## Como funciona O formato em tempo de execução é: @@ -280,7 +290,7 @@ flowchart LR I --> M["Main Reply"] ``` -O subagente de memória com bloqueio pode usar apenas: +O subagente de memória de bloqueio pode usar apenas: - `memory_search` - `memory_get` @@ -289,19 +299,19 @@ Se a conexão estiver fraca, ele deve retornar `NONE`. ## Modos de consulta -`config.queryMode` controla quanto da conversa o subagente de memória com bloqueio vê. +`config.queryMode` controla quanto da conversa o subagente de memória de bloqueio vê. ## Estilos de prompt -`config.promptStyle` controla o quão disposto ou rigoroso o subagente de memória com bloqueio é +`config.promptStyle` controla o quão disposto ou rigoroso o subagente de memória de bloqueio é ao decidir se deve retornar memória. Estilos disponíveis: - `balanced`: padrão de uso geral para o modo `recent` -- `strict`: menos disposto; melhor quando você quer pouquíssima interferência do contexto próximo +- `strict`: menos disposto; melhor quando você quer pouquíssimo vazamento do contexto próximo - `contextual`: mais favorável à continuidade; melhor quando o histórico da conversa deve importar mais -- `recall-heavy`: mais disposto a trazer memória à tona em correspondências mais suaves, mas ainda plausíveis +- `recall-heavy`: mais disposto a trazer memória em correspondências mais leves, mas ainda plausíveis - `precision-heavy`: prefere agressivamente `NONE`, a menos que a correspondência seja óbvia - `preference-only`: otimizado para favoritos, hábitos, rotinas, gostos e fatos pessoais recorrentes @@ -321,7 +331,7 @@ Exemplo: promptStyle: "preference-only" ``` -## Política de fallback do modelo +## Política de fallback de modelo Se `config.model` não estiver definido, a Memória ativa tenta resolver um modelo nesta ordem: @@ -329,32 +339,28 @@ Se `config.model` não estiver definido, a Memória ativa tenta resolver um mode explicit plugin model -> current session model -> agent primary model --> optional built-in remote fallback +-> optional configured fallback model ``` -`config.modelFallbackPolicy` controla a última etapa. +`config.modelFallback` controla a etapa de fallback configurado. -Padrão: +Fallback personalizado opcional: ```json5 -modelFallbackPolicy: "default-remote" +modelFallback: "google/gemini-3-flash" ``` -Outra opção: +Se nenhum modelo explícito, herdado ou de fallback configurado puder ser resolvido, a Memória ativa +ignora a recuperação nesse turno. -```json5 -modelFallbackPolicy: "resolved-only" -``` +`config.modelFallbackPolicy` é mantido apenas como um campo de compatibilidade obsoleto +para configurações antigas. Ele não altera mais o comportamento em tempo de execução. -Use `resolved-only` se quiser que a Memória ativa ignore a recordação em vez de fazer -fallback para o padrão remoto integrado quando nenhum modelo explícito ou herdado -estiver disponível. +## Escapes avançados -## Válvulas de escape avançadas +Estas opções intencionalmente não fazem parte da configuração recomendada. -Essas opções intencionalmente não fazem parte da configuração recomendada. - -`config.thinking` pode substituir o nível de raciocínio do subagente de memória com bloqueio: +`config.thinking` pode substituir o nível de thinking do subagente de memória de bloqueio: ```json5 thinking: "medium" @@ -366,8 +372,8 @@ Padrão: thinking: "off" ``` -Não ative isso por padrão. A Memória ativa é executada no caminho da resposta, então o tempo extra -de raciocínio aumenta diretamente a latência visível para o usuário. +Não habilite isso por padrão. A Memória ativa é executada no caminho da resposta, então tempo +extra de thinking aumenta diretamente a latência visível para o usuário. `config.promptAppend` adiciona instruções extras do operador após o prompt padrão da Memória ativa e antes do contexto da conversa: @@ -383,22 +389,22 @@ ainda acrescenta o contexto da conversa depois: promptOverride: "You are a memory search agent. Return NONE or one compact user fact." ``` -A personalização de prompt não é recomendada, a menos que você esteja testando deliberadamente um -contrato de recordação diferente. O prompt padrão é ajustado para retornar `NONE` -ou um contexto compacto de fato do usuário para o modelo principal. +A personalização do prompt não é recomendada, a menos que você esteja testando deliberadamente um +contrato de recuperação diferente. O prompt padrão é ajustado para retornar `NONE` +ou contexto compacto de fatos do usuário para o modelo principal. ### `message` -Somente a mensagem mais recente do usuário é enviada. +Apenas a mensagem mais recente do usuário é enviada. ```text Latest user message only ``` -Use isto quando: +Use isso quando: - você quiser o comportamento mais rápido -- você quiser o viés mais forte em direção à recordação de preferências estáveis +- você quiser a maior inclinação para recuperar preferências estáveis - turnos de acompanhamento não precisarem de contexto conversacional Tempo limite recomendado: @@ -407,7 +413,7 @@ Tempo limite recomendado: ### `recent` -A mensagem mais recente do usuário mais uma pequena cauda recente da conversa são enviadas. +A mensagem mais recente do usuário mais um pequeno trecho recente da conversa são enviados. ```text Recent conversation tail: @@ -419,7 +425,7 @@ Latest user message: ... ``` -Use isto quando: +Use isso quando: - você quiser um melhor equilíbrio entre velocidade e embasamento conversacional - perguntas de acompanhamento frequentemente dependerem dos últimos turnos @@ -430,7 +436,7 @@ Tempo limite recomendado: ### `full` -A conversa completa é enviada ao subagente de memória com bloqueio. +A conversa completa é enviada ao subagente de memória de bloqueio. ```text Full conversation context: @@ -440,15 +446,15 @@ user: ... ... ``` -Use isto quando: +Use isso quando: -- a qualidade máxima de recordação importar mais do que a latência -- a conversa contiver uma preparação importante muito antes no tópico +- a melhor qualidade possível de recuperação importar mais do que a latência +- a conversa contiver preparação importante muito antes no fio Tempo limite recomendado: - aumente-o substancialmente em comparação com `message` ou `recent` -- comece em torno de `15000` ms ou mais, dependendo do tamanho do tópico +- comece em torno de `15000` ms ou mais, dependendo do tamanho do fio Em geral, o tempo limite deve aumentar com o tamanho do contexto: @@ -456,18 +462,18 @@ Em geral, o tempo limite deve aumentar com o tamanho do contexto: message < recent < full ``` -## Persistência da transcrição +## Persistência de transcrição -As execuções do subagente de memória com bloqueio da memória ativa criam uma transcrição real `session.jsonl` -durante a chamada do subagente de memória com bloqueio. +As execuções do subagente de memória de bloqueio da memória ativa criam uma transcrição real `session.jsonl` +durante a chamada do subagente de memória de bloqueio. Por padrão, essa transcrição é temporária: - ela é gravada em um diretório temporário -- ela é usada apenas para a execução do subagente de memória com bloqueio -- ela é excluída imediatamente após a conclusão da execução +- ela é usada apenas para a execução do subagente de memória de bloqueio +- ela é excluída imediatamente após o término da execução -Se quiser manter essas transcrições do subagente de memória com bloqueio em disco para depuração ou +Se você quiser manter essas transcrições do subagente de memória de bloqueio em disco para depuração ou inspeção, ative a persistência explicitamente: ```json5 @@ -487,11 +493,11 @@ inspeção, ative a persistência explicitamente: } ``` -Quando ativada, a memória ativa armazena transcrições em um diretório separado dentro da -pasta de sessões do agente de destino, e não no caminho principal de transcrição da conversa -do usuário. +Quando habilitada, a memória ativa armazena transcrições em um diretório separado dentro da +pasta de sessões do agente de destino, e não no caminho principal da transcrição +da conversa do usuário. -O layout padrão, em termos conceituais, é: +O layout padrão é conceitualmente: ```text agents//sessions/active-memory/.jsonl @@ -501,9 +507,9 @@ Você pode alterar o subdiretório relativo com `config.transcriptDir`. Use isso com cuidado: -- as transcrições do subagente de memória com bloqueio podem se acumular rapidamente em sessões movimentadas -- o modo de consulta `full` pode duplicar muito contexto de conversa -- essas transcrições contêm contexto oculto de prompt e memórias recuperadas +- as transcrições do subagente de memória de bloqueio podem se acumular rapidamente em sessões movimentadas +- o modo de consulta `full` pode duplicar muito contexto da conversa +- essas transcrições contêm contexto de prompt oculto e memórias recuperadas ## Configuração @@ -517,30 +523,30 @@ Os campos mais importantes são: | Chave | Tipo | Significado | | --------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -| `enabled` | `boolean` | Ativa o próprio plugin | +| `enabled` | `boolean` | Habilita o próprio plugin | | `config.agents` | `string[]` | IDs de agentes que podem usar memória ativa | -| `config.model` | `string` | Referência opcional do modelo do subagente de memória com bloqueio; quando não definido, a memória ativa usa o modelo da sessão atual | -| `config.queryMode` | `"message" \| "recent" \| "full"` | Controla quanto da conversa o subagente de memória com bloqueio vê | -| `config.promptStyle` | `"balanced" \| "strict" \| "contextual" \| "recall-heavy" \| "precision-heavy" \| "preference-only"` | Controla o quão disposto ou rigoroso o subagente de memória com bloqueio é ao decidir se deve retornar memória | -| `config.thinking` | `"off" \| "minimal" \| "low" \| "medium" \| "high" \| "xhigh" \| "adaptive"` | Substituição avançada de raciocínio para o subagente de memória com bloqueio; padrão `off` para velocidade | -| `config.promptOverride` | `string` | Substituição avançada completa do prompt; não recomendada para uso normal | -| `config.promptAppend` | `string` | Instruções extras avançadas anexadas ao prompt padrão ou substituído | -| `config.timeoutMs` | `number` | Tempo limite rígido para o subagente de memória com bloqueio | -| `config.maxSummaryChars` | `number` | Número máximo total de caracteres permitidos no resumo da memória ativa | +| `config.model` | `string` | Referência opcional de modelo para o subagente de memória de bloqueio; quando não definido, a memória ativa usa o modelo da sessão atual | +| `config.queryMode` | `"message" \| "recent" \| "full"` | Controla quanto da conversa o subagente de memória de bloqueio vê | +| `config.promptStyle` | `"balanced" \| "strict" \| "contextual" \| "recall-heavy" \| "precision-heavy" \| "preference-only"` | Controla o quão disposto ou rigoroso o subagente de memória de bloqueio é ao decidir se retorna memória | +| `config.thinking` | `"off" \| "minimal" \| "low" \| "medium" \| "high" \| "xhigh" \| "adaptive"` | Substituição avançada de thinking para o subagente de memória de bloqueio; padrão `off` por velocidade | +| `config.promptOverride` | `string` | Substituição avançada completa do prompt; não recomendada para uso normal | +| `config.promptAppend` | `string` | Instruções extras avançadas acrescentadas ao prompt padrão ou substituído | +| `config.timeoutMs` | `number` | Tempo limite rígido para o subagente de memória de bloqueio | +| `config.maxSummaryChars` | `number` | Total máximo de caracteres permitido no resumo da memória ativa | | `config.logging` | `boolean` | Emite logs da memória ativa durante o ajuste | -| `config.persistTranscripts` | `boolean` | Mantém as transcrições do subagente de memória com bloqueio em disco em vez de excluir arquivos temporários | -| `config.transcriptDir` | `string` | Diretório relativo das transcrições do subagente de memória com bloqueio dentro da pasta de sessões do agente | +| `config.persistTranscripts` | `boolean` | Mantém em disco as transcrições do subagente de memória de bloqueio em vez de excluir arquivos temporários | +| `config.transcriptDir` | `string` | Diretório relativo de transcrições do subagente de memória de bloqueio dentro da pasta de sessões do agente | Campos úteis para ajuste: -| Chave | Tipo | Significado | -| ----------------------------- | -------- | ----------------------------------------------------------- | -| `config.maxSummaryChars` | `number` | Número máximo total de caracteres permitidos no resumo da memória ativa | +| Chave | Tipo | Significado | +| ----------------------------- | -------- | --------------------------------------------------------------- | +| `config.maxSummaryChars` | `number` | Total máximo de caracteres permitido no resumo da memória ativa | | `config.recentUserTurns` | `number` | Turnos anteriores do usuário a incluir quando `queryMode` for `recent` | | `config.recentAssistantTurns` | `number` | Turnos anteriores do assistente a incluir quando `queryMode` for `recent` | -| `config.recentUserChars` | `number` | Máximo de caracteres por turno recente do usuário | -| `config.recentAssistantChars` | `number` | Máximo de caracteres por turno recente do assistente | -| `config.cacheTtlMs` | `number` | Reutilização de cache para consultas idênticas repetidas | +| `config.recentUserChars` | `number` | Máximo de caracteres por turno recente do usuário | +| `config.recentAssistantChars` | `number` | Máximo de caracteres por turno recente do assistente | +| `config.cacheTtlMs` | `number` | Reutilização de cache para consultas idênticas repetidas | ## Configuração recomendada @@ -566,25 +572,25 @@ Comece com `recent`. } ``` -Se quiser inspecionar o comportamento em tempo real durante o ajuste, use `/verbose on` na +Se você quiser inspecionar o comportamento ao vivo durante o ajuste, use `/verbose on` na sessão em vez de procurar um comando de depuração separado da memória ativa. -Depois passe para: +Depois, mude para: - `message` se quiser menor latência -- `full` se decidir que contexto extra vale o subagente de memória com bloqueio mais lento +- `full` se decidir que o contexto extra vale o subagente de memória de bloqueio mais lento ## Depuração Se a memória ativa não estiver aparecendo onde você espera: -1. Confirme que o plugin está ativado em `plugins.entries.active-memory.enabled`. +1. Confirme que o plugin está habilitado em `plugins.entries.active-memory.enabled`. 2. Confirme que o ID do agente atual está listado em `config.agents`. -3. Confirme que você está testando por meio de uma sessão de chat persistente e interativa. +3. Confirme que você está testando por meio de uma sessão de chat interativa persistente. 4. Ative `config.logging: true` e observe os logs do gateway. 5. Verifique se a própria pesquisa de memória funciona com `openclaw memory status --deep`. -Se os resultados de memória estiverem ruidosos, ajuste mais: +Se os resultados da memória estiverem ruidosos, ajuste: - `maxSummaryChars` @@ -592,7 +598,7 @@ Se a memória ativa estiver lenta demais: - reduza `queryMode` - reduza `timeoutMs` -- reduza a contagem de turnos recentes +- reduza as contagens de turnos recentes - reduza os limites de caracteres por turno ## Páginas relacionadas diff --git a/docs/pt-BR/concepts/system-prompt.md b/docs/pt-BR/concepts/system-prompt.md index 125a902c3..8a3b41c49 100644 --- a/docs/pt-BR/concepts/system-prompt.md +++ b/docs/pt-BR/concepts/system-prompt.md @@ -1,14 +1,14 @@ --- read_when: - - Ao editar o texto do prompt do sistema, a lista de ferramentas ou as seções de hora/heartbeat - - Ao alterar o bootstrap do workspace ou o comportamento de injeção de Skills + - 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 x-i18n: - generated_at: "2026-04-08T02:14:23Z" + generated_at: "2026-04-12T05:33:09Z" model: gpt-5.4 provider: openai - source_hash: e55fc886bc8ec47584d07c9e60dfacd964dc69c7db976ea373877dc4fe09a79a + source_hash: 057f01aac51f7737b5223f61f5d55e552d9011232aebb130426e269d8f6c257f source_path: concepts/system-prompt.md workflow: 15 --- @@ -19,65 +19,60 @@ O OpenClaw cria um prompt do sistema personalizado para cada execução de agent O prompt é montado pelo OpenClaw e injetado em cada execução de agente. -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: +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: - 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 por família de modelos. Mantenha a mutação legada de prompt -`before_prompt_build` para compatibilidade ou mudanças de prompt verdadeiramente 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 para 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 estruturado da fonte de verdade das ferramentas, além de orientações de uso de ferramentas em tempo de execução. -- **Segurança**: lembrete curto de proteção para evitar comportamento de busca por poder ou desvio de supervisão. +- **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. - **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`, corrigir a configuração com `config.patch`, substituir a configuração inteira - com `config.apply` e executar `update.run` apenas sob solicitação explícita do usuário. A ferramenta - `gateway`, disponível apenas para o proprietário, também se recusa a reescrever + `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 `tools.exec.ask` / `tools.exec.security`, incluindo aliases legados `tools.bash.*` - que são normalizados para esses caminhos protegidos de exec. + que são normalizados para esses caminhos de exec protegidos. - **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 arquivos de bootstrap estão incluídos abaixo. -- **Sandbox** (quando habilitado): indica runtime em sandbox, caminhos da sandbox e se exec elevado 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 com privilégios elevados 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 ack, quando heartbeats estão habilitados para o agente padrão. +- **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 para alternância com /reasoning. +- **Raciocínio**: nível atual de visibilidade + dica do toggle `/reasoning`. A seção Ferramentas também inclui orientações de runtime para trabalhos de longa duração: -- use cron para acompanhamentos futuros (`check back later`, lembretes, trabalho recorrente) - em vez de loops de sleep com `exec`, truques de atraso com `yieldMs` ou sondagem repetida de `process` +- 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 em segundo plano -- quando o wake automático na conclusão estiver habilitado, inicie o comando uma vez e conte com - o caminho de wake baseado em push quando ele emitir saída ou falhar +- 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 - 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 do subagente é +- 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 esperar +- não faça polling de `subagents list` / `sessions_list` em loop apenas para aguardar 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 de várias etapas, manter exatamente uma +modelo para usá-la apenas em trabalhos não triviais com múltiplas 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ão de canais para imposição rígida; operadores podem desativá-las por design. +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. Em canais com cartões/botões de aprovação nativos, o prompt de runtime agora informa ao -agente que ele deve depender primeiro dessa interface nativa de aprovação. 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 +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. ## Modos de prompt @@ -90,14 +85,14 @@ O OpenClaw pode renderizar prompts do sistema menores para subagentes. O runtime **Mensagens**, **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 base de identidade. +- `none`: retorna apenas a linha de identidade base. Quando `promptMode=minimal`, prompts extras injetados são rotulados como **Contexto do subagente** em vez de **Contexto do chat em grupo**. ## Injeção de bootstrap do workspace -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: +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: - `AGENTS.md` - `SOUL.md` @@ -106,18 +101,19 @@ Arquivos de bootstrap são recortados e anexados em **Contexto do projeto** para - `USER.md` - `HEARTBEAT.md` - `BOOTSTRAP.md` (apenas em workspaces totalmente novos) -- `MEMORY.md` quando presente; caso contrário, `memory.md` como fallback em minúsculas +- `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 -uma regra específica do arquivo se aplique. `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 compactação mais frequente. +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. -> **Observação:** arquivos diários `memory/*.md` **não** são injetados automaticamente. 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. +> **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. 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 @@ -130,22 +126,22 @@ padrão: `once`). Sessões de subagente injetam apenas `AGENTS.md` e `TOOLS.md` (os outros arquivos de bootstrap são filtrados para manter pequeno o contexto do subagente). -Hooks internos podem interceptar esta etapa via `agent:bootstrap` para mutar ou substituir +Hooks internos podem interceptar esta etapa via `agent:bootstrap` para modificar ou substituir os arquivos de bootstrap injetados (por exemplo, trocando `SOUL.md` por uma persona alternativa). -Se você quiser tornar o agente menos genérico, comece com o +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 do overhead de schema de ferramenta), 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 de ferramentas), use `/context list` ou `/context detail`. Veja [Contexto](/pt-BR/concepts/context). -## Tratamento de hora +## Tratamento de tempo O prompt do sistema inclui uma seção dedicada **Data e hora atuais** quando o -fuso horário do usuário é conhecido. Para manter a estabilidade do cache do prompt, ele agora inclui apenas -o **fuso horário** (sem relógio dinâmico nem formato de hora). +fuso horário do usuário é conhecido. Para manter o cache do prompt estável, agora ele 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 pode opcionalmente definir uma substituição +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). Configure com: @@ -153,18 +149,18 @@ Configure com: - `agents.defaults.userTimezone` - `agents.defaults.timeFormat` (`auto` | `12` | `24`) -Consulte [Data e hora](/pt-BR/date-time) para detalhes completos do comportamento. +Veja [Data e hora](/pt-BR/date-time) para detalhes completos do comportamento. ## Skills -Quando há Skills elegíveis, o OpenClaw injeta uma **lista compacta de Skills disponíveis** +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 nenhuma skill for elegível, a seção +(workspace, gerenciado ou empacotado). Se não houver skills elegíveis, a seção Skills é omitida. -A elegibilidade inclui regras de metadados da skill, verificações de ambiente/configuração de runtime -e a lista de permissão efetiva de skills do agente quando `agents.defaults.skills` ou +A elegibilidade inclui gates 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. ``` @@ -177,13 +173,13 @@ e a lista de permissão efetiva de skills do agente quando `agents.defaults.skil ``` -Isso mantém o prompt base pequeno, ao mesmo tempo em que ainda permite uso direcionado de skills. +Isso mantém o prompt base pequeno, ao mesmo tempo que ainda permite uso direcionado de skills. ## Documentação Quando disponível, o prompt do 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 empacotada do pacote npm) e também menciona o espelho público, o repositório de origem, o Discord da comunidade e 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). diff --git a/docs/pt-BR/plugins/architecture.md b/docs/pt-BR/plugins/architecture.md index 490942629..100e70c5a 100644 --- a/docs/pt-BR/plugins/architecture.md +++ b/docs/pt-BR/plugins/architecture.md @@ -1,17 +1,17 @@ --- read_when: - Criando ou depurando plugins nativos do OpenClaw - - Entendendo o modelo de capacidades de plugins ou os limites de propriedade - - Trabalhando no pipeline de carregamento de plugins ou no registro - - Implementando hooks de runtime de provedor ou plugins de canal + - Entender o modelo de capacidades do plugin ou os limites de propriedade + - Trabalhar no pipeline de carregamento ou no registro de plugins + - Implementar hooks de runtime de provedores ou plugins de canal sidebarTitle: Internals summary: 'Internos de plugins: modelo de capacidades, propriedade, contratos, pipeline de carregamento e auxiliares de runtime' title: Internos de plugins x-i18n: - generated_at: "2026-04-11T15:16:05Z" + generated_at: "2026-04-12T05:33:13Z" model: gpt-5.4 provider: openai - source_hash: 7cac67984d0d729c0905bcf5c18372fb0d9b02bbd3a531580b7e2ef483ef40a6 + source_hash: 6165a9da8b40de3bb7334fcb16023da5515deb83c4897ca1df1726f4a97db9e0 source_path: plugins/architecture.md workflow: 15 --- @@ -19,7 +19,7 @@ x-i18n: # Internos de plugins - Esta é a **referência aprofundada de arquitetura**. Para guias práticos, consulte: + Esta é a **referência profunda de arquitetura**. Para guias práticos, consulte: - [Instalar e usar plugins](/pt-BR/tools/plugin) — guia do usuário - [Primeiros passos](/pt-BR/plugins/building-plugins) — primeiro tutorial de plugin - [Plugins de canal](/pt-BR/plugins/sdk-channel-plugins) — crie um canal de mensagens @@ -27,21 +27,21 @@ x-i18n: - [Visão geral do SDK](/pt-BR/plugins/sdk-overview) — mapa de importação e API de registro -Esta página aborda a arquitetura interna do sistema de plugins do OpenClaw. +Esta página cobre a arquitetura interna do sistema de plugins do OpenClaw. ## Modelo público de capacidades -As capacidades são o modelo público de **plugin nativo** dentro do OpenClaw. Todo -plugin nativo do OpenClaw é registrado em um ou mais tipos de capacidade: +Capacidades são o modelo público de **plugin nativo** dentro do OpenClaw. Todo +plugin nativo do OpenClaw registra uma ou mais capacidades: | Capacidade | Método de registro | Plugins de exemplo | | ---------------------- | ----------------------------------------------- | ----------------------------------- | | Inferência de texto | `api.registerProvider(...)` | `openai`, `anthropic` | -| Backend de inferência da CLI | `api.registerCliBackend(...)` | `openai`, `anthropic` | +| Backend de inferência da CLI | `api.registerCliBackend(...)` | `openai`, `anthropic` | | Fala | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | | Transcrição em tempo real | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | | Voz em tempo real | `api.registerRealtimeVoiceProvider(...)` | `openai` | -| Compreensão de mídia | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` | +| Entendimento de mídia | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` | | Geração de imagens | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` | | Geração de música | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` | | Geração de vídeo | `api.registerVideoGenerationProvider(...)` | `qwen` | @@ -50,54 +50,55 @@ plugin nativo do OpenClaw é registrado em um ou mais tipos de capacidade: | Canal / mensagens | `api.registerChannel(...)` | `msteams`, `matrix` | Um plugin que registra zero capacidades, mas fornece hooks, ferramentas ou -serviços, é um plugin **legado somente com hooks**. Esse padrão ainda é totalmente compatível. +serviços, é um plugin **legado apenas com hooks**. Esse padrão ainda é +totalmente suportado. -### Postura de compatibilidade externa +### Posição de compatibilidade externa -O modelo de capacidades já está incorporado ao core e é usado por plugins -nativos/embutidos hoje, mas a compatibilidade de plugins externos ainda precisa -de um critério mais rigoroso do que “está exportado, portanto está congelado”. +O modelo de capacidades foi incorporado ao core e é usado hoje por plugins +nativos/inclusos, mas a compatibilidade de plugins externos ainda precisa de um +critério mais rigoroso do que "está exportado, portanto está congelado". Orientação atual: -- **plugins externos existentes:** mantenha as integrações baseadas em hooks funcionando; trate - isso como a linha de base de compatibilidade -- **novos plugins nativos/embutidos:** prefira registro explícito de capacidades em vez de - acessos específicos de fornecedor ou novos designs somente com hooks +- **plugins externos existentes:** mantenha integrações baseadas em hooks funcionando; trate + isso como a base de compatibilidade +- **novos plugins nativos/inclusos:** prefira registro explícito de capacidades em vez de + acessos específicos de fornecedor ou novos designs apenas com hooks - **plugins externos adotando registro de capacidades:** permitido, mas trate as - superfícies auxiliares específicas de capacidade como evolutivas, a menos que a documentação marque explicitamente - um contrato como estável + superfícies auxiliares específicas de capacidade como evolutivas, a menos que a documentação + marque explicitamente um contrato como estável Regra prática: -- as APIs de registro de capacidades são a direção pretendida -- hooks legados continuam sendo o caminho mais seguro para evitar quebras em plugins externos durante +- APIs de registro de capacidades são a direção pretendida +- hooks legados continuam sendo o caminho mais seguro, sem quebras, para plugins externos durante a transição -- os subcaminhos auxiliares exportados não são todos equivalentes; prefira o contrato - documentado e específico, não exportações auxiliares incidentais +- nem todos os subcaminhos auxiliares exportados são equivalentes; prefira o contrato + estreito documentado, não exports auxiliares incidentais -### Formas de plugins +### Formatos de plugin -O OpenClaw classifica todo plugin carregado em uma forma com base no seu +O OpenClaw classifica cada plugin carregado em um formato com base no seu comportamento real de registro (não apenas em metadados estáticos): - **plain-capability** -- registra exatamente um tipo de capacidade (por exemplo, um - plugin somente de provedor, como `mistral`) + plugin somente de provedor como `mistral`) - **hybrid-capability** -- registra vários tipos de capacidade (por exemplo, - `openai` é responsável por inferência de texto, fala, compreensão de mídia e - geração de imagens) + `openai` é responsável por inferência de texto, fala, entendimento de mídia e geração + de imagens) - **hook-only** -- registra apenas hooks (tipados ou personalizados), sem capacidades, ferramentas, comandos ou serviços -- **non-capability** -- registra ferramentas, comandos, serviços ou rotas, mas não +- **non-capability** -- registra ferramentas, comandos, serviços ou rotas, mas sem capacidades -Use `openclaw plugins inspect ` para ver a forma de um plugin e o detalhamento -de capacidades. Consulte a [referência da CLI](/cli/plugins#inspect) para mais detalhes. +Use `openclaw plugins inspect ` para ver o formato de um plugin e o detalhamento +das capacidades. Consulte [referência da CLI](/cli/plugins#inspect) para mais detalhes. ### Hooks legados -O hook `before_agent_start` continua compatível como caminho de compatibilidade para -plugins somente com hooks. Plugins legados do mundo real ainda dependem dele. +O hook `before_agent_start` continua suportado como caminho de compatibilidade para +plugins apenas com hooks. Plugins legados do mundo real ainda dependem dele. Direção: @@ -105,22 +106,22 @@ Direção: - documente-o como legado - prefira `before_model_resolve` para trabalho de substituição de modelo/provedor - prefira `before_prompt_build` para trabalho de mutação de prompt -- remova-o apenas depois que o uso real cair e a cobertura de fixtures comprovar a segurança da migração +- remova-o apenas depois que o uso real diminuir e a cobertura de fixtures comprovar a segurança da migração ### Sinais de compatibilidade Quando você executa `openclaw doctor` ou `openclaw plugins inspect `, pode ver um destes rótulos: -| Sinal | Significado | -| -------------------------- | ------------------------------------------------------------ | -| **config valid** | A configuração é analisada corretamente e os plugins são resolvidos | -| **compatibility advisory** | O plugin usa um padrão compatível, mas mais antigo (por exemplo, `hook-only`) | -| **legacy warning** | O plugin usa `before_agent_start`, que está obsoleto | -| **hard error** | A configuração é inválida ou o plugin falhou ao carregar | +| Sinal | Significado | +| ------------------------- | ------------------------------------------------------------- | +| **config valid** | A configuração é analisada corretamente e os plugins são resolvidos | +| **compatibility advisory** | O plugin usa um padrão suportado, mas mais antigo (por exemplo, `hook-only`) | +| **legacy warning** | O plugin usa `before_agent_start`, que está obsoleto | +| **hard error** | A configuração é inválida ou o plugin falhou ao carregar | -Nem `hook-only` nem `before_agent_start` quebrarão seu plugin hoje -- -`hook-only` é apenas informativo, e `before_agent_start` apenas dispara um aviso. Esses +Nem `hook-only` nem `before_agent_start` vão quebrar seu plugin hoje -- +`hook-only` é apenas informativo, e `before_agent_start` só gera um aviso. Esses sinais também aparecem em `openclaw status --all` e `openclaw plugins doctor`. ## Visão geral da arquitetura @@ -129,56 +130,56 @@ O sistema de plugins do OpenClaw tem quatro camadas: 1. **Manifesto + descoberta** O OpenClaw encontra plugins candidatos em caminhos configurados, raízes de workspace, - raízes globais de extensões e extensões embutidas. A descoberta lê primeiro os - manifestos nativos `openclaw.plugin.json` e os manifestos de bundle compatíveis. + raízes globais de extensões e extensões incluídas. A descoberta lê primeiro + manifestos nativos `openclaw.plugin.json` e manifestos de bundle suportados. 2. **Habilitação + validação** O core decide se um plugin descoberto está habilitado, desabilitado, bloqueado ou selecionado para um slot exclusivo, como memória. 3. **Carregamento em runtime** - Plugins nativos do OpenClaw são carregados in-process via jiti e registram + Plugins nativos do OpenClaw são carregados no processo via jiti e registram capacidades em um registro central. Bundles compatíveis são normalizados em registros do registro sem importar código de runtime. -4. **Consumo da superfície** +4. **Consumo de superfície** O restante do OpenClaw lê o registro para expor ferramentas, canais, configuração - de provedor, hooks, rotas HTTP, comandos da CLI e serviços. + de provedores, hooks, rotas HTTP, comandos da CLI e serviços. -Especificamente para a CLI de plugins, a descoberta do comando raiz é dividida em duas fases: +Especificamente para a CLI de plugins, a descoberta de comandos raiz é dividida em duas fases: -- os metadados em tempo de parsing vêm de `registerCli(..., { descriptors: [...] })` -- o módulo real da CLI do plugin pode continuar lazy e registrar na primeira invocação +- metadados em tempo de análise vêm de `registerCli(..., { descriptors: [...] })` +- o módulo real da CLI do plugin pode permanecer lazy e ser registrado na primeira invocação -Isso mantém o código da CLI pertencente ao plugin dentro do próprio plugin, ao mesmo tempo -que permite ao OpenClaw reservar nomes de comando raiz antes do parsing. +Isso mantém o código de CLI pertencente ao plugin dentro do plugin, ao mesmo tempo que permite ao OpenClaw +reservar nomes de comandos raiz antes da análise. O limite de design importante: -- descoberta + validação de configuração devem funcionar a partir de **metadados de manifesto/esquema** +- descoberta + validação de configuração devem funcionar a partir de **metadados de manifesto/schema** sem executar código do plugin - o comportamento nativo em runtime vem do caminho `register(api)` do módulo do plugin -Essa separação permite que o OpenClaw valide configuração, explique plugins -ausentes/desabilitados e construa dicas de UI/esquema antes que o runtime completo esteja ativo. +Essa separação permite que o OpenClaw valide configuração, explique plugins ausentes/desabilitados e +construa dicas de UI/schema antes que todo o runtime esteja ativo. -### Plugins de canal e a ferramenta compartilhada de mensagens +### Plugins de canal e a ferramenta compartilhada de mensagem Plugins de canal não precisam registrar uma ferramenta separada de enviar/editar/reagir para -ações normais de chat. O OpenClaw mantém uma única ferramenta `message` compartilhada no core, -e os plugins de canal são responsáveis pela descoberta e execução específicas do canal por trás dela. +ações normais de chat. O OpenClaw mantém uma ferramenta `message` compartilhada no core, e +os plugins de canal são responsáveis pela descoberta e execução específicas do canal por trás dela. O limite atual é: -- o core é responsável pelo host da ferramenta `message` compartilhada, pela integração com prompts, pelo - controle de sessão/thread e pelo despacho de execução -- plugins de canal são responsáveis pela descoberta de ações com escopo, descoberta de - capacidades e quaisquer fragmentos de esquema específicos do canal -- plugins de canal são responsáveis pela gramática de conversação de sessão específica do provedor, como - ids de conversa codificam ids de thread ou herdam de conversas pai +- o core é responsável pelo host da ferramenta `message` compartilhada, wiring de prompt, controle de sessão/thread + e despacho de execução +- plugins de canal são responsáveis pela descoberta de ações com escopo, descoberta de capacidades e quaisquer + fragmentos de schema específicos do canal +- plugins de canal são responsáveis pela gramática de conversa de sessão específica do provedor, como + IDs de conversa codificam IDs de thread ou herdam de conversas pai - plugins de canal executam a ação final por meio de seu adaptador de ações Para plugins de canal, a superfície do SDK é `ChannelMessageActionAdapter.describeMessageTool(...)`. Essa chamada unificada de descoberta -permite que um plugin retorne suas ações visíveis, capacidades e contribuições de esquema em -conjunto, para que essas partes não se desalinhem. +permite que um plugin retorne suas ações visíveis, capacidades e contribuições de schema +juntas, para que essas partes não se desalinhem. O core passa o escopo de runtime para essa etapa de descoberta. Campos importantes incluem: @@ -192,72 +193,74 @@ O core passa o escopo de runtime para essa etapa de descoberta. Campos important - `requesterSenderId` de entrada confiável Isso é importante para plugins sensíveis ao contexto. Um canal pode ocultar ou expor -ações de mensagem com base na conta ativa, sala/thread/mensagem atual ou +ações de mensagem com base na conta ativa, sala/thread/mensagem atual, ou identidade confiável do solicitante, sem codificar ramificações específicas do canal na ferramenta `message` do core. -É por isso que mudanças de roteamento do embedded-runner ainda são trabalho do plugin: o runner é -responsável por encaminhar a identidade atual de chat/sessão para o limite de descoberta do plugin, para que a -ferramenta `message` compartilhada exponha a superfície correta, pertencente ao canal, +É por isso que mudanças de roteamento do runner incorporado ainda são trabalho de plugin: o runner é +responsável por encaminhar a identidade atual do chat/sessão para o limite de descoberta do plugin +para que a ferramenta `message` compartilhada exponha a superfície pertencente ao canal correta para o turno atual. -Para auxiliares de execução pertencentes ao canal, plugins embutidos devem manter o runtime -de execução dentro de seus próprios módulos de extensão. O core não é mais responsável pelos -runtimes de ação de mensagem de Discord, Slack, Telegram ou WhatsApp em `src/agents/tools`. -Não publicamos subcaminhos separados `plugin-sdk/*-action-runtime`, e plugins embutidos +Para auxiliares de execução pertencentes ao canal, plugins incluídos devem manter o runtime de execução +dentro de seus próprios módulos de extensão. O core não é mais responsável pelos runtimes de ação de mensagem +de Discord, Slack, Telegram ou WhatsApp em `src/agents/tools`. +Não publicamos subcaminhos separados `plugin-sdk/*-action-runtime`, e plugins incluídos devem importar seu próprio código de runtime local diretamente de seus módulos pertencentes à extensão. -O mesmo limite se aplica, em geral, a seams do SDK nomeadas por provedor: o core não -deve importar barrels de conveniência específicos de canal para Slack, Discord, Signal, -WhatsApp ou extensões semelhantes. Se o core precisar de um comportamento, deve consumir o -próprio barrel `api.ts` / `runtime-api.ts` do plugin embutido ou promover a necessidade -para uma capacidade genérica e específica no SDK compartilhado. +O mesmo limite se aplica a seams do SDK nomeados por provedor em geral: o core não +deve importar barris de conveniência específicos de canal para extensões como Slack, Discord, Signal, +WhatsApp ou semelhantes. Se o core precisa de um comportamento, deve consumir o próprio barril +`api.ts` / `runtime-api.ts` do plugin incluído ou promover a necessidade +a uma capacidade genérica e estreita no SDK compartilhado. -Especificamente para enquetes, há dois caminhos de execução: +Especificamente para enquetes, existem dois caminhos de execução: -- `outbound.sendPoll` é a linha de base compartilhada para canais que se encaixam no modelo - comum de enquetes -- `actions.handleAction("poll")` é o caminho preferido para semânticas de enquete - específicas do canal ou parâmetros extras de enquete +- `outbound.sendPoll` é a base compartilhada para canais compatíveis com o modelo comum de + enquete +- `actions.handleAction("poll")` é o caminho preferido para semântica de enquete específica do canal + ou parâmetros extras de enquete -Agora o core adia o parsing compartilhado de enquetes até que o despacho de enquete do plugin -recuse a ação, para que tratadores de enquete pertencentes ao plugin possam aceitar -campos de enquete específicos do canal sem serem bloqueados primeiro pelo parser genérico de enquetes. +O core agora adia a análise compartilhada de enquetes até que o despacho da enquete do plugin recuse +a ação, para que manipuladores de enquete pertencentes ao plugin possam aceitar campos de enquete específicos do canal +sem serem bloqueados primeiro pelo analisador genérico de enquetes. Consulte [Pipeline de carregamento](#load-pipeline) para a sequência completa de inicialização. ## Modelo de propriedade de capacidades -O OpenClaw trata um plugin nativo como o limite de propriedade de uma **empresa** ou um -**recurso**, não como uma coleção de integrações sem relação. +O OpenClaw trata um plugin nativo como o limite de propriedade para uma **empresa** ou um +**recurso**, não como uma coleção de integrações não relacionadas. Isso significa: -- um plugin de empresa normalmente deve ser responsável por todas as superfícies do OpenClaw voltadas - para essa empresa -- um plugin de recurso normalmente deve ser responsável pela superfície completa do recurso que introduz -- canais devem consumir capacidades compartilhadas do core em vez de reimplementar comportamento - de provedor de forma ad hoc +- um plugin de empresa normalmente deve ser responsável por todas as superfícies do OpenClaw + dessa empresa +- um plugin de recurso normalmente deve ser responsável por toda a superfície do recurso que introduz +- canais devem consumir capacidades compartilhadas do core em vez de reimplementar + comportamento de provedor de forma ad hoc Exemplos: -- o plugin embutido `openai` é responsável pelo comportamento de provedor de modelos da OpenAI e pelo comportamento de - fala + voz em tempo real + compreensão de mídia + geração de imagens da OpenAI -- o plugin embutido `elevenlabs` é responsável pelo comportamento de fala da ElevenLabs -- o plugin embutido `microsoft` é responsável pelo comportamento de fala da Microsoft -- o plugin embutido `google` é responsável pelo comportamento de provedor de modelos do Google, além do comportamento de - compreensão de mídia + geração de imagens + pesquisa na web do Google -- o plugin embutido `firecrawl` é responsável pelo comportamento de busca na web do Firecrawl -- os plugins embutidos `minimax`, `mistral`, `moonshot` e `zai` são responsáveis por seus - backends de compreensão de mídia -- o plugin `voice-call` é um plugin de recurso: ele é responsável por transporte de chamadas, ferramentas, - CLI, rotas e ponte de fluxo de mídia do Twilio, mas consome capacidades compartilhadas de fala - mais transcrição em tempo real e voz em tempo real, em vez de importar plugins de fornecedor diretamente +- o plugin incluído `openai` é responsável pelo comportamento de provedor de modelos da OpenAI e pelo comportamento de + fala + voz em tempo real + entendimento de mídia + geração de imagens da OpenAI +- o plugin incluído `elevenlabs` é responsável pelo comportamento de fala da ElevenLabs +- o plugin incluído `microsoft` é responsável pelo comportamento de fala da Microsoft +- o plugin incluído `google` é responsável pelo comportamento de provedor de modelos do Google, além do comportamento de + entendimento de mídia + geração de imagens + pesquisa na web do Google +- o plugin incluído `firecrawl` é responsável pelo comportamento de busca na web do Firecrawl +- os plugins incluídos `minimax`, `mistral`, `moonshot` e `zai` são responsáveis por seus + backends de entendimento de mídia +- o plugin incluído `qwen` é responsável pelo comportamento de provedor de texto do Qwen, além do + comportamento de entendimento de mídia e geração de vídeo +- o plugin `voice-call` é um plugin de recurso: ele é responsável por transporte de chamada, ferramentas, + CLI, rotas e bridging de fluxo de mídia do Twilio, mas consome capacidades compartilhadas de fala + mais transcrição em tempo real e voz em tempo real em vez de importar plugins de fornecedor diretamente O estado final pretendido é: -- A OpenAI fica em um único plugin, mesmo que abranja modelos de texto, fala, imagens e +- a OpenAI fica em um único plugin, mesmo que abranja modelos de texto, fala, imagens e vídeo no futuro - outro fornecedor pode fazer o mesmo para sua própria área de atuação - canais não se importam com qual plugin de fornecedor é responsável pelo provedor; eles consomem o @@ -266,46 +269,46 @@ O estado final pretendido é: Esta é a distinção principal: - **plugin** = limite de propriedade -- **capacidade** = contrato do core que vários plugins podem implementar ou consumir +- **capability** = contrato do core que vários plugins podem implementar ou consumir -Portanto, se o OpenClaw adicionar um novo domínio, como vídeo, a primeira pergunta não é -“qual provedor deve codificar o tratamento de vídeo?” A primeira pergunta é “qual é -o contrato de capacidade de vídeo do core?” Quando esse contrato existir, plugins de fornecedor -poderão se registrar nele, e plugins de canal/recurso poderão consumi-lo. +Então, se o OpenClaw adicionar um novo domínio, como vídeo, a primeira pergunta não é +"qual provedor deve codificar o tratamento de vídeo?" A primeira pergunta é "qual é +o contrato de capacidade de vídeo do core?" Assim que esse contrato existir, plugins de fornecedores +poderão se registrar nele e plugins de canal/recurso poderão consumi-lo. -Se a capacidade ainda não existir, o movimento correto normalmente é: +Se a capacidade ainda não existir, a ação correta geralmente é: 1. definir a capacidade ausente no core -2. expô-la por meio da API/runtime de plugins de forma tipada +2. expô-la por meio da API/runtime de plugin de forma tipada 3. conectar canais/recursos a essa capacidade -4. deixar que plugins de fornecedor registrem implementações +4. permitir que plugins de fornecedores registrem implementações -Isso mantém a propriedade explícita e evita comportamentos no core que dependam de um -único fornecedor ou de um caminho de código específico de um plugin isolado. +Isso mantém a propriedade explícita e evita comportamento no core que dependa de um +único fornecedor ou de um caminho de código específico de plugin e pontual. ### Camadas de capacidade Use este modelo mental ao decidir onde o código deve ficar: -- **camada de capacidade do core**: orquestração compartilhada, política, fallback, regras - de mesclagem de configuração, semântica de entrega e contratos tipados +- **camada de capacidade do core**: orquestração compartilhada, política, fallback, regras de + mesclagem de configuração, semântica de entrega e contratos tipados - **camada de plugin de fornecedor**: APIs específicas do fornecedor, autenticação, catálogos de modelos, síntese de fala, geração de imagens, futuros backends de vídeo, endpoints de uso - **camada de plugin de canal/recurso**: integração com Slack/Discord/voice-call/etc. que consome capacidades do core e as apresenta em uma superfície -Por exemplo, TTS segue esta forma: +Por exemplo, TTS segue este formato: - o core é responsável pela política de TTS no momento da resposta, ordem de fallback, preferências e entrega por canal - `openai`, `elevenlabs` e `microsoft` são responsáveis pelas implementações de síntese -- `voice-call` consome o auxiliar de runtime de TTS para telefonia +- `voice-call` consome o auxiliar de runtime de TTS de telefonia Esse mesmo padrão deve ser preferido para capacidades futuras. ### Exemplo de plugin de empresa com múltiplas capacidades Um plugin de empresa deve parecer coeso por fora. Se o OpenClaw tiver contratos compartilhados -para modelos, fala, transcrição em tempo real, voz em tempo real, compreensão de mídia, +para modelos, fala, transcrição em tempo real, voz em tempo real, entendimento de mídia, geração de imagens, geração de vídeo, busca na web e pesquisa na web, um fornecedor pode ser responsável por todas as suas superfícies em um só lugar: @@ -361,63 +364,62 @@ const plugin: OpenClawPluginDefinition = { export default plugin; ``` -O que importa não é o nome exato dos auxiliares. A forma é o que importa: +O que importa não são os nomes exatos dos auxiliares. O que importa é o formato: -- um único plugin é responsável pela superfície do fornecedor -- o core continua responsável pelos contratos de capacidade -- plugins de canal e de recurso consomem auxiliares `api.runtime.*`, não código do fornecedor -- testes de contrato podem afirmar que o plugin registrou as capacidades das quais - afirma ser responsável +- um plugin é responsável pela superfície do fornecedor +- o core continua sendo responsável pelos contratos de capacidade +- canais e plugins de recurso consomem auxiliares `api.runtime.*`, não código do fornecedor +- testes de contrato podem afirmar que o plugin registrou as capacidades que + afirma possuir -### Exemplo de capacidade: compreensão de vídeo +### Exemplo de capacidade: entendimento de vídeo -O OpenClaw já trata compreensão de imagem/áudio/vídeo como uma única +O OpenClaw já trata entendimento de imagem/áudio/vídeo como uma única capacidade compartilhada. O mesmo modelo de propriedade se aplica aqui: -1. o core define o contrato de compreensão de mídia -2. plugins de fornecedor registram `describeImage`, `transcribeAudio` e +1. o core define o contrato de media-understanding +2. plugins de fornecedores registram `describeImage`, `transcribeAudio` e `describeVideo`, conforme aplicável -3. plugins de canal e de recurso consomem o comportamento compartilhado do core em vez de +3. canais e plugins de recurso consomem o comportamento compartilhado do core em vez de se conectarem diretamente ao código do fornecedor -Isso evita incorporar no core as suposições de vídeo de um único provedor. O plugin é responsável -pela superfície do fornecedor; o core é responsável pelo contrato de capacidade e pelo comportamento de fallback. +Isso evita incorporar ao core as suposições de vídeo de um único provedor. O plugin é responsável pela +superfície do fornecedor; o core é responsável pelo contrato de capacidade e pelo comportamento de fallback. A geração de vídeo já usa essa mesma sequência: o core é responsável pelo contrato tipado de -capacidade e pelo auxiliar de runtime, e plugins de fornecedor registram -implementações `api.registerVideoGenerationProvider(...)` nela. +capacidade e pelo auxiliar de runtime, e plugins de fornecedores registram +implementações `api.registerVideoGenerationProvider(...)` nele. Precisa de um checklist concreto de rollout? Consulte [Livro de receitas de capacidades](/pt-BR/plugins/architecture). ## Contratos e aplicação -A superfície da API de plugins é intencionalmente tipada e centralizada em -`OpenClawPluginApi`. Esse contrato define os pontos de registro compatíveis e +A superfície da API de plugin é intencionalmente tipada e centralizada em +`OpenClawPluginApi`. Esse contrato define os pontos de registro suportados e os auxiliares de runtime nos quais um plugin pode confiar. Por que isso importa: -- autores de plugins têm um padrão interno estável +- autores de plugins obtêm um padrão interno estável - o core pode rejeitar propriedade duplicada, como dois plugins registrando o mesmo - id de provedor -- a inicialização pode exibir diagnósticos acionáveis para registros malformados -- testes de contrato podem aplicar a propriedade de plugins embutidos e evitar desvios silenciosos + ID de provedor +- a inicialização pode expor diagnósticos acionáveis para registros malformados +- testes de contrato podem aplicar a propriedade de plugins incluídos e evitar deriva silenciosa Há duas camadas de aplicação: -1. **aplicação de registro em runtime** +1. **aplicação do registro em runtime** O registro de plugins valida os registros à medida que os plugins são carregados. Exemplos: - ids de provedor duplicados, ids de provedor de fala duplicados e registros + IDs de provedor duplicados, IDs de provedor de fala duplicados e registros malformados produzem diagnósticos de plugin em vez de comportamento indefinido. 2. **testes de contrato** - Plugins embutidos são capturados em registros de contrato durante as execuções de teste para que o - OpenClaw possa afirmar explicitamente a propriedade. Hoje isso é usado para - provedores de modelos, provedores de fala, provedores de pesquisa na web e propriedade - de registro de plugins embutidos. + Plugins incluídos são capturados em registros de contrato durante execuções de teste, para que o + OpenClaw possa afirmar a propriedade explicitamente. Hoje isso é usado para + provedores de modelos, provedores de fala, provedores de pesquisa na web e propriedade de registro incluída. O efeito prático é que o OpenClaw sabe, antecipadamente, qual plugin é responsável por qual -superfície. Isso permite que o core e os canais componham sem atritos, porque a propriedade é +superfície. Isso permite que o core e os canais componham sem atrito porque a propriedade é declarada, tipada e testável, em vez de implícita. ### O que pertence a um contrato @@ -426,121 +428,125 @@ Bons contratos de plugin são: - tipados - pequenos -- específicos de capacidade +- específicos por capacidade - pertencentes ao core -- reutilizáveis por vários plugins +- reutilizáveis por múltiplos plugins - consumíveis por canais/recursos sem conhecimento do fornecedor -Contratos ruins de plugin são: +Maus contratos de plugin são: -- política específica de fornecedor escondida no core -- rotas de escape pontuais de plugin que contornam o registro +- política específica de fornecedor oculta no core +- escapes pontuais de plugin que contornam o registro - código de canal acessando diretamente uma implementação de fornecedor -- objetos ad hoc de runtime que não fazem parte de `OpenClawPluginApi` nem de +- objetos de runtime ad hoc que não fazem parte de `OpenClawPluginApi` ou `api.runtime` -Em caso de dúvida, aumente o nível de abstração: defina primeiro a capacidade e -depois deixe os plugins se conectarem a ela. +Em caso de dúvida, eleve o nível de abstração: defina primeiro a capacidade e depois +permita que os plugins se conectem a ela. ## Modelo de execução -Plugins nativos do OpenClaw são executados **in-process** com o Gateway. Eles não -são isolados em sandbox. Um plugin nativo carregado tem o mesmo limite de confiança -no nível de processo que o código do core. +Plugins nativos do OpenClaw são executados **no processo** com o Gateway. Eles não +são isolados em sandbox. Um plugin nativo carregado tem o mesmo limite de confiança no nível de processo que +o código do core. Implicações: -- um plugin nativo pode registrar ferramentas, manipuladores de rede, hooks e serviços -- um bug em um plugin nativo pode derrubar ou desestabilizar o gateway +- um plugin nativo pode registrar ferramentas, handlers de rede, hooks e serviços +- um bug em um plugin nativo pode travar ou desestabilizar o gateway - um plugin nativo malicioso equivale a execução arbitrária de código dentro do processo do OpenClaw -Bundles compatíveis são mais seguros por padrão, porque o OpenClaw atualmente os trata +Bundles compatíveis são mais seguros por padrão porque o OpenClaw atualmente os trata como pacotes de metadados/conteúdo. Nas versões atuais, isso significa principalmente -Skills empacotadas. +Skills incluídas. -Use listas de permissão e caminhos explícitos de instalação/carregamento para plugins não empacotados. -Trate plugins de workspace como código de tempo de desenvolvimento, não como padrões de produção. +Use allowlists e caminhos explícitos de instalação/carregamento para plugins não incluídos. Trate +plugins de workspace como código de desenvolvimento, não como padrão de produção. -Para nomes de pacotes de workspace embutidos, mantenha o id do plugin ancorado no nome npm: +Para nomes de pacotes de workspace incluídos, mantenha o ID do plugin ancorado no nome npm: `@openclaw/` por padrão, ou um sufixo tipado aprovado, como `-provider`, `-plugin`, `-speech`, `-sandbox` ou `-media-understanding`, quando o pacote expõe intencionalmente uma função de plugin mais restrita. Observação importante sobre confiança: -- `plugins.allow` confia em **ids de plugin**, não na procedência da origem. -- Um plugin de workspace com o mesmo id de um plugin embutido intencionalmente sobrepõe - a cópia embutida quando esse plugin de workspace está habilitado/na lista de permissão. +- `plugins.allow` confia em **IDs de plugin**, não na procedência da origem. +- Um plugin de workspace com o mesmo ID de um plugin incluído intencionalmente sombreia + a cópia incluída quando esse plugin de workspace está habilitado/em allowlist. - Isso é normal e útil para desenvolvimento local, testes de patch e hotfixes. ## Limite de exportação O OpenClaw exporta capacidades, não conveniências de implementação. -Mantenha o registro de capacidades público. Remova exportações auxiliares fora do contrato: +Mantenha público o registro de capacidades. Remova exports auxiliares fora de contrato: -- subcaminhos específicos de auxiliares de plugins embutidos -- subcaminhos de infraestrutura de runtime que não são destinados a ser API pública +- subcaminhos auxiliares específicos de plugins incluídos +- subcaminhos de plumbing de runtime não destinados a serem API pública - auxiliares de conveniência específicos de fornecedor - auxiliares de configuração/onboarding que são detalhes de implementação -Alguns subcaminhos auxiliares de plugins embutidos ainda permanecem no mapa gerado de exportação do SDK -por compatibilidade e manutenção de plugins embutidos. Exemplos atuais incluem +Alguns subcaminhos auxiliares de plugins incluídos ainda permanecem no mapa de exportação +gerado do SDK por compatibilidade e manutenção de plugins incluídos. Exemplos atuais incluem `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` e vários seams `plugin-sdk/matrix*`. Trate-os como -exportações reservadas de detalhe de implementação, não como o padrão recomendado de SDK para +exports reservados de detalhe de implementação, não como o padrão de SDK recomendado para novos plugins de terceiros. ## Pipeline de carregamento Na inicialização, o OpenClaw faz aproximadamente isto: -1. descobre raízes candidatas de plugins -2. lê manifestos nativos ou de bundles compatíveis e metadados de pacote +1. descobre raízes de plugins candidatas +2. lê manifestos nativos ou de bundle compatível e metadados de pacote 3. rejeita candidatos inseguros 4. normaliza a configuração de plugins (`plugins.enabled`, `allow`, `deny`, `entries`, `slots`, `load.paths`) -5. decide a habilitação para cada candidato +5. decide a habilitação de cada candidato 6. carrega módulos nativos habilitados via jiti -7. chama os hooks nativos `register(api)` (ou `activate(api)` — um alias legado) e coleta os registros no registro de plugins -8. expõe o registro para comandos/superfícies de runtime +7. chama hooks nativos `register(api)` (ou `activate(api)` — um alias legado) e coleta os registros no registro de plugins +8. expõe o registro para superfícies de comandos/runtime -`activate` é um alias legado para `register` — o carregador resolve o que estiver presente (`def.register ?? def.activate`) e o chama no mesmo ponto. Todos os plugins embutidos usam `register`; prefira `register` para novos plugins. +`activate` é um alias legado para `register` — o loader resolve o que estiver presente (`def.register ?? def.activate`) e o chama no mesmo ponto. Todos os plugins incluídos usam `register`; prefira `register` em novos plugins. As barreiras de segurança acontecem **antes** da execução em runtime. Candidatos são bloqueados -quando a entrada escapa da raiz do plugin, o caminho tem permissão de escrita para todos, ou a -propriedade do caminho parece suspeita para plugins não embutidos. +quando a entrada escapa da raiz do plugin, o caminho pode ser escrito por qualquer usuário ou a propriedade do caminho parece suspeita para plugins não incluídos. -### Comportamento manifest-first +### Comportamento orientado por manifesto O manifesto é a fonte de verdade do plano de controle. O OpenClaw o usa para: - identificar o plugin -- descobrir canais/Skills/esquema de configuração declarados ou capacidades de bundle +- descobrir canais/Skills/schema de configuração declarados ou capacidades do bundle - validar `plugins.entries..config` -- complementar rótulos/placeholders da Control UI +- complementar rótulos/placeholders da UI de controle - mostrar metadados de instalação/catálogo - preservar descritores baratos de ativação e configuração sem carregar o runtime do plugin Para plugins nativos, o módulo de runtime é a parte do plano de dados. Ele registra -o comportamento real, como hooks, ferramentas, comandos ou fluxos de provedor. +comportamento real, como hooks, ferramentas, comandos ou fluxos de provedor. Blocos opcionais `activation` e `setup` do manifesto permanecem no plano de controle. Eles são descritores somente de metadados para planejamento de ativação e descoberta de configuração; -não substituem registro em runtime, `register(...)` nem `setupEntry`. +não substituem registro em runtime, `register(...)` ou `setupEntry`. -### O que o carregador mantém em cache +A descoberta de configuração agora prefere IDs pertencentes a descritores, como +`setup.providers` e `setup.cliBackends`, para restringir plugins candidatos antes de recorrer a +`setup-api` para plugins que ainda precisam de hooks de runtime em tempo de configuração. Se mais de +um plugin descoberto afirmar o mesmo ID normalizado de provedor de configuração ou backend de CLI, a busca de configuração recusa o proprietário ambíguo em vez de depender da ordem de descoberta. -O OpenClaw mantém caches curtos in-process para: +### O que o loader armazena em cache + +O OpenClaw mantém caches curtos no processo para: - resultados de descoberta - dados do registro de manifestos - registros de plugins carregados -Esses caches reduzem inicializações em rajadas e a sobrecarga de comandos repetidos. É seguro +Esses caches reduzem picos de inicialização e sobrecarga de comandos repetidos. É seguro pensar neles como caches de desempenho de curta duração, não como persistência. Observação de desempenho: @@ -555,35 +561,34 @@ Observação de desempenho: Plugins carregados não mutam diretamente globais aleatórios do core. Eles se registram em um registro central de plugins. -O registro acompanha: +O registro rastreia: - registros de plugin (identidade, origem, procedência, status, diagnósticos) - ferramentas - hooks legados e hooks tipados - canais - provedores -- manipuladores de RPC do gateway +- handlers RPC do gateway - rotas HTTP - registradores da CLI - serviços em segundo plano -- comandos pertencentes ao plugin +- comandos pertencentes a plugins -Recursos do core então leem esse registro em vez de falar diretamente com módulos de plugin. -Isso mantém o carregamento em um só sentido: +Os recursos do core então leem esse registro em vez de falar diretamente com módulos de plugin. +Isso mantém o carregamento unidirecional: -- módulo do plugin -> registro no registro -- runtime do core -> consumo do registro +- módulo do plugin -> registro no registry +- runtime do core -> consumo do registry -Essa separação é importante para a manutenção. Ela significa que a maioria das superfícies do core só -precisa de um ponto de integração: “ler o registro”, não “criar caso especial para cada -módulo de plugin”. +Essa separação é importante para a manutenção. Significa que a maioria das superfícies do core +precisa de apenas um ponto de integração: "ler o registry", e não "tratar cada módulo de plugin +como caso especial". -## Callbacks de associação de conversa +## Callbacks de vínculo de conversa -Plugins que associam uma conversa podem reagir quando uma aprovação é resolvida. +Plugins que vinculam uma conversa podem reagir quando uma aprovação é resolvida. -Use `api.onConversationBindingResolved(...)` para receber um callback depois que uma solicitação de associação -for aprovada ou negada: +Use `api.onConversationBindingResolved(...)` para receber um callback depois que uma solicitação de vínculo for aprovada ou negada: ```ts export default { @@ -607,22 +612,22 @@ Campos do payload do callback: - `status`: `"approved"` ou `"denied"` - `decision`: `"allow-once"`, `"allow-always"` ou `"deny"` -- `binding`: a associação resolvida para solicitações aprovadas -- `request`: o resumo da solicitação original, dica de desanexação, id do remetente e +- `binding`: o vínculo resolvido para solicitações aprovadas +- `request`: o resumo da solicitação original, dica de desvinculação, ID do remetente e metadados da conversa -Esse callback é apenas de notificação. Ele não altera quem tem permissão para associar uma -conversa, e é executado depois que o tratamento de aprovação do core termina. +Esse callback é apenas de notificação. Ele não muda quem tem permissão para vincular uma +conversa e é executado depois que o tratamento de aprovação do core termina. ## Hooks de runtime de provedor -Os plugins de provedor agora têm duas camadas: +Plugins de provedor agora têm duas camadas: - metadados do manifesto: `providerAuthEnvVars` para busca barata de autenticação do provedor por env - antes do carregamento do runtime, `providerAuthAliases` para variantes de provedor que compartilham - autenticação, `channelEnvVars` para busca barata de env/configuração de canal antes do carregamento do runtime, + antes do carregamento em runtime, `providerAuthAliases` para variantes de provedor que compartilham + autenticação, `channelEnvVars` para busca barata de env/configuração de canal antes do carregamento em runtime, além de `providerAuthChoices` para rótulos baratos de onboarding/escolha de autenticação e - metadados de flags da CLI antes do carregamento do runtime + metadados de flags da CLI antes do carregamento em runtime - hooks em tempo de configuração: `catalog` / legado `discovery` mais `applyConfigDefaults` - hooks de runtime: `normalizeModelId`, `normalizeTransport`, `normalizeConfig`, @@ -644,86 +649,84 @@ Os plugins de provedor agora têm duas camadas: `buildReplayPolicy`, `sanitizeReplayHistory`, `validateReplayTurns`, `onModelSelected` -O OpenClaw continua sendo responsável pelo loop genérico do agente, failover, tratamento de transcrições e +O OpenClaw continua sendo responsável pelo loop genérico do agente, failover, tratamento de transcrição e política de ferramentas. Esses hooks são a superfície de extensão para comportamento específico de provedor sem precisar de um transporte de inferência totalmente personalizado. -Use o manifesto `providerAuthEnvVars` quando o provedor tiver credenciais baseadas em env +Use o `providerAuthEnvVars` do manifesto quando o provedor tiver credenciais baseadas em env que caminhos genéricos de autenticação/status/seletor de modelo devam enxergar sem carregar o runtime do plugin. -Use o manifesto `providerAuthAliases` quando um id de provedor precisar reutilizar -as variáveis de ambiente, perfis de autenticação, autenticação baseada em configuração e a opção de onboarding -de chave de API de outro id de provedor. Use o manifesto `providerAuthChoices` quando superfícies da CLI -de onboarding/escolha de autenticação precisarem conhecer o id de escolha do provedor, rótulos de grupo e -ligação simples de autenticação com uma única flag sem carregar o runtime do provedor. Mantenha o `envVars` -do runtime do provedor para dicas voltadas ao operador, como rótulos de onboarding ou variáveis de -configuração de client-id/client-secret de OAuth. +Use `providerAuthAliases` do manifesto quando um ID de provedor precisar reutilizar as variáveis de ambiente, +perfis de autenticação, autenticação baseada em configuração e opção de onboarding de chave de API de outro ID de provedor. +Use `providerAuthChoices` do manifesto quando as superfícies da CLI de onboarding/escolha de autenticação +precisarem conhecer o ID de escolha do provedor, rótulos de grupo e wiring simples de autenticação com uma única flag +sem carregar o runtime do provedor. Mantenha `envVars` no runtime do provedor para dicas voltadas ao operador, como +rótulos de onboarding ou variáveis de configuração de client-id/client-secret de OAuth. -Use o manifesto `channelEnvVars` quando um canal tiver autenticação ou configuração orientada por env que -fallback genérico para env do shell, verificações de config/status ou prompts de configuração devam enxergar +Use `channelEnvVars` do manifesto quando um canal tiver autenticação ou configuração orientada por env que +fallback genérico de env do shell, verificações de config/status ou prompts de configuração devam enxergar sem carregar o runtime do canal. ### Ordem e uso dos hooks Para plugins de modelo/provedor, o OpenClaw chama hooks aproximadamente nesta ordem. -A coluna “Quando usar” é o guia rápido de decisão. +A coluna "Quando usar" é o guia rápido de decisão. -| # | Hook | O que faz | Quando usar | -| --- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -| 1 | `catalog` | Publica a configuração do provedor em `models.providers` durante a geração de `models.json` | O provedor é responsável por um catálogo ou por padrões de URL base | -| 2 | `applyConfigDefaults` | Aplica padrões globais de configuração pertencentes ao provedor durante a materialização da configuração | Os padrões dependem do modo de autenticação, env ou da semântica da família de modelos do provedor | -| -- | _(built-in model lookup)_ | O OpenClaw tenta primeiro o caminho normal de registro/catálogo | _(não é um hook de plugin)_ | -| 3 | `normalizeModelId` | Normaliza aliases legados ou de preview de id de modelo antes da busca | O provedor é responsável pela limpeza de aliases antes da resolução canônica do modelo | -| 4 | `normalizeTransport` | Normaliza `api` / `baseUrl` da família de provedores antes da montagem genérica do modelo | O provedor é responsável pela limpeza de transporte para ids de provedor personalizados na mesma família de transporte | -| 5 | `normalizeConfig` | Normaliza `models.providers.` antes da resolução de runtime/provedor | O provedor precisa de limpeza de configuração que deve ficar com o plugin; auxiliares empacotados da família Google também dão suporte a entradas de configuração Google compatíveis | -| 6 | `applyNativeStreamingUsageCompat` | Aplica reescritas de compatibilidade de uso de streaming nativo a provedores de configuração | O provedor precisa de correções de metadados de uso de streaming nativo orientadas por endpoint | -| 7 | `resolveConfigApiKey` | Resolve autenticação por marcador de env para provedores de configuração antes do carregamento da autenticação de runtime | O provedor tem resolução de chave de API por marcador de env pertencente ao provedor; `amazon-bedrock` também tem aqui um resolvedor embutido de marcador de env da AWS | -| 8 | `resolveSyntheticAuth` | Expõe autenticação local/self-hosted ou baseada em configuração sem persistir texto simples | O provedor pode operar com um marcador de credencial sintético/local | -| 9 | `resolveExternalAuthProfiles` | Sobrepõe perfis de autenticação externos pertencentes ao provedor; o `persistence` padrão é `runtime-only` para credenciais pertencentes à CLI/app | O provedor reutiliza credenciais de autenticação externas sem persistir refresh tokens copiados | -| 10 | `shouldDeferSyntheticProfileAuth` | Rebaixa placeholders sintéticos armazenados em perfis atrás de autenticação baseada em env/configuração | O provedor armazena perfis placeholder sintéticos que não devem ter precedência | -| 11 | `resolveDynamicModel` | Fallback síncrono para ids de modelo pertencentes ao provedor que ainda não estão no registro local | O provedor aceita ids de modelo arbitrários do upstream | -| 12 | `prepareDynamicModel` | Aquecimento assíncrono; depois `resolveDynamicModel` é executado novamente | O provedor precisa de metadados de rede antes de resolver ids desconhecidos | -| 13 | `normalizeResolvedModel` | Reescrita final antes que o embedded runner use o modelo resolvido | O provedor precisa de reescritas de transporte, mas ainda usa um transporte do core | -| 14 | `contributeResolvedModelCompat` | Contribui com flags de compatibilidade para modelos do fornecedor atrás de outro transporte compatível | O provedor reconhece seus próprios modelos em transportes proxy sem assumir o provedor | -| 15 | `capabilities` | Metadados de transcrição/ferramentas pertencentes ao provedor, usados pela lógica compartilhada do core | O provedor precisa de particularidades de transcrição/família de provedores | -| 16 | `normalizeToolSchemas` | Normaliza esquemas de ferramentas antes que o embedded runner os veja | O provedor precisa de limpeza de esquema da família de transporte | -| 17 | `inspectToolSchemas` | Expõe diagnósticos de esquema pertencentes ao provedor após a normalização | O provedor quer avisos de palavras-chave sem ensinar ao core regras específicas do provedor | -| 18 | `resolveReasoningOutputMode` | Seleciona contrato de saída de raciocínio nativo ou com tags | O provedor precisa de saída final/de raciocínio com tags em vez de campos nativos | -| 19 | `prepareExtraParams` | Normalização de parâmetros da solicitação antes dos wrappers genéricos de opções de stream | O provedor precisa de parâmetros padrão de solicitação ou limpeza de parâmetros por provedor | -| 20 | `createStreamFn` | Substitui completamente o caminho normal de stream por um transporte personalizado | O provedor precisa de um protocolo de transporte personalizado, não apenas de um wrapper | -| 21 | `wrapStreamFn` | Wrapper de stream depois que os wrappers genéricos são aplicados | O provedor precisa de wrappers de compatibilidade de headers/corpo/modelo da solicitação sem um transporte personalizado | -| 22 | `resolveTransportTurnState` | Anexa headers ou metadados nativos por turno ao transporte | O provedor quer que transportes genéricos enviem identidade de turno nativa do provedor | -| 23 | `resolveWebSocketSessionPolicy` | Anexa headers nativos de WebSocket ou política de resfriamento de sessão | O provedor quer que transportes WS genéricos ajustem headers de sessão ou política de fallback | -| 24 | `formatApiKey` | Formatador de perfil de autenticação: o perfil armazenado se torna a string `apiKey` de runtime | O provedor armazena metadados extras de autenticação e precisa de um formato personalizado de token de runtime | -| 25 | `refreshOAuth` | Sobrescrita de atualização de OAuth para endpoints personalizados de atualização ou política de falha na atualização | O provedor não se encaixa nos atualizadores compartilhados de `pi-ai` | -| 26 | `buildAuthDoctorHint` | Dica de reparo acrescentada quando a atualização de OAuth falha | O provedor precisa de orientação de reparo de autenticação pertencente ao provedor após falha na atualização | -| 27 | `matchesContextOverflowError` | Correspondência de overflow de janela de contexto pertencente ao provedor | O provedor tem erros brutos de overflow que heurísticas genéricas deixariam passar | -| 28 | `classifyFailoverReason` | Classificação de motivo de failover pertencente ao provedor | O provedor pode mapear erros brutos de API/transporte para rate limit/sobrecarga/etc. | -| 29 | `isCacheTtlEligible` | Política de cache de prompt para provedores proxy/backhaul | O provedor precisa de controle de TTL de cache específico para proxy | -| 30 | `buildMissingAuthMessage` | Substituição para a mensagem genérica de recuperação de autenticação ausente | O provedor precisa de uma dica de recuperação de autenticação ausente específica do provedor | -| 31 | `suppressBuiltInModel` | Supressão de modelo upstream obsoleto com dica de erro opcional voltada ao usuário | O provedor precisa ocultar linhas obsoletas do upstream ou substituí-las por uma dica do fornecedor | -| 32 | `augmentModelCatalog` | Linhas sintéticas/finais de catálogo acrescentadas após a descoberta | O provedor precisa de linhas sintéticas de compatibilidade futura em `models list` e seletores | -| 33 | `isBinaryThinking` | Alternância de raciocínio ligado/desligado para provedores com raciocínio binário | O provedor expõe apenas raciocínio binário ligado/desligado | -| 34 | `supportsXHighThinking` | Suporte a raciocínio `xhigh` para modelos selecionados | O provedor quer `xhigh` apenas em um subconjunto de modelos | -| 35 | `resolveDefaultThinkingLevel` | Nível padrão de `/think` para uma família específica de modelos | O provedor é responsável pela política padrão de `/think` para uma família de modelos | -| 36 | `isModernModelRef` | Correspondência de modelo moderno para filtros de perfil live e seleção de smoke | O provedor é responsável pela correspondência de modelo preferido para live/smoke | -| 37 | `prepareRuntimeAuth` | Troca uma credencial configurada pelo token/chave real de runtime pouco antes da inferência | O provedor precisa de uma troca de token ou de uma credencial de solicitação de curta duração | -| 38 | `resolveUsageAuth` | Resolve credenciais de uso/faturamento para `/usage` e superfícies relacionadas de status | O provedor precisa de parsing personalizado de token de uso/cota ou de uma credencial de uso diferente | -| 39 | `fetchUsageSnapshot` | Busca e normaliza snapshots de uso/cota específicos do provedor depois que a autenticação é resolvida | O provedor precisa de um endpoint de uso específico do provedor ou de um parser de payload | -| 40 | `createEmbeddingProvider` | Cria um adaptador de embeddings pertencente ao provedor para memória/pesquisa | O comportamento de embeddings de memória pertence ao plugin do provedor | -| 41 | `buildReplayPolicy` | Retorna uma política de replay que controla o tratamento de transcrição para o provedor | O provedor precisa de uma política personalizada de transcrição, por exemplo, remoção de blocos de raciocínio | -| 42 | `sanitizeReplayHistory` | Reescreve o histórico de replay após a limpeza genérica de transcrição | O provedor precisa de reescritas de replay específicas do provedor além dos auxiliares compartilhados de compactação | -| 43 | `validateReplayTurns` | Validação final ou remodelagem dos turnos de replay antes do embedded runner | O transporte do provedor precisa de validação mais rígida dos turnos após a sanitização genérica | -| 44 | `onModelSelected` | Executa efeitos colaterais pós-seleção pertencentes ao provedor | O provedor precisa de telemetria ou estado pertencente ao provedor quando um modelo se torna ativo | +| # | Hook | O que faz | Quando usar | +| --- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | `catalog` | Publica a configuração do provedor em `models.providers` durante a geração de `models.json` | O provedor é responsável por um catálogo ou por padrões de URL base | +| 2 | `applyConfigDefaults` | Aplica padrões globais de configuração pertencentes ao provedor durante a materialização da configuração | Os padrões dependem do modo de autenticação, env ou da semântica da família de modelos do provedor | +| -- | _(built-in model lookup)_ | O OpenClaw tenta primeiro o caminho normal de registry/catálogo | _(não é um hook de plugin)_ | +| 3 | `normalizeModelId` | Normaliza aliases legados ou de preview de IDs de modelo antes da busca | O provedor é responsável pela limpeza de aliases antes da resolução canônica do modelo | +| 4 | `normalizeTransport` | Normaliza `api` / `baseUrl` da família do provedor antes da montagem genérica do modelo | O provedor é responsável pela limpeza do transporte para IDs de provedor personalizados na mesma família de transporte | +| 5 | `normalizeConfig` | Normaliza `models.providers.` antes da resolução em runtime/do provedor | O provedor precisa de limpeza de configuração que deve ficar junto com o plugin; auxiliares incluídos da família Google também dão suporte a entradas de configuração do Google compatíveis | +| 6 | `applyNativeStreamingUsageCompat` | Aplica reescritas de compatibilidade de uso de streaming nativo a provedores de configuração | O provedor precisa de correções de metadados de uso de streaming nativo orientadas por endpoint | +| 7 | `resolveConfigApiKey` | Resolve autenticação por marcador de env para provedores de configuração antes do carregamento da autenticação em runtime | O provedor tem resolução de chave de API por marcador de env pertencente ao provedor; `amazon-bedrock` também tem aqui um resolvedor integrado de marcador de env da AWS | +| 8 | `resolveSyntheticAuth` | Expõe autenticação local/self-hosted ou baseada em configuração sem persistir texto simples | O provedor pode operar com um marcador de credencial sintética/local | +| 9 | `resolveExternalAuthProfiles` | Sobrepõe perfis externos de autenticação pertencentes ao provedor; o `persistence` padrão é `runtime-only` para credenciais pertencentes à CLI/ao app | O provedor reutiliza credenciais externas de autenticação sem persistir tokens de refresh copiados | +| 10 | `shouldDeferSyntheticProfileAuth` | Rebaixa placeholders armazenados de perfis sintéticos abaixo da autenticação baseada em env/configuração | O provedor armazena perfis placeholder sintéticos que não devem ter precedência | +| 11 | `resolveDynamicModel` | Fallback síncrono para IDs de modelo pertencentes ao provedor que ainda não estão no registry local | O provedor aceita IDs arbitrários de modelos upstream | +| 12 | `prepareDynamicModel` | Aquecimento assíncrono; depois, `resolveDynamicModel` é executado novamente | O provedor precisa de metadados de rede antes de resolver IDs desconhecidos | +| 13 | `normalizeResolvedModel` | Reescrita final antes de o runner incorporado usar o modelo resolvido | O provedor precisa de reescritas de transporte, mas ainda usa um transporte do core | +| 14 | `contributeResolvedModelCompat` | Contribui com flags de compatibilidade para modelos de fornecedor por trás de outro transporte compatível | O provedor reconhece seus próprios modelos em transportes proxy sem assumir o controle do provedor | +| 15 | `capabilities` | Metadados de transcrição/ferramentas pertencentes ao provedor usados pela lógica compartilhada do core | O provedor precisa de peculiaridades de transcrição/família de provedor | +| 16 | `normalizeToolSchemas` | Normaliza schemas de ferramentas antes de o runner incorporado vê-los | O provedor precisa de limpeza de schema da família de transporte | +| 17 | `inspectToolSchemas` | Expõe diagnósticos de schema pertencentes ao provedor após a normalização | O provedor quer avisos de palavras-chave sem ensinar regras específicas do provedor ao core | +| 18 | `resolveReasoningOutputMode` | Seleciona o contrato de saída de raciocínio nativo versus marcado | O provedor precisa de saída final/de raciocínio marcada em vez de campos nativos | +| 19 | `prepareExtraParams` | Normalização de parâmetros de requisição antes de wrappers genéricos de opções de stream | O provedor precisa de parâmetros padrão de requisição ou limpeza de parâmetros por provedor | +| 20 | `createStreamFn` | Substitui totalmente o caminho normal de stream por um transporte personalizado | O provedor precisa de um protocolo de transporte personalizado, e não apenas de um wrapper | +| 21 | `wrapStreamFn` | Wrapper de stream após a aplicação dos wrappers genéricos | O provedor precisa de wrappers de compatibilidade para cabeçalhos/corpo/modelo de requisição sem um transporte personalizado | +| 22 | `resolveTransportTurnState` | Anexa cabeçalhos ou metadados nativos por turno do transporte | O provedor quer que transportes genéricos enviem identidade de turno nativa do provedor | +| 23 | `resolveWebSocketSessionPolicy` | Anexa cabeçalhos nativos de WebSocket ou política de resfriamento de sessão | O provedor quer que transportes WS genéricos ajustem cabeçalhos de sessão ou política de fallback | +| 24 | `formatApiKey` | Formatador de perfil de autenticação: o perfil armazenado se torna a string `apiKey` em runtime | O provedor armazena metadados extras de autenticação e precisa de um formato personalizado de token em runtime | +| 25 | `refreshOAuth` | Substituição da atualização de OAuth para endpoints personalizados de refresh ou política de falha na atualização | O provedor não se encaixa nos atualizadores compartilhados de `pi-ai` | +| 26 | `buildAuthDoctorHint` | Dica de reparo anexada quando a atualização de OAuth falha | O provedor precisa de orientação de reparo de autenticação pertencente ao provedor após falha na atualização | +| 27 | `matchesContextOverflowError` | Correspondência de overflow de janela de contexto pertencente ao provedor | O provedor tem erros brutos de overflow que heurísticas genéricas não detectariam | +| 28 | `classifyFailoverReason` | Classificação do motivo de failover pertencente ao provedor | O provedor pode mapear erros brutos de API/transporte para limite de taxa/sobrecarga/etc. | +| 29 | `isCacheTtlEligible` | Política de cache de prompt para provedores proxy/backhaul | O provedor precisa de controle de TTL de cache específico de proxy | +| 30 | `buildMissingAuthMessage` | Substituição para a mensagem genérica de recuperação de autenticação ausente | O provedor precisa de uma dica de recuperação de autenticação ausente específica do provedor | +| 31 | `suppressBuiltInModel` | Supressão de modelo upstream desatualizado mais dica opcional de erro voltada ao usuário | O provedor precisa ocultar linhas upstream desatualizadas ou substituí-las por uma dica do fornecedor | +| 32 | `augmentModelCatalog` | Linhas sintéticas/finais de catálogo anexadas após a descoberta | O provedor precisa de linhas sintéticas de compatibilidade futura em `models list` e seletores | +| 33 | `isBinaryThinking` | Alternância de raciocínio ligado/desligado para provedores de raciocínio binário | O provedor expõe apenas raciocínio binário ligado/desligado | +| 34 | `supportsXHighThinking` | Suporte a raciocínio `xhigh` para modelos selecionados | O provedor quer `xhigh` apenas em um subconjunto de modelos | +| 35 | `resolveDefaultThinkingLevel` | Nível padrão de `/think` para uma família de modelos específica | O provedor é responsável pela política padrão de `/think` para uma família de modelos | +| 36 | `isModernModelRef` | Correspondência de modelo moderno para filtros de perfil ao vivo e seleção de smoke | O provedor é responsável pela correspondência de modelo preferido para testes ao vivo/smoke | +| 37 | `prepareRuntimeAuth` | Troca uma credencial configurada pelo token/chave real de runtime imediatamente antes da inferência | O provedor precisa de uma troca de token ou de uma credencial de requisição de curta duração | +| 38 | `resolveUsageAuth` | Resolve credenciais de uso/faturamento para `/usage` e superfícies relacionadas de status | O provedor precisa de parsing personalizado de token de uso/cota ou de uma credencial de uso diferente | +| 39 | `fetchUsageSnapshot` | Busca e normaliza snapshots de uso/cota específicos do provedor após a resolução da autenticação | O provedor precisa de um endpoint de uso específico do provedor ou de um parser de payload | +| 40 | `createEmbeddingProvider` | Cria um adaptador de embeddings pertencente ao provedor para memória/pesquisa | O comportamento de embeddings de memória pertence ao plugin do provedor | +| 41 | `buildReplayPolicy` | Retorna uma política de replay que controla o tratamento da transcrição para o provedor | O provedor precisa de uma política de transcrição personalizada (por exemplo, remoção de blocos de raciocínio) | +| 42 | `sanitizeReplayHistory` | Reescreve o histórico de replay após a limpeza genérica da transcrição | O provedor precisa de reescritas de replay específicas do provedor além dos auxiliares compartilhados de compactação | +| 43 | `validateReplayTurns` | Validação final ou remodelagem dos turnos de replay antes do runner incorporado | O transporte do provedor precisa de validação mais rígida dos turnos após a sanitização genérica | +| 44 | `onModelSelected` | Executa efeitos colaterais pós-seleção pertencentes ao provedor | O provedor precisa de telemetria ou de estado pertencente ao provedor quando um modelo se torna ativo | `normalizeModelId`, `normalizeTransport` e `normalizeConfig` primeiro verificam o -plugin de provedor correspondente e depois passam por outros plugins de provedor com suporte a hooks -até que um deles realmente altere o id do modelo ou o transporte/configuração. Isso mantém -funcionando os shims de alias/provedor compatível sem exigir que o chamador saiba qual -plugin embutido é responsável pela reescrita. Se nenhum hook de provedor reescrever uma entrada de -configuração compatível da família Google, o normalizador de configuração embutido do Google ainda aplicará -essa limpeza de compatibilidade. +plugin de provedor correspondente e depois passam pelos outros plugins de provedor capazes de usar hooks +até que um realmente altere o ID do modelo ou o transporte/configuração. Isso mantém +shims de alias/provedor compatível funcionando sem exigir que o chamador saiba qual +plugin incluído é responsável pela reescrita. Se nenhum hook de provedor reescrever uma entrada de configuração compatível da +família Google, o normalizador de configuração incluído do Google ainda aplica essa limpeza de compatibilidade. -Se o provedor precisar de um protocolo de transporte totalmente personalizado ou de um executor de requisição personalizado, +Se o provedor precisar de um protocolo de comunicação totalmente personalizado ou de um executor de requisição personalizado, essa é uma classe diferente de extensão. Esses hooks são para comportamento de provedor que ainda é executado no loop normal de inferência do OpenClaw. @@ -781,114 +784,110 @@ api.registerProvider({ }); ``` -### Exemplos embutidos +### Exemplos incluídos - Anthropic usa `resolveDynamicModel`, `capabilities`, `buildAuthDoctorHint`, `resolveUsageAuth`, `fetchUsageSnapshot`, `isCacheTtlEligible`, `resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef` - e `wrapStreamFn` porque é responsável por forward-compat do Claude 4.6, - dicas da família de provedores, orientação de reparo de autenticação, integração - com endpoint de uso, elegibilidade de cache de prompt, padrões de configuração com reconhecimento - de autenticação, política padrão/adaptativa de pensamento do Claude e modelagem de stream - específica da Anthropic para headers beta, `/fast` / `serviceTier` e `context1m`. -- Os auxiliares de stream específicos do Claude da Anthropic permanecem, por enquanto, no - próprio seam público `api.ts` / `contract-api.ts` do plugin embutido. Essa superfície do pacote + e `wrapStreamFn` porque é responsável por compatibilidade futura com Claude 4.6, + dicas de família de provedor, orientação de reparo de autenticação, integração + com endpoint de uso, elegibilidade de cache de prompt, padrões de configuração com reconhecimento de autenticação, política + padrão/adaptativa de raciocínio do Claude e modelagem de stream específica da Anthropic para + cabeçalhos beta, `/fast` / `serviceTier` e `context1m`. +- Os auxiliares de stream específicos do Claude da Anthropic permanecem, por enquanto, no próprio + seam público `api.ts` / `contract-api.ts` do plugin incluído. Essa superfície do pacote exporta `wrapAnthropicProviderStream`, `resolveAnthropicBetas`, `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` e os builders de wrapper - de Anthropic de nível mais baixo, em vez de ampliar o SDK genérico em torno das regras de - headers beta de um único provedor. + de nível inferior da Anthropic, em vez de ampliar o SDK genérico em torno das regras de cabeçalho beta + de um único provedor. - OpenAI usa `resolveDynamicModel`, `normalizeResolvedModel` e `capabilities`, além de `buildMissingAuthMessage`, `suppressBuiltInModel`, - `augmentModelCatalog`, `supportsXHighThinking` e `isModernModelRef`, - porque é responsável por forward-compat do GPT-5.4, pela normalização direta da OpenAI - de `openai-completions` -> `openai-responses`, por dicas de autenticação com reconhecimento - do Codex, supressão do Spark, linhas sintéticas da OpenAI em listas e pela política de pensamento / - modelo live do GPT-5; a família de streams `openai-responses-defaults` é responsável pelos - wrappers nativos compartilhados do OpenAI Responses para headers de atribuição, - `/fast`/`serviceTier`, verbosidade de texto, pesquisa nativa na web do Codex, + `augmentModelCatalog`, `supportsXHighThinking` e `isModernModelRef` + porque é responsável por compatibilidade futura com GPT-5.4, pela normalização direta da OpenAI de + `openai-completions` -> `openai-responses`, dicas de autenticação com reconhecimento de Codex, + supressão do Spark, linhas sintéticas da lista OpenAI e política de raciocínio / modelo ao vivo do GPT-5; a família de stream `openai-responses-defaults` é responsável pelos + wrappers nativos compartilhados do OpenAI Responses para cabeçalhos de atribuição, + `/fast`/`serviceTier`, verbosidade de texto, pesquisa na web nativa do Codex, modelagem de payload de compatibilidade de raciocínio e gerenciamento de contexto do Responses. - OpenRouter usa `catalog`, além de `resolveDynamicModel` e `prepareDynamicModel`, porque o provedor é pass-through e pode expor novos - ids de modelo antes que o catálogo estático do OpenClaw seja atualizado; ele também usa + IDs de modelo antes das atualizações do catálogo estático do OpenClaw; também usa `capabilities`, `wrapStreamFn` e `isCacheTtlEligible` para manter - fora do core headers de requisição específicos do provedor, metadados de roteamento, patches - de raciocínio e política de cache de prompt. Sua política de replay vem da - família `passthrough-gemini`, enquanto a família de streams `openrouter-thinking` - é responsável pela injeção de raciocínio no proxy e pelos skips de modelos não compatíveis / `auto`. + cabeçalhos de requisição específicos do provedor, metadados de roteamento, patches de raciocínio e + política de cache de prompt fora do core. Sua política de replay vem da + família `passthrough-gemini`, enquanto a família de stream `openrouter-thinking` + é responsável pela injeção de raciocínio via proxy e pelos ignoramentos de modelo não suportado / `auto`. - GitHub Copilot usa `catalog`, `auth`, `resolveDynamicModel` e `capabilities`, além de `prepareRuntimeAuth` e `fetchUsageSnapshot`, porque - precisa de login por dispositivo pertencente ao provedor, comportamento de fallback de modelo, - particularidades de transcrição do Claude, troca de token GitHub -> token Copilot - e um endpoint de uso pertencente ao provedor. + precisa de login por dispositivo pertencente ao provedor, comportamento de fallback de modelo, peculiaridades + de transcrição do Claude, troca de token GitHub -> token Copilot e um endpoint de uso pertencente ao provedor. - OpenAI Codex usa `catalog`, `resolveDynamicModel`, `normalizeResolvedModel`, `refreshOAuth` e `augmentModelCatalog`, além de `prepareExtraParams`, `resolveUsageAuth` e `fetchUsageSnapshot`, porque ainda é executado nos transportes OpenAI do core, mas é responsável por sua normalização - de transporte/base URL, política de fallback de refresh OAuth, escolha de transporte padrão, - linhas sintéticas de catálogo do Codex e integração com endpoint de uso do ChatGPT; ele - compartilha a mesma família de streams `openai-responses-defaults` da OpenAI direta. + de transporte/URL base, política de fallback de atualização de OAuth, escolha padrão + de transporte, linhas sintéticas de catálogo do Codex e integração com endpoint de uso do ChatGPT; ele + compartilha a mesma família de stream `openai-responses-defaults` da OpenAI direta. - Google AI Studio e Gemini CLI OAuth usam `resolveDynamicModel`, `buildReplayPolicy`, `sanitizeReplayHistory`, `resolveReasoningOutputMode`, `wrapStreamFn` e `isModernModelRef` porque a - família de replay `google-gemini` é responsável por fallback de forward-compat do Gemini 3.1, - validação nativa de replay do Gemini, sanitização de replay de bootstrap, modo - de saída de raciocínio com tags e correspondência de modelo moderno, enquanto a - família de streams `google-thinking` é responsável pela normalização do payload de pensamento do Gemini; + família de replay `google-gemini` é responsável pelo fallback de compatibilidade futura do Gemini 3.1, + validação nativa de replay do Gemini, sanitização de replay na inicialização, modo + de saída de raciocínio marcada e correspondência de modelos modernos, enquanto a + família de stream `google-thinking` é responsável pela normalização do payload de raciocínio do Gemini; Gemini CLI OAuth também usa `formatApiKey`, `resolveUsageAuth` e - `fetchUsageSnapshot` para formatação de token, parsing de token e ligação - com endpoint de cota. + `fetchUsageSnapshot` para formatação de token, parsing de token e + wiring do endpoint de cota. - Anthropic Vertex usa `buildReplayPolicy` por meio da - família de replay `anthropic-by-model`, para que a limpeza de replay específica do Claude fique - limitada a ids do Claude em vez de a todo transporte `anthropic-messages`. + família de replay `anthropic-by-model`, para que a limpeza de replay específica do Claude permaneça + restrita a IDs do Claude em vez de todo transporte `anthropic-messages`. - Amazon Bedrock usa `buildReplayPolicy`, `matchesContextOverflowError`, - `classifyFailoverReason` e `resolveDefaultThinkingLevel`, porque é responsável - pela classificação específica do Bedrock de erros de throttle/not-ready/context-overflow - para tráfego Anthropic-on-Bedrock; sua política de replay ainda compartilha a mesma proteção - `anthropic-by-model` exclusiva do Claude. + `classifyFailoverReason` e `resolveDefaultThinkingLevel` porque é responsável pela classificação de erros específicos do Bedrock de throttling/não pronto/overflow de contexto + para tráfego Anthropic-on-Bedrock; sua política de replay ainda compartilha a mesma + proteção somente para Claude `anthropic-by-model`. - OpenRouter, Kilocode, Opencode e Opencode Go usam `buildReplayPolicy` por meio da família de replay `passthrough-gemini`, porque fazem proxy de modelos Gemini - por transportes compatíveis com OpenAI e precisam de sanitização de assinatura de pensamento - do Gemini sem validação nativa de replay do Gemini nem reescritas de bootstrap. + por transportes compatíveis com OpenAI e precisam de sanitização de assinatura de pensamento do Gemini + sem validação nativa de replay do Gemini nem reescritas de inicialização. - MiniMax usa `buildReplayPolicy` por meio da - família de replay `hybrid-anthropic-openai`, porque um provedor é responsável por semânticas - tanto de mensagens Anthropic quanto compatíveis com OpenAI; ele mantém a remoção de - blocos de pensamento exclusivos do Claude no lado Anthropic, enquanto substitui o modo de - saída de raciocínio de volta para nativo, e a família de streams `minimax-fast-mode` é responsável por - reescritas de modelos fast-mode no caminho de stream compartilhado. + família de replay `hybrid-anthropic-openai`, porque um provedor é responsável tanto pela semântica + de mensagens Anthropic quanto pela semântica compatível com OpenAI; ele mantém + a remoção de blocos de pensamento somente do Claude no lado Anthropic, enquanto substitui o modo de + saída de raciocínio de volta para nativo, e a família de stream `minimax-fast-mode` é responsável pelas reescritas de modelos + de modo rápido no caminho compartilhado de stream. - Moonshot usa `catalog`, além de `wrapStreamFn`, porque ainda usa o transporte - OpenAI compartilhado, mas precisa de normalização de payload de pensamento pertencente ao provedor; a - família de streams `moonshot-thinking` mapeia configuração mais estado de `/think` para seu - payload nativo de pensamento binário. + compartilhado da OpenAI, mas precisa de normalização de payload de raciocínio pertencente ao provedor; a + família de stream `moonshot-thinking` mapeia configuração mais estado de `/think` para seu + payload nativo de raciocínio binário. - Kilocode usa `catalog`, `capabilities`, `wrapStreamFn` e - `isCacheTtlEligible`, porque precisa de headers de requisição pertencentes ao provedor, - normalização de payload de raciocínio, dicas de transcrição do Gemini e controle de TTL de cache - da Anthropic; a família de streams `kilocode-thinking` mantém a injeção de pensamento do Kilo - no caminho de stream proxy compartilhado, enquanto ignora `kilo/auto` e - outros ids de modelo proxy que não aceitam payloads explícitos de raciocínio. + `isCacheTtlEligible` porque precisa de cabeçalhos de requisição pertencentes ao provedor, + normalização de payload de raciocínio, dicas de transcrição do Gemini e controle de + TTL de cache da Anthropic; a família de stream `kilocode-thinking` mantém a injeção de raciocínio do Kilo + no caminho compartilhado de stream por proxy, enquanto ignora `kilo/auto` e + outros IDs de modelo proxy que não suportam payloads explícitos de raciocínio. - Z.AI usa `resolveDynamicModel`, `prepareExtraParams`, `wrapStreamFn`, `isCacheTtlEligible`, `isBinaryThinking`, `isModernModelRef`, - `resolveUsageAuth` e `fetchUsageSnapshot`, porque é responsável por fallback do GLM-5, - padrões de `tool_stream`, UX de pensamento binário, correspondência de modelo moderno e por - autenticação de uso + busca de cota; a família de streams `tool-stream-default-on` mantém - o wrapper de `tool_stream` ativado por padrão fora da cola manual por provedor. + `resolveUsageAuth` e `fetchUsageSnapshot` porque é responsável pelo fallback do GLM-5, + pelos padrões de `tool_stream`, UX de raciocínio binário, correspondência de modelos modernos e por autenticação de uso + busca de cota; a família de stream `tool-stream-default-on` mantém o wrapper + padrão ligado de `tool_stream` fora de glue manual por provedor. - xAI usa `normalizeResolvedModel`, `normalizeTransport`, `contributeResolvedModelCompat`, `prepareExtraParams`, `wrapStreamFn`, - `resolveSyntheticAuth`, `resolveDynamicModel` e `isModernModelRef`, - porque é responsável pela normalização nativa de transporte do xAI Responses, reescritas - de aliases fast-mode do Grok, `tool_stream` padrão, limpeza de ferramenta estrita / payload - de raciocínio, reutilização de autenticação fallback para ferramentas pertencentes ao plugin, resolução - de forward-compat de modelos Grok e patches de compatibilidade pertencentes ao provedor, como perfil - de esquema de ferramenta do xAI, palavras-chave de esquema não compatíveis, `web_search` nativo e - decodificação de argumentos de chamadas de ferramenta com entidades HTML. -- Mistral, OpenCode Zen e OpenCode Go usam apenas `capabilities` - para manter particularidades de transcrição/ferramentas fora do core. -- Provedores embutidos somente de catálogo, como `byteplus`, `cloudflare-ai-gateway`, + `resolveSyntheticAuth`, `resolveDynamicModel` e `isModernModelRef` + porque é responsável pela normalização nativa do transporte xAI Responses, reescritas de alias + do modo rápido do Grok, `tool_stream` padrão, limpeza estrita de ferramenta / payload de raciocínio, + reutilização de autenticação de fallback para ferramentas pertencentes ao plugin, resolução de modelo Grok + compatível com versões futuras e patches de compatibilidade pertencentes ao provedor, como perfil de schema de ferramentas da xAI, + palavras-chave de schema não suportadas, `web_search` nativo e decodificação + de entidades HTML em argumentos de chamadas de ferramenta. +- Mistral, OpenCode Zen e OpenCode Go usam apenas `capabilities` para manter + peculiaridades de transcrição/ferramentas fora do core. +- Provedores incluídos somente de catálogo, como `byteplus`, `cloudflare-ai-gateway`, `huggingface`, `kimi-coding`, `nvidia`, `qianfan`, `synthetic`, `together`, `venice`, `vercel-ai-gateway` e `volcengine`, usam apenas `catalog`. -- Qwen usa `catalog` para seu provedor de texto, além de registros compartilhados de - compreensão de mídia e geração de vídeo para suas superfícies multimodais. -- MiniMax e Xiaomi usam `catalog`, além de hooks de uso, porque seu comportamento de `/usage` +- Qwen usa `catalog` para seu provedor de texto, além de registros compartilhados de media-understanding e + video-generation para suas superfícies multimodais. +- MiniMax e Xiaomi usam `catalog` mais hooks de uso porque seu comportamento de `/usage` pertence ao plugin, embora a inferência ainda seja executada pelos transportes compartilhados. ## Auxiliares de runtime @@ -916,9 +915,9 @@ Observações: - `textToSpeech` retorna o payload normal de saída de TTS do core para superfícies de arquivo/mensagem de voz. - Usa a configuração `messages.tts` do core e a seleção de provedor. -- Retorna buffer de áudio PCM + sample rate. Plugins devem fazer resampling/codificação para provedores. -- `listVoices` é opcional por provedor. Use-o para seletores de voz ou fluxos de configuração pertencentes ao fornecedor. -- Listagens de voz podem incluir metadados mais ricos, como locale, gender e tags de personalidade para seletores com reconhecimento do provedor. +- Retorna buffer de áudio PCM + taxa de amostragem. Plugins devem reamostrar/codificar para provedores. +- `listVoices` é opcional por provedor. Use-o para seletores de voz pertencentes ao fornecedor ou fluxos de configuração. +- Listagens de vozes podem incluir metadados mais ricos, como localidade, gênero e tags de personalidade para seletores com reconhecimento de provedor. - OpenAI e ElevenLabs oferecem suporte a telefonia hoje. Microsoft não. Plugins também podem registrar provedores de fala via `api.registerSpeechProvider(...)`. @@ -943,13 +942,13 @@ Observações: - Mantenha política de TTS, fallback e entrega de resposta no core. - Use provedores de fala para comportamento de síntese pertencente ao fornecedor. -- A entrada legada `edge` da Microsoft é normalizada para o id de provedor `microsoft`. -- O modelo de propriedade preferido é orientado à empresa: um único plugin de fornecedor pode ser responsável por - provedores de texto, fala, imagem e mídia futura à medida que o OpenClaw adicionar esses +- A entrada legada `edge` da Microsoft é normalizada para o ID de provedor `microsoft`. +- O modelo de propriedade preferido é orientado por empresa: um plugin de fornecedor pode ser responsável por + texto, fala, imagem e futuros provedores de mídia à medida que o OpenClaw adiciona esses contratos de capacidade. -Para compreensão de imagem/áudio/vídeo, plugins registram um provedor tipado único de -compreensão de mídia em vez de um saco genérico de chave/valor: +Para entendimento de imagem/áudio/vídeo, plugins registram um provedor tipado de +media-understanding em vez de um pacote genérico de chave/valor: ```ts api.registerMediaUnderstandingProvider({ @@ -963,16 +962,16 @@ api.registerMediaUnderstandingProvider({ Observações: -- Mantenha orquestração, fallback, configuração e integração com canais no core. +- Mantenha orquestração, fallback, configuração e wiring de canal no core. - Mantenha o comportamento do fornecedor no plugin do provedor. -- A expansão aditiva deve permanecer tipada: novos métodos opcionais, novos campos opcionais - de resultado, novas capacidades opcionais. +- A expansão aditiva deve permanecer tipada: novos métodos opcionais, novos + campos de resultado opcionais, novas capacidades opcionais. - A geração de vídeo já segue o mesmo padrão: - o core é responsável pelo contrato de capacidade e pelo auxiliar de runtime - - plugins de fornecedor registram `api.registerVideoGenerationProvider(...)` + - plugins de fornecedores registram `api.registerVideoGenerationProvider(...)` - plugins de recurso/canal consomem `api.runtime.videoGeneration.*` -Para auxiliares de runtime de compreensão de mídia, plugins podem chamar: +Para auxiliares de runtime de media-understanding, plugins podem chamar: ```ts const image = await api.runtime.mediaUnderstanding.describeImageFile({ @@ -987,7 +986,7 @@ const video = await api.runtime.mediaUnderstanding.describeVideoFile({ }); ``` -Para transcrição de áudio, plugins podem usar o runtime de compreensão de mídia +Para transcrição de áudio, plugins podem usar o runtime de media-understanding ou o alias STT mais antigo: ```ts @@ -1002,10 +1001,10 @@ const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ Observações: - `api.runtime.mediaUnderstanding.*` é a superfície compartilhada preferida para - compreensão de imagem/áudio/vídeo. -- Usa a configuração de áudio de compreensão de mídia do core (`tools.media.audio`) e a ordem de fallback do provedor. -- Retorna `{ text: undefined }` quando nenhuma saída de transcrição é produzida (por exemplo, entrada ignorada/não compatível). -- `api.runtime.stt.transcribeAudioFile(...)` permanece como alias de compatibilidade. + entendimento de imagem/áudio/vídeo. +- Usa a configuração de áudio de media-understanding do core (`tools.media.audio`) e a ordem de fallback do provedor. +- Retorna `{ text: undefined }` quando nenhuma saída de transcrição é produzida (por exemplo, entrada ignorada/não suportada). +- `api.runtime.stt.transcribeAudioFile(...)` permanece como um alias de compatibilidade. Plugins também podem iniciar execuções de subagente em segundo plano por meio de `api.runtime.subagent`: @@ -1021,14 +1020,14 @@ const result = await api.runtime.subagent.run({ Observações: -- `provider` e `model` são substituições opcionais por execução, não alterações persistentes de sessão. +- `provider` e `model` são substituições opcionais por execução, não mudanças persistentes de sessão. - O OpenClaw só respeita esses campos de substituição para chamadores confiáveis. -- Para execuções de fallback pertencentes ao plugin, operadores precisam ativar explicitamente com `plugins.entries..subagent.allowModelOverride: true`. -- Use `plugins.entries..subagent.allowedModels` para restringir plugins confiáveis a alvos canônicos específicos `provider/model`, ou `"*"` para permitir explicitamente qualquer alvo. -- Execuções de subagente de plugins não confiáveis continuam funcionando, mas solicitações de substituição são rejeitadas em vez de silenciosamente fazer fallback. +- Para execuções de fallback pertencentes ao plugin, operadores precisam optar por isso com `plugins.entries..subagent.allowModelOverride: true`. +- Use `plugins.entries..subagent.allowedModels` para restringir plugins confiáveis a destinos canônicos específicos `provider/model`, ou `"*"` para permitir explicitamente qualquer destino. +- Execuções de subagente de plugins não confiáveis ainda funcionam, mas solicitações de substituição são rejeitadas em vez de cair silenciosamente em fallback. -Para pesquisa na web, plugins podem consumir o auxiliar de runtime compartilhado em vez de -acessar diretamente a integração da ferramenta do agente: +Para pesquisa na web, plugins podem consumir o auxiliar compartilhado de runtime em vez de +acessar o wiring da ferramenta do agente: ```ts const providers = api.runtime.webSearch.listProviders({ @@ -1067,7 +1066,7 @@ const providers = api.runtime.imageGeneration.listProviders({ ``` - `generate(...)`: gera uma imagem usando a cadeia configurada de provedores de geração de imagem. -- `listProviders(...)`: lista provedores disponíveis de geração de imagem e suas capacidades. +- `listProviders(...)`: lista os provedores de geração de imagem disponíveis e suas capacidades. ## Rotas HTTP do Gateway @@ -1089,32 +1088,32 @@ api.registerHttpRoute({ Campos da rota: - `path`: caminho da rota sob o servidor HTTP do gateway. -- `auth`: obrigatório. Use `"gateway"` para exigir a autenticação normal do gateway, ou `"plugin"` para autenticação/validação de webhook gerenciada pelo plugin. +- `auth`: obrigatório. Use `"gateway"` para exigir a autenticação normal do gateway, ou `"plugin"` para autenticação gerenciada por plugin/verificação de webhook. - `match`: opcional. `"exact"` (padrão) ou `"prefix"`. - `replaceExisting`: opcional. Permite que o mesmo plugin substitua seu próprio registro de rota existente. - `handler`: retorne `true` quando a rota tiver tratado a requisição. Observações: -- `api.registerHttpHandler(...)` foi removido e causará um erro de carregamento do plugin. Use `api.registerHttpRoute(...)` em vez disso. +- `api.registerHttpHandler(...)` foi removido e causará um erro de carregamento do plugin. Use `api.registerHttpRoute(...)` no lugar. - Rotas de plugin devem declarar `auth` explicitamente. - Conflitos exatos de `path + match` são rejeitados, a menos que `replaceExisting: true`, e um plugin não pode substituir a rota de outro plugin. -- Rotas sobrepostas com diferentes níveis de `auth` são rejeitadas. Mantenha cadeias de fallthrough `exact`/`prefix` apenas no mesmo nível de autenticação. -- Rotas `auth: "plugin"` **não** recebem automaticamente escopos de runtime do operador. Elas servem para webhooks/validação de assinatura gerenciados pelo plugin, não para chamadas privilegiadas de auxiliares do Gateway. +- Rotas sobrepostas com níveis de `auth` diferentes são rejeitadas. Mantenha cadeias de fallback `exact`/`prefix` apenas no mesmo nível de autenticação. +- Rotas `auth: "plugin"` **não** recebem automaticamente escopos de runtime do operador. Elas são para webhooks/verificação de assinatura gerenciados por plugin, não para chamadas auxiliares privilegiadas do Gateway. - Rotas `auth: "gateway"` são executadas dentro de um escopo de runtime de requisição do Gateway, mas esse escopo é intencionalmente conservador: - - autenticação bearer por segredo compartilhado (`gateway.auth.mode = "token"` / `"password"`) mantém os escopos de runtime de rotas de plugin fixados em `operator.write`, mesmo que o chamador envie `x-openclaw-scopes` - - modos HTTP confiáveis com identidade (por exemplo, `trusted-proxy` ou `gateway.auth.mode = "none"` em uma entrada privada) respeitam `x-openclaw-scopes` apenas quando o header está explicitamente presente - - se `x-openclaw-scopes` estiver ausente nessas requisições com identidade para rotas de plugin, o escopo de runtime volta para `operator.write` -- Regra prática: não assuma que uma rota de plugin autenticada pelo gateway é implicitamente uma superfície de administração. Se sua rota precisar de comportamento exclusivo de admin, exija um modo de autenticação com identidade e documente o contrato explícito do header `x-openclaw-scopes`. + - autenticação bearer por segredo compartilhado (`gateway.auth.mode = "token"` / `"password"`) mantém os escopos de runtime da rota do plugin fixos em `operator.write`, mesmo que o chamador envie `x-openclaw-scopes` + - modos HTTP confiáveis com identidade (por exemplo `trusted-proxy` ou `gateway.auth.mode = "none"` em uma entrada privada) respeitam `x-openclaw-scopes` apenas quando o cabeçalho está explicitamente presente + - se `x-openclaw-scopes` estiver ausente nessas requisições de rota de plugin com identidade, o escopo de runtime recai para `operator.write` +- Regra prática: não assuma que uma rota de plugin autenticada pelo gateway é implicitamente uma superfície de administrador. Se sua rota precisar de comportamento restrito a admin, exija um modo de autenticação com identidade e documente o contrato explícito do cabeçalho `x-openclaw-scopes`. -## Caminhos de importação do SDK de plugins +## Caminhos de importação do Plugin SDK Use subcaminhos do SDK em vez da importação monolítica `openclaw/plugin-sdk` ao criar plugins: -- `openclaw/plugin-sdk/plugin-entry` para primitivas de registro de plugins. +- `openclaw/plugin-sdk/plugin-entry` para primitivas de registro de plugin. - `openclaw/plugin-sdk/core` para o contrato genérico compartilhado voltado a plugins. -- `openclaw/plugin-sdk/config-schema` para a exportação do esquema Zod raiz de `openclaw.json` +- `openclaw/plugin-sdk/config-schema` para o export do schema Zod raiz de `openclaw.json` (`OpenClawSchema`). - Primitivas estáveis de canal, como `openclaw/plugin-sdk/channel-setup`, `openclaw/plugin-sdk/setup-runtime`, @@ -1128,11 +1127,11 @@ criar plugins: `openclaw/plugin-sdk/channel-reply-pipeline`, `openclaw/plugin-sdk/command-auth`, `openclaw/plugin-sdk/secret-input` e - `openclaw/plugin-sdk/webhook-ingress` para integração compartilhada de configuração/autenticação/resposta/webhook. - `channel-inbound` é o lar compartilhado para debounce, correspondência de menções, + `openclaw/plugin-sdk/webhook-ingress` para wiring compartilhado de + configuração/autenticação/resposta/webhook. `channel-inbound` é o local compartilhado para debounce, correspondência de menções, auxiliares de política de menção de entrada, formatação de envelope e auxiliares de contexto de envelope de entrada. - `channel-setup` é o seam estreito de configuração de instalação opcional. + `channel-setup` é o seam estreito de configuração opcional de instalação. `setup-runtime` é a superfície de configuração segura para runtime usada por `setupEntry` / inicialização adiada, incluindo os adaptadores de patch de configuração seguros para importação. `setup-adapter-runtime` é o seam de adaptador de configuração de conta com reconhecimento de env. @@ -1158,43 +1157,40 @@ criar plugins: `openclaw/plugin-sdk/text-runtime`, `openclaw/plugin-sdk/runtime-store` e `openclaw/plugin-sdk/directory-runtime` para auxiliares compartilhados de runtime/configuração. - `telegram-command-config` é o seam público estreito para normalização/validação de comandos personalizados do Telegram e continua disponível mesmo se a superfície de contrato embutida do Telegram estiver temporariamente indisponível. + `telegram-command-config` é o seam público estreito para normalização/validação de comando personalizado do Telegram e permanece disponível mesmo que a superfície de contrato incluída do Telegram esteja temporariamente indisponível. `text-runtime` é o seam compartilhado de texto/markdown/logging, incluindo - remoção de texto visível para o assistente, auxiliares de renderização/fragmentação de markdown, auxiliares de redação, + remoção de texto visível ao assistente, auxiliares de renderização/fragmentação de markdown, auxiliares de redação, auxiliares de tags de diretiva e utilitários de texto seguro. - Seams de canal específicos de aprovação devem preferir um único contrato `approvalCapability` no plugin. O core então lê autenticação de aprovação, entrega, renderização, - roteamento nativo e comportamento lazy de tratador nativo por meio dessa única + roteamento nativo e comportamento lazy de handler nativo por meio dessa única capacidade, em vez de misturar comportamento de aprovação em campos não relacionados do plugin. - `openclaw/plugin-sdk/channel-runtime` está obsoleto e permanece apenas como um - shim de compatibilidade para plugins antigos. Código novo deve importar as primitivas - genéricas mais estreitas, e o código do repositório não deve adicionar novas importações do + shim de compatibilidade para plugins mais antigos. Código novo deve importar as primitivas genéricas mais estreitas, e o código do repositório não deve adicionar novos imports do shim. -- Internos de extensões embutidas permanecem privados. Plugins externos devem usar apenas - subcaminhos `openclaw/plugin-sdk/*`. Código core/de teste do OpenClaw pode usar os +- Internos de extensões incluídas continuam privados. Plugins externos devem usar apenas subcaminhos `openclaw/plugin-sdk/*`. Código do core/teste do OpenClaw pode usar os pontos de entrada públicos do repositório sob a raiz de um pacote de plugin, como `index.js`, `api.js`, `runtime-api.js`, `setup-entry.js` e arquivos de escopo estreito, como `login-qr-api.js`. Nunca importe `src/*` de um pacote de plugin a partir do core ou de outra extensão. -- Divisão de ponto de entrada do repositório: +- Divisão do ponto de entrada do repositório: `/api.js` é o barrel de auxiliares/tipos, `/runtime-api.js` é o barrel somente de runtime, - `/index.js` é a entrada do plugin embutido, + `/index.js` é a entrada do plugin incluído, e `/setup-entry.js` é a entrada do plugin de configuração. -- Exemplos atuais de provedores embutidos: +- Exemplos atuais de provedores incluídos: - Anthropic usa `api.js` / `contract-api.js` para auxiliares de stream do Claude, como - `wrapAnthropicProviderStream`, auxiliares de header beta e parsing de `service_tier`. + `wrapAnthropicProviderStream`, auxiliares de cabeçalho beta e parsing de `service_tier`. - OpenAI usa `api.js` para builders de provedor, auxiliares de modelo padrão e builders de provedor em tempo real. - OpenRouter usa `api.js` para seu builder de provedor, além de auxiliares de onboarding/configuração, - enquanto `register.runtime.js` ainda pode reexportar auxiliares genéricos de - `plugin-sdk/provider-stream` para uso local do repositório. -- Pontos de entrada públicos carregados por façade preferem o snapshot ativo de configuração de runtime - quando ele existe, e depois recorrem ao arquivo de configuração resolvido em disco quando o + enquanto `register.runtime.js` ainda pode reexportar auxiliares genéricos + `plugin-sdk/provider-stream` para uso local no repositório. +- Pontos de entrada públicos carregados por facade preferem o snapshot de configuração de runtime ativo + quando ele existe e, em seguida, recorrem ao arquivo de configuração resolvido em disco quando o OpenClaw ainda não está servindo um snapshot de runtime. -- Primitivas genéricas compartilhadas continuam sendo o contrato público preferido do SDK. Ainda - existe um pequeno conjunto reservado de compatibilidade de seams auxiliares com marca de canais embutidos. - Trate-os como seams de manutenção/compatibilidade embutida, não como novos alvos de importação de terceiros; novos contratos entre canais ainda devem chegar em subcaminhos genéricos `plugin-sdk/*` ou nos barrels locais do plugin `api.js` / +- Primitivas genéricas compartilhadas continuam sendo o contrato público preferido do SDK. Ainda existe um pequeno + conjunto reservado de compatibilidade de seams auxiliares com marca de canal incluído. Trate-os como seams de manutenção/compatibilidade de incluídos, não como novos alvos de importação de terceiros; novos contratos entre canais ainda devem ficar em subcaminhos genéricos `plugin-sdk/*` ou nos barrels locais do plugin `api.js` / `runtime-api.js`. Observação de compatibilidade: @@ -1202,83 +1198,81 @@ Observação de compatibilidade: - Evite o barrel raiz `openclaw/plugin-sdk` em código novo. - Prefira primeiro as primitivas estáveis e estreitas. Os subcaminhos mais novos de setup/pairing/reply/ feedback/contract/inbound/threading/command/secret-input/webhook/infra/ - allowlist/status/message-tool são o contrato pretendido para novos - plugins embutidos e externos. - O parsing/matching de destino pertence a `openclaw/plugin-sdk/channel-targets`. - Barreiras de ação de mensagem e auxiliares de message-id de reação pertencem a + allowlist/status/message-tool são o contrato pretendido para novos trabalhos + de plugins incluídos e externos. + Parsing/correspondência de destinos pertence a `openclaw/plugin-sdk/channel-targets`. + Gates de ação de mensagem e auxiliares de ID de mensagem de reação pertencem a `openclaw/plugin-sdk/channel-actions`. -- Barrels de auxiliares específicos de extensões embutidas não são estáveis por padrão. Se um - auxiliar for necessário apenas para uma extensão embutida, mantenha-o atrás do - seam local `api.js` ou `runtime-api.js` da extensão em vez de promovê-lo para +- Barrels auxiliares específicos de extensões incluídas não são estáveis por padrão. Se um + auxiliar for necessário apenas para uma extensão incluída, mantenha-o por trás do seam local + `api.js` ou `runtime-api.js` da extensão, em vez de promovê-lo para `openclaw/plugin-sdk/`. -- Novos seams de auxiliares compartilhados devem ser genéricos, não com marca de canal. O parsing - compartilhado de destino pertence a `openclaw/plugin-sdk/channel-targets`; internos - específicos do canal permanecem atrás do seam local `api.js` ou `runtime-api.js` - do plugin proprietário. +- Novos seams auxiliares compartilhados devem ser genéricos, não associados a uma marca de canal. O parsing compartilhado de destino + pertence a `openclaw/plugin-sdk/channel-targets`; internos específicos do canal + permanecem por trás do seam local `api.js` ou `runtime-api.js` do plugin proprietário. - Subcaminhos específicos de capacidade, como `image-generation`, - `media-understanding` e `speech`, existem porque plugins nativos/embutidos os usam - hoje. A presença deles, por si só, não significa que todo auxiliar exportado seja um + `media-understanding` e `speech`, existem porque plugins nativos/incluídos os usam + hoje. Sua presença não significa, por si só, que todo auxiliar exportado seja um contrato externo congelado de longo prazo. -## Esquemas da ferramenta de mensagem +## Schemas da ferramenta de mensagem -Plugins devem ser responsáveis pelas contribuições de esquema específicas de canal em +Plugins devem ser responsáveis por contribuições de schema específicas de canal em `describeMessageTool(...)`. Mantenha campos específicos do provedor no plugin, não no core compartilhado. -Para fragmentos de esquema portáteis compartilhados, reutilize os auxiliares genéricos exportados por +Para fragmentos de schema portáveis compartilhados, reutilize os auxiliares genéricos exportados por `openclaw/plugin-sdk/channel-actions`: -- `createMessageToolButtonsSchema()` para payloads em estilo grade de botões -- `createMessageToolCardSchema()` para payloads estruturados de cards +- `createMessageToolButtonsSchema()` para payloads no estilo grade de botões +- `createMessageToolCardSchema()` para payloads estruturados de cartão -Se um formato de esquema só fizer sentido para um provedor, defina-o no código-fonte -desse plugin em vez de promovê-lo para o SDK compartilhado. +Se um formato de schema só fizer sentido para um provedor, defina-o no próprio +código-fonte desse plugin em vez de promovê-lo ao SDK compartilhado. -## Resolução de destino de canal +## Resolução de destinos de canal -Plugins de canal devem ser responsáveis pela semântica de destino específica do canal. Mantenha o -host de saída compartilhado genérico e use a superfície do adaptador de mensagens para regras do provedor: +Plugins de canal devem ser responsáveis por semântica de destino específica do canal. Mantenha o +host compartilhado de saída genérico e use a superfície do adaptador de mensagens para regras do provedor: - `messaging.inferTargetChatType({ to })` decide se um destino normalizado - deve ser tratado como `direct`, `group` ou `channel` antes da busca em diretório. + deve ser tratado como `direct`, `group` ou `channel` antes da busca no diretório. - `messaging.targetResolver.looksLikeId(raw, normalized)` informa ao core se uma - entrada deve pular direto para resolução semelhante a id em vez de busca no diretório. + entrada deve pular direto para resolução semelhante a ID em vez de busca no diretório. - `messaging.targetResolver.resolveTarget(...)` é o fallback do plugin quando o - core precisa de uma resolução final pertencente ao provedor após a normalização ou após - uma falha de busca no diretório. -- `messaging.resolveOutboundSessionRoute(...)` é responsável pela construção da rota de sessão + core precisa de uma resolução final pertencente ao provedor após normalização ou após falha no diretório. +- `messaging.resolveOutboundSessionRoute(...)` é responsável pela construção de rota de sessão específica do provedor depois que um destino é resolvido. -Separação recomendada: +Divisão recomendada: -- Use `inferTargetChatType` para decisões de categoria que devem acontecer antes - da busca por pares/grupos. -- Use `looksLikeId` para verificações do tipo “trate isto como um id de destino explícito/nativo”. +- Use `inferTargetChatType` para decisões de categoria que devem acontecer antes de + pesquisar pares/grupos. +- Use `looksLikeId` para verificações do tipo "trate isto como um ID de destino explícito/nativo". - Use `resolveTarget` para fallback de normalização específico do provedor, não para busca ampla em diretório. -- Mantenha ids nativos do provedor, como ids de chat, ids de thread, JIDs, handles e ids de sala, - dentro de valores `target` ou parâmetros específicos do provedor, não em campos genéricos do SDK. +- Mantenha IDs nativos do provedor, como chat ids, thread ids, JIDs, handles e room + ids, dentro de valores `target` ou parâmetros específicos do provedor, não em campos genéricos do SDK. ## Diretórios baseados em configuração -Plugins que derivam entradas de diretório a partir da configuração devem manter essa lógica no +Plugins que derivam entradas de diretório da configuração devem manter essa lógica no plugin e reutilizar os auxiliares compartilhados de `openclaw/plugin-sdk/directory-runtime`. Use isso quando um canal precisar de pares/grupos baseados em configuração, como: - pares de DM orientados por allowlist -- mapas configurados de canais/grupos -- fallbacks estáticos de diretório com escopo por conta +- mapas configurados de canal/grupo +- fallbacks estáticos de diretório com escopo de conta -Os auxiliares compartilhados em `directory-runtime` tratam apenas operações genéricas: +Os auxiliares compartilhados em `directory-runtime` lidam apenas com operações genéricas: - filtragem de consulta - aplicação de limite - auxiliares de deduplicação/normalização - construção de `ChannelDirectoryEntry[]` -Inspeção de conta e normalização de id específicas do canal devem permanecer na +Inspeção de conta específica do canal e normalização de ID devem permanecer na implementação do plugin. ## Catálogos de provedores @@ -1292,19 +1286,19 @@ Plugins de provedor podem definir catálogos de modelos para inferência com - `{ provider }` para uma entrada de provedor - `{ providers }` para várias entradas de provedor -Use `catalog` quando o plugin for responsável por ids de modelo específicos do provedor, padrões -de URL base ou metadados de modelo condicionados à autenticação. +Use `catalog` quando o plugin for responsável por IDs de modelo específicos do provedor, padrões de URL base +ou metadados de modelo controlados por autenticação. `catalog.order` controla quando o catálogo de um plugin é mesclado em relação aos -provedores implícitos embutidos do OpenClaw: +provedores implícitos internos do OpenClaw: -- `simple`: provedores simples orientados por chave de API ou env +- `simple`: provedores simples por chave de API ou orientados por env - `profile`: provedores que aparecem quando existem perfis de autenticação - `paired`: provedores que sintetizam várias entradas de provedor relacionadas -- `late`: última passagem, depois de outros provedores implícitos +- `late`: última passagem, após outros provedores implícitos -Provedores posteriores vencem em caso de colisão de chave, então plugins podem intencionalmente sobrescrever uma -entrada de provedor embutida com o mesmo id de provedor. +Provedores posteriores vencem em colisão de chave, então plugins podem substituir intencionalmente +uma entrada de provedor interna com o mesmo ID de provedor. Compatibilidade: @@ -1314,36 +1308,36 @@ Compatibilidade: ## Inspeção de canal somente leitura Se o seu plugin registrar um canal, prefira implementar -`plugin.config.inspectAccount(cfg, accountId)` juntamente com `resolveAccount(...)`. +`plugin.config.inspectAccount(cfg, accountId)` junto com `resolveAccount(...)`. Por quê: -- `resolveAccount(...)` é o caminho de runtime. Ele pode assumir que as credenciais - estão totalmente materializadas e falhar rapidamente quando segredos obrigatórios estiverem ausentes. +- `resolveAccount(...)` é o caminho de runtime. Pode assumir que as credenciais + estão totalmente materializadas e pode falhar rapidamente quando segredos obrigatórios estiverem ausentes. - Caminhos de comando somente leitura, como `openclaw status`, `openclaw status --all`, - `openclaw channels status`, `openclaw channels resolve` e fluxos de doctor/reparo - de configuração, não devem precisar materializar credenciais de runtime apenas para + `openclaw channels status`, `openclaw channels resolve` e fluxos de reparo de doctor/config + não devem precisar materializar credenciais de runtime apenas para descrever a configuração. -Comportamento recomendado para `inspectAccount(...)`: +Comportamento recomendado de `inspectAccount(...)`: - Retorne apenas o estado descritivo da conta. - Preserve `enabled` e `configured`. -- Inclua campos de origem/status de credenciais quando relevantes, como: +- Inclua campos de origem/status de credencial quando relevante, como: - `tokenSource`, `tokenStatus` - `botTokenSource`, `botTokenStatus` - `appTokenSource`, `appTokenStatus` - `signingSecretSource`, `signingSecretStatus` -- Você não precisa retornar valores brutos de token apenas para relatar disponibilidade - somente leitura. Retornar `tokenStatus: "available"` (e o campo de origem correspondente) - já é suficiente para comandos de status. +- Você não precisa retornar valores brutos de token apenas para relatar disponibilidade somente leitura. + Retornar `tokenStatus: "available"` (e o campo de origem correspondente) + é suficiente para comandos no estilo status. - Use `configured_unavailable` quando uma credencial estiver configurada via SecretRef, mas indisponível no caminho de comando atual. -Isso permite que comandos somente leitura relatem “configurado, mas indisponível neste caminho de comando” -em vez de travar ou informar incorretamente que a conta não está configurada. +Isso permite que comandos somente leitura relatem "configurado, mas indisponível neste caminho de comando" +em vez de travar ou relatar incorretamente a conta como não configurada. -## Pacotes multipack +## Packs de pacote Um diretório de plugin pode incluir um `package.json` com `openclaw.extensions`: @@ -1357,63 +1351,64 @@ Um diretório de plugin pode incluir um `package.json` com `openclaw.extensions` } ``` -Cada entrada se torna um plugin. Se o pacote listar várias extensões, o id do plugin +Cada entrada vira um plugin. Se o pack listar várias extensões, o ID do plugin passa a ser `name/`. -Se o seu plugin importar dependências npm, instale-as nesse diretório para que +Se seu plugin importar dependências npm, instale-as nesse diretório para que `node_modules` esteja disponível (`npm install` / `pnpm install`). -Barreira de segurança: toda entrada de `openclaw.extensions` deve permanecer dentro do diretório do plugin -após a resolução de symlink. Entradas que escaparem do diretório do pacote serão +Barreira de segurança: toda entrada em `openclaw.extensions` deve permanecer dentro do diretório do plugin +após a resolução de symlink. Entradas que escapem do diretório do pacote são rejeitadas. Observação de segurança: `openclaw plugins install` instala dependências de plugin com -`npm install --omit=dev --ignore-scripts` (sem scripts de lifecycle, sem dependências de desenvolvimento em runtime). Mantenha as árvores de dependência do plugin em "pure JS/TS" e evite pacotes que exijam builds em `postinstall`. +`npm install --omit=dev --ignore-scripts` (sem scripts de ciclo de vida, sem dependências de desenvolvimento em runtime). Mantenha as árvores de dependências do plugin em "JS/TS puro" e evite pacotes que exijam builds em `postinstall`. Opcional: `openclaw.setupEntry` pode apontar para um módulo leve somente de configuração. Quando o OpenClaw precisa de superfícies de configuração para um plugin de canal desabilitado, ou quando um plugin de canal está habilitado, mas ainda não configurado, ele carrega `setupEntry` em vez da entrada completa do plugin. Isso mantém a inicialização e a configuração mais leves -quando a entrada principal do seu plugin também registra ferramentas, hooks ou outro código exclusivo de runtime. +quando a entrada principal do seu plugin também conecta ferramentas, hooks ou outro +código somente de runtime. Opcional: `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` -pode incluir um plugin de canal no mesmo caminho de `setupEntry` durante a fase de -inicialização pré-listen do gateway, mesmo quando o canal já está configurado. +pode fazer um plugin de canal optar por esse mesmo caminho `setupEntry` durante a +fase de inicialização pré-listen do gateway, mesmo quando o canal já estiver configurado. -Use isso apenas quando `setupEntry` cobrir totalmente a superfície de inicialização que precisa existir -antes de o gateway começar a escutar. Na prática, isso significa que a entrada de configuração +Use isso apenas quando `setupEntry` cobrir totalmente a superfície de inicialização que deve existir +antes que o gateway comece a escutar. Na prática, isso significa que a entrada de configuração deve registrar toda capacidade pertencente ao canal da qual a inicialização depende, como: - o próprio registro do canal - quaisquer rotas HTTP que precisem estar disponíveis antes de o gateway começar a escutar - quaisquer métodos, ferramentas ou serviços do gateway que precisem existir durante essa mesma janela -Se sua entrada completa ainda for responsável por alguma capacidade obrigatória de inicialização, não habilite -essa flag. Mantenha o plugin no comportamento padrão e deixe o OpenClaw carregar a +Se sua entrada completa ainda for responsável por qualquer capacidade de inicialização obrigatória, não habilite +essa flag. Mantenha o comportamento padrão do plugin e deixe o OpenClaw carregar a entrada completa durante a inicialização. -Canais embutidos também podem publicar auxiliares de superfície de contrato somente de configuração que o core -pode consultar antes que o runtime completo do canal seja carregado. A superfície atual de promoção de setup é: +Canais incluídos também podem publicar auxiliares de superfície de contrato somente de configuração que o core +pode consultar antes de o runtime completo do canal ser carregado. A superfície atual de promoção de configuração +é: - `singleAccountKeysToMove` - `namedAccountPromotionKeys` - `resolveSingleAccountPromotionTarget(...)` -O core usa essa superfície quando precisa promover uma configuração legada de canal de conta única +O core usa essa superfície quando precisa promover uma configuração legada de canal com conta única para `channels..accounts.*` sem carregar a entrada completa do plugin. -Matrix é o exemplo embutido atual: ele move apenas chaves de autenticação/bootstrap para uma -conta promovida nomeada quando contas nomeadas já existem e pode preservar uma -chave configurada de conta padrão não canônica em vez de sempre criar +Matrix é o exemplo incluído atual: ele move apenas chaves de autenticação/bootstrap para uma +conta promovida com nome quando contas nomeadas já existem e pode preservar uma +chave de conta padrão configurada e não canônica em vez de sempre criar `accounts.default`. -Esses adaptadores de patch de setup mantêm lazy a descoberta da superfície de contrato embutida. O tempo -de importação permanece leve; a superfície de promoção é carregada apenas no primeiro uso, em vez de -reentrar na inicialização de canal embutido na importação do módulo. +Esses adaptadores de patch de configuração mantêm a descoberta da superfície de contrato incluída de forma lazy. +O tempo de importação permanece leve; a superfície de promoção é carregada apenas no primeiro uso, em vez de reentrar na inicialização do canal incluído na importação do módulo. -Quando essas superfícies de inicialização incluem métodos RPC do gateway, mantenha-os em um +Quando essas superfícies de inicialização incluírem métodos RPC do gateway, mantenha-os em um prefixo específico do plugin. Namespaces administrativos do core (`config.*`, -`exec.approvals.*`, `wizard.*`, `update.*`) permanecem reservados e sempre são resolvidos -para `operator.admin`, mesmo que um plugin solicite um escopo mais estreito. +`exec.approvals.*`, `wizard.*`, `update.*`) continuam reservados e sempre são resolvidos +como `operator.admin`, mesmo que um plugin solicite um escopo mais estreito. Exemplo: @@ -1432,8 +1427,8 @@ Exemplo: ### Metadados de catálogo de canal -Plugins de canal podem anunciar metadados de configuração/descoberta por meio de `openclaw.channel` e -dicas de instalação por meio de `openclaw.install`. Isso mantém os dados de catálogo fora do core. +Plugins de canal podem anunciar metadados de configuração/descoberta via `openclaw.channel` e +dicas de instalação via `openclaw.install`. Isso mantém os dados de catálogo do core vazios. Exemplo: @@ -1464,20 +1459,20 @@ Exemplo: Campos úteis de `openclaw.channel` além do exemplo mínimo: - `detailLabel`: rótulo secundário para superfícies mais ricas de catálogo/status -- `docsLabel`: substitui o texto do link para a documentação -- `preferOver`: ids de plugin/canal de prioridade mais baixa que esta entrada de catálogo deve superar -- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: controles de cópia para superfícies de seleção +- `docsLabel`: substitui o texto do link para os docs +- `preferOver`: IDs de plugin/canal de prioridade mais baixa que esta entrada de catálogo deve superar +- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: controles de cópia da superfície de seleção - `markdownCapable`: marca o canal como compatível com markdown para decisões de formatação de saída -- `exposure.configured`: oculta o canal de superfícies de listagem de canais configurados quando definido como `false` -- `exposure.setup`: oculta o canal de seletores interativos de configuração/setup quando definido como `false` -- `exposure.docs`: marca o canal como interno/privado para superfícies de navegação de documentação +- `exposure.configured`: oculta o canal das superfícies de listagem de canais configurados quando definido como `false` +- `exposure.setup`: oculta o canal dos seletores interativos de configuração quando definido como `false` +- `exposure.docs`: marca o canal como interno/privado para superfícies de navegação de docs - `showConfigured` / `showInSetup`: aliases legados ainda aceitos por compatibilidade; prefira `exposure` -- `quickstartAllowFrom`: inclui o canal no fluxo padrão `allowFrom` de início rápido -- `forceAccountBinding`: exige associação explícita de conta mesmo quando existe apenas uma conta +- `quickstartAllowFrom`: faz o canal optar pelo fluxo padrão de início rápido `allowFrom` +- `forceAccountBinding`: exige vínculo explícito de conta mesmo quando existe apenas uma conta - `preferSessionLookupForAnnounceTarget`: prefere busca de sessão ao resolver destinos de anúncio -O OpenClaw também pode mesclar **catálogos de canais externos** (por exemplo, uma -exportação de registro MPM). Coloque um arquivo JSON em um destes locais: +O OpenClaw também pode mesclar **catálogos externos de canal** (por exemplo, uma exportação +de registro MPM). Coloque um arquivo JSON em um destes locais: - `~/.openclaw/mpm/plugins.json` - `~/.openclaw/mpm/catalog.json` @@ -1489,12 +1484,12 @@ conter `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, " ## Plugins de mecanismo de contexto -Plugins de mecanismo de contexto são responsáveis pela orquestração do contexto de sessão para ingestão, montagem +Plugins de mecanismo de contexto são responsáveis pela orquestração do contexto da sessão para ingestão, montagem e compactação. Registre-os a partir do seu plugin com -`api.registerContextEngine(id, factory)` e então selecione o mecanismo ativo com +`api.registerContextEngine(id, factory)` e depois selecione o mecanismo ativo com `plugins.slots.contextEngine`. -Use isso quando seu plugin precisar substituir ou estender o pipeline de contexto padrão +Use isso quando seu plugin precisar substituir ou estender o pipeline de contexto padrão, em vez de apenas adicionar pesquisa de memória ou hooks. ```ts @@ -1523,8 +1518,8 @@ export default function (api) { } ``` -Se o seu mecanismo **não** for responsável pelo algoritmo de compactação, mantenha `compact()` -implementado e delegue explicitamente: +Se seu mecanismo **não** for responsável pelo algoritmo de compactação, mantenha `compact()` +implementado e delegue-o explicitamente: ```ts import { @@ -1559,10 +1554,10 @@ export default function (api) { } ``` -## Adicionando uma nova capacidade +## Adicionar uma nova capacidade -Quando um plugin precisar de um comportamento que não se encaixe na API atual, não contorne -o sistema de plugins com um acesso privado. Adicione a capacidade ausente. +Quando um plugin precisa de um comportamento que não se encaixa na API atual, não contorne +o sistema de plugins com um acesso privado interno. Adicione a capacidade ausente. Sequência recomendada: @@ -1570,39 +1565,38 @@ Sequência recomendada: Decida qual comportamento compartilhado o core deve possuir: política, fallback, mesclagem de configuração, ciclo de vida, semântica voltada a canais e formato do auxiliar de runtime. 2. adicione superfícies tipadas de registro/runtime de plugin - Estenda `OpenClawPluginApi` e/ou `api.runtime` com a menor - superfície de capacidade tipada útil. + Estenda `OpenClawPluginApi` e/ou `api.runtime` com a menor superfície útil de capacidade tipada. 3. conecte consumidores do core + canal/recurso Canais e plugins de recurso devem consumir a nova capacidade por meio do core, não importando diretamente uma implementação de fornecedor. 4. registre implementações de fornecedor - Plugins de fornecedor então registram seus backends nessa capacidade. + Plugins de fornecedores então registram seus backends nessa capacidade. 5. adicione cobertura de contrato Adicione testes para que a propriedade e o formato do registro permaneçam explícitos ao longo do tempo. -É assim que o OpenClaw permanece opinativo sem ficar codificado para a visão de mundo de um -único provedor. Consulte o [Livro de receitas de capacidades](/pt-BR/plugins/architecture) -para um checklist concreto de arquivos e um exemplo prático. +É assim que o OpenClaw permanece opinativo sem ficar codificado rigidamente à visão de mundo +de um único provedor. Consulte o [Livro de receitas de capacidades](/pt-BR/plugins/architecture) +para um checklist concreto de arquivos e um exemplo completo. ### Checklist de capacidade -Ao adicionar uma nova capacidade, a implementação normalmente deve tocar essas +Quando você adiciona uma nova capacidade, a implementação normalmente deve tocar estas superfícies em conjunto: - tipos de contrato do core em `src//types.ts` -- helper de runner/runtime do core em `src//runtime.ts` -- superfície de registro da API de plugin em `src/plugins/types.ts` -- integração com o registro de plugins em `src/plugins/registry.ts` -- exposição de runtime do plugin em `src/plugins/runtime/*` quando plugins de recurso/canal +- runner/auxiliar de runtime do core em `src//runtime.ts` +- superfície da API de registro de plugin em `src/plugins/types.ts` +- wiring do registro de plugins em `src/plugins/registry.ts` +- exposição de runtime de plugin em `src/plugins/runtime/*` quando plugins de recurso/canal precisarem consumi-la - auxiliares de captura/teste em `src/test-utils/plugin-registration.ts` -- afirmações de propriedade/contrato em `src/plugins/contracts/registry.ts` +- asserções de propriedade/contrato em `src/plugins/contracts/registry.ts` - documentação para operadores/plugins em `docs/` -Se uma dessas superfícies estiver ausente, isso normalmente é um sinal de que a capacidade +Se uma dessas superfícies estiver ausente, isso geralmente é um sinal de que a capacidade ainda não está totalmente integrada. -### Modelo de capacidade +### Template de capacidade Padrão mínimo: @@ -1639,6 +1633,6 @@ expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); Isso mantém a regra simples: - o core é responsável pelo contrato de capacidade + orquestração -- plugins de fornecedor são responsáveis pelas implementações do fornecedor +- plugins de fornecedores são responsáveis por implementações de fornecedor - plugins de recurso/canal consomem auxiliares de runtime - testes de contrato mantêm a propriedade explícita diff --git a/docs/pt-BR/plugins/manifest.md b/docs/pt-BR/plugins/manifest.md index 1bc8652f8..2ca08c3dd 100644 --- a/docs/pt-BR/plugins/manifest.md +++ b/docs/pt-BR/plugins/manifest.md @@ -1,14 +1,14 @@ --- read_when: - Você está criando um plugin do OpenClaw - - Você precisa fornecer um schema de configuração do plugin ou depurar erros de validação do plugin -summary: Manifesto do plugin + requisitos do schema JSON (validação estrita de configuração) + - Você precisa fornecer um esquema de configuração do plugin ou depurar erros de validação do plugin +summary: Manifesto do plugin + requisitos do esquema JSON (validação estrita de configuração) title: Manifesto do plugin x-i18n: - generated_at: "2026-04-11T15:16:04Z" + generated_at: "2026-04-12T05:33:10Z" model: gpt-5.4 provider: openai - source_hash: 42d454b560a8f6bf714c5d782f34216be1216d83d0a319d08d7349332c91a9e4 + source_hash: bf666b0f41f07641375a248f52e29ba6a68c3ec20404bedb6b52a20a5cd92e91 source_path: plugins/manifest.md workflow: 15 --- @@ -17,46 +17,61 @@ x-i18n: Esta página é apenas para o **manifesto nativo de plugin do OpenClaw**. -Para layouts de bundle compatíveis, consulte [Bundles de plugin](/pt-BR/plugins/bundles). +Para layouts de bundle compatíveis, veja [Bundles de plugins](/pt-BR/plugins/bundles). Formatos de bundle compatíveis usam arquivos de manifesto diferentes: - Bundle do Codex: `.codex-plugin/plugin.json` -- Bundle do Claude: `.claude-plugin/plugin.json` ou o layout padrão de componente do Claude sem manifesto +- Bundle do Claude: `.claude-plugin/plugin.json` ou o layout padrão de componente do Claude + sem manifesto - Bundle do Cursor: `.cursor-plugin/plugin.json` -O OpenClaw também detecta automaticamente esses layouts de bundle, mas eles não são validados em relação ao schema `openclaw.plugin.json` descrito aqui. +O OpenClaw também detecta automaticamente esses layouts de bundle, mas eles não são validados +em relação ao esquema `openclaw.plugin.json` descrito aqui. -Para bundles compatíveis, o OpenClaw atualmente lê os metadados do bundle, além das raízes de Skills declaradas, raízes de comandos do Claude, padrões de `settings.json` do bundle do Claude, padrões de LSP do bundle do Claude e pacotes de hooks compatíveis quando o layout corresponde às expectativas de runtime do OpenClaw. +Para bundles compatíveis, o OpenClaw atualmente lê os metadados do bundle mais as +raízes de skill declaradas, raízes de comando do Claude, padrões `settings.json` do bundle do Claude, +padrões de LSP do bundle do Claude e pacotes de hooks compatíveis quando o layout corresponde +às expectativas de runtime do OpenClaw. -Todo plugin nativo do OpenClaw **deve** fornecer um arquivo `openclaw.plugin.json` na **raiz do plugin**. O OpenClaw usa esse manifesto para validar a configuração **sem executar o código do plugin**. Manifestos ausentes ou inválidos são tratados como erros de plugin e bloqueiam a validação da configuração. +Todo plugin nativo do OpenClaw **deve** fornecer um arquivo `openclaw.plugin.json` na +**raiz do plugin**. O OpenClaw usa esse manifesto para validar a configuração +**sem executar o código do plugin**. Manifestos ausentes ou inválidos são tratados como +erros de plugin e bloqueiam a validação da configuração. -Consulte o guia completo do sistema de plugins: [Plugins](/pt-BR/tools/plugin). +Veja o guia completo do sistema de plugins: [Plugins](/pt-BR/tools/plugin). Para o modelo nativo de capacidades e a orientação atual de compatibilidade externa: [Modelo de capacidades](/pt-BR/plugins/architecture#public-capability-model). -## O que este arquivo faz +## O que esse arquivo faz -`openclaw.plugin.json` são os metadados que o OpenClaw lê antes de carregar o código do seu plugin. +`openclaw.plugin.json` são os metadados que o OpenClaw lê antes de carregar o +código do seu plugin. Use-o para: - identidade do plugin - validação de configuração -- metadados de autenticação e onboarding que devem estar disponíveis sem iniciar o runtime do plugin -- dicas de ativação leves que as superfícies do plano de controle podem inspecionar antes de o runtime ser carregado -- descritores de configuração leves que as superfícies de configuração/onboarding podem inspecionar antes de o runtime ser carregado -- metadados de alias e autoativação que devem ser resolvidos antes de o runtime do plugin ser carregado -- metadados abreviados de propriedade de família de modelos que devem autoativar o plugin antes de o runtime ser carregado -- snapshots estáticos de propriedade de capacidades usados para o cabeamento de compatibilidade empacotado e cobertura de contrato -- metadados de configuração específicos de canal que devem ser mesclados em superfícies de catálogo e validação sem carregar o runtime +- metadados de autenticação e onboarding que devem estar disponíveis sem iniciar o + runtime do plugin +- dicas baratas de ativação que superfícies do plano de controle podem inspecionar antes de o runtime + carregar +- descritores baratos de configuração que superfícies de configuração/onboarding podem inspecionar antes + de o runtime carregar +- metadados de alias e autoativação que devem ser resolvidos antes de o runtime do plugin carregar +- metadados abreviados de propriedade de família de modelos que devem autoativar o + plugin antes de o runtime carregar +- snapshots estáticos de propriedade de capacidades usados para wiring de compatibilidade + empacotada e cobertura de contrato +- metadados de configuração específicos de canal que devem ser mesclados em superfícies + de catálogo e validação sem carregar o runtime - dicas de UI de configuração Não o use para: - registrar comportamento de runtime - declarar entrypoints de código -- metadados de instalação do npm +- metadados de instalação npm Esses pertencem ao código do seu plugin e ao `package.json`. @@ -129,62 +144,64 @@ Esses pertencem ao código do seu plugin e ao `package.json`. } ``` -## Referência dos campos de nível superior +## Referência de campos de nível superior | Campo | Obrigatório | Tipo | O que significa | | ----------------------------------- | ----------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `id` | Sim | `string` | ID canônico do plugin. Este é o ID usado em `plugins.entries.`. | -| `configSchema` | Sim | `object` | Schema JSON inline para a configuração deste plugin. | -| `enabledByDefault` | Não | `true` | Marca um plugin empacotado como habilitado por padrão. Omita-o ou defina qualquer valor diferente de `true` para deixar o plugin desabilitado por padrão. | +| `id` | Sim | `string` | ID canônico do plugin. Esse é o ID usado em `plugins.entries.`. | +| `configSchema` | Sim | `object` | Esquema JSON inline para a configuração deste plugin. | +| `enabledByDefault` | Não | `true` | Marca um plugin empacotado como habilitado por padrão. Omita-o, ou defina qualquer valor diferente de `true`, para manter o plugin desabilitado por padrão. | | `legacyPluginIds` | Não | `string[]` | IDs legados que são normalizados para este ID canônico de plugin. | -| `autoEnableWhenConfiguredProviders` | Não | `string[]` | IDs de provedores que devem autoativar este plugin quando autenticação, configuração ou referências de modelo os mencionarem. | +| `autoEnableWhenConfiguredProviders` | Não | `string[]` | IDs de provedores que devem autoativar este plugin quando autenticação, configuração ou referências de modelo os mencionarem. | | `kind` | Não | `"memory"` \| `"context-engine"` | Declara um tipo exclusivo de plugin usado por `plugins.slots.*`. | -| `channels` | Não | `string[]` | IDs de canais pertencentes a este plugin. Usado para descoberta e validação de configuração. | +| `channels` | Não | `string[]` | IDs de canais pertencentes a este plugin. Usado para descoberta e validação de configuração. | | `providers` | Não | `string[]` | IDs de provedores pertencentes a este plugin. | -| `modelSupport` | Não | `object` | Metadados abreviados de família de modelos pertencentes ao manifesto usados para carregar automaticamente o plugin antes do runtime. | -| `cliBackends` | Não | `string[]` | IDs de backends de inferência da CLI pertencentes a este plugin. Usado para autoativação na inicialização a partir de referências explícitas de configuração. | -| `commandAliases` | Não | `object[]` | Nomes de comandos pertencentes a este plugin que devem produzir diagnósticos de configuração e CLI cientes do plugin antes de o runtime ser carregado. | -| `providerAuthEnvVars` | Não | `Record` | Metadados leves de variáveis de ambiente de autenticação de provedor que o OpenClaw pode inspecionar sem carregar o código do plugin. | -| `providerAuthAliases` | Não | `Record` | IDs de provedores que devem reutilizar outro ID de provedor para busca de autenticação, por exemplo, um provedor de programação que compartilha a chave de API do provedor base e perfis de autenticação. | -| `channelEnvVars` | Não | `Record` | Metadados leves de variáveis de ambiente de canal que o OpenClaw pode inspecionar sem carregar o código do plugin. Use isso para configuração de canal orientada por env ou superfícies de autenticação que helpers genéricos de inicialização/configuração devem enxergar. | -| `providerAuthChoices` | Não | `object[]` | Metadados leves de opções de autenticação para seletores de onboarding, resolução de provedor preferido e cabeamento simples de flags de CLI. | -| `activation` | Não | `object` | Dicas leves de ativação para carregamento acionado por provedor, comando, canal, rota e capacidade. Apenas metadados; o runtime do plugin ainda é dono do comportamento real. | -| `setup` | Não | `object` | Descritores leves de configuração/onboarding que superfícies de descoberta e configuração podem inspecionar sem carregar o runtime do plugin. | -| `contracts` | Não | `object` | Snapshot estático de capacidades empacotadas para fala, transcrição em tempo real, voz em tempo real, media-understanding, geração de imagem, geração de música, geração de vídeo, web-fetch, busca na web e propriedade de ferramentas. | -| `channelConfigs` | Não | `Record` | Metadados de configuração de canal pertencentes ao manifesto mesclados em superfícies de descoberta e validação antes de o runtime ser carregado. | -| `skills` | Não | `string[]` | Diretórios de Skills para carregar, relativos à raiz do plugin. | +| `modelSupport` | Não | `object` | Metadados abreviados de família de modelos pertencentes ao manifesto usados para autocarregar o plugin antes do runtime. | +| `cliBackends` | Não | `string[]` | IDs de backend de inferência da CLI pertencentes a este plugin. Usado para autoativação na inicialização a partir de referências explícitas de configuração. | +| `commandAliases` | Não | `object[]` | Nomes de comando pertencentes a este plugin que devem produzir diagnósticos de configuração e CLI com reconhecimento de plugin antes de o runtime carregar. | +| `providerAuthEnvVars` | Não | `Record` | Metadados leves de variáveis de ambiente de autenticação do provedor que o OpenClaw pode inspecionar sem carregar o código do plugin. | +| `providerAuthAliases` | Não | `Record` | IDs de provedores que devem reutilizar outro ID de provedor para busca de autenticação, por exemplo um provedor de código que compartilha a chave de API e os perfis de autenticação do provedor base. | +| `channelEnvVars` | Não | `Record` | Metadados leves de variáveis de ambiente de canal que o OpenClaw pode inspecionar sem carregar o código do plugin. Use isso para superfícies de configuração ou autenticação de canal baseadas em env que helpers genéricos de inicialização/configuração devem enxergar. | +| `providerAuthChoices` | Não | `object[]` | Metadados leves de escolha de autenticação para seletores de onboarding, resolução de provedor preferencial e wiring simples de flags da CLI. | +| `activation` | Não | `object` | Dicas leves de ativação para carregamento disparado por provedor, comando, canal, rota e capacidade. Apenas metadados; o runtime do plugin ainda é dono do comportamento real. | +| `setup` | Não | `object` | Descritores leves de configuração/onboarding que superfícies de descoberta e configuração podem inspecionar sem carregar o runtime do plugin. | +| `contracts` | Não | `object` | Snapshot estático de capacidades empacotadas para fala, transcrição em tempo real, voz em tempo real, compreensão de mídia, geração de imagem, geração de música, geração de vídeo, web-fetch, pesquisa na web e propriedade de ferramentas. | +| `channelConfigs` | Não | `Record` | Metadados de configuração de canal pertencentes ao manifesto, mesclados em superfícies de descoberta e validação antes de o runtime carregar. | +| `skills` | Não | `string[]` | Diretórios de Skills a carregar, relativos à raiz do plugin. | | `name` | Não | `string` | Nome legível do plugin. | -| `description` | Não | `string` | Resumo curto mostrado em superfícies de plugin. | +| `description` | Não | `string` | Resumo curto mostrado nas superfícies do plugin. | | `version` | Não | `string` | Versão informativa do plugin. | | `uiHints` | Não | `Record` | Rótulos de UI, placeholders e dicas de sensibilidade para campos de configuração. | ## Referência de `providerAuthChoices` -Cada entrada em `providerAuthChoices` descreve uma opção de onboarding ou autenticação. -O OpenClaw lê isso antes de o runtime do provedor ser carregado. +Cada entrada de `providerAuthChoices` descreve uma escolha de onboarding ou autenticação. +O OpenClaw lê isso antes de o runtime do provedor carregar. -| Campo | Obrigatório | Tipo | O que significa | -| --------------------- | ----------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------- | -| `provider` | Sim | `string` | ID do provedor ao qual esta opção pertence. | -| `method` | Sim | `string` | ID do método de autenticação para encaminhamento. | -| `choiceId` | Sim | `string` | ID estável da opção de autenticação usado por fluxos de onboarding e CLI. | -| `choiceLabel` | Não | `string` | Rótulo visível ao usuário. Se omitido, o OpenClaw usa `choiceId` como fallback. | -| `choiceHint` | Não | `string` | Texto curto de ajuda para o seletor. | -| `assistantPriority` | Não | `number` | Valores menores são ordenados antes em seletores interativos conduzidos pelo assistente. | -| `assistantVisibility` | Não | `"visible"` \| `"manual-only"` | Oculta a opção dos seletores do assistente, mas ainda permite seleção manual pela CLI. | -| `deprecatedChoiceIds` | Não | `string[]` | IDs legados de opções que devem redirecionar usuários para esta opção de substituição. | -| `groupId` | Não | `string` | ID opcional de grupo para agrupar opções relacionadas. | -| `groupLabel` | Não | `string` | Rótulo visível ao usuário para esse grupo. | -| `groupHint` | Não | `string` | Texto curto de ajuda para o grupo. | -| `optionKey` | Não | `string` | Chave de opção interna para fluxos simples de autenticação com uma única flag. | -| `cliFlag` | Não | `string` | Nome da flag da CLI, como `--openrouter-api-key`. | -| `cliOption` | Não | `string` | Formato completo da opção da CLI, como `--openrouter-api-key `. | -| `cliDescription` | Não | `string` | Descrição usada na ajuda da CLI. | -| `onboardingScopes` | Não | `Array<"text-inference" \| "image-generation">` | Em quais superfícies de onboarding esta opção deve aparecer. Se omitido, o padrão é `["text-inference"]`. | +| Campo | Obrigatório | Tipo | O que significa | +| --------------------- | ----------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- | +| `provider` | Sim | `string` | ID do provedor ao qual esta escolha pertence. | +| `method` | Sim | `string` | ID do método de autenticação para o qual encaminhar. | +| `choiceId` | Sim | `string` | ID estável de escolha de autenticação usado por fluxos de onboarding e da CLI. | +| `choiceLabel` | Não | `string` | Rótulo voltado ao usuário. Se omitido, o OpenClaw usa `choiceId` como fallback. | +| `choiceHint` | Não | `string` | Texto curto de ajuda para o seletor. | +| `assistantPriority` | Não | `number` | Valores menores aparecem primeiro em seletores interativos conduzidos pelo assistente. | +| `assistantVisibility` | Não | `"visible"` \| `"manual-only"` | Oculta a escolha dos seletores do assistente, mas ainda permite seleção manual pela CLI. | +| `deprecatedChoiceIds` | Não | `string[]` | IDs legados de escolha que devem redirecionar os usuários para esta escolha de substituição. | +| `groupId` | Não | `string` | ID de grupo opcional para agrupar escolhas relacionadas. | +| `groupLabel` | Não | `string` | Rótulo voltado ao usuário para esse grupo. | +| `groupHint` | Não | `string` | Texto curto de ajuda para o grupo. | +| `optionKey` | Não | `string` | Chave interna de opção para fluxos simples de autenticação com uma única flag. | +| `cliFlag` | Não | `string` | Nome da flag da CLI, como `--openrouter-api-key`. | +| `cliOption` | Não | `string` | Formato completo da opção da CLI, como `--openrouter-api-key `. | +| `cliDescription` | Não | `string` | Descrição usada na ajuda da CLI. | +| `onboardingScopes` | Não | `Array<"text-inference" \| "image-generation">` | Em quais superfícies de onboarding esta escolha deve aparecer. Se omitido, o padrão é `["text-inference"]`. | ## Referência de `commandAliases` -Use `commandAliases` quando um plugin é dono de um nome de comando de runtime que os usuários podem colocar por engano em `plugins.allow` ou tentar executar como um comando raiz da CLI. O OpenClaw usa esses metadados para diagnósticos sem importar o código de runtime do plugin. +Use `commandAliases` quando um plugin é dono de um nome de comando de runtime que os usuários podem +colocar por engano em `plugins.allow` ou tentar executar como um comando raiz da CLI. O OpenClaw +usa esses metadados para diagnósticos sem importar o código de runtime do plugin. ```json { @@ -198,17 +215,19 @@ Use `commandAliases` quando um plugin é dono de um nome de comando de runtime q } ``` -| Campo | Obrigatório | Tipo | O que significa | -| ------------ | ----------- | ----------------- | ------------------------------------------------------------------------------ | -| `name` | Sim | `string` | Nome do comando que pertence a este plugin. | -| `kind` | Não | `"runtime-slash"` | Marca o alias como um comando de barra do chat em vez de um comando raiz da CLI. | -| `cliCommand` | Não | `string` | Comando raiz relacionado da CLI a ser sugerido para operações de CLI, se existir. | +| Campo | Obrigatório | Tipo | O que significa | +| ------------ | ----------- | ----------------- | ------------------------------------------------------------------------- | +| `name` | Sim | `string` | Nome do comando que pertence a este plugin. | +| `kind` | Não | `"runtime-slash"` | Marca o alias como um comando slash de chat em vez de um comando raiz da CLI. | +| `cliCommand` | Não | `string` | Comando raiz relacionado da CLI a ser sugerido para operações da CLI, se existir. | ## Referência de `activation` -Use `activation` quando o plugin puder declarar de forma leve quais eventos do plano de controle devem ativá-lo depois. +Use `activation` quando o plugin puder declarar de forma leve quais eventos do plano de controle +devem ativá-lo depois. -Este bloco contém apenas metadados. Ele não registra comportamento de runtime e não substitui `register(...)`, `setupEntry` nem outros entrypoints de runtime/plugin. +Esse bloco é apenas metadados. Ele não registra comportamento de runtime e não +substitui `register(...)`, `setupEntry` nem outros entrypoints de runtime/plugin. ```json { @@ -232,7 +251,8 @@ Este bloco contém apenas metadados. Ele não registra comportamento de runtime ## Referência de `setup` -Use `setup` quando superfícies de configuração e onboarding precisarem de metadados leves pertencentes ao plugin antes de o runtime ser carregado. +Use `setup` quando superfícies de configuração e onboarding precisarem de metadados leves pertencentes ao plugin +antes de o runtime carregar. ```json { @@ -251,35 +271,48 @@ Use `setup` quando superfícies de configuração e onboarding precisarem de met } ``` -O `cliBackends` de nível superior continua válido e continua descrevendo backends de inferência da CLI. `setup.cliBackends` é a superfície de descritor específica de configuração para fluxos de configuração/plano de controle que devem permanecer apenas como metadados. +O `cliBackends` de nível superior continua válido e segue descrevendo backends +de inferência da CLI. `setup.cliBackends` é a superfície de descritor específica de configuração para +fluxos do plano de controle/configuração que devem permanecer apenas como metadados. + +Quando presentes, `setup.providers` e `setup.cliBackends` são a superfície preferencial +baseada em descritores para busca de configuração. Se o descritor apenas restringir +o plugin candidato e a configuração ainda precisar de hooks de runtime mais ricos no momento da configuração, +defina `requiresRuntime: true` e mantenha `setup-api` como caminho de execução +de fallback. + +Como a busca de configuração pode executar código `setup-api` pertencente ao plugin, os valores normalizados de +`setup.providers[].id` e `setup.cliBackends[]` devem permanecer exclusivos entre +os plugins descobertos. Propriedade ambígua falha de forma fechada em vez de escolher +um vencedor com base na ordem de descoberta. ### Referência de `setup.providers` -| Campo | Obrigatório | Tipo | O que significa | -| ------------- | ----------- | ---------- | --------------------------------------------------------------------------------------- | -| `id` | Sim | `string` | ID do provedor exposto durante a configuração ou onboarding. | -| `authMethods` | Não | `string[]` | IDs de métodos de configuração/autenticação que este provedor oferece sem carregar todo o runtime. | -| `envVars` | Não | `string[]` | Variáveis de ambiente que superfícies genéricas de configuração/status podem verificar antes de o runtime do plugin ser carregado. | +| Campo | Obrigatório | Tipo | O que significa | +| ------------- | ----------- | ---------- | ------------------------------------------------------------------------------------ | +| `id` | Sim | `string` | ID do provedor exposto durante a configuração ou onboarding. Mantenha IDs normalizados globalmente exclusivos. | +| `authMethods` | Não | `string[]` | IDs de métodos de configuração/autenticação que este provedor oferece sem carregar o runtime completo. | +| `envVars` | Não | `string[]` | Variáveis de ambiente que superfícies genéricas de configuração/status podem verificar antes de o runtime do plugin carregar. | ### Campos de `setup` -| Campo | Obrigatório | Tipo | O que significa | -| ------------------ | ----------- | ---------- | ------------------------------------------------------------------------------ | -| `providers` | Não | `object[]` | Descritores de configuração de provedor expostos durante a configuração e o onboarding. | -| `cliBackends` | Não | `string[]` | IDs de backend disponíveis no momento da configuração sem ativação completa do runtime. | -| `configMigrations` | Não | `string[]` | IDs de migração de configuração pertencentes à superfície de configuração deste plugin. | -| `requiresRuntime` | Não | `boolean` | Se a configuração ainda precisa da execução do runtime do plugin após a busca do descritor. | +| Campo | Obrigatório | Tipo | O que significa | +| ------------------ | ----------- | ---------- | --------------------------------------------------------------------------------------------------- | +| `providers` | Não | `object[]` | Descritores de configuração de provedor expostos durante a configuração e o onboarding. | +| `cliBackends` | Não | `string[]` | IDs de backend em tempo de configuração usados para busca de configuração com base em descritor primeiro. Mantenha IDs normalizados globalmente exclusivos. | +| `configMigrations` | Não | `string[]` | IDs de migração de configuração pertencentes à superfície de configuração deste plugin. | +| `requiresRuntime` | Não | `boolean` | Se a configuração ainda precisa da execução de `setup-api` após a busca por descritor. | ## Referência de `uiHints` -`uiHints` é um mapa de nomes de campos de configuração para pequenas dicas de renderização. +`uiHints` é um mapa dos nomes de campos de configuração para pequenas dicas de renderização. ```json { "uiHints": { "apiKey": { "label": "Chave de API", - "help": "Usada para solicitações ao OpenRouter", + "help": "Usada para solicitações do OpenRouter", "placeholder": "sk-or-v1-...", "sensitive": true } @@ -289,18 +322,19 @@ O `cliBackends` de nível superior continua válido e continua descrevendo backe Cada dica de campo pode incluir: -| Campo | Tipo | O que significa | -| ------------- | ---------- | ----------------------------------------- | -| `label` | `string` | Rótulo do campo visível ao usuário. | -| `help` | `string` | Texto curto de ajuda. | -| `tags` | `string[]` | Tags opcionais da UI. | -| `advanced` | `boolean` | Marca o campo como avançado. | -| `sensitive` | `boolean` | Marca o campo como secreto ou sensível. | +| Campo | Tipo | O que significa | +| ------------- | ---------- | ---------------------------------------- | +| `label` | `string` | Rótulo do campo voltado ao usuário. | +| `help` | `string` | Texto curto de ajuda. | +| `tags` | `string[]` | Tags opcionais de UI. | +| `advanced` | `boolean` | Marca o campo como avançado. | +| `sensitive` | `boolean` | Marca o campo como secreto ou sensível. | | `placeholder` | `string` | Texto de placeholder para entradas de formulário. | ## Referência de `contracts` -Use `contracts` apenas para metadados estáticos de propriedade de capacidades que o OpenClaw pode ler sem importar o runtime do plugin. +Use `contracts` apenas para metadados estáticos de propriedade de capacidades que o OpenClaw pode +ler sem importar o runtime do plugin. ```json { @@ -320,21 +354,22 @@ Use `contracts` apenas para metadados estáticos de propriedade de capacidades q Cada lista é opcional: -| Campo | Tipo | O que significa | -| -------------------------------- | ---------- | ---------------------------------------------------------------- | -| `speechProviders` | `string[]` | IDs de provedores de fala pertencentes a este plugin. | +| Campo | Tipo | O que significa | +| -------------------------------- | ---------- | ------------------------------------------------------------ | +| `speechProviders` | `string[]` | IDs de provedores de fala pertencentes a este plugin. | | `realtimeTranscriptionProviders` | `string[]` | IDs de provedores de transcrição em tempo real pertencentes a este plugin. | | `realtimeVoiceProviders` | `string[]` | IDs de provedores de voz em tempo real pertencentes a este plugin. | -| `mediaUnderstandingProviders` | `string[]` | IDs de provedores de media-understanding pertencentes a este plugin. | +| `mediaUnderstandingProviders` | `string[]` | IDs de provedores de compreensão de mídia pertencentes a este plugin. | | `imageGenerationProviders` | `string[]` | IDs de provedores de geração de imagem pertencentes a este plugin. | | `videoGenerationProviders` | `string[]` | IDs de provedores de geração de vídeo pertencentes a este plugin. | -| `webFetchProviders` | `string[]` | IDs de provedores de web-fetch pertencentes a este plugin. | -| `webSearchProviders` | `string[]` | IDs de provedores de busca na web pertencentes a este plugin. | +| `webFetchProviders` | `string[]` | IDs de provedores de web-fetch pertencentes a este plugin. | +| `webSearchProviders` | `string[]` | IDs de provedores de pesquisa na web pertencentes a este plugin. | | `tools` | `string[]` | Nomes de ferramentas do agente pertencentes a este plugin para verificações de contrato empacotadas. | ## Referência de `channelConfigs` -Use `channelConfigs` quando um plugin de canal precisar de metadados leves de configuração antes de o runtime ser carregado. +Use `channelConfigs` quando um plugin de canal precisar de metadados leves de configuração antes de o +runtime carregar. ```json { @@ -354,7 +389,7 @@ Use `channelConfigs` quando um plugin de canal precisar de metadados leves de co } }, "label": "Matrix", - "description": "Conexão com homeserver Matrix", + "description": "Conexão com o homeserver Matrix", "preferOver": ["matrix-legacy"] } } @@ -363,17 +398,19 @@ Use `channelConfigs` quando um plugin de canal precisar de metadados leves de co Cada entrada de canal pode incluir: -| Campo | Tipo | O que significa | -| ------------- | ------------------------ | ------------------------------------------------------------------------------------------------ | -| `schema` | `object` | Schema JSON para `channels.`. Obrigatório para cada entrada declarada de configuração de canal. | -| `uiHints` | `Record` | Rótulos/placeholders/dicas opcionais de sensibilidade da UI para essa seção de configuração de canal. | -| `label` | `string` | Rótulo do canal mesclado em superfícies de seleção e inspeção quando os metadados de runtime não estiverem prontos. | -| `description` | `string` | Descrição curta do canal para superfícies de inspeção e catálogo. | -| `preferOver` | `string[]` | IDs de plugins legados ou de menor prioridade que este canal deve superar em superfícies de seleção. | +| Campo | Tipo | O que significa | +| ------------- | ------------------------ | -------------------------------------------------------------------------------------- | +| `schema` | `object` | Esquema JSON para `channels.`. Obrigatório para cada entrada declarada de configuração de canal. | +| `uiHints` | `Record` | Rótulos/placeholders/dicas de sensibilidade de UI opcionais para essa seção de configuração de canal. | +| `label` | `string` | Rótulo do canal mesclado em superfícies de seletor e inspeção quando os metadados de runtime ainda não estiverem prontos. | +| `description` | `string` | Descrição curta do canal para superfícies de inspeção e catálogo. | +| `preferOver` | `string[]` | IDs de plugin legados ou de menor prioridade que este canal deve superar em superfícies de seleção. | ## Referência de `modelSupport` -Use `modelSupport` quando o OpenClaw deve inferir seu plugin de provedor a partir de IDs abreviados de modelo como `gpt-5.4` ou `claude-sonnet-4.6` antes de o runtime do plugin ser carregado. +Use `modelSupport` quando o OpenClaw precisar inferir seu plugin de provedor a partir de +IDs abreviados de modelo, como `gpt-5.4` ou `claude-sonnet-4.6`, antes de o runtime do plugin +carregar. ```json { @@ -386,58 +423,74 @@ Use `modelSupport` quando o OpenClaw deve inferir seu plugin de provedor a parti O OpenClaw aplica esta precedência: -- referências explícitas `provider/model` usam os metadados de manifesto de `providers` correspondentes +- referências explícitas `provider/model` usam os metadados de manifesto `providers` do plugin proprietário - `modelPatterns` têm precedência sobre `modelPrefixes` -- se um plugin não empacotado e um plugin empacotado corresponderem, o plugin não empacotado vence +- se um plugin não empacotado e um plugin empacotado corresponderem ao mesmo tempo, o plugin não empacotado + vence - a ambiguidade restante é ignorada até que o usuário ou a configuração especifique um provedor Campos: | Campo | Tipo | O que significa | -| --------------- | ---------- | --------------------------------------------------------------------------------- | -| `modelPrefixes` | `string[]` | Prefixos comparados com `startsWith` em relação a IDs abreviados de modelo. | -| `modelPatterns` | `string[]` | Fontes de regex comparadas com IDs abreviados de modelo após a remoção do sufixo de perfil. | +| --------------- | ---------- | -------------------------------------------------------------------------------- | +| `modelPrefixes` | `string[]` | Prefixos correspondidos com `startsWith` em IDs abreviados de modelo. | +| `modelPatterns` | `string[]` | Fontes de regex correspondidas em IDs abreviados de modelo após a remoção do sufixo de perfil. | -Chaves legadas de capacidade no nível superior estão obsoletas. Use `openclaw doctor --fix` para mover `speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders` e `webSearchProviders` para `contracts`; o carregamento normal do manifesto não trata mais esses campos de nível superior como propriedade de capacidade. +Chaves legadas de capacidade no nível superior estão obsoletas. Use `openclaw doctor --fix` para +mover `speechProviders`, `realtimeTranscriptionProviders`, +`realtimeVoiceProviders`, `mediaUnderstandingProviders`, +`imageGenerationProviders`, `videoGenerationProviders`, +`webFetchProviders` e `webSearchProviders` para `contracts`; o carregamento normal +do manifesto não trata mais esses campos de nível superior como propriedade +de capacidades. ## Manifesto versus package.json -Os dois arquivos servem para funções diferentes: +Os dois arquivos têm funções diferentes: -| Arquivo | Use para | -| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.plugin.json` | Descoberta, validação de configuração, metadados de opção de autenticação e dicas de UI que precisam existir antes de o código do plugin ser executado | -| `package.json` | Metadados do npm, instalação de dependências e o bloco `openclaw` usado para entrypoints, controle de instalação, configuração ou metadados de catálogo | +| Arquivo | Use para | +| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | +| `openclaw.plugin.json` | Descoberta, validação de configuração, metadados de escolha de autenticação e dicas de UI que devem existir antes de o código do plugin executar | +| `package.json` | Metadados npm, instalação de dependências e o bloco `openclaw` usado para entrypoints, controle de instalação, configuração ou metadados de catálogo | Se você não tiver certeza de onde um metadado pertence, use esta regra: - se o OpenClaw precisa conhecê-lo antes de carregar o código do plugin, coloque-o em `openclaw.plugin.json` -- se ele trata de empacotamento, arquivos de entrada ou comportamento de instalação do npm, coloque-o em `package.json` +- se for sobre empacotamento, arquivos de entrada ou comportamento de instalação do npm, coloque-o em `package.json` ### Campos de `package.json` que afetam a descoberta -Alguns metadados de plugin pré-runtime ficam intencionalmente em `package.json`, dentro do bloco `openclaw`, em vez de `openclaw.plugin.json`. +Alguns metadados de plugin pré-runtime intencionalmente ficam em `package.json` no bloco +`openclaw`, em vez de `openclaw.plugin.json`. Exemplos importantes: -| Campo | O que significa | -| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.extensions` | Declara entrypoints nativos de plugin. | -| `openclaw.setupEntry` | Entrypoint leve apenas para configuração usado durante o onboarding e a inicialização adiada de canal. | +| Campo | O que significa | +| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.extensions` | Declara entrypoints de plugin nativo. | +| `openclaw.setupEntry` | Entrypoint leve apenas de configuração usado durante onboarding e inicialização adiada de canal. | | `openclaw.channel` | Metadados leves de catálogo de canal, como rótulos, caminhos de documentação, aliases e texto de seleção. | -| `openclaw.channel.configuredState` | Metadados leves do verificador de estado configurado que podem responder "a configuração apenas por env já existe?" sem carregar o runtime completo do canal. | +| `openclaw.channel.configuredState` | Metadados leves do verificador de estado configurado que podem responder "já existe configuração somente por env?" sem carregar o runtime completo do canal. | | `openclaw.channel.persistedAuthState` | Metadados leves do verificador de autenticação persistida que podem responder "já existe algo autenticado?" sem carregar o runtime completo do canal. | -| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Dicas de instalação/atualização para plugins empacotados e publicados externamente. | -| `openclaw.install.defaultChoice` | Caminho de instalação preferido quando várias fontes de instalação estão disponíveis. | -| `openclaw.install.minHostVersion` | Versão mínima compatível do host OpenClaw, usando um piso de semver como `>=2026.3.22`. | -| `openclaw.install.allowInvalidConfigRecovery` | Permite um caminho restrito de recuperação por reinstalação de plugin empacotado quando a configuração é inválida. | -| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Permite que superfícies de canal apenas de configuração sejam carregadas antes do plugin completo do canal durante a inicialização. | +| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Dicas de instalação/atualização para plugins empacotados e publicados externamente. | +| `openclaw.install.defaultChoice` | Caminho de instalação preferido quando várias fontes de instalação estão disponíveis. | +| `openclaw.install.minHostVersion` | Versão mínima suportada do host OpenClaw, usando um piso semver como `>=2026.3.22`. | +| `openclaw.install.allowInvalidConfigRecovery` | Permite um caminho restrito de recuperação por reinstalação de plugin empacotado quando a configuração é inválida. | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Permite que superfícies de canal apenas de configuração carreguem antes do plugin de canal completo durante a inicialização. | -`openclaw.install.minHostVersion` é aplicado durante a instalação e o carregamento do registro de manifestos. Valores inválidos são rejeitados; valores válidos, porém mais novos, fazem o plugin ser ignorado em hosts mais antigos. +`openclaw.install.minHostVersion` é aplicado durante a instalação e o carregamento do registro +de manifestos. Valores inválidos são rejeitados; valores válidos, mas mais novos, ignoram o +plugin em hosts mais antigos. -`openclaw.install.allowInvalidConfigRecovery` é intencionalmente restrito. Ele não torna configurações arbitrariamente quebradas instaláveis. Hoje ele permite apenas que fluxos de instalação se recuperem de falhas específicas e antigas de upgrade de plugin empacotado, como um caminho ausente de plugin empacotado ou uma entrada `channels.` antiga para esse mesmo plugin empacotado. Erros de configuração não relacionados continuam bloqueando a instalação e encaminham operadores para `openclaw doctor --fix`. +`openclaw.install.allowInvalidConfigRecovery` é intencionalmente restrito. Ele não torna +instaláveis configurações arbitrariamente quebradas. Hoje, ele apenas permite que fluxos de instalação +se recuperem de falhas específicas e obsoletas de atualização de plugin empacotado, como um +caminho ausente do plugin empacotado ou uma entrada `channels.` obsoleta para esse mesmo +plugin empacotado. Erros de configuração não relacionados ainda bloqueiam a instalação e enviam os +operadores para `openclaw doctor --fix`. -`openclaw.channel.persistedAuthState` é um metadado de pacote para um módulo verificador mínimo: +`openclaw.channel.persistedAuthState` é um metadado de pacote para um módulo verificador +mínimo: ```json { @@ -453,9 +506,13 @@ Exemplos importantes: } ``` -Use-o quando fluxos de configuração, Doctor ou estado configurado precisarem de uma verificação barata de autenticação sim/não antes de o plugin completo do canal ser carregado. A exportação de destino deve ser uma função pequena que leia apenas o estado persistido; não a encaminhe pelo barrel completo de runtime do canal. +Use isso quando fluxos de configuração, doctor ou estado configurado precisarem de uma sondagem barata +de autenticação sim/não antes de o plugin completo do canal carregar. A exportação de destino deve ser uma função +pequena que leia apenas o estado persistido; não a encaminhe pelo barrel completo do runtime do +canal. -`openclaw.channel.configuredState` segue o mesmo formato para verificações baratas de estado configurado apenas por env: +`openclaw.channel.configuredState` segue o mesmo formato para verificações leves de estado +configurado somente por env: ```json { @@ -471,42 +528,64 @@ Use-o quando fluxos de configuração, Doctor ou estado configurado precisarem d } ``` -Use-o quando um canal puder responder ao estado configurado a partir de env ou outras entradas pequenas fora do runtime. Se a verificação precisar da resolução completa da configuração ou do runtime real do canal, mantenha essa lógica no hook `config.hasConfiguredState` do plugin. +Use isso quando um canal puder responder ao estado configurado a partir de env ou de outras entradas +mínimas não ligadas ao runtime. Se a verificação precisar da resolução completa da configuração ou do runtime +real do canal, mantenha essa lógica no hook `config.hasConfiguredState` do plugin. -## Requisitos do JSON Schema +## Requisitos do esquema JSON -- **Todo plugin deve fornecer um JSON Schema**, mesmo que não aceite nenhuma configuração. -- Um schema vazio é aceitável, por exemplo `{ "type": "object", "additionalProperties": false }`. -- Os schemas são validados no momento de leitura/gravação da configuração, não em runtime. +- **Todo plugin deve fornecer um esquema JSON**, mesmo que não aceite configuração. +- Um esquema vazio é aceitável (por exemplo, `{ "type": "object", "additionalProperties": false }`). +- Os esquemas são validados no momento de leitura/gravação da configuração, não em runtime. ## Comportamento de validação -- Chaves desconhecidas em `channels.*` são **erros**, a menos que o ID do canal seja declarado por um manifesto de plugin. -- `plugins.entries.`, `plugins.allow`, `plugins.deny` e `plugins.slots.*` devem referenciar IDs de plugin **detectáveis**. IDs desconhecidos são **erros**. -- Se um plugin estiver instalado, mas tiver um manifesto ou schema ausente ou com erro, a validação falha e o Doctor informa o erro do plugin. -- Se a configuração do plugin existir, mas o plugin estiver **desabilitado**, a configuração é mantida e um **aviso** é exibido no Doctor + logs. +- Chaves desconhecidas em `channels.*` são **erros**, a menos que o ID do canal seja declarado por + um manifesto de plugin. +- `plugins.entries.`, `plugins.allow`, `plugins.deny` e `plugins.slots.*` + devem referenciar IDs de plugin **detectáveis**. IDs desconhecidos são **erros**. +- Se um plugin estiver instalado, mas tiver um manifesto ou esquema ausente ou quebrado, + a validação falhará e o Doctor reportará o erro do plugin. +- Se existir configuração de plugin, mas o plugin estiver **desabilitado**, a configuração será mantida e + um **aviso** será exibido no Doctor + logs. -Consulte [Referência de configuração](/pt-BR/gateway/configuration) para o schema completo de `plugins.*`. +Veja [Referência de configuração](/pt-BR/gateway/configuration) para o esquema completo de `plugins.*`. ## Observações - O manifesto é **obrigatório para plugins nativos do OpenClaw**, incluindo carregamentos locais do sistema de arquivos. -- O runtime ainda carrega o módulo do plugin separadamente; o manifesto serve apenas para descoberta + validação. -- Manifestos nativos são analisados com JSON5, então comentários, vírgulas finais e chaves sem aspas são aceitos, desde que o valor final ainda seja um objeto. -- Apenas os campos documentados do manifesto são lidos pelo carregador de manifesto. Evite adicionar aqui chaves personalizadas de nível superior. -- `providerAuthEnvVars` é o caminho de metadados leve para sondagens de autenticação, validação de marcadores de env e superfícies semelhantes de autenticação de provedor que não devem iniciar o runtime do plugin apenas para inspecionar nomes de env. -- `providerAuthAliases` permite que variantes de provedor reutilizem variáveis de ambiente de autenticação, perfis de autenticação, autenticação baseada em configuração e a opção de onboarding por chave de API de outro provedor sem codificar rigidamente esse relacionamento no core. -- `channelEnvVars` é o caminho de metadados leve para fallback de env do shell, prompts de configuração e superfícies semelhantes de canal que não devem iniciar o runtime do plugin apenas para inspecionar nomes de env. -- `providerAuthChoices` é o caminho de metadados leve para seletores de opção de autenticação, resolução de `--auth-choice`, mapeamento de provedor preferido e registro simples de flags da CLI de onboarding antes de o runtime do provedor ser carregado. Para metadados de assistente de runtime que exigem código do provedor, consulte [Hooks de runtime do provedor](/pt-BR/plugins/architecture#provider-runtime-hooks). +- O runtime ainda carrega o módulo do plugin separadamente; o manifesto serve apenas para + descoberta + validação. +- Manifestos nativos são analisados com JSON5, então comentários, vírgulas à direita e + chaves sem aspas são aceitos, contanto que o valor final continue sendo um objeto. +- Apenas campos documentados do manifesto são lidos pelo carregador de manifestos. Evite adicionar + chaves personalizadas de nível superior aqui. +- `providerAuthEnvVars` é o caminho leve de metadados para sondagens de autenticação, validação de marcadores de env + e superfícies semelhantes de autenticação de provedor que não devem iniciar o runtime do plugin + apenas para inspecionar nomes de env. +- `providerAuthAliases` permite que variantes de provedor reutilizem as variáveis de ambiente de autenticação de outro provedor, + perfis de autenticação, autenticação baseada em configuração e escolha de onboarding de chave de API + sem codificar esse relacionamento no core. +- `channelEnvVars` é o caminho leve de metadados para fallback de env do shell, prompts de configuração + e superfícies semelhantes de canal que não devem iniciar o runtime do plugin + apenas para inspecionar nomes de env. +- `providerAuthChoices` é o caminho leve de metadados para seletores de escolha de autenticação, + resolução de `--auth-choice`, mapeamento de provedor preferencial e registro simples + de flags de CLI de onboarding antes de o runtime do provedor carregar. Para metadados + de assistente de runtime que exigem código do provedor, veja + [Hooks de runtime do provedor](/pt-BR/plugins/architecture#provider-runtime-hooks). - Tipos exclusivos de plugin são selecionados por meio de `plugins.slots.*`. - `kind: "memory"` é selecionado por `plugins.slots.memory`. - - `kind: "context-engine"` é selecionado por `plugins.slots.contextEngine` (padrão: `legacy` interno). -- `channels`, `providers`, `cliBackends` e `skills` podem ser omitidos quando um plugin não precisa deles. -- Se seu plugin depender de módulos nativos, documente as etapas de build e quaisquer requisitos de allowlist do gerenciador de pacotes, por exemplo pnpm `allow-build-scripts` - - `pnpm rebuild `. + - `kind: "context-engine"` é selecionado por `plugins.slots.contextEngine` + (padrão: `legacy` embutido). +- `channels`, `providers`, `cliBackends` e `skills` podem ser omitidos quando um + plugin não precisar deles. +- Se seu plugin depender de módulos nativos, documente as etapas de build e quaisquer + requisitos de allowlist do gerenciador de pacotes (por exemplo, pnpm `allow-build-scripts` + - `pnpm rebuild `). ## Relacionado -- [Criando Plugins](/pt-BR/plugins/building-plugins) — primeiros passos com plugins -- [Arquitetura de plugins](/pt-BR/plugins/architecture) — arquitetura interna -- [Visão geral do SDK](/pt-BR/plugins/sdk-overview) — referência do SDK de plugins +- [Criando Plugins](/pt-BR/plugins/building-plugins) — introdução a plugins +- [Arquitetura de Plugins](/pt-BR/plugins/architecture) — arquitetura interna +- [Visão geral do SDK](/pt-BR/plugins/sdk-overview) — referência do SDK de Plugins diff --git a/docs/pt-BR/reference/templates/AGENTS.md b/docs/pt-BR/reference/templates/AGENTS.md index 35e58d781..21941a205 100644 --- a/docs/pt-BR/reference/templates/AGENTS.md +++ b/docs/pt-BR/reference/templates/AGENTS.md @@ -4,59 +4,64 @@ read_when: summary: Modelo de workspace para AGENTS.md title: Modelo de AGENTS.md x-i18n: - generated_at: "2026-04-11T02:47:24Z" + generated_at: "2026-04-12T05:33:09Z" model: gpt-5.4 provider: openai - source_hash: 6d8a3e96f547da6cc082d747c042555b0ec4963b66921d1700b4590f0e0c38b4 + source_hash: b7a68a1f0b4b837298bfe6edf8ce855d6ef6902ea8e7277b0d9a8442b23daf54 source_path: reference/templates/AGENTS.md workflow: 15 --- -# AGENTS.md - Seu workspace +# AGENTS.md - Seu Workspace -Esta pasta é a sua casa. Trate-a assim. +Esta pasta é sua casa. Trate-a como tal. ## Primeira execução -Se `BOOTSTRAP.md` existir, essa é a sua certidão de nascimento. Siga-o, descubra quem você é e depois exclua-o. Você não vai precisar dele novamente. +Se `BOOTSTRAP.md` existir, essa é a sua certidão de nascimento. Siga-o, descubra quem você é e então exclua-o. Você não vai precisar dele novamente. -## Início da sessão +## Inicialização da sessão -Antes de fazer qualquer outra coisa: +Use primeiro o contexto de inicialização fornecido pelo runtime. -1. Leia `SOUL.md` — isso é quem você é -2. Leia `USER.md` — isso é quem você está ajudando -3. Leia `memory/YYYY-MM-DD.md` (hoje + ontem) para contexto recente -4. **Se estiver na SESSÃO PRINCIPAL** (chat direto com seu humano): leia também `MEMORY.md` +Esse contexto talvez já inclua: -Não peça permissão. Apenas faça. +- `AGENTS.md`, `SOUL.md` e `USER.md` +- memória diária recente, como `memory/YYYY-MM-DD.md` +- `MEMORY.md` quando esta for a sessão principal + +Não releia manualmente os arquivos de inicialização, a menos que: + +1. O usuário peça explicitamente +2. Falte no contexto fornecido algo de que você precisa +3. Você precise fazer uma leitura complementar mais profunda além do contexto de inicialização fornecido ## Memória -Você acorda do zero em cada sessão. Estes arquivos são a sua continuidade: +Você desperta renovado a cada sessão. Estes arquivos são a sua continuidade: -- **Notas diárias:** `memory/YYYY-MM-DD.md` (crie `memory/` se necessário) — logs brutos do que aconteceu +- **Notas diárias:** `memory/YYYY-MM-DD.md` (crie `memory/` se necessário) — registros brutos do que aconteceu - **Longo prazo:** `MEMORY.md` — suas memórias curadas, como a memória de longo prazo de um humano -Registre o que importa. Decisões, contexto, coisas para lembrar. Pule os segredos, a menos que peçam para guardá-los. +Registre o que importa. Decisões, contexto, coisas para lembrar. Ignore segredos, a menos que peçam para guardá-los. ### 🧠 MEMORY.md - Sua memória de longo prazo -- **Carregue APENAS na sessão principal** (chats diretos com seu humano) +- **Carregue SOMENTE na sessão principal** (conversas diretas com seu humano) - **NÃO carregue em contextos compartilhados** (Discord, chats em grupo, sessões com outras pessoas) -- Isso é por **segurança** — contém contexto pessoal que não deve vazar para estranhos +- Isto é por **segurança** — contém contexto pessoal que não deve vazar para estranhos - Você pode **ler, editar e atualizar** `MEMORY.md` livremente em sessões principais -- Escreva eventos significativos, pensamentos, decisões, opiniões e lições aprendidas -- Esta é a sua memória curada — a essência destilada, não logs brutos -- Com o tempo, revise seus arquivos diários e atualize `MEMORY.md` com o que vale a pena guardar +- Escreva eventos, pensamentos, decisões, opiniões e lições significativos +- Esta é sua memória curada — a essência destilada, não registros brutos +- Com o tempo, revise seus arquivos diários e atualize `MEMORY.md` com o que vale a pena manter ### 📝 Anote - Nada de "notas mentais"! -- **A memória é limitada** — se você quiser lembrar de algo, ESCREVA EM UM ARQUIVO -- "Notas mentais" não sobrevivem ao reinício da sessão. Arquivos sobrevivem. +- **A memória é limitada** — se você quiser se lembrar de algo, ESCREVA EM UM ARQUIVO +- "Notas mentais" não sobrevivem a reinicializações de sessão. Arquivos sim. - Quando alguém disser "lembre-se disso" → atualize `memory/YYYY-MM-DD.md` ou o arquivo relevante -- Quando você aprender uma lição → atualize AGENTS.md, TOOLS.md ou a skill relevante -- Quando você cometer um erro → documente para que você do futuro não o repita +- Quando aprender uma lição → atualize AGENTS.md, TOOLS.md ou a skill relevante +- Quando cometer um erro → documente-o para que seu eu do futuro não o repita - **Texto > Cérebro** 📝 ## Linhas vermelhas @@ -68,7 +73,7 @@ Registre o que importa. Decisões, contexto, coisas para lembrar. Pule os segred ## Externo vs interno -**Seguro fazer livremente:** +**Seguro para fazer livremente:** - Ler arquivos, explorar, organizar, aprender - Pesquisar na web, verificar calendários @@ -76,13 +81,13 @@ Registre o que importa. Decisões, contexto, coisas para lembrar. Pule os segred **Pergunte antes:** -- Enviar e-mails, tweets, posts públicos +- Enviar emails, tweets, posts públicos - Qualquer coisa que saia da máquina -- Qualquer coisa sobre a qual você não tenha certeza +- Qualquer coisa sobre a qual você esteja em dúvida ## Chats em grupo -Você tem acesso às coisas do seu humano. Isso não significa que você _compartilha_ as coisas dele. Em grupos, você é um participante — não a voz dele, nem o representante dele. Pense antes de falar. +Você tem acesso às coisas do seu humano. Isso não significa que você _compartilha_ as coisas dele. Em grupos, você é um participante — não a voz dele, não o representante dele. Pense antes de falar. ### 💬 Saiba quando falar! @@ -91,87 +96,87 @@ Em chats em grupo nos quais você recebe todas as mensagens, seja **inteligente **Responda quando:** - Você for mencionado diretamente ou receber uma pergunta -- Você puder agregar valor genuíno (informação, insight, ajuda) +- Você puder agregar valor real (informação, insight, ajuda) - Algo espirituoso/divertido se encaixar naturalmente -- For preciso corrigir uma desinformação importante +- For preciso corrigir desinformação importante - Pedirem um resumo **Fique em silêncio (`HEARTBEAT_OK`) quando:** -- For apenas conversa casual entre humanos +- For só conversa casual entre humanos - Alguém já tiver respondido à pergunta -- Sua resposta seria só "sim" ou "boa" +- Sua resposta seria apenas "sim" ou "boa" - A conversa estiver fluindo bem sem você - Adicionar uma mensagem interromperia o clima -**A regra humana:** Humanos em chats em grupo não respondem a cada mensagem. Você também não deve. Qualidade > quantidade. Se você não enviaria isso em um chat real com amigos, não envie. +**A regra humana:** Humanos em chats em grupo não respondem a cada mensagem. Você também não deve responder. Qualidade > quantidade. Se você não enviaria isso em um chat em grupo real com amigos, não envie. -**Evite o triplo toque:** Não responda várias vezes à mesma mensagem com reações diferentes. Uma resposta pensada vale mais do que três fragmentos. +**Evite o triplo toque:** Não responda várias vezes à mesma mensagem com reações diferentes. Uma resposta cuidadosa é melhor do que três fragmentos. Participe, não domine. ### 😊 Reaja como um humano! -Em plataformas com suporte a reações (Discord, Slack), use reações com emoji de forma natural: +Em plataformas que suportam reações (Discord, Slack), use reações com emoji de forma natural: **Reaja quando:** - Você aprecia algo, mas não precisa responder (👍, ❤️, 🙌) - Algo fez você rir (😂, 💀) - Você achou interessante ou instigante (🤔, 💡) -- Você quer reconhecer algo sem interromper o fluxo -- É uma situação simples de sim/não ou aprovação (✅, 👀) +- Você quer reconhecer sem interromper o fluxo +- For uma situação simples de sim/não ou aprovação (✅, 👀) **Por que isso importa:** -Reações são sinais sociais leves. Humanos as usam o tempo todo — elas dizem "eu vi isso, reconheço você" sem poluir o chat. Você também deveria. +Reações são sinais sociais leves. Humanos as usam o tempo todo — elas dizem "eu vi isso, eu reconheço você" sem poluir o chat. Você também deve fazer isso. -**Não exagere:** no máximo uma reação por mensagem. Escolha a que melhor se encaixar. +**Não exagere:** No máximo uma reação por mensagem. Escolha a que melhor se encaixar. ## Ferramentas -As Skills fornecem suas ferramentas. Quando precisar de uma, verifique o `SKILL.md` dela. Mantenha notas locais (nomes de câmera, detalhes de SSH, preferências de voz) em `TOOLS.md`. +As Skills fornecem suas ferramentas. Quando precisar de uma, consulte o `SKILL.md` dela. Mantenha notas locais (nomes de câmera, detalhes de SSH, preferências de voz) em `TOOLS.md`. -**🎭 Narração por voz:** Se você tiver `sag` (TTS da ElevenLabs), use voz para histórias, resumos de filmes e momentos de "hora da história"! É muito mais envolvente do que paredes de texto. Surpreenda as pessoas com vozes engraçadas. +**🎭 Narração por voz:** Se você tiver `sag` (ElevenLabs TTS), use voz para histórias, resumos de filmes e momentos de "hora da história"! Muito mais envolvente do que muralhas de texto. Surpreenda as pessoas com vozes engraçadas. **📝 Formatação por plataforma:** -- **Discord/WhatsApp:** Sem tabelas em markdown! Use listas com marcadores -- **Links no Discord:** Envolva vários links em `<>` para suprimir embeds: `` -- **WhatsApp:** Sem cabeçalhos — use **negrito** ou MAIÚSCULAS para dar ênfase +- **Discord/WhatsApp:** Nada de tabelas em markdown! Use listas com marcadores +- **Links no Discord:** Coloque vários links entre `<>` para suprimir embeds: `` +- **WhatsApp:** Sem cabeçalhos — use **negrito** ou CAIXA ALTA para dar ênfase ## 💓 Heartbeats - Seja proativo! -Quando você receber um heartbeat poll (mensagem correspondente ao prompt de heartbeat configurado), não responda apenas `HEARTBEAT_OK` toda vez. Use os heartbeats de forma produtiva! +Quando você receber uma sondagem de heartbeat (mensagem que corresponde ao prompt de heartbeat configurado), não responda apenas `HEARTBEAT_OK` toda vez. Use heartbeats de forma produtiva! -Você pode editar livremente `HEARTBEAT.md` com uma lista curta de verificação ou lembretes. Mantenha pequeno para limitar o gasto de tokens. +Você pode editar livremente `HEARTBEAT.md` com uma pequena checklist ou lembretes. Mantenha-o pequeno para limitar o consumo de tokens. ### Heartbeat vs Cron: quando usar cada um **Use heartbeat quando:** -- Várias verificações puderem ser agrupadas (caixa de entrada + calendário + notificações em um só turno) +- Várias verificações puderem ser agrupadas (caixa de entrada + calendário + notificações em um turno) - Você precisar de contexto conversacional de mensagens recentes -- O timing puder variar um pouco (a cada ~30 min está bom, não precisa ser exato) +- O horário puder variar um pouco (a cada ~30 min está bom, não precisa ser exato) - Você quiser reduzir chamadas de API combinando verificações periódicas **Use cron quando:** -- O horário exato importar ("9:00 em ponto toda segunda-feira") +- O horário exato importar ("às 9:00 em ponto toda segunda-feira") - A tarefa precisar de isolamento do histórico da sessão principal - Você quiser um modelo diferente ou outro nível de raciocínio para a tarefa -- Quiser lembretes pontuais ("me lembre em 20 minutos") -- A saída precisar ser entregue diretamente a um canal sem envolver a sessão principal +- Forem lembretes pontuais ("me lembre em 20 minutos") +- A saída deva ser entregue diretamente a um canal sem envolver a sessão principal **Dica:** Agrupe verificações periódicas semelhantes em `HEARTBEAT.md` em vez de criar vários jobs cron. Use cron para agendas precisas e tarefas independentes. -**Coisas para verificar (rode entre elas, de 2 a 4 vezes por dia):** +**Coisas para verificar (altere entre elas, 2 a 4 vezes por dia):** -- **E-mails** - Há mensagens urgentes não lidas? +- **Emails** - Há mensagens não lidas urgentes? - **Calendário** - Há eventos próximos nas próximas 24-48h? -- **Menções** - Notificações de Twitter/redes sociais? -- **Clima** - Relevante se seu humano puder sair? +- **Menções** - Notificações no Twitter/redes sociais? +- **Clima** - É relevante caso seu humano vá sair? -**Acompanhe suas verificações** em `memory/heartbeat-state.json`: +**Registre suas verificações** em `memory/heartbeat-state.json`: ```json { @@ -185,12 +190,12 @@ Você pode editar livremente `HEARTBEAT.md` com uma lista curta de verificação **Quando entrar em contato:** -- Chegou um e-mail importante +- Chegou um email importante - Um evento do calendário está próximo (<2h) - Você encontrou algo interessante -- Faz >8h desde a última vez que você falou algo +- Faz >8h desde a última vez que você disse algo -**Quando ficar quieto (`HEARTBEAT_OK`):** +**Quando ficar em silêncio (`HEARTBEAT_OK`):** - Tarde da noite (23:00-08:00), a menos que seja urgente - O humano esteja claramente ocupado @@ -203,21 +208,21 @@ Você pode editar livremente `HEARTBEAT.md` com uma lista curta de verificação - Verificar projetos (git status etc.) - Atualizar documentação - Fazer commit e push das suas próprias alterações -- **Revisar e atualizar MEMORY.md** (veja abaixo) +- **Revisar e atualizar `MEMORY.md`** (veja abaixo) -### 🔄 Manutenção de memória (durante heartbeats) +### 🔄 Manutenção da memória (durante heartbeats) Periodicamente (a cada poucos dias), use um heartbeat para: -1. Ler os arquivos recentes `memory/YYYY-MM-DD.md` -2. Identificar eventos significativos, lições ou insights que valham a pena manter no longo prazo +1. Ler arquivos recentes `memory/YYYY-MM-DD.md` +2. Identificar eventos, lições ou insights significativos que valham a pena manter no longo prazo 3. Atualizar `MEMORY.md` com aprendizados destilados -4. Remover informações desatualizadas de `MEMORY.md` que não sejam mais relevantes +4. Remover de `MEMORY.md` informações desatualizadas que não sejam mais relevantes -Pense nisso como um humano revendo seu diário e atualizando seu modelo mental. Os arquivos diários são notas brutas; `MEMORY.md` é sabedoria curada. +Pense nisso como um humano revisando seu diário e atualizando seu modelo mental. Os arquivos diários são notas brutas; `MEMORY.md` é sabedoria curada. O objetivo: ser útil sem ser incômodo. Verifique algumas vezes por dia, faça trabalho útil em segundo plano, mas respeite os momentos de silêncio. -## Faça do seu jeito +## Deixe com a sua cara Este é um ponto de partida. Adicione suas próprias convenções, estilo e regras à medida que descobrir o que funciona. diff --git a/docs/pt-BR/reference/token-use.md b/docs/pt-BR/reference/token-use.md index 371b73b0c..7ea804506 100644 --- a/docs/pt-BR/reference/token-use.md +++ b/docs/pt-BR/reference/token-use.md @@ -1,22 +1,22 @@ --- read_when: - - Explicando uso de tokens, custos ou janelas de contexto - - Depurando crescimento de contexto ou comportamento de compactação -summary: Como o OpenClaw monta o contexto do prompt e relata uso de tokens + custos + - 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 x-i18n: - generated_at: "2026-04-07T05:31:38Z" + generated_at: "2026-04-12T05:33:21Z" model: gpt-5.4 provider: openai - source_hash: 0683693d6c6fcde7d5fba236064ba97dd4b317ae6bea3069db969fcd178119d9 + source_hash: f8c856549cd28b8364a640e6fa9ec26aa736895c7a993e96cbe85838e7df2dfb 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 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 uma média de ~4 caracteres por token em texto em inglês. ## Como o prompt do sistema é montado @@ -25,105 +25,105 @@ 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`) - Instruções de autoatualização -- Workspace + arquivos de bootstrap (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md` quando novos, 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 `memory/*.md` são sob demanda via ferramentas de memória e não são injetados automaticamente. +- 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`. - Hora (UTC + fuso horário do usuário) - Tags de resposta + comportamento de heartbeat - Metadados de runtime (host/OS/model/thinking) -Consulte a decomposição completa em [Prompt do sistema](/pt-BR/concepts/system-prompt). +Veja o detalhamento completo 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 + do assistente) -- Chamadas de ferramenta e resultados de ferramenta +- Histórico da conversa (mensagens do usuário + assistente) +- Chamadas de ferramentas e resultados de ferramentas - Anexos/transcrições (imagens, áudio, arquivos) - Resumos de compactação e artefatos de poda -- Wrappers do provedor ou cabeçalhos de segurança (não visíveis, mas ainda contam) +- Wrappers do provedor ou cabeçalhos de segurança (não visíveis, mas ainda contabilizados) -Para imagens, o OpenClaw reduz o tamanho de payloads de imagem de transcript/ferramenta antes das chamadas ao provedor. +Para imagens, o OpenClaw reduz a escala das cargas de imagens de transcrição/ferramentas antes das chamadas ao provedor. Use `agents.defaults.imageMaxDimensionPx` (padrão: `1200`) para ajustar isso: -- Valores menores normalmente reduzem o uso de vision-tokens e o tamanho do payload. -- Valores maiores preservam mais detalhes visuais para OCR/capturas de tela pesadas em UI. +- 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. -Para uma decomposição prática (por arquivo injetado, ferramentas, Skills e tamanho do prompt do sistema), use `/context list` ou `/context detail`. Consulte [Contexto](/pt-BR/concepts/context). +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). ## Como ver o uso atual de tokens Use estes comandos no chat: -- `/status` → **cartão de status rico em emoji** com o modelo da sessão, uso de contexto, +- `/status` → **cartão de status rico em emojis** 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` → acrescenta um **rodapé de uso por resposta** a cada resposta. +- `/usage off|tokens|full` → adiciona um **rodapé de uso por resposta** a cada resposta. - Persiste por sessão (armazenado como `responseUsage`). - - Auth OAuth **oculta custo** (somente tokens). + - 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. 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% left`, não custos por resposta). - Provedores atuais de janela de uso: Anthropic, GitHub Copilot, Gemini CLI, + janelas de cota normalizadas do provedor (`X% restantes`, 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 Responses da família OpenAI, isso inclui tanto `input_tokens` / -`output_tokens` quanto `prompt_tokens` / `completion_tokens`, para que nomes de campo -específicos de transporte não alterem `/status`, `/usage` ou resumos de sessão. -O uso JSON do Gemini CLI também é normalizado: o texto da resposta vem de `response`, e +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 `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 Responses nativo da família OpenAI, aliases de uso WebSocket/SSE são +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 `total_tokens` está ausente ou é `0`. -Quando o snapshot da sessão atual é escasso, `/status` e `session_status` também podem -recuperar contadores de token/cache e o rótulo do modelo de runtime ativo do -log de uso mais recente do transcript. Valores live existentes e diferentes de zero ainda têm -precedência sobre valores de fallback do transcript, e totais maiores orientados por prompt -do transcript podem prevalecer quando os totais armazenados estiverem ausentes ou menores. -A auth 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 credenciais OAuth/chave de API correspondentes -de perfis auth, env ou config. +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 +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 +de perfis de autenticação, env ou config. -## Estimativa de custo (quando mostrada) +## Estimativa de custo (quando exibida) -Os custos são estimados a partir da sua configuração de preços do modelo: +Os custos são estimados a partir da configuração de preços do seu modelo: ``` models.providers..models[].cost ``` -Esses valores são em **USD por 1M tokens** para `input`, `output`, `cacheRead` e -`cacheWrite`. Se não houver preços, o OpenClaw mostra apenas tokens. Tokens OAuth +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. -## Impacto do TTL de cache e da poda +## Impacto de TTL de cache e poda O cache de prompt do provedor só se aplica dentro da janela de TTL do cache. O OpenClaw pode -executar opcionalmente **poda de cache-ttl**: ele poda a sessão quando o TTL do cache -expira e depois redefine a janela de cache para que solicitações subsequentes possam reutilizar o -contexto recém-colocado em cache, em vez de recachear todo o histórico. Isso mantém os custos -de gravação de cache mais baixos quando uma sessão fica ociosa além do TTL. +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. -Configure isso em [Configuração do gateway](/pt-BR/gateway/configuration) e veja os +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). -O 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 um pouco abaixo disso (por exemplo, `55m`) pode evitar -recachear o prompt completo, reduzindo custos de gravação de cache. +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. -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`. +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`. -Para um guia completo, opção por opção, consulte [Prompt Caching](/pt-BR/reference/prompt-caching). +Para um guia completo de cada ajuste, 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 de cache são cobradas com um multiplicador mais alto. Consulte os -preços de prompt caching da Anthropic para as taxas e multiplicadores de TTL mais recentes: +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: [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 @@ -159,16 +159,16 @@ agents: every: "55m" # mantém o cache longo aquecido para sessões profundas - id: "alerts" params: - cacheRetention: "none" # evita gravações de cache para notificações em rajada + cacheRetention: "none" # evita gravações em cache para notificações intermitentes ``` -`agents.list[].params` é mesclado sobre os `params` do modelo selecionado, então você pode +`agents.list[].params` é mesclado sobre `params` do modelo selecionado, então você pode substituir apenas `cacheRetention` e herdar os outros padrões do modelo sem alterações. -### Exemplo: ativar o cabeçalho beta de contexto 1M da Anthropic +### Exemplo: habilitar 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ê ativa `context1m` em modelos Opus +valor `anthropic-beta` necessário quando você habilita `context1m` em modelos Opus ou Sonnet compatíveis. ```yaml @@ -185,7 +185,7 @@ 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. 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 no lado do provedor para essa solicitação. +a Anthropic responde com um erro de limite de taxa do lado do provedor para essa solicitação. Se você autenticar a Anthropic com tokens OAuth/assinatura (`sk-ant-oat-*`), o OpenClaw ignora o cabeçalho beta `context-1m-*` porque a Anthropic atualmente @@ -194,9 +194,9 @@ rejeita essa combinação com HTTP 401. ## Dicas para reduzir a pressão de tokens - Use `/compact` para resumir sessões longas. -- Reduza saídas grandes de ferramentas em seus fluxos de trabalho. -- Diminua `agents.defaults.imageMaxDimensionPx` em sessões com muitas capturas de tela. +- Corte saídas grandes de ferramentas nos seus fluxos de trabalho. +- Reduza `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 verboso e exploratório. +- Prefira modelos menores para trabalho exploratório e verboso. -Consulte [Skills](/pt-BR/tools/skills) para a fórmula exata de sobrecarga da lista de Skills. +Veja [Skills](/pt-BR/tools/skills) para a fórmula exata de overhead da lista de Skills.