Internos do Plugin

Esta é a referência de arquitetura profunda para o sistema de plugins do OpenClaw. Para guias práticos, comece com uma das páginas focadas abaixo.

Modelo público de capacidades

Capacidades são o modelo público de plugin nativo dentro do OpenClaw. Todo plugin nativo do OpenClaw se registra em um ou mais tipos de capacidade:

Postura de compatibilidade externa

O modelo de capacidades já está implementado no core e é usado por plugins empacotados/nativos hoje, mas a compatibilidade de plugins externos ainda precisa de um critério mais rigoroso do que "está exportado, portanto está congelado".

O registro de capacidades é a direção pretendida. Hooks legados continuam sendo o caminho mais seguro sem quebras para plugins externos durante a transição. Subcaminhos auxiliares exportados não são todos iguais — prefira contratos estreitos e documentados em vez de exports auxiliares incidentais.

Formatos de plugin

O OpenClaw classifica todo plugin carregado em um formato com base em seu comportamento real de registro (não apenas em metadados estáticos):

Use openclaw plugins inspect <id> para ver o formato e a decomposição de capacidades de um plugin. Consulte a referência da CLI para detalhes.

Hooks legados

O hook before_agent_start continua compatível como um caminho de compatibilidade para plugins somente de hooks. Plugins legados reais ainda dependem dele.

Direção:

• mantê-lo funcionando
• documentá-lo como legado
• preferir before_model_resolve para trabalho de substituição de modelo/provedor
• preferir before_prompt_build para trabalho de mutação de prompt
• remover somente depois que o uso real cair e a cobertura de fixtures provar a segurança da migração

Sinais de compatibilidade

Ao executar openclaw doctor ou openclaw plugins inspect <id>, você pode ver um destes rótulos:

Nem hook-only nem before_agent_start quebrarão seu plugin hoje: hook-only é consultivo, e before_agent_start apenas aciona um aviso. Esses sinais também aparecem em openclaw status --all e openclaw plugins doctor.

Visão geral da arquitetura

O sistema de plugins do OpenClaw tem quatro camadas:

Especificamente para a CLI de plugins, a descoberta de comandos raiz é dividida em duas fases:

• metadados em tempo de análise vêm de registerCli(..., { descriptors: [...] })
• o módulo real da CLI do plugin pode permanecer lazy e registrar no primeiro uso

Isso mantém o código CLI pertencente ao plugin dentro do plugin, ao mesmo tempo em que ainda permite ao OpenClaw reservar nomes de comandos raiz antes da análise.

O limite de design importante:

• a validação de manifesto/configuração deve funcionar a partir de metadados de manifesto/schema sem executar código do plugin
• a descoberta de capacidades nativas pode carregar código de entrada de plugin confiável para construir um snapshot de registro sem ativação
• o comportamento nativo em runtime vem do caminho register(api) do módulo do plugin com api.registrationMode === "full"

Essa separação permite que o OpenClaw valide configuração, explique plugins ausentes/desabilitados e construa dicas de UI/schema antes que o runtime completo esteja ativo.

Snapshot de metadados de plugin e tabela de lookup

A inicialização do Gateway constrói um PluginMetadataSnapshot para o snapshot de configuração atual. O snapshot contém apenas metadados: ele armazena o índice de plugins instalados, registro de manifestos, diagnósticos de manifesto, mapas de proprietários, um normalizador de id de plugin e registros de manifesto. Ele não contém módulos de plugin carregados, SDKs de provedores, conteúdo de pacotes ou exports de runtime.

A validação de configuração ciente de plugins, a habilitação automática na inicialização e o bootstrap de plugins do Gateway consomem esse snapshot em vez de reconstruírem metadados de manifesto/índice independentemente. PluginLookUpTable é derivada do mesmo snapshot e adiciona o plano de plugins de inicialização para a configuração de runtime atual.

Após a inicialização, o Gateway mantém o snapshot de metadados atual como um produto de runtime substituível. Descobertas repetidas de provedores em runtime podem aproveitar esse snapshot em vez de reconstruir o índice instalado e o registro de manifestos para cada passagem do catálogo de provedores. O snapshot é limpo ou substituído no encerramento do Gateway, em mudanças de configuração/inventário de plugins e em gravações do índice instalado; chamadores recorrem ao caminho frio de manifesto/índice quando não existe um snapshot atual compatível. As verificações de compatibilidade devem incluir raízes de descoberta de plugins, como plugins.load.paths e o workspace padrão do agente, porque plugins de workspace fazem parte do escopo dos metadados.

O snapshot e a tabela de lookup mantêm decisões repetidas de inicialização no caminho rápido:

• propriedade de canal
• inicialização adiada de canal
• ids de plugins de inicialização
• propriedade de provedor e backend CLI
• propriedade de provedor de configuração, alias de comando, provedor de catálogo de modelos e contrato de manifesto
• validação de schema de configuração de plugin e schema de configuração de canal
• decisões de habilitação automática na inicialização

O limite de segurança é a substituição do snapshot, não a mutação. Reconstrua o snapshot quando configuração, inventário de plugins, registros de instalação ou política de índice persistido mudarem. Não o trate como um registro global mutável amplo e não mantenha snapshots históricos sem limite. O carregamento de plugins em runtime permanece separado de snapshots de metadados, para que estado de runtime obsoleto não possa ficar oculto atrás de um cache de metadados.

A regra de cache está documentada em Internos da arquitetura de plugins: metadados de manifesto e descoberta são frescos, a menos que um chamador mantenha um snapshot explícito, tabela de lookup ou registro de manifestos para o fluxo atual. Caches de metadados ocultos e TTLs baseados em relógio não fazem parte do carregamento de plugins. Somente caches de carregador de runtime, módulo e artefato de dependência podem persistir depois que código ou artefatos instalados são realmente carregados.

Alguns chamadores de caminho frio ainda reconstroem registros de manifesto diretamente a partir do índice persistido de plugins instalados, em vez de receber uma PluginLookUpTable do Gateway. Esse caminho agora reconstrói o registro sob demanda; prefira passar a tabela de lookup atual ou um registro de manifestos explícito pelos fluxos de runtime quando um chamador já tiver um.

Planejamento de ativação

O planejamento de ativação faz parte do plano de controle. Chamadores podem perguntar quais plugins são relevantes para um comando, provedor, canal, rota, harness de agente ou capacidade concreta antes de carregar registros de runtime mais amplos.

O planejador mantém o comportamento atual de manifesto compatível:

• Os campos activation.* são dicas explícitas para o planejador
• providers, channels, commandAliases, setup.providers, contracts.tools e hooks continuam sendo o fallback de propriedade do manifesto
• a API do planejador somente com ids continua disponível para chamadores existentes
• a API de plano relata rótulos de motivo para que diagnósticos possam distinguir dicas explícitas do fallback de propriedade

Plugins de canal e a ferramenta de mensagem compartilhada

Plugins de canal não precisam registrar uma ferramenta separada de envio/edição/reação para ações normais de chat. O OpenClaw mantém uma única ferramenta message compartilhada no core, e os plugins de canal são responsáveis pela descoberta e execução específicas do canal por trás dela.

O limite atual é:

• o core é responsável pelo host da ferramenta message compartilhada, pela conexão com o prompt, pela contabilidade de sessão/thread e pelo dispatch de execução
• plugins de canal são responsáveis pela descoberta de ações com escopo, pela descoberta de capacidades e por quaisquer fragmentos de schema específicos do canal
• plugins de canal são responsáveis pela gramática de conversas de sessão específica do provedor, como a forma como ids de conversa codificam ids de thread ou herdam de conversas pai
• plugins de canal executam a ação final por meio de seu adaptador de ações

Para plugins de canal, a superfície do SDK é ChannelMessageActionAdapter.describeMessageTool(...). Essa chamada de descoberta unificada permite que um plugin retorne suas ações visíveis, capacidades e contribuições de schema em conjunto, para que essas partes não se desalinhem.

Quando um parâmetro da ferramenta de mensagem específico do canal carrega uma fonte de mídia, como um caminho local ou URL de mídia remota, o plugin também deve retornar mediaSourceParams de describeMessageTool(...). O core usa essa lista explícita para aplicar normalização de caminho de sandbox e dicas de acesso a mídia de saída sem hardcodar nomes de parâmetros pertencentes ao plugin. Prefira mapas com escopo de ação ali, não uma lista plana para o canal inteiro, para que um parâmetro de mídia somente de perfil não seja normalizado em ações não relacionadas, como send.

O core passa o escopo de runtime para essa etapa de descoberta. Campos importantes incluem:

• accountId
• currentChannelId
• currentThreadTs
• currentMessageId
• sessionKey
• sessionId
• agentId
• requesterSenderId de entrada confiável

Isso importa para plugins sensíveis a contexto. Um canal pode ocultar ou expor ações de mensagem com base na conta ativa, na sala/thread/mensagem atual ou na identidade confiável do solicitante sem hardcodar ramificações específicas do canal na ferramenta message do core.

É por isso que mudanças de roteamento do runner embutido ainda são trabalho de plugin: o runner é responsável por encaminhar a identidade atual de chat/sessão para o limite de descoberta do plugin, para que a ferramenta message compartilhada exponha a superfície correta pertencente ao canal para o turno atual.

Para auxiliares de execução pertencentes ao canal, plugins agrupados devem manter o runtime de execução dentro de seus próprios módulos de extensão. O core não é mais responsável pelos runtimes de ações de mensagem do Discord, Slack, Telegram ou WhatsApp em src/agents/tools. Não publicamos subcaminhos separados plugin-sdk/*-action-runtime, e plugins agrupados devem importar seu próprio código de runtime local diretamente de seus módulos pertencentes à extensão.

O mesmo limite se aplica a interfaces do SDK nomeadas por provedor em geral: o core não deve importar barrels de conveniência específicos de canal para Slack, Discord, Signal, WhatsApp ou extensões semelhantes. Se o core precisar de um comportamento, consuma o próprio barrel api.ts / runtime-api.ts do plugin agrupado ou promova a necessidade para uma capacidade genérica estreita no SDK compartilhado.

Plugins agrupados seguem a mesma regra. O runtime-api.ts de um plugin agrupado não deve reexportar sua própria fachada de marca openclaw/plugin-sdk/<plugin-id>. Essas fachadas de marca continuam sendo shims de compatibilidade para plugins externos e consumidores mais antigos, mas plugins agrupados devem usar exportações locais mais subcaminhos genéricos estreitos do SDK, como openclaw/plugin-sdk/channel-policy, openclaw/plugin-sdk/runtime-store ou openclaw/plugin-sdk/webhook-ingress. Código novo não deve adicionar fachadas do SDK específicas de plugin-id, a menos que o limite de compatibilidade para um ecossistema externo existente exija isso.

Para enquetes especificamente, há dois caminhos de execução:

• outbound.sendPoll é a base compartilhada para canais que se encaixam no modelo comum de enquete
• actions.handleAction("poll") é o caminho preferido para semântica de enquete específica do canal ou parâmetros extras de enquete

O core agora adia o parsing compartilhado de enquetes até depois que o dispatch de enquete do plugin recusa a ação, para que handlers de enquete pertencentes ao plugin possam aceitar campos de enquete específicos do canal sem serem bloqueados primeiro pelo parser genérico de enquetes.

Veja internos da arquitetura de Plugin para a sequência completa de inicialização.

Modelo de propriedade de capacidade

O OpenClaw trata um Plugin nativo como o limite de propriedade para uma empresa ou um recurso, não como um conjunto avulso de integrações sem relação.

Isso significa:

• um Plugin de empresa normalmente deve ser responsável por todas as superfícies dessa empresa voltadas para o OpenClaw
• um Plugin de recurso normalmente deve ser responsável por toda a superfície do recurso que ele introduz
• canais devem consumir capacidades compartilhadas do core em vez de reimplementar comportamento de provedor ad hoc

O estado final pretendido é:

• OpenAI fica em um único Plugin, mesmo que abranja modelos de texto, fala, imagens e vídeo futuro
• outro fornecedor pode fazer o mesmo para sua própria área de superfície
• canais não se importam com qual Plugin de fornecedor possui o provedor; eles consomem o contrato de capacidade compartilhado exposto pelo core

Esta é a distinção principal:

• Plugin = limite de propriedade
• capacidade = contrato do core que vários plugins podem implementar ou consumir

Então, se o OpenClaw adicionar um novo domínio, como vídeo, a primeira pergunta não é "qual provedor deve hardcodar o tratamento de vídeo?" A primeira pergunta é "qual é o contrato de capacidade de vídeo do core?" Depois que esse contrato existe, plugins de fornecedores podem se registrar nele e plugins de canal/recurso podem consumi-lo.

Se a capacidade ainda não existir, o movimento certo geralmente é:

Isso mantém a propriedade explícita enquanto evita comportamento do core que dependa de um único fornecedor ou de um caminho de código específico de plugin pontual.

Camadas de capacidade

Use este modelo mental ao decidir onde o código pertence:

Por exemplo, TTS segue este formato:

• o core é responsável pela política de TTS no momento da resposta, ordem de fallback, preferências e entrega por canal
• openai, elevenlabs e microsoft são responsáveis por implementações de síntese
• voice-call consome o auxiliar de runtime de TTS de telefonia

Esse mesmo padrão deve ser preferido para capacidades futuras.

Exemplo de Plugin de empresa com várias capacidades

Um Plugin de empresa deve parecer coeso visto de fora. Se o OpenClaw tiver contratos compartilhados para modelos, fala, transcrição em tempo real, voz em tempo real, compreensão de mídia, geração de imagens, geração de vídeo, busca de web e pesquisa na web, um fornecedor pode possuir todas as suas superfícies em um só lugar:

    describeImageWithModel,  transcribeOpenAiCompatibleAudio,} from "openclaw/plugin-sdk/media-understanding"; const plugin: OpenClawPluginDefinition = {  id: "exampleai",  name: "ExampleAI",  register(api) {    api.registerProvider({      id: "exampleai",      // auth/model catalog/runtime hooks    });     api.registerSpeechProvider({      id: "exampleai",      // vendor speech config — implement the SpeechProviderPlugin interface directly    });     api.registerMediaUnderstandingProvider({      id: "exampleai",      capabilities: ["image", "audio", "video"],      async describeImage(req) {        return describeImageWithModel({          provider: "exampleai",          model: req.model,          input: req.input,        });      },      async transcribeAudio(req) {        return transcribeOpenAiCompatibleAudio({          provider: "exampleai",          model: req.model,          input: req.input,        });      },    });     api.registerWebSearchProvider(      createPluginBackedWebSearchProvider({        id: "exampleai-search",        // credential + fetch logic      }),    );  },}; export default plugin;

O que importa não são os nomes exatos dos auxiliares. O formato importa:

• um Plugin é responsável pela superfície do fornecedor
• o core ainda é responsável pelos contratos de capacidade
• canais e plugins de recurso consomem auxiliares api.runtime.*, não código do fornecedor
• testes de contrato podem afirmar que o Plugin registrou as capacidades que declara possuir

Exemplo de capacidade: compreensão de vídeo

O OpenClaw já trata compreensão de imagem/áudio/vídeo como uma capacidade compartilhada. O mesmo modelo de propriedade se aplica ali:

Isso evita incorporar as suposições de vídeo de um provedor no core. O plugin é responsável pela superfície do fornecedor; o core é responsável pelo contrato de capacidade e pelo comportamento de fallback.

Geração de vídeo já usa essa mesma sequência: o core é responsável pelo contrato de capacidade tipado e pelo auxiliar de runtime, e plugins de fornecedores registram implementações api.registerVideoGenerationProvider(...) nele.

Precisa de uma checklist concreta de rollout? Veja Capability Cookbook.

Contratos e aplicação

A superfície da API de plugin é intencionalmente tipada e centralizada em OpenClawPluginApi. Esse contrato define os pontos de registro compatíveis e os auxiliares de runtime nos quais um plugin pode confiar.

Por que isso importa:

• autores de plugin têm um padrão interno estável único
• o core pode rejeitar propriedade duplicada, como dois plugins registrando o mesmo id de provedor
• a inicialização pode exibir diagnósticos acionáveis para registro malformado
• testes de contrato podem aplicar a propriedade de plugins agrupados e impedir desvio silencioso

Há duas camadas de aplicação:

O efeito prático é que o OpenClaw sabe, de antemão, qual plugin é proprietário de qual superfície. Isso permite que o núcleo e os canais componham perfeitamente, porque a propriedade é declarada, tipada e testável, em vez de implícita.

O que pertence a um contrato

Em caso de dúvida, eleve o nível de abstração: defina a capacidade primeiro e, depois, deixe os plugins se conectarem a ela.

Modelo de execução

Plugins nativos do OpenClaw são executados em processo com o Gateway. Eles não são isolados em sandbox. Um plugin nativo carregado tem o mesmo limite de confiança em nível de processo que o código do núcleo.

Pacotes compatíveis são mais seguros por padrão porque o OpenClaw atualmente os trata como pacotes de metadados/conteúdo. Nas versões atuais, isso significa principalmente Skills integradas.

Use listas de permissões e caminhos explícitos de instalação/carregamento para plugins não integrados. Trate plugins de workspace como código de desenvolvimento, não como padrões de produção.

Para nomes de pacotes de workspace integrados, mantenha o id do plugin ancorado no nome npm: @openclaw/<id> por padrão, ou um sufixo tipado aprovado, como -provider, -plugin, -speech, -sandbox ou -media-understanding, quando o pacote expõe intencionalmente uma função de plugin mais restrita.

Limite de exportação

O OpenClaw exporta capacidades, não conveniência de implementação.

Mantenha público o registro de capacidades. Remova exportações auxiliares que não fazem parte do contrato:

• subcaminhos auxiliares específicos de plugins integrados
• subcaminhos de encanamento de tempo de execução não destinados a API pública
• auxiliares de conveniência específicos de fornecedor
• auxiliares de configuração/onboarding que são detalhes de implementação

Subcaminhos auxiliares reservados de plugins integrados foram aposentados do mapa de exportação gerado do SDK. Mantenha auxiliares específicos do proprietário dentro do pacote do plugin proprietário; promova apenas comportamento reutilizável do host para contratos genéricos do SDK, como plugin-sdk/gateway-runtime, plugin-sdk/security-runtime e plugin-sdk/plugin-config-runtime.

Internos e referência

Para o pipeline de carregamento, o modelo de registro, hooks de tempo de execução de provedores, rotas HTTP do Gateway, esquemas de ferramentas de mensagem, resolução de destino de canais, catálogos de provedores, plugins do mecanismo de contexto e o guia para adicionar uma nova capacidade, consulte Internos da arquitetura de plugins.

Relacionados

• Criação de plugins
• Manifesto do plugin
• Configuração do SDK de plugin