Visão geral do SDK de Plugin

O SDK de plugins é 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; mantenha openclaw/plugin-sdk/core para a superfície guarda-chuva 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 do OpenClaw usam plugin-sdk/bundled-channel-config-schema para schemas mantidos de canais incluídos. Exportações de compatibilidade obsoletas permanecem em plugin-sdk/channel-config-schema-legacy; nenhum dos subcaminhos de schema incluído é um padrão para novos plugins.

Referência de subcaminhos

O SDK de plugins é 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 vinculado — consulte Subcaminhos do SDK de plugins.

O inventário de pontos de entrada do compilador fica em scripts/lib/plugin-sdk-entrypoints.json; as exportações de pacote são geradas a partir do subconjunto público após subtrair os subcaminhos de teste/internos locais do repositório listados em scripts/lib/plugin-sdk-private-local-only-subpaths.json. Execute pnpm plugin-sdk:surface para auditar a contagem de exportações públicas. Subcaminhos públicos obsoletos que são 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 obsoletos de reexportação 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

Ferramentas e comandos

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

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 Plan Mode pode usá-los, mas fluxos de aprovação, gates de política de workspace, monitores em segundo plano, assistentes de configuração e plugins companheiros de UI também podem.

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 permanecem disponíveis como aliases de compatibilidade obsoletos para plugins existentes. Não adicione novo código de plugin que chame 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 diretamente.

scheduleSessionTurn(...) é uma conveniência com escopo de sessão sobre o agendador Cron do Gateway. Cron é responsável pelo tempo e cria o registro da tarefa em segundo plano quando o turno é executado; o SDK de Plugin 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 dividem a autoridade intencionalmente:

• Plugins externos podem possuir 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 dos hooks before_tool_call comuns e são apenas para plugins incluídos no pacote porque participam da política de segurança do host.
• A propriedade de comandos reservados é apenas para plugins incluídos no pacote. Plugins externos devem usar seus próprios nomes de comando ou aliases.
• allowPromptInjection=false desabilita hooks que modificam prompts, incluindo agent_turn_prepare, before_prompt_build, heartbeat_prompt_contribution, campos de prompt do before_agent_start legado e enqueueNextTurnInjection.

Exemplos de consumidores que não são 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 manipulador 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 são responsáveis pela confiança.

Metadados de registro da CLI

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

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

Para recursos de nó pareado, 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 permaneça carregado de forma preguiçosa no caminho normal da CLI raiz, 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 você não precisar de registro preguiçoso da CLI raiz. Esse caminho de compatibilidade ansioso continua compatível, mas não instala placeholders baseados em descritores para carregamento preguiçoso em tempo de análise.

Registro de backend da CLI

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

• O id do backend se torna o prefixo do provider em referências de modelo como codex-cli/gpt-5.
• A config do backend usa o mesmo formato que 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 com escopo de solicitação que pertencem ao dialeto da CLI, como mapear níveis de raciocínio do OpenClaw para uma flag de esforço nativa.

Para um guia de autoria completo, consulte plugins de backend da CLI.

Slots exclusivos

Adaptadores de embedding de memória

• registerMemoryCapability é a API exclusiva preferida para plugins de memória.
• registerMemoryCapability também pode expor publicArtifacts.listArtifacts(...) para que plugins complementares possam consumir 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 legado.
• MemoryFlushPlan.model pode fixar o turno de flush em uma referência exata de provider/model, como ollama/qwen3:8b, sem herdar a cadeia de fallback ativa.
• 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).
• Configurações do usuário como agents.defaults.memorySearch.provider e agents.defaults.memorySearch.fallback são resolvidas contra esses ids de adaptador registrados.

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 de hooks

• before_tool_call: retornar { block: true } é terminal. Depois que qualquer manipulador o define, manipuladores de prioridade mais baixa sã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. Depois que qualquer manipulador o define, manipuladores de prioridade mais baixa sã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. Depois que qualquer manipulador reivindica o despacho, manipuladores de prioridade mais baixa e o caminho padrão de despacho do modelo são ignorados.
• message_sending: retornar { cancel: true } é terminal. Depois que qualquer manipulador o define, manipuladores de prioridade mais baixa são ignorados.
• message_sending: retornar { cancel: false } é tratado como nenhuma decisão (igual a omitir cancel), não como uma substituição.
• message_received: use o campo tipado threadId quando precisar de roteamento de tópico/thread de entrada. Mantenha metadata para extras específicos do canal.
• message_sending: use campos de roteamento tipados replyToId / threadId antes de recorrer a metadata específico do canal.
• gateway_start: use ctx.config, ctx.workspaceDir e ctx.getCron?.() para 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 ativação, 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ódulo interno

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 de runtime apenas internas  index.ts          # Ponto de entrada do Plugin  setup-entry.ts    # Entrada leve apenas de setup (opcional)

Superfícies públicas de plugins empacotados carregados por fachada (api.ts, runtime-api.ts, index.ts, setup-entry.ts e arquivos de entrada públicos semelhantes) preferem o snapshot da configuração de runtime ativa quando o OpenClaw já está em execução. Se ainda não existir um snapshot de runtime, elas usam como fallback o arquivo de configuração resolvido no disco. Fachadas de plugins empacotados devem ser carregadas pelos carregadores de fachada de Plugin do OpenClaw; importações diretas de dist/extensions/... contornam o manifesto e as verificações de sidecar de runtime que instalações empacotadas usam para código pertencente ao Plugin.

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 empacotados:

• Anthropic: seam pública api.ts / contract-api.ts para helpers de stream de beta-header do Claude e service_tier.
• @openclaw/openai-provider: api.ts exporta builders de provedor, helpers de modelo padrão e builders de provedor em tempo real.
• @openclaw/openrouter-provider: api.ts exporta o builder de provedor mais helpers de onboarding/configuração.

Relacionados