Pular para o conteúdo principal

​
Visão geral do Plugin SDK

O Plugin SDK é 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.
Está procurando um guia prático?

​
Convenção de importação

Sempre importe de um subcaminho específico: 
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
Cada subcaminho é um módulo pequeno e autocontido. Isso mantém a inicialização rápida e evita problemas de dependência circular. Para auxiliares de entrada/construção específicos de canal, prefira openclaw/plugin-sdk/channel-core; mantenha openclaw/plugin-sdk/core para a superfície mais ampla e os auxiliares compartilhados, como buildChannelConfigSchema. Não adicione nem dependa de interfaces de conveniência nomeadas por provedor, como openclaw/plugin-sdk/slack, openclaw/plugin-sdk/discord, openclaw/plugin-sdk/signal, openclaw/plugin-sdk/whatsapp, ou interfaces auxiliares com marca de canal. Plugins empacotados devem compor subcaminhos genéricos do SDK dentro de seus próprios barrels api.ts ou runtime-api.ts, e o núcleo deve usar esses barrels locais do plugin ou adicionar um contrato genérico estreito do SDK quando a necessidade realmente for entre canais. O mapa de exportação gerado ainda contém um pequeno conjunto de interfaces auxiliares de plugins empacotados, como plugin-sdk/feishu, plugin-sdk/feishu-setup, plugin-sdk/zalo, plugin-sdk/zalo-setup e plugin-sdk/matrix*. Esses subcaminhos existem apenas para manutenção e compatibilidade de plugins empacotados; eles são intencionalmente omitidos da tabela comum abaixo e não são o caminho de importação recomendado para novos plugins de terceiros.

​
Referência de subcaminhos

Os subcaminhos mais usados, agrupados por finalidade. A lista completa gerada de mais de 200 subcaminhos está em scripts/lib/plugin-sdk-entrypoints.json. Subcaminhos auxiliares reservados de plugins empacotados ainda aparecem nessa lista gerada. Trate-os como detalhes de implementação/superfícies de compatibilidade, a menos que uma página da documentação promova explicitamente um deles como público.

​
Entrada de plugin

SubcaminhoExportações principais
plugin-sdk/plugin-entrydefinePluginEntry
plugin-sdk/coredefineChannelPluginEntry, createChatChannelPlugin, createChannelPluginBase, defineSetupPluginEntry, buildChannelConfigSchema
plugin-sdk/config-schemaOpenClawSchema
plugin-sdk/provider-entrydefineSingleProviderPluginEntry
SubcaminhoExportações principais
plugin-sdk/channel-coredefineChannelPluginEntry, defineSetupPluginEntry, createChatChannelPlugin, createChannelPluginBase
plugin-sdk/config-schemaExportação do esquema Zod raiz de openclaw.json (OpenClawSchema)
plugin-sdk/channel-setupcreateOptionalChannelSetupSurface, createOptionalChannelSetupAdapter, createOptionalChannelSetupWizard, além de DEFAULT_ACCOUNT_ID, createTopLevelChannelDmPolicy, setSetupChannelEnabled, splitSetupEntries
plugin-sdk/setupAuxiliares compartilhados de assistente de configuração, prompts de allowlist, construtores de status de configuração
plugin-sdk/setup-runtimecreatePatchedAccountSetupAdapter, createEnvPatchedAccountSetupAdapter, createSetupInputPresenceValidator, noteChannelLookupFailure, noteChannelLookupSummary, promptResolvedAllowFrom, splitSetupEntries, createAllowlistSetupWizardProxy, createDelegatedSetupWizardProxy
plugin-sdk/setup-adapter-runtimecreateEnvPatchedAccountSetupAdapter
plugin-sdk/setup-toolsformatCliCommand, detectBinary, extractArchive, resolveBrewExecutable, formatDocsLink, CONFIG_DIR
plugin-sdk/account-coreAuxiliares de configuração/mecanismo de ação para múltiplas contas e auxiliares de fallback de conta padrão
plugin-sdk/account-idDEFAULT_ACCOUNT_ID, auxiliares de normalização de account-id
plugin-sdk/account-resolutionAuxiliares de busca de conta + fallback padrão
plugin-sdk/account-helpersAuxiliares restritos de lista/ação de conta
plugin-sdk/channel-pairingcreateChannelPairingController
plugin-sdk/channel-reply-pipelinecreateChannelReplyPipeline
plugin-sdk/channel-config-helperscreateHybridChannelConfigAdapter
plugin-sdk/channel-config-schemaTipos de esquema de configuração de canal
plugin-sdk/telegram-command-configAuxiliares de normalização/validação de comando personalizado do Telegram com fallback de contrato empacotado
plugin-sdk/channel-policyresolveChannelGroupRequireMention
plugin-sdk/channel-lifecyclecreateAccountStatusSink
plugin-sdk/inbound-envelopeAuxiliares compartilhados de rota de entrada + construtor de envelope
plugin-sdk/inbound-reply-dispatchAuxiliares compartilhados de registro e despacho de entrada
plugin-sdk/messaging-targetsAuxiliares de parsing/correspondência de alvo
plugin-sdk/outbound-mediaAuxiliares compartilhados de carregamento de mídia de saída
plugin-sdk/outbound-runtimeAuxiliares de identidade de saída/delegação de envio
plugin-sdk/thread-bindings-runtimeAuxiliares de ciclo de vida e adaptador de vínculo de thread
plugin-sdk/agent-media-payloadConstrutor legado de payload de mídia do agente
plugin-sdk/conversation-runtimeAuxiliares de vínculo de conversa/thread, pareamento e vínculo configurado
plugin-sdk/runtime-config-snapshotAuxiliar de snapshot de configuração de runtime
plugin-sdk/runtime-group-policyAuxiliares de resolução de política de grupo em runtime
plugin-sdk/channel-statusAuxiliares compartilhados de snapshot/resumo de status de canal
plugin-sdk/channel-config-primitivesPrimitivos restritos de esquema de configuração de canal
plugin-sdk/channel-config-writesAuxiliares de autorização de escrita de configuração de canal
plugin-sdk/channel-plugin-commonExportações de prelúdio compartilhadas para plugins de canal
plugin-sdk/allowlist-config-editAuxiliares de edição/leitura de configuração de allowlist
plugin-sdk/group-accessAuxiliares compartilhados de decisão de acesso de grupo
plugin-sdk/direct-dmAuxiliares compartilhados de autenticação/proteção de DM direta
plugin-sdk/interactive-runtimeAuxiliares de normalização/redução de payload de resposta interativa
plugin-sdk/channel-inboundAuxiliares de debounce, correspondência de menção e envelope
plugin-sdk/channel-send-resultTipos de resultado de resposta
plugin-sdk/channel-actionscreateMessageToolButtonsSchema, createMessageToolCardSchema
plugin-sdk/channel-targetsAuxiliares de parsing/correspondência de alvo
plugin-sdk/channel-contractTipos de contrato de canal
plugin-sdk/channel-feedbackConexão de feedback/reação
SubcaminhoExportações principais
plugin-sdk/provider-entrydefineSingleProviderPluginEntry
plugin-sdk/provider-setupAuxiliares curados de configuração de provedor local/hospedado pelo usuário
plugin-sdk/self-hosted-provider-setupAuxiliares focados de configuração de provedor auto-hospedado compatível com OpenAI
plugin-sdk/cli-backendPadrões de backend de CLI + constantes de watchdog
plugin-sdk/provider-auth-runtimeAuxiliares de resolução de chave de API em runtime para plugins de provedor
plugin-sdk/provider-auth-api-keyAuxiliares de onboarding/gravação de perfil de chave de API
plugin-sdk/provider-auth-resultConstrutor padrão de resultado de autenticação OAuth
plugin-sdk/provider-auth-loginAuxiliares compartilhados de login interativo para plugins de provedor
plugin-sdk/provider-env-varsAuxiliares de busca de variáveis de ambiente de autenticação de provedor
plugin-sdk/provider-authcreateProviderApiKeyAuthMethod, ensureApiKeyFromOptionEnvOrPrompt, upsertAuthProfile
plugin-sdk/provider-model-sharedProviderReplayFamily, buildProviderReplayFamilyHooks, normalizeModelCompat, construtores compartilhados de política de replay, auxiliares de endpoint de provedor e auxiliares de normalização de model-id como normalizeNativeXaiModelId
plugin-sdk/provider-catalog-sharedfindCatalogTemplate, buildSingleProviderApiKeyCatalog, supportsNativeStreamingUsageCompat, applyProviderNativeStreamingUsageCompat
plugin-sdk/provider-httpAuxiliares genéricos de capacidade HTTP/endpoint de provedor
plugin-sdk/provider-web-fetchAuxiliares de registro/cache de provedor de web-fetch
plugin-sdk/provider-web-searchAuxiliares de registro/cache/configuração de provedor de web-search
plugin-sdk/provider-toolsProviderToolCompatFamily, buildProviderToolCompatFamilyHooks, limpeza de esquema do Gemini + diagnósticos, e auxiliares de compatibilidade xAI como resolveXaiModelCompatPatch / applyXaiModelCompat
plugin-sdk/provider-usagefetchClaudeUsage e similares
plugin-sdk/provider-streamProviderStreamFamily, buildProviderStreamFamilyHooks, composeProviderStreamWrappers, tipos de encapsulamento de stream, e auxiliares compartilhados de encapsulamento para Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot
plugin-sdk/provider-onboardAuxiliares de patch de configuração de onboarding
plugin-sdk/global-singletonAuxiliares de singleton/mapa/cache locais ao processo
SubcaminhoExportações principais
plugin-sdk/command-authresolveControlCommandGate, auxiliares de registro de comando, auxiliares de autorização do remetente
plugin-sdk/approval-auth-runtimeAuxiliares de resolução de aprovador e autenticação de ação no mesmo chat
plugin-sdk/approval-client-runtimeAuxiliares de perfil/filtro de aprovação de exec nativo
plugin-sdk/approval-delivery-runtimeAdaptadores nativos de capacidade/entrega de aprovação
plugin-sdk/approval-native-runtimeAuxiliares nativos de alvo de aprovação + vínculo de conta
plugin-sdk/approval-reply-runtimeAuxiliares de payload de resposta para aprovação de exec/plugin
plugin-sdk/command-auth-nativeAuxiliares nativos de autenticação de comando + alvo de sessão nativa
plugin-sdk/command-detectionAuxiliares compartilhados de detecção de comando
plugin-sdk/command-surfaceAuxiliares de normalização de corpo de comando e superfície de comando
plugin-sdk/allow-fromformatAllowFromLowercase
plugin-sdk/security-runtimeAuxiliares compartilhados de confiança, bloqueio de DM, conteúdo externo e coleta de segredo
plugin-sdk/ssrf-policyAuxiliares de allowlist de host e política SSRF de rede privada
plugin-sdk/ssrf-runtimeAuxiliares de dispatcher fixado, fetch protegido por SSRF e política SSRF
plugin-sdk/secret-inputAuxiliares de parsing de entrada de segredo
plugin-sdk/webhook-ingressAuxiliares de requisição/alvo de webhook
plugin-sdk/webhook-request-guardsAuxiliares de tamanho do corpo/tempo limite de requisição
SubcaminhoExportações principais
plugin-sdk/runtimeAuxiliares amplos de runtime/logging/backup/instalação de plugin
plugin-sdk/runtime-envAuxiliares restritos de ambiente de runtime, logger, timeout, retry e backoff
plugin-sdk/runtime-storecreatePluginRuntimeStore
plugin-sdk/plugin-runtimeAuxiliares compartilhados de comando/hook/http/interativo de plugin
plugin-sdk/hook-runtimeAuxiliares compartilhados de pipeline de webhook/hook interno
plugin-sdk/lazy-runtimeAuxiliares de importação/vínculo de runtime lazy como createLazyRuntimeModule, createLazyRuntimeMethod e createLazyRuntimeSurface
plugin-sdk/process-runtimeAuxiliares de execução de processo
plugin-sdk/cli-runtimeAuxiliares de formatação, espera e versão de CLI
plugin-sdk/gateway-runtimeAuxiliares de cliente do gateway e patch de status de canal
plugin-sdk/config-runtimeAuxiliares de carregamento/gravação de configuração
plugin-sdk/telegram-command-configNormalização de nome/descrição de comando do Telegram e verificações de duplicidade/conflito, mesmo quando a superfície de contrato empacotada do Telegram não está disponível
plugin-sdk/approval-runtimeAuxiliares de aprovação de exec/plugin, construtores de capacidade de aprovação, auxiliares de autenticação/perfil, auxiliares nativos de roteamento/runtime
plugin-sdk/reply-runtimeAuxiliares compartilhados de runtime de entrada/resposta, fragmentação, despacho, heartbeat, planejador de resposta
plugin-sdk/reply-dispatch-runtimeAuxiliares restritos de despacho/finalização de resposta
plugin-sdk/reply-historyAuxiliares compartilhados de histórico de resposta em janela curta como buildHistoryContext, recordPendingHistoryEntry e clearHistoryEntriesIfEnabled
plugin-sdk/reply-referencecreateReplyReferencePlanner
plugin-sdk/reply-chunkingAuxiliares restritos de fragmentação de texto/markdown
plugin-sdk/session-store-runtimeAuxiliares de caminho e updated-at do armazenamento de sessão
plugin-sdk/state-pathsAuxiliares de caminho de diretório de estado/OAuth
plugin-sdk/routingAuxiliares de rota/session-key/vínculo de conta como resolveAgentRoute, buildAgentSessionKey e resolveDefaultAgentBoundAccountId
plugin-sdk/status-helpersAuxiliares compartilhados de resumo de status de canal/conta, padrões de estado de runtime e auxiliares de metadados de problema
plugin-sdk/target-resolver-runtimeAuxiliares compartilhados de resolução de alvo
plugin-sdk/string-normalization-runtimeAuxiliares de normalização de slug/string
plugin-sdk/request-urlExtrair URLs string de entradas semelhantes a fetch/request
plugin-sdk/run-commandExecutor de comando temporizado com resultados normalizados de stdout/stderr
plugin-sdk/param-readersLeitores comuns de parâmetros de ferramenta/CLI
plugin-sdk/tool-sendExtrair campos canônicos de alvo de envio de argumentos de ferramenta
plugin-sdk/temp-pathAuxiliares compartilhados de caminho temporário de download
plugin-sdk/logging-coreLogger de subsistema e auxiliares de ocultação
plugin-sdk/markdown-table-runtimeAuxiliares de modo de tabela Markdown
plugin-sdk/json-storePequenos auxiliares de leitura/gravação de estado JSON
plugin-sdk/file-lockAuxiliares de file-lock reentrante
plugin-sdk/persistent-dedupeAuxiliares de cache de deduplicação com persistência em disco
plugin-sdk/acp-runtimeAuxiliares de runtime/sessão ACP
plugin-sdk/agent-config-primitivesPrimitivos restritos de esquema de configuração de runtime do agente
plugin-sdk/boolean-paramLeitor flexível de parâmetro booleano
plugin-sdk/dangerous-name-runtimeAuxiliares de resolução de correspondência de nome perigoso
plugin-sdk/device-bootstrapAuxiliares de bootstrap de dispositivo e token de pareamento
plugin-sdk/extension-sharedPrimitivos auxiliares compartilhados de canal passivo e status
plugin-sdk/models-provider-runtimeAuxiliares de resposta para comando/provedor /models
plugin-sdk/skill-commands-runtimeAuxiliares de listagem de comandos de Skills
plugin-sdk/native-command-registryAuxiliares nativos de registro/construção/serialização de comando
plugin-sdk/provider-zai-endpointAuxiliares de detecção de endpoint Z.AI
plugin-sdk/infra-runtimeAuxiliares de evento do sistema/heartbeat
plugin-sdk/collection-runtimePequenos auxiliares de cache limitado
plugin-sdk/diagnostic-runtimeAuxiliares de sinalizador e evento de diagnóstico
plugin-sdk/error-runtimeGrafo de erro, formatação, auxiliares compartilhados de classificação de erro, isApprovalNotFoundError
plugin-sdk/fetch-runtimeAuxiliares de fetch encapsulado, proxy e busca fixada
plugin-sdk/host-runtimeAuxiliares de normalização de hostname e host SCP
plugin-sdk/retry-runtimeAuxiliares de configuração de retry e executor de retry
plugin-sdk/agent-runtimeAuxiliares de diretório/identidade/workspace do agente
plugin-sdk/directory-runtimeConsulta/deduplicação de diretório com suporte de configuração
plugin-sdk/keyed-async-queueKeyedAsyncQueue
SubcaminhoExportações principais
plugin-sdk/media-runtimeAuxiliares compartilhados de busca/transformação/armazenamento de mídia, além de construtores de payload de mídia
plugin-sdk/media-understandingTipos de provedor de entendimento de mídia, além de exportações auxiliares voltadas ao provedor para imagem/áudio
plugin-sdk/text-runtimeAuxiliares compartilhados de texto/markdown/logging como remoção de texto visível ao assistente, renderização/fragmentação/tabelas Markdown, auxiliares de ocultação, auxiliares de tags de diretiva e utilitários de texto seguro
plugin-sdk/text-chunkingAuxiliar de fragmentação de texto de saída
plugin-sdk/speechTipos de provedor de fala, além de auxiliares voltados ao provedor para diretiva, registro e validação
plugin-sdk/speech-coreTipos compartilhados de provedor de fala, registro, diretiva e auxiliares de normalização
plugin-sdk/realtime-transcriptionTipos de provedor de transcrição em tempo real e auxiliares de registro
plugin-sdk/realtime-voiceTipos de provedor de voz em tempo real e auxiliares de registro
plugin-sdk/image-generationTipos de provedor de geração de imagem
plugin-sdk/image-generation-coreTipos compartilhados de geração de imagem, failover, autenticação e auxiliares de registro
plugin-sdk/video-generationTipos de provedor/requisição/resultado de geração de vídeo
plugin-sdk/video-generation-coreTipos compartilhados de geração de vídeo, auxiliares de failover, busca de provedor e parsing de referência de modelo
plugin-sdk/webhook-targetsRegistro de alvos de webhook e auxiliares de instalação de rota
plugin-sdk/webhook-pathAuxiliares de normalização de caminho de webhook
plugin-sdk/web-mediaAuxiliares compartilhados de carregamento de mídia remota/local
plugin-sdk/zodzod reexportado para consumidores do Plugin SDK
plugin-sdk/testinginstallCommonResolveTargetErrorCases, shouldAckReaction
SubcaminhoExportações principais
plugin-sdk/memory-coreSuperfície auxiliar empacotada de memory-core para auxiliares de gerenciador/configuração/arquivo/CLI
plugin-sdk/memory-core-engine-runtimeFachada de runtime de índice/busca de memória
plugin-sdk/memory-core-host-engine-foundationExportações do engine base do host de memória
plugin-sdk/memory-core-host-engine-embeddingsExportações do engine de embeddings do host de memória
plugin-sdk/memory-core-host-engine-qmdExportações do engine QMD do host de memória
plugin-sdk/memory-core-host-engine-storageExportações do engine de armazenamento do host de memória
plugin-sdk/memory-core-host-multimodalAuxiliares multimodais do host de memória
plugin-sdk/memory-core-host-queryAuxiliares de consulta do host de memória
plugin-sdk/memory-core-host-secretAuxiliares de segredo do host de memória
plugin-sdk/memory-core-host-statusAuxiliares de status do host de memória
plugin-sdk/memory-core-host-runtime-cliAuxiliares de runtime de CLI do host de memória
plugin-sdk/memory-core-host-runtime-coreAuxiliares centrais de runtime do host de memória
plugin-sdk/memory-core-host-runtime-filesAuxiliares de arquivo/runtime do host de memória
plugin-sdk/memory-lancedbSuperfície auxiliar empacotada de memory-lancedb
FamíliaSubcaminhos atuaisUso pretendido
Browserplugin-sdk/browser-config-support, plugin-sdk/browser-supportAuxiliares de suporte para plugin empacotado de browser
Matrixplugin-sdk/matrix, plugin-sdk/matrix-helper, plugin-sdk/matrix-runtime-heavy, plugin-sdk/matrix-runtime-shared, plugin-sdk/matrix-runtime-surface, plugin-sdk/matrix-surface, plugin-sdk/matrix-thread-bindingsSuperfície auxiliar/runtime empacotada do Matrix
Lineplugin-sdk/line, plugin-sdk/line-core, plugin-sdk/line-runtime, plugin-sdk/line-surfaceSuperfície auxiliar/runtime empacotada do LINE
IRCplugin-sdk/irc, plugin-sdk/irc-surfaceSuperfície auxiliar empacotada do IRC
Auxiliares específicos de canalplugin-sdk/googlechat, plugin-sdk/zalouser, plugin-sdk/bluebubbles, plugin-sdk/bluebubbles-policy, plugin-sdk/mattermost, plugin-sdk/mattermost-policy, plugin-sdk/feishu-conversation, plugin-sdk/msteams, plugin-sdk/nextcloud-talk, plugin-sdk/nostr, plugin-sdk/tlon, plugin-sdk/twitchInterfaces auxiliares/de compatibilidade de canal empacotadas
Auxiliares específicos de autenticação/pluginplugin-sdk/github-copilot-login, plugin-sdk/github-copilot-token, plugin-sdk/diagnostics-otel, plugin-sdk/diffs, plugin-sdk/llm-task, plugin-sdk/thread-ownership, plugin-sdk/voice-callInterfaces auxiliares de recurso/plugin empacotadas; plugin-sdk/github-copilot-token atualmente exporta DEFAULT_COPILOT_API_BASE_URL, deriveCopilotApiBaseUrlFromToken e resolveCopilotApiToken

​
API de registro

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

​
Registro de capacidades

MétodoO que ele registra
api.registerProvider(...)Inferência de texto (LLM)
api.registerCliBackend(...)Backend local de inferência via 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 bidirecionais em tempo real
api.registerMediaUnderstandingProvider(...)Análise de imagem/áudio/vídeo
api.registerImageGenerationProvider(...)Geração de imagem
api.registerVideoGenerationProvider(...)Geração de vídeo
api.registerWebFetchProvider(...)Provedor de web fetch / scraping
api.registerWebSearchProvider(...)Busca na web

​
Ferramentas e comandos

MétodoO que ele registra
api.registerTool(tool, opts?)Ferramenta de agente (obrigatória ou { optional: true })
api.registerCommand(def)Comando personalizado (ignora o LLM)

​
Infraestrutura

MétodoO 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.registerCli(registrar, opts?)Subcomando de CLI
api.registerService(service)Serviço em segundo plano
api.registerInteractiveHandler(registration)Manipulador interativo
Namespaces administrativos reservados do núcleo (config.*, exec.approvals.*, wizard.*, update.*) sempre permanecem como operator.admin, mesmo que um plugin tente atribuir um escopo mais restrito ao método do gateway. Prefira prefixos específicos do plugin para métodos pertencentes ao plugin.

​
Metadados de registro de CLI

api.registerCli(registrar, opts?) aceita dois tipos de metadados de nível superior:
  • commands: raízes de comando explícitas pertencentes ao registrador
  • descriptors: descritores de comando em tempo de parsing usados para ajuda da CLI raiz, roteamento e registro lazy da CLI do plugin
Se você quiser que um comando de plugin permaneça lazy-loaded 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: "Gerenciar contas, verificação, dispositivos e estado de perfil do Matrix",
        hasSubcommands: true,
      },
    ],
  },
);
Use commands sozinho apenas quando você não precisar de registro lazy na CLI raiz. Esse caminho compatível com carregamento antecipado continua sendo suportado, mas não instala placeholders com base em descritor para carregamento lazy em tempo de parsing.

​
Registro de backend de CLI

api.registerCliBackend(...) permite que um plugin seja dono da configuração padrão de um backend local de CLI de IA, como claude-cli ou codex-cli.
  • O id do backend torna-se o prefixo do provedor em referências de modelo como claude-cli/opus.
  • A 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 a configuraçã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, normalizando formatos antigos de flags).

​
Slots exclusivos

MétodoO que ele registra
api.registerContextEngine(id, factory)Engine de contexto (um ativo por vez)
api.registerMemoryPromptSection(builder)Construtor de seção de prompt de memória
api.registerMemoryFlushPlan(resolver)Resolver de plano de flush de memória
api.registerMemoryRuntime(runtime)Adaptador de runtime de memória

​
Adaptadores de embedding de memória

MétodoO que ele registra
api.registerMemoryEmbeddingProvider(adapter)Adaptador de embedding de memória para o plugin ativo
  • registerMemoryPromptSection, registerMemoryFlushPlan e registerMemoryRuntime são exclusivos para plugins de memória.
  • 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 em relação a esses ids de adaptador registrados.

​
Eventos e ciclo de vida

MétodoO que ele faz
api.on(hookName, handler, opts?)Hook de ciclo de vida tipado
api.onConversationBindingResolved(handler)Callback de vínculo de conversa

​
Semântica de decisão de hook

  • before_tool_call: retornar { block: true } é terminal. Assim que algum manipulador define isso, manipuladores de prioridade inferior são ignorados.
  • before_tool_call: retornar { block: false } é tratado como ausência de decisão (igual a omitir block), não como sobrescrita.
  • before_install: retornar { block: true } é terminal. Assim que algum manipulador define isso, manipuladores de prioridade inferior são ignorados.
  • before_install: retornar { block: false } é tratado como ausência de decisão (igual a omitir block), não como sobrescrita.
  • message_sending: retornar { cancel: true } é terminal. Assim que algum manipulador define isso, manipuladores de prioridade inferior são ignorados.
  • message_sending: retornar { cancel: false } é tratado como ausência de decisão (igual a omitir cancel), não como sobrescrita.

​
Campos do objeto API

CampoTipoDescrição
api.idstringId do plugin
api.namestringNome de exibição
api.versionstring?Versão do plugin (opcional)
api.descriptionstring?Descrição do plugin (opcional)
api.sourcestringCaminho de origem do plugin
api.rootDirstring?Diretório raiz do plugin (opcional)
api.configOpenClawConfigSnapshot atual da configuração (snapshot ativo em memória do runtime quando disponível)
api.pluginConfigRecord<string, unknown>Configuração específica do plugin em plugins.entries.<id>.config
api.runtimePluginRuntimeAuxiliares de runtime
api.loggerPluginLoggerLogger com escopo (debug, info, warn, error)
api.registrationModePluginRegistrationModeModo de carregamento atual; "setup-runtime" é a janela leve de inicialização/configuração antes da entrada completa
api.resolvePath(input)(string) => stringResolve caminho relativo à raiz do plugin

​
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 para configuração (opcional)
Nunca importe seu próprio plugin por meio de openclaw/plugin-sdk/<your-plugin> no código de produção. Encaminhe importações internas por ./api.ts ou ./runtime-api.ts. O caminho do SDK é apenas o contrato externo.
Superfícies públicas de plugins empacotados carregadas por fachada (api.ts, runtime-api.ts, index.ts, setup-entry.ts e arquivos de entrada públicos semelhantes) agora preferem o snapshot ativo da configuração de runtime quando o OpenClaw já está em execução. Se ainda não existir um snapshot de runtime, elas recorrem ao arquivo de configuração resolvido em disco. Plugins de provedor também podem expor um barrel de contrato local restrito quando um auxiliar for intencionalmente específico do provedor e ainda não pertencer a um subcaminho genérico do SDK. Exemplo empacotado atual: o provedor Anthropic mantém seus auxiliares de stream do Claude em sua própria interface pública api.ts / contract-api.ts em vez de promover a lógica de cabeçalho beta da Anthropic e service_tier para um contrato genérico plugin-sdk/*. Outros exemplos empacotados atuais:
  • @openclaw/openai-provider: api.ts exporta construtores de provedor, auxiliares de modelo padrão e construtores de provedor em tempo real
  • @openclaw/openrouter-provider: api.ts exporta o construtor do provedor mais auxiliares de onboarding/configuração
O código de produção de extensões também deve evitar importações openclaw/plugin-sdk/<other-plugin>. Se um auxiliar for realmente compartilhado, promova-o para um subcaminho neutro do SDK como openclaw/plugin-sdk/speech, .../provider-model-shared ou outra superfície orientada a capacidade, em vez de acoplar dois plugins.

​
Relacionado