Detalhes internos da arquitetura de Plugin

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Pipeline de carregamento

1. descobre raízes candidatas de plugin
2. lê manifestos 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 de cada candidato
6. carrega módulos nativos habilitados: módulos embutidos compilados usam um carregador nativo; código-fonte TypeScript local de terceiros usa o fallback emergencial do 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 orientado pelo manifesto

• identificar o plugin
• descobrir canais/skills/schema de configuração declarados ou capacidades de bundle
• validar plugins.entries.<id>.config
• complementar rótulos/placeholders da UI de Controle
• mostrar 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 restringe aos plugins que são donos do comando primário solicitado
• a resolução de setup/plugin de canal restringe aos plugins que são donos do id de canal solicitado
• a resolução explícita de setup/runtime de provedor restringe aos plugins que são donos do id de provedor solicitado
• o planejamento de inicialização do Gateway usa activation.onStartup para importações explícitas de inicialização e opt-outs de inicialização; plugins sem metadados de inicialização carregam apenas por gatilhos de ativação mais restritos

​

Limite de cache de plugin

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

• resultados de descoberta
• registros diretos de manifesto
• registros de manifesto 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 uma alteração de manifesto, índice instalado ou caminho de carregamento deva ficar visível na próxima leitura de metadados

​

Modelo de registro

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

• módulo de plugin -> registro no registro
• runtime do core -> 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 manifesto para busca 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 cobrindo autenticação, resolução de modelo, encapsulamento de stream, níveis de raciocínio, política de replay e endpoints de uso. Consulte a lista completa em Ordem e uso de hooks.

​

Ordem e uso de 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 núcleo para superfícies de arquivo/nota de voz.
• Usa a configuração principal 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 configuração controlados pelo fornecedor.
• Listagens de voz podem incluir metadados mais ricos, como localidade, gênero e tags de personalidade para seletores cientes do provedor.
• OpenAI e ElevenLabs oferecem suporte a telefonia hoje. Microsoft não oferece.

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 respostas no núcleo.
• Use provedores de fala para comportamento de síntese controlado pelo 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 responsável por 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 fiação de canais no núcleo.
• 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 núcleo é responsável pelo contrato de capacidade e pelo 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 entendimento de imagem/áudio/vídeo.
• extractStructuredWithModel(...) é a fronteira voltada a plugins para extração limitada, controlada pelo provedor e orientada primeiro por imagem. Inclua pelo menos uma entrada de imagem; entradas de texto são contexto suplementar. plugins de produto são responsáveis por suas rotas e esquemas, enquanto o OpenClaw é responsável pela fronteira de provedor/runtime.
• Usa a configuração principal de áudio de entendimento de mídia (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 um 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 da sessão.
• O OpenClaw honra esses campos de substituição apenas para chamadores confiáveis.
• Para execuções de fallback controladas por plugin, operadores devem optar por habilitá-las com plugins.entries.<id>.subagent.allowModelOverride: true.
• Use plugins.entries.<id>.subagent.allowedModels para restringir plugins confiáveis a alvos canônicos específicos de provider/model, ou "*" para permitir explicitamente qualquer alvo.
• Execuções de subagente de plugins não confiáveis ainda funcionam, mas solicitações de substituição são rejeitadas em vez de cair silenciosamente em 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 próprias; a exclusão arbitrária de sessão ainda exige uma solicitação do 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 a seleção de provedor, resolução de credenciais e semântica compartilhada de solicitação no núcleo.
• 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 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 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/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: retorna true quando a rota tratou a solicitação.

• api.registerHttpHandler(...) foi removido e causará um erro de carregamento do plugin. Use api.registerHttpRoute(...) em vez disso.
• As 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 de auth diferentes são rejeitadas. Mantenha cadeias de fallthrough exact/prefix somente no mesmo nível de auth.
• Rotas 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 auth: "gateway" são executadas dentro de um escopo de runtime de solicitação do Gateway, mas esse escopo é intencionalmente conservador:
  • auth bearer de segredo compartilhado (gateway.auth.mode = "token" / "password") mantém os escopos de runtime de rotas de plugin fixados em operator.write, mesmo que o chamador envie x-openclaw-scopes
  • modos HTTP confiáveis que carregam 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 de plugin que carregam identidade, o escopo de runtime volta para operator.write
• Regra prática: não presuma que uma rota de plugin com auth de gateway seja uma superfície administrativa implícita. Se sua rota precisar de comportamento exclusivo de administrador, exija um modo de auth que carregue identidade e documente o contrato explícito do cabeçalho x-openclaw-scopes.

​

Caminhos de importação do SDK de Plugin

• index.js — entrada de plugin incluído
• api.js — barrel de auxiliares/tipos
• runtime-api.js — barrel somente de runtime
• setup-entry.js — entrada de plugin de setup

​

Esquemas da ferramenta de mensagem

• presentation para blocos de apresentação semânticos (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 resolução semelhante a id em vez de busca 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 falha no diretório.
• messaging.resolveOutboundSessionRoute(...) é dono da 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 de provedor, como ids de chat, ids de thread, JIDs, handles e ids de sala, dentro de valores target ou parâmetros específicos de provedor, não em campos genéricos do SDK.

​

Diretórios baseados em configuração

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

• filtragem de consultas
• aplicação de limite
• auxiliares de deduplicaçã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 orientados por chave de API ou env
• profile: provedores que aparecem quando perfis de auth existem
• 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 obsolescência
• se catalog e discovery forem registrados, o OpenClaw usa catalog
• augmentModelCatalog está obsoleto; provedores incluídos devem publicar linhas suplementares por meio de registerModelCatalogProvider

​

Inspeção de canal somente leitura

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

• Retorne apenas estado descritivo da conta.
• Preserve enabled e configured.
• Inclua campos de origem/status de credenciais 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 no 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 devem estar disponíveis antes que o gateway comece a escutar
• quaisquer métodos, ferramentas ou serviços do gateway que devem 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 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 capaz de 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/ajuste 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: inclui o canal no fluxo padrão de quickstart allowFrom
• forceAccountBinding: exige vinculação explícita 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", (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 capability

1. defina o contrato do core Decida qual comportamento compartilhado o core deve possuir: política, fallback, mesclagem de configuração, ciclo de vida, semântica voltada a 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 capability útil.
3. conecte o core + consumidores de canal/funcionalidade Canais e plugins de funcionalidade devem consumir a nova capability por meio do core, não importando diretamente uma implementação de fornecedor.
4. registre implementações de fornecedor Plugins de fornecedor então registram seus backends contra a capability.
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 capability

• tipos de contrato do core em src/<capability>/types.ts
• runner/helper de runtime do core em src/<capability>/runtime.ts
• superfície de registro da API de plugin em src/plugins/types.ts
• wiring do registro de plugins em src/plugins/registry.ts
• exposição de runtime do plugin em src/plugins/runtime/* quando plugins de funcionalidade/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 de operador/plugin em docs/

​

Template de capability

// 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 da capability + orquestração
• plugins de fornecedor possuem implementações de fornecedor
• plugins de funcionalidade/canal consomem helpers de runtime
• testes de contrato mantêm a propriedade explícita

​

Relacionados

• Arquitetura de plugins — modelo público de capabilities e formatos
• Subpaths do SDK de plugin
• Configuração do SDK de plugin
• Criando plugins