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.Documentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
Esta página é para autores de plugins que usam
openclaw/plugin-sdk/* dentro do
OpenClaw. Para apps externos, scripts, dashboards, trabalhos de CI e extensões
de IDE que querem executar agentes por meio do Gateway, use o
OpenClaw App SDK e o pacote @openclaw/sdk
em vez disso.Convenção de importação
Sempre importe de um subcaminho específico: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 emscripts/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 callbackregister(api) recebe um objeto OpenClawPluginApi com estes
métodos:
Registro de capability
| 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 de 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 de voz duplex em tempo real |
api.registerMediaUnderstandingProvider(...) | Análise de imagem/áudio/vídeo |
api.registerImageGenerationProvider(...) | Geração de imagens |
api.registerMusicGenerationProvider(...) | Geração de música |
api.registerVideoGenerationProvider(...) | Geração de vídeo |
api.registerWebFetchProvider(...) | Provedor de busca/coleta na web |
api.registerWebSearchProvider(...) | Pesquisa na web |
Ferramentas e comandos
| Método | O que ele registra |
|---|---|
api.registerTool(tool, opts?) | Ferramenta de agente (obrigatória ou { optional: true }) |
api.registerCommand(def) | Comando personalizado (ignora o LLM) |
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
| 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.registerGatewayDiscoveryService(service) | Anunciante de descoberta do Gateway local |
api.registerCli(registrar, opts?) | Subcomando de CLI |
api.registerNodeCliFeature(registrar, opts?) | CLI de recurso Node em openclaw nodes |
api.registerService(service) | Serviço em segundo plano |
api.registerInteractiveHandler(registration) | Handler interativo |
api.registerAgentToolResultMiddleware(...) | Middleware de resultado de ferramenta em runtime |
api.registerMemoryPromptSupplement(builder) | Seção de prompt aditiva adjacente à memória |
api.registerMemoryCorpusSupplement(adapter) | Corpus aditivo de pesquisa/leitura de memória |
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.| Método | Contrato que ele possui |
|---|---|
api.session.state.registerSessionExtension(...) | Estado de sessão pertencente ao plugin e compatível com JSON, projetado por meio de sessões do Gateway |
api.session.workflow.enqueueNextTurnInjection(...) | Contexto durável exatamente uma vez injetado na próxima rodada do agente para uma sessão |
api.registerTrustedToolPolicy(...) | Política de ferramenta pré-plugin incluída/confiável que pode bloquear ou reescrever parâmetros de ferramenta |
api.registerToolMetadata(...) | Metadados de exibição do catálogo de ferramentas sem alterar a implementação da ferramenta |
api.registerCommand(...) | Comandos de plugin com escopo; resultados de comando podem definir continueAgent: true; comandos nativos do Discord aceitam descriptionLocalizations |
api.session.controls.registerControlUiDescriptor(...) | Descritores de contribuição de UI de controle para superfícies de sessão, ferramenta, execução ou configurações |
api.lifecycle.registerRuntimeLifecycle(...) | Callbacks de limpeza para recursos de runtime pertencentes ao plugin em caminhos de reset/delete/reload |
api.agent.events.registerAgentEventSubscription(...) | Assinaturas de eventos sanitizadas para estado de workflow e monitores |
api.runContext.setRunContext(...) / getRunContext(...) / clearRunContext(...) | Estado temporário por execução do plugin limpo no ciclo de vida terminal da execução |
api.session.workflow.registerSessionSchedulerJob(...) | Metadados de limpeza para trabalhos de scheduler pertencentes ao plugin; não agenda trabalho nem cria registros de tarefa |
api.session.workflow.sendSessionAttachment(...) | Entrega de anexo de arquivo mediada pelo host e apenas para incluídos para a rota direta de saída ativa da sessão |
api.session.workflow.scheduleSessionTurn(...) / unscheduleSessionTurnsByTag(...) | Rodadas de sessão agendadas com base em Cron e apenas para incluídos, mais limpeza baseada em tags |
api.session.controls.registerSessionAction(...) | Ações de sessão tipadas que clientes podem despachar por meio do Gateway |
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(...)
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_callcomuns 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=falsedesabilita hooks que modificam prompts, incluindoagent_turn_prepare,before_prompt_build,heartbeat_prompt_contribution, campos de prompt dobefore_agent_startlegado eenqueueNextTurnInjection.
| Arquétipo de plugin | Hooks usados |
|---|---|
| Fluxo de aprovação | Extensão de sessão, continuação de comando, injeção no próximo turno, descritor de UI |
| Gate de política de orçamento/workspace | Política de ferramenta confiável, metadados de ferramenta, projeção de sessão |
| Monitor de ciclo de vida em segundo plano | Limpeza de ciclo de vida em runtime, assinatura de evento do agente, propriedade/limpeza do agendador de sessão, contribuição de prompt de heartbeat, descritor de UI |
| Assistente de configuração ou onboarding | Extensão de sessão, comandos com escopo, descritor de UI de controle |
Namespaces administrativos centrais reservados (
config.*, exec.approvals.*, wizard.*,
update.*) sempre permanecem como operator.admin, mesmo que um plugin tente atribuir um
escopo de método de gateway mais restrito. Prefira prefixos específicos do plugin para
métodos pertencentes ao plugin.Quando usar middleware de resultado de ferramenta
Quando usar middleware de resultado de ferramenta
Plugins incluídos no pacote podem usar
api.registerAgentToolResultMiddleware(...) quando
precisam reescrever um resultado de ferramenta após a execução e antes que o runtime
alimente esse resultado de volta ao modelo. Esta é a integração confiável e neutra em relação ao runtime
para redutores de saída assíncronos como tokenjuice.Plugins incluídos no pacote devem declarar contracts.agentToolResultMiddleware para cada
runtime de destino, por exemplo ["pi", "codex"]. Plugins externos
não podem registrar este middleware; mantenha os hooks normais de plugin do OpenClaw para trabalhos
que não precisam do tempo de resultado de ferramenta antes do modelo. O antigo caminho de registro
da fábrica de extensão embutida somente para Pi foi removido.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.
Metadados de registro da CLI
api.registerCli(registrar, opts?) aceita dois tipos de metadados de comando:
commands: nomes de comando explícitos pertencentes ao registradordescriptors: descritores de comando em tempo de análise usados para ajuda da CLI, roteamento e registro preguiçoso da CLI de pluginparentPath: caminho opcional do comando pai para grupos de comandos aninhados, como["nodes"]
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.
program:
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
iddo backend se torna o prefixo do provider em referências de modelo comocodex-cli/gpt-5. - A
configdo backend usa o mesmo formato queagents.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
normalizeConfigquando um backend precisar de reescritas de compatibilidade após a mesclagem (por exemplo, normalizar formatos antigos de flags). - Use
resolveExecutionArgspara 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.
Slots exclusivos
| Método | O que registra |
|---|---|
api.registerContextEngine(id, factory) | Motor de contexto (um ativo por vez). O callback assemble() recebe availableTools e citationsMode para que o motor possa ajustar 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 |
Adaptadores de embedding de memória
| Método | O que registra |
|---|---|
api.registerMemoryEmbeddingProvider(adapter) | Adaptador de embedding de memória para o plugin ativo |
registerMemoryCapabilityé a API exclusiva preferida para plugins de memória.registerMemoryCapabilitytambém pode exporpublicArtifacts.listArtifacts(...)para que plugins complementares possam consumir artefatos de memória exportados por meio deopenclaw/plugin-sdk/memory-host-coreem vez de acessar o layout privado de um plugin de memória específico.registerMemoryPromptSection,registerMemoryFlushPlaneregisterMemoryRuntimesão APIs exclusivas de plugin de memória compatíveis com legado.MemoryFlushPlan.modelpode fixar o turno de flush em uma referência exata deprovider/model, comoollama/qwen3:8b, sem herdar a cadeia de fallback ativa.registerMemoryEmbeddingProviderpermite que o plugin de memória ativo registre um ou mais ids de adaptador de embedding (por exemplo,openai,geminiou um id personalizado definido pelo plugin).- Configurações do usuário como
agents.defaults.memorySearch.providereagents.defaults.memorySearch.fallbacksão resolvidas contra esses ids de adaptador registrados.
Eventos e ciclo de vida
| Método | O que 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
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 omitirblock), 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 omitirblock), 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 omitircancel), não como uma substituição.message_received: use o campo tipadothreadIdquando precisar de roteamento de tópico/thread de entrada. Mantenhametadatapara extras específicos do canal.message_sending: use campos de roteamento tipadosreplyToId/threadIdantes de recorrer ametadataespecífico do canal.gateway_start: usectx.config,ctx.workspaceDirectx.getCron?.()para estado de inicialização pertencente ao gateway em vez de depender de hooks internosgateway:startup.cron_changed: observe mudanças no ciclo de vida do cron pertencente ao gateway. Useevent.job?.state?.nextRunAtMsectx.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
| 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 de runtime em memória ativo quando disponível) |
api.pluginConfig | Record<string, unknown> | Configuração específica do Plugin de plugins.entries.<id>.config |
api.runtime | PluginRuntime | Helpers de 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/setup antes da entrada completa |
api.resolvePath(input) | (string) => string | Resolve o caminho relativo à raiz do Plugin |
Convenção de módulo interno
Dentro do seu Plugin, use arquivos barrel locais para importações internas: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.tspara helpers de stream de beta-header do Claude eservice_tier. @openclaw/openai-provider:api.tsexporta builders de provedor, helpers de modelo padrão e builders de provedor em tempo real.@openclaw/openrouter-provider:api.tsexporta o builder de provedor mais helpers de onboarding/configuração.
Relacionados
Entry points
Opções de
definePluginEntry e defineChannelPluginEntry.Runtime helpers
Referência completa do namespace
api.runtime.Setup and config
Empacotamento, manifestos e esquemas de configuração.
Testing
Utilitários de teste e regras de lint.
SDK migration
Migração de superfícies obsoletas.
Plugin internals
Arquitetura profunda e modelo de capacidades.