Visão geral do SDK de Plugin

​

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

​

API de registro

​

Registro de capacidades

​

Ferramentas e comandos

agentPromptGuidance: [
  "Global command hint.",
  { text: "Only show this in the main OpenClaw prompt.", surfaces: ["openclaw_main"] },
];

​

Infraestrutura

​

Hooks do host para Plugins de fluxo de trabalho

api.session.controls.registerControlUiDescriptor({
  surface: "tab",
  id: "logbook",
  label: "Diário de bordo",
  description: "Seu dia como uma linha do tempo, criada a partir de capturas de tela.",
  icon: "sun",
  group: "control",
  requiredScopes: ["operator.write"],
});

• 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(...)

• Plugins externos podem controlar extensões de sessão, descritores de interface, comandos, metadados de ferramentas, injeções no próximo turno e hooks normais.
• As políticas confiáveis de ferramentas são executadas antes dos hooks comuns before_tool_call e são confiadas pelo host. As políticas integradas são executadas primeiro; as políticas de Plugins instalados exigem habilitação explícita, além de seus IDs locais em contracts.trustedToolPolicies, e são executadas em seguida, na ordem de carregamento dos Plugins. Os IDs das políticas têm escopo restrito ao Plugin que as registra.
• A propriedade de comandos reservados é exclusiva de Plugins integrados. Plugins externos devem usar seus próprios nomes de comandos ou aliases.
• allowPromptInjection=false desabilita hooks que alteram o prompt, incluindo agent_turn_prepare, before_prompt_build, heartbeat_prompt_contribution, campos de prompt do before_agent_start legado e enqueueNextTurnInjection.

​

Registro de descoberta 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() };
  },
});

​

Metadados de registro da CLI

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

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,
      },
    ],
  },
);

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,
      },
    ],
  },
);

​

Registro de backend da CLI

• O id do backend se torna o prefixo do provedor em referências de modelo como my-cli/gpt-5.
• 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 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 pertençam ao dialeto da CLI, como mapear níveis de raciocínio do OpenClaw para uma flag nativa de esforço. O hook recebe ctx.executionMode; use "side-question" para adicionar flags de isolamento nativas do backend para chamadas efêmeras de /btw. Se essas flags desabilitarem de forma confiável as ferramentas nativas de uma CLI que, de outra forma, as manteria sempre ativas, declare também sideQuestionToolMode: "disabled".
• Backends que podem desabilitar todas as ferramentas nativas para uma execução específica podem declarar nativeToolMode: "selectable". Chamadas restritas transmitem uma tupla ctx.toolAvailability.native vazia, além de uma lista de permissões MCP exata e isolada do host; resolveExecutionArgs deve impor ambas no argv final, seja em uma execução nova ou retomada. O OpenClaw falha de forma fechada se o backend não puder fazer isso.

​

Slots exclusivos

​

Adaptadores obsoletos de embedding de memória

• registerMemoryCapability é a API exclusiva preferencial 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 versões legadas.
• MemoryFlushPlan.model pode fixar o turno de liberação em uma referência exata de provider/model, como ollama/qwen3:8b, sem herdar a cadeia de fallback ativa.
• registerMemoryEmbeddingProvider está obsoleto. Novos provedores de embedding devem usar api.registerEmbeddingProvider(...) e contracts.embeddingProviders.
• Provedores existentes específicos de memória continuam funcionando durante a janela de migração, mas a inspeção de plugins relata isso como dívida de compatibilidade para plugins não integrados.

​

Eventos e ciclo de vida

​

Semântica de decisão dos hooks

• before_tool_call: retornar { block: true } é terminal. Assim que qualquer manipulador o definir, os manipuladores de prioridade inferior serã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 qualquer manipulador o definir, os manipuladores de prioridade inferior serã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 qualquer manipulador assumir o despacho, os manipuladores de prioridade inferior e o caminho padrão de despacho do modelo serão ignorados.
• message_sending: retornar { cancel: true } é terminal. Assim que qualquer manipulador o definir, os manipuladores de prioridade inferior serão ignorados.
• message_sending: retornar { cancel: false } é tratado como nenhuma decisão (o mesmo que omitir cancel), não como uma substituição.
• message_received: use o campo tipado threadId quando precisar rotear threads/tópicos de entrada. Reserve metadata para dados adicionais específicos do canal.
• message_sending: use os 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 o estado de inicialização pertencente ao Gateway, em vez de depender dos hooks internos gateway:startup. O Cron ainda pode estar sendo carregado nesse momento.
• cron_reconciled: reconstrua uma projeção externa completa do Cron após a inicialização ou o recarregamento do agendador. Ela inclui reason e o estado efetivo de enabled, inclusive enabled: false, enquanto ctx.getCron?.() retorna o agendador reconciliado exato. Passe ctx.abortSignal ao trabalho de projeção durável; ele é abortado quando esse instantâneo do agendador é substituído ou o Gateway é fechado.
• cron_changed: observe as alterações no ciclo de vida do Cron pertencente ao Gateway. Os eventos scheduled e removed são indicações de reconciliação pós-confirmação, não um registro ordenado de alterações. O event.nextRunAtMs de um evento agendado fica ausente quando a tarefa não tem uma próxima ativação; um evento removido ainda contém o instantâneo da tarefa excluída.

​

Campos do objeto da API

​

Convenção de módulos internos

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

• Anthropic: interface pública api.ts / contract-api.ts para auxiliares de cabeçalho beta e de fluxo service_tier do Claude.
• @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 de provedor e auxiliares de integração/configuração.

​

Relacionados