​

Visão geral do SDK de plugins

​

Convenção de importação

import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";

​

Referência de subcaminhos

​

Entrada de plugin

​

API de registro

​

Registro de capacidade

​

Ferramentas e comandos

​

Infraestrutura

​

Metadados de registro da CLI

• commands: raízes explícitas de comando 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

api.registerCli(
  async ({ program }) => {
    const { registerMatrixCli } = await import("./src/cli.js");
    registerMatrixCli({ program });
  },
  {
    descriptors: [
      {
        name: "matrix",
        description: "Gerencie contas, verificação, dispositivos e estado de perfil do Matrix",
        hasSubcommands: true,
      },
    ],
  },
);

​

Registro de backend da CLI

• O id do backend se torna o prefixo do provedor em refs de modelo como codex-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 regravações de compatibilidade após a mesclagem (por exemplo, normalizar formatos antigos de flag).

​

Slots exclusivos

​

Adapters de embeddings de memória

• registerMemoryCapability é a API preferida de plugin de memória exclusiva.
• 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 de plugin de memória compatíveis com o legado.
• registerMemoryEmbeddingProvider permite que o plugin de memória ativo registre um ou mais ids de adapter de embeddings (por exemplo openai, gemini ou um id personalizado definido pelo plugin).
• A configuração do usuário, como agents.defaults.memorySearch.provider e agents.defaults.memorySearch.fallback, é resolvida em relação a esses ids de adapter registrados.

​

Eventos e ciclo de vida

​

Semântica de decisão de hooks

• before_tool_call: retornar { block: true } é terminal. Assim que algum handler definir isso, handlers de prioridade mais baixa são ignorados.
• before_tool_call: retornar { block: false } é tratado como nenhuma decisão (o mesmo que omitir block), não como uma substituição.
• before_install: retornar { block: true } é terminal. Assim que algum handler definir isso, handlers de prioridade mais baixa são ignorados.
• before_install: retornar { block: false } é tratado como nenhuma decisão (o mesmo que omitir block), não como uma substituição.
• reply_dispatch: retornar { handled: true, ... } é terminal. Assim que algum handler assumir o dispatch, handlers de prioridade mais baixa e o caminho padrão de dispatch do modelo são ignorados.
• message_sending: retornar { cancel: true } é terminal. Assim que algum handler definir isso, handlers de prioridade mais baixa são ignorados.
• message_sending: retornar { cancel: false } é tratado como nenhuma decisão (o mesmo que omitir cancel), não como uma substituição.

​

Campos do objeto API

​

Convenção de módulo interno

my-plugin/
  api.ts            # Exportações públicas para consumidores externos
  runtime-api.ts    # Exportações internas apenas de runtime
  index.ts          # Ponto de entrada do plugin
  setup-entry.ts    # Entrada leve apenas para configuração (opcional)

• @openclaw/openai-provider: api.ts exporta builders de provedor, helpers de modelo padrão e builders de provedor realtime
• @openclaw/openrouter-provider: api.ts exporta o builder de provedor mais helpers de onboarding/configuração

​

Relacionado

• Pontos de entrada — opções de definePluginEntry e defineChannelPluginEntry
• Helpers de runtime — referência completa do namespace api.runtime
• Configuração e setup — empacotamento, manifests, schemas de configuração
• Testing — utilitários de teste e regras de lint
• Migração do SDK — migração de superfícies descontinuadas
• Internals de plugins — arquitetura profunda e modelo de capacidade