Aspectos internos de la arquitectura de Plugin

​

Canalización de carga

1. descubre raíces candidatas de Plugin
2. lee manifiestos de paquetes nativos o compatibles y metadatos del paquete
3. rechaza candidatos inseguros
4. normaliza la configuración del Plugin (plugins.enabled, allow, deny, entries, slots, load.paths)
5. decide la habilitación de cada candidato
6. carga módulos nativos habilitados: los módulos integrados compilados usan un cargador nativo; los Plugin nativos no compilados usan jiti
7. llama a los hooks nativos register(api) y recopila los registros en el registro de Plugin
8. expone el registro a los comandos/superficies de ejecución

​

Comportamiento con prioridad del manifiesto

• identificar el Plugin
• descubrir canales/Skills/esquema de configuración declarados o capacidades del paquete
• validar plugins.entries.<id>.config
• ampliar etiquetas/marcadores de posición de la interfaz de Control
• mostrar metadatos de instalación/catálogo
• conservar descriptores baratos de activación y configuración sin cargar el tiempo de ejecución del Plugin

• La carga de la CLI se limita a los Plugin que poseen el comando principal solicitado
• la resolución de configuración del canal/Plugin se limita a los Plugin que poseen el id. de canal solicitado
• la resolución explícita de configuración/tiempo de ejecución del proveedor se limita a los Plugin que poseen el id. de proveedor solicitado

​

Qué almacena en caché el cargador

• resultados de descubrimiento
• datos del registro de manifiestos
• registros de Plugin cargados

• Establece OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1 o OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1 para desactivar estas cachés.
• Ajusta las ventanas de caché con OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS y OPENCLAW_PLUGIN_MANIFEST_CACHE_MS.

​

Modelo de registro

• registros de Plugin (identidad, fuente, origen, estado, diagnósticos)
• herramientas
• hooks heredados y hooks tipados
• canales
• proveedores
• controladores RPC del Gateway
• rutas HTTP
• registradores de CLI
• servicios en segundo plano
• comandos propiedad del Plugin

• módulo de Plugin -> registro en el registro
• tiempo de ejecución del núcleo -> consumo del registro

​

Callbacks de vinculación de conversaciones

export default {
  id: "my-plugin",
  register(api) {
    api.onConversationBindingResolved(async (event) => {
      if (event.status === "approved") {
        // Ahora existe una vinculación para este plugin + conversación.
        console.log(event.binding?.conversationId);
        return;
      }

      // La solicitud fue denegada; borra cualquier estado local pendiente.
      console.log(event.request.conversation.conversationId);
    });
  },
};

• status: "approved" o "denied"
• decision: "allow-once", "allow-always" o "deny"
• binding: la vinculación resuelta para solicitudes aprobadas
• request: el resumen de la solicitud original, sugerencia de desvinculación, id. del remitente y metadatos de la conversación

​

Hooks de ejecución del proveedor

• Metadatos del manifiesto para búsquedas baratas previas al tiempo de ejecución: providerAuthEnvVars, providerAuthAliases, providerAuthChoices y channelEnvVars.
• Hooks de tiempo de configuración: catalog (heredado discovery) más applyConfigDefaults.
• Hooks de tiempo de ejecución: más de 40 hooks opcionales que cubren autenticación, resolución de modelos, envoltura de flujo, niveles de pensamiento, política de repetición y endpoints de uso. Consulta la lista completa en Orden y uso de hooks.

​

Orden y uso de hooks

​

Ejemplo de proveedor

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

​

Ejemplos integrados

​

Helpers de ejecución

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 devuelve la carga útil de salida TTS normal del núcleo para superficies de archivo/nota de voz.
• Usa la configuración del núcleo messages.tts y la selección del proveedor.
• Devuelve búfer de audio PCM + frecuencia de muestreo. Los Plugin deben remuestrear/codificar para los proveedores.
• listVoices es opcional por proveedor. Úsalo para selectores de voz o flujos de configuración propiedad del proveedor.
• Los listados de voces pueden incluir metadatos más ricos, como etiquetas de configuración regional, género y personalidad, para selectores conscientes del proveedor.
• OpenAI y ElevenLabs admiten telefonía hoy. Microsoft no.

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

• Mantén en el núcleo la política de TTS, la alternativa y la entrega de respuestas.
• Usa proveedores de voz para el comportamiento de síntesis propiedad del proveedor.
• La entrada heredada de Microsoft edge se normaliza al id. de proveedor microsoft.
• El modelo de propiedad preferido está orientado a empresas: un Plugin de proveedor puede poseer texto, voz, imagen y futuros proveedores de medios a medida que OpenClaw añada esos contratos de capacidad.

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

• Mantén en el núcleo la orquestación, la alternativa, la configuración y el cableado del canal.
• Mantén el comportamiento del proveedor dentro del Plugin del proveedor.
• La expansión aditiva debe seguir siendo tipada: nuevos métodos opcionales, nuevos campos opcionales de resultado, nuevas capacidades opcionales.
• La generación de video ya sigue el mismo patrón:
  • el núcleo posee el contrato de capacidad y el helper de ejecución
  • los Plugin de proveedor registran api.registerVideoGenerationProvider(...)
  • los Plugin de característica/canal consumen 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 cuando el tipo MIME no puede inferirse de forma fiable:
  mime: "audio/ogg",
});

• api.runtime.mediaUnderstanding.* es la superficie compartida preferida para comprensión de imagen/audio/video.
• Usa la configuración de audio de comprensión de medios del núcleo (tools.media.audio) y el orden de alternativas del proveedor.
• Devuelve { text: undefined } cuando no se produce salida de transcripción (por ejemplo, entrada omitida/no compatible).
• api.runtime.stt.transcribeAudioFile(...) se mantiene como alias de compatibilidad.

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 y model son anulaciones opcionales por ejecución, no cambios persistentes de sesión.
• OpenClaw solo respeta esos campos de anulación para llamadores de confianza.
• Para ejecuciones alternativas propiedad del Plugin, los operadores deben habilitarlo con plugins.entries.<id>.subagent.allowModelOverride: true.
• Usa plugins.entries.<id>.subagent.allowedModels para restringir los Plugin de confianza a destinos canónicos específicos provider/model, o "*" para permitir explícitamente cualquier destino.
• Las ejecuciones de subagentes de Plugin no confiables siguen funcionando, pero las solicitudes de anulación se rechazan en lugar de recurrir silenciosamente a una alternativa.

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

• Mantén en el núcleo la selección de proveedor, la resolución de credenciales y la semántica compartida de solicitudes.
• Usa proveedores de búsqueda web para transportes de búsqueda específicos del proveedor.
• api.runtime.webSearch.* es la superficie compartida preferida para Plugin de característica/canal que necesiten comportamiento de búsqueda sin depender del envoltorio de herramientas del 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(...): genera una imagen usando la cadena configurada de proveedores de generación de imágenes.
• listProviders(...): lista los proveedores disponibles de generación de imágenes y sus capacidades.

​

Rutas HTTP del Gateway

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

• path: ruta bajo el servidor HTTP del Gateway.
• auth: obligatorio. Usa "gateway" para requerir la autenticación normal del Gateway, o "plugin" para autenticación/verificación de Webhook gestionada por el Plugin.
• match: opcional. "exact" (predeterminado) o "prefix".
• replaceExisting: opcional. Permite que el mismo Plugin reemplace su propio registro de ruta existente.
• handler: devuelve true cuando la ruta gestionó la solicitud.

• api.registerHttpHandler(...) se eliminó y provocará un error de carga del Plugin. Usa api.registerHttpRoute(...) en su lugar.
• Las rutas de Plugin deben declarar auth explícitamente.
• Los conflictos exactos de path + match se rechazan salvo que replaceExisting: true, y un Plugin no puede reemplazar la ruta de otro Plugin.
• Las rutas superpuestas con distintos niveles de auth se rechazan. Mantén las cadenas de continuidad exact/prefix solo en el mismo nivel de autenticación.
• Las rutas auth: "plugin" no reciben automáticamente ámbitos de ejecución del operador. Son para webhooks/verificación de firma gestionados por el Plugin, no para llamadas privilegiadas a helpers del Gateway.
• Las rutas auth: "gateway" se ejecutan dentro de un ámbito de ejecución de solicitud del Gateway, pero ese ámbito es intencionalmente conservador:
  • la autenticación bearer con secreto compartido (gateway.auth.mode = "token" / "password") mantiene los ámbitos de ejecución de la ruta del Plugin fijados en operator.write, incluso si el llamador envía x-openclaw-scopes
  • los modos HTTP de confianza con identidad (por ejemplo trusted-proxy o gateway.auth.mode = "none" en un ingreso privado) respetan x-openclaw-scopes solo cuando el encabezado está presente explícitamente
  • si x-openclaw-scopes está ausente en esas solicitudes de ruta de Plugin con identidad, el ámbito de ejecución vuelve a operator.write
• Regla práctica: no asumas que una ruta de Plugin autenticada por gateway es implícitamente una superficie de administración. Si tu ruta necesita comportamiento solo de administrador, exige un modo de autenticación con identidad y documenta el contrato explícito del encabezado x-openclaw-scopes.

​

Rutas de importación del SDK de Plugin

• index.js — entrada del Plugin integrado
• api.js — barrel de helpers/tipos
• runtime-api.js — barrel solo de tiempo de ejecución
• setup-entry.js — entrada del Plugin de configuración

​

Esquemas de herramientas de mensajes

• presentation para bloques de presentación semántica (text, context, divider, buttons, select)
• delivery-pin para solicitudes de entrega fijada

​

Resolución de objetivos de canal

• messaging.inferTargetChatType({ to }) decide si un objetivo normalizado debe tratarse como direct, group o channel antes de la búsqueda en el directorio.
• messaging.targetResolver.looksLikeId(raw, normalized) indica al núcleo si una entrada debe pasar directamente a la resolución tipo id. en lugar de a la búsqueda en directorio.
• messaging.targetResolver.resolveTarget(...) es la alternativa del Plugin cuando el núcleo necesita una resolución final propiedad del proveedor después de la normalización o tras un fallo de búsqueda en el directorio.
• messaging.resolveOutboundSessionRoute(...) posee la construcción de la ruta de sesión específica del proveedor una vez resuelto un objetivo.

• Usa inferTargetChatType para decisiones de categoría que deben ocurrir antes de buscar pares/grupos.
• Usa looksLikeId para comprobaciones de “tratar esto como un id. de objetivo explícito/nativo”.
• Usa resolveTarget para la alternativa de normalización específica del proveedor, no para una búsqueda amplia en el directorio.
• Mantén id. nativos del proveedor, como id. de chat, id. de hilo, JID, identificadores y id. de sala, dentro de valores target o parámetros específicos del proveedor, no en campos genéricos del SDK.

​

Directorios respaldados por configuración

• pares de mensajes directos impulsados por lista de permitidos
• mapas configurados de canal/grupo
• alternativas de directorio estático con ámbito de cuenta

• filtrado de consultas
• aplicación de límites
• helpers de deduplicación/normalización
• construcción de ChannelDirectoryEntry[]

​

Catálogos de proveedores

• { provider } para una entrada de proveedor
• { providers } para varias entradas de proveedor

• simple: proveedores sencillos impulsados por clave de API o entorno
• profile: proveedores que aparecen cuando existen perfiles de autenticación
• paired: proveedores que sintetizan varias entradas relacionadas de proveedor
• late: última pasada, después de otros proveedores implícitos

• discovery sigue funcionando como alias heredado
• si se registran tanto catalog como discovery, OpenClaw usa catalog

​

Inspección de canal de solo lectura

• resolveAccount(...) es la ruta de tiempo de ejecución. Puede asumir que las credenciales están completamente materializadas y puede fallar rápidamente cuando faltan secretos requeridos.
• Las rutas de comandos de solo lectura como openclaw status, openclaw status --all, openclaw channels status, openclaw channels resolve y los flujos de doctor/reparación de configuración no deberían necesitar materializar credenciales de tiempo de ejecución solo para describir la configuración.

• Devuelve solo el estado descriptivo de la cuenta.
• Conserva enabled y configured.
• Incluye campos de origen/estado de credenciales cuando sea relevante, como:
  • tokenSource, tokenStatus
  • botTokenSource, botTokenStatus
  • appTokenSource, appTokenStatus
  • signingSecretSource, signingSecretStatus
• No necesitas devolver valores sin procesar de tokens solo para informar disponibilidad de solo lectura. Devolver tokenStatus: "available" (y el campo de origen correspondiente) es suficiente para comandos de tipo estado.
• Usa configured_unavailable cuando una credencial esté configurada mediante SecretRef pero no esté disponible en la ruta de comando actual.

​

Paquetes empaquetados

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

• el propio registro del canal
• cualquier ruta HTTP que deba estar disponible antes de que el Gateway empiece a escuchar
• cualquier método, herramienta o servicio del Gateway que deba existir durante esa misma ventana

• singleAccountKeysToMove
• namedAccountPromotionKeys
• resolveSingleAccountPromotionTarget(...)

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

​

Metadatos del catálogo de canales

{
  "name": "@openclaw/nextcloud-talk",
  "openclaw": {
    "extensions": ["./index.ts"],
    "channel": {
      "id": "nextcloud-talk",
      "label": "Nextcloud Talk",
      "selectionLabel": "Nextcloud Talk (alojado por cuenta propia)",
      "docsPath": "/channels/nextcloud-talk",
      "docsLabel": "nextcloud-talk",
      "blurb": "Chat alojado por cuenta propia mediante bots de Webhook de Nextcloud Talk.",
      "order": 65,
      "aliases": ["nc-talk", "nc"]
    },
    "install": {
      "npmSpec": "@openclaw/nextcloud-talk",
      "localPath": "<bundled-plugin-local-path>",
      "defaultChoice": "npm"
    }
  }
}

• detailLabel: etiqueta secundaria para superficies de catálogo/estado más ricas
• docsLabel: anula el texto del enlace para el enlace a la documentación
• preferOver: id. de Plugin/canal de menor prioridad a los que esta entrada de catálogo debe superar
• selectionDocsPrefix, selectionDocsOmitLabel, selectionExtras: controles de texto para la superficie de selección
• markdownCapable: marca el canal como compatible con Markdown para decisiones de formato saliente
• exposure.configured: oculta el canal de las superficies de listado de canales configurados cuando se establece en false
• exposure.setup: oculta el canal de los selectores interactivos de configuración/cuadro de configuración cuando se establece en false
• exposure.docs: marca el canal como interno/privado para las superficies de navegación de documentación
• showConfigured / showInSetup: alias heredados que siguen aceptándose por compatibilidad; prefiere exposure
• quickstartAllowFrom: hace que el canal participe en el flujo estándar de inicio rápido allowFrom
• forceAccountBinding: requiere vinculación explícita de cuenta incluso cuando solo existe una cuenta
• preferSessionLookupForAnnounceTarget: prefiere la búsqueda de sesión al resolver objetivos de anuncio

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

​

Plugin de motor 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);
    },
  }));
}

​

Agregar una nueva capacidad

1. define el contrato del núcleo Decide qué comportamiento compartido debe poseer el núcleo: política, alternativa, combinación de configuración, ciclo de vida, semántica orientada al canal y forma del helper de tiempo de ejecución.
2. añade superficies tipadas de registro/tiempo de ejecución de Plugin Amplía OpenClawPluginApi y/o api.runtime con la superficie tipada de capacidad útil más pequeña.
3. conecta consumidores del núcleo y de canal/característica Los canales y los Plugin de características deben consumir la nueva capacidad a través del núcleo, no importando directamente una implementación del proveedor.
4. registra implementaciones del proveedor Los Plugin del proveedor registran entonces sus backends contra la capacidad.
5. añade cobertura de contrato Añade pruebas para que la propiedad y la forma del registro sigan siendo explícitas con el tiempo.

​

Lista de comprobación de capacidades

• tipos de contrato del núcleo en src/<capability>/types.ts
• ejecutor/helper de tiempo de ejecución del núcleo en src/<capability>/runtime.ts
• superficie de registro de API de Plugin en src/plugins/types.ts
• cableado del registro de Plugin en src/plugins/registry.ts
• exposición del tiempo de ejecución del Plugin en src/plugins/runtime/* cuando los Plugin de característica/canal necesiten consumirla
• helpers de captura/prueba en src/test-utils/plugin-registration.ts
• aserciones de propiedad/contrato en src/plugins/contracts/registry.ts
• documentación para operadores/Plugin en docs/

​

Plantilla de capacidad

// contrato del núcleo
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);
  },
});

// helper compartido de tiempo de ejecución para Plugin de característica/canal
const clip = await api.runtime.videoGeneration.generate({
  prompt: "Show the robot walking through the lab.",
  cfg,
});

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

• el núcleo posee el contrato de capacidad + la orquestación
• los Plugin del proveedor poseen las implementaciones del proveedor
• los Plugin de característica/canal consumen helpers de tiempo de ejecución
• las pruebas de contrato mantienen explícita la propiedad

​

Relacionado

• Arquitectura de Plugin — modelo público de capacidades y formas
• Subrutas del SDK de Plugin
• Configuración del SDK de Plugin
• Creación de Plugin