Internos da arquitetura de Plugin

​

Pipeline de carregamento

1. descobre raízes de plugins candidatas
2. lê manifestos de bundles nativos ou compatíveis e metadados de pacote
3. rejeita candidatos inseguros
4. normaliza a configuração de plugins (plugins.enabled, allow, deny, entries, slots, load.paths)
5. decide a ativação de cada candidato
6. carrega módulos nativos habilitados: módulos empacotados integrados usam um carregador nativo; código-fonte TypeScript local de terceiros usa o fallback emergencial Jiti
7. chama hooks nativos register(api) e coleta registros no registro de plugins
8. expõe o registro a comandos/superfícies de runtime

​

Comportamento com manifesto primeiro

• identificar o plugin
• descobrir canais/skills/esquema de configuração declarados ou recursos do bundle
• validar plugins.entries.<id>.config
• complementar rótulos/placeholders da Control UI
• mostrar metadados de instalação/catálogo
• preservar descritores baratos de ativação e setup sem carregar o runtime do plugin

• o carregamento da CLI restringe aos plugins que possuem o comando primário solicitado
• a resolução de setup/plugin de canal restringe aos plugins que possuem o id de canal solicitado
• a resolução explícita de setup/runtime de provedor restringe aos plugins que possuem o id de provedor solicitado
• o planejamento de inicialização do Gateway usa activation.onStartup para importações explícitas na inicialização e opt-outs de inicialização; plugins sem metadados de inicialização carregam apenas por acionadores de ativação mais restritos

​

Limite do cache de plugins

• PluginLoaderCacheState e registros de runtime ativos compatíveis
• caches de jiti/módulos e caches de carregador de superfície pública usados para evitar importar repetidamente a mesma superfície de runtime
• caches de sistema de arquivos para artefatos de plugin instalados
• mapas de vida curta por chamada para normalização de caminhos ou resolução de duplicatas

• resultados de descoberta
• registros diretos de manifestos
• registros de manifestos reconstruídos a partir do índice de plugins instalados
• busca de proprietário de provedor, supressão de modelo, política de provedor ou metadados de artefato público
• qualquer outra resposta derivada de manifesto em que um manifesto, índice instalado ou caminho de carregamento alterado deva ficar visível na próxima leitura de metadados

​

Modelo de registro

• registros de plugin (identidade, fonte, origem, status, diagnósticos)
• ferramentas
• hooks legados e hooks tipados
• canais
• provedores
• handlers RPC do gateway
• rotas HTTP
• registradores de CLI
• serviços em segundo plano
• comandos pertencentes a plugins

• módulo de plugin -> registro no registry
• runtime do core -> consumo do registry

​

Callbacks de vinculação de conversa

export default {
  id: "my-plugin",
  register(api) {
    api.onConversationBindingResolved(async (event) => {
      if (event.status === "approved") {
        // A binding now exists for this plugin + conversation.
        console.log(event.binding?.conversationId);
        return;
      }

      // The request was denied; clear any local pending state.
      console.log(event.request.conversation.conversationId);
    });
  },
};

• status: "approved" ou "denied"
• decision: "allow-once", "allow-always" ou "deny"
• binding: a vinculação resolvida para solicitações aprovadas
• request: o resumo da solicitação original, dica de desvinculação, id do remetente e metadados da conversa

​

Hooks de runtime de provedores

• Metadados do manifesto para consulta barata antes do runtime: setup.providers[].envVars, compatibilidade obsoleta providerAuthEnvVars, providerAuthAliases, providerAuthChoices e channelEnvVars.
• Hooks em tempo de configuração: catalog (discovery legado) mais applyConfigDefaults.
• Hooks de runtime: mais de 40 hooks opcionais que cobrem autenticação, resolução de modelo, encapsulamento de stream, níveis de raciocínio, política de replay e endpoints de uso. Veja a lista completa em Ordem e uso dos hooks.

​

Ordem e uso dos hooks

​

Exemplo de provedor

api.registerProvider({
  id: "example-proxy",
  label: "Example Proxy",
  auth: [],
  catalog: {
    order: "simple",
    run: async (ctx) => {
      const apiKey = ctx.resolveProviderApiKey("example-proxy").apiKey;
      if (!apiKey) {
        return null;
      }
      return {
        provider: {
          baseUrl: "https://proxy.example.com/v1",
          apiKey,
          api: "openai-completions",
          models: [{ id: "auto", name: "Auto" }],
        },
      };
    },
  },
  resolveDynamicModel: (ctx) => ({
    id: ctx.modelId,
    name: ctx.modelId,
    provider: "example-proxy",
    api: "openai-completions",
    baseUrl: "https://proxy.example.com/v1",
    reasoning: false,
    input: ["text"],
    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
    contextWindow: 128000,
    maxTokens: 8192,
  }),
  prepareRuntimeAuth: async (ctx) => {
    const exchanged = await exchangeToken(ctx.apiKey);
    return {
      apiKey: exchanged.token,
      baseUrl: exchanged.baseUrl,
      expiresAt: exchanged.expiresAt,
    };
  },
  resolveUsageAuth: async (ctx) => {
    const auth = await ctx.resolveOAuthToken();
    return auth ? { token: auth.token } : null;
  },
  fetchUsageSnapshot: async (ctx) => {
    return await fetchExampleProxyUsage(ctx.token, ctx.timeoutMs, ctx.fetchFn);
  },
});

​

Exemplos integrados

​

Auxiliares de runtime

const clip = await api.runtime.tts.textToSpeech({
  text: "Hello from OpenClaw",
  cfg: api.config,
});

const result = await api.runtime.tts.textToSpeechTelephony({
  text: "Hello from OpenClaw",
  cfg: api.config,
});

const voices = await api.runtime.tts.listVoices({
  provider: "elevenlabs",
  cfg: api.config,
});

• textToSpeech retorna o payload normal de saída de TTS do core para superfícies de arquivo/nota de voz.
• Usa a configuração messages.tts do core e a seleção de provedor.
• Retorna buffer de áudio PCM + taxa de amostragem. Plugins precisam reamostrar/codificar para provedores.
• listVoices é opcional por provedor. Use-o para seletores de voz ou fluxos de configuração pertencentes ao fornecedor.
• Listagens de vozes podem incluir metadados mais ricos, como localidade, gênero e tags de personalidade para seletores conscientes de provedor.
• OpenAI e ElevenLabs são compatíveis com telefonia hoje. Microsoft não é.

api.registerSpeechProvider({
  id: "acme-speech",
  label: "Acme Speech",
  isConfigured: ({ config }) => Boolean(config.messages?.tts),
  synthesize: async (req) => {
    return {
      audioBuffer: Buffer.from([]),
      outputFormat: "mp3",
      fileExtension: ".mp3",
      voiceCompatible: false,
    };
  },
});

• Mantenha a política, o fallback e a entrega de respostas de TTS no core.
• Use provedores de fala para comportamento de síntese pertencente ao fornecedor.
• A entrada legada edge da Microsoft é normalizada para o id de provedor microsoft.
• O modelo de propriedade preferido é orientado por empresa: um plugin de fornecedor pode ser dono de provedores de texto, fala, imagem e mídia futura conforme o OpenClaw adiciona esses contratos de capacidade.

api.registerMediaUnderstandingProvider({
  id: "google",
  capabilities: ["image", "audio", "video"],
  describeImage: async (req) => ({ text: "..." }),
  transcribeAudio: async (req) => ({ text: "..." }),
  describeVideo: async (req) => ({ text: "..." }),
});

• Mantenha orquestração, fallback, configuração e ligação de canais no core.
• Mantenha o comportamento do fornecedor no plugin de provedor.
• A expansão aditiva deve permanecer tipada: novos métodos opcionais, novos campos opcionais de resultado, novas capacidades opcionais.
• A geração de vídeo já segue o mesmo padrão:
  • o core é dono do contrato de capacidade e do auxiliar de runtime
  • plugins de fornecedor registram api.registerVideoGenerationProvider(...)
  • plugins de recurso/canal consomem api.runtime.videoGeneration.*

const image = await api.runtime.mediaUnderstanding.describeImageFile({
  filePath: "/tmp/inbound-photo.jpg",
  cfg: api.config,
  agentDir: "/tmp/agent",
});

const video = await api.runtime.mediaUnderstanding.describeVideoFile({
  filePath: "/tmp/inbound-video.mp4",
  cfg: api.config,
});

const extraction = await api.runtime.mediaUnderstanding.extractStructuredWithModel({
  provider: "codex",
  model: "gpt-5.5",
  input: [
    {
      type: "image",
      buffer: receiptImageBuffer,
      fileName: "receipt.png",
      mime: "image/png",
    },
    { type: "text", text: "Use the printed fields as the source of truth." },
  ],
  instructions: "Return entities and searchable tags.",
  schemaName: "example.evidence",
  jsonSchema: {
    type: "object",
    properties: {
      entities: { type: "array", items: { type: "string" } },
      tags: { type: "array", items: { type: "string" } },
    },
  },
  cfg: api.config,
});

const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({
  filePath: "/tmp/inbound-audio.ogg",
  cfg: api.config,
  // Optional when MIME cannot be inferred reliably:
  mime: "audio/ogg",
});

• api.runtime.mediaUnderstanding.* é a superfície compartilhada preferida para compreensão de imagem/áudio/vídeo.
• extractStructuredWithModel(...) é o ponto de contato voltado a plugins para extração limitada, pertencente ao provedor e centrada em imagem. Inclua pelo menos uma entrada de imagem; entradas de texto são contexto suplementar. plugins de produto são donos de suas rotas e esquemas, enquanto o OpenClaw é dono da fronteira de provedor/runtime.
• Usa a configuração de áudio de compreensão de mídia do core (tools.media.audio) e a ordem de fallback de provedores.
• Retorna { text: undefined } quando nenhuma saída de transcrição é produzida (por exemplo, entrada ignorada/sem suporte).
• api.runtime.stt.transcribeAudioFile(...) permanece como alias de compatibilidade.

const result = await api.runtime.subagent.run({
  sessionKey: "agent:main:subagent:search-helper",
  message: "Expand this query into focused follow-up searches.",
  provider: "openai",
  model: "gpt-4.1-mini",
  deliver: false,
});

• provider e model são substituições opcionais por execução, não alterações persistentes de sessão.
• O OpenClaw só honra esses campos de substituição para chamadores confiáveis.
• Para execuções de fallback pertencentes a plugins, operadores precisam optar por isso com plugins.entries.<id>.subagent.allowModelOverride: true.
• Use plugins.entries.<id>.subagent.allowedModels para restringir plugins confiáveis a destinos canônicos específicos provider/model, ou "*" para permitir explicitamente qualquer destino.
• Execuções de subagentes de plugins não confiáveis ainda funcionam, mas solicitações de substituição são rejeitadas em vez de cair silenciosamente no fallback.
• Sessões de subagente criadas por plugins são marcadas com o id do plugin criador. O fallback api.runtime.subagent.deleteSession(...) pode excluir apenas essas sessões de propriedade dele; a exclusão arbitrária de sessões ainda exige uma requisição Gateway com escopo de administrador.

const providers = api.runtime.webSearch.listProviders({
  config: api.config,
});

const result = await api.runtime.webSearch.search({
  config: api.config,
  args: {
    query: "OpenClaw plugin runtime helpers",
    count: 5,
  },
});

• Mantenha seleção de provedor, resolução de credenciais e semântica de requisição compartilhada no core.
• Use provedores de pesquisa na web para transportes de pesquisa específicos de fornecedor.
• api.runtime.webSearch.* é a superfície compartilhada preferida para plugins de recurso/canal que precisam de comportamento de pesquisa sem depender do wrapper da ferramenta do agente.

​

api.runtime.imageGeneration

const result = await api.runtime.imageGeneration.generate({
  config: api.config,
  args: { prompt: "A friendly lobster mascot", size: "1024x1024" },
});

const providers = api.runtime.imageGeneration.listProviders({
  config: api.config,
});

• generate(...): gera uma imagem usando a cadeia configurada de provedores de geração de imagens.
• listProviders(...): lista os provedores de geração de imagens disponíveis e suas capacidades.

​

Rotas HTTP do Gateway

api.registerHttpRoute({
  path: "/acme/webhook",
  auth: "plugin",
  match: "exact",
  handler: async (_req, res) => {
    res.statusCode = 200;
    res.end("ok");
    return true;
  },
});

• path: caminho da rota sob o servidor HTTP do Gateway.
• auth: obrigatório. Use "gateway" para exigir a autenticação normal do Gateway, ou "plugin" para autenticação/verificação de Webhook gerenciada pelo Plugin.
• match: opcional. "exact" (padrão) ou "prefix".
• replaceExisting: opcional. Permite que o mesmo Plugin substitua seu próprio registro de rota existente.
• handler: retorne true quando a rota tiver tratado a solicitação.

• api.registerHttpHandler(...) foi removido e causará um erro de carregamento do Plugin. Use api.registerHttpRoute(...) em vez disso.
• As rotas do Plugin devem declarar auth explicitamente.
• Conflitos exatos de path + match são rejeitados, a menos que replaceExisting: true, e um Plugin não pode substituir a rota de outro Plugin.
• Rotas sobrepostas com níveis de auth diferentes são rejeitadas. Mantenha cadeias de passagem exact/prefix apenas no mesmo nível de auth.
• Rotas com auth: "plugin" não recebem escopos de runtime do operador automaticamente. Elas são para Webhooks/verificação de assinatura gerenciados pelo Plugin, não para chamadas privilegiadas de auxiliares do Gateway.
• Rotas com auth: "gateway" rodam dentro de um escopo de runtime de solicitação do Gateway, mas esse escopo é intencionalmente conservador:
  • autenticação bearer por segredo compartilhado (gateway.auth.mode = "token" / "password") mantém os escopos de runtime de rotas do Plugin fixados em operator.write, mesmo que o chamador envie x-openclaw-scopes
  • modos HTTP confiáveis com identidade (por exemplo, trusted-proxy ou gateway.auth.mode = "none" em um ingresso privado) respeitam x-openclaw-scopes somente quando o cabeçalho está explicitamente presente
  • se x-openclaw-scopes estiver ausente nessas solicitações de rota do Plugin com identidade, o escopo de runtime volta para operator.write
• Regra prática: não assuma que uma rota de Plugin autenticada pelo Gateway é uma superfície administrativa implícita. Se sua rota precisar de comportamento exclusivo para administradores, exija um modo de autenticação com identidade e documente o contrato explícito do cabeçalho x-openclaw-scopes.

​

Caminhos de importação do SDK de Plugin

• index.js — entrada do Plugin empacotado
• api.js — barrel de auxiliares/tipos
• runtime-api.js — barrel somente de runtime
• setup-entry.js — entrada de Plugin de setup

​

Esquemas de ferramentas de mensagem

• presentation para blocos de apresentação semântica (text, context, divider, buttons, select)
• delivery-pin para solicitações de entrega fixada

​

Resolução de destino de canal

• messaging.inferTargetChatType({ to }) decide se um destino normalizado deve ser tratado como direct, group ou channel antes da consulta ao diretório.
• messaging.targetResolver.looksLikeId(raw, normalized) informa ao core se uma entrada deve ir direto para a resolução semelhante a id em vez da busca no diretório.
• messaging.targetResolver.reservedLiterals lista palavras simples que são referências de canal/sessão para esse provedor. A resolução preserva entradas de diretório configuradas antes de rejeitar literais reservados e, então, falha de forma fechada em uma ausência no diretório.
• messaging.targetResolver.resolveTarget(...) é o fallback do Plugin quando o core precisa de uma resolução final pertencente ao provedor após a normalização ou após uma ausência no diretório.
• messaging.resolveOutboundSessionRoute(...) possui a construção de rota de sessão específica do provedor depois que um destino é resolvido.

• Use inferTargetChatType para decisões de categoria que devem acontecer antes de pesquisar pares/grupos.
• Use looksLikeId para verificações de “trate isto como um id de destino explícito/nativo”.
• Use resolveTarget para fallback de normalização específico do provedor, não para busca ampla no diretório.
• Mantenha ids nativos do provedor, como ids de chat, ids de thread, JIDs, handles e ids de sala dentro de valores target ou parâmetros específicos do provedor, não em campos genéricos do SDK.

​

Diretórios baseados em configuração

• pares de DM orientados por allowlist
• mapas configurados de canal/grupo
• fallbacks de diretório estático com escopo de conta

• filtragem de consultas
• aplicação de limite
• auxiliares de desduplicação/normalização
• construção de ChannelDirectoryEntry[]

​

Catálogos de provedores

• { provider } para uma entrada de provedor
• { providers } para várias entradas de provedor

• simple: provedores simples por chave de API ou env
• profile: provedores que aparecem quando existem perfis de autenticação
• paired: provedores que sintetizam várias entradas de provedor relacionadas
• late: última passagem, após outros provedores implícitos

• discovery ainda funciona como alias legado, mas emite um aviso de depreciação
• se tanto catalog quanto discovery forem registrados, o OpenClaw usa catalog
• augmentModelCatalog está obsoleto; provedores empacotados devem publicar linhas suplementares por meio de registerModelCatalogProvider

​

Inspeção de canal somente leitura

• resolveAccount(...) é o caminho de runtime. Ele pode assumir que as credenciais estão totalmente materializadas e pode falhar rapidamente quando segredos obrigatórios estão ausentes.
• Caminhos de comando somente leitura, como openclaw status, openclaw status --all, openclaw channels status, openclaw channels resolve e fluxos de reparo de doctor/configuração não devem precisar materializar credenciais de runtime apenas para descrever a configuração.

• Retorne apenas o estado descritivo da conta.
• Preserve enabled e configured.
• Inclua campos de origem/status de credencial quando relevante, como:
  • tokenSource, tokenStatus
  • botTokenSource, botTokenStatus
  • appTokenSource, appTokenStatus
  • signingSecretSource, signingSecretStatus
• Você não precisa retornar valores brutos de token apenas para relatar disponibilidade somente leitura. Retornar tokenStatus: "available" (e o campo de origem correspondente) é suficiente para comandos de estilo status.
• Use configured_unavailable quando uma credencial estiver configurada via SecretRef, mas indisponível no caminho de comando atual.

​

Pacotes de pacotes

{
  "name": "my-pack",
  "openclaw": {
    "extensions": ["./src/safety.ts", "./src/tools.ts"],
    "setupEntry": "./src/setup-entry.ts"
  }
}

• o próprio registro do canal
• quaisquer rotas HTTP que precisem estar disponíveis antes de o Gateway começar a escutar
• quaisquer métodos, ferramentas ou serviços do Gateway que precisem existir durante essa mesma janela

• singleAccountKeysToMove
• namedAccountPromotionKeys
• resolveSingleAccountPromotionTarget(...)

{
  "name": "@scope/my-channel",
  "openclaw": {
    "extensions": ["./index.ts"],
    "setupEntry": "./setup-entry.ts",
    "startup": {
      "deferConfiguredChannelFullLoadUntilAfterListen": true
    }
  }
}

​

Metadados do catálogo de canais

{
  "name": "@openclaw/nextcloud-talk",
  "openclaw": {
    "extensions": ["./index.ts"],
    "channel": {
      "id": "nextcloud-talk",
      "label": "Nextcloud Talk",
      "selectionLabel": "Nextcloud Talk (self-hosted)",
      "docsPath": "/channels/nextcloud-talk",
      "docsLabel": "nextcloud-talk",
      "blurb": "Self-hosted chat via Nextcloud Talk webhook bots.",
      "order": 65,
      "aliases": ["nc-talk", "nc"]
    },
    "install": {
      "npmSpec": "@openclaw/nextcloud-talk",
      "localPath": "<bundled-plugin-local-path>",
      "defaultChoice": "npm"
    }
  }
}

• detailLabel: rótulo secundário para superfícies mais ricas de catálogo/status
• docsLabel: substitui o texto do link para o link da documentação
• preferOver: ids de plugin/canal de prioridade menor que esta entrada do catálogo deve superar
• selectionDocsPrefix, selectionDocsOmitLabel, selectionExtras: controles de texto da superfície de seleção
• markdownCapable: marca o canal como compatível com markdown para decisões de formatação de saída
• exposure.configured: oculta o canal das superfícies de listagem de canais configurados quando definido como false
• exposure.setup: oculta o canal de seletores interativos de configuração quando definido como false
• exposure.docs: marca o canal como interno/privado para superfícies de navegação da documentação
• showConfigured / showInSetup: aliases legados ainda aceitos para compatibilidade; prefira exposure
• quickstartAllowFrom: faz o canal optar pelo fluxo padrão de início rápido allowFrom
• forceAccountBinding: exige vinculação explícita de conta mesmo quando existe apenas uma conta
• preferSessionLookupForAnnounceTarget: prefere busca de sessão ao resolver alvos de anúncio

• ~/.openclaw/mpm/plugins.json
• ~/.openclaw/mpm/catalog.json
• ~/.openclaw/plugins/catalog.json

​

Plugins de mecanismo de contexto

import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core";

export default function (api) {
  api.registerContextEngine("lossless-claw", (ctx) => ({
    info: { id: "lossless-claw", name: "Lossless Claw", ownsCompaction: true },
    async ingest() {
      return { ingested: true };
    },
    async assemble({ messages, availableTools, citationsMode }) {
      return {
        messages,
        estimatedTokens: 0,
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
        }),
      };
    },
    async compact() {
      return { ok: true, compacted: false };
    },
  }));
}

import {
  buildMemorySystemPromptAddition,
  delegateCompactionToRuntime,
} from "openclaw/plugin-sdk/core";

export default function (api) {
  api.registerContextEngine("my-memory-engine", (ctx) => ({
    info: {
      id: "my-memory-engine",
      name: "My Memory Engine",
      ownsCompaction: false,
    },
    async ingest() {
      return { ingested: true };
    },
    async assemble({ messages, availableTools, citationsMode }) {
      return {
        messages,
        estimatedTokens: 0,
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
        }),
      };
    },
    async compact(params) {
      return await delegateCompactionToRuntime(params);
    },
  }));
}

​

Adicionando uma nova capacidade

1. defina o contrato do núcleo Decida qual comportamento compartilhado o núcleo deve possuir: política, fallback, mesclagem de configuração, ciclo de vida, semântica voltada para canais e formato de helper de runtime.
2. adicione superfícies tipadas de registro/runtime de plugin Estenda OpenClawPluginApi e/ou api.runtime com a menor superfície tipada de capacidade que seja útil.
3. conecte consumidores do núcleo + canal/recurso Canais e plugins de recurso devem consumir a nova capacidade por meio do núcleo, não importando diretamente uma implementação de fornecedor.
4. registre implementações de fornecedores Plugins de fornecedores então registram seus backends contra a capacidade.
5. adicione cobertura de contrato Adicione testes para que a propriedade e o formato de registro permaneçam explícitos ao longo do tempo.

​

Checklist de capacidade

• tipos de contrato do núcleo em src/<capability>/types.ts
• helper de executor/runtime do núcleo em src/<capability>/runtime.ts
• superfície de registro da API de plugins em src/plugins/types.ts
• conexão do registro de plugins em src/plugins/registry.ts
• exposição de runtime de plugin em src/plugins/runtime/* quando plugins de recurso/canal precisam consumi-la
• helpers de captura/teste em src/test-utils/plugin-registration.ts
• asserções de propriedade/contrato em src/plugins/contracts/registry.ts
• documentação para operador/plugin em docs/

​

Modelo de capacidade

// core contract
export type VideoGenerationProviderPlugin = {
  id: string;
  label: string;
  generateVideo: (req: VideoGenerationRequest) => Promise<VideoGenerationResult>;
};

// plugin API
api.registerVideoGenerationProvider({
  id: "openai",
  label: "OpenAI",
  async generateVideo(req) {
    return await generateOpenAiVideo(req);
  },
});

// shared runtime helper for feature/channel plugins
const clip = await api.runtime.videoGeneration.generate({
  prompt: "Show the robot walking through the lab.",
  cfg,
});

expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]);

• o core possui o contrato de capacidade + orquestração
• plugins de fornecedores possuem implementações de fornecedores
• plugins de recurso/canal consomem helpers de runtime
• testes de contrato mantêm a propriedade explícita

​

Relacionados

• Arquitetura de Plugin — modelo e formatos públicos de capacidade
• Subcaminhos do Plugin SDK
• Configuração do Plugin SDK
• Criando plugins