Arquitetura interna de Plugin

​

Pipeline de carregamento

1. descobre raízes candidatas de plugins
2. lê manifests de bundles nativos ou compatíveis e metadados de pacote
3. rejeita candidatos inseguros
4. normaliza a configuração de plugin (plugins.enabled, allow, deny, entries, slots, load.paths)
5. decide a habilitação para cada candidato
6. carrega módulos nativos habilitados: módulos empacotados e compilados usam um carregador nativo; plugins nativos não compilados usam jiti
7. chama hooks nativos register(api) e coleta os registros no registro de plugins
8. expõe o registro para comandos/superfícies de runtime

​

Comportamento orientado por manifest

• identificar o plugin
• descobrir canais/Skills/schema de configuração declarados ou capacidades do bundle
• validar plugins.entries.<id>.config
• complementar rótulos/placeholders da UI de Controle
• exibir metadados de instalação/catálogo
• preservar descritores baratos de ativação e configuração sem carregar o runtime do plugin

• o carregamento da CLI se restringe a plugins que possuem o comando primário solicitado
• a resolução de setup/plugin de canal se restringe a plugins que possuem o id de canal solicitado
• a resolução explícita de setup/runtime de provedor se restringe a plugins que possuem o id de provedor solicitado

​

O que o carregador mantém em cache

• resultados de descoberta
• dados do registro de manifests
• registros de plugins carregados

• Defina OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1 ou OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1 para desabilitar esses caches.
• Ajuste as janelas de cache com OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS e OPENCLAW_PLUGIN_MANIFEST_CACHE_MS.

​

Modelo de registro

• registros de plugins (identidade, origem, procedência, 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 ao plugin

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

​

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: o vínculo resolvido 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 provedor

• Metadados de manifest para busca barata antes do runtime: providerAuthEnvVars, providerAuthAliases, providerAuthChoices e channelEnvVars.
• Hooks em tempo de configuração: catalog (legado discovery) mais applyConfigDefaults.
• Hooks de runtime: mais de 40 hooks opcionais cobrindo autenticação, resolução de modelo, encapsulamento de stream, níveis de thinking, política de replay e endpoints de uso. Consulte 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 internos

​

Helpers 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 TTS do núcleo para superfícies de arquivo/mensagem de voz.
• Usa a configuração central messages.tts e a seleção de provedor.
• Retorna buffer de áudio PCM + taxa de amostragem. Plugins devem reamostrar/codificar para provedores.
• listVoices é opcional por provedor. Use-o para seletores de voz ou fluxos de setup controlados pelo fornecedor.
• Listagens de voz podem incluir metadados mais ricos, como locale, gênero e tags de personalidade para seletores com reconhecimento do provedor.
• OpenAI e ElevenLabs oferecem suporte a 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 de TTS, fallback e entrega de resposta no núcleo.
• Use provedores de fala para comportamento de síntese controlado pelo fornecedor.
• A entrada legada Microsoft edge é normalizada para o id de provedor microsoft.
• O modelo de propriedade preferido é orientado por empresa: um único plugin de fornecedor pode controlar provedores de texto, fala, imagem e futuras mídias à medida que o OpenClaw adicionar 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 encadeamento de canal no núcleo.
• Mantenha o comportamento do fornecedor no plugin do provedor.
• A expansão aditiva deve permanecer tipada: novos métodos opcionais, novos campos de resultado opcionais, novas capacidades opcionais.
• A geração de vídeo já segue o mesmo padrão:
  • o núcleo controla o contrato de capacidade e o helper de runtime
  • plugins de fornecedor registram api.registerVideoGenerationProvider(...)
  • plugins de funcionalidade/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 { 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.
• Usa a configuração central de áudio de compreensão de mídia (tools.media.audio) e a ordem de fallback do provedor.
• Retorna { text: undefined } quando nenhuma saída de transcrição é produzida (por exemplo, entrada ignorada/não suportada).
• api.runtime.stt.transcribeAudioFile(...) continua disponível 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 mudanças persistentes de sessão.
• O OpenClaw só considera esses campos de substituição para chamadores confiáveis.
• Para execuções de fallback controladas pelo plugin, operadores devem habilitar explicitamente com plugins.entries.<id>.subagent.allowModelOverride: true.
• Use plugins.entries.<id>.subagent.allowedModels para restringir plugins confiáveis a alvos canônicos específicos provider/model, ou "*" para permitir explicitamente qualquer alvo.
• Execuções de subagente de plugins não confiáveis continuam funcionando, mas solicitações de substituição são rejeitadas em vez de silenciosamente recorrerem a fallback.

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 compartilhada de requisição no núcleo.
• Use provedores de busca na web para transportes de busca específicos de fornecedor.
• api.runtime.webSearch.* é a superfície compartilhada preferida para plugins de funcionalidade/canal que precisam de comportamento de busca sem depender do wrapper de 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 imagem.
• listProviders(...): lista os provedores de geração de imagem 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/validaçã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 requisição.

• api.registerHttpHandler(...) foi removido e causará um erro de carregamento de plugin. Use api.registerHttpRoute(...).
• Rotas de 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 diferentes de auth são rejeitadas. Mantenha cadeias de fallthrough exact/prefix apenas no mesmo nível de autenticação.
• Rotas auth: "plugin" não recebem automaticamente escopos de runtime de operador. Elas servem para Webhooks/validação de assinatura gerenciados pelo plugin, não para chamadas privilegiadas a helpers do Gateway.
• Rotas auth: "gateway" são executadas dentro de um escopo de runtime de requisiçã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 da rota 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 uma entrada privada) só respeitam x-openclaw-scopes quando o header está explicitamente presente
  • se x-openclaw-scopes estiver ausente nessas requisições de rota de plugin com identidade, o escopo de runtime recorre a operator.write
• Regra prática: não suponha que uma rota de plugin autenticada pelo gateway seja implicitamente uma superfície de administrador. Se sua rota precisar de comportamento exclusivo de admin, exija um modo de autenticação com identidade e documente o contrato explícito do header x-openclaw-scopes.

​

Caminhos de importação da SDK de Plugin

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

​

Schemas de ferramentas de mensagem

• presentation para blocos semânticos de apresentação (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 busca no diretório.
• messaging.targetResolver.looksLikeId(raw, normalized) informa ao núcleo se uma entrada deve pular direto para resolução semelhante a id em vez de busca no diretório.
• messaging.targetResolver.resolveTarget(...) é o fallback do plugin quando o núcleo precisa de uma resolução final controlada pelo provedor após a normalização ou após uma falha de busca no diretório.
• messaging.resolveOutboundSessionRoute(...) controla 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 buscar pares/grupos.
• Use looksLikeId para verificações do tipo “tratar 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 em 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 da SDK.

​

Diretórios baseados em configuração

• pares de DM controlados por lista de permissão
• mapas configurados de canal/grupo
• fallbacks estáticos de diretório por escopo de conta

• filtragem de consulta
• aplicação de limite
• helpers de deduplicação/normalização
• construção de ChannelDirectoryEntry[]

​

Catálogos de provedor

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

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

• discovery ainda funciona como alias legado
• se catalog e discovery estiverem registrados, o OpenClaw usa catalog

​

Inspeção de canal somente leitura

• resolveAccount(...) é o caminho de runtime. Ele pode presumir que as credenciais estão totalmente materializadas e pode falhar rapidamente quando segredos obrigatórios estiverem ausentes.
• Caminhos de comando somente leitura, como openclaw status, openclaw status --all, openclaw channels status, openclaw channels resolve e fluxos de reparo doctor/config, não devem precisar materializar credenciais de runtime só 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 em modo somente leitura. Retornar tokenStatus: "available" (e o campo de origem correspondente) é suficiente para comandos de status.
• Use configured_unavailable quando uma credencial estiver configurada via SecretRef, mas indisponível no caminho de comando atual.

​

Pacotes de empacotamento

{
  "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 de catálogo de canal

{
  "name": "@openclaw/nextcloud-talk",
  "openclaw": {
    "extensions": ["./index.ts"],
    "channel": {
      "id": "nextcloud-talk",
      "label": "Nextcloud Talk",
      "selectionLabel": "Nextcloud Talk (auto-hospedado)",
      "docsPath": "/channels/nextcloud-talk",
      "docsLabel": "nextcloud-talk",
      "blurb": "Chat auto-hospedado via bots de Webhook do Nextcloud Talk.",
      "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 mais baixa que esta entrada de 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 dos seletores interativos de setup/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 aderir ao fluxo padrão allowFrom de início rápido
• forceAccountBinding: exige vínculo explícito de conta mesmo quando existe apenas uma conta
• preferSessionLookupForAnnounceTarget: prefere busca de sessão ao resolver destinos 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", () => ({
    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", () => ({
    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 central Decida qual comportamento compartilhado o núcleo deve controlar: política, fallback, mesclagem de configuração, ciclo de vida, semântica voltada para canal e formato do 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 útil.
3. conecte consumidores de núcleo + canal/funcionalidade Canais e plugins de funcionalidade devem consumir a nova capacidade por meio do núcleo, não importando diretamente uma implementação de fornecedor.
4. registre implementações de fornecedor Plugins de fornecedor então registram seus backends na capacidade.
5. adicione cobertura de contrato Adicione testes para que o formato de propriedade e registro permaneça explícito ao longo do tempo.

​

Checklist de capacidade

• tipos de contrato do núcleo em src/<capability>/types.ts
• executor central/helper de runtime em src/<capability>/runtime.ts
• superfície de registro da API de plugin em src/plugins/types.ts
• conexão do registro de plugins em src/plugins/registry.ts
• exposição de runtime do plugin em src/plugins/runtime/* quando plugins de funcionalidade/canal precisarem 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 núcleo controla o contrato de capacidade + a orquestração
• plugins de fornecedor controlam implementações do fornecedor
• plugins de funcionalidade/canal consomem helpers de runtime
• testes de contrato mantêm a propriedade explícita

​

Relacionado

• Arquitetura de Plugin — modelo público de capacidades e formatos
• Subcaminhos da SDK de Plugin
• Setup da SDK de Plugin
• Criando plugins