​

Internos de Plugin

​

Modelo público de capacidades

​

Posição de compatibilidade externa

• Plugins externos existentes: mantenha integrações baseadas em hooks funcionando; trate isso como a base de compatibilidade
• novos Plugins empacotados/nativos: prefira registro explícito de capacidades em vez de acessos específicos por fornecedor ou novos designs apenas com hooks
• Plugins externos adotando registro de capacidades: permitido, mas trate as superfícies auxiliares específicas de capacidade como evolutivas, a menos que a documentação marque explicitamente um contrato como estável

• APIs de registro de capacidade são a direção pretendida
• hooks legados continuam sendo o caminho mais seguro para evitar quebra de compatibilidade para Plugins externos durante a transição
• nem todos os subcaminhos auxiliares exportados são iguais; prefira o contrato documentado e estreito, não exports auxiliares incidentais

​

Formas de Plugin

• plain-capability — registra exatamente um tipo de capacidade (por exemplo, um Plugin apenas de provedor como mistral)
• hybrid-capability — registra vários tipos de capacidade (por exemplo, openai é dono de inferência de texto, fala, entendimento de mídia e geração de imagem)
• hook-only — registra apenas hooks (tipados ou personalizados), sem capacidades, ferramentas, comandos ou serviços
• non-capability — registra ferramentas, comandos, serviços ou rotas, mas sem capacidades

​

Hooks legados

• mantê-lo funcionando
• documentá-lo como legado
• preferir before_model_resolve para trabalho de sobrescrita de modelo/provedor
• preferir before_prompt_build para trabalho de mutação de prompt
• removê-lo apenas depois que o uso real cair e a cobertura de fixtures comprovar segurança de migração

​

Sinais de compatibilidade

​

Visão geral da arquitetura

1. Manifest + descoberta O OpenClaw encontra Plugins candidatos a partir de caminhos configurados, raízes de workspace, raízes globais de extensões e extensões empacotadas. A descoberta lê primeiro manifests nativos openclaw.plugin.json, além de manifests de bundles suportados.
2. Habilitação + validação O núcleo decide se um Plugin descoberto está habilitado, desabilitado, bloqueado ou selecionado para um slot exclusivo, como memória.
3. Carregamento em runtime Plugins nativos do OpenClaw são carregados in-process via jiti e registram capacidades em um registro central. Bundles compatíveis são normalizados em registros do registro sem importar código de runtime.
4. Consumo de superfície O restante do OpenClaw lê o registro para expor ferramentas, canais, configuração de provedor, hooks, rotas HTTP, comandos de CLI e serviços.

• metadados de tempo de parsing vêm de registerCli(..., { descriptors: [...] })
• o módulo real da CLI do Plugin pode continuar lazy e se registrar na primeira invocação

• descoberta + validação de configuração devem funcionar a partir de metadados de manifest/schema sem executar código do Plugin
• o comportamento nativo em runtime vem do caminho register(api) do módulo do Plugin

​

Plugins de canal e a ferramenta message compartilhada

• o núcleo é dono do host da ferramenta message compartilhada, integração no prompt, registro de sessão/thread e despacho de execução
• Plugins de canal são donos da descoberta de ações por escopo, descoberta de capacidades e quaisquer fragmentos de schema específicos do canal
• Plugins de canal são donos da gramática de conversa de sessão específica do provedor, como ids de conversa codificam ids de thread ou herdam de conversas pai
• Plugins de canal executam a ação final por meio de seu adaptador de ação

• accountId
• currentChannelId
• currentThreadTs
• currentMessageId
• sessionKey
• sessionId
• agentId
• requesterSenderId confiável de entrada

• outbound.sendPoll é a base compartilhada para canais que se encaixam no modelo comum de enquete
• actions.handleAction("poll") é o caminho preferido para semântica de enquete específica de canal ou parâmetros extras de enquete

​

Modelo de propriedade de capacidade

• um Plugin de empresa normalmente deve ser dono de todas as superfícies do OpenClaw voltadas para aquela empresa
• um Plugin de recurso normalmente deve ser dono da superfície completa do recurso que introduz
• canais devem consumir capacidades centrais compartilhadas em vez de reimplementar comportamento de provedor de forma ad hoc

• o Plugin empacotado openai é dono do comportamento de provedor de modelos OpenAI e do comportamento OpenAI de fala + voz em tempo real + entendimento de mídia + geração de imagem
• o Plugin empacotado elevenlabs é dono do comportamento de fala do ElevenLabs
• o Plugin empacotado microsoft é dono do comportamento de fala da Microsoft
• o Plugin empacotado google é dono do comportamento de provedor de modelos Google, além do comportamento Google de entendimento de mídia + geração de imagem + pesquisa na web
• o Plugin empacotado firecrawl é dono do comportamento de busca na web do Firecrawl
• os Plugins empacotados minimax, mistral, moonshot e zai são donos de seus backends de entendimento de mídia
• o Plugin empacotado qwen é dono do comportamento de provedor de texto Qwen, além do comportamento de entendimento de mídia e geração de vídeo
• o Plugin voice-call é um Plugin de recurso: ele é dono do transporte de chamada, ferramentas, CLI, rotas e bridge de stream de mídia do Twilio, mas consome capacidades compartilhadas de fala e também de transcrição em tempo real e voz em tempo real, em vez de importar diretamente Plugins de fornecedor

• OpenAI vive em um único Plugin, mesmo que cubra modelos de texto, fala, imagens e vídeo no futuro
• outro fornecedor pode fazer o mesmo para sua própria área de superfície
• canais não se importam com qual Plugin de fornecedor é dono do provedor; eles consomem o contrato de capacidade compartilhada exposto pelo núcleo

• Plugin = limite de propriedade
• capacidade = contrato central que múltiplos Plugins podem implementar ou consumir

1. definir a capacidade ausente no núcleo
2. expô-la pela API/runtime de Plugin de forma tipada
3. conectar canais/recursos a essa capacidade
4. deixar Plugins de fornecedor registrarem implementações

​

Camadas de capacidade

• camada central de capacidade: orquestração compartilhada, política, fallback, regras de mesclagem de configuração, semântica de entrega e contratos tipados
• camada de Plugin de fornecedor: APIs específicas do fornecedor, autenticação, catálogos de modelos, síntese de fala, geração de imagem, futuros backends de vídeo, endpoints de uso
• camada de Plugin de canal/recurso: integração Slack/Discord/voice-call/etc. que consome capacidades centrais e as apresenta em uma superfície

• o núcleo é dono da política de TTS no momento da resposta, ordem de fallback, preferências e entrega no canal
• openai, elevenlabs e microsoft são donos das implementações de síntese
• voice-call consome o auxiliar de runtime de TTS para telefonia

​

Exemplo de Plugin de empresa com múltiplas capacidades

import type { OpenClawPluginDefinition } from "openclaw/plugin-sdk/plugin-entry";
import {
  describeImageWithModel,
  transcribeOpenAiCompatibleAudio,
} from "openclaw/plugin-sdk/media-understanding";

const plugin: OpenClawPluginDefinition = {
  id: "exampleai",
  name: "ExampleAI",
  register(api) {
    api.registerProvider({
      id: "exampleai",
      // hooks de autenticação/catálogo de modelos/runtime
    });

    api.registerSpeechProvider({
      id: "exampleai",
      // configuração de fala do fornecedor — implemente diretamente a interface SpeechProviderPlugin
    });

    api.registerMediaUnderstandingProvider({
      id: "exampleai",
      capabilities: ["image", "audio", "video"],
      async describeImage(req) {
        return describeImageWithModel({
          provider: "exampleai",
          model: req.model,
          input: req.input,
        });
      },
      async transcribeAudio(req) {
        return transcribeOpenAiCompatibleAudio({
          provider: "exampleai",
          model: req.model,
          input: req.input,
        });
      },
    });

    api.registerWebSearchProvider(
      createPluginBackedWebSearchProvider({
        id: "exampleai-search",
        // lógica de credencial + busca
      }),
    );
  },
};

export default plugin;

• um único Plugin é dono da superfície do fornecedor
• o núcleo continua sendo dono dos contratos de capacidade
• canais e Plugins de recurso consomem auxiliares api.runtime.*, não código do fornecedor
• testes de contrato podem afirmar que o Plugin registrou as capacidades que afirma possuir

​

Exemplo de capacidade: entendimento de vídeo

1. o núcleo define o contrato de entendimento de mídia
2. Plugins de fornecedor registram describeImage, transcribeAudio e describeVideo, conforme aplicável
3. canais e Plugins de recurso consomem o comportamento central compartilhado em vez de se conectarem diretamente ao código do fornecedor

​

Contratos e enforcement

• autores de Plugins recebem um único padrão interno estável
• o núcleo pode rejeitar propriedade duplicada, como dois Plugins registrando o mesmo id de provedor
• a inicialização pode expor diagnósticos acionáveis para registros malformados
• testes de contrato podem impor a propriedade de Plugins empacotados e evitar deriva silenciosa

1. enforcement de registro em runtime O registro de Plugins valida registros à medida que os Plugins são carregados. Exemplos: ids duplicados de provedor, ids duplicados de provedor de fala e registros malformados produzem diagnósticos de Plugin em vez de comportamento indefinido.
2. testes de contrato Plugins empacotados são capturados em registros de contrato durante execuções de teste, para que o OpenClaw possa afirmar a propriedade explicitamente. Hoje isso é usado para provedores de modelo, provedores de fala, provedores de pesquisa na web e propriedade de registro empacotado.

​

O que pertence a um contrato

• tipados
• pequenos
• específicos de capacidade
• de propriedade do núcleo
• reutilizáveis por múltiplos Plugins
• consumíveis por canais/recursos sem conhecimento do fornecedor

• política específica do fornecedor escondida no núcleo
• rotas de escape pontuais de Plugin que contornam o registro
• código de canal acessando diretamente uma implementação de fornecedor
• objetos ad hoc de runtime que não fazem parte de OpenClawPluginApi ou api.runtime

​

Modelo de execução

• um Plugin nativo pode registrar ferramentas, handlers de rede, hooks e serviços
• um bug em um Plugin nativo pode derrubar ou desestabilizar o Gateway
• um Plugin nativo malicioso equivale a execução arbitrária de código dentro do processo do OpenClaw

• plugins.allow confia em ids de Plugin, não na proveniência da origem.
• Um Plugin de workspace com o mesmo id de um Plugin empacotado intencionalmente sombreia a cópia empacotada quando esse Plugin de workspace está habilitado/na allowlist.
• Isso é normal e útil para desenvolvimento local, teste de patches e hotfixes.

​

Limite de exportação

• subcaminhos auxiliares específicos de Plugin empacotado
• subcaminhos de plumbing de runtime não destinados a API pública
• auxiliares de conveniência específicos de fornecedor
• auxiliares de configuração/onboarding que são detalhes de implementação

​

Pipeline de carregamento

1. descobre raízes de Plugins candidatos
2. lê manifests nativos ou de bundles 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 via jiti
7. chama hooks nativos register(api) (ou activate(api) — um alias legado) e coleta registros no registro de Plugins
8. expõe o registro para superfícies de comando/runtime

​

Comportamento manifest-first

• 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
• 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 configuração de canal/resolução de Plugin restringe aos Plugins que são donos do id de canal solicitado
• a configuração/resolução explícita de provedor em runtime restringe aos Plugins que são donos do id de provedor solicitado

​

O que o loader mantém em cache

• resultados de descoberta
• dados do registro de manifest
• registros de Plugins carregados

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

​

Modelo de registro

• registros de Plugin (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 de propriedade do Plugin

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

​

Callbacks de vínculo de conversa

export default {
  id: "my-plugin",
  register(api) {
    api.onConversationBindingResolved(async (event) => {
      if (event.status === "approved") {
        // Agora existe um vínculo para este plugin + conversa.
        console.log(event.binding?.conversationId);
        return;
      }

      // A solicitação foi negada; limpe qualquer estado pendente local.
      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 desanexação, id do remetente e metadados da conversa

​

Hooks de runtime de provedor

• metadados de manifest: providerAuthEnvVars para busca barata de autenticação de provedor por variável de ambiente antes do carregamento do runtime, providerAuthAliases para variantes de provedor que compartilham autenticação, channelEnvVars para busca barata de setup/ambiente de canal antes do carregamento do runtime, além de providerAuthChoices para rótulos baratos de onboarding/escolha de autenticação e metadados de flags da CLI antes do carregamento do runtime
• hooks em tempo de configuração: catalog / discovery legado e applyConfigDefaults
• hooks de runtime: normalizeModelId, normalizeTransport, normalizeConfig, applyNativeStreamingUsageCompat, resolveConfigApiKey, resolveSyntheticAuth, resolveExternalAuthProfiles, shouldDeferSyntheticProfileAuth, resolveDynamicModel, prepareDynamicModel, normalizeResolvedModel, contributeResolvedModelCompat, capabilities, normalizeToolSchemas, inspectToolSchemas, resolveReasoningOutputMode, prepareExtraParams, createStreamFn, wrapStreamFn, resolveTransportTurnState, resolveWebSocketSessionPolicy, formatApiKey, refreshOAuth, buildAuthDoctorHint, matchesContextOverflowError, classifyFailoverReason, isCacheTtlEligible, buildMissingAuthMessage, suppressBuiltInModel, augmentModelCatalog, isBinaryThinking, supportsXHighThinking, supportsAdaptiveThinking, resolveDefaultThinkingLevel, isModernModelRef, prepareRuntimeAuth, resolveUsageAuth, fetchUsageSnapshot, createEmbeddingProvider, buildReplayPolicy, sanitizeReplayHistory, validateReplayTurns, onModelSelected

​

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

• O Anthropic usa resolveDynamicModel, capabilities, buildAuthDoctorHint, resolveUsageAuth, fetchUsageSnapshot, isCacheTtlEligible, supportsAdaptiveThinking, resolveDefaultThinkingLevel, applyConfigDefaults, isModernModelRef e wrapStreamFn porque é dono da compatibilidade futura do Claude 4.6, dicas de família de provedor, orientação de reparo de autenticação, integração com endpoint de uso, elegibilidade de cache de prompt, padrões de configuração conscientes de autenticação, política padrão/adaptativa de thinking do Claude e modelagem de stream específica do Anthropic para cabeçalhos beta, /fast / serviceTier e context1m.
• Os auxiliares de stream específicos do Claude no Anthropic permanecem por enquanto na sua própria interface pública api.ts / contract-api.ts do Plugin empacotado. Essa superfície de pacote exporta wrapAnthropicProviderStream, resolveAnthropicBetas, resolveAnthropicFastMode, resolveAnthropicServiceTier e builders de wrapper de Anthropic em nível mais baixo, em vez de ampliar o SDK genérico em torno das regras de cabeçalho beta de um único provedor.
• A OpenAI usa resolveDynamicModel, normalizeResolvedModel e capabilities, além de buildMissingAuthMessage, suppressBuiltInModel, augmentModelCatalog, supportsXHighThinking e isModernModelRef porque é dona da compatibilidade futura do GPT-5.4, da normalização direta OpenAI openai-completions -> openai-responses, de dicas de autenticação com reconhecimento de Codex, da supressão de Spark, de linhas sintéticas da lista OpenAI e da política de thinking / modelo ao vivo do GPT-5; a família de stream openai-responses-defaults é dona dos wrappers compartilhados nativos do OpenAI Responses para cabeçalhos de atribuição, /fast/serviceTier, verbosidade de texto, pesquisa nativa na web do Codex, modelagem de payload de compatibilidade de raciocínio e gerenciamento de contexto de Responses.
• O OpenRouter usa catalog, além de resolveDynamicModel e prepareDynamicModel, porque o provedor é pass-through e pode expor novos ids de modelo antes das atualizações do catálogo estático do OpenClaw; ele também usa capabilities, wrapStreamFn e isCacheTtlEligible para manter fora do núcleo cabeçalhos de requisição específicos do provedor, metadados de roteamento, patches de raciocínio e política de cache de prompt. Sua política de replay vem da família passthrough-gemini, enquanto a família de stream openrouter-thinking é dona da injeção de raciocínio do proxy e dos pulos de modelo não suportado / auto.
• O GitHub Copilot usa catalog, auth, resolveDynamicModel e capabilities, além de prepareRuntimeAuth e fetchUsageSnapshot, porque precisa de login por dispositivo de propriedade do provedor, comportamento de fallback de modelo, particularidades de transcrição do Claude, troca de token GitHub -> token Copilot e um endpoint de uso de propriedade do provedor.
• O OpenAI Codex usa catalog, resolveDynamicModel, normalizeResolvedModel, refreshOAuth e augmentModelCatalog, além de prepareExtraParams, resolveUsageAuth e fetchUsageSnapshot, porque ainda roda nos transportes centrais da OpenAI, mas é dono de sua normalização de transporte/base URL, política de fallback de refresh de OAuth, escolha padrão de transporte, linhas sintéticas de catálogo do Codex e integração com endpoint de uso do ChatGPT; ele compartilha a mesma família de stream openai-responses-defaults da OpenAI direta.
• O Google AI Studio e o Gemini CLI OAuth usam resolveDynamicModel, buildReplayPolicy, sanitizeReplayHistory, resolveReasoningOutputMode, wrapStreamFn e isModernModelRef, porque a família de replay google-gemini é dona do fallback de compatibilidade futura do Gemini 3.1, da validação nativa de replay do Gemini, da sanitização de replay no bootstrap, do modo de saída de raciocínio com tags e da correspondência de modelos modernos, enquanto a família de stream google-thinking é dona da normalização do payload de thinking do Gemini; o Gemini CLI OAuth também usa formatApiKey, resolveUsageAuth e fetchUsageSnapshot para formatação de token, parsing de token e ligação do endpoint de cota.
• O Anthropic Vertex usa buildReplayPolicy por meio da família de replay anthropic-by-model, para que a limpeza de replay específica do Claude permaneça delimitada a ids de Claude em vez de todo transporte anthropic-messages.
• O Amazon Bedrock usa buildReplayPolicy, matchesContextOverflowError, classifyFailoverReason e resolveDefaultThinkingLevel porque é dono da classificação específica do Bedrock para erros de throttle/not-ready/context-overflow no tráfego Anthropic-on-Bedrock; sua política de replay ainda compartilha a mesma proteção anthropic-by-model apenas para Claude.
• OpenRouter, Kilocode, Opencode e Opencode Go usam buildReplayPolicy por meio da família de replay passthrough-gemini porque fazem proxy de modelos Gemini por transportes compatíveis com OpenAI e precisam da sanitização de assinatura de pensamento do Gemini sem validação nativa de replay do Gemini nem reescritas de bootstrap.
• O MiniMax usa buildReplayPolicy por meio da família de replay hybrid-anthropic-openai, porque um único provedor é dono tanto da semântica de mensagem Anthropic quanto da compatível com OpenAI; ele mantém a remoção de blocos de thinking apenas do Claude no lado Anthropic ao mesmo tempo em que sobrescreve o modo de saída de raciocínio de volta para nativo, e a família de stream minimax-fast-mode é dona de reescritas de modelo em modo rápido no caminho de stream compartilhado.
• O Moonshot usa catalog, além de wrapStreamFn, porque ainda usa o transporte compartilhado da OpenAI, mas precisa de normalização de payload de thinking de propriedade do provedor; a família de stream moonshot-thinking mapeia configuração e estado de /think para seu payload nativo binário de thinking.
• O Kilocode usa catalog, capabilities, wrapStreamFn e isCacheTtlEligible porque precisa de cabeçalhos de requisição de propriedade do provedor, normalização de payload de raciocínio, dicas de transcrição do Gemini e barreira de TTL de cache do Anthropic; a família de stream kilocode-thinking mantém a injeção de thinking do Kilo no caminho compartilhado de stream do proxy ao mesmo tempo em que ignora kilo/auto e outros ids de modelo de proxy que não suportam payloads explícitos de raciocínio.
• O Z.AI usa resolveDynamicModel, prepareExtraParams, wrapStreamFn, isCacheTtlEligible, isBinaryThinking, isModernModelRef, resolveUsageAuth e fetchUsageSnapshot porque é dono do fallback do GLM-5, dos padrões tool_stream, da UX de thinking binário, da correspondência de modelos modernos e tanto da autenticação de uso quanto da busca de cota; a família de stream tool-stream-default-on mantém o wrapper padrão-ativo de tool_stream fora de cola manual por provedor.
• A xAI usa normalizeResolvedModel, normalizeTransport, contributeResolvedModelCompat, prepareExtraParams, wrapStreamFn, resolveSyntheticAuth, resolveDynamicModel e isModernModelRef porque é dona da normalização do transporte nativo xAI Responses, de reescritas de alias do modo rápido do Grok, do tool_stream padrão, da limpeza rigorosa de ferramentas / payload de raciocínio, da reutilização de autenticação de fallback para ferramentas de propriedade do Plugin, da resolução de modelo Grok com compatibilidade futura e de patches de compatibilidade de propriedade do provedor, como perfil de schema de ferramenta xAI, palavras-chave de schema não suportadas, web_search nativo e decodificação de argumentos de chamada de ferramenta com entidade HTML.
• Mistral, OpenCode Zen e OpenCode Go usam apenas capabilities para manter particularidades de transcrição/ferramentas fora do núcleo.
• Provedores empacotados apenas com catálogo, como byteplus, cloudflare-ai-gateway, huggingface, kimi-coding, nvidia, qianfan, synthetic, together, venice, vercel-ai-gateway e volcengine, usam apenas catalog.
• O Qwen usa catalog para seu provedor de texto, além de registros compartilhados de entendimento de mídia e geração de vídeo para suas superfícies multimodais.
• MiniMax e Xiaomi usam catalog, além de hooks de uso, porque seu comportamento de /usage pertence ao Plugin, mesmo que a inferência ainda rode pelos transportes compartilhados.

​

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 central messages.tts e 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 de propriedade do fornecedor.
• Listagens de vozes podem incluir metadados mais ricos, como locale, gênero e tags de personalidade para seletores com reconhecimento de provedor.
• OpenAI e ElevenLabs suportam 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 política, fallback e entrega de resposta de TTS no núcleo.
• Use provedores de fala para comportamento de síntese de propriedade do fornecedor.
• A entrada legada edge da Microsoft é normalizada para o id de provedor microsoft.
• O modelo preferido de propriedade é orientado por empresa: um único Plugin de fornecedor pode ser dono de texto, fala, imagem e futuros provedores de mídia à medida que 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 integração com canais 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 opcionais de resultado, novas capacidades opcionais.
• A geração de vídeo já segue o mesmo padrão:
  • o núcleo é 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 { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({
  filePath: "/tmp/inbound-audio.ogg",
  cfg: api.config,
  // Opcional quando o MIME não pode ser inferido com confiabilidade:
  mime: "audio/ogg",
});

• api.runtime.mediaUnderstanding.* é a superfície compartilhada preferida para entendimento de imagem/áudio/vídeo.
• Usa a configuração central de áudio de entendimento de mídia (tools.media.audio) e a ordem de fallback de provedor.
• Retorna { text: undefined } quando nenhuma saída de transcrição é produzida (por exemplo, entrada ignorada/não suportada).
• 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 sobrescritas opcionais por execução, não mudanças persistentes de sessão.
• O OpenClaw só respeita esses campos de sobrescrita para chamadores confiáveis.
• Para execuções de fallback pertencentes ao Plugin, operadores precisam optar por isso 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 Plugin não confiável ainda funcionam, mas solicitações de sobrescrita são rejeitadas em vez de cair silenciosamente em 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 pesquisa na web para transportes de pesquisa específicos do 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 disponíveis de geração de imagem 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 autenticação normal do Gateway, ou "plugin" para autenticação gerenciada pelo Plugin/verificação de Webhook.
• 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 tratar a requisição.

• api.registerHttpHandler(...) foi removido e causará erro de carregamento do Plugin. Use api.registerHttpRoute(...) no lugar.
• 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 diferentes níveis 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 do operador. Elas são para Webhooks/verificação de assinatura gerenciados pelo Plugin, não para chamadas privilegiadas a auxiliares do Gateway.
• Rotas auth: "gateway" rodam 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 escopos de runtime de rota de Plugin fixados em operator.write, mesmo se o chamador enviar x-openclaw-scopes
  • modos HTTP confiáveis com identidade (por exemplo trusted-proxy ou gateway.auth.mode = "none" em uma entrada privada) respeitam x-openclaw-scopes apenas quando o cabeçalho está explicitamente presente
  • se x-openclaw-scopes estiver ausente nessas requisições de rota de Plugin com identidade, o escopo de runtime volta para operator.write
• Regra prática: não presuma que uma rota de Plugin com autenticação do Gateway seja uma superfície implícita de administração. Se sua rota precisar de comportamento exclusivo de administrador, 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

• openclaw/plugin-sdk/plugin-entry para primitivas de registro de Plugin.
• openclaw/plugin-sdk/core para o contrato genérico compartilhado voltado a Plugins.
• openclaw/plugin-sdk/config-schema para o export do schema Zod raiz de openclaw.json (OpenClawSchema).
• Primitivas estáveis de canal, como openclaw/plugin-sdk/channel-setup, openclaw/plugin-sdk/setup-runtime, openclaw/plugin-sdk/setup-adapter-runtime, openclaw/plugin-sdk/setup-tools, openclaw/plugin-sdk/channel-pairing, openclaw/plugin-sdk/channel-contract, openclaw/plugin-sdk/channel-feedback, openclaw/plugin-sdk/channel-inbound, openclaw/plugin-sdk/channel-lifecycle, openclaw/plugin-sdk/channel-reply-pipeline, openclaw/plugin-sdk/command-auth, openclaw/plugin-sdk/secret-input e openclaw/plugin-sdk/webhook-ingress para integração compartilhada de setup/autenticação/resposta/Webhook. channel-inbound é a superfície compartilhada para debounce, correspondência de menções, auxiliares de política de menção de entrada, formatação de envelope e auxiliares de contexto de envelope de entrada. channel-setup é a interface estreita de setup opcional na instalação. setup-runtime é a superfície segura em runtime para setup usada por setupEntry / inicialização adiada, incluindo adaptadores de patch de setup seguros para importação. setup-adapter-runtime é a interface de adaptador de setup de conta sensível a ambiente. setup-tools é a pequena interface de auxiliares de CLI/arquivo/docs (formatCliCommand, detectBinary, extractArchive, resolveBrewExecutable, formatDocsLink, CONFIG_DIR).
• Subcaminhos de domínio como openclaw/plugin-sdk/channel-config-helpers, openclaw/plugin-sdk/allow-from, openclaw/plugin-sdk/channel-config-schema, openclaw/plugin-sdk/telegram-command-config, openclaw/plugin-sdk/channel-policy, openclaw/plugin-sdk/approval-gateway-runtime, openclaw/plugin-sdk/approval-handler-adapter-runtime, openclaw/plugin-sdk/approval-handler-runtime, openclaw/plugin-sdk/approval-runtime, openclaw/plugin-sdk/config-runtime, openclaw/plugin-sdk/infra-runtime, openclaw/plugin-sdk/agent-runtime, openclaw/plugin-sdk/lazy-runtime, openclaw/plugin-sdk/reply-history, openclaw/plugin-sdk/routing, openclaw/plugin-sdk/status-helpers, openclaw/plugin-sdk/text-runtime, openclaw/plugin-sdk/runtime-store e openclaw/plugin-sdk/directory-runtime para auxiliares compartilhados de runtime/configuração. telegram-command-config é a interface pública estreita para normalização/validação de comandos personalizados do Telegram e permanece disponível mesmo se a superfície de contrato do Telegram empacotado estiver temporariamente indisponível. text-runtime é a interface compartilhada de texto/Markdown/logging, incluindo remoção de texto visível para o assistente, auxiliares de renderização/fragmentação de Markdown, auxiliares de redação, auxiliares de tag de diretiva e utilitários de texto seguro.
• Interfaces específicas de canal para aprovação devem preferir um único contrato approvalCapability no Plugin. O núcleo então lê autenticação, entrega, renderização, roteamento nativo e comportamento lazy de handler nativo de aprovação por essa única capacidade em vez de misturar comportamento de aprovação em campos não relacionados do Plugin.
• openclaw/plugin-sdk/channel-runtime está obsoleto e permanece apenas como shim de compatibilidade para Plugins mais antigos. Código novo deve importar as primitivas genéricas mais estreitas, e o código do repositório não deve adicionar novos imports do shim.
• Internos de extensões empacotadas permanecem privados. Plugins externos devem usar apenas subcaminhos openclaw/plugin-sdk/*. Código central/de teste do OpenClaw pode usar os pontos de entrada públicos do repositório sob a raiz de pacote de um Plugin, como index.js, api.js, runtime-api.js, setup-entry.js e arquivos de escopo estreito como login-qr-api.js. Nunca importe src/* de um pacote de Plugin a partir do núcleo ou de outra extensão.
• Divisão de pontos de entrada do repositório: <plugin-package-root>/api.js é o barrel de auxiliares/tipos, <plugin-package-root>/runtime-api.js é o barrel apenas de runtime, <plugin-package-root>/index.js é o ponto de entrada do Plugin empacotado e <plugin-package-root>/setup-entry.js é o ponto de entrada do Plugin de setup.
• Exemplos atuais de provedores empacotados:
  • Anthropic usa api.js / contract-api.js para auxiliares de stream do Claude, como wrapAnthropicProviderStream, auxiliares de cabeçalho beta e parsing de service_tier.
  • OpenAI usa api.js para builders de provedor, auxiliares de modelo padrão e builders de provedor em tempo real.
  • OpenRouter usa api.js para seu builder de provedor, além de auxiliares de onboarding/configuração, enquanto register.runtime.js ainda pode reexportar auxiliares genéricos plugin-sdk/provider-stream para uso local no repositório.
• Pontos de entrada públicos carregados por facade preferem o snapshot ativo de configuração de runtime quando ele existe, e depois recorrem ao arquivo de configuração resolvido em disco quando o OpenClaw ainda não está servindo um snapshot de runtime.
• Primitivas genéricas compartilhadas continuam sendo o contrato público preferido do SDK. Um pequeno conjunto reservado de compatibilidade de interfaces auxiliares com marca de canal empacotado ainda existe. Trate isso como interfaces de manutenção/compatibilidade de empacotados, não como novos alvos de importação para terceiros; novos contratos entre canais ainda devem cair em subcaminhos genéricos plugin-sdk/* ou nos barrels locais do Plugin api.js / runtime-api.js.

• Evite o barrel raiz openclaw/plugin-sdk em código novo.
• Prefira primeiro as primitivas estáveis e estreitas. Os subcaminhos mais novos de setup/pairing/reply/ feedback/contract/inbound/threading/command/secret-input/webhook/infra/ allowlist/status/message-tool são o contrato pretendido para novo trabalho com Plugins empacotados e externos. Parsing/matching de alvo pertence a openclaw/plugin-sdk/channel-targets. Barreiras de ação de mensagem e auxiliares de message-id de reação pertencem a openclaw/plugin-sdk/channel-actions.
• Barrels auxiliares específicos de extensão empacotada não são estáveis por padrão. Se um auxiliar só for necessário por uma extensão empacotada, mantenha-o atrás da interface local api.js ou runtime-api.js da extensão, em vez de promovê-lo para openclaw/plugin-sdk/<extension>.
• Novas interfaces auxiliares compartilhadas devem ser genéricas, não com marca de canal. Parsing compartilhado de alvo pertence a openclaw/plugin-sdk/channel-targets; internos específicos de canal ficam atrás da interface local api.js ou runtime-api.js do Plugin proprietário.
• Subcaminhos específicos de capacidade como image-generation, media-understanding e speech existem porque Plugins empacotados/nativos os usam hoje. Sua presença não significa por si só que todo auxiliar exportado seja um contrato externo congelado de longo prazo.

​

Schemas da ferramenta message

• createMessageToolButtonsSchema() para payloads no estilo grade de botões
• createMessageToolCardSchema() para payloads estruturados de cartão

​

Resolução de alvo de canal

• messaging.inferTargetChatType({ to }) decide se um alvo normalizado deve ser tratado como direct, group ou channel antes da busca em diretório.
• messaging.targetResolver.looksLikeId(raw, normalized) informa ao núcleo se uma entrada deve pular diretamente para resolução por id em vez de busca em diretório.
• messaging.targetResolver.resolveTarget(...) é o fallback do Plugin quando o núcleo precisa de uma resolução final de propriedade do provedor após normalização ou após um erro de busca em diretório.
• messaging.resolveOutboundSessionRoute(...) é dona da construção de rota de sessão específica do provedor depois que um alvo é resolvido.

• Use inferTargetChatType para decisões de categoria que devem acontecer antes de buscar pares/grupos.
• Use looksLikeId para verificações do tipo “trate isto como um id de alvo explícito/nativo”.
• Use resolveTarget para fallback de normalização específica 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 do SDK.

​

Diretórios baseados em configuração

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

• filtragem de consulta
• aplicação de limite
• auxiliares de remoção de duplicidade/normalização
• construção de ChannelDirectoryEntry[]

​

Catálogos de provedor

• { provider } para uma entrada de provedor
• { providers } para múltiplas entradas de provedor

• simple: provedores simples com chave de API ou orientados por variável de ambiente
• profile: provedores que aparecem quando existem perfis de autenticação
• paired: provedores que sintetizam múltiplas entradas relacionadas de provedor
• late: última passada, depois de outros provedores implícitos

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

​

Inspeção somente leitura de canal

• resolveAccount(...) é o caminho de runtime. Ele pode assumir que 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 repair doctor/configuração 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 credencial quando relevantes, 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 pack

{
  "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 que o Gateway comece a ouvir
• 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 (self-hosted)",
      "docsPath": "/channels/nextcloud-talk",
      "docsLabel": "nextcloud-talk",
      "blurb": "Chat self-hosted 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: sobrescreve o texto do link para a documentação
• preferOver: ids de Plugin/canal de prioridade menor que esta entrada de catálogo deve superar
• selectionDocsPrefix, selectionDocsOmitLabel, selectionExtras: controles de cópia 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 setup/configuração quando definido como false
• exposure.docs: marca o canal como interno/privado para superfícies de navegação de documentação
• showConfigured / showInSetup: aliases legados ainda aceitos por compatibilidade; prefira exposure
• quickstartAllowFrom: coloca o canal no fluxo padrão de início rápido de allowFrom
• forceAccountBinding: exige vínculo explícito de conta mesmo quando existe apenas uma conta
• preferSessionLookupForAnnounceTarget: prefere busca por 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", () => ({
    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 possuir: política, fallback, mesclagem de configuração, ciclo de vida, semântica voltada a canais e formato do auxiliar de runtime.
2. adicione superfícies tipadas de registro/runtime de Plugin Estenda OpenClawPluginApi e/ou api.runtime com a menor superfície tipada útil de capacidade.
3. conecte consumidores centrais + de 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 fornecedor Plugins de fornecedor então registram seus backends nessa 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 centrais de contrato em src/<capability>/types.ts
• executor/auxiliar central de runtime em src/<capability>/runtime.ts
• superfície de registro da API de Plugin em src/plugins/types.ts
• integração com o registro de Plugins em src/plugins/registry.ts
• exposição de runtime de Plugin em src/plugins/runtime/* quando Plugins de recurso/canal precisarem consumi-la
• auxiliares de captura/teste em src/test-utils/plugin-registration.ts
• assertions de propriedade/contrato em src/plugins/contracts/registry.ts
• documentação para operador/Plugin em docs/

​

Template de capacidade

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

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

// auxiliar compartilhado de runtime para Plugins de recurso/canal
const clip = await api.runtime.videoGeneration.generate({
  prompt: "Show the robot walking through the lab.",
  cfg,
});

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

• o núcleo é dono do contrato de capacidade + orquestração
• Plugins de fornecedor são donos das implementações do fornecedor
• Plugins de recurso/canal consomem auxiliares de runtime
• testes de contrato mantêm a propriedade explícita