Aspectos internos do Plugin

Esta é a referência detalhada de arquitetura do sistema de plugins do OpenClaw. Para guias práticos, comece por uma das páginas específicas abaixo.

Modelo público de capacidades

As capacidades são o modelo público de plugins nativos no OpenClaw. Cada 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 núcleo e é usado atualmente por plugins incluídos/nativos, mas a compatibilidade de plugins externos ainda exige critérios mais rigorosos do que "se foi exportado, então está congelado".

O registro de capacidades é a direção pretendida. Durante a transição, os hooks legados continuam sendo o caminho mais seguro para evitar incompatibilidades em plugins externos. Nem todos os subcaminhos auxiliares exportados são equivalentes — prefira contratos restritos e documentados a exportações auxiliares incidentais.

Formatos de plugins

O OpenClaw classifica cada plugin carregado em um formato com base no comportamento real de registro, não apenas nos metadados estáticos:

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

Hooks legados

O hook before_agent_start continua sendo compatível como caminho de compatibilidade para plugins somente com hooks. Plugins legados usados no mundo real ainda dependem dele.

Direção:

• mantê-lo funcionando
• documentá-lo como legado
• preferir before_model_resolve para substituições de modelo/provedor
• preferir before_prompt_build para alterações de prompts
• removê-lo somente após a redução do uso real e quando a cobertura de fixtures comprovar a segurança da migração

Sinais de compatibilidade

openclaw doctor, openclaw plugins inspect <id>, openclaw status --all e openclaw plugins doctor exibem estes avisos de compatibilidade:

Atualmente, nenhum dos sinais informativos ou de aviso interrompe o funcionamento do seu plugin. 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:

• os metadados no momento da análise vêm de registerCli(..., { descriptors: [...] })
• o módulo real da CLI do plugin pode permanecer com carregamento tardio e se registrar na primeira invocação

Isso mantém o código da CLI pertencente ao plugin dentro dele e ainda permite que o OpenClaw reserve nomes de comandos raiz antes da análise.

O limite de projeto importante:

• a validação do manifesto/configuração deve funcionar a partir dos metadados do manifesto/esquema, sem executar o código do plugin
• a descoberta de capacidades nativas pode carregar o código de entrada de plugins confiáveis para criar um instantâneo não ativador do registro
• o comportamento nativo em tempo de execução vem do caminho register(api) do módulo do plugin com api.registrationMode === "full"

Essa separação permite que o OpenClaw valide a configuração, explique plugins ausentes/desabilitados e crie dicas para a interface/esquema antes que o tempo de execução completo esteja ativo.

Instantâneo de metadados de plugins e tabela de consulta

A inicialização do Gateway cria um PluginMetadataSnapshot para o instantâneo atual da configuração. O instantâneo contém apenas metadados: ele armazena o índice de plugins instalados, o registro de manifestos, os diagnósticos de manifestos, os mapas de proprietários, um normalizador de IDs de plugins e os registros de manifestos. Ele não contém módulos de plugins carregados, SDKs de provedores, conteúdo de pacotes nem exportações de tempo de execução.

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

Após a inicialização, o Gateway mantém o instantâneo de metadados atual como um produto substituível do tempo de execução. Descobertas repetidas de provedores em tempo de execução podem reutilizar esse instantâneo, em vez de reconstruir o índice instalado e o registro de manifestos a cada passagem pelo catálogo de provedores. O instantâneo é limpo ou substituído quando o Gateway é encerrado, quando a configuração ou o inventário de plugins muda e quando há gravações no índice instalado; os chamadores recorrem ao caminho frio de manifesto/índice quando não existe um instantâneo atual compatível. As verificações de compatibilidade devem incluir raízes de descoberta de plugins, como plugins.load.paths, e o espaço de trabalho padrão do agente, pois os plugins do espaço de trabalho fazem parte do escopo dos metadados.

O instantâneo e a tabela de consulta mantêm decisões repetidas de inicialização no caminho rápido:

• propriedade dos canais
• inicialização adiada de canais
• IDs dos plugins de inicialização
• propriedade dos provedores e backends da CLI
• propriedade do provedor de configuração, do alias de comando, do provedor do catálogo de modelos e do contrato do manifesto
• validação do esquema de configuração de plugins e do esquema de configuração de canais
• decisões de habilitação automática na inicialização

O limite de segurança é a substituição do instantâneo, não sua mutação. Reconstrua o instantâneo quando a configuração, o inventário de plugins, os registros de instalação ou a política persistida do índice forem alterados. Não o trate como um registro global mutável e abrangente nem mantenha instantâneos históricos ilimitados. O carregamento de plugins em tempo de execução permanece separado dos instantâneos de metadados, para que um estado obsoleto do tempo de execução não possa ser ocultado por um cache de metadados.

A regra de cache está documentada em Detalhes internos da arquitetura de plugins: os metadados de manifesto e descoberta são atuais, a menos que um chamador mantenha um instantâneo explícito, uma tabela de consulta ou um registro de manifestos para o fluxo atual. Caches ocultos de metadados e TTLs baseados no relógio não fazem parte do carregamento de plugins. Somente caches do carregador de tempo de execução, de módulos e de artefatos de dependências podem persistir após o código ou os artefatos instalados serem efetivamente carregados.

Alguns chamadores do caminho frio ainda reconstroem registros de manifestos diretamente a partir do índice persistido de plugins instalados, em vez de receberem uma PluginLookUpTable do Gateway. Agora, esse caminho reconstrói o registro sob demanda; prefira transmitir a tabela de consulta atual ou um registro explícito de manifestos pelos fluxos de tempo de execução quando um chamador já tiver um deles.

Planejamento de ativação

O planejamento de ativação faz parte do plano de controle. Os chamadores podem consultar quais plugins são relevantes para um comando, provedor, canal, rota, infraestrutura de agente ou recurso específico antes de carregar registros de runtime mais abrangentes.

O planejador mantém compatibilidade com o comportamento atual do manifesto:

• os campos activation.* são dicas explícitas para o planejador
• providers, channels, commandAliases, setup.providers, contracts.tools e os hooks continuam sendo o fallback de propriedade do manifesto
• a API do planejador que retorna apenas IDs permanece disponível para chamadores existentes
• a API de plano informa rótulos de motivo para que os diagnósticos possam distinguir dicas explícitas do fallback de propriedade

Plugins de canal e a ferramenta compartilhada de mensagens

Os 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 compartilhada message no núcleo, e os plugins de canal controlam a descoberta e a execução específicas do canal por trás dela.

O limite atual é:

• o núcleo controla o host da ferramenta compartilhada message, a integração com prompts, a manutenção dos registros de sessão/thread e o despacho da execução
• os plugins de canal controlam a descoberta de ações com escopo, a descoberta de recursos e quaisquer fragmentos de esquema específicos do canal
• os plugins de canal controlam a gramática de conversação de sessão específica do provedor, como a forma pela qual os IDs de conversa codificam IDs de thread ou são herdados de conversas pai
• os plugins de canal executam a ação final por meio de seu adaptador de ações

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

Quando um parâmetro específico do canal da ferramenta de mensagens contém uma fonte de mídia, como um caminho local ou uma URL de mídia remota, o plugin também deve retornar mediaSourceParams de describeMessageTool(...). O núcleo usa essa lista explícita para aplicar a normalização de caminhos do sandbox e dicas de acesso a mídia de saída sem codificar diretamente nomes de parâmetros pertencentes ao plugin. Nesse caso, prefira mapas com escopo por ação, em vez de uma única lista plana para todo o canal, para que um parâmetro de mídia exclusivo de perfil não seja normalizado em ações não relacionadas, como send.

O núcleo passa o escopo de runtime para essa etapa de descoberta. Campos importantes incluem:

• accountId
• currentChannelId
• currentThreadTs
• currentMessageId
• sessionKey
• sessionId
• agentId
• o requesterSenderId confiável da mensagem recebida

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

É por isso que alterações de roteamento do executor incorporado ainda são responsabilidade do plugin: o executor é responsável por encaminhar a identidade atual do chat/sessão ao limite de descoberta do plugin, para que a ferramenta compartilhada message exponha a superfície correta pertencente ao canal no turno atual.

Para auxiliares de execução pertencentes ao canal, os plugins incluídos no pacote devem manter o runtime de execução dentro de seus próprios módulos de plugin. O núcleo não controla mais os runtimes de ações de mensagens do Discord, Slack, Telegram ou WhatsApp em src/agents/tools. Não publicamos subcaminhos separados plugin-sdk/*-action-runtime, e os plugins incluídos no pacote devem importar diretamente seu próprio código de runtime local dos módulos pertencentes ao plugin.

O mesmo limite se aplica, de modo geral, às interfaces do SDK nomeadas por provedor: o núcleo não deve importar módulos agregadores de conveniência específicos de canal para Discord, Signal, Slack, WhatsApp ou plugins semelhantes. Se o núcleo precisar de um comportamento, deverá consumir o módulo agregador api.ts / runtime-api.ts do próprio plugin incluído no pacote ou promover a necessidade a um recurso genérico e restrito no SDK compartilhado.

Os plugins incluídos no pacote seguem a mesma regra. O runtime-api.ts de um plugin incluído no pacote não deve reexportar sua própria fachada identificada como openclaw/plugin-sdk/<plugin-id>. Essas fachadas identificadas continuam sendo camadas de compatibilidade para plugins externos e consumidores antigos, mas os plugins incluídos no pacote devem usar exportações locais e subcaminhos genéricos e restritos 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 de SDK específicas de ID de plugin, a menos que o limite de compatibilidade de um ecossistema externo existente exija isso.

Especificamente para enquetes, há dois caminhos de execução:

• outbound.sendPoll é a base compartilhada para canais que se adequam ao modelo comum de enquetes
• actions.handleAction("poll") é o caminho preferencial para semânticas de enquete específicas do canal ou parâmetros adicionais de enquete

Agora, o núcleo adia a análise compartilhada da enquete até que o despacho da enquete pelo plugin recuse a ação, permitindo que manipuladores de enquete pertencentes ao plugin aceitem campos de enquete específicos do canal sem serem bloqueados primeiro pelo analisador genérico de enquetes.

Consulte Aspectos internos da arquitetura de plugins para ver a sequência completa de inicialização.

Modelo de propriedade de recursos

O OpenClaw trata um plugin nativo como o limite de propriedade de uma empresa ou de um recurso, e não como uma coleção desorganizada de integrações sem relação entre si.

Isso significa que:

• um plugin de empresa geralmente deve controlar todas as superfícies dessa empresa voltadas ao OpenClaw
• um plugin de recurso geralmente deve controlar toda a superfície do recurso que introduz
• os canais devem consumir recursos compartilhados do núcleo em vez de reimplementar de forma ad hoc o comportamento do provedor

O estado final pretendido é:

• a superfície de um fornecedor voltada ao OpenClaw reside em um único plugin, mesmo que abranja modelos de texto, fala, imagens e vídeo
• outros fornecedores podem fazer o mesmo em suas próprias áreas de atuação
• os canais não precisam saber qual plugin de fornecedor controla o provedor; eles consomem o contrato de recurso compartilhado exposto pelo núcleo

Esta é a distinção fundamental:

• plugin = limite de propriedade
• recurso = contrato do núcleo que vários plugins podem implementar ou consumir

Portanto, se o OpenClaw adicionar um novo domínio, como vídeo, a primeira pergunta não será "qual provedor deve codificar diretamente o processamento de vídeo?". A primeira pergunta será "qual é o contrato de recurso de vídeo do núcleo?". Depois que esse contrato existir, os plugins de fornecedores poderão se registrar nele, e os plugins de canal/recurso poderão consumi-lo.

Se o recurso ainda não existir, a ação correta geralmente será:

Isso mantém a propriedade explícita e evita comportamentos do núcleo que dependam de um único fornecedor ou de um caminho de código específico de um plugin isolado.

Camadas de recursos

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

Por exemplo, o TTS segue esta estrutura:

• o núcleo controla a política de TTS no momento da resposta, a ordem de fallback, as preferências e a entrega pelo canal
• elevenlabs, google, microsoft e openai controlam as implementações de síntese
• voice-call consome o auxiliar de runtime de TTS para telefonia

Esse mesmo padrão deve ser preferido para recursos futuros.

Exemplo de plugin de empresa com vários recursos

Um plugin de empresa deve parecer coeso externamente. 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ídeos, busca de conteúdo na web e pesquisa na web, um fornecedor poderá controlar 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({          ...req,          provider: "exampleai",        });      },      async transcribeAudio(req) {        return transcribeOpenAiCompatibleAudio({          ...req,          provider: "exampleai",        });      },    });     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 que importa é a estrutura:

• um único plugin controla a superfície do fornecedor
• o núcleo continua controlando os contratos de recursos
• os canais e plugins de recursos consomem auxiliares api.runtime.*, e não código do fornecedor
• testes de contrato podem verificar se o plugin registrou os recursos que declara controlar

Exemplo de recurso: compreensão de vídeo

O OpenClaw já trata a compreensão de imagens/áudio/vídeo como um único recurso compartilhado. O mesmo modelo de propriedade se aplica nesse caso:

Isso evita incorporar ao núcleo as premissas de vídeo de um único provedor. O plugin controla a superfície do fornecedor; o núcleo controla o contrato de recurso e o comportamento de fallback.

A geração de vídeos já usa essa mesma sequência: o núcleo controla o contrato tipado de recurso e o auxiliar de runtime, e os plugins de fornecedores registram implementações de api.registerVideoGenerationProvider(...) nele.

Precisa de uma lista de verificação concreta para a implementação? Consulte o Guia prático de recursos.

Contratos e aplicação

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

Por que isso é importante:

• os autores de plugins têm um único padrão interno estável
• o núcleo pode rejeitar propriedade duplicada, como quando dois plugins registram o mesmo id de provedor
• a inicialização pode apresentar diagnósticos acionáveis para registros malformados
• testes de contrato podem impor a propriedade de plugins integrados e evitar desvios silenciosos

Há duas camadas de aplicação:

O efeito prático é que o OpenClaw sabe, antecipadamente, qual plugin é proprietário de cada superfície. Isso permite que o núcleo e os canais se componham de forma integrada, pois 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 primeiro a capacidade e, depois, permita que os plugins se conectem a ela.

Modelo de execução

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

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

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

Para nomes de pacotes integrados do workspace, 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 expuser intencionalmente uma função de plugin mais específica.

Limite de exportação

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

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

• subcaminhos auxiliares específicos de plugins integrados
• subcaminhos de infraestrutura de runtime que não se destinam a ser uma API pública
• auxiliares de conveniência específicos de fornecedores
• auxiliares de configuração/integração inicial que sejam detalhes de implementação

Os subcaminhos auxiliares reservados de plugins integrados foram removidos do mapa de exportação gerado do SDK. Mantenha os auxiliares específicos de cada proprietário dentro do pacote do plugin correspondente; promova apenas comportamentos reutilizáveis do host a contratos genéricos do SDK, como plugin-sdk/gateway-runtime, plugin-sdk/security-runtime e plugin-sdk/plugin-config-runtime.

Aspectos internos e referência

Para conhecer o pipeline de carregamento, o modelo de registro, os hooks de runtime dos provedores, as rotas HTTP do Gateway, os esquemas de ferramentas de mensagens, a resolução de destinos de canais, os catálogos de provedores, os plugins do mecanismo de contexto e o guia para adicionar uma nova capacidade, consulte Aspectos internos da arquitetura de plugins.

Relacionados

• Como criar plugins
• Manifesto de plugin
• Configuração do SDK de plugins