Pontos de entrada do Plugin

Todo plugin exporta um objeto de entrada padrão. O SDK fornece auxiliares para criá-los.

Para plugins instalados, package.json deve apontar o carregamento em tempo de execução para JavaScript compilado quando disponível:

{  "openclaw": {    "extensions": ["./src/index.ts"],    "runtimeExtensions": ["./dist/index.js"],    "setupEntry": "./src/setup-entry.ts",    "runtimeSetupEntry": "./dist/setup-entry.js"  }}

extensions e setupEntry continuam sendo entradas de código-fonte válidas para desenvolvimento em workspace e checkout git. runtimeExtensions e runtimeSetupEntry são preferidos quando o OpenClaw carrega um pacote instalado e permitem que pacotes npm evitem compilação TypeScript em tempo de execução. Entradas de runtime explícitas são obrigatórias: runtimeSetupEntry requer setupEntry, e artefatos runtimeExtensions ou runtimeSetupEntry ausentes fazem a instalação/descoberta falhar em vez de voltar silenciosamente ao código-fonte. Se um pacote instalado declarar apenas uma entrada de código-fonte TypeScript, o OpenClaw usará um par dist/*.js compilado correspondente quando ele existir e, depois, voltará ao código-fonte TypeScript.

Todos os caminhos de entrada devem permanecer dentro do diretório do pacote do plugin. Entradas de runtime e pares JavaScript compilados inferidos não tornam válido um caminho de código-fonte extensions ou setupEntry que escape do diretório.

defineToolPlugin

Importação: openclaw/plugin-sdk/tool-plugin

Para plugins simples que apenas adicionam ferramentas de agente. defineToolPlugin mantém o código-fonte de autoria pequeno, infere tipos de configuração e de parâmetros de ferramenta a partir de esquemas TypeBox, envolve valores de retorno simples no formato de resultado de ferramenta do OpenClaw e expõe metadados estáticos que openclaw plugins build grava no manifesto do plugin.

  export default defineToolPlugin({  id: "stock-quotes",  name: "Stock Quotes",  description: "Fetch stock quotes.",  configSchema: Type.Object({    apiKey: Type.Optional(Type.String({ description: "API key." })),  }),  tools: (tool) => [    tool({      name: "quote",      label: "Quote",      description: "Fetch a quote.",      parameters: Type.Object({        symbol: Type.String({ description: "Ticker symbol." }),      }),      execute: async ({ symbol }, config) => ({ symbol, hasKey: Boolean(config.apiKey) }),    }),  ],});

• configSchema é opcional. Quando omitido, o OpenClaw usa um esquema de objeto vazio estrito e o manifesto gerado ainda inclui configSchema.
• execute retorna uma string simples ou um valor serializável em JSON. O auxiliar o envolve como um resultado de ferramenta de texto com details.
• Os nomes de ferramentas são estáticos. openclaw plugins build deriva contracts.tools das ferramentas declaradas, para que autores não dupliquem nomes manualmente.
• O carregamento em runtime continua estrito. Plugins instalados ainda precisam de openclaw.plugin.json e openclaw.extensions em package.json; o OpenClaw não executa código do plugin para inferir dados de manifesto ausentes.

definePluginEntry

Importação: openclaw/plugin-sdk/plugin-entry

Para plugins de provedor, plugins de ferramenta avançados, plugins de hook e qualquer coisa que não seja um canal de mensagens.

 export default definePluginEntry({  id: "my-plugin",  name: "My Plugin",  description: "Short summary",  register(api) {    api.registerProvider({      /* ... */    });    api.registerTool({      /* ... */    });  },});

• id deve corresponder ao seu manifesto openclaw.plugin.json.
• kind é para slots exclusivos: "memory" ou "context-engine".
• configSchema pode ser uma função para avaliação preguiçosa.
• O OpenClaw resolve e memoiza esse esquema no primeiro acesso, então construtores de esquema caros são executados apenas uma vez.

defineChannelPluginEntry

Importação: openclaw/plugin-sdk/channel-core

Envolve definePluginEntry com fiação específica de canal. Chama automaticamente api.registerChannel({ plugin }), expõe uma costura opcional de metadados da CLI de ajuda raiz e bloqueia registerFull com base no modo de registro.

 export default defineChannelPluginEntry({  id: "my-channel",  name: "My Channel",  description: "Short summary",  plugin: myChannelPlugin,  setRuntime: setMyRuntime,  registerCliMetadata(api) {    api.registerCli(/* ... */);  },  registerFull(api) {    api.registerGatewayMethod(/* ... */);  },});

• setRuntime é chamado durante o registro para que você possa armazenar a referência de runtime (normalmente via createPluginRuntimeStore). Ele é ignorado durante a captura de metadados da CLI.
• registerCliMetadata é executado durante api.registrationMode === "cli-metadata", api.registrationMode === "discovery" e api.registrationMode === "full". Use-o como o lugar canônico para descritores de CLI pertencentes ao canal, para que a ajuda raiz não ative o canal, snapshots de descoberta incluam metadados de comandos estáticos e o registro normal de comandos da CLI permaneça compatível com carregamentos completos de plugin.
• O registro de descoberta não é ativador, mas não é livre de importação. O OpenClaw pode avaliar a entrada do plugin confiável e o módulo do plugin de canal para criar o snapshot, então mantenha importações de nível superior sem efeitos colaterais e coloque sockets, clientes, workers e serviços atrás de caminhos exclusivos de "full".
• registerFull só é executado quando api.registrationMode === "full". Ele é ignorado durante carregamento somente de setup.
• Assim como definePluginEntry, configSchema pode ser uma factory preguiçosa e o OpenClaw memoiza o esquema resolvido no primeiro acesso.
• Para comandos de CLI raiz pertencentes ao plugin, prefira api.registerCli(..., { descriptors: [...] }) quando quiser que o comando permaneça carregado de forma preguiçosa sem desaparecer da árvore de análise da CLI raiz. Para comandos de recurso de nó pareados, prefira api.registerNodeCliFeature(...) para que o comando fique em openclaw nodes. Para outros comandos de plugin aninhados, adicione parentPath e registre comandos no objeto program passado ao registrador; o OpenClaw o resolve para o comando pai antes de chamar o plugin. Para plugins de canal, prefira registrar esses descritores a partir de registerCliMetadata(...) e mantenha registerFull(...) focado em trabalho exclusivo de runtime.
• Se registerFull(...) também registrar métodos RPC do Gateway, mantenha-os em um prefixo específico do plugin. Namespaces reservados de administração do core (config.*, exec.approvals.*, wizard.*, update.*) são sempre forçados para operator.admin.

defineSetupPluginEntry

Importação: openclaw/plugin-sdk/channel-core

Para o arquivo leve setup-entry.ts. Retorna apenas { plugin }, sem fiação de runtime ou CLI.

 export default defineSetupPluginEntry(myChannelPlugin);

O OpenClaw carrega isso em vez da entrada completa quando um canal está desabilitado, não configurado ou quando o carregamento diferido está ativado. Veja Setup e configuração para saber quando isso importa.

Na prática, combine defineSetupPluginEntry(...) com as famílias estreitas de auxiliares de setup:

• openclaw/plugin-sdk/setup-runtime para auxiliares de setup seguros para runtime, como createSetupTranslator, adaptadores de patch de setup seguros para importação, saída de notas de lookup, promptResolvedAllowFrom, splitSetupEntries e proxies de setup delegados
• openclaw/plugin-sdk/channel-setup para superfícies de setup de instalação opcional
• openclaw/plugin-sdk/setup-tools para auxiliares de setup/instalação de CLI/arquivo/docs

Mantenha SDKs pesados, registro de CLI e serviços de runtime de longa duração na entrada completa.

Canais de workspace incluídos no pacote que separam superfícies de setup e de runtime podem usar defineBundledChannelSetupEntry(...) de openclaw/plugin-sdk/channel-entry-contract. Esse contrato permite que a entrada de setup mantenha exportações de plugin/secrets seguras para setup enquanto ainda expõe um setter de runtime:

 export default defineBundledChannelSetupEntry({  importMetaUrl: import.meta.url,  plugin: {    specifier: "./channel-plugin-api.js",    exportName: "myChannelPlugin",  },  runtime: {    specifier: "./runtime-api.js",    exportName: "setMyChannelRuntime",  },  registerSetupRuntime(api) {    api.registerHttpRoute({      path: "/my-channel/events",      auth: "plugin",      handler: async (req, res) => {        /* setup-safe route */      },    });  },});

Use esse contrato incluído no pacote apenas quando fluxos de setup realmente precisarem de um setter de runtime leve ou de uma superfície do Gateway segura para setup antes de a entrada completa do canal carregar. registerSetupRuntime é executado apenas para carregamentos "setup-runtime"; mantenha-o limitado a rotas ou métodos apenas de configuração que precisam existir antes da ativação completa diferida.

Modo de registro

api.registrationMode informa ao seu plugin como ele foi carregado:

defineChannelPluginEntry lida com essa divisão automaticamente. Se você usar definePluginEntry diretamente para um canal, verifique o modo por conta própria:

register(api) {  if (    api.registrationMode === "cli-metadata" ||    api.registrationMode === "discovery" ||    api.registrationMode === "full"  ) {    api.registerCli(/* ... */);    if (api.registrationMode === "cli-metadata") return;  }   api.registerChannel({ plugin: myPlugin });  if (api.registrationMode !== "full") return;   // Heavy runtime-only registrations  api.registerService(/* ... */);}

O modo de descoberta cria um snapshot de registro sem ativação. Ele ainda pode avaliar a entrada do Plugin e o objeto de Plugin de canal para que o OpenClaw possa registrar capacidades de canal e descritores estáticos da CLI. Trate a avaliação de módulo na descoberta como confiável, mas leve: sem clientes de rede, subprocessos, listeners, conexões de banco de dados, workers em segundo plano, leituras de credenciais ou outros efeitos colaterais de runtime ativo no nível superior.

Trate "setup-runtime" como a janela em que as superfícies de inicialização apenas de configuração devem existir sem reentrar no runtime completo do canal empacotado. Boas opções são registro de canal, rotas HTTP seguras para configuração, métodos do Gateway seguros para configuração e helpers de configuração delegados. Serviços pesados em segundo plano, registradores da CLI e bootstraps de SDKs de provedor/cliente ainda pertencem a "full".

Para registradores da CLI especificamente:

• use descriptors quando o registrador possuir um ou mais comandos raiz e você quiser que o OpenClaw carregue o módulo real da CLI sob demanda na primeira invocação
• certifique-se de que esses descritores cubram cada raiz de comando de nível superior exposta pelo registrador
• mantenha nomes de comando de descritores com letras, números, hífen e sublinhado, começando com uma letra ou número; o OpenClaw rejeita nomes de descritores fora desse formato e remove sequências de controle de terminal das descrições antes de renderizar a ajuda
• use apenas commands somente para caminhos de compatibilidade ansiosos

Formatos de Plugin

O OpenClaw classifica plugins carregados pelo comportamento de registro deles:

Use openclaw plugins inspect <id> para ver o formato de um Plugin.

Relacionados

• Visão geral do SDK - API de registro e referência de subcaminhos
• Helpers de runtime - api.runtime e createPluginRuntimeStore
• Configuração e configuração - manifesto, entrada de configuração, carregamento adiado
• Plugins de canal - criação do objeto ChannelPlugin
• Plugins de provedor - registro de provedor e hooks