openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh pt-BR translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-17 05:39:10 +00:00
parent b8b8a7ab26
commit 65ab16f7ea
5 changed files with 989 additions and 975 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

180
docs/pt-BR/concepts/qa-e2e-automation.md
View File

@ -1,37 +1,37 @@
---
read_when:
- Estendendo qa-lab ou qa-channel
- Estendendo o qa-lab ou o qa-channel
- Adicionando cenários de QA com suporte do repositório
- Criando automação de QA com maior realismo em torno do painel do Gateway
summary: Formato da automação privada de QA para qa-lab, qa-channel, cenários com seed e relatórios de protocolo
- Criando uma automação de QA com maior realismo em torno do painel do Gateway
summary: Forma da automação privada de QA para qa-lab, qa-channel, cenários com seed e relatórios de protocolo
title: Automação E2E de QA
x-i18n:
generated_at: "2026-04-16T21:51:16Z"
generated_at: "2026-04-17T05:36:09Z"
model: gpt-5.4
provider: openai
source_hash: 7deefda1c90a0d2e21e2155ffd8b585fb999e7416bdbaf0ff57eb33ccc063afc
source_hash: 51f97293c184d7c04c95d9858305668fbc0f93273f587ec7e54896ad5d603ab0
source_path: concepts/qa-e2e-automation.md
workflow: 15
---
# Automação E2E de QA
A stack privada de QA foi criada para exercitar o OpenClaw de uma forma mais realista,
no formato de canal, do que um único teste unitário consegue.
A stack privada de QA foi feita para exercitar o OpenClaw de uma forma mais realista,
no formato de canais, do que um único teste unitário consegue.
Peças atuais:
- `extensions/qa-channel`: canal de mensagens sintético com superfícies de DM, canal, thread,
reação, edição e exclusão.
- `extensions/qa-lab`: UI de depuração e barramento de QA para observar a transcrição,
injetar mensagens de entrada e exportar um relatório em Markdown.
- `qa/`: recursos de seed com suporte do repositório para a tarefa inicial e cenários
injetar mensagens recebidas e exportar um relatório em Markdown.
- `qa/`: recursos seed com suporte do repositório para a tarefa inicial e cenários
básicos de QA.
O fluxo atual do operador de QA é um site de QA com dois painéis:
- Esquerda: painel do Gateway (Control UI) com o agente.
- Direita: QA Lab, mostrando a transcrição estilo Slack e o plano do cenário.
- Direita: QA Lab, mostrando a transcrição em estilo Slack e o plano de cenário.
Execute com:
@ -39,13 +39,13 @@ Execute com:
pnpm qa:lab:up
```
Isso compila o site de QA, inicia a rota do gateway com suporte de Docker e expõe a
Isso compila o site de QA, inicia a lane do gateway com suporte de Docker e expõe a
página do QA Lab, onde um operador ou loop de automação pode dar ao agente uma
missão de QA, observar o comportamento real do canal e registrar o que funcionou,
falhou ou permaneceu bloqueado.
Para uma iteração mais rápida da UI do QA Lab sem recompilar a imagem Docker toda vez,
inicie a stack com um bundle do QA Lab montado por bind:
Para uma iteração mais rápida da UI do QA Lab sem reconstruir a imagem Docker a cada vez,
inicie a stack com um bundle do QA Lab montado por bind mount:
```bash
pnpm openclaw qa docker-build-image
@ -54,55 +54,55 @@ pnpm qa:lab:up:fast
pnpm qa:lab:watch
```
`qa:lab:up:fast` mantém os serviços Docker em uma imagem pré-compilada e faz bind-mount de
`qa:lab:up:fast` mantém os serviços Docker em uma imagem pré-compilada e faz bind mount de
`extensions/qa-lab/web/dist` no contêiner `qa-lab`. `qa:lab:watch`
recompila esse bundle a cada alteração, e o navegador recarrega automaticamente quando o hash
recompila esse bundle quando há mudanças, e o navegador recarrega automaticamente quando o hash
do recurso do QA Lab muda.
Para uma rota de smoke do Matrix com transporte real, execute:
Para uma lane de smoke do Matrix com transporte real, execute:
```bash
pnpm openclaw qa matrix
```
Essa rota provisiona um homeserver Tuwunel descartável em Docker, registra usuários
Essa lane provisiona um homeserver Tuwunel descartável no Docker, registra usuários
temporários de driver, SUT e observador, cria uma sala privada e então executa
o Plugin real do Matrix dentro de um processo filho de gateway de QA. A rota de transporte ativo
mantém a configuração filha restrita ao transporte em teste, então o Matrix é executado sem
`qa-channel` na configuração filha. Ela grava os artefatos de relatório estruturado e
o Plugin real do Matrix dentro de um filho de gateway de QA. A lane de transporte ao vivo mantém
a configuração do filho restrita ao transporte em teste, então o Matrix roda sem
`qa-channel` na configuração do filho. Ela grava os artefatos do relatório estruturado e
um log combinado de stdout/stderr no diretório de saída de QA do Matrix selecionado. Para
capturar também a saída externa de build/launcher de `scripts/run-node.mjs`, defina
`OPENCLAW_RUN_NODE_OUTPUT_LOG=<path>` como um arquivo de log local ao repositório.
capturar também a saída externa de compilação/launcher de `scripts/run-node.mjs`, defina
`OPENCLAW_RUN_NODE_OUTPUT_LOG=<path>` para um arquivo de log local ao repositório.
Para uma rota de smoke do Telegram com transporte real, execute:
Para uma lane de smoke do Telegram com transporte real, execute:
```bash
pnpm openclaw qa telegram
```
Essa rota mira um grupo privado real do Telegram em vez de provisionar um servidor
descartável. Ela requer `OPENCLAW_QA_TELEGRAM_GROUP_ID`,
Essa lane usa um grupo privado real do Telegram em vez de provisionar um
servidor descartável. Ela exige `OPENCLAW_QA_TELEGRAM_GROUP_ID`,
`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` e
`OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`, além de dois bots distintos no mesmo
grupo privado. O bot SUT deve ter um nome de usuário do Telegram, e a observação
bot-para-bot funciona melhor quando ambos os bots têm o Modo de Comunicação Bot-to-Bot
habilitado no `@BotFather`.
grupo privado. O bot SUT precisa ter um nome de usuário no Telegram, e a
observação bot-para-bot funciona melhor quando ambos os bots têm o Bot-to-Bot Communication Mode
ativado no `@BotFather`.
As rotas de transporte ativo agora compartilham um contrato menor em vez de cada uma
inventar seu próprio formato de lista de cenários:
As lanes de transporte ao vivo agora compartilham um contrato menor em vez de cada uma
inventar o próprio formato de lista de cenários.
`qa-channel` continua sendo a suíte ampla de comportamento sintético do produto e não faz parte
da matriz de cobertura de transporte ativo.
da matriz de cobertura de transporte ao vivo.
| Rota | Canary | Bloqueio por menção | Bloco por allowlist | Resposta de nível superior | Retomada após reinício | Acompanhamento em thread | Isolamento de thread | Observação de reação | Comando de ajuda |
| -------- | ------ | ------------------- | ------------------- | -------------------------- | ---------------------- | ------------------------ | -------------------- | -------------------- | ---------------- |
| Matrix | x | x | x | x | x | x | x | x | |
| Telegram | x | | | | | | | | x |
| Lane | Canary | Bloqueio por menção | Bloqueio por allowlist | Resposta de nível superior | Retomada após reinício | Acompanhamento em thread | Isolamento de thread | Observação de reação | Comando de ajuda |
| -------- | ------ | ------------------- | ---------------------- | -------------------------- | ---------------------- | ------------------------ | -------------------- | -------------------- | ---------------- |
| Matrix | x | x | x | x | x | x | x | x | |
| Telegram | x | | | | | | | | x |
Isso mantém `qa-channel` como a suíte ampla de comportamento do produto, enquanto Matrix,
Telegram e futuros transportes ativos compartilham uma checklist explícita de contrato de transporte.
Telegram e futuros transportes ao vivo compartilham uma checklist explícita de contrato de transporte.
Para uma rota descartável de VM Linux sem colocar o Docker no caminho do QA, execute:
Para uma lane de VM Linux descartável sem colocar Docker no caminho de QA, execute:
```bash
pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline
@ -111,71 +111,87 @@ pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline
Isso inicializa um guest novo do Multipass, instala dependências, compila o OpenClaw
dentro do guest, executa `qa suite` e então copia o relatório e
resumo normais de QA de volta para `.artifacts/qa-e2e/...` no host.
Ele reutiliza o mesmo comportamento de seleção de cenário de `qa suite` no host.
Isso reutiliza o mesmo comportamento de seleção de cenário de `qa suite` no host.
As execuções da suíte no host e no Multipass executam vários cenários selecionados em paralelo
com workers de gateway isolados por padrão, até 64 workers ou a contagem de cenários
selecionada. Use `--concurrency <count>` para ajustar a quantidade de workers, ou
selecionados. Use `--concurrency <count>` para ajustar a quantidade de workers, ou
`--concurrency 1` para execução serial.
As execuções ativas encaminham as entradas de autenticação de QA compatíveis que são práticas para o
guest: chaves de provedor baseadas em env, o caminho de configuração do provedor ativo de QA e
As execuções ao vivo encaminham as entradas de autenticação de QA suportadas que são práticas para o
guest: chaves de provider via variável de ambiente, o caminho de configuração do provider ao vivo de QA e
`CODEX_HOME` quando presente. Mantenha `--output-dir` sob a raiz do repositório para que o guest
possa gravar de volta por meio do workspace montado.
possa gravar de volta pelo workspace montado.
## Seeds com suporte do repositório
Os recursos de seed ficam em `qa/`:
Os recursos seed ficam em `qa/`:
- `qa/scenarios/index.md`
- `qa/scenarios/*.md`
Eles ficam intencionalmente no git para que o plano de QA seja visível tanto para humanos quanto para o
agente.
Eles ficam intencionalmente no git para que o plano de QA seja visível tanto para humanos
quanto para o agente.
`qa-lab` deve permanecer um executor genérico de Markdown. Cada arquivo Markdown de cenário
é a fonte da verdade para uma execução de teste e deve definir:
`qa-lab` deve permanecer um executor genérico de Markdown. Cada arquivo Markdown de cenário é
a fonte da verdade para uma execução de teste e deve definir:
- metadados do cenário
- referências de documentação e código
- requisitos opcionais de Plugin
- referências de docs e código
- requisitos opcionais de plugin
- patch opcional de configuração do gateway
- o `qa-flow` executável
A superfície de runtime reutilizável que dá suporte a `qa-flow` pode continuar sendo genérica
A superfície de runtime reutilizável que dá suporte ao `qa-flow` pode permanecer genérica
e transversal. Por exemplo, cenários em Markdown podem combinar helpers do lado do transporte
com helpers do lado do navegador que dirigem a Control UI embutida por meio da superfície
Gateway `browser.request` sem adicionar um executor com caso especial.
com helpers do lado do navegador que controlam a Control UI embutida por meio da
superfície `browser.request` do Gateway sem adicionar um executor com caso especial.
A lista básica deve permanecer ampla o suficiente para cobrir:
- chat em DM e canal
- chat em DM e em canal
- comportamento de thread
- ciclo de vida de ações de mensagem
- callbacks de Cron
- recuperação de memória
- troca de modelo
- handoff de subagente
- leitura de repositório e documentação
- handoff para subagente
- leitura do repositório e de docs
- uma pequena tarefa de compilação, como Lobster Invaders
## Lanes de mock de provider
`qa suite` tem duas lanes locais de mock de provider:
- `mock-openai` é o mock do OpenClaw sensível ao cenário. Ele continua sendo a
lane de mock determinística padrão para QA com suporte do repositório e gates de paridade.
- `aimock` inicia um servidor de provider com suporte do AIMock para cobertura experimental de protocolo,
fixture, gravação/reprodução e caos. Ele é aditivo e não substitui o dispatcher
de cenários do `mock-openai`.
A implementação da lane de provider fica em `extensions/qa-lab/src/providers/`.
Cada provider é dono dos próprios padrões, inicialização do servidor local, configuração
de modelo do gateway, necessidades de preparação de perfil de autenticação e flags de capacidade
ao vivo/mock. O código compartilhado da suíte e do gateway deve rotear pelo registro de providers em vez de
ramificar com base em nomes de providers.
## Adaptadores de transporte
`qa-lab` é dono de uma superfície genérica de transporte para cenários de QA em Markdown.
`qa-channel` é o primeiro adaptador nessa superfície, mas o objetivo do design é mais amplo:
futuros canais reais ou sintéticos devem se conectar ao mesmo executor de suíte
em vez de adicionar um executor de QA específico por transporte.
canais futuros, reais ou sintéticos, devem se conectar ao mesmo executor de suíte em vez de
adicionar um executor de QA específico para cada transporte.
No nível da arquitetura, a divisão é:
No nível de arquitetura, a divisão é:
- `qa-lab` é dono da execução genérica de cenários, concorrência de workers, gravação de artefatos e relatórios.
- o adaptador de transporte é dono da configuração do gateway, prontidão, observação de entrada e saída, ações de transporte e estado de transporte normalizado.
- os arquivos Markdown de cenário em `qa/scenarios/` definem a execução de teste; `qa-lab` fornece a superfície de runtime reutilizável que os executa.
- arquivos de cenário em Markdown em `qa/scenarios/` definem a execução de teste; `qa-lab` fornece a superfície de runtime reutilizável que os executa.
A orientação de adoção voltada para mantenedores para novos adaptadores de canal fica em
A orientação de adoção voltada para maintainers para novos adaptadores de canal está em
[Testing](/pt-BR/help/testing#adding-a-channel-to-qa).
## Relatórios
`qa-lab` exporta um relatório de protocolo em Markdown a partir da linha do tempo observada no barramento.
`qa-lab` exporta um relatório de protocolo em Markdown a partir da linha do tempo do barramento observado.
O relatório deve responder:
- O que funcionou
@ -183,7 +199,7 @@ O relatório deve responder:
- O que permaneceu bloqueado
- Quais cenários de acompanhamento valem a pena adicionar
Para verificações de caráter e estilo, execute o mesmo cenário em várias refs de modelo ativas
Para verificações de caráter e estilo, execute o mesmo cenário em várias refs de modelos ao vivo
e grave um relatório em Markdown avaliado:
```bash
@ -203,30 +219,30 @@ pnpm openclaw qa character-eval \
--judge-concurrency 16
```
O comando executa processos filhos locais de gateway de QA, não Docker. Os cenários de avaliação
de caráter devem definir a persona por meio de `SOUL.md` e então executar turnos normais de usuário,
como chat, ajuda com workspace e pequenas tarefas com arquivos. O modelo candidato
O comando executa processos filhos locais do gateway de QA, não Docker. Cenários de avaliação de caráter
devem definir a persona por meio de `SOUL.md` e então executar turnos normais de usuário
como chat, ajuda sobre o workspace e pequenas tarefas em arquivos. O modelo candidato
não deve ser informado de que está sendo avaliado. O comando preserva cada transcrição
completa, registra estatísticas básicas da execução e então pede aos modelos juízes no modo fast com
raciocínio `xhigh` para classificar as execuções por naturalidade, vibe e humor.
Use `--blind-judge-models` ao comparar provedores: o prompt do juiz ainda recebe
cada transcrição e status da execução, mas as refs candidatas são substituídas por rótulos
neutros como `candidate-01`; o relatório mapeia as classificações de volta para as refs reais após
completa, registra estatísticas básicas da execução e então pede que os modelos juízes, em modo fast com
raciocínio `xhigh`, classifiquem as execuções por naturalidade, vibe e humor.
Use `--blind-judge-models` ao comparar providers: o prompt do juiz ainda recebe
cada transcrição e status da execução, mas as refs candidatas são substituídas por rótulos neutros
como `candidate-01`; o relatório mapeia as classificações de volta para as refs reais após
o parsing.
As execuções candidatas usam `high` por padrão, com `xhigh` para modelos OpenAI que
oferecem suporte a isso. Substitua um candidato específico inline com
`--model provider/model,thinking=<level>`. `--thinking <level>` ainda define um
fallback global, e a forma antiga `--model-thinking <provider/model=level>` é
mantida por compatibilidade.
As execuções dos candidatos usam por padrão `high` thinking, com `xhigh` para modelos OpenAI que
oferecem suporte. Substitua um candidato específico inline com
`--model provider/model,thinking=<level>`. `--thinking <level>` ainda define um fallback
global, e o formato mais antigo `--model-thinking <provider/model=level>` é
mantido por compatibilidade.
As refs candidatas da OpenAI usam o modo fast por padrão para que o processamento prioritário seja usado
quando o provedor oferecer suporte. Adicione `,fast`, `,no-fast` ou `,fast=false` inline quando um
único candidato ou juiz precisar de uma substituição. Passe `--fast` apenas quando quiser
quando o provider oferecer suporte. Adicione `,fast`, `,no-fast` ou `,fast=false` inline quando
um único candidato ou juiz precisar de uma substituição. Passe `--fast` apenas quando quiser
forçar o modo fast para todos os modelos candidatos. As durações de candidatos e juízes são
registradas no relatório para análise de benchmark, mas os prompts dos juízes dizem explicitamente
para não classificar por velocidade.
As execuções de modelos candidatos e juízes usam concorrência 16 por padrão. Reduza
`--concurrency` ou `--judge-concurrency` quando limites do provedor ou pressão no gateway local
deixarem a execução ruidosa demais.
para não classificar com base em velocidade.
As execuções dos modelos candidatos e dos juízes usam concorrência 16 por padrão. Reduza
`--concurrency` ou `--judge-concurrency` quando limites do provider ou pressão no gateway local
tornarem uma execução muito ruidosa.
Quando nenhum `--model` candidato é passado, a avaliação de caráter usa por padrão
`openai/gpt-5.4`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`,
`anthropic/claude-sonnet-4-6`, `zai/glm-5.1`,
@ -236,7 +252,7 @@ Quando nenhum `--judge-model` é passado, os juízes usam por padrão
`openai/gpt-5.4,thinking=xhigh,fast` e
`anthropic/claude-opus-4-6,thinking=high`.
## Documentos relacionados
## Docs relacionadas
- [Testing](/pt-BR/help/testing)
- [QA Channel](/pt-BR/channels/qa-channel)

701
docs/pt-BR/help/testing.md
View File

File diff suppressed because it is too large Load Diff

366
docs/pt-BR/plugins/sdk-migration.md
View File

@ -2,44 +2,36 @@
read_when:
- Você vê o aviso OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED
- Você vê o aviso OPENCLAW_EXTENSION_API_DEPRECATED
- Você está atualizando um plugin para a arquitetura moderna de plugins
- Você mantém um plugin externo do OpenClaw
- Você está atualizando um Plugin para a arquitetura moderna de plugins
- Você mantém um Plugin externo do OpenClaw
sidebarTitle: Migrate to SDK
summary: Migre da camada legada de compatibilidade retroativa para o SDK de plugin moderno
title: Migração do SDK de Plugin
summary: Migrar da camada legada de compatibilidade retroativa para o Plugin SDK moderno
title: Migração do Plugin SDK
x-i18n:
generated_at: "2026-04-09T01:30:36Z"
generated_at: "2026-04-17T05:36:07Z"
model: gpt-5.4
provider: openai
source_hash: 60cbb6c8be30d17770887d490c14e3a4538563339a5206fb419e51e0558bbc07
source_hash: f0283f949eec358a12a0709db846cde2a1509f28e5c60db6e563cb8a540b979d
source_path: plugins/sdk-migration.md
workflow: 15
---
# Migração do SDK de Plugin
# Migração do Plugin SDK
O OpenClaw migrou de uma ampla camada de compatibilidade retroativa para uma
arquitetura moderna de plugins com imports focados e documentados. Se o seu
plugin foi criado antes da nova arquitetura, este guia ajuda na migração.
O OpenClaw migrou de uma camada ampla de compatibilidade retroativa para uma arquitetura moderna de plugins com imports focados e documentados. Se o seu Plugin foi criado antes da nova arquitetura, este guia ajuda você a migrar.
## O que está mudando
O sistema antigo de plugins fornecia duas superfícies amplas e abertas que permitiam que plugins importassem
qualquer coisa de que precisassem a partir de um único ponto de entrada:
O sistema antigo de plugins fornecia duas superfícies amplas que permitiam que os plugins importassem qualquer coisa de que precisassem a partir de um único ponto de entrada:
- **`openclaw/plugin-sdk/compat`** — um único import que reexportava dezenas de
helpers. Ele foi introduzido para manter plugins mais antigos baseados em hooks funcionando enquanto a
nova arquitetura de plugins estava sendo construída.
- **`openclaw/extension-api`** — uma bridge que dava aos plugins acesso direto a
helpers do lado do host, como o executor de agente embutido.
- **`openclaw/plugin-sdk/compat`** — um único import que reexportava dezenas de helpers. Ele foi introduzido para manter plugins antigos baseados em hooks funcionando enquanto a nova arquitetura de plugins era desenvolvida.
- **`openclaw/extension-api`** — uma ponte que dava aos plugins acesso direto a helpers do lado do host, como o executor de agentes embutido.
Ambas as superfícies agora estão **obsoletas**. Elas ainda funcionam em runtime, mas
novos plugins não devem usá-las, e plugins existentes devem migrar antes que a próxima
versão major as remova.
Ambas as superfícies agora estão **obsoletas**. Elas ainda funcionam em tempo de execução, mas novos plugins não devem usá-las, e os plugins existentes devem migrar antes que a próxima versão principal as remova.
<Warning>
A camada de compatibilidade retroativa será removida em uma futura versão major.
Plugins que ainda importarem dessas superfícies vão quebrar quando isso acontecer.
A camada de compatibilidade retroativa será removida em uma futura versão principal.
Plugins que ainda importarem dessas superfícies deixarão de funcionar quando isso acontecer.
</Warning>
## Por que isso mudou
@ -48,27 +40,27 @@ A abordagem antiga causava problemas:
- **Inicialização lenta** — importar um helper carregava dezenas de módulos não relacionados
- **Dependências circulares** — reexportações amplas facilitavam a criação de ciclos de import
- **Superfície de API pouco clara** — não havia como dizer quais exports eram estáveis e quais eram internos
- **Superfície de API pouco clara** — não havia como saber quais exports eram estáveis e quais eram internos
O SDK de plugin moderno corrige isso: cada caminho de import (`openclaw/plugin-sdk/\<subpath\>`)
é um módulo pequeno, autocontido, com um propósito claro e contrato documentado.
O Plugin SDK moderno corrige isso: cada caminho de import (`openclaw/plugin-sdk/\<subpath\>`)
é um módulo pequeno e autocontido com um propósito claro e um contrato documentado.
As seams legadas de conveniência de provedor para canais incluídos também acabaram. Imports
As conveniências legadas para providers de canais empacotados também desapareceram. Imports
como `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`,
`openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`,
seams helper com marca de canal e
superfícies auxiliares com marca de canal e
`openclaw/plugin-sdk/telegram-core` eram atalhos privados do mono-repo, não
contratos estáveis de plugin. Use subcaminhos genéricos e estreitos do SDK. Dentro do
workspace de plugins incluídos, mantenha helpers pertencentes ao provedor no próprio
`api.ts` ou `runtime-api.ts` desse plugin.
contratos estáveis de plugin. Use subcaminhos genéricos e restritos do SDK em vez disso. Dentro do
workspace de plugins empacotados, mantenha helpers pertencentes ao provider no próprio
`api.ts` ou `runtime-api.ts` daquele Plugin.
Exemplos atuais de provedores incluídos:
Exemplos atuais de providers empacotados:
- Anthropic mantém helpers de stream específicos do Claude em sua própria seam `api.ts` /
- O Anthropic mantém helpers de streaming específicos do Claude em sua própria superfície `api.ts` /
`contract-api.ts`
- OpenAI mantém builders de provedor, helpers de modelo padrão e builders de provedor
realtime em seu próprio `api.ts`
- OpenRouter mantém o builder de provedor e helpers de onboarding/config em seu próprio
- O OpenAI mantém builders de provider, helpers de modelo padrão e builders de provider
em tempo real em seu próprio `api.ts`
- O OpenRouter mantém helpers de builder de provider e de onboarding/configuração em seu próprio
`api.ts`
## Como migrar
@ -76,55 +68,55 @@ Exemplos atuais de provedores incluídos:
<Steps>
<Step title="Migrar handlers nativos de aprovação para fatos de capacidade">
Plugins de canal com suporte a aprovação agora expõem comportamento nativo de aprovação por meio de
`approvalCapability.nativeRuntime` mais o registro compartilhado de contexto de runtime.
`approvalCapability.nativeRuntime` junto com o registro compartilhado de contexto de runtime.
Principais mudanças:
- Substitua `approvalCapability.handler.loadRuntime(...)` por
`approvalCapability.nativeRuntime`
- Mova autenticação/entrega específicas de aprovação para fora do wiring legado `plugin.auth` /
`plugin.approvals` e para `approvalCapability`
- `ChannelPlugin.approvals` foi removido do contrato público
de plugin de canal; mova os campos de entrega/nativo/render para `approvalCapability`
- `plugin.auth` permanece apenas para fluxos de login/logout de canal; hooks de autenticação
- Mova autenticação/entrega específicas de aprovação da antiga estrutura `plugin.auth` /
`plugin.approvals` para `approvalCapability`
- `ChannelPlugin.approvals` foi removido do contrato público de
plugin de canal; mova os campos delivery/native/render para `approvalCapability`
- `plugin.auth` permanece apenas para fluxos de login/logout do canal; hooks de autenticação
de aprovação ali não são mais lidos pelo core
- Registre objetos de runtime pertencentes ao canal, como clientes, tokens ou apps
- Registre objetos de runtime pertencentes ao canal, como clients, tokens ou apps
Bolt, por meio de `openclaw/plugin-sdk/channel-runtime-context`
- Não envie avisos de redirecionamento pertencentes ao plugin a partir de handlers nativos de aprovação;
o core agora é responsável por avisos de encaminhamento para outro lugar a partir de resultados reais de entrega
- Não envie avisos de redirecionamento pertencentes ao Plugin a partir de handlers nativos de aprovação;
o core agora é responsável pelos avisos de “encaminhado para outro lugar” com base nos resultados reais de entrega
- Ao passar `channelRuntime` para `createChannelManager(...)`, forneça uma
superfície real de `createPluginRuntime().channel`. Stubs parciais são rejeitados.
Consulte `/plugins/sdk-channel-plugins` para o layout atual da
Consulte `/plugins/sdk-channel-plugins` para ver o layout atual da
capacidade de aprovação.
</Step>
<Step title="Auditar o comportamento de fallback do wrapper do Windows">
Se o seu plugin usa `openclaw/plugin-sdk/windows-spawn`, wrappers `.cmd`/`.bat` não resolvidos no Windows
agora falham de forma fechada, a menos que você passe explicitamente
`allowShellFallback: true`.
Se o seu Plugin usa `openclaw/plugin-sdk/windows-spawn`, wrappers `.cmd`/`.bat`
não resolvidos no Windows agora falham de forma fechada, a menos que você passe
explicitamente `allowShellFallback: true`.
```typescript
// Antes
// Before
const program = applyWindowsSpawnProgramPolicy({ candidate });
// Depois
// After
const program = applyWindowsSpawnProgramPolicy({
candidate,
// Defina isso apenas para chamadores de compatibilidade confiáveis que
// aceitam intencionalmente fallback mediado por shell.
// Only set this for trusted compatibility callers that intentionally
// accept shell-mediated fallback.
allowShellFallback: true,
});
```
Se o seu chamador não depender intencionalmente de fallback por shell, não defina
Se o seu chamador não depende intencionalmente de fallback por shell, não defina
`allowShellFallback` e trate o erro lançado.
</Step>
<Step title="Encontrar imports obsoletos">
Pesquise no seu plugin imports vindos de qualquer uma das superfícies obsoletas:
Procure no seu Plugin imports de qualquer uma das superfícies obsoletas:
```bash
grep -r "plugin-sdk/compat" my-plugin/
@ -137,14 +129,14 @@ Exemplos atuais de provedores incluídos:
Cada export da superfície antiga corresponde a um caminho de import moderno específico:
```typescript
// Antes (camada obsoleta de compatibilidade retroativa)
// Before (deprecated backwards-compatibility layer)
import {
createChannelReplyPipeline,
createPluginRuntimeStore,
resolveControlCommandGate,
} from "openclaw/plugin-sdk/compat";
// Depois (imports modernos e focados)
// After (modern focused imports)
import { createChannelReplyPipeline } from "openclaw/plugin-sdk/channel-reply-pipeline";
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth";
@ -154,15 +146,15 @@ Exemplos atuais de provedores incluídos:
diretamente:
```typescript
// Antes (bridge obsoleta extension-api)
// Before (deprecated extension-api bridge)
import { runEmbeddedPiAgent } from "openclaw/extension-api";
const result = await runEmbeddedPiAgent({ sessionId, prompt });
// Depois (runtime injetado)
// After (injected runtime)
const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt });
```
O mesmo padrão se aplica a outros helpers legados da bridge:
O mesmo padrão se aplica a outros helpers legados da ponte:
| Import antigo | Equivalente moderno |
| --- | --- |
@ -184,148 +176,148 @@ Exemplos atuais de provedores incluídos:
</Step>
</Steps>
## Referência de caminhos de import
## Referência de caminhos de importação
<Accordion title="Tabela de caminhos de import comuns">
| Caminho de import | Finalidade | Principais exports |
<Accordion title="Tabela comum de caminhos de importação">
| Caminho de importação | Finalidade | Principais exports |
| --- | --- | --- |
| `plugin-sdk/plugin-entry` | Helper canônico de entrada de plugin | `definePluginEntry` |
| `plugin-sdk/core` | Reexportação guarda-chuva legada para definições/builders de entrada de canal | `defineChannelPluginEntry`, `createChatChannelPlugin` |
| `plugin-sdk/config-schema` | Export do esquema raiz de configuração | `OpenClawSchema` |
| `plugin-sdk/provider-entry` | Helper de entrada de provedor único | `defineSingleProviderPluginEntry` |
| `plugin-sdk/plugin-entry` | Helper canônico de entrada de Plugin | `definePluginEntry` |
| `plugin-sdk/core` | Reexportação abrangente legada para definições/builders de entrada de canal | `defineChannelPluginEntry`, `createChatChannelPlugin` |
| `plugin-sdk/config-schema` | Export da schema de configuração raiz | `OpenClawSchema` |
| `plugin-sdk/provider-entry` | Helper de entrada para provider único | `defineSingleProviderPluginEntry` |
| `plugin-sdk/channel-core` | Definições e builders focados de entrada de canal | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
| `plugin-sdk/setup` | Helpers compartilhados do assistente de configuração | Prompts de allowlist, builders de status de configuração |
| `plugin-sdk/setup-runtime` | Helpers de runtime em tempo de configuração | Adaptadores de patch de configuração seguros para import, helpers de nota de lookup, `promptResolvedAllowFrom`, `splitSetupEntries`, proxies de configuração delegada |
| `plugin-sdk/setup-runtime` | Helpers de runtime no momento da configuração | Adaptadores de patch de configuração seguros para importação, helpers de nota de lookup, `promptResolvedAllowFrom`, `splitSetupEntries`, proxies de configuração delegada |
| `plugin-sdk/setup-adapter-runtime` | Helpers de adaptador de configuração | `createEnvPatchedAccountSetupAdapter` |
| `plugin-sdk/setup-tools` | Helpers de tooling de configuração | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
| `plugin-sdk/account-core` | Helpers de múltiplas contas | Helpers de lista/configuração de conta/porta de ação |
| `plugin-sdk/setup-tools` | Helpers de ferramentas de configuração | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
| `plugin-sdk/account-core` | Helpers de múltiplas contas | Helpers de lista/configuração de contas/portão de ação |
| `plugin-sdk/account-id` | Helpers de ID de conta | `DEFAULT_ACCOUNT_ID`, normalização de ID de conta |
| `plugin-sdk/account-resolution` | Helpers de lookup de conta | Helpers de lookup de conta + fallback padrão |
| `plugin-sdk/account-helpers` | Helpers estreitos de conta | Helpers de lista de conta/ação de conta |
| `plugin-sdk/channel-setup` | Adaptadores do assistente de configuração | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, mais `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
| `plugin-sdk/channel-pairing` | Primitivas de pareamento de DM | `createChannelPairingController` |
| `plugin-sdk/channel-reply-pipeline` | Wiring de prefixo de resposta + digitação | `createChannelReplyPipeline` |
| `plugin-sdk/account-helpers` | Helpers restritos de conta | Helpers de lista de contas/ação de conta |
| `plugin-sdk/channel-setup` | Adaptadores do assistente de configuração | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, além de `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
| `plugin-sdk/channel-pairing` | Primitivas de pareamento por DM | `createChannelPairingController` |
| `plugin-sdk/channel-reply-pipeline` | Prefixo de resposta + encadeamento de digitação | `createChannelReplyPipeline` |
| `plugin-sdk/channel-config-helpers` | Fábricas de adaptadores de configuração | `createHybridChannelConfigAdapter` |
| `plugin-sdk/channel-config-schema` | Builders de esquema de configuração | Tipos de esquema de configuração de canal |
| `plugin-sdk/telegram-command-config` | Helpers de configuração de comando do Telegram | Normalização de nome de comando, trimming de descrição, validação de duplicidade/conflito |
| `plugin-sdk/channel-config-schema` | Builders de schema de configuração | Tipos de schema de configuração de canal |
| `plugin-sdk/telegram-command-config` | Helpers de configuração de comandos do Telegram | Normalização de nome de comando, truncamento de descrição, validação de duplicidade/conflito |
| `plugin-sdk/channel-policy` | Resolução de política de grupo/DM | `resolveChannelGroupRequireMention` |
| `plugin-sdk/channel-lifecycle` | Rastreamento de status de conta | `createAccountStatusSink` |
| `plugin-sdk/inbound-envelope` | Helpers de envelope de entrada | Helpers compartilhados de rota + builder de envelope |
| `plugin-sdk/inbound-reply-dispatch` | Helpers de resposta de entrada | Helpers compartilhados de registrar e despachar |
| `plugin-sdk/inbound-reply-dispatch` | Helpers de resposta de entrada | Helpers compartilhados de registro e despacho |
| `plugin-sdk/messaging-targets` | Parsing de destinos de mensagens | Helpers de parsing/correspondência de destino |
| `plugin-sdk/outbound-media` | Helpers de mídia de saída | Carregamento compartilhado de mídia de saída |
| `plugin-sdk/outbound-runtime` | Helpers de runtime de saída | Helpers de identidade de saída/delegado de envio |
| `plugin-sdk/thread-bindings-runtime` | Helpers de vínculo de thread | Ciclo de vida de vínculo de thread e helpers de adaptador |
| `plugin-sdk/agent-media-payload` | Helpers legados de payload de mídia | Builder de payload de mídia de agente para layouts legados de campo |
| `plugin-sdk/channel-runtime` | Shim obsoleto de compatibilidade | Apenas utilitários legados de runtime de canal |
| `plugin-sdk/outbound-runtime` | Helpers de runtime de saída | Helpers de identidade de saída/delegação de envio |
| `plugin-sdk/thread-bindings-runtime` | Helpers de vínculo de thread | Helpers de ciclo de vida e adaptador de vínculo de thread |
| `plugin-sdk/agent-media-payload` | Helpers legados de payload de mídia | Builder de payload de mídia de agente para layouts legados de campos |
| `plugin-sdk/channel-runtime` | Shim de compatibilidade obsoleto | Apenas utilitários legados de runtime de canal |
| `plugin-sdk/channel-send-result` | Tipos de resultado de envio | Tipos de resultado de resposta |
| `plugin-sdk/runtime-store` | Armazenamento persistente de plugin | `createPluginRuntimeStore` |
| `plugin-sdk/runtime-store` | Armazenamento persistente do Plugin | `createPluginRuntimeStore` |
| `plugin-sdk/runtime` | Helpers amplos de runtime | Helpers de runtime/logging/backup/instalação de plugin |
| `plugin-sdk/runtime-env` | Helpers estreitos de env de runtime | Logger/env de runtime, helpers de timeout, retry e backoff |
| `plugin-sdk/plugin-runtime` | Helpers compartilhados de runtime de plugin | Helpers de comandos/hooks/http/interativo de plugin |
| `plugin-sdk/hook-runtime` | Helpers de pipeline de hook | Helpers compartilhados de pipeline de webhook/hook interno |
| `plugin-sdk/runtime-env` | Helpers restritos de ambiente de runtime | Logger/ambiente de runtime, timeout, retry e helpers de backoff |
| `plugin-sdk/plugin-runtime` | Helpers compartilhados de runtime de plugin | Helpers de comandos/hooks/http/interativos de plugin |
| `plugin-sdk/hook-runtime` | Helpers de pipeline de hook | Helpers compartilhados de pipeline de hook interno/Webhook |
| `plugin-sdk/lazy-runtime` | Helpers de runtime lazy | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` |
| `plugin-sdk/process-runtime` | Helpers de processo | Helpers compartilhados de execução |
| `plugin-sdk/process-runtime` | Helpers de processo | Helpers compartilhados de exec |
| `plugin-sdk/cli-runtime` | Helpers de runtime de CLI | Formatação de comando, esperas, helpers de versão |
| `plugin-sdk/gateway-runtime` | Helpers de gateway | Cliente de gateway e helpers de patch de status de canal |
| `plugin-sdk/config-runtime` | Helpers de configuração | Helpers de carregar/gravar configuração |
| `plugin-sdk/telegram-command-config` | Helpers de comando do Telegram | Helpers de validação de comandos do Telegram estáveis para fallback quando a superfície de contrato do Telegram incluído não está disponível |
| `plugin-sdk/approval-runtime` | Helpers de prompt de aprovação | Payload de aprovação exec/plugin, helpers de perfil/capacidade de aprovação, helpers nativos de routing/runtime de aprovação |
| `plugin-sdk/gateway-runtime` | Helpers de Gateway | Cliente de Gateway e helpers de patch de status de canal |
| `plugin-sdk/config-runtime` | Helpers de configuração | Helpers de carregamento/gravação de configuração |
| `plugin-sdk/telegram-command-config` | Helpers de comando do Telegram | Helpers de validação de comando do Telegram estáveis em fallback quando a superfície contratual empacotada do Telegram não está disponível |
| `plugin-sdk/approval-runtime` | Helpers de prompt de aprovação | Payload de aprovação de exec/plugin, helpers de capacidade/perfil de aprovação, helpers nativos de roteamento/runtime de aprovação |
| `plugin-sdk/approval-auth-runtime` | Helpers de autenticação de aprovação | Resolução de aprovador, autenticação de ação no mesmo chat |
| `plugin-sdk/approval-client-runtime` | Helpers de cliente de aprovação | Helpers de perfil/filtro de aprovação nativa exec |
| `plugin-sdk/approval-delivery-runtime` | Helpers de entrega de aprovação | Adaptadores de capacidade/entrega de aprovação nativa |
| `plugin-sdk/approval-gateway-runtime` | Helpers de gateway de aprovação | Helper compartilhado de resolução de gateway de aprovação |
| `plugin-sdk/approval-handler-adapter-runtime` | Helpers de adaptador de aprovação | Helpers leves de carregamento de adaptador nativo de aprovação para entrypoints quentes de canal |
| `plugin-sdk/approval-handler-runtime` | Helpers de handler de aprovação | Helpers mais amplos de runtime de handler de aprovação; prefira as seams mais estreitas de adaptador/gateway quando forem suficientes |
| `plugin-sdk/approval-native-runtime` | Helpers de alvo de aprovação | Helpers nativos de vínculo de alvo/conta de aprovação |
| `plugin-sdk/approval-reply-runtime` | Helpers de resposta de aprovação | Helpers de payload de resposta de aprovação exec/plugin |
| `plugin-sdk/approval-client-runtime` | Helpers de cliente de aprovação | Helpers nativos de perfil/filtro de aprovação de exec |
| `plugin-sdk/approval-delivery-runtime` | Helpers de entrega de aprovação | Adaptadores nativos de capacidade/entrega de aprovação |
| `plugin-sdk/approval-gateway-runtime` | Helpers de Gateway de aprovação | Helper compartilhado de resolução de Gateway de aprovação |
| `plugin-sdk/approval-handler-adapter-runtime` | Helpers de adaptador de aprovação | Helpers leves de carregamento de adaptador nativo de aprovação para pontos de entrada quentes de canal |
| `plugin-sdk/approval-handler-runtime` | Helpers de handler de aprovação | Helpers mais amplos de runtime de handler de aprovação; prefira as superfícies mais restritas de adaptador/Gateway quando elas forem suficientes |
| `plugin-sdk/approval-native-runtime` | Helpers de destino de aprovação | Helpers nativos de vínculo de destino/conta de aprovação |
| `plugin-sdk/approval-reply-runtime` | Helpers de resposta de aprovação | Helpers de payload de resposta de aprovação de exec/plugin |
| `plugin-sdk/channel-runtime-context` | Helpers de contexto de runtime de canal | Helpers genéricos de registrar/obter/observar contexto de runtime de canal |
| `plugin-sdk/security-runtime` | Helpers de segurança | Helpers compartilhados de confiança, controle de DM, conteúdo externo e coleta de segredo |
| `plugin-sdk/ssrf-policy` | Helpers de política SSRF | Helpers de allowlist de host e política de rede privada |
| `plugin-sdk/ssrf-runtime` | Helpers de runtime SSRF | Helpers de dispatcher fixado, fetch protegido, política SSRF |
| `plugin-sdk/security-runtime` | Helpers de segurança | Helpers compartilhados de confiança, bloqueio de DM, conteúdo externo e coleta de segredos |
| `plugin-sdk/ssrf-policy` | Helpers de política de SSRF | Helpers de allowlist de host e política de rede privada |
| `plugin-sdk/ssrf-runtime` | Helpers de runtime de SSRF | Helpers de pinned-dispatcher, fetch protegido e política de SSRF |
| `plugin-sdk/collection-runtime` | Helpers de cache limitado | `pruneMapToMaxSize` |
| `plugin-sdk/diagnostic-runtime` | Helpers de porta de diagnóstico | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` |
| `plugin-sdk/diagnostic-runtime` | Helpers de bloqueio de diagnóstico | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` |
| `plugin-sdk/error-runtime` | Helpers de formatação de erro | `formatUncaughtError`, `isApprovalNotFoundError`, helpers de grafo de erro |
| `plugin-sdk/fetch-runtime` | Helpers de fetch/proxy encapsulados | `resolveFetch`, helpers de proxy |
| `plugin-sdk/host-runtime` | Helpers de normalização de host | `normalizeHostname`, `normalizeScpRemoteHost` |
| `plugin-sdk/retry-runtime` | Helpers de retry | `RetryConfig`, `retryAsync`, executores de política |
| `plugin-sdk/allow-from` | Formatação de allowlist | `formatAllowFromLowercase` |
| `plugin-sdk/allowlist-resolution` | Mapeamento de entrada de allowlist | `mapAllowlistResolutionInputs` |
| `plugin-sdk/command-auth` | Porta de comando e helpers de superfície de comando | `resolveControlCommandGate`, helpers de autorização do remetente, helpers de registro de comandos |
| `plugin-sdk/command-auth` | Bloqueio de comando e helpers de superfície de comando | `resolveControlCommandGate`, helpers de autorização do remetente, helpers de registro de comandos |
| `plugin-sdk/command-status` | Renderizadores de status/ajuda de comando | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` |
| `plugin-sdk/secret-input` | Parsing de entrada secreta | Helpers de entrada secreta |
| `plugin-sdk/webhook-ingress` | Helpers de requisição de webhook | Utilitários de destino de webhook |
| `plugin-sdk/webhook-request-guards` | Helpers de proteção de corpo de webhook | Helpers de leitura/limite de corpo de requisição |
| `plugin-sdk/reply-runtime` | Runtime compartilhado de resposta | Despacho de entrada, heartbeat, planejador de resposta, fragmentação |
| `plugin-sdk/reply-dispatch-runtime` | Helpers estreitos de despacho de resposta | Finalizar + helpers de despacho de provedor |
| `plugin-sdk/secret-input` | Parsing de entrada de segredo | Helpers de entrada de segredo |
| `plugin-sdk/webhook-ingress` | Helpers de requisição de Webhook | Utilitários de destino de Webhook |
| `plugin-sdk/webhook-request-guards` | Helpers de proteção do corpo de requisição de Webhook | Helpers de leitura/limite do corpo da requisição |
| `plugin-sdk/reply-runtime` | Runtime compartilhado de resposta | Despacho de entrada, Heartbeat, planejador de resposta, fragmentação |
| `plugin-sdk/reply-dispatch-runtime` | Helpers restritos de despacho de resposta | Helpers de finalização + despacho de provider |
| `plugin-sdk/reply-history` | Helpers de histórico de resposta | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` |
| `plugin-sdk/reply-reference` | Planejamento de referência de resposta | `createReplyReferencePlanner` |
| `plugin-sdk/reply-chunking` | Helpers de chunk de resposta | Helpers de fragmentação de texto/markdown |
| `plugin-sdk/session-store-runtime` | Helpers de armazenamento de sessão | Helpers de caminho de armazenamento + updated-at |
| `plugin-sdk/reply-chunking` | Helpers de fragmentação de resposta | Helpers de fragmentação de texto/markdown |
| `plugin-sdk/session-store-runtime` | Helpers de armazenamento de sessão | Helpers de caminho do armazenamento + updated-at |
| `plugin-sdk/state-paths` | Helpers de caminhos de estado | Helpers de diretório de estado e OAuth |
| `plugin-sdk/routing` | Helpers de routing/chave de sessão | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, helpers de normalização de chave de sessão |
| `plugin-sdk/status-helpers` | Helpers de status de canal | Builders de resumo de status de canal/conta, padrões de estado de runtime, helpers de metadados de issue |
| `plugin-sdk/routing` | Helpers de roteamento/chave de sessão | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, helpers de normalização de chave de sessão |
| `plugin-sdk/status-helpers` | Helpers de status de canal | Builders de resumo de status de canal/conta, padrões de estado de runtime, helpers de metadados de problema |
| `plugin-sdk/target-resolver-runtime` | Helpers de resolvedor de destino | Helpers compartilhados de resolvedor de destino |
| `plugin-sdk/string-normalization-runtime` | Helpers de normalização de string | Helpers de normalização de slug/string |
| `plugin-sdk/request-url` | Helpers de URL de requisição | Extrair URLs string de entradas semelhantes a request |
| `plugin-sdk/run-command` | Helpers de comando cronometrado | Executor de comando cronometrado com stdout/stderr normalizados |
| `plugin-sdk/param-readers` | Leitores de parâmetro | Leitores comuns de parâmetros de ferramenta/CLI |
| `plugin-sdk/tool-payload` | Extração de payload de ferramenta | Extrair payloads normalizados de objetos de resultado de ferramenta |
| `plugin-sdk/tool-send` | Extração de envio de ferramenta | Extrair campos canônicos de destino de envio dos args da ferramenta |
| `plugin-sdk/request-url` | Helpers de URL de requisição | Extrai URLs em string de entradas semelhantes a requisição |
| `plugin-sdk/run-command` | Helpers de comando com tempo controlado | Executor de comando com stdout/stderr normalizados |
| `plugin-sdk/param-readers` | Leitores de parâmetros | Leitores comuns de parâmetros de ferramenta/CLI |
| `plugin-sdk/tool-payload` | Extração de payload de ferramenta | Extrai payloads normalizados de objetos de resultado de ferramenta |
| `plugin-sdk/tool-send` | Extração de envio de ferramenta | Extrai campos canônicos de destino de envio de argumentos de ferramenta |
| `plugin-sdk/temp-path` | Helpers de caminho temporário | Helpers compartilhados de caminho temporário para download |
| `plugin-sdk/logging-core` | Helpers de logging | Logger de subsistema e helpers de redação |
| `plugin-sdk/markdown-table-runtime` | Helpers de tabela markdown | Helpers de modo de tabela markdown |
| `plugin-sdk/markdown-table-runtime` | Helpers de tabela Markdown | Helpers de modo de tabela Markdown |
| `plugin-sdk/reply-payload` | Tipos de resposta de mensagem | Tipos de payload de resposta |
| `plugin-sdk/provider-setup` | Helpers curados de configuração de provedor local/self-hosted | Helpers de descoberta/configuração de provedor self-hosted |
| `plugin-sdk/self-hosted-provider-setup` | Helpers focados de configuração de provedor self-hosted compatível com OpenAI | Os mesmos helpers de descoberta/configuração de provedor self-hosted |
| `plugin-sdk/provider-auth-runtime` | Helpers de autenticação de runtime de provedor | Helpers de resolução de chave de API em runtime |
| `plugin-sdk/provider-auth-api-key` | Helpers de configuração de chave de API do provedor | Helpers de onboarding/gravação de perfil de chave de API |
| `plugin-sdk/provider-auth-result` | Helpers de resultado de autenticação de provedor | Builder padrão de resultado de autenticação OAuth |
| `plugin-sdk/provider-auth-login` | Helpers de login interativo de provedor | Helpers compartilhados de login interativo |
| `plugin-sdk/provider-env-vars` | Helpers de variáveis de env de provedor | Helpers de lookup de variáveis de env de autenticação do provedor |
| `plugin-sdk/provider-model-shared` | Helpers compartilhados de modelo/replay de provedor | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, builders compartilhados de política de replay, helpers de endpoint de provedor e helpers de normalização de ID de modelo |
| `plugin-sdk/provider-catalog-shared` | Helpers compartilhados de catálogo de provedor | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
| `plugin-sdk/provider-onboard` | Patches de onboarding de provedor | Helpers de configuração de onboarding |
| `plugin-sdk/provider-http` | Helpers HTTP de provedor | Helpers genéricos de HTTP/capacidade de endpoint de provedor |
| `plugin-sdk/provider-web-fetch` | Helpers de web-fetch de provedor | Helpers de registro/cache de provedor web-fetch |
| `plugin-sdk/provider-web-search-config-contract` | Helpers de configuração de web search de provedor | Helpers estreitos de configuração/credencial de web search para provedores que não precisam de wiring de habilitação de plugin |
| `plugin-sdk/provider-web-search-contract` | Helpers de contrato de web search de provedor | Helpers estreitos de contrato de configuração/credencial de web search, como `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` e setters/getters de credenciais com escopo |
| `plugin-sdk/provider-web-search` | Helpers de web search de provedor | Helpers de registro/cache/runtime de provedor web-search |
| `plugin-sdk/provider-tools` | Helpers de compat de ferramenta/esquema de provedor | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, limpeza + diagnósticos de esquema Gemini e helpers de compat xAI como `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
| `plugin-sdk/provider-usage` | Helpers de uso de provedor | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` e outros helpers de uso de provedor |
| `plugin-sdk/provider-stream` | Helpers de wrapper de stream de provedor | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, tipos de wrapper de stream e helpers compartilhados de wrapper Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
| `plugin-sdk/provider-setup` | Helpers curados de configuração de provider local/self-hosted | Helpers de descoberta/configuração de provider self-hosted |
| `plugin-sdk/self-hosted-provider-setup` | Helpers focados de configuração de provider self-hosted compatível com OpenAI | Os mesmos helpers de descoberta/configuração de provider self-hosted |
| `plugin-sdk/provider-auth-runtime` | Helpers de autenticação de runtime de provider | Helpers de resolução de chave de API em runtime |
| `plugin-sdk/provider-auth-api-key` | Helpers de configuração de chave de API de provider | Helpers de onboarding/gravação de perfil de chave de API |
| `plugin-sdk/provider-auth-result` | Helpers de resultado de autenticação de provider | Builder padrão de resultado de autenticação OAuth |
| `plugin-sdk/provider-auth-login` | Helpers de login interativo de provider | Helpers compartilhados de login interativo |
| `plugin-sdk/provider-env-vars` | Helpers de variáveis de ambiente de provider | Helpers de lookup de variável de ambiente de autenticação de provider |
| `plugin-sdk/provider-model-shared` | Helpers compartilhados de modelo/replay de provider | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, builders compartilhados de política de replay, helpers de endpoint de provider e helpers de normalização de ID de modelo |
| `plugin-sdk/provider-catalog-shared` | Helpers compartilhados de catálogo de providers | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
| `plugin-sdk/provider-onboard` | Patches de onboarding de provider | Helpers de configuração de onboarding |
| `plugin-sdk/provider-http` | Helpers HTTP de provider | Helpers genéricos de capacidade HTTP/endpoint de provider |
| `plugin-sdk/provider-web-fetch` | Helpers de web-fetch de provider | Helpers de registro/cache de provider de web-fetch |
| `plugin-sdk/provider-web-search-config-contract` | Helpers de configuração de busca na web de provider | Helpers restritos de configuração/credencial de busca na web para providers que não precisam de wiring de ativação de plugin |
| `plugin-sdk/provider-web-search-contract` | Helpers de contrato de busca na web de provider | Helpers restritos de contrato de configuração/credencial de busca na web, como `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` e setters/getters de credenciais com escopo |
| `plugin-sdk/provider-web-search` | Helpers de busca na web de provider | Helpers de registro/cache/runtime de provider de busca na web |
| `plugin-sdk/provider-tools` | Helpers de compatibilidade de ferramenta/schema de provider | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, limpeza de schema do Gemini + diagnósticos e helpers de compatibilidade do xAI, como `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
| `plugin-sdk/provider-usage` | Helpers de uso de provider | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` e outros helpers de uso de provider |
| `plugin-sdk/provider-stream` | Helpers de wrapper de stream de provider | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, tipos de wrapper de stream e helpers compartilhados de wrapper de Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
| `plugin-sdk/keyed-async-queue` | Fila assíncrona ordenada | `KeyedAsyncQueue` |
| `plugin-sdk/media-runtime` | Helpers compartilhados de mídia | Helpers de fetch/transform/store de mídia mais builders de payload de mídia |
| `plugin-sdk/media-runtime` | Helpers compartilhados de mídia | Helpers de fetch/transform/store de mídia, além de builders de payload de mídia |
| `plugin-sdk/media-generation-runtime` | Helpers compartilhados de geração de mídia | Helpers compartilhados de failover, seleção de candidatos e mensagens de modelo ausente para geração de imagem/vídeo/música |
| `plugin-sdk/media-understanding` | Helpers de media-understanding | Tipos de provedor de compreensão de mídia mais exports de helper voltados ao provedor para imagem/áudio |
| `plugin-sdk/text-runtime` | Helpers compartilhados de texto | Remoção de texto visível ao assistente, helpers de renderização/fragmentação/tabela markdown, helpers de redação, helpers de tag de diretiva, utilitários de texto seguro e helpers relacionados de texto/logging |
| `plugin-sdk/media-understanding` | Helpers de compreensão de mídia | Tipos de provider de compreensão de mídia, além de exports de helpers de imagem/áudio voltados para providers |
| `plugin-sdk/text-runtime` | Helpers compartilhados de texto | Remoção de texto visível ao assistente, helpers de renderização/fragmentação/tabela em markdown, helpers de redação, helpers de tag de diretiva, utilitários de texto seguro e helpers relacionados de texto/logging |
| `plugin-sdk/text-chunking` | Helpers de fragmentação de texto | Helper de fragmentação de texto de saída |
| `plugin-sdk/speech` | Helpers de speech | Tipos de provedor de speech mais exports de helper voltados ao provedor para diretiva, registro e validação |
| `plugin-sdk/speech-core` | Core compartilhado de speech | Tipos de provedor de speech, registro, diretivas, normalização |
| `plugin-sdk/realtime-transcription` | Helpers de transcrição em tempo real | Tipos de provedor e helpers de registro |
| `plugin-sdk/realtime-voice` | Helpers de voz em tempo real | Tipos de provedor e helpers de registro |
| `plugin-sdk/image-generation-core` | Core compartilhado de geração de imagem | Tipos, failover, autenticação e helpers de registro de geração de imagem |
| `plugin-sdk/music-generation` | Helpers de geração de música | Tipos de provedor/solicitação/resultado de geração de música |
| `plugin-sdk/music-generation-core` | Core compartilhado de geração de música | Tipos, helpers de failover, lookup de provedor e parsing de referência de modelo para geração de música |
| `plugin-sdk/video-generation` | Helpers de geração de vídeo | Tipos de provedor/solicitação/resultado de geração de vídeo |
| `plugin-sdk/video-generation-core` | Core compartilhado de geração de vídeo | Tipos, helpers de failover, lookup de provedor e parsing de referência de modelo para geração de vídeo |
| `plugin-sdk/speech` | Helpers de fala | Tipos de provider de fala, além de helpers de diretiva, registro e validação voltados para providers |
| `plugin-sdk/speech-core` | Core compartilhado de fala | Tipos de provider de fala, registro, diretivas, normalização |
| `plugin-sdk/realtime-transcription` | Helpers de transcrição em tempo real | Tipos de provider e helpers de registro |
| `plugin-sdk/realtime-voice` | Helpers de voz em tempo real | Tipos de provider e helpers de registro |
| `plugin-sdk/image-generation-core` | Core compartilhado de geração de imagens | Tipos de geração de imagens, failover, autenticação e helpers de registro |
| `plugin-sdk/music-generation` | Helpers de geração de música | Tipos de provider/request/result de geração de música |
| `plugin-sdk/music-generation-core` | Core compartilhado de geração de música | Tipos de geração de música, helpers de failover, lookup de provider e parsing de model-ref |
| `plugin-sdk/video-generation` | Helpers de geração de vídeo | Tipos de provider/request/result de geração de vídeo |
| `plugin-sdk/video-generation-core` | Core compartilhado de geração de vídeo | Tipos de geração de vídeo, helpers de failover, lookup de provider e parsing de model-ref |
| `plugin-sdk/interactive-runtime` | Helpers de resposta interativa | Normalização/redução de payload de resposta interativa |
| `plugin-sdk/channel-config-primitives` | Primitivas de configuração de canal | Primitivas estreitas de esquema de configuração de canal |
| `plugin-sdk/channel-config-primitives` | Primitivas de configuração de canal | Primitivas restritas de config-schema de canal |
| `plugin-sdk/channel-config-writes` | Helpers de gravação de configuração de canal | Helpers de autorização de gravação de configuração de canal |
| `plugin-sdk/channel-plugin-common` | Prelúdio compartilhado de canal | Exports compartilhados do prelúdio de plugin de canal |
| `plugin-sdk/channel-status` | Helpers de status de canal | Helpers compartilhados de snapshot/resumo de status de canal |
| `plugin-sdk/allowlist-config-edit` | Helpers de configuração de allowlist | Helpers de editar/ler configuração de allowlist |
| `plugin-sdk/group-access` | Helpers de acesso de grupo | Helpers compartilhados de decisão de acesso de grupo |
| `plugin-sdk/direct-dm` | Helpers de DM direto | Helpers compartilhados de autenticação/proteção de DM direto |
| `plugin-sdk/extension-shared` | Helpers compartilhados de extensão | Primitivas helper de canal/status passivo e proxy ambiente |
| `plugin-sdk/webhook-targets` | Helpers de destino de webhook | Registro de destino de webhook e helpers de instalação de rota |
| `plugin-sdk/webhook-path` | Helpers de caminho de webhook | Helpers de normalização de caminho de webhook |
| `plugin-sdk/allowlist-config-edit` | Helpers de configuração de allowlist | Helpers de edição/leitura de configuração de allowlist |
| `plugin-sdk/group-access` | Helpers de acesso a grupo | Helpers compartilhados de decisão de acesso a grupo |
| `plugin-sdk/direct-dm` | Helpers de DM direta | Helpers compartilhados de autenticação/proteção de DM direta |
| `plugin-sdk/extension-shared` | Helpers compartilhados de extensão | Primitivas de canal/status passivo e helper de proxy ambiental |
| `plugin-sdk/webhook-targets` | Helpers de destino de Webhook | Helpers de registro de destino de Webhook e instalação de rota |
| `plugin-sdk/webhook-path` | Helpers de caminho de Webhook | Helpers de normalização de caminho de Webhook |
| `plugin-sdk/web-media` | Helpers compartilhados de mídia web | Helpers de carregamento de mídia remota/local |
| `plugin-sdk/zod` | Reexportação de Zod | `zod` reexportado para consumidores do SDK de plugin |
| `plugin-sdk/memory-core` | Helpers incluídos de memory-core | Superfície helper de gerenciador/configuração/arquivo/CLI de memória |
| `plugin-sdk/memory-core-engine-runtime` | Fachada de runtime do mecanismo de memória | Fachada de runtime de índice/pesquisa de memória |
| `plugin-sdk/memory-core-host-engine-foundation` | Mecanismo foundation do host de memória | Exports do mecanismo foundation do host de memória |
| `plugin-sdk/memory-core-host-engine-embeddings` | Mecanismo de embeddings do host de memória | Exports do mecanismo de embeddings do host de memória |
| `plugin-sdk/zod` | Reexportação do Zod | `zod` reexportado para consumidores do Plugin SDK |
| `plugin-sdk/memory-core` | Helpers empacotados de memory-core | Superfície de helpers de gerenciador/configuração/arquivo/CLI de memória |
| `plugin-sdk/memory-core-engine-runtime` | Fachada de runtime do mecanismo de memória | Fachada de runtime de índice/busca de memória |
| `plugin-sdk/memory-core-host-engine-foundation` | Mecanismo de fundação do host de memória | Exports do mecanismo de fundação do host de memória |
| `plugin-sdk/memory-core-host-engine-embeddings` | Mecanismo de embeddings do host de memória | Contratos de embedding de memória, acesso ao registro, provider local e helpers genéricos de lote/remoto; providers remotos concretos ficam em seus plugins proprietários |
| `plugin-sdk/memory-core-host-engine-qmd` | Mecanismo QMD do host de memória | Exports do mecanismo QMD do host de memória |
| `plugin-sdk/memory-core-host-engine-storage` | Mecanismo de armazenamento do host de memória | Exports do mecanismo de armazenamento do host de memória |
| `plugin-sdk/memory-core-host-multimodal` | Helpers multimodais do host de memória | Helpers multimodais do host de memória |
@ -333,37 +325,37 @@ Exemplos atuais de provedores incluídos:
| `plugin-sdk/memory-core-host-secret` | Helpers de segredo do host de memória | Helpers de segredo do host de memória |
| `plugin-sdk/memory-core-host-events` | Helpers de journal de eventos do host de memória | Helpers de journal de eventos do host de memória |
| `plugin-sdk/memory-core-host-status` | Helpers de status do host de memória | Helpers de status do host de memória |
| `plugin-sdk/memory-core-host-runtime-cli` | Runtime CLI do host de memória | Helpers de runtime CLI do host de memória |
| `plugin-sdk/memory-core-host-runtime-cli` | Runtime de CLI do host de memória | Helpers de runtime de CLI do host de memória |
| `plugin-sdk/memory-core-host-runtime-core` | Runtime core do host de memória | Helpers de runtime core do host de memória |
| `plugin-sdk/memory-core-host-runtime-files` | Helpers de arquivo/runtime do host de memória | Helpers de arquivo/runtime do host de memória |
| `plugin-sdk/memory-host-core` | Alias de runtime core do host de memória | Alias neutro em relação ao fornecedor para helpers de runtime core do host de memória |
| `plugin-sdk/memory-host-events` | Alias de journal de eventos do host de memória | Alias neutro em relação ao fornecedor para helpers de journal de eventos do host de memória |
| `plugin-sdk/memory-host-files` | Alias de arquivo/runtime do host de memória | Alias neutro em relação ao fornecedor para helpers de arquivo/runtime do host de memória |
| `plugin-sdk/memory-host-core` | Alias de runtime core do host de memória | Alias neutro em relação a fornecedor para helpers de runtime core do host de memória |
| `plugin-sdk/memory-host-events` | Alias de journal de eventos do host de memória | Alias neutro em relação a fornecedor para helpers de journal de eventos do host de memória |
| `plugin-sdk/memory-host-files` | Alias de arquivo/runtime do host de memória | Alias neutro em relação a fornecedor para helpers de arquivo/runtime do host de memória |
| `plugin-sdk/memory-host-markdown` | Helpers de markdown gerenciado | Helpers compartilhados de markdown gerenciado para plugins adjacentes à memória |
| `plugin-sdk/memory-host-search` | Fachada de pesquisa de memória ativa | Fachada lazy de runtime do gerenciador de pesquisa de memória ativa |
| `plugin-sdk/memory-host-status` | Alias de status do host de memória | Alias neutro em relação ao fornecedor para helpers de status do host de memória |
| `plugin-sdk/memory-lancedb` | Helpers incluídos de memory-lancedb | Superfície helper de memory-lancedb |
| `plugin-sdk/memory-host-search` | Fachada de busca de Active Memory | Fachada lazy de runtime do gerenciador de busca de Active Memory |
| `plugin-sdk/memory-host-status` | Alias de status do host de memória | Alias neutro em relação a fornecedor para helpers de status do host de memória |
| `plugin-sdk/memory-lancedb` | Helpers empacotados de memory-lancedb | Superfície de helpers de memory-lancedb |
| `plugin-sdk/testing` | Utilitários de teste | Helpers e mocks de teste |
</Accordion>
Esta tabela é intencionalmente o subconjunto comum de migração, não a superfície completa
do SDK. A lista completa de mais de 200 entrypoints está em
Esta tabela é intencionalmente o subconjunto comum de migração, não toda a
superfície do SDK. A lista completa de mais de 200 pontos de entrada está em
`scripts/lib/plugin-sdk-entrypoints.json`.
Essa lista ainda inclui algumas seams helper de plugins incluídos, como
Essa lista ainda inclui algumas superfícies auxiliares de plugins empacotados, como
`plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`,
`plugin-sdk/zalo-setup` e `plugin-sdk/matrix*`. Elas continuam exportadas para
manutenção e compatibilidade de plugins incluídos, mas são intencionalmente
manutenção e compatibilidade de plugins empacotados, mas são intencionalmente
omitidas da tabela comum de migração e não são o destino recomendado para
novo código de plugin.
novo código de Plugin.
A mesma regra se aplica a outras famílias de helper incluídas, como:
A mesma regra se aplica a outras famílias de helpers empacotados, como:
- helpers de suporte a navegador: `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support`
- Matrix: `plugin-sdk/matrix*`
- LINE: `plugin-sdk/line*`
- IRC: `plugin-sdk/irc*`
- superfícies incluídas de helper/plugin como `plugin-sdk/googlechat`,
- superfícies auxiliares/de plugin empacotadas, como `plugin-sdk/googlechat`,
`plugin-sdk/zalouser`, `plugin-sdk/bluebubbles*`,
`plugin-sdk/mattermost*`, `plugin-sdk/msteams`,
`plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`,
@ -372,22 +364,22 @@ A mesma regra se aplica a outras famílias de helper incluídas, como:
`plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`,
`plugin-sdk/thread-ownership` e `plugin-sdk/voice-call`
`plugin-sdk/github-copilot-token` atualmente expõe a superfície estreita de helper de token
`DEFAULT_COPILOT_API_BASE_URL`,
Atualmente, `plugin-sdk/github-copilot-token` expõe a superfície restrita de helper
de token `DEFAULT_COPILOT_API_BASE_URL`,
`deriveCopilotApiBaseUrlFromToken` e `resolveCopilotApiToken`.
Use o import mais estreito que corresponda à tarefa. Se você não encontrar um export,
Use o import mais restrito que corresponda à tarefa. Se você não encontrar um export,
verifique a fonte em `src/plugin-sdk/` ou pergunte no Discord.
## Linha do tempo de remoção
## Cronograma de remoção
| Quando | O que acontece |
| ---------------------- | ------------------------------------------------------------------------ |
| **Agora** | Superfícies obsoletas emitem avisos em runtime |
| **Próxima versão major** | Superfícies obsoletas serão removidas; plugins que ainda as usam falharão |
| Quando | O que acontece |
| ---------------------- | ----------------------------------------------------------------------- |
| **Agora** | As superfícies obsoletas emitem avisos em tempo de execução |
| **Próxima versão principal** | As superfícies obsoletas serão removidas; plugins que ainda as utilizarem falharão |
Todos os plugins core já foram migrados. Plugins externos devem migrar
antes da próxima versão major.
Todos os plugins do core já foram migrados. Plugins externos devem migrar
antes da próxima versão principal.
## Suprimindo os avisos temporariamente
@ -398,13 +390,13 @@ OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run
OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run
```
Isto é uma rota de escape temporária, não uma solução permanente.
Esta é uma rota de escape temporária, não uma solução permanente.
## Relacionado
- [Primeiros passos](/pt-BR/plugins/building-plugins) — crie seu primeiro plugin
- [Primeiros passos](/pt-BR/plugins/building-plugins) — crie seu primeiro Plugin
- [Visão geral do SDK](/pt-BR/plugins/sdk-overview) — referência completa de imports por subcaminho
- [Plugins de canal](/pt-BR/plugins/sdk-channel-plugins) — criando plugins de canal
- [Plugins de provedor](/pt-BR/plugins/sdk-provider-plugins) — criando plugins de provedor
- [Internos de plugin](/pt-BR/plugins/architecture) — análise aprofundada da arquitetura
- [Manifesto de Plugin](/pt-BR/plugins/manifest) — referência do esquema de manifesto
- [Plugins de provider](/pt-BR/plugins/sdk-provider-plugins) — criando plugins de provider
- [Internals de Plugin](/pt-BR/plugins/architecture) — aprofundamento na arquitetura
- [Manifesto de Plugin](/pt-BR/plugins/manifest) — referência do schema de manifesto

606
docs/pt-BR/plugins/sdk-overview.md
View File

@ -1,30 +1,30 @@
---
read_when:
- Você precisa saber de qual subcaminho do SDK importar
- Você quer uma referência para todos os métodos de registro em OpenClawPluginApi
- Você quer uma referência de todos os métodos de registro em `OpenClawPluginApi`
- Você está procurando uma exportação específica do SDK
sidebarTitle: SDK Overview
summary: Mapa de importação, referência da API de registro e arquitetura do SDK
title: Visão geral do SDK de plugins
title: Visão geral do Plugin SDK
x-i18n:
generated_at: "2026-04-11T02:46:25Z"
generated_at: "2026-04-17T05:36:06Z"
model: gpt-5.4
provider: openai
source_hash: 4bfeb5896f68e3e4ee8cf434d43a019e0d1fe5af57f5bf7a5172847c476def0c
source_hash: b177fdb6830f415d998a24812bc2c7db8124d3ba77b0174c9a67ac7d747f7e5a
source_path: plugins/sdk-overview.md
workflow: 15
---
# Visão geral do SDK de plugins
# Visão geral do Plugin SDK
O SDK de plugins é o contrato tipado entre plugins e o core. Esta página é a
O SDK de plugin é o contrato tipado entre plugins e o núcleo. Esta página é a
referência para **o que importar** e **o que você pode registrar**.
<Tip>
**Está procurando um guia prático?**
**Procurando um guia prático?**
- Primeiro plugin? Comece com [Primeiros passos](/pt-BR/plugins/building-plugins)
- Plugin de canal? Consulte [Plugins de canal](/pt-BR/plugins/sdk-channel-plugins)
- Plugin de provedor? Consulte [Plugins de provedor](/pt-BR/plugins/sdk-provider-plugins)
- Plugin de canal? Veja [Plugins de canal](/pt-BR/plugins/sdk-channel-plugins)
- Plugin de provedor? Veja [Plugins de provedor](/pt-BR/plugins/sdk-provider-plugins)
</Tip>
## Convenção de importação
@ -37,269 +37,269 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
```
Cada subcaminho é um módulo pequeno e autocontido. Isso mantém a inicialização rápida e
evita problemas de dependência circular. Para helpers específicos de entrada/build de canal,
prefira `openclaw/plugin-sdk/channel-core`; mantenha `openclaw/plugin-sdk/core` para
a superfície guarda-chuva mais ampla e helpers compartilhados como
evita problemas de dependência circular. Para auxiliares específicos de
entrada/construção de canal, prefira `openclaw/plugin-sdk/channel-core`; mantenha `openclaw/plugin-sdk/core` para
a superfície guarda-chuva mais ampla e auxiliares compartilhados, como
`buildChannelConfigSchema`.
Não adicione nem dependa de seams de conveniência nomeadas por provedor, como
Não adicione nem dependa de seams de conveniência com nome de provedor, como
`openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`,
`openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, ou
seams de helper com marca de canal. Plugins empacotados devem compor subcaminhos genéricos
do SDK dentro de seus próprios barrels `api.ts` ou `runtime-api.ts`, e o core
deve usar esses barrels locais do plugin ou adicionar um contrato genérico e estreito do SDK
seams auxiliares com marca de canal. Plugins empacotados devem compor
subcaminhos genéricos do SDK dentro de seus próprios barrels `api.ts` ou `runtime-api.ts`, e o núcleo
deve usar esses barrels locais do plugin ou adicionar um contrato genérico e restrito do SDK
quando a necessidade for realmente entre canais.
O mapa de exportações gerado ainda contém um pequeno conjunto de
seams de helper de plugins empacotados, como `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`,
O mapa de exportação gerado ainda contém um pequeno conjunto de
seams auxiliares de plugins empacotados, como `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`,
`plugin-sdk/zalo`, `plugin-sdk/zalo-setup` e `plugin-sdk/matrix*`. Esses
subcaminhos existem apenas para manutenção e compatibilidade de plugins empacotados; eles são
omitidos intencionalmente da tabela comum abaixo e não são o caminho de importação recomendado
para novos plugins de terceiros.
intencionalmente omitidos da tabela comum abaixo e não são o caminho de
importação recomendado para novos plugins de terceiros.
## Referência de subcaminhos
Os subcaminhos mais usados, agrupados por finalidade. A lista completa gerada com
mais de 200 subcaminhos fica em `scripts/lib/plugin-sdk-entrypoints.json`.
Os subcaminhos usados com mais frequência, agrupados por finalidade. A lista completa gerada de
mais de 200 subcaminhos está em `scripts/lib/plugin-sdk-entrypoints.json`.
Subcaminhos reservados de helper de plugins empacotados ainda aparecem nessa lista gerada.
Subcaminhos auxiliares reservados para plugins empacotados ainda aparecem nessa lista gerada.
Trate-os como superfícies de detalhe de implementação/compatibilidade, a menos que uma página da documentação
promova explicitamente algum deles como público.
promova explicitamente um deles como público.
### Entrada de plugin
### Entrada do plugin
| Subcaminho | Exportações principais |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `plugin-sdk/plugin-entry` | `definePluginEntry` |
| `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` |
| `plugin-sdk/config-schema` | `OpenClawSchema` |
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
| Subcaminho | Principais exportações |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `plugin-sdk/plugin-entry` | `definePluginEntry` |
| `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` |
| `plugin-sdk/config-schema` | `OpenClawSchema` |
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
<AccordionGroup>
<Accordion title="Subcaminhos de canal">
| Subcaminho | Exportações principais |
| Subcaminho | Principais exportações |
| --- | --- |
| `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
| `plugin-sdk/config-schema` | Exportação do schema Zod raiz de `openclaw.json` (`OpenClawSchema`) |
| `plugin-sdk/config-schema` | Exportação do esquema Zod raiz de `openclaw.json` (`OpenClawSchema`) |
| `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, além de `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
| `plugin-sdk/setup` | Helpers compartilhados de assistente de configuração, prompts de allowlist, builders de status de configuração |
| `plugin-sdk/setup` | Auxiliares compartilhados do assistente de configuração, prompts de allowlist, construtores de status de configuração |
| `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
| `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` |
| `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
| `plugin-sdk/account-core` | Helpers de configuração multi-account/action-gate e helpers de fallback de conta padrão |
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, helpers de normalização de account-id |
| `plugin-sdk/account-resolution` | Helpers de busca de conta + fallback padrão |
| `plugin-sdk/account-helpers` | Helpers estreitos de lista de contas/ações de conta |
| `plugin-sdk/account-core` | Auxiliares de gate de ação/configuração com múltiplas contas, auxiliares de fallback de conta padrão |
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, auxiliares de normalização de ID de conta |
| `plugin-sdk/account-resolution` | Auxiliares de busca de conta + fallback padrão |
| `plugin-sdk/account-helpers` | Auxiliares restritos para lista de contas/ação de conta |
| `plugin-sdk/channel-pairing` | `createChannelPairingController` |
| `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` |
| `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` |
| `plugin-sdk/channel-config-schema` | Tipos de schema de configuração de canal |
| `plugin-sdk/telegram-command-config` | Helpers de normalização/validação de comando personalizado do Telegram com fallback de contrato empacotado |
| `plugin-sdk/channel-config-schema` | Tipos de esquema de configuração de canal |
| `plugin-sdk/telegram-command-config` | Auxiliares de normalização/validação de comandos personalizados do Telegram com fallback de contrato empacotado |
| `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` |
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` |
| `plugin-sdk/inbound-envelope` | Helpers compartilhados de rota de entrada + builder de envelope |
| `plugin-sdk/inbound-reply-dispatch` | Helpers compartilhados de registro e dispatch de entrada |
| `plugin-sdk/messaging-targets` | Helpers de parsing/correspondência de alvo |
| `plugin-sdk/outbound-media` | Helpers compartilhados de carregamento de mídia de saída |
| `plugin-sdk/outbound-runtime` | Helpers de identidade de saída/delegação de envio |
| `plugin-sdk/thread-bindings-runtime` | Lifecycle de binding de thread e helpers de adapter |
| `plugin-sdk/agent-media-payload` | Builder legado de payload de mídia do agente |
| `plugin-sdk/conversation-runtime` | Helpers de binding configurado, pairing e binding de conversa/thread |
| `plugin-sdk/runtime-config-snapshot` | Helper de snapshot de configuração de runtime |
| `plugin-sdk/runtime-group-policy` | Helpers de resolução de política de grupo em runtime |
| `plugin-sdk/channel-status` | Helpers compartilhados de snapshot/resumo de status de canal |
| `plugin-sdk/channel-config-primitives` | Primitivos estreitos de schema de configuração de canal |
| `plugin-sdk/channel-config-writes` | Helpers de autorização de escrita de configuração de canal |
| `plugin-sdk/channel-plugin-common` | Exportações de prelude compartilhadas de plugin de canal |
| `plugin-sdk/allowlist-config-edit` | Helpers de leitura/edição de configuração de allowlist |
| `plugin-sdk/group-access` | Helpers compartilhados de decisão de acesso a grupo |
| `plugin-sdk/direct-dm` | Helpers compartilhados de autenticação/proteção de DM direta |
| `plugin-sdk/interactive-runtime` | Helpers de normalização/redução de payload de resposta interativa |
| `plugin-sdk/channel-inbound` | Helpers de debounce de entrada, correspondência de menção, política de menção e envelope |
| `plugin-sdk/inbound-envelope` | Auxiliares compartilhados de rota de entrada + construtor de envelope |
| `plugin-sdk/inbound-reply-dispatch` | Auxiliares compartilhados de registro e despacho de entrada |
| `plugin-sdk/messaging-targets` | Auxiliares de análise/correspondência de alvos |
| `plugin-sdk/outbound-media` | Auxiliares compartilhados de carregamento de mídia de saída |
| `plugin-sdk/outbound-runtime` | Auxiliares de identidade de saída/delegação de envio |
| `plugin-sdk/thread-bindings-runtime` | Ciclo de vida de vínculo de thread e auxiliares de adaptador |
| `plugin-sdk/agent-media-payload` | Construtor legado de payload de mídia do agente |
| `plugin-sdk/conversation-runtime` | Auxiliares de vínculo de conversa/thread, pareamento e vínculo configurado |
| `plugin-sdk/runtime-config-snapshot` | Auxiliar de snapshot de configuração em runtime |
| `plugin-sdk/runtime-group-policy` | Auxiliares de resolução de política de grupo em runtime |
| `plugin-sdk/channel-status` | Auxiliares compartilhados de snapshot/resumo de status do canal |
| `plugin-sdk/channel-config-primitives` | Primitivas restritas de esquema de configuração de canal |
| `plugin-sdk/channel-config-writes` | Auxiliares de autorização de gravação de configuração de canal |
| `plugin-sdk/channel-plugin-common` | Exportações de prelúdio compartilhadas de plugin de canal |
| `plugin-sdk/allowlist-config-edit` | Auxiliares de leitura/edição de configuração de allowlist |
| `plugin-sdk/group-access` | Auxiliares compartilhados de decisão de acesso a grupo |
| `plugin-sdk/direct-dm` | Auxiliares compartilhados de autenticação/proteção de DM direta |
| `plugin-sdk/interactive-runtime` | Auxiliares de normalização/redução de payload de resposta interativa |
| `plugin-sdk/channel-inbound` | Debounce de entrada, correspondência de menção, auxiliares de política de menção e auxiliares de envelope |
| `plugin-sdk/channel-send-result` | Tipos de resultado de resposta |
| `plugin-sdk/channel-actions` | `createMessageToolButtonsSchema`, `createMessageToolCardSchema` |
| `plugin-sdk/channel-targets` | Helpers de parsing/correspondência de alvo |
| `plugin-sdk/channel-targets` | Auxiliares de análise/correspondência de alvos |
| `plugin-sdk/channel-contract` | Tipos de contrato de canal |
| `plugin-sdk/channel-feedback` | Wiring de feedback/reação |
| `plugin-sdk/channel-secret-runtime` | Helpers estreitos de contrato de segredo, como `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, e tipos de destino de segredo |
| `plugin-sdk/channel-feedback` | Ligação de feedback/reação |
| `plugin-sdk/channel-secret-runtime` | Auxiliares restritos de contrato de segredo, como `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment` e tipos de alvo de segredo |
</Accordion>
<Accordion title="Subcaminhos de provedor">
| Subcaminho | Exportações principais |
| Subcaminho | Principais exportações |
| --- | --- |
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
| `plugin-sdk/provider-setup` | Helpers selecionados de configuração de provedor local/self-hosted |
| `plugin-sdk/self-hosted-provider-setup` | Helpers focados de configuração de provedor self-hosted compatível com OpenAI |
| `plugin-sdk/cli-backend` | Padrões de backend de CLI + constantes de watchdog |
| `plugin-sdk/provider-auth-runtime` | Helpers de runtime para resolução de chave de API para plugins de provedor |
| `plugin-sdk/provider-auth-api-key` | Helpers de onboarding/escrita de perfil de chave de API, como `upsertApiKeyProfile` |
| `plugin-sdk/provider-auth-result` | Builder padrão de resultado de autenticação OAuth |
| `plugin-sdk/provider-auth-login` | Helpers compartilhados de login interativo para plugins de provedor |
| `plugin-sdk/provider-env-vars` | Helpers de busca de variáveis de ambiente para autenticação de provedor |
| `plugin-sdk/provider-setup` | Auxiliares curados de configuração de provedor local/self-hosted |
| `plugin-sdk/self-hosted-provider-setup` | Auxiliares focados de configuração de provedor self-hosted compatível com OpenAI |
| `plugin-sdk/cli-backend` | Padrões de backend da CLI + constantes de watchdog |
| `plugin-sdk/provider-auth-runtime` | Auxiliares de runtime para resolução de chave de API para plugins de provedor |
| `plugin-sdk/provider-auth-api-key` | Auxiliares de onboarding/gravação de perfil de chave de API, como `upsertApiKeyProfile` |
| `plugin-sdk/provider-auth-result` | Construtor padrão de resultado de autenticação OAuth |
| `plugin-sdk/provider-auth-login` | Auxiliares compartilhados de login interativo para plugins de provedor |
| `plugin-sdk/provider-env-vars` | Auxiliares de busca de variáveis de ambiente de autenticação do provedor |
| `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` |
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, builders compartilhados de política de replay, helpers de endpoint de provedor e helpers de normalização de model-id, como `normalizeNativeXaiModelId` |
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, construtores compartilhados de política de replay, auxiliares de endpoint do provedor e auxiliares de normalização de ID de modelo, como `normalizeNativeXaiModelId` |
| `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
| `plugin-sdk/provider-http` | Helpers genéricos de capacidade HTTP/endpoint de provedor |
| `plugin-sdk/provider-web-fetch-contract` | Helpers estreitos de contrato de configuração/seleção de web-fetch, como `enablePluginInConfig` e `WebFetchProviderPlugin` |
| `plugin-sdk/provider-web-fetch` | Helpers de registro/cache de provedor web-fetch |
| `plugin-sdk/provider-web-search-config-contract` | Helpers estreitos de configuração/credenciais de web-search para provedores que não precisam de wiring de ativação de plugin |
| `plugin-sdk/provider-web-search-contract` | Helpers estreitos de contrato de configuração/credenciais de web-search, como `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` e setters/getters de credenciais com escopo |
| `plugin-sdk/provider-web-search` | Helpers de registro/cache/runtime de provedor web-search |
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, limpeza + diagnósticos de schema Gemini e helpers de compatibilidade xAI, como `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
| `plugin-sdk/provider-http` | Auxiliares genéricos de HTTP/capacidade de endpoint do provedor |
| `plugin-sdk/provider-web-fetch-contract` | Auxiliares restritos de contrato de configuração/seleção de web-fetch, como `enablePluginInConfig` e `WebFetchProviderPlugin` |
| `plugin-sdk/provider-web-fetch` | Auxiliares de registro/cache de provedor web-fetch |
| `plugin-sdk/provider-web-search-config-contract` | Auxiliares restritos de configuração/credencial de web-search para provedores que não precisam de ligação de ativação de plugin |
| `plugin-sdk/provider-web-search-contract` | Auxiliares restritos de contrato de configuração/credencial de web-search, como `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` e setters/getters de credenciais com escopo |
| `plugin-sdk/provider-web-search` | Auxiliares de runtime/registro/cache de provedor web-search |
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, limpeza + diagnóstico de esquema Gemini e auxiliares de compatibilidade xAI, como `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
| `plugin-sdk/provider-usage` | `fetchClaudeUsage` e similares |
| `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, tipos de wrapper de stream e helpers compartilhados de wrapper Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
| `plugin-sdk/provider-onboard` | Helpers de patch de configuração de onboarding |
| `plugin-sdk/global-singleton` | Helpers de singleton/map/cache local ao processo |
| `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, tipos de wrapper de stream e auxiliares compartilhados de wrapper para Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
| `plugin-sdk/provider-onboard` | Auxiliares de patch de configuração de onboarding |
| `plugin-sdk/global-singleton` | Auxiliares de singleton/mapa/cache local ao processo |
</Accordion>
<Accordion title="Subcaminhos de autenticação e segurança">
| Subcaminho | Exportações principais |
| Subcaminho | Principais exportações |
| --- | --- |
| `plugin-sdk/command-auth` | `resolveControlCommandGate`, helpers de registro de comandos, helpers de autorização do remetente |
| `plugin-sdk/command-status` | Builders de mensagens de comando/ajuda, como `buildCommandsMessagePaginated` e `buildHelpMessage` |
| `plugin-sdk/approval-auth-runtime` | Helpers de resolução de aprovador e autenticação de ação no mesmo chat |
| `plugin-sdk/approval-client-runtime` | Helpers de perfil/filtro de aprovação de execução nativa |
| `plugin-sdk/approval-delivery-runtime` | Adapters de capacidade/entrega de aprovação nativa |
| `plugin-sdk/approval-gateway-runtime` | Helper compartilhado de resolução de gateway de aprovação |
| `plugin-sdk/approval-handler-adapter-runtime` | Helpers leves de carregamento de adapter de aprovação nativa para entrypoints quentes de canal |
| `plugin-sdk/approval-handler-runtime` | Helpers mais amplos de runtime para handler de aprovação; prefira os seams mais estreitos de adapter/gateway quando forem suficientes |
| `plugin-sdk/approval-native-runtime` | Helpers nativos de alvo de aprovação + binding de conta |
| `plugin-sdk/approval-reply-runtime` | Helpers de payload de resposta de aprovação de execução/plugin |
| `plugin-sdk/command-auth-native` | Helpers nativos de autenticação de comando + helpers nativos de alvo de sessão |
| `plugin-sdk/command-detection` | Helpers compartilhados de detecção de comando |
| `plugin-sdk/command-surface` | Helpers de normalização de corpo de comando e de superfície de comando |
| `plugin-sdk/command-auth` | `resolveControlCommandGate`, auxiliares de registro de comandos, auxiliares de autorização do remetente |
| `plugin-sdk/command-status` | Construtores de mensagem de comando/ajuda, como `buildCommandsMessagePaginated` e `buildHelpMessage` |
| `plugin-sdk/approval-auth-runtime` | Resolução de aprovador e auxiliares de autenticação de ação no mesmo chat |
| `plugin-sdk/approval-client-runtime` | Auxiliares de perfil/filtro de aprovação para execução nativa |
| `plugin-sdk/approval-delivery-runtime` | Adaptadores nativos de capacidade/entrega de aprovação |
| `plugin-sdk/approval-gateway-runtime` | Auxiliar compartilhado de resolução de Gateway de aprovação |
| `plugin-sdk/approval-handler-adapter-runtime` | Auxiliares leves de carregamento de adaptador de aprovação nativa para entrypoints de canal de hot path |
| `plugin-sdk/approval-handler-runtime` | Auxiliares mais amplos de runtime do manipulador de aprovação; prefira os seams mais restritos de adaptador/Gateway quando forem suficientes |
| `plugin-sdk/approval-native-runtime` | Auxiliares nativos de alvo de aprovação + vínculo de conta |
| `plugin-sdk/approval-reply-runtime` | Auxiliares de payload de resposta de aprovação de execução/plugin |
| `plugin-sdk/command-auth-native` | Auxiliares nativos de autenticação de comando + alvo de sessão nativa |
| `plugin-sdk/command-detection` | Auxiliares compartilhados de detecção de comandos |
| `plugin-sdk/command-surface` | Auxiliares de normalização de corpo de comando e superfície de comando |
| `plugin-sdk/allow-from` | `formatAllowFromLowercase` |
| `plugin-sdk/channel-secret-runtime` | Helpers estreitos de coleta de contrato de segredo para superfícies de segredo de canal/plugin |
| `plugin-sdk/secret-ref-runtime` | Helpers estreitos de `coerceSecretRef` e tipagem de SecretRef para parsing de contrato/configuração de segredo |
| `plugin-sdk/security-runtime` | Helpers compartilhados de confiança, bloqueio de DM, conteúdo externo e coleta de segredo |
| `plugin-sdk/ssrf-policy` | Helpers de política SSRF para allowlist de host e rede privada |
| `plugin-sdk/ssrf-runtime` | Helpers de dispatcher fixado, fetch protegido por SSRF e política SSRF |
| `plugin-sdk/secret-input` | Helpers de parsing de entrada de segredo |
| `plugin-sdk/webhook-ingress` | Helpers de requisição/alvo de webhook |
| `plugin-sdk/webhook-request-guards` | Helpers de tamanho do corpo da requisição/timeout |
| `plugin-sdk/channel-secret-runtime` | Auxiliares restritos de coleta de contrato de segredo para superfícies de segredo de canal/plugin |
| `plugin-sdk/secret-ref-runtime` | Auxiliares restritos de tipagem de `coerceSecretRef` e SecretRef para parsing de contrato/configuração de segredo |
| `plugin-sdk/security-runtime` | Auxiliares compartilhados de confiança, controle de DM, conteúdo externo e coleta de segredos |
| `plugin-sdk/ssrf-policy` | Auxiliares de allowlist de host e política de SSRF para rede privada |
| `plugin-sdk/ssrf-runtime` | Auxiliares de dispatcher fixado, fetch protegido contra SSRF e política de SSRF |
| `plugin-sdk/secret-input` | Auxiliares de parsing de entrada de segredo |
| `plugin-sdk/webhook-ingress` | Auxiliares de requisição/alvo de Webhook |
| `plugin-sdk/webhook-request-guards` | Auxiliares de tamanho do corpo/timeout da requisição |
</Accordion>
<Accordion title="Subcaminhos de runtime e armazenamento">
| Subcaminho | Exportações principais |
| Subcaminho | Principais exportações |
| --- | --- |
| `plugin-sdk/runtime` | Helpers amplos de runtime/logging/backup/instalação de plugin |
| `plugin-sdk/runtime-env` | Helpers estreitos de env de runtime, logger, timeout, retry e backoff |
| `plugin-sdk/channel-runtime-context` | Helpers genéricos de registro e busca de contexto de runtime de canal |
| `plugin-sdk/runtime` | Auxiliares amplos de runtime/logging/backup/instalação de plugin |
| `plugin-sdk/runtime-env` | Auxiliares restritos de ambiente de runtime, logger, timeout, retry e backoff |
| `plugin-sdk/channel-runtime-context` | Auxiliares genéricos de registro e busca de contexto de runtime de canal |
| `plugin-sdk/runtime-store` | `createPluginRuntimeStore` |
| `plugin-sdk/plugin-runtime` | Helpers compartilhados de comando/hook/http/interativo de plugin |
| `plugin-sdk/hook-runtime` | Helpers compartilhados de pipeline de webhook/hook interno |
| `plugin-sdk/lazy-runtime` | Helpers de importação/binding lazy de runtime, como `createLazyRuntimeModule`, `createLazyRuntimeMethod` e `createLazyRuntimeSurface` |
| `plugin-sdk/process-runtime` | Helpers de execução de processo |
| `plugin-sdk/cli-runtime` | Helpers de formatação, espera e versão da CLI |
| `plugin-sdk/gateway-runtime` | Helpers de cliente do Gateway e patch de status de canal |
| `plugin-sdk/config-runtime` | Helpers de carregamento/escrita de configuração |
| `plugin-sdk/plugin-runtime` | Auxiliares compartilhados de comando/hook/http/interativo de plugin |
| `plugin-sdk/hook-runtime` | Auxiliares compartilhados de pipeline de Webhook/hook interno |
| `plugin-sdk/lazy-runtime` | Auxiliares de importação/vínculo lazy de runtime, como `createLazyRuntimeModule`, `createLazyRuntimeMethod` e `createLazyRuntimeSurface` |
| `plugin-sdk/process-runtime` | Auxiliares de execução de processo |
| `plugin-sdk/cli-runtime` | Auxiliares de formatação, espera e versão da CLI |
| `plugin-sdk/gateway-runtime` | Auxiliares de cliente Gateway e patch de status de canal |
| `plugin-sdk/config-runtime` | Auxiliares de carregamento/gravação de configuração |
| `plugin-sdk/telegram-command-config` | Normalização de nome/descrição de comando do Telegram e verificações de duplicidade/conflito, mesmo quando a superfície de contrato empacotada do Telegram não está disponível |
| `plugin-sdk/approval-runtime` | Helpers de aprovação de execução/plugin, builders de capacidade de aprovação, helpers de autenticação/perfil, helpers nativos de roteamento/runtime |
| `plugin-sdk/reply-runtime` | Helpers compartilhados de runtime de entrada/resposta, chunking, dispatch, heartbeat, planejador de resposta |
| `plugin-sdk/reply-dispatch-runtime` | Helpers estreitos de dispatch/finalização de resposta |
| `plugin-sdk/reply-history` | Helpers compartilhados de histórico de resposta em janela curta, como `buildHistoryContext`, `recordPendingHistoryEntry` e `clearHistoryEntriesIfEnabled` |
| `plugin-sdk/approval-runtime` | Auxiliares de aprovação de execução/plugin, construtores de capacidade de aprovação, auxiliares de autenticação/perfil, auxiliares nativos de roteamento/runtime |
| `plugin-sdk/reply-runtime` | Auxiliares compartilhados de runtime de entrada/resposta, fragmentação, despacho, Heartbeat, planejador de resposta |
| `plugin-sdk/reply-dispatch-runtime` | Auxiliares restritos de despacho/finalização de resposta |
| `plugin-sdk/reply-history` | Auxiliares compartilhados de histórico de respostas de janela curta, como `buildHistoryContext`, `recordPendingHistoryEntry` e `clearHistoryEntriesIfEnabled` |
| `plugin-sdk/reply-reference` | `createReplyReferencePlanner` |
| `plugin-sdk/reply-chunking` | Helpers estreitos de chunking de texto/Markdown |
| `plugin-sdk/session-store-runtime` | Helpers de caminho do armazenamento de sessão + updated-at |
| `plugin-sdk/state-paths` | Helpers de caminho de diretório de estado/OAuth |
| `plugin-sdk/routing` | Helpers de binding de rota/chave de sessão/conta, como `resolveAgentRoute`, `buildAgentSessionKey` e `resolveDefaultAgentBoundAccountId` |
| `plugin-sdk/status-helpers` | Helpers compartilhados de resumo de status de canal/conta, padrões de estado de runtime e helpers de metadados de problema |
| `plugin-sdk/target-resolver-runtime` | Helpers compartilhados de resolvedor de alvo |
| `plugin-sdk/string-normalization-runtime` | Helpers de normalização de slug/string |
| `plugin-sdk/request-url` | Extrai URLs string de entradas do tipo fetch/request |
| `plugin-sdk/run-command` | Executor de comando com tempo controlado e resultados normalizados de stdout/stderr |
| `plugin-sdk/reply-chunking` | Auxiliares restritos de fragmentação de texto/markdown |
| `plugin-sdk/session-store-runtime` | Auxiliares de caminho da store de sessão + updated-at |
| `plugin-sdk/state-paths` | Auxiliares de caminho de diretório de estado/OAuth |
| `plugin-sdk/routing` | Auxiliares de roteamento/chave de sessão/vínculo de conta, como `resolveAgentRoute`, `buildAgentSessionKey` e `resolveDefaultAgentBoundAccountId` |
| `plugin-sdk/status-helpers` | Auxiliares compartilhados de resumo de status de canal/conta, padrões de estado de runtime e auxiliares de metadados de problema |
| `plugin-sdk/target-resolver-runtime` | Auxiliares compartilhados de resolvedor de alvo |
| `plugin-sdk/string-normalization-runtime` | Auxiliares de normalização de slug/string |
| `plugin-sdk/request-url` | Extrair URLs em string de entradas do tipo fetch/request |
| `plugin-sdk/run-command` | Executor de comandos com tempo controlado e resultados normalizados de stdout/stderr |
| `plugin-sdk/param-readers` | Leitores comuns de parâmetros de ferramenta/CLI |
| `plugin-sdk/tool-payload` | Extrai payloads normalizados de objetos de resultado de ferramenta |
| `plugin-sdk/tool-send` | Extrai campos canônicos de alvo de envio de argumentos de ferramenta |
| `plugin-sdk/temp-path` | Helpers compartilhados de caminho temporário para download |
| `plugin-sdk/logging-core` | Helpers de logger de subsistema e de redação |
| `plugin-sdk/markdown-table-runtime` | Helpers de modo de tabela Markdown |
| `plugin-sdk/json-store` | Pequenos helpers de leitura/escrita de estado JSON |
| `plugin-sdk/file-lock` | Helpers de file-lock reentrante |
| `plugin-sdk/persistent-dedupe` | Helpers de cache de deduplicação persistente em disco |
| `plugin-sdk/acp-runtime` | Helpers de runtime/sessão ACP e dispatch de resposta |
| `plugin-sdk/agent-config-primitives` | Primitivos estreitos de schema de configuração de runtime de agente |
| `plugin-sdk/tool-payload` | Extrair payloads normalizados de objetos de resultado de ferramenta |
| `plugin-sdk/tool-send` | Extrair campos canônicos de alvo de envio de argumentos de ferramenta |
| `plugin-sdk/temp-path` | Auxiliares compartilhados de caminho temporário para download |
| `plugin-sdk/logging-core` | Auxiliares de logger de subsistema e redação |
| `plugin-sdk/markdown-table-runtime` | Auxiliares de modo de tabela em Markdown |
| `plugin-sdk/json-store` | Pequenos auxiliares de leitura/gravação de estado JSON |
| `plugin-sdk/file-lock` | Auxiliares de file lock reentrante |
| `plugin-sdk/persistent-dedupe` | Auxiliares de cache de deduplicação com persistência em disco |
| `plugin-sdk/acp-runtime` | Auxiliares de runtime/sessão do ACP e despacho de resposta |
| `plugin-sdk/agent-config-primitives` | Primitivas restritas de esquema de configuração de runtime de agente |
| `plugin-sdk/boolean-param` | Leitor flexível de parâmetro booleano |
| `plugin-sdk/dangerous-name-runtime` | Helpers de resolução de correspondência de nome perigoso |
| `plugin-sdk/device-bootstrap` | Helpers de bootstrap de dispositivo e token de pairing |
| `plugin-sdk/extension-shared` | Primitivos auxiliares compartilhados de canal passivo, status e proxy ambiente |
| `plugin-sdk/models-provider-runtime` | Helpers de resposta de provedor/comando `/models` |
| `plugin-sdk/skill-commands-runtime` | Helpers de listagem de comandos de Skills |
| `plugin-sdk/native-command-registry` | Helpers de registro/build/serialização de comando nativo |
| `plugin-sdk/agent-harness` | Superfície experimental de plugin confiável para harnesses de agente de baixo nível: tipos de harness, helpers de condução/aborto de execução ativa, bridge de ferramentas do OpenClaw e utilitários de resultado de tentativa |
| `plugin-sdk/provider-zai-endpoint` | Helpers de detecção de endpoint Z.A.I |
| `plugin-sdk/infra-runtime` | Helpers de evento do sistema/heartbeat |
| `plugin-sdk/collection-runtime` | Pequenos helpers de cache limitado |
| `plugin-sdk/diagnostic-runtime` | Helpers de flag e evento de diagnóstico |
| `plugin-sdk/error-runtime` | Grafo de erros, formatação, helpers compartilhados de classificação de erros, `isApprovalNotFoundError` |
| `plugin-sdk/fetch-runtime` | Helpers de fetch encapsulado, proxy e busca fixada |
| `plugin-sdk/host-runtime` | Helpers de normalização de hostname e host SCP |
| `plugin-sdk/retry-runtime` | Helpers de configuração e executor de retry |
| `plugin-sdk/agent-runtime` | Helpers de diretório/identidade/workspace de agente |
| `plugin-sdk/dangerous-name-runtime` | Auxiliares de resolução de correspondência de nomes perigosos |
| `plugin-sdk/device-bootstrap` | Auxiliares de bootstrap de dispositivo e token de pareamento |
| `plugin-sdk/extension-shared` | Primitivas auxiliares compartilhadas de canal passivo, status e proxy ambiente |
| `plugin-sdk/models-provider-runtime` | Auxiliares de resposta de provedor/comando `/models` |
| `plugin-sdk/skill-commands-runtime` | Auxiliares de listagem de comandos de Skills |
| `plugin-sdk/native-command-registry` | Auxiliares de registro/construção/serialização de comandos nativos |
| `plugin-sdk/agent-harness` | Superfície experimental de plugin confiável para harnesses de agente de baixo nível: tipos de harness, auxiliares de condução/aborto de execução ativa, auxiliares de ponte de ferramenta do OpenClaw e utilitários de resultado de tentativa |
| `plugin-sdk/provider-zai-endpoint` | Auxiliares de detecção de endpoint do Z.A.I |
| `plugin-sdk/infra-runtime` | Auxiliares de evento do sistema/Heartbeat |
| `plugin-sdk/collection-runtime` | Pequenos auxiliares de cache limitado |
| `plugin-sdk/diagnostic-runtime` | Auxiliares de flag e evento de diagnóstico |
| `plugin-sdk/error-runtime` | Grafo de erros, formatação, auxiliares compartilhados de classificação de erros, `isApprovalNotFoundError` |
| `plugin-sdk/fetch-runtime` | Auxiliares de fetch encapsulado, proxy e busca fixada |
| `plugin-sdk/host-runtime` | Auxiliares de normalização de hostname e host SCP |
| `plugin-sdk/retry-runtime` | Auxiliares de configuração de retry e executor de retry |
| `plugin-sdk/agent-runtime` | Auxiliares de diretório/identidade/workspace de agente |
| `plugin-sdk/directory-runtime` | Consulta/deduplicação de diretório com base em configuração |
| `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` |
</Accordion>
<Accordion title="Subcaminhos de capacidade e teste">
| Subcaminho | Exportações principais |
<Accordion title="Subcaminhos de capacidade e testes">
| Subcaminho | Principais exportações |
| --- | --- |
| `plugin-sdk/media-runtime` | Helpers compartilhados de busca/transformação/armazenamento de mídia, além de builders de payload de mídia |
| `plugin-sdk/media-generation-runtime` | Helpers compartilhados de failover de geração de mídia, seleção de candidatos e mensagens de modelo ausente |
| `plugin-sdk/media-understanding` | Tipos de provedor de interpretação de mídia, além de exportações de helpers de imagem/áudio voltadas a provedores |
| `plugin-sdk/text-runtime` | Helpers compartilhados de texto/Markdown/logging, como remoção de texto visível ao assistente, helpers de renderização/chunking/tabela em Markdown, helpers de redação, helpers de tag de diretiva e utilitários de texto seguro |
| `plugin-sdk/text-chunking` | Helper de chunking de texto de saída |
| `plugin-sdk/speech` | Tipos de provedor de fala, além de helpers voltados a provedores para diretiva, registro e validação |
| `plugin-sdk/speech-core` | Tipos compartilhados de provedor de fala, helpers de registro, diretiva e normalização |
| `plugin-sdk/realtime-transcription` | Tipos de provedor de transcrição em tempo real e helpers de registro |
| `plugin-sdk/realtime-voice` | Tipos de provedor de voz em tempo real e helpers de registro |
| `plugin-sdk/media-runtime` | Auxiliares compartilhados de busca/transformação/armazenamento de mídia, além de construtores de payload de mídia |
| `plugin-sdk/media-generation-runtime` | Auxiliares compartilhados de failover de geração de mídia, seleção de candidatos e mensagens para modelo ausente |
| `plugin-sdk/media-understanding` | Tipos de provedor de entendimento de mídia, além de exportações auxiliares voltadas ao provedor para imagem/áudio |
| `plugin-sdk/text-runtime` | Auxiliares compartilhados de texto/markdown/logging, como remoção de texto visível ao assistente, auxiliares de renderização/fragmentação/tabela em markdown, auxiliares de redação, auxiliares de tag de diretiva e utilitários de texto seguro |
| `plugin-sdk/text-chunking` | Auxiliar de fragmentação de texto de saída |
| `plugin-sdk/speech` | Tipos de provedor de fala, além de auxiliares voltados ao provedor para diretiva, registro e validação |
| `plugin-sdk/speech-core` | Tipos compartilhados de provedor de fala, auxiliares de registro, diretiva e normalização |
| `plugin-sdk/realtime-transcription` | Tipos de provedor de transcrição em tempo real e auxiliares de registro |
| `plugin-sdk/realtime-voice` | Tipos de provedor de voz em tempo real e auxiliares de registro |
| `plugin-sdk/image-generation` | Tipos de provedor de geração de imagem |
| `plugin-sdk/image-generation-core` | Tipos compartilhados de geração de imagem, helpers de failover, autenticação e registro |
| `plugin-sdk/image-generation-core` | Tipos compartilhados de geração de imagem, auxiliares de failover, autenticação e registro |
| `plugin-sdk/music-generation` | Tipos de provedor/requisição/resultado de geração de música |
| `plugin-sdk/music-generation-core` | Tipos compartilhados de geração de música, helpers de failover, busca de provedor e parsing de model-ref |
| `plugin-sdk/music-generation-core` | Tipos compartilhados de geração de música, auxiliares de failover, busca de provedor e parsing de referência de modelo |
| `plugin-sdk/video-generation` | Tipos de provedor/requisição/resultado de geração de vídeo |
| `plugin-sdk/video-generation-core` | Tipos compartilhados de geração de vídeo, helpers de failover, busca de provedor e parsing de model-ref |
| `plugin-sdk/webhook-targets` | Registro de alvos de webhook e helpers de instalação de rota |
| `plugin-sdk/webhook-path` | Helpers de normalização de caminho de webhook |
| `plugin-sdk/web-media` | Helpers compartilhados de carregamento de mídia remota/local |
| `plugin-sdk/zod` | `zod` reexportado para consumidores do SDK de plugins |
| `plugin-sdk/video-generation-core` | Tipos compartilhados de geração de vídeo, auxiliares de failover, busca de provedor e parsing de referência de modelo |
| `plugin-sdk/webhook-targets` | Registro de alvos de Webhook e auxiliares de instalação de rota |
| `plugin-sdk/webhook-path` | Auxiliares de normalização de caminho de Webhook |
| `plugin-sdk/web-media` | Auxiliares compartilhados de carregamento de mídia remota/local |
| `plugin-sdk/zod` | `zod` reexportado para consumidores do Plugin SDK |
| `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` |
</Accordion>
<Accordion title="Subcaminhos de memória">
| Subcaminho | Exportações principais |
| Subcaminho | Principais exportações |
| --- | --- |
| `plugin-sdk/memory-core` | Superfície auxiliar empacotada de memory-core para helpers de manager/configuração/arquivo/CLI |
| `plugin-sdk/memory-core` | Superfície auxiliar empacotada de memory-core para auxiliares de manager/configuração/arquivo/CLI |
| `plugin-sdk/memory-core-engine-runtime` | Fachada de runtime de índice/busca de memória |
| `plugin-sdk/memory-core-host-engine-foundation` | Exportações do motor de fundação do host de memória |
| `plugin-sdk/memory-core-host-engine-embeddings` | Exportações do motor de embeddings do host de memória |
| `plugin-sdk/memory-core-host-engine-qmd` | Exportações do motor QMD do host de memória |
| `plugin-sdk/memory-core-host-engine-storage` | Exportações do motor de armazenamento do host de memória |
| `plugin-sdk/memory-core-host-multimodal` | Helpers multimodais do host de memória |
| `plugin-sdk/memory-core-host-query` | Helpers de consulta do host de memória |
| `plugin-sdk/memory-core-host-secret` | Helpers de segredo do host de memória |
| `plugin-sdk/memory-core-host-events` | Helpers de journal de eventos do host de memória |
| `plugin-sdk/memory-core-host-status` | Helpers de status do host de memória |
| `plugin-sdk/memory-core-host-runtime-cli` | Helpers de runtime de CLI do host de memória |
| `plugin-sdk/memory-core-host-runtime-core` | Helpers de runtime core do host de memória |
| `plugin-sdk/memory-core-host-runtime-files` | Helpers de arquivo/runtime do host de memória |
| `plugin-sdk/memory-host-core` | Alias neutro em relação ao fornecedor para helpers de runtime core do host de memória |
| `plugin-sdk/memory-host-events` | Alias neutro em relação ao fornecedor para helpers de journal de eventos do host de memória |
| `plugin-sdk/memory-host-files` | Alias neutro em relação ao fornecedor para helpers de arquivo/runtime do host de memória |
| `plugin-sdk/memory-host-markdown` | Helpers compartilhados de Markdown gerenciado para plugins adjacentes à memória |
| `plugin-sdk/memory-host-search` | Fachada de runtime de memória ativa para acesso ao search-manager |
| `plugin-sdk/memory-host-status` | Alias neutro em relação ao fornecedor para helpers de status do host de memória |
| `plugin-sdk/memory-core-host-engine-foundation` | Exportações do engine foundation do host de memória |
| `plugin-sdk/memory-core-host-engine-embeddings` | Contratos de embedding do host de memória, acesso ao registro, provedor local e auxiliares genéricos de lote/remoto |
| `plugin-sdk/memory-core-host-engine-qmd` | Exportações do engine QMD do host de memória |
| `plugin-sdk/memory-core-host-engine-storage` | Exportações do engine de armazenamento do host de memória |
| `plugin-sdk/memory-core-host-multimodal` | Auxiliares multimodais do host de memória |
| `plugin-sdk/memory-core-host-query` | Auxiliares de consulta do host de memória |
| `plugin-sdk/memory-core-host-secret` | Auxiliares de segredo do host de memória |
| `plugin-sdk/memory-core-host-events` | Auxiliares de journal de eventos do host de memória |
| `plugin-sdk/memory-core-host-status` | Auxiliares de status do host de memória |
| `plugin-sdk/memory-core-host-runtime-cli` | Auxiliares de runtime da CLI do host de memória |
| `plugin-sdk/memory-core-host-runtime-core` | Auxiliares centrais de runtime do host de memória |
| `plugin-sdk/memory-core-host-runtime-files` | Auxiliares de arquivo/runtime do host de memória |
| `plugin-sdk/memory-host-core` | Alias neutro em relação ao fornecedor para os auxiliares centrais de runtime do host de memória |
| `plugin-sdk/memory-host-events` | Alias neutro em relação ao fornecedor para os auxiliares de journal de eventos do host de memória |
| `plugin-sdk/memory-host-files` | Alias neutro em relação ao fornecedor para os auxiliares de arquivo/runtime do host de memória |
| `plugin-sdk/memory-host-markdown` | Auxiliares compartilhados de managed-markdown para plugins adjacentes à memória |
| `plugin-sdk/memory-host-search` | Fachada de runtime de Active Memory para acesso ao gerenciador de busca |
| `plugin-sdk/memory-host-status` | Alias neutro em relação ao fornecedor para os auxiliares de status do host de memória |
| `plugin-sdk/memory-lancedb` | Superfície auxiliar empacotada de memory-lancedb |
</Accordion>
<Accordion title="Subcaminhos reservados de helper empacotado">
<Accordion title="Subcaminhos auxiliares empacotados reservados">
| Família | Subcaminhos atuais | Uso pretendido |
| --- | --- | --- |
| Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Helpers de suporte do plugin Browser empacotado (`browser-support` continua sendo o barrel de compatibilidade) |
| Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Superfície de helper/runtime do Matrix empacotado |
| Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Superfície de helper/runtime do LINE empacotado |
| IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Superfície de helper do IRC empacotado |
| Helpers específicos de canal | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Seams de compatibilidade/helper de canais empacotados |
| Helpers específicos de autenticação/plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Seams de helper de recurso/plugin empacotado; `plugin-sdk/github-copilot-token` atualmente exporta `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` e `resolveCopilotApiToken` |
| Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Auxiliares de suporte do Plugin de navegador empacotado (`browser-support` continua sendo o barrel de compatibilidade) |
| Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Superfície auxiliar/runtime empacotada do Matrix |
| Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Superfície auxiliar/runtime empacotada do LINE |
| IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Superfície auxiliar empacotada do IRC |
| Auxiliares específicos de canal | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Seams de compatibilidade/auxiliares de canais empacotados |
| Auxiliares específicos de autenticação/plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Seams auxiliares de recursos/plugins empacotados; `plugin-sdk/github-copilot-token` atualmente exporta `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` e `resolveCopilotApiToken` |
</Accordion>
</AccordionGroup>
@ -308,58 +308,58 @@ promova explicitamente algum deles como público.
O callback `register(api)` recebe um objeto `OpenClawPluginApi` com estes
métodos:
### Registro de capacidade
### Registro de capacidades
| Método | O que ele registra |
| ------------------------------------------------ | ------------------------------------- |
| `api.registerProvider(...)` | Inferência de texto (LLM) |
| Método | O que ele registra |
| ------------------------------------------------ | ----------------------------------- |
| `api.registerProvider(...)` | Inferência de texto (LLM) |
| `api.registerAgentHarness(...)` | Executor experimental de agente de baixo nível |
| `api.registerCliBackend(...)` | Backend local de inferência por CLI |
| `api.registerChannel(...)` | Canal de mensagens |
| `api.registerSpeechProvider(...)` | Síntese de texto para fala / STT |
| `api.registerCliBackend(...)` | Backend de inferência local da CLI |
| `api.registerChannel(...)` | Canal de mensagens |
| `api.registerSpeechProvider(...)` | Síntese de texto para fala / STT |
| `api.registerRealtimeTranscriptionProvider(...)` | Transcrição em tempo real por streaming |
| `api.registerRealtimeVoiceProvider(...)` | Sessões duplex de voz em tempo real |
| `api.registerMediaUnderstandingProvider(...)` | Análise de imagem/áudio/vídeo |
| `api.registerImageGenerationProvider(...)` | Geração de imagem |
| `api.registerMusicGenerationProvider(...)` | Geração de música |
| `api.registerVideoGenerationProvider(...)` | Geração de vídeo |
| `api.registerWebFetchProvider(...)` | Provedor de busca/coleta da web |
| `api.registerWebSearchProvider(...)` | Busca na web |
| `api.registerRealtimeVoiceProvider(...)` | Sessões de voz duplex em tempo real |
| `api.registerMediaUnderstandingProvider(...)` | Análise de imagem/áudio/vídeo |
| `api.registerImageGenerationProvider(...)` | Geração de imagem |
| `api.registerMusicGenerationProvider(...)` | Geração de música |
| `api.registerVideoGenerationProvider(...)` | Geração de vídeo |
| `api.registerWebFetchProvider(...)` | Provedor de busca/scrape da web |
| `api.registerWebSearchProvider(...)` | Busca na web |
### Ferramentas e comandos
| Método | O que ele registra |
| ------------------------------- | --------------------------------------------- |
| Método | O que ele registra |
| ------------------------------- | -------------------------------------------- |
| `api.registerTool(tool, opts?)` | Ferramenta do agente (obrigatória ou `{ optional: true }`) |
| `api.registerCommand(def)` | Comando personalizado (ignora o LLM) |
| `api.registerCommand(def)` | Comando personalizado (ignora o LLM) |
### Infraestrutura
| Método | O que ele registra |
| ---------------------------------------------- | ------------------------------------- |
| `api.registerHook(events, handler, opts?)` | Hook de evento |
| `api.registerHttpRoute(params)` | Endpoint HTTP do Gateway |
| `api.registerGatewayMethod(name, handler)` | Método RPC do Gateway |
| `api.registerCli(registrar, opts?)` | Subcomando da CLI |
| `api.registerService(service)` | Serviço em segundo plano |
| `api.registerInteractiveHandler(registration)` | Handler interativo |
| Método | O que ele registra |
| ---------------------------------------------- | -------------------------------------- |
| `api.registerHook(events, handler, opts?)` | Hook de evento |
| `api.registerHttpRoute(params)` | Endpoint HTTP do Gateway |
| `api.registerGatewayMethod(name, handler)` | Método RPC do Gateway |
| `api.registerCli(registrar, opts?)` | Subcomando da CLI |
| `api.registerService(service)` | Serviço em segundo plano |
| `api.registerInteractiveHandler(registration)` | Manipulador interativo |
| `api.registerMemoryPromptSupplement(builder)` | Seção de prompt aditiva adjacente à memória |
| `api.registerMemoryCorpusSupplement(adapter)` | Corpus aditivo de busca/leitura de memória |
Namespaces administrativos reservados do core (`config.*`, `exec.approvals.*`, `wizard.*`,
Namespaces administrativos reservados do núcleo (`config.*`, `exec.approvals.*`, `wizard.*`,
`update.*`) sempre permanecem `operator.admin`, mesmo que um plugin tente atribuir um
escopo de método de gateway mais restrito. Prefira prefixos específicos do plugin para
escopo mais restrito ao método do Gateway. Prefira prefixos específicos do plugin para
métodos pertencentes ao plugin.
### Metadados de registro da CLI
`api.registerCli(registrar, opts?)` aceita dois tipos de metadados de nível superior:
- `commands`: raízes explícitas de comando pertencentes ao registrador
- `commands`: raízes de comando explícitas pertencentes ao registrador
- `descriptors`: descritores de comando em tempo de parsing usados para ajuda da CLI raiz,
roteamento e registro lazy da CLI do plugin
Se você quiser que um comando do plugin permaneça com carregamento lazy no caminho normal da CLI raiz,
Se você quiser que um comando de plugin permaneça com carregamento lazy no caminho normal da CLI raiz,
forneça `descriptors` que cubram toda raiz de comando de nível superior exposta por esse
registrador.
@ -373,7 +373,7 @@ api.registerCli(
descriptors: [
{
name: "matrix",
description: "Gerencie contas, verificação, dispositivos e estado de perfil do Matrix",
description: "Gerencie contas do Matrix, verificação, dispositivos e estado do perfil",
hasSubcommands: true,
},
],
@ -382,124 +382,124 @@ api.registerCli(
```
Use `commands` sozinho apenas quando você não precisar de registro lazy na CLI raiz.
Esse caminho de compatibilidade eager continua compatível, mas não instala
placeholders com suporte a descritor para carregamento lazy em tempo de parsing.
Esse caminho de compatibilidade eager continua sendo compatível, mas não instala
placeholders com suporte de descritor para carregamento lazy em tempo de parsing.
### Registro de backend da CLI
`api.registerCliBackend(...)` permite que um plugin seja responsável pela configuração padrão de um backend
local de CLI de IA, como `codex-cli`.
`api.registerCliBackend(...)` permite que um plugin seja o dono da configuração padrão de um
backend local de CLI de IA, como `codex-cli`.
- O `id` do backend se torna o prefixo do provedor em refs de modelo como `codex-cli/gpt-5`.
- O `config` do backend usa o mesmo formato de `agents.defaults.cliBackends.<id>`.
- A configuração do usuário ainda prevalece. O OpenClaw mescla `agents.defaults.cliBackends.<id>` sobre o
- O `id` do backend se torna o prefixo do provedor em referências de modelo como `codex-cli/gpt-5`.
- A `config` do backend usa o mesmo formato de `agents.defaults.cliBackends.<id>`.
- A configuração do usuário continua tendo prioridade. O OpenClaw mescla `agents.defaults.cliBackends.<id>` sobre o
padrão do plugin antes de executar a CLI.
- Use `normalizeConfig` quando um backend precisar de regravações de compatibilidade após a mesclagem
(por exemplo, normalizar formatos antigos de flag).
- Use `normalizeConfig` quando um backend precisar de reescritas de compatibilidade após a mesclagem
(por exemplo, normalizando formatos antigos de flags).
### Slots exclusivos
| Método | O que ele registra |
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `api.registerContextEngine(id, factory)` | Motor de contexto (apenas um ativo por vez). O callback `assemble()` recebe `availableTools` e `citationsMode` para que o motor possa adaptar adições ao prompt. |
| `api.registerMemoryCapability(capability)` | Capacidade unificada de memória |
| `api.registerMemoryPromptSection(builder)` | Builder de seção de prompt de memória |
| `api.registerMemoryFlushPlan(resolver)` | Resolver de plano de flush de memória |
| `api.registerMemoryRuntime(runtime)` | Adapter de runtime de memória |
| `api.registerContextEngine(id, factory)` | Mecanismo de contexto (apenas um ativo por vez). O callback `assemble()` recebe `availableTools` e `citationsMode` para que o mecanismo adapte adições ao prompt. |
| `api.registerMemoryCapability(capability)` | Capacidade de memória unificada |
| `api.registerMemoryPromptSection(builder)` | Construtor de seção de prompt de memória |
| `api.registerMemoryFlushPlan(resolver)` | Resolvedor de plano de flush de memória |
| `api.registerMemoryRuntime(runtime)` | Adaptador de runtime de memória |
### Adapters de embeddings de memória
### Adaptadores de embedding de memória
| Método | O que ele registra |
| ---------------------------------------------- | ---------------------------------------------- |
| `api.registerMemoryEmbeddingProvider(adapter)` | Adapter de embeddings de memória para o plugin ativo |
| Método | O que ele registra |
| ---------------------------------------------- | ------------------------------------------ |
| `api.registerMemoryEmbeddingProvider(adapter)` | Adaptador de embedding de memória para o Plugin ativo |
- `registerMemoryCapability` é a API preferida de plugin de memória exclusiva.
- `registerMemoryCapability` é a API exclusiva preferida para plugin de memória.
- `registerMemoryCapability` também pode expor `publicArtifacts.listArtifacts(...)`
para que plugins complementares consumam artefatos de memória exportados por meio de
`openclaw/plugin-sdk/memory-host-core` em vez de acessar o layout privado de um
plugin de memória específico.
- `registerMemoryPromptSection`, `registerMemoryFlushPlan` e
`registerMemoryRuntime` são APIs exclusivas de plugin de memória compatíveis com o legado.
- `registerMemoryEmbeddingProvider` permite que o plugin de memória ativo registre um
ou mais ids de adapter de embeddings (por exemplo `openai`, `gemini` ou um id
`registerMemoryRuntime` são APIs exclusivas de plugin de memória compatíveis com versões legadas.
- `registerMemoryEmbeddingProvider` permite que o Plugin de memória ativo registre um
ou mais IDs de adaptador de embedding (por exemplo, `openai`, `gemini` ou um ID
personalizado definido pelo plugin).
- A configuração do usuário, como `agents.defaults.memorySearch.provider` e
`agents.defaults.memorySearch.fallback`, é resolvida em relação a esses ids de adapter
registrados.
- Configurações do usuário como `agents.defaults.memorySearch.provider` e
`agents.defaults.memorySearch.fallback` são resolvidas com base nesses IDs de
adaptador registrados.
### Eventos e ciclo de vida
| Método | O que ele faz |
| -------------------------------------------- | --------------------------- |
| `api.on(hookName, handler, opts?)` | Hook tipado de ciclo de vida |
| `api.onConversationBindingResolved(handler)` | Callback de binding de conversa |
| Método | O que ele faz |
| -------------------------------------------- | ----------------------------- |
| `api.on(hookName, handler, opts?)` | Hook tipado de ciclo de vida |
| `api.onConversationBindingResolved(handler)` | Callback de vínculo de conversa |
### Semântica de decisão de hooks
### Semântica de decisão de hook
- `before_tool_call`: retornar `{ block: true }` é terminal. Assim que algum handler definir isso, handlers de prioridade mais baixa são ignorados.
- `before_tool_call`: retornar `{ block: false }` é tratado como nenhuma decisão (o mesmo que omitir `block`), não como uma substituição.
- `before_install`: retornar `{ block: true }` é terminal. Assim que algum handler definir isso, handlers de prioridade mais baixa são ignorados.
- `before_install`: retornar `{ block: false }` é tratado como nenhuma decisão (o mesmo que omitir `block`), não como uma substituição.
- `reply_dispatch`: retornar `{ handled: true, ... }` é terminal. Assim que algum handler assumir o dispatch, handlers de prioridade mais baixa e o caminho padrão de dispatch do modelo são ignorados.
- `message_sending`: retornar `{ cancel: true }` é terminal. Assim que algum handler definir isso, handlers de prioridade mais baixa são ignorados.
- `message_sending`: retornar `{ cancel: false }` é tratado como nenhuma decisão (o mesmo que omitir `cancel`), não como uma substituição.
- `before_tool_call`: retornar `{ block: true }` é terminal. Assim que qualquer manipulador definir isso, manipuladores de menor prioridade serão ignorados.
- `before_tool_call`: retornar `{ block: false }` é tratado como nenhuma decisão (igual a omitir `block`), não como uma substituição.
- `before_install`: retornar `{ block: true }` é terminal. Assim que qualquer manipulador definir isso, manipuladores de menor prioridade serão ignorados.
- `before_install`: retornar `{ block: false }` é tratado como nenhuma decisão (igual a omitir `block`), não como uma substituição.
- `reply_dispatch`: retornar `{ handled: true, ... }` é terminal. Assim que qualquer manipulador assumir o despacho, manipuladores de menor prioridade e o caminho padrão de despacho do modelo serão ignorados.
- `message_sending`: retornar `{ cancel: true }` é terminal. Assim que qualquer manipulador definir isso, manipuladores de menor prioridade serão ignorados.
- `message_sending`: retornar `{ cancel: false }` é tratado como nenhuma decisão (igual a omitir `cancel`), não como uma substituição.
### Campos do objeto API
### Campos do objeto da API
| Campo | Tipo | Descrição |
| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- |
| `api.id` | `string` | Id do plugin |
| `api.name` | `string` | Nome de exibição |
| `api.version` | `string?` | Versão do plugin (opcional) |
| `api.description` | `string?` | Descrição do plugin (opcional) |
| `api.source` | `string` | Caminho de origem do plugin |
| `api.rootDir` | `string?` | Diretório raiz do plugin (opcional) |
| `api.config` | `OpenClawConfig` | Snapshot de configuração atual (snapshot de runtime ativo em memória quando disponível) |
| `api.pluginConfig` | `Record<string, unknown>` | Configuração específica do plugin em `plugins.entries.<id>.config` |
| `api.runtime` | `PluginRuntime` | [Helpers de runtime](/pt-BR/plugins/sdk-runtime) |
| `api.logger` | `PluginLogger` | Logger com escopo (`debug`, `info`, `warn`, `error`) |
| Campo | Tipo | Descrição |
| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------ |
| `api.id` | `string` | ID do plugin |
| `api.name` | `string` | Nome de exibição |
| `api.version` | `string?` | Versão do plugin (opcional) |
| `api.description` | `string?` | Descrição do plugin (opcional) |
| `api.source` | `string` | Caminho de origem do plugin |
| `api.rootDir` | `string?` | Diretório raiz do plugin (opcional) |
| `api.config` | `OpenClawConfig` | Snapshot da configuração atual (snapshot ativo em memória no runtime quando disponível) |
| `api.pluginConfig` | `Record<string, unknown>` | Configuração específica do plugin em `plugins.entries.<id>.config` |
| `api.runtime` | `PluginRuntime` | [Auxiliares de runtime](/pt-BR/plugins/sdk-runtime) |
| `api.logger` | `PluginLogger` | Logger com escopo (`debug`, `info`, `warn`, `error`) |
| `api.registrationMode` | `PluginRegistrationMode` | Modo de carregamento atual; `"setup-runtime"` é a janela leve de inicialização/configuração antes da entrada completa |
| `api.resolvePath(input)` | `(string) => string` | Resolve caminho relativo à raiz do plugin |
| `api.resolvePath(input)` | `(string) => string` | Resolve o caminho em relação à raiz do plugin |
## Convenção de módulo interno
## Convenção de módulos internos
Dentro do seu plugin, use arquivos barrel locais para importações internas:
```
my-plugin/
api.ts # Exportações públicas para consumidores externos
runtime-api.ts # Exportações internas apenas de runtime
runtime-api.ts # Exportações de runtime somente internas
index.ts # Ponto de entrada do plugin
setup-entry.ts # Entrada leve apenas para configuração (opcional)
setup-entry.ts # Entrada leve somente para configuração (opcional)
```
<Warning>
Nunca importe seu próprio plugin por `openclaw/plugin-sdk/<your-plugin>`
a partir de código de produção. Encaminhe importações internas por
`./api.ts` ou `./runtime-api.ts`. O caminho do SDK é apenas o contrato externo.
Nunca importe seu próprio plugin por meio de `openclaw/plugin-sdk/<your-plugin>`
a partir de código de produção. Direcione importações internas por `./api.ts` ou
`./runtime-api.ts`. O caminho do SDK é apenas o contrato externo.
</Warning>
Superfícies públicas de plugins empacotados carregadas por fachada (`api.ts`, `runtime-api.ts`,
`index.ts`, `setup-entry.ts` e arquivos de entrada pública semelhantes) agora preferem o
snapshot ativo de configuração de runtime quando o OpenClaw já está em execução. Se ainda não existir
snapshot de runtime, elas recorrem ao arquivo de configuração resolvido em disco.
`index.ts`, `setup-entry.ts` e arquivos públicos de entrada semelhantes) agora preferem o
snapshot ativo de configuração do runtime quando o OpenClaw já está em execução. Se ainda não existir
um snapshot de runtime, elas recorrem à configuração resolvida no arquivo em disco.
Plugins de provedor também podem expor um barrel de contrato local e estreito ao plugin quando um
helper for intencionalmente específico do provedor e ainda não pertencer a um subcaminho genérico do SDK. Exemplo
empacotado atual: o provedor Anthropic mantém seus helpers de stream Claude em seu próprio
seam público `api.ts` / `contract-api.ts` em vez de promover lógica de cabeçalho beta da Anthropic e
`service_tier` para um contrato genérico `plugin-sdk/*`.
Plugins de provedor também podem expor um barrel de contrato local e restrito ao plugin quando um
auxiliar for intencionalmente específico do provedor e ainda não pertencer a um subcaminho genérico do SDK.
Exemplo empacotado atual: o provedor Anthropic mantém seus auxiliares de stream do Claude em seu próprio
seam público `api.ts` / `contract-api.ts`, em vez de promover a lógica de cabeçalho beta do Anthropic e `service_tier`
para um contrato genérico `plugin-sdk/*`.
Outros exemplos empacotados atuais:
- `@openclaw/openai-provider`: `api.ts` exporta builders de provedor,
helpers de modelo padrão e builders de provedor realtime
- `@openclaw/openrouter-provider`: `api.ts` exporta o builder de provedor mais
helpers de onboarding/configuração
- `@openclaw/openai-provider`: `api.ts` exporta construtores de provedor,
auxiliares de modelo padrão e construtores de provedor em tempo real
- `@openclaw/openrouter-provider`: `api.ts` exporta o construtor do provedor e
auxiliares de onboarding/configuração
<Warning>
O código de produção de extensões também deve evitar importações de `openclaw/plugin-sdk/<other-plugin>`.
Se um helper for realmente compartilhado, promova-o para um subcaminho neutro do SDK,
Se um auxiliar for realmente compartilhado, promova-o a um subcaminho neutro do SDK,
como `openclaw/plugin-sdk/speech`, `.../provider-model-shared` ou outra
superfície orientada por capacidade, em vez de acoplar dois plugins.
</Warning>
@ -507,8 +507,8 @@ Outros exemplos empacotados atuais:
## Relacionado
- [Pontos de entrada](/pt-BR/plugins/sdk-entrypoints) — opções de `definePluginEntry` e `defineChannelPluginEntry`
- [Helpers de runtime](/pt-BR/plugins/sdk-runtime) — referência completa do namespace `api.runtime`
- [Configuração e setup](/pt-BR/plugins/sdk-setup) — empacotamento, manifests, schemas de configuração
- [Testing](/pt-BR/plugins/sdk-testing) — utilitários de teste e regras de lint
- [Auxiliares de runtime](/pt-BR/plugins/sdk-runtime) — referência completa do namespace `api.runtime`
- [Configuração e setup](/pt-BR/plugins/sdk-setup) — empacotamento, manifests, esquemas de configuração
- [Testes](/pt-BR/plugins/sdk-testing) — utilitários de teste e regras de lint
- [Migração do SDK](/pt-BR/plugins/sdk-migration) — migração de superfícies descontinuadas
- [Internals de plugins](/pt-BR/plugins/architecture) — arquitetura profunda e modelo de capacidade
- [Internals de plugin](/pt-BR/plugins/architecture) — arquitetura detalhada e modelo de capacidade

111
docs/pt-BR/tools/thinking.md
View File

@ -1,60 +1,62 @@
---
read_when:
- Ajustando a análise ou os padrões das diretivas de thinking, modo rápido ou verbose
- Ajuste da análise, do modo rápido ou da análise detalhada na interpretação de diretivas ou nos padrões definidos
summary: Sintaxe de diretivas para /think, /fast, /verbose, /trace e visibilidade do raciocínio
title: Níveis de raciocínio
title: Níveis de reflexão
x-i18n:
generated_at: "2026-04-12T23:33:33Z"
generated_at: "2026-04-17T05:36:05Z"
model: gpt-5.4
provider: openai
source_hash: 4f3b1341281f07ba4e9061e3355845dca234be04cc0d358594312beeb7676e68
source_hash: 1cb44a7bf75546e5a8c3204e12f3297221449b881161d173dea4983da3921649
source_path: tools/thinking.md
workflow: 15
---
# Níveis de raciocínio (diretivas /think)
# Níveis de reflexão (diretivas /think)
## O que faz
- Diretiva inline em qualquer corpo de mensagem recebida: `/t <level>`, `/think:<level>` ou `/thinking <level>`.
- Diretiva inline em qualquer corpo de mensagem recebido: `/t <level>`, `/think:<level>` ou `/thinking <level>`.
- Níveis (aliases): `off | minimal | low | medium | high | xhigh | adaptive`
- minimal → “think”
- low → “think hard”
- medium → “think harder”
- minimal → “pensar”
- low → “pensar bastante”
- medium → “pensar ainda mais”
- high → “ultrathink” (orçamento máximo)
- xhigh → “ultrathink+” (somente modelos GPT-5.2 + Codex)
- adaptive → orçamento de raciocínio adaptativo gerenciado pelo provedor (compatível com a família de modelos Anthropic Claude 4.6)
- xhigh → “ultrathink+” (esforço GPT-5.2 + modelos Codex e Anthropic Claude Opus 4.7)
- adaptive → reflexão adaptativa gerenciada pelo provedor (compatível com Anthropic Claude 4.6 e Opus 4.7)
- `x-high`, `x_high`, `extra-high`, `extra high` e `extra_high` são mapeados para `xhigh`.
- `highest`, `max` são mapeados para `high`.
- Observações por provedor:
- Os modelos Anthropic Claude 4.6 usam `adaptive` por padrão quando nenhum nível explícito de raciocínio é definido.
- MiniMax (`minimax/*`) no caminho de streaming compatível com Anthropic usa por padrão `thinking: { type: "disabled" }`, a menos que você defina explicitamente o raciocínio nos params do modelo ou nos params da solicitação. Isso evita vazamento de deltas `reasoning_content` do formato de stream Anthropic não nativo do MiniMax.
- Z.AI (`zai/*`) oferece suporte apenas a raciocínio binário (`on`/`off`). Qualquer nível diferente de `off` é tratado como `on` (mapeado para `low`).
- Moonshot (`moonshot/*`) mapeia `/think off` para `thinking: { type: "disabled" }` e qualquer nível diferente de `off` para `thinking: { type: "enabled" }`. Quando o raciocínio está ativado, o Moonshot aceita apenas `tool_choice` `auto|none`; o OpenClaw normaliza valores incompatíveis para `auto`.
- Modelos Anthropic Claude 4.6 usam `adaptive` por padrão quando nenhum nível de reflexão explícito é definido.
- Anthropic Claude Opus 4.7 não usa reflexão adaptativa por padrão. O padrão de esforço da API continua sendo definido pelo provedor, a menos que você defina explicitamente um nível de reflexão.
- Anthropic Claude Opus 4.7 mapeia `/think xhigh` para reflexão adaptativa mais `output_config.effort: "xhigh"`, porque `/think` é uma diretiva de reflexão e `xhigh` é a configuração de esforço do Opus 4.7.
- MiniMax (`minimax/*`) no caminho de streaming compatível com Anthropic usa `thinking: { type: "disabled" }` por padrão, a menos que você defina explicitamente a reflexão em parâmetros do modelo ou da requisição. Isso evita vazamento de deltas `reasoning_content` do formato de stream Anthropic não nativo do MiniMax.
- Z.AI (`zai/*`) oferece suporte apenas a reflexão binária (`on`/`off`). Qualquer nível diferente de `off` é tratado como `on` (mapeado para `low`).
- Moonshot (`moonshot/*`) mapeia `/think off` para `thinking: { type: "disabled" }` e qualquer nível diferente de `off` para `thinking: { type: "enabled" }`. Quando a reflexão está habilitada, o Moonshot aceita apenas `tool_choice` `auto|none`; o OpenClaw normaliza valores incompatíveis para `auto`.
## Ordem de resolução
1. Diretiva inline na mensagem (aplica-se somente a essa mensagem).
1. Diretiva inline na mensagem (aplica-se apenas àquela mensagem).
2. Substituição da sessão (definida ao enviar uma mensagem contendo apenas a diretiva).
3. Padrão por agente (`agents.list[].thinkingDefault` na configuração).
4. Padrão global (`agents.defaults.thinkingDefault` na configuração).
5. Fallback: `adaptive` para modelos Anthropic Claude 4.6, `low` para outros modelos compatíveis com raciocínio, `off` caso contrário.
5. Fallback: `adaptive` para modelos Anthropic Claude 4.6, `off` para Anthropic Claude Opus 4.7, a menos que explicitamente configurado, `low` para outros modelos com capacidade de raciocínio e `off` caso contrário.
## Definindo um padrão da sessão
## Definindo um padrão de sessão
- Envie uma mensagem que seja **somente** a diretiva (espaços em branco permitidos), por exemplo `/think:medium` ou `/t high`.
- Isso permanece na sessão atual (por padrão, por remetente); é limpo por `/think:off` ou por reset por inatividade da sessão.
- Uma resposta de confirmação é enviada (`Nível de raciocínio definido como high.` / `Raciocínio desativado.`). Se o nível for inválido (por exemplo, `/thinking big`), o comando é rejeitado com uma dica e o estado da sessão permanece inalterado.
- Envie `/think` (ou `/think:`) sem argumento para ver o nível atual de raciocínio.
- Envie uma mensagem que seja **apenas** a diretiva (espaços em branco são permitidos), por exemplo `/think:medium` ou `/t high`.
- Isso permanece na sessão atual (por remetente, por padrão); é limpo por `/think:off` ou pela redefinição por inatividade da sessão.
- Uma resposta de confirmação é enviada (`Thinking level set to high.` / `Thinking disabled.`). Se o nível for inválido (por exemplo `/thinking big`), o comando é rejeitado com uma dica e o estado da sessão permanece inalterado.
- Envie `/think` (ou `/think:`) sem argumento para ver o nível de reflexão atual.
## Aplicação por agente
- **Embedded Pi**: o nível resolvido é passado para o runtime do agente Pi em processo.
- **Pi incorporado**: o nível resolvido é passado para o runtime do agente Pi em processo.
## Modo rápido (/fast)
- Níveis: `on|off`.
- Uma mensagem contendo apenas a diretiva alterna uma substituição de modo rápido da sessão e responde `Modo rápido ativado.` / `Modo rápido desativado.`.
- Uma mensagem contendo apenas a diretiva alterna uma substituição do modo rápido na sessão e responde com `Fast mode enabled.` / `Fast mode disabled.`.
- Envie `/fast` (ou `/fast status`) sem modo para ver o estado efetivo atual do modo rápido.
- O OpenClaw resolve o modo rápido nesta ordem:
1. `/fast on|off` inline/somente diretiva
@ -62,41 +64,41 @@ x-i18n:
3. Padrão por agente (`agents.list[].fastModeDefault`)
4. Configuração por modelo: `agents.defaults.models["<provider>/<model>"].params.fastMode`
5. Fallback: `off`
- Para `openai/*`, o modo rápido é mapeado para processamento prioritário da OpenAI, enviando `service_tier=priority` em solicitações Responses compatíveis.
- Para `openai-codex/*`, o modo rápido envia o mesmo sinalizador `service_tier=priority` em Responses do Codex. O OpenClaw mantém uma única alternância compartilhada `/fast` para ambos os caminhos de auth.
- Para solicitações públicas diretas `anthropic/*`, incluindo tráfego autenticado por OAuth enviado para `api.anthropic.com`, o modo rápido é mapeado para service tiers da Anthropic: `/fast on` define `service_tier=auto`, `/fast off` define `service_tier=standard_only`.
- Para `openai/*`, o modo rápido é mapeado para processamento prioritário da OpenAI, enviando `service_tier=priority` em requisições Responses compatíveis.
- Para `openai-codex/*`, o modo rápido envia a mesma flag `service_tier=priority` em Codex Responses. O OpenClaw mantém um único alternador `/fast` compartilhado entre ambos os caminhos de autenticação.
- Para requisições diretas públicas `anthropic/*`, incluindo tráfego autenticado via OAuth enviado para `api.anthropic.com`, o modo rápido é mapeado para níveis de serviço da Anthropic: `/fast on` define `service_tier=auto`, `/fast off` define `service_tier=standard_only`.
- Para `minimax/*` no caminho compatível com Anthropic, `/fast on` (ou `params.fastMode: true`) reescreve `MiniMax-M2.7` para `MiniMax-M2.7-highspeed`.
- Params explícitos de modelo Anthropic `serviceTier` / `service_tier` substituem o padrão do modo rápido quando ambos estão definidos. O OpenClaw ainda ignora a injeção de service tier da Anthropic para base URLs proxy não Anthropic.
- Parâmetros explícitos de modelo Anthropic `serviceTier` / `service_tier` substituem o padrão do modo rápido quando ambos são definidos. O OpenClaw ainda ignora a injeção de nível de serviço da Anthropic para URLs base de proxy que não sejam Anthropic.
## Diretivas verbose (/verbose ou /v)
## Diretivas detalhadas (/verbose ou /v)
- Níveis: `on` (mínimo) | `full` | `off` (padrão).
- Uma mensagem contendo apenas a diretiva alterna o verbose da sessão e responde `Verbose logging ativado.` / `Verbose logging desativado.`; níveis inválidos retornam uma dica sem alterar o estado.
- `/verbose off` armazena uma substituição explícita da sessão; limpe-a pela UI de Sessions escolhendo `inherit`.
- A diretiva inline afeta somente aquela mensagem; os padrões de sessão/globais se aplicam nos demais casos.
- Envie `/verbose` (ou `/verbose:`) sem argumento para ver o nível verbose atual.
- Quando verbose está ativado, agentes que emitem resultados estruturados de ferramentas (Pi, outros agentes JSON) enviam cada chamada de ferramenta de volta como sua própria mensagem somente de metadados, com prefixo `<emoji> <tool-name>: <arg>` quando disponível (caminho/comando). Esses resumos de ferramenta são enviados assim que cada ferramenta começa (bolhas separadas), não como deltas de streaming.
- Resumos de falha de ferramenta continuam visíveis no modo normal, mas sufixos brutos com detalhes de erro ficam ocultos, a menos que verbose esteja `on` ou `full`.
- Quando verbose está `full`, as saídas das ferramentas também são encaminhadas após a conclusão (bolha separada, truncada para um tamanho seguro). Se você alternar `/verbose on|full|off` enquanto uma execução estiver em andamento, as bolhas de ferramenta subsequentes respeitarão a nova configuração.
- Uma mensagem contendo apenas a diretiva alterna o modo detalhado da sessão e responde com `Verbose logging enabled.` / `Verbose logging disabled.`; níveis inválidos retornam uma dica sem alterar o estado.
- `/verbose off` armazena uma substituição explícita da sessão; limpe-a pela interface de Sessões escolhendo `inherit`.
- A diretiva inline afeta apenas aquela mensagem; os padrões de sessão/globais se aplicam caso contrário.
- Envie `/verbose` (ou `/verbose:`) sem argumento para ver o nível detalhado atual.
- Quando o modo detalhado está ativado, agentes que emitem resultados estruturados de ferramentas (Pi, outros agentes JSON) enviam cada chamada de ferramenta de volta como sua própria mensagem somente de metadados, com o prefixo `<emoji> <tool-name>: <arg>` quando disponível (caminho/comando). Esses resumos de ferramenta são enviados assim que cada ferramenta começa (em bolhas separadas), não como deltas de streaming.
- Resumos de falha de ferramenta permanecem visíveis no modo normal, mas sufixos brutos com detalhes de erro ficam ocultos, a menos que o modo detalhado esteja em `on` ou `full`.
- Quando o modo detalhado está em `full`, as saídas das ferramentas também são encaminhadas após a conclusão (em bolha separada, truncadas para um tamanho seguro). Se você alternar `/verbose on|full|off` enquanto uma execução estiver em andamento, as bolhas de ferramenta subsequentes respeitarão a nova configuração.
## Diretivas de trace do Plugin (/trace)
## Diretivas de rastreamento de Plugin (/trace)
- Níveis: `on` | `off` (padrão).
- Uma mensagem contendo apenas a diretiva alterna a saída de trace de Plugin da sessão e responde `Trace de Plugin ativado.` / `Trace de Plugin desativado.`.
- A diretiva inline afeta somente aquela mensagem; os padrões de sessão/globais se aplicam nos demais casos.
- Envie `/trace` (ou `/trace:`) sem argumento para ver o nível atual de trace.
- `/trace` é mais restrito que `/verbose`: ele expõe apenas linhas de trace/debug pertencentes ao plugin, como resumos de depuração de Active Memory.
- Linhas de trace podem aparecer em `/status` e como uma mensagem diagnóstica de acompanhamento após a resposta normal do assistente.
- Uma mensagem contendo apenas a diretiva alterna a saída de rastreamento de Plugin da sessão e responde com `Plugin trace enabled.` / `Plugin trace disabled.`.
- A diretiva inline afeta apenas aquela mensagem; os padrões de sessão/globais se aplicam caso contrário.
- Envie `/trace` (ou `/trace:`) sem argumento para ver o nível de rastreamento atual.
- `/trace` é mais restrito que `/verbose`: ele expõe apenas linhas de rastreamento/depuração pertencentes ao Plugin, como resumos de depuração do Active Memory.
- Linhas de rastreamento podem aparecer em `/status` e como uma mensagem de diagnóstico de acompanhamento após a resposta normal do assistente.
## Visibilidade do raciocínio (/reasoning)
- Níveis: `on|off|stream`.
- Uma mensagem contendo apenas a diretiva alterna se blocos de raciocínio são mostrados nas respostas.
- Quando ativado, o raciocínio é enviado como uma **mensagem separada** com o prefixo `Reasoning:`.
- `stream` (somente Telegram): faz streaming do raciocínio na bolha de rascunho do Telegram enquanto a resposta é gerada e depois envia a resposta final sem raciocínio.
- Uma mensagem contendo apenas a diretiva alterna se blocos de reflexão são exibidos nas respostas.
- Quando habilitado, o raciocínio é enviado como uma **mensagem separada** com o prefixo `Reasoning:`.
- `stream` (somente Telegram): transmite o raciocínio na bolha de rascunho do Telegram enquanto a resposta é gerada e, em seguida, envia a resposta final sem o raciocínio.
- Alias: `/reason`.
- Envie `/reasoning` (ou `/reasoning:`) sem argumento para ver o nível atual de raciocínio.
- Ordem de resolução: diretiva inline, depois substituição da sessão, depois padrão por agente (`agents.list[].reasoningDefault`), depois fallback (`off`).
- Ordem de resolução: diretiva inline, depois substituição da sessão, depois padrão por agente (`agents.list[].reasoningDefault`) e, por fim, fallback (`off`).
## Relacionado
@ -104,15 +106,16 @@ x-i18n:
## Heartbeats
- O corpo da sonda de Heartbeat é o prompt de heartbeat configurado (padrão: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Diretivas inline em uma mensagem de heartbeat se aplicam normalmente (mas evite alterar padrões de sessão a partir de heartbeats).
- A entrega de Heartbeat usa por padrão apenas o payload final. Para também enviar a mensagem separada `Reasoning:` (quando disponível), defina `agents.defaults.heartbeat.includeReasoning: true` ou por agente `agents.list[].heartbeat.includeReasoning: true`.
- O corpo da sondagem de Heartbeat é o prompt de heartbeat configurado (padrão: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Diretivas inline em uma mensagem de heartbeat se aplicam normalmente (mas evite alterar padrões de sessão a partir de heartbeats).
- A entrega de Heartbeat usa apenas a carga final por padrão. Para também enviar a mensagem separada `Reasoning:` (quando disponível), defina `agents.defaults.heartbeat.includeReasoning: true` ou `agents.list[].heartbeat.includeReasoning: true` por agente.
## Web chat UI
## Interface web de chat
- O seletor de raciocínio do chat web espelha o nível armazenado da sessão a partir do armazenamento/configuração de sessão de entrada quando a página é carregada.
- Escolher outro nível grava imediatamente a substituição da sessão via `sessions.patch`; não espera o próximo envio e não é uma substituição única `thinkingOnce`.
- A primeira opção é sempre `Default (<resolved level>)`, em que o padrão resolvido vem do modelo ativo da sessão: `adaptive` para Claude 4.6 em Anthropic/Bedrock, `low` para outros modelos compatíveis com raciocínio, `off` caso contrário.
- O seletor permanece sensível ao provedor:
- O seletor de reflexão do chat na web espelha o nível armazenado da sessão a partir do armazenamento/configuração de sessão de entrada quando a página é carregada.
- Escolher outro nível grava imediatamente a substituição da sessão via `sessions.patch`; não espera o próximo envio e não é uma substituição `thinkingOnce` de uso único.
- A primeira opção é sempre `Default (<resolved level>)`, em que o padrão resolvido vem do modelo ativo da sessão: `adaptive` para Claude 4.6 na Anthropic, `off` para Anthropic Claude Opus 4.7, a menos que configurado, `low` para outros modelos com capacidade de raciocínio e `off` caso contrário.
- O seletor permanece ciente do provedor:
- a maioria dos provedores mostra `off | minimal | low | medium | high | adaptive`
- Anthropic Claude Opus 4.7 mostra `off | minimal | low | medium | high | xhigh | adaptive`
- Z.AI mostra `off | on` binário
- `/think:<level>` ainda funciona e atualiza o mesmo nível armazenado da sessão, então as diretivas do chat e o seletor permanecem sincronizados.
- `/think:<level>` continua funcionando e atualiza o mesmo nível armazenado da sessão, para que as diretivas do chat e o seletor permaneçam sincronizados.