Visão geral do SDK de Plugin

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.

Convenção de importação

Sempre importe de um subcaminho específico:

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 de entrada/build específicos de canal, prefira openclaw/plugin-sdk/channel-core; reserve openclaw/plugin-sdk/core para a superfície mais ampla e helpers compartilhados, como buildChannelConfigSchema.

Para configuração de canal, publique o JSON Schema pertencente ao canal por meio de openclaw.plugin.json#channelConfigs. O subcaminho plugin-sdk/channel-config-schema é para primitivas de schema compartilhadas e o builder genérico. Os plugins incluídos no OpenClaw usam plugin-sdk/bundled-channel-config-schema para schemas retidos de canais incluídos. Exports de compatibilidade obsoletos permanecem em plugin-sdk/channel-config-schema-legacy; nenhum subcaminho de schema incluído é um padrão para novos plugins.

Referência de subcaminhos

O SDK de Plugin é exposto como um conjunto de subcaminhos estreitos agrupados por área (entrada de plugin, canal, provedor, autenticação, runtime, capability, memória e helpers reservados de plugins incluídos). Para o catálogo completo — agrupado e com links — veja Subcaminhos do SDK de Plugin.

O inventário de pontos de entrada do compilador fica em scripts/lib/plugin-sdk-entrypoints.json; os exports do pacote são gerados a partir do subconjunto público depois de subtrair subcaminhos de teste/internos locais ao repositório listados em scripts/lib/plugin-sdk-private-local-only-subpaths.json. Execute pnpm plugin-sdk:surface para auditar a contagem de exports públicos. Subcaminhos públicos obsoletos antigos o suficiente e não usados por código de produção de extensões incluídas são rastreados em scripts/lib/plugin-sdk-deprecated-public-subpaths.json; barrels amplos de re-export obsoletos são rastreados em scripts/lib/plugin-sdk-deprecated-barrel-subpaths.json.

API de registro

O callback register(api) recebe um objeto OpenClawPluginApi com estes métodos:

Registro de capability

Provedores de embedding registrados com api.registerEmbeddingProvider(...) também devem ser listados em contracts.embeddingProviders no manifesto do plugin. Esta é a superfície genérica de embedding para geração vetorial reutilizável. A busca de memória pode consumir esta superfície genérica de provedor. A seam mais antiga api.registerMemoryEmbeddingProvider(...) e contracts.memoryEmbeddingProviders é compatibilidade obsoleta enquanto provedores existentes específicos de memória migram.

Provedores específicos de memória que ainda expõem um runtime batchEmbed(...) permanecem no contrato existente de batching por arquivo, a menos que seu runtime defina explicitamente sourceWideBatchEmbed: true. Essa adesão permite que o host de memória envie chunks de vários arquivos de memória sujos e fontes habilitadas em uma chamada batchEmbed(...) até os limites de lote do host. Adaptadores de lote que fazem upload de arquivos de requisição JSONL devem dividir tarefas de provedor antes de atingir seu limite de tamanho de upload, bem como seu limite de quantidade de requisições. O provedor deve retornar um embedding por chunk de entrada na mesma ordem de batch.chunks; omita a flag quando o provedor espera lotes locais ao arquivo ou não consegue preservar a ordenação de entrada em uma tarefa maior que abrange a fonte inteira.

Ferramentas e comandos

Use defineToolPlugin para plugins simples somente de ferramenta com nomes de ferramentas fixos. Use api.registerTool(...) diretamente para plugins mistos ou registro de ferramentas totalmente dinâmico.

Comandos de plugin podem definir agentPromptGuidance quando o agente precisa de uma dica curta, pertencente ao comando, para roteamento. Mantenha esse texto sobre o próprio comando; não adicione política específica de provedor ou plugin aos builders de prompt do núcleo.

Entradas de orientação podem ser strings legadas, que se aplicam a toda superfície de prompt, ou entradas estruturadas:

agentPromptGuidance: [  "Global command hint.",  { text: "Only show this in the main OpenClaw prompt.", surfaces: ["openclaw_main"] },];

surfaces estruturadas podem incluir openclaw_main, codex_app_server, cli_backend, acp_backend ou subagent. pi_main permanece um alias obsoleto para openclaw_main. Omita surfaces para orientação intencional em todas as superfícies. Não passe um array surfaces vazio; ele é rejeitado para que perda acidental de escopo não vire texto global de prompt.

As instruções de desenvolvedor nativas do app-server do Codex são mais rígidas que outras superfícies de prompt: somente orientação explicitamente escopada para codex_app_server é promovida para essa faixa de maior prioridade. Orientação legada em string e orientação estruturada sem escopo permanecem disponíveis para superfícies de prompt que não são Codex por compatibilidade.

Infraestrutura

Hooks de host para plugins de workflow

Hooks de host são as seams do SDK para plugins que precisam participar do ciclo de vida do host em vez de apenas adicionar um provedor, canal ou ferramenta. Eles são contratos genéricos; o Modo de Planejamento pode usá-los, mas também podem workflows de aprovação, gates de política de workspace, monitores em segundo plano, assistentes de configuração e plugins companheiros de UI.

Use os namespaces agrupados para novo código de plugin:

• api.session.state.registerSessionExtension(...)
• api.session.workflow.enqueueNextTurnInjection(...)
• api.session.workflow.registerSessionSchedulerJob(...)
• api.session.workflow.sendSessionAttachment(...)
• api.session.workflow.scheduleSessionTurn(...)
• api.session.workflow.unscheduleSessionTurnsByTag(...)
• api.session.controls.registerSessionAction(...)
• api.session.controls.registerControlUiDescriptor(...)
• api.agent.events.registerAgentEventSubscription(...)
• api.agent.events.emitAgentEvent(...)
• api.runContext.setRunContext(...) / getRunContext(...) / clearRunContext(...)
• api.lifecycle.registerRuntimeLifecycle(...)

Os métodos planos equivalentes continuam disponíveis como aliases de compatibilidade obsoletos para plugins existentes. Não adicione novo código de plugin que chame diretamente api.registerSessionExtension, api.enqueueNextTurnInjection, api.registerControlUiDescriptor, api.registerRuntimeLifecycle, api.registerAgentEventSubscription, api.emitAgentEvent, api.setRunContext, api.getRunContext, api.clearRunContext, api.registerSessionSchedulerJob, api.registerSessionAction, api.sendSessionAttachment, api.scheduleSessionTurn ou api.unscheduleSessionTurnsByTag.

scheduleSessionTurn(...) é uma conveniência com escopo de sessão sobre o agendador Cron do Gateway. Cron detém a temporização e cria o registro da tarefa em segundo plano quando o turno é executado; o Plugin SDK apenas restringe a sessão de destino, a nomenclatura pertencente ao plugin e a limpeza. Use api.runtime.tasks.managedFlows dentro do turno agendado quando o trabalho em si precisar de estado durável de Task Flow em várias etapas.

Os contratos separam autoridade intencionalmente:

• Plugins externos podem deter extensões de sessão, descritores de UI, comandos, metadados de ferramentas, injeções no próximo turno e hooks normais.
• Políticas de ferramentas confiáveis são executadas antes de hooks before_tool_call comuns e são confiadas pelo host. Políticas integradas são executadas primeiro; políticas de plugins instalados exigem habilitação explícita mais seus ids locais em contracts.trustedToolPolicies, e são executadas em seguida na ordem de carregamento dos plugins. IDs de política têm escopo no plugin que as registra.
• A propriedade de comandos reservados é apenas para plugins integrados. Plugins externos devem usar seus próprios nomes de comando ou aliases.
• allowPromptInjection=false desativa hooks que alteram prompts, incluindo agent_turn_prepare, before_prompt_build, heartbeat_prompt_contribution, campos de prompt do legado before_agent_start e enqueueNextTurnInjection.

Exemplos de consumidores que não são do Plan:

Registro de descoberta do Gateway

api.registerGatewayDiscoveryService(...) permite que um plugin anuncie o Gateway ativo em um transporte de descoberta local, como mDNS/Bonjour. O OpenClaw chama o serviço durante a inicialização do Gateway quando a descoberta local está habilitada, passa as portas atuais do Gateway e dados de dica TXT não secretos, e chama o handler stop retornado durante o desligamento do Gateway.

api.registerGatewayDiscoveryService({  id: "my-discovery",  async advertise(ctx) {    const handle = await startMyAdvertiser({      gatewayPort: ctx.gatewayPort,      tls: ctx.gatewayTlsEnabled,      displayName: ctx.machineDisplayName,    });    return { stop: () => handle.stop() };  },});

Plugins de descoberta do Gateway não devem tratar valores TXT anunciados como segredos ou autenticação. A descoberta é uma dica de roteamento; a autenticação do Gateway e a fixação de TLS ainda detêm a confiança.

Metadados de registro da CLI

api.registerCli(registrar, opts?) aceita dois tipos de metadados de comando:

• commands: nomes explícitos de comandos pertencentes ao registrador
• descriptors: descritores de comando em tempo de análise usados para ajuda da CLI, roteamento e registro lento da CLI do plugin
• parentPath: caminho opcional do comando pai para grupos de comandos aninhados, como ["nodes"]

Para recursos de nós pareados, prefira api.registerNodeCliFeature(registrar, opts?). Ele é um pequeno wrapper em torno de api.registerCli(..., { parentPath: ["nodes"] }) e torna comandos como openclaw nodes canvas recursos de nó explicitamente pertencentes ao plugin.

Se você quiser que um comando de plugin continue com carregamento lento no caminho raiz normal da CLI, forneça descriptors que cubram cada raiz de comando de nível superior exposta por esse registrador.

api.registerCli(  async ({ program }) => {    const { registerMatrixCli } = await import("./src/cli.js");    registerMatrixCli({ program });  },  {    descriptors: [      {        name: "matrix",        description: "Manage Matrix accounts, verification, devices, and profile state",        hasSubcommands: true,      },    ],  },);

Comandos aninhados recebem o comando pai resolvido como program:

api.registerCli(  async ({ program }) => {    const { registerNodesCanvasCommands } = await import("./src/cli.js");    registerNodesCanvasCommands(program);  },  {    parentPath: ["nodes"],    descriptors: [      {        name: "canvas",        description: "Capture or render canvas content from a paired node",        hasSubcommands: true,      },    ],  },);

Use commands sozinho apenas quando não precisar de registro lento da CLI raiz. Esse caminho de compatibilidade ansioso continua aceito, mas não instala placeholders baseados em descritores para carregamento lento em tempo de análise.

Registro de backend da CLI

api.registerCliBackend(...) permite que um plugin detenha a configuração padrão para um backend local de CLI de IA, como claude-cli ou my-cli.

• O id do backend se torna o prefixo do provedor em referências de modelo como my-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 padrão do plugin antes de executar a CLI.
• Use normalizeConfig quando um backend precisar de reescritas de compatibilidade após a mesclagem (por exemplo, normalizar formatos antigos de flags).
• Use resolveExecutionArgs para reescritas de argv no escopo da solicitação que pertencem ao dialeto da CLI, como mapear níveis de raciocínio do OpenClaw para uma flag nativa de esforço. O hook recebe ctx.executionMode; use "side-question" para adicionar flags de isolamento nativas do backend para chamadas efêmeras de /btw. Se essas flags desativarem de forma confiável as ferramentas nativas de uma CLI que, de outro modo, ficaria sempre ativa, declare também sideQuestionToolMode: "disabled".

Para um guia de autoria de ponta a ponta, consulte plugins de backend de CLI.

Slots exclusivos

Adaptadores de embedding de memória obsoletos

• registerMemoryCapability é a API exclusiva preferida para plugins 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 compatíveis com legado para plugins de memória.
• MemoryFlushPlan.model pode fixar o turno de flush a uma referência exata de provider/model, como ollama/qwen3:8b, sem herdar a cadeia de fallback ativa.
• registerMemoryEmbeddingProvider está obsoleto. Novos provedores de embedding devem usar api.registerEmbeddingProvider(...) e contracts.embeddingProviders.
• Provedores existentes específicos de memória continuam funcionando durante a janela de migração, mas a inspeção de plugins relata isso como dívida de compatibilidade para plugins não integrados.

Eventos e ciclo de vida

Consulte Hooks de plugin para exemplos, nomes comuns de hooks e semântica de guardas.

Semântica de decisão dos hooks

before_install é um hook de ciclo de vida do runtime de plugins, não a superfície de política de instalação do operador. Use security.installPolicy quando uma decisão de permitir/bloquear precisar cobrir caminhos de instalação ou atualização baseados em CLI e Gateway.

• before_tool_call: retornar { block: true } é terminal. Assim que qualquer handler o define, handlers de prioridade menor são ignorados.
• before_tool_call: retornar { block: false } é tratado como ausência de decisão (o mesmo que omitir block), não como uma substituição.
• before_install: retornar { block: true } é terminal. Assim que qualquer handler o define, handlers de prioridade menor são ignorados.
• before_install: retornar { block: false } é tratado como ausência de decisão (o mesmo que omitir block), não como uma substituição.
• reply_dispatch: retornar { handled: true, ... } é terminal. Assim que qualquer handler reivindica o despacho, handlers de prioridade menor e o caminho padrão de despacho do modelo são ignorados.
• message_sending: retornar { cancel: true } é terminal. Assim que qualquer handler o define, handlers de prioridade menor são ignorados.
• message_sending: retornar { cancel: false } é tratado como ausência de decisão (o mesmo que omitir cancel), não como uma substituição.
• message_received: use o campo tipado threadId quando precisar de roteamento de thread/tópico de entrada. Mantenha metadata para extras específicos do canal.
• message_sending: use os campos tipados de roteamento replyToId / threadId antes de recorrer a metadata específico do canal.
• gateway_start: use ctx.config, ctx.workspaceDir e ctx.getCron?.() para o estado de inicialização pertencente ao gateway, em vez de depender de hooks internos gateway:startup.
• cron_changed: observe mudanças no ciclo de vida do cron pertencente ao gateway. Use event.job?.state?.nextRunAtMs e ctx.getCron?.() ao sincronizar agendadores externos de despertar, e mantenha o OpenClaw como a fonte da verdade para verificações de vencimento e execução.

Campos do objeto de API

Convenção de módulos internos

Dentro do seu plugin, use arquivos barrel locais para imports internos:

my-plugin/  api.ts            # Public exports for external consumers  runtime-api.ts    # Internal-only runtime exports  index.ts          # Plugin entry point  setup-entry.ts    # Lightweight setup-only entry (optional)

Superfícies públicas de plugins integrados carregados por fachada (api.ts, runtime-api.ts, index.ts, setup-entry.ts e arquivos de entrada públicos semelhantes) preferem o snapshot ativo da configuração de runtime quando o OpenClaw já está em execução. Se ainda não houver snapshot de runtime, elas recorrem ao arquivo de configuração resolvido no disco. Fachadas de plugins integrados empacotados devem ser carregadas por meio dos carregadores de fachada de plugins do OpenClaw; imports diretos de dist/extensions/... ignoram as verificações de manifesto e de sidecar de runtime que instalações empacotadas usam para código pertencente a plugins.

Plugins de provedor podem expor um barrel de contrato estreito e local ao plugin quando um helper é intencionalmente específico do provedor e ainda não pertence a um subcaminho genérico do SDK. Exemplos integrados:

• Anthropic: ponto de integração público api.ts / contract-api.ts para helpers de streaming de beta-header do Claude e service_tier.
• @openclaw/openai-provider: api.ts exporta construtores de provedor, helpers de modelo padrão e construtores de provedor em tempo real.
• @openclaw/openrouter-provider: api.ts exporta o construtor de provedor mais helpers de onboarding/configuração.

Relacionado