Detalles internos de la arquitectura de plugins

​

Pipeline de carga

1. descubre las raíces de plugins candidatas
2. lee los manifiestos de paquetes nativos o compatibles y los metadatos de paquetes
3. rechaza los candidatos no seguros
4. normaliza la configuración de los plugins (plugins.enabled, allow, deny, entries, slots, load.paths)
5. decide la habilitación de cada candidato
6. carga los módulos nativos habilitados: los módulos incluidos y compilados usan un cargador nativo; el código fuente TypeScript local de terceros usa el mecanismo de reserva de emergencia Jiti
7. llama a los hooks nativos register(api) y recopila los registros en el registro de plugins
8. expone el registro a los comandos y las superficies de tiempo de ejecución

• su punto de entrada resuelto sale de la raíz del plugin
• su ruta (o su directorio raíz) permite la escritura a cualquier usuario
• para los plugins no incluidos, la propiedad de la ruta no coincide con el uid actual (o root)

​

Comportamiento basado primero en el manifiesto

• identificar el plugin
• descubrir los canales, Skills, esquemas de configuración o capacidades del paquete declarados
• validar plugins.entries.<id>.config
• ampliar las etiquetas y los textos de marcador de posición de la interfaz de control
• mostrar los metadatos de instalación y catálogo
• conservar descriptores ligeros de activación y configuración sin cargar el tiempo de ejecución del plugin

• la carga de la CLI se limita a los plugins que poseen el comando principal solicitado
• la configuración del canal o resolución del plugin se limita a los plugins que poseen el id de canal solicitado
• la configuración explícita o resolución en tiempo de ejecución del proveedor se limita a los plugins que poseen el id de proveedor solicitado
• la planificación del inicio del Gateway utiliza activation.onStartup para las importaciones explícitas de inicio; los plugins sin metadatos de inicio solo se cargan mediante activadores de activación más específicos

​

Límite de caché de plugins

• PluginLoaderCacheState y registros activos de tiempo de ejecución compatibles
• cachés de jiti/módulos y cachés de cargadores de superficies públicas utilizadas para evitar importar repetidamente la misma superficie de tiempo de ejecución
• cachés del sistema de archivos para los artefactos de plugins instalados
• mapas de corta duración por llamada para normalizar rutas o resolver duplicados

• resultados del descubrimiento
• registros directos de manifiestos
• registros de manifiestos reconstruidos a partir del índice de plugins instalados
• la búsqueda del propietario del proveedor, la supresión de modelos, la política de proveedores o los metadatos de artefactos públicos
• cualquier otra respuesta derivada de manifiestos en la que un cambio en el manifiesto, el índice instalado o la ruta de carga deba ser visible en la siguiente lectura de metadatos

​

Modelo de registro

• módulo del 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 y esta conversación.
        console.log(event.binding?.conversationId);
        return;
      }

      // La solicitud se denegó; 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 las solicitudes aprobadas
• request: el resumen de la solicitud original, la indicación de desvinculación, el id del remitente y los metadatos de la conversación

​

Hooks de tiempo de ejecución del proveedor

• Metadatos del manifiesto para búsquedas ligeras previas al tiempo de ejecución: setup.providers[].envVars, providerAuthAliases, providerAuthChoices y channelConfigs.
• Hooks durante la configuración: catalog más applyConfigDefaults.
• Hooks de tiempo de ejecución: más de 40 hooks opcionales que abarcan la autenticación, la resolución de modelos, el encapsulado de flujos, los niveles de razonamiento, la política de reproducción y los endpoints de uso. Consulte Orden y uso de los hooks.

​

Orden y uso de los 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

​

Ayudantes de tiempo 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 archivos/notas de voz.
• Utiliza la configuración tts y la selección de proveedor del núcleo.
• Devuelve un búfer de audio PCM y la frecuencia de muestreo. Los plugins deben remuestrear/codificar para los proveedores.
• listVoices es opcional para cada proveedor. Se utiliza para selectores de voz o flujos de configuración gestionados por el proveedor.
• El núcleo pasa un plazo de solicitud resuelto a los hooks listVoices del proveedor; los ajustes de tiempo de espera específicos del proveedor pueden reemplazarlo.
• Las listas de voces pueden incluir metadatos más completos, como configuración regional, género y etiquetas de personalidad, para selectores conscientes del proveedor.
• OpenAI y ElevenLabs admiten actualmente telefonía. 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,
    };
  },
});

• Mantenga en el núcleo la política de TTS, las alternativas y la entrega de respuestas.
• Utilice proveedores de voz para el comportamiento de síntesis gestionado por el proveedor.
• La entrada heredada edge de Microsoft se normaliza al identificador de proveedor microsoft.
• El modelo de propiedad preferido está orientado a empresas: un plugin de proveedor puede gestionar proveedores de texto, voz, imágenes y medios futuros a medida que OpenClaw añada esos contratos de capacidades.

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

• Mantenga en el núcleo la orquestación, las alternativas, la configuración y la conexión con canales.
• Mantenga el comportamiento del proveedor en el plugin del proveedor.
• La ampliación aditiva debe conservar los tipos: nuevos métodos opcionales, nuevos campos de resultados opcionales y nuevas capacidades opcionales.
• La generación de vídeo ya sigue el mismo patrón:
  • el núcleo gestiona el contrato de capacidades y el ayudante de tiempo de ejecución
  • los plugins de proveedores registran api.registerVideoGenerationProvider(...)
  • los plugins de funcionalidades/canales 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 extraction = await api.runtime.mediaUnderstanding.extractStructuredWithModel({
  provider: "codex",
  model: "gpt-5.6-sol",
  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.* es la superficie compartida preferida para la comprensión de imágenes/audio/vídeo.
• extractStructuredWithModel(...) es la interfaz orientada a plugins para la extracción acotada, centrada primero en imágenes y gestionada por el proveedor. Incluya al menos una entrada de imagen; las entradas de texto son contexto complementario. Los plugins de producto gestionan sus rutas y esquemas, mientras que OpenClaw gestiona el límite entre el proveedor y el tiempo de ejecución.
• Utiliza la configuración de audio de comprensión multimedia del núcleo (tools.media.audio) y el orden de alternativas de proveedores.
• Devuelve { text: undefined } cuando no se produce ninguna salida de transcripción (por ejemplo, una entrada omitida/no compatible).

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

• provider y model son reemplazos opcionales por ejecución, no cambios persistentes de la sesión.
• toolsAlsoAllow acepta nombres de herramientas exactos y con propietario único registrados por el plugin llamador. Se rechazan los nombres del núcleo y los ambiguos. Se añade al perfil normal, pero las listas de permisos y denegaciones del operador siguen siendo autoritativas.
• OpenClaw solo respeta esos campos de reemplazo para llamadores de confianza.
• Para las ejecuciones alternativas gestionadas por plugins, los operadores deben habilitarlas explícitamente con plugins.entries.<id>.subagent.allowModelOverride: true.
• Utilice plugins.entries.<id>.subagent.allowedModels para restringir los plugins de confianza a destinos canónicos provider/model específicos, o "*" para permitir explícitamente cualquier destino.
• Las ejecuciones de subagentes de plugins que no son de confianza siguen funcionando, pero las solicitudes de reemplazo se rechazan en lugar de recurrir silenciosamente a una alternativa.
• Las sesiones de subagentes creadas por plugins se etiquetan con el identificador del plugin creador. El mecanismo alternativo api.runtime.subagent.deleteSession(...) solo puede eliminar esas sesiones propias; la eliminación arbitraria de sesiones sigue requiriendo una solicitud del Gateway con ámbito 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,
  },
});

• Mantenga en el núcleo la selección de proveedores, la resolución de credenciales y la semántica compartida de las solicitudes.
• Utilice proveedores de búsqueda web para transportes de búsqueda específicos del proveedor.
• api.runtime.webSearch.* es la superficie compartida preferida para plugins de funcionalidades/canales que necesitan comportamiento de búsqueda sin depender del contenedor 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 mediante la cadena de proveedores de generación de imágenes configurada.
• listProviders(...): enumera los proveedores de generación de imágenes disponibles 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 dentro del servidor HTTP del Gateway.
• auth: obligatorio, "gateway" o "plugin". Use "gateway" para exigir la autenticación normal del Gateway, o "plugin" para la autenticación o verificación de Webhooks gestionada por el plugin.
• match: opcional. "exact" (predeterminado) o "prefix".
• handleUpgrade: controlador opcional para solicitudes de actualización a WebSocket en la misma ruta.
• replaceExisting: opcional. Permite que el mismo plugin sustituya su propio registro de ruta existente.
• handler: devuelve true cuando la ruta haya gestionado la solicitud.

• api.registerHttpHandler(...) se eliminó y provocará un error al cargar el plugin. Use api.registerHttpRoute(...) en su lugar.
• Las rutas de plugins deben declarar auth explícitamente.
• Los conflictos exactos de path + match se rechazan salvo que se use replaceExisting: true, y un plugin no puede sustituir la ruta de otro plugin.
• Las rutas superpuestas con distintos niveles de auth se rechazan. Mantenga las cadenas de continuidad exact/prefix únicamente en el mismo nivel de autenticación.
• Las rutas auth: "plugin" no reciben automáticamente ámbitos de ejecución del operador. Están destinadas a Webhooks o a la verificación de firmas gestionados por el plugin, no a llamadas privilegiadas a los auxiliares del Gateway.
• Las rutas auth: "gateway" se ejecutan dentro del ámbito de ejecución de una solicitud del Gateway. La superficie predeterminada (gatewayRuntimeScopeSurface: "write-default") es intencionadamente conservadora:
  • la autenticación de portador mediante secreto compartido (gateway.auth.mode = "token" / "password") y cualquier método de autenticación que no sea de proxy de confianza obtienen un único ámbito operator.write, incluso si el llamador envía x-openclaw-scopes
  • los llamadores trusted-proxy sin un encabezado x-openclaw-scopes explícito también conservan la superficie heredada limitada a operator.write
  • los llamadores trusted-proxy que sí envían x-openclaw-scopes obtienen en su lugar los ámbitos declarados
  • una ruta puede optar por gatewayRuntimeScopeSurface: "trusted-operator" para respetar siempre x-openclaw-scopes en los modos de autenticación que incluyen identidad (y recurrir al conjunto completo de ámbitos predeterminados de la CLI cuando el encabezado no está presente)
• Las pestañas externas aisladas de la interfaz de control respaldadas por rutas auth: "gateway" usan una concesión de cookie firmada y de corta duración, emitida únicamente mediante un arranque autenticado; las pestañas con autenticación de plugin conservan su ruta directa de iframe. Antes del montaje, el elemento principal ejecuta una comprobación propiedad de la ruta dentro del mismo entorno aislado opaco y bloquea el acceso cuando la política de privacidad del navegador impide usar la cookie. La concesión está vinculada al plugin propietario, a la raíz de la ruta coincidente y a la generación de autenticación actual; el nombre aleatorio por proceso de su cookie evita que Gateways de confianza del mismo host se sobrescriban entre sí, pero las cookies nunca aíslan los puertos TCP. Por tanto, el nombre de host del Gateway constituye un único límite de credenciales: no aloje conjuntamente servicios que no confíen entre sí en ese nombre de host, ni siquiera en otros puertos. El enrutamiento rechaza reutilizarla en una ruta anidada propiedad de otro plugin. Como los descendientes del entorno aislado son sitios distintos a efectos de las cookies, la concesión solo acepta GET y HEAD con operator.read; las mutaciones y actualizaciones a WebSocket permanecen en superficies con autenticación explícita del Gateway. La cookie no puede usar CHIPS intencionadamente: los navegadores actuales incluyen un bit de ancestro entre sitios en la clave de partición, por lo que los marcos aislados opacos anidados perderían el acceso a los recursos de la misma ruta. La cookie requiere un contexto seguro y permiso del navegador para usar cookies entre sitios, por lo que las pestañas externas con autenticación del Gateway no están disponibles en orígenes LAN con HTTP simple ni cuando se bloquean por completo las cookies de terceros; use HTTPS/Tailscale Serve o un bucle local de confianza para el navegador con una política de cookies compatible.
• La concesión impide la divulgación del token de portador del Gateway y la reutilización accidental de rutas o ámbitos; no crea un límite de seguridad entre plugins nativos. El código de los plugins nativos y el contenido de la interfaz que sirven siguen formando parte del mismo límite de confianza del plugin dentro del proceso.
• Regla práctica: no suponga que una ruta de plugin con autenticación del Gateway sea implícitamente una superficie administrativa. Si la ruta necesita un comportamiento exclusivo para administradores, opte por la superficie de ámbitos trusted-operator, exija un modo de autenticación que incluya identidad y documente el contrato explícito del encabezado x-openclaw-scopes.
• Después de encontrar la ruta y autenticar la solicitud, los controladores normales participan en la admisión de trabajo raíz del Gateway. Un Gateway preparado o en proceso de reinicio devuelve 503 antes de invocar el controlador. La única excepción limitada es una ruta auth: "gateway" autorizada por el manifiesto que también opte por la superficie específica de la ruta trusted-operator; permanece accesible para que el enrutamiento del control de suspensión no quede bloqueado, mientras que las demás rutas normales del mismo plugin permanecen detrás del límite de admisión. La propiedad de handleUpgrade de WebSocket utiliza el mismo límite de admisión atómico; una vez que el controlador acepta un socket, su ciclo de vida posterior pertenece al plugin y este límite no realiza su seguimiento.

​

Rutas de importación del SDK de plugins

• index.js — punto de entrada del plugin incluido
• api.js — barrel de auxiliares y tipos
• runtime-api.js — barrel exclusivo de ejecución
• setup-entry.js — punto de entrada de configuración del plugin

​

Esquemas de la herramienta de mensajes

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

​

Resolución de destinos de canales

• messaging.inferTargetChatType({ to }) decide si un destino normalizado debe tratarse como direct, group o channel antes de buscarlo en el directorio.
• messaging.targetResolver.looksLikeId(raw, normalized) indica al núcleo si una entrada debe pasar directamente a una resolución similar a un identificador en lugar de buscar en el directorio.
• messaging.targetResolver.reservedLiterals enumera las palabras sin formato que son referencias de canal o sesión para ese proveedor. La resolución conserva las entradas configuradas del directorio antes de rechazar los literales reservados y, después, se bloquea si no encuentra una coincidencia en el directorio.
• messaging.targetResolver.resolveTarget(...) es la alternativa del plugin cuando el núcleo necesita una resolución final propiedad del proveedor tras la normalización o después de no encontrar una coincidencia en el directorio.
• messaging.resolveOutboundSessionRoute(...) controla la construcción de rutas de sesión específicas del proveedor una vez resuelto el destino.

• Use inferTargetChatType para las decisiones de categoría que deban tomarse antes de buscar pares o grupos.
• Use looksLikeId para comprobar si «esto debe tratarse como un identificador de destino explícito o nativo».
• Use resolveTarget como alternativa de normalización específica del proveedor, no para búsquedas amplias en el directorio.
• Mantenga los identificadores nativos del proveedor, como identificadores de chat, de hilos, JID, nombres de usuario e identificadores de salas, dentro de los valores target o de parámetros específicos del proveedor, no en campos genéricos del SDK.

​

Directorios respaldados por la configuración

• pares de mensajes directos controlados mediante una lista de permitidos
• asignaciones configuradas de canales o grupos
• alternativas de directorio estáticas limitadas a una cuenta

• filtrado de consultas
• aplicación de límites
• auxiliares de desduplicación y normalización
• creación de ChannelDirectoryEntry[]

​

Catálogos de proveedores

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

• simple: proveedores simples basados en claves de API o variables de entorno
• profile: proveedores que aparecen cuando existen perfiles de autenticación
• paired: proveedores que sintetizan varias entradas de proveedor relacionadas
• late: última pasada, después de los demás proveedores implícitos

• discovery sigue funcionando como alias heredado, pero emite una advertencia de obsolescencia
• si se registran tanto catalog como discovery, OpenClaw usa catalog y emite una advertencia
• augmentModelCatalog está obsoleto; los proveedores incluidos deben publicar filas complementarias mediante registerModelCatalogProvider

​

Inspección de canales de solo lectura

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

• Devuelva únicamente el estado descriptivo de la cuenta.
• Conserve enabled y configured.
• Incluya campos de origen/estado de las credenciales cuando corresponda, como:
  • tokenSource, tokenStatus
  • botTokenSource, botTokenStatus
  • appTokenSource, appTokenStatus
  • signingSecretSource, signingSecretStatus
• No es necesario devolver los valores sin procesar de los tokens solo para informar sobre la disponibilidad de solo lectura. Devolver tokenStatus: "available" (y el campo de origen correspondiente) es suficiente para los comandos de estado.
• Use configured_unavailable cuando una credencial esté configurada mediante SecretRef, pero no esté disponible en la ruta de comandos actual.

​

Paquetes de plugins

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

• el propio registro del canal
• todas las rutas HTTP que deban estar disponibles antes de que el gateway comience a escuchar
• todos los métodos, herramientas o servicios del gateway que deban existir durante ese mismo periodo

• 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 (alojamiento propio)",
      "docsPath": "/channels/nextcloud-talk",
      "docsLabel": "nextcloud-talk",
      "blurb": "Chat con alojamiento propio 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 completas
• docsLabel: sobrescribe el texto del enlace a la documentación
• preferOver: identificadores de plugins/canales de menor prioridad que esta entrada del catálogo debe superar
• selectionDocsPrefix, selectionDocsOmitLabel, selectionExtras: controles de texto de la superficie de selección
• markdownCapable: marca el canal como compatible con Markdown para las decisiones de formato saliente
• exposure.configured: oculta el canal en las superficies de listado de canales configurados cuando se establece en false
• exposure.setup: oculta el canal en los selectores interactivos de configuración cuando se establece en false
• exposure.docs: marca el canal como interno/privado para las superficies de navegación de la documentación
• quickstartAllowFrom: incorpora el canal al flujo estándar de inicio rápido allowFrom
• forceAccountBinding: exige una vinculación explícita de la cuenta incluso cuando solo existe una
• preferSessionLookupForAnnounceTarget: prioriza la búsqueda de sesiones al resolver los destinos de anuncios

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

​

Plugins del motor 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, sessionKey, availableTools, citationsMode }) {
      return {
        messages,
        estimatedTokens: 0,
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
          agentSessionKey: sessionKey,
        }),
      };
    },
    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, sessionKey, availableTools, citationsMode }) {
      return {
        messages,
        estimatedTokens: 0,
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
          agentSessionKey: sessionKey,
        }),
      };
    },
    async compact(params) {
      return await delegateCompactionToRuntime(params);
    },
  }));
}

​

Añadir una capacidad nueva

1. Defina el contrato del núcleo. Decida qué comportamiento compartido debe controlar el núcleo: políticas, mecanismo alternativo, combinación de configuración, ciclo de vida, semántica orientada a canales y forma del asistente de tiempo de ejecución.
2. Añada superficies tipadas de registro y tiempo de ejecución de plugins. Amplíe OpenClawPluginApi y/o api.runtime con la superficie tipada de capacidad útil más pequeña.
3. Conecte el núcleo y los consumidores de canales/funcionalidades. Los canales y plugins de funcionalidades deben consumir la nueva capacidad a través del núcleo, no importando directamente una implementación de un proveedor.
4. Registre las implementaciones de los proveedores. A continuación, los plugins de los proveedores registran sus backends para la capacidad.
5. Añada cobertura del contrato. Añada pruebas para que la propiedad y la forma del registro permanezcan explícitas con el tiempo.

​

Lista de comprobación de capacidades

• tipos de contratos del núcleo en src/<capability>/types.ts
• ejecutor o asistente de tiempo de ejecución del núcleo en src/<capability>/runtime.ts
• superficie de registro de la API de plugins en src/plugins/types.ts
• conexión del registro de plugins en src/plugins/registry.ts
• exposición del tiempo de ejecución del plugin en src/plugins/runtime/* cuando los plugins de funcionalidades o canales necesiten consumirla
• asistentes de captura y pruebas en src/test-utils/plugin-registration.ts
• aserciones de propiedad y contrato en src/plugins/contracts/registry.ts
• documentación para operadores y plugins en docs/

​

Plantilla de capacidad

// 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(pluginManifest.contracts?.videoGenerationProviders).toEqual(["openai"]);

• el núcleo controla el contrato y la orquestación de la capacidad
• los plugins de los proveedores controlan sus implementaciones
• los plugins de funcionalidades y canales consumen los asistentes de tiempo de ejecución
• las pruebas de contratos mantienen explícita la propiedad

​

Contenido relacionado

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