Saltar al contenido principal

Documentation Index

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

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

Para el modelo público de capacidades, las formas de Plugin y los contratos de propiedad/ejecución, consulta arquitectura de Plugin. Esta página es la referencia para la mecánica interna: canalización de carga, registro, hooks de runtime, rutas HTTP del Gateway, rutas de importación y tablas de esquema.

Canalización de carga

Al iniciar, OpenClaw hace aproximadamente esto:
  1. descubre raíces candidatas de Plugin
  2. lee manifiestos de bundles nativos o compatibles y metadatos del paquete
  3. rechaza candidatos no seguros
  4. normaliza la configuración de 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 construidos usan un cargador nativo; el código fuente local TypeScript de terceros usa el fallback de emergencia Jiti
  7. llama a los hooks nativos register(api) y recopila los registros en el registro de Plugin
  8. expone el registro a comandos/superficies de runtime
activate es un alias heredado de register: el cargador resuelve el que esté presente (def.register ?? def.activate) y lo llama en el mismo punto. Todos los plugins integrados usan register; prefiere register para plugins nuevos.
Las puertas de seguridad ocurren antes de la ejecución de runtime. Los candidatos se bloquean cuando la entrada escapa de la raíz del Plugin, la ruta es escribible por todo el mundo o la propiedad de la ruta parece sospechosa para plugins no integrados. Los candidatos bloqueados permanecen vinculados a su id de Plugin para diagnósticos. Si la configuración todavía hace referencia a ese id, la validación informa que el Plugin está presente pero bloqueado y apunta de nuevo a la advertencia de seguridad de ruta en lugar de tratar la entrada de configuración como obsoleta.

Comportamiento centrado en el manifiesto

El manifiesto es la fuente de verdad del plano de control. OpenClaw lo usa para:
  • identificar el Plugin
  • descubrir canales/Skills/esquema de configuración declarados o capacidades del bundle
  • 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 runtime del Plugin
Para plugins nativos, el módulo de runtime es la parte del plano de datos. Registra comportamiento real, como hooks, herramientas, comandos o flujos de proveedor. Los bloques opcionales activation y setup del manifiesto permanecen en el plano de control. Son descriptores de solo metadatos para la planificación de activación y el descubrimiento de configuración; no sustituyen el registro de runtime, register(...) ni setupEntry. Los primeros consumidores de activación en vivo ahora usan indicios de comandos, canales y proveedores del manifiesto para acotar la carga de Plugin antes de una materialización más amplia del registro:
  • la carga de la CLI se acota a los plugins que poseen el comando principal solicitado
  • la resolución de configuración/Plugin de canal se acota a los plugins que poseen el id de canal solicitado
  • la resolución explícita de configuración/runtime de proveedor se acota a los plugins que poseen el id de proveedor solicitado
  • la planificación de inicio del Gateway usa activation.onStartup para importaciones explícitas de inicio y exclusiones de inicio; los plugins sin metadatos de inicio se cargan solo mediante disparadores de activación más acotados
Las precargas de runtime en tiempo de solicitud que piden el ámbito amplio all siguen derivando un conjunto explícito efectivo de ids de Plugin a partir de la configuración, la planificación de inicio, los canales configurados, los slots y las reglas de habilitación automática. Si ese conjunto derivado está vacío, OpenClaw carga un registro de runtime vacío en lugar de ampliarse a todos los plugins descubribles. El planificador de activación expone tanto una API solo de ids para llamadores existentes como una API de plan para diagnósticos nuevos. Las entradas del plan informan por qué se seleccionó un Plugin, separando los indicios explícitos del planificador activation.* de la propiedad de manifiesto de fallback, como providers, channels, commandAliases, setup.providers, contracts.tools y hooks. Esa separación de motivos es el límite de compatibilidad: los metadatos existentes de Plugin siguen funcionando, mientras que el código nuevo puede detectar indicios amplios o comportamiento de fallback sin cambiar la semántica de carga de runtime. El descubrimiento de configuración ahora prefiere ids propiedad del descriptor, como setup.providers y setup.cliBackends, para acotar plugins candidatos antes de recurrir a setup-api para plugins que todavía necesitan hooks de runtime en tiempo de configuración. Las listas de configuración de proveedores usan providerAuthChoices del manifiesto, opciones de configuración derivadas de descriptores y metadatos de catálogo de instalación sin cargar el runtime del proveedor. setup.requiresRuntime: false explícito es un corte solo de descriptor; omitir requiresRuntime mantiene el fallback heredado de setup-api por compatibilidad. Si más de un Plugin descubierto reclama el mismo id normalizado de proveedor de configuración o backend de CLI, la búsqueda de configuración rechaza el propietario ambiguo en lugar de depender del orden de descubrimiento. Cuando sí se ejecuta el runtime de configuración, los diagnósticos del registro informan desviaciones entre setup.providers / setup.cliBackends y los proveedores o backends de CLI registrados por setup-api sin bloquear plugins heredados.

Límite de caché de Plugin

OpenClaw no almacena en caché los resultados de descubrimiento de Plugin ni datos directos del registro de manifiestos detrás de ventanas de reloj de pared. Las instalaciones, ediciones de manifiestos y cambios de rutas de carga deben volverse visibles en la siguiente lectura explícita de metadatos o reconstrucción de snapshot. El analizador de archivos de manifiesto puede mantener una caché acotada de firma de archivo, indexada por la ruta de manifiesto abierta, inode, tamaño y marcas de tiempo; esa caché solo evita volver a analizar bytes sin cambios y no debe almacenar en caché respuestas de descubrimiento, registro, propietario o política. La ruta rápida segura de metadatos es la propiedad explícita de objetos, no una caché oculta. Las rutas críticas de inicio del Gateway deben pasar el PluginMetadataSnapshot actual, la PluginLookUpTable derivada o un registro explícito de manifiestos por la cadena de llamadas. La validación de configuración, la habilitación automática de inicio, el arranque de Plugin y la selección de proveedor pueden reutilizar esos objetos mientras representen la configuración y el inventario de Plugin actuales. La búsqueda de configuración todavía reconstruye metadatos de manifiesto bajo demanda salvo que la ruta específica de configuración reciba un registro explícito de manifiestos; mantén eso como fallback de ruta fría en lugar de añadir cachés ocultas de búsqueda. Cuando la entrada cambie, reconstruye y reemplaza el snapshot en lugar de mutarlo o conservar copias históricas. Las vistas sobre el registro activo de Plugin y los helpers de arranque de canales integrados deben recomputarse a partir del registro/raíz actual. Los mapas de vida corta están bien dentro de una llamada para deduplicar trabajo o proteger la reentrada; no deben convertirse en cachés de metadatos de proceso. Para la carga de Plugin, la capa de caché persistente es la carga de runtime. Puede reutilizar estado del cargador cuando el código o los artefactos instalados se cargan realmente, como:
  • PluginLoaderCacheState y registros activos de runtime compatibles
  • cachés de jiti/módulos y cachés de cargador de superficie pública usadas para evitar importar la misma superficie de runtime repetidamente
  • cachés de sistema de archivos para artefactos instalados de Plugin
  • mapas por llamada de vida corta para normalización de rutas o resolución de duplicados
Esas cachés son detalles de implementación del plano de datos. No deben responder preguntas del plano de control como “¿qué Plugin posee este proveedor?” salvo que el llamador haya pedido deliberadamente carga de runtime. No añadas cachés persistentes ni de reloj de pared para:
  • resultados de descubrimiento
  • registros directos de manifiestos
  • registros de manifiestos reconstruidos a partir del índice de plugins instalados
  • búsqueda de propietario de proveedor, supresión de modelos, política de proveedor o metadatos de artefacto público
  • cualquier otra respuesta derivada de manifiesto donde un manifiesto, índice instalado o ruta de carga cambiados deban ser visibles en la siguiente lectura de metadatos
Los llamadores que reconstruyen metadatos de manifiesto a partir del índice persistido de plugins instalados reconstruyen ese registro bajo demanda. El índice instalado es estado durable del plano fuente; no es una caché oculta de metadatos en proceso.

Modelo de registro

Los plugins cargados no mutan directamente globals aleatorios del core. Se registran en un registro central de Plugin. El registro rastrea:
  • registros de Plugin (identidad, fuente, origen, estado, diagnósticos)
  • herramientas
  • hooks heredados y hooks tipados
  • canales
  • proveedores
  • manejadores RPC del Gateway
  • rutas HTTP
  • registradores de CLI
  • servicios en segundo plano
  • comandos propiedad de Plugin
Luego, las funcionalidades del core leen de ese registro en lugar de comunicarse directamente con módulos de Plugin. Esto mantiene la carga en una sola dirección:
  • módulo de Plugin -> registro en el registro
  • runtime del core -> consumo del registro
Esa separación importa para la mantenibilidad. Significa que la mayoría de las superficies del core solo necesitan un punto de integración: “leer el registro”, no “especializar cada módulo de Plugin”.

Callbacks de vinculación de conversación

Los plugins que vinculan una conversación pueden reaccionar cuando se resuelve una aprobación. Usa api.onConversationBindingResolved(...) para recibir un callback después de que una solicitud de vinculación sea aprobada o denegada:
export default {
  id: "my-plugin",
  register(api) {
    api.onConversationBindingResolved(async (event) => {
      if (event.status === "approved") {
        // A binding now exists for this plugin + conversation.
        console.log(event.binding?.conversationId);
        return;
      }

      // The request was denied; clear any local pending state.
      console.log(event.request.conversation.conversationId);
    });
  },
};
Campos de la carga útil del callback:
  • 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, indicio de desvinculación, id del remitente y metadatos de conversación
Este callback es solo de notificación. No cambia quién tiene permitido vincular una conversación y se ejecuta después de que termina el manejo de aprobación del core.

Hooks de runtime de proveedor

Los plugins de proveedor tienen tres capas:
  • Metadatos de manifiesto para búsqueda barata previa al runtime: setup.providers[].envVars, compatibilidad obsoleta providerAuthEnvVars, providerAuthAliases, providerAuthChoices y channelEnvVars.
  • Hooks en tiempo de configuración: catalog (discovery heredado) más applyConfigDefaults.
  • Hooks de runtime: más de 40 hooks opcionales que cubren autenticación, resolución de modelos, envoltura de streams, niveles de razonamiento, política de reproducción y endpoints de uso. Consulta la lista completa en orden y uso de hooks.
OpenClaw sigue siendo propietario del bucle genérico de agente, failover, manejo de transcript y política de herramientas. Estos hooks son la superficie de extensión para comportamiento específico de proveedor sin necesitar un transporte de inferencia totalmente personalizado. Usa setup.providers[].envVars del manifiesto cuando el proveedor tenga credenciales basadas en env que las rutas genéricas de autenticación/estado/selector de modelos deban ver sin cargar el runtime del Plugin. providerAuthEnvVars obsoleto todavía es leído por el adaptador de compatibilidad durante la ventana de deprecación, y los plugins no integrados que lo usan reciben un diagnóstico de manifiesto. Usa providerAuthAliases del manifiesto cuando un id de proveedor deba reutilizar las env vars de otro id de proveedor, perfiles de autenticación, autenticación respaldada por configuración y opción de onboarding con clave de API. Usa providerAuthChoices del manifiesto cuando las superficies de CLI de onboarding/elección de autenticación deban conocer el id de opción del proveedor, etiquetas de grupo y cableado de autenticación simple de una bandera sin cargar el runtime del proveedor. Mantén envVars de runtime del proveedor para indicios orientados al operador, como etiquetas de onboarding o vars de configuración de client-id/client-secret de OAuth. Usa channelEnvVars del manifiesto cuando un canal tenga autenticación o configuración impulsada por env que el fallback genérico de env de shell, las comprobaciones de configuración/estado o los prompts de configuración deban ver sin cargar el runtime del canal.

Orden y uso de hooks

Para plugins de modelo/proveedor, OpenClaw llama hooks en este orden aproximado. La columna “Cuándo usar” es la guía rápida de decisión. Los campos de proveedor solo de compatibilidad que OpenClaw ya no llama, como ProviderPlugin.capabilities y suppressBuiltInModel, no se enumeran intencionalmente aquí.
#HookQué haceCuándo usarlo
1catalogPublica la configuración del proveedor en models.providers durante la generación de models.jsonEl proveedor es propietario de un catálogo o de valores predeterminados de URL base
2applyConfigDefaultsAplica los valores predeterminados de configuración global propiedad del proveedor durante la materialización de la configuraciónLos valores predeterminados dependen del modo de autenticación, el entorno o la semántica de la familia de modelos del proveedor
(búsqueda de modelos integrada)OpenClaw intenta primero la ruta normal de registro/catálogo(no es un hook de Plugin)
3normalizeModelIdNormaliza alias de ids de modelo heredados o de vista previa antes de la búsquedaEl proveedor es propietario de la limpieza de alias antes de la resolución canónica del modelo
4normalizeTransportNormaliza api / baseUrl de la familia del proveedor antes del ensamblado genérico del modeloEl proveedor es propietario de la limpieza de transporte para ids de proveedor personalizados en la misma familia de transporte
5normalizeConfigNormaliza models.providers.<id> antes de la resolución de tiempo de ejecución/proveedorEl proveedor necesita una limpieza de configuración que debería vivir con el Plugin; los helpers incluidos de la familia Google también respaldan entradas de configuración Google compatibles
6applyNativeStreamingUsageCompatAplica reescrituras de compatibilidad de uso de streaming nativo a los proveedores de configuraciónEl proveedor necesita correcciones de metadatos de uso de streaming nativo controladas por el endpoint
7resolveConfigApiKeyResuelve la autenticación con marcador de entorno para proveedores de configuración antes de cargar la autenticación de tiempo de ejecuciónEl proveedor tiene resolución de clave API con marcador de entorno propiedad del proveedor; amazon-bedrock también tiene aquí un resolvedor integrado de marcadores de entorno de AWS
8resolveSyntheticAuthExpone autenticación local/autohospedada o respaldada por configuración sin persistir texto planoEl proveedor puede operar con un marcador de credencial sintético/local
9resolveExternalAuthProfilesSuperpone perfiles de autenticación externa propiedad del proveedor; el valor predeterminado de persistence es runtime-only para credenciales propiedad de CLI/aplicaciónEl proveedor reutiliza credenciales de autenticación externa sin persistir tokens de actualización copiados; declara contracts.externalAuthProviders en el manifiesto
10shouldDeferSyntheticProfileAuthReduce la precedencia de los marcadores de posición de perfiles sintéticos almacenados frente a autenticación respaldada por entorno/configuraciónEl proveedor almacena perfiles de marcador de posición sintéticos que no deberían ganar precedencia
11resolveDynamicModelSincroniza una alternativa para ids de modelo propiedad del proveedor que aún no están en el registro localEl proveedor acepta ids de modelo ascendentes arbitrarios
12prepareDynamicModelCalentamiento asíncrono, luego resolveDynamicModel se ejecuta de nuevoEl proveedor necesita metadatos de red antes de resolver ids desconocidos
13normalizeResolvedModelReescritura final antes de que el ejecutor integrado use el modelo resueltoEl proveedor necesita reescrituras de transporte, pero sigue usando un transporte del núcleo
14contributeResolvedModelCompatAporta marcas de compatibilidad para modelos de proveedor detrás de otro transporte compatibleEl proveedor reconoce sus propios modelos en transportes proxy sin tomar el control del proveedor
15normalizeToolSchemasNormaliza esquemas de herramientas antes de que el ejecutor integrado los veaEl proveedor necesita limpieza de esquemas de la familia de transporte
16inspectToolSchemasExpone diagnósticos de esquemas propiedad del proveedor después de la normalizaciónEl proveedor quiere advertencias de palabras clave sin enseñar al núcleo reglas específicas del proveedor
17resolveReasoningOutputModeSelecciona el contrato de salida de razonamiento nativo frente al etiquetadoEl proveedor necesita razonamiento/salida final etiquetados en lugar de campos nativos
18prepareExtraParamsNormalización de parámetros de solicitud antes de los contenedores genéricos de opciones de streamingEl proveedor necesita parámetros de solicitud predeterminados o limpieza de parámetros por proveedor
19createStreamFnReemplaza por completo la ruta de streaming normal con un transporte personalizadoEl proveedor necesita un protocolo de cable personalizado, no solo un contenedor
20wrapStreamFnContenedor de streaming después de aplicar los contenedores genéricosEl proveedor necesita contenedores de compatibilidad de encabezados/cuerpo/modelo de solicitud sin un transporte personalizado
21resolveTransportTurnStateAdjunta encabezados o metadatos de transporte nativos por turnoEl proveedor quiere que los transportes genéricos envíen identidad de turno nativa del proveedor
22resolveWebSocketSessionPolicyAdjunta encabezados WebSocket nativos o una política de enfriamiento de sesiónEl proveedor quiere que los transportes WS genéricos ajusten encabezados de sesión o la política de alternativa
23formatApiKeyFormateador de perfil de autenticación: el perfil almacenado se convierte en la cadena apiKey de tiempo de ejecuciónEl proveedor almacena metadatos de autenticación adicionales y necesita una forma de token de tiempo de ejecución personalizada
24refreshOAuthSobrescritura de actualización OAuth para endpoints de actualización personalizados o política de error de actualizaciónEl proveedor no encaja con los actualizadores compartidos de pi-ai
25buildAuthDoctorHintSugerencia de reparación añadida cuando falla la actualización OAuthEl proveedor necesita orientación de reparación de autenticación propiedad del proveedor después de un fallo de actualización
26matchesContextOverflowErrorCoincidencia de desbordamiento de ventana de contexto propiedad del proveedorEl proveedor tiene errores de desbordamiento sin procesar que las heurísticas genéricas pasarían por alto
27classifyFailoverReasonClasificación de razones de conmutación por error propiedad del proveedorEl proveedor puede asignar errores sin procesar de API/transporte a límite de tasa/sobrecarga/etc.
28isCacheTtlEligiblePolítica de caché de prompts para proveedores proxy/backhaulEl proveedor necesita control de TTL de caché específico de proxy
29buildMissingAuthMessageReemplazo del mensaje genérico de recuperación por autenticación faltanteEl proveedor necesita una sugerencia de recuperación por autenticación faltante específica del proveedor
30augmentModelCatalogFilas de catálogo sintéticas/finales añadidas después del descubrimientoEl proveedor necesita filas sintéticas de compatibilidad futura en models list y selectores
31resolveThinkingProfileConjunto de niveles /think específicos del modelo, etiquetas de visualización y valor predeterminadoEl proveedor expone una escala de pensamiento personalizada o una etiqueta binaria para modelos seleccionados
32isBinaryThinkingHook de compatibilidad del interruptor de razonamiento activado/desactivadoEl proveedor expone solo pensamiento binario activado/desactivado
33supportsXHighThinkingHook de compatibilidad de razonamiento xhighEl proveedor quiere xhigh solo en un subconjunto de modelos
34resolveDefaultThinkingLevelHook de compatibilidad del nivel /think predeterminadoEl proveedor es propietario de la política /think predeterminada para una familia de modelos
35isModernModelRefCoincidencia de modelo moderno para filtros de perfiles en vivo y selección de smokeEl proveedor es propietario de la coincidencia de modelos preferidos para vivo/smoke
36prepareRuntimeAuthIntercambia una credencial configurada por el token/clave de tiempo de ejecución real justo antes de la inferenciaEl proveedor necesita un intercambio de tokens o una credencial de solicitud de corta duración
37resolveUsageAuthResolver las credenciales de uso/facturación para /usage y superficies de estado relacionadasEl proveedor necesita análisis personalizado de tokens de uso/cuota o una credencial de uso diferente
38fetchUsageSnapshotObtener y normalizar snapshots de uso/cuota específicos del proveedor después de resolver la autenticaciónEl proveedor necesita un endpoint de uso específico del proveedor o un analizador de payload
39createEmbeddingProviderCrear un adaptador de embeddings propiedad del proveedor para memoria/búsquedaEl comportamiento de embeddings de memoria pertenece al Plugin del proveedor
40buildReplayPolicyDevolver una política de reproducción que controle el manejo de transcripciones para el proveedorEl proveedor necesita una política de transcripción personalizada (por ejemplo, eliminación de bloques de razonamiento)
41sanitizeReplayHistoryReescribir el historial de reproducción después de la limpieza genérica de transcripcionesEl proveedor necesita reescrituras de reproducción específicas del proveedor más allá de los ayudantes de compaction compartidos
42validateReplayTurnsValidación final de turnos de reproducción o reformateo antes del runner integradoEl transporte del proveedor necesita una validación de turnos más estricta después del saneamiento genérico
43onModelSelectedEjecutar efectos secundarios posteriores a la selección propiedad del proveedorEl proveedor necesita telemetría o estado propiedad del proveedor cuando un modelo se vuelve activo
normalizeModelId, normalizeTransport y normalizeConfig comprueban primero el plugin de proveedor coincidente y luego pasan a otros plugins de proveedor con hooks hasta que uno cambia realmente el id de modelo o el transporte/configuración. Eso mantiene funcionando los shims de proveedor de alias/compatibilidad sin exigir que el llamador sepa qué plugin incluido es dueño de la reescritura. Si ningún hook de proveedor reescribe una entrada de configuración compatible de la familia Google, el normalizador de configuración de Google incluido sigue aplicando esa limpieza de compatibilidad. Si el proveedor necesita un protocolo de cable totalmente personalizado o un ejecutor de solicitudes personalizado, eso es una clase distinta de extensión. Estos hooks son para comportamiento de proveedor que todavía se ejecuta en el bucle de inferencia normal de OpenClaw.

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

Los plugins de proveedor incluidos combinan los hooks anteriores para adaptarse al catálogo, la autenticación, el razonamiento, la reproducción y las necesidades de uso de cada proveedor. El conjunto de hooks autoritativo reside con cada plugin bajo extensions/; esta página ilustra las formas en lugar de reflejar la lista.
OpenRouter, Kilocode, Z.AI y xAI registran catalog junto con resolveDynamicModel / prepareDynamicModel para poder exponer ids de modelos upstream antes del catálogo estático de OpenClaw.
GitHub Copilot, Gemini CLI, ChatGPT Codex, MiniMax, Xiaomi, z.ai emparejan prepareRuntimeAuth o formatApiKey con resolveUsageAuth + fetchUsageSnapshot para hacerse cargo del intercambio de tokens y la integración con /usage.
Las familias compartidas con nombre (google-gemini, passthrough-gemini, anthropic-by-model, hybrid-anthropic-openai) permiten que los proveedores adopten la política de transcripción mediante buildReplayPolicy en lugar de que cada plugin vuelva a implementar la limpieza.
byteplus, cloudflare-ai-gateway, huggingface, kimi-coding, nvidia, qianfan, synthetic, together, venice, vercel-ai-gateway y volcengine registran solo catalog y usan el bucle de inferencia compartido.
Los encabezados beta, /fast / serviceTier y context1m viven dentro de la interfaz pública api.ts / contract-api.ts del plugin de Anthropic (wrapAnthropicProviderStream, resolveAnthropicBetas, resolveAnthropicFastMode, resolveAnthropicServiceTier) en lugar de en el SDK genérico.

Ayudantes de tiempo de ejecución

Los plugins pueden acceder a ayudantes centrales seleccionados mediante api.runtime. Para TTS:
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,
});
Notas:
  • textToSpeech devuelve la carga útil de salida TTS normal del núcleo para superficies de archivo/nota de voz.
  • Usa la configuración central messages.tts y la selección de proveedor.
  • Devuelve búfer de audio PCM + frecuencia de muestreo. Los plugins 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 configuración regional, género y etiquetas de personalidad para selectores conscientes del proveedor.
  • OpenAI y ElevenLabs admiten telefonía actualmente. Microsoft no.
Los plugins también pueden registrar proveedores de voz mediante api.registerSpeechProvider(...).
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,
    };
  },
});
Notas:
  • Mantén la política de TTS, el fallback y la entrega de respuestas en el núcleo.
  • Usa proveedores de voz para comportamiento de síntesis propiedad del proveedor.
  • La entrada heredada edge de Microsoft se normaliza al id de proveedor microsoft.
  • El modelo de propiedad preferido está orientado a la empresa: un plugin de proveedor puede ser dueño de proveedores de texto, voz, imagen y medios futuros a medida que OpenClaw agrega esos contratos de capacidad.
Para comprensión de imagen/audio/video, los plugins registran un proveedor tipado de comprensión de medios en lugar de una bolsa genérica de clave/valor:
api.registerMediaUnderstandingProvider({
  id: "google",
  capabilities: ["image", "audio", "video"],
  describeImage: async (req) => ({ text: "..." }),
  transcribeAudio: async (req) => ({ text: "..." }),
  describeVideo: async (req) => ({ text: "..." }),
});
Notas:
  • Mantén la orquestación, el fallback, la configuración y el cableado de canales en el núcleo.
  • Mantén el comportamiento de proveedor en el plugin de proveedor.
  • La expansión aditiva debe seguir tipada: nuevos métodos opcionales, nuevos campos de resultado opcionales, nuevas capacidades opcionales.
  • La generación de video ya sigue el mismo patrón:
    • el núcleo posee el contrato de capacidad y el ayudante de tiempo de ejecución
    • los plugins de proveedor registran api.registerVideoGenerationProvider(...)
    • los plugins de característica/canal consumen api.runtime.videoGeneration.*
Para los ayudantes de tiempo de ejecución de comprensión de medios, los plugins pueden llamar:
const image = await api.runtime.mediaUnderstanding.describeImageFile({
  filePath: "/tmp/inbound-photo.jpg",
  cfg: api.config,
  agentDir: "/tmp/agent",
});

const video = await api.runtime.mediaUnderstanding.describeVideoFile({
  filePath: "/tmp/inbound-video.mp4",
  cfg: api.config,
});

const extraction = await api.runtime.mediaUnderstanding.extractStructuredWithModel({
  provider: "codex",
  model: "gpt-5.5",
  input: [
    {
      type: "image",
      buffer: receiptImageBuffer,
      fileName: "receipt.png",
      mime: "image/png",
    },
    { type: "text", text: "Use the printed fields as the source of truth." },
  ],
  instructions: "Return entities and searchable tags.",
  schemaName: "example.evidence",
  jsonSchema: {
    type: "object",
    properties: {
      entities: { type: "array", items: { type: "string" } },
      tags: { type: "array", items: { type: "string" } },
    },
  },
  cfg: api.config,
});
Para transcripción de audio, los plugins pueden usar el tiempo de ejecución de comprensión de medios o el alias STT anterior:
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",
});
Notas:
  • api.runtime.mediaUnderstanding.* es la superficie compartida preferida para comprensión de imagen/audio/video.
  • extractStructuredWithModel(...) es la interfaz orientada a plugins para extracción acotada propiedad del proveedor y centrada primero en imágenes. Incluye al menos una entrada de imagen; las entradas de texto son contexto suplementario. los plugins de producto son dueños de sus rutas y esquemas mientras OpenClaw posee el límite de proveedor/tiempo de ejecución.
  • Usa la configuración de audio de comprensión de medios del núcleo (tools.media.audio) y el orden de fallback de proveedores.
  • Devuelve { text: undefined } cuando no se produce salida de transcripción (por ejemplo, entrada omitida/no compatible).
  • api.runtime.stt.transcribeAudioFile(...) permanece como alias de compatibilidad.
Los plugins también pueden lanzar ejecuciones de subagentes en segundo plano mediante api.runtime.subagent:
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,
});
Notas:
  • provider y model son sobrescrituras opcionales por ejecución, no cambios de sesión persistentes.
  • OpenClaw solo respeta esos campos de sobrescritura para llamadores de confianza.
  • Para ejecuciones de fallback propiedad del plugin, los operadores deben optar por habilitarlas con plugins.entries.<id>.subagent.allowModelOverride: true.
  • Usa plugins.entries.<id>.subagent.allowedModels para restringir plugins de confianza a objetivos canónicos provider/model específicos, o "*" para permitir explícitamente cualquier objetivo.
  • Las ejecuciones de subagente de plugins no confiables siguen funcionando, pero las solicitudes de sobrescritura se rechazan en lugar de hacer fallback silenciosamente.
  • Las sesiones de subagente creadas por plugins se etiquetan con el id del plugin creador. El fallback api.runtime.subagent.deleteSession(...) puede eliminar solo esas sesiones propias; la eliminación arbitraria de sesiones sigue requiriendo una solicitud de Gateway con alcance de administrador.
Para búsqueda web, los plugins pueden consumir el ayudante de tiempo de ejecución compartido en lugar de acceder al cableado de herramientas del agente:
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,
  },
});
Los plugins también pueden registrar proveedores de búsqueda web mediante api.registerWebSearchProvider(...). Notas:
  • Mantén la selección de proveedores, la resolución de credenciales y la semántica de solicitud compartida en el núcleo.
  • Usa proveedores de búsqueda web para transportes de búsqueda específicos de proveedor.
  • api.runtime.webSearch.* es la superficie compartida preferida para plugins de característica/canal que necesitan comportamiento de búsqueda sin depender del wrapper de herramienta 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 de proveedores de generación de imágenes configurada.
  • listProviders(...): lista los proveedores de generación de imágenes disponibles y sus capacidades.

Rutas HTTP del Gateway

Los plugins pueden exponer endpoints HTTP con api.registerHttpRoute(...).
api.registerHttpRoute({
  path: "/acme/webhook",
  auth: "plugin",
  match: "exact",
  handler: async (_req, res) => {
    res.statusCode = 200;
    res.end("ok");
    return true;
  },
});
Campos de ruta:
  • path: ruta bajo el servidor HTTP del Gateway.
  • auth: requerido. 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 sustituya su propio registro de ruta existente.
  • handler: devuelve true cuando la ruta gestionó la solicitud.
Notas:
  • 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 solapadas con distintos niveles de auth se rechazan. Mantén las cadenas de continuación exact/prefix solo en el mismo nivel de autenticación.
  • Las rutas auth: "plugin" no reciben automáticamente ámbitos de runtime del operador. Están destinadas a webhooks/verificación de firmas gestionados por el plugin, no a llamadas privilegiadas de ayuda del Gateway.
  • Las rutas auth: "gateway" se ejecutan dentro de un ámbito de runtime de solicitud del Gateway, pero ese ámbito es intencionadamente conservador:
    • la autenticación bearer con secreto compartido (gateway.auth.mode = "token" / "password") mantiene los ámbitos de runtime de rutas de plugin fijados a operator.write, incluso si el llamador envía x-openclaw-scopes
    • los modos HTTP confiables que transportan 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 rutas de plugin que transportan identidad, el ámbito de runtime vuelve a operator.write
  • Regla práctica: no asumas que una ruta de plugin con autenticación de gateway es una superficie de administración implícita. Si tu ruta necesita comportamiento exclusivo de administrador, exige un modo de autenticación que transporte identidad y documenta el contrato explícito del encabezado x-openclaw-scopes.

Rutas de importación del SDK de Plugin

Usa subrutas estrechas del SDK en lugar del barrel raíz monolítico openclaw/plugin-sdk al crear plugins nuevos. Subrutas principales:
SubrutaPropósito
openclaw/plugin-sdk/plugin-entryPrimitivas de registro de Plugin
openclaw/plugin-sdk/channel-coreAyudantes de entrada/compilación de canal
openclaw/plugin-sdk/coreAyudantes compartidos genéricos y contrato paraguas
openclaw/plugin-sdk/config-schemaEsquema Zod raíz de openclaw.json (OpenClawSchema)
Los plugins de canal eligen entre una familia de puntos de integración estrechos: channel-setup, setup-runtime, setup-tools, channel-pairing, channel-contract, channel-feedback, channel-inbound, channel-lifecycle, channel-reply-pipeline, command-auth, secret-input, webhook-ingress, channel-targets y channel-actions. El comportamiento de aprobación debe consolidarse en un único contrato approvalCapability en lugar de mezclarse entre campos de plugin no relacionados. Consulta Plugins de canal. Los ayudantes de runtime y configuración viven bajo subrutas enfocadas *-runtime correspondientes (approval-runtime, agent-runtime, lazy-runtime, directory-runtime, text-runtime, runtime-store, system-event-runtime, heartbeat-runtime, channel-activity-runtime, etc.). Prefiere config-contracts, plugin-config-runtime, runtime-config-snapshot y config-mutation en lugar del barrel amplio de compatibilidad config-runtime.
openclaw/plugin-sdk/channel-runtime, openclaw/plugin-sdk/config-runtime y openclaw/plugin-sdk/infra-runtime son shims de compatibilidad obsoletos para plugins antiguos. El código nuevo debe importar primitivas genéricas más estrechas.
Puntos de entrada internos del repositorio (por raíz de paquete de plugin incluido):
  • index.js — entrada de plugin incluido
  • api.js — barrel de ayudantes/tipos
  • runtime-api.js — barrel solo de runtime
  • setup-entry.js — entrada de plugin de configuración
Los plugins externos solo deben importar subrutas openclaw/plugin-sdk/*. Nunca importes el src/* de otro paquete de plugin desde el núcleo ni desde otro plugin. Los puntos de entrada cargados por fachada prefieren la instantánea activa de configuración de runtime cuando existe una, y luego recurren al archivo de configuración resuelto en disco. Existen subrutas específicas de capacidad como image-generation, media-understanding y speech porque los plugins incluidos las usan hoy. No son contratos externos congelados automáticamente a largo plazo: consulta la página de referencia del SDK correspondiente cuando dependas de ellas.

Esquemas de herramientas de mensajes

Los plugins deben poseer contribuciones de esquema describeMessageTool(...) específicas del canal para primitivas que no sean mensajes, como reacciones, lecturas y encuestas. La presentación compartida de envío debe usar el contrato genérico MessagePresentation en lugar de campos nativos del proveedor para botones, componentes, bloques o tarjetas. Consulta Presentación de mensajes para el contrato, las reglas de fallback, el mapeo de proveedores y la lista de verificación para autores de plugins. Los plugins con capacidad de envío declaran qué pueden renderizar mediante capacidades de mensaje:
  • presentation para bloques de presentación semántica (text, context, divider, buttons, select)
  • delivery-pin para solicitudes de entrega fijada
El núcleo decide si renderiza la presentación de forma nativa o la degrada a texto. No expongas vías de escape de IU nativas del proveedor desde la herramienta genérica de mensajes. Los ayudantes obsoletos del SDK para esquemas nativos heredados siguen exportándose para plugins de terceros existentes, pero los plugins nuevos no deben usarlos.

Resolución de destinos de canal

Los plugins de canal deben poseer la semántica de destino específica del canal. Mantén genérico el host de salida compartido y usa la superficie del adaptador de mensajería para reglas del proveedor:
  • messaging.inferTargetChatType({ to }) decide si un destino 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 saltar directamente a una resolución similar a id en lugar de buscar en el directorio.
  • messaging.targetResolver.resolveTarget(...) es el fallback del plugin cuando el núcleo necesita una resolución final propiedad del proveedor después de la normalización o tras un fallo en el directorio.
  • messaging.resolveOutboundSessionRoute(...) posee la construcción de rutas de sesión específica del proveedor una vez resuelto un destino.
División recomendada:
  • 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 destino explícito/nativo”.
  • Usa resolveTarget para el fallback de normalización específico del proveedor, no para búsquedas amplias en el directorio.
  • Mantén ids nativos del proveedor como ids de chat, ids de hilo, JID, identificadores y ids 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

Los plugins que derivan entradas de directorio desde la configuración deben mantener esa lógica en el plugin y reutilizar los ayudantes compartidos de openclaw/plugin-sdk/directory-runtime. Usa esto cuando un canal necesite pares/grupos respaldados por configuración, como:
  • pares de DM impulsados por allowlist
  • mapas de canal/grupo configurados
  • fallbacks de directorio estático con ámbito de cuenta
Los ayudantes compartidos en directory-runtime solo gestionan operaciones genéricas:
  • filtrado de consultas
  • aplicación de límites
  • ayudantes de desduplicación/normalización
  • creación de ChannelDirectoryEntry[]
La inspección de cuentas específica del canal y la normalización de ids deben permanecer en la implementación del plugin.

Catálogos de proveedores

Los plugins de proveedor pueden definir catálogos de modelos para inferencia con registerProvider({ catalog: { run(...) { ... } } }). catalog.run(...) devuelve la misma forma que OpenClaw escribe en models.providers:
  • { provider } para una entrada de proveedor
  • { providers } para varias entradas de proveedor
Usa catalog cuando el plugin posea ids de modelo específicos del proveedor, valores predeterminados de URL base o metadatos de modelo restringidos por autenticación. catalog.order controla cuándo se fusiona el catálogo de un plugin respecto a los proveedores implícitos integrados de OpenClaw:
  • simple: proveedores simples impulsados por clave de API o 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 otros proveedores implícitos
Los proveedores posteriores ganan en colisiones de clave, por lo que los plugins pueden sobrescribir intencionadamente una entrada de proveedor integrada con el mismo id de proveedor. Los plugins también pueden publicar filas de modelo de solo lectura mediante api.registerModelCatalogProvider({ provider, kinds, staticCatalog, liveCatalog }). Esta es la ruta futura para superficies de lista/ayuda/selector y admite filas text, image_generation, video_generation y music_generation. Los plugins de proveedor siguen siendo propietarios de las llamadas a endpoints en vivo, el intercambio de tokens y el mapeo de respuestas del proveedor; el núcleo posee la forma de fila común, las etiquetas de origen y el formato de ayuda de herramientas multimedia. Los registros de proveedores de generación multimedia sintetizan filas de catálogo estático automáticamente desde defaultModel, models y capabilities. Compatibilidad:
  • discovery sigue funcionando como alias heredado, pero emite una advertencia de obsolescencia
  • si se registran catalog y discovery, OpenClaw usa catalog
  • augmentModelCatalog está obsoleto; los proveedores incluidos deben publicar filas suplementarias mediante registerModelCatalogProvider

Inspección de canal de solo lectura

Si tu plugin registra un canal, prefiere implementar plugin.config.inspectAccount(cfg, accountId) junto con resolveAccount(...). Motivo:
  • resolveAccount(...) es la ruta de runtime. Puede asumir que las credenciales están materializadas por completo y fallar rápido 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 reparación de doctor/config no deberían necesitar materializar credenciales de runtime solo para describir la configuración.
Comportamiento recomendado de inspectAccount(...):
  • Devuelve solo estado descriptivo de la cuenta.
  • Preserva enabled y configured.
  • Incluye campos de origen/estado de credenciales cuando corresponda, como:
    • tokenSource, tokenStatus
    • botTokenSource, botTokenStatus
    • appTokenSource, appTokenStatus
    • signingSecretSource, signingSecretStatus
  • No necesitas devolver valores de token sin procesar solo para informar disponibilidad de solo lectura. Devolver tokenStatus: "available" (y el campo de origen correspondiente) es suficiente para comandos de estilo estado.
  • Usa configured_unavailable cuando una credencial esté configurada mediante SecretRef pero no esté disponible en la ruta de comando actual.
Esto permite que los comandos de solo lectura informen “configurado pero no disponible en esta ruta de comando” en lugar de bloquearse o informar incorrectamente que la cuenta no está configurada.

Paquetes de paquetes

Un directorio de plugin puede incluir un package.json con openclaw.extensions:
{
  "name": "my-pack",
  "openclaw": {
    "extensions": ["./src/safety.ts", "./src/tools.ts"],
    "setupEntry": "./src/setup-entry.ts"
  }
}
Cada entrada se convierte en un plugin. Si el paquete enumera varias extensions, el id del plugin se convierte en name/<fileBase>. Si tu plugin importa dependencias npm, instálalas en ese directorio para que node_modules esté disponible (npm install / pnpm install). Medida de seguridad: toda entrada openclaw.extensions debe permanecer dentro del directorio del plugin después de la resolución de symlinks. Las entradas que escapan del directorio del paquete se rechazan. Nota de seguridad: openclaw plugins install instala dependencias de plugins con un npm install --omit=dev --ignore-scripts local al proyecto (sin scripts de ciclo de vida, sin dependencias de desarrollo en runtime), ignorando la configuración global heredada de instalación de npm. Mantén los árboles de dependencias de plugins como “JS/TS puro” y evita paquetes que requieran compilaciones postinstall. Opcional: openclaw.setupEntry puede apuntar a un módulo ligero solo de configuración. Cuando OpenClaw necesita superficies de configuración para un plugin de canal deshabilitado, o cuando un plugin de canal está habilitado pero aún sin configurar, carga setupEntry en lugar de la entrada completa del plugin. Esto hace que el arranque y la configuración sean más ligeros cuando la entrada principal de tu plugin también conecta herramientas, hooks u otro código solo de runtime. Opcional: openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen puede inscribir a un plugin de canal en la misma ruta setupEntry durante la fase de arranque previa a la escucha del gateway, incluso cuando el canal ya está configurado. Use esto solo cuando setupEntry cubra por completo la superficie de inicio que debe existir antes de que el Gateway empiece a escuchar. En la práctica, eso significa que la entrada de configuración debe registrar todas las capacidades propiedad del canal de las que depende el inicio, como:
  • el registro del canal en sí
  • 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
Si tu entrada completa todavía posee alguna capacidad de inicio requerida, no habilites esta bandera. Mantén el Plugin con el comportamiento predeterminado y deja que OpenClaw cargue la entrada completa durante el inicio. Los canales incluidos también pueden publicar ayudantes de superficie de contrato solo de configuración que el núcleo puede consultar antes de que se cargue el runtime completo del canal. La superficie actual de promoción de configuración es:
  • singleAccountKeysToMove
  • namedAccountPromotionKeys
  • resolveSingleAccountPromotionTarget(...)
El núcleo usa esa superficie cuando necesita promover una configuración heredada de canal de cuenta única a channels.<id>.accounts.* sin cargar la entrada completa del Plugin. Matrix es el ejemplo incluido actual: mueve solo claves de autenticación/arranque a una cuenta promovida con nombre cuando ya existen cuentas con nombre, y puede conservar una clave de cuenta predeterminada no canónica configurada en lugar de crear siempre accounts.default. Esos adaptadores de parches de configuración mantienen diferido el descubrimiento de la superficie de contrato incluida. El tiempo de importación sigue siendo ligero; la superficie de promoción se carga solo en el primer uso en lugar de volver a entrar en el inicio del canal incluido al importar el módulo. Cuando esas superficies de inicio incluyan métodos RPC del Gateway, mantenlos en un prefijo específico del Plugin. Los espacios de nombres de administración del núcleo (config.*, exec.approvals.*, wizard.*, update.*) permanecen reservados y siempre se resuelven como operator.admin, incluso si un Plugin solicita un alcance más restringido. Ejemplo:
{
  "name": "@scope/my-channel",
  "openclaw": {
    "extensions": ["./index.ts"],
    "setupEntry": "./setup-entry.ts",
    "startup": {
      "deferConfiguredChannelFullLoadUntilAfterListen": true
    }
  }
}

Metadatos del catálogo de canales

Los Plugins de canal pueden anunciar metadatos de configuración/descubrimiento mediante openclaw.channel y pistas de instalación mediante openclaw.install. Esto mantiene el catálogo del núcleo sin datos. Ejemplo:
{
  "name": "@openclaw/nextcloud-talk",
  "openclaw": {
    "extensions": ["./index.ts"],
    "channel": {
      "id": "nextcloud-talk",
      "label": "Nextcloud Talk",
      "selectionLabel": "Nextcloud Talk (self-hosted)",
      "docsPath": "/channels/nextcloud-talk",
      "docsLabel": "nextcloud-talk",
      "blurb": "Self-hosted chat via Nextcloud Talk webhook bots.",
      "order": 65,
      "aliases": ["nc-talk", "nc"]
    },
    "install": {
      "npmSpec": "@openclaw/nextcloud-talk",
      "localPath": "<bundled-plugin-local-path>",
      "defaultChoice": "npm"
    }
  }
}
Campos útiles de openclaw.channel más allá del ejemplo mínimo:
  • detailLabel: etiqueta secundaria para superficies de catálogo/estado más completas
  • docsLabel: sobrescribe el texto del enlace de documentación
  • preferOver: ids de Plugin/canal de menor prioridad que esta entrada de 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 decisiones de formato de salida
  • 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 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 todavía se aceptan por compatibilidad; prefiere exposure
  • quickstartAllowFrom: incluye el canal en el flujo estándar de inicio rápido allowFrom
  • forceAccountBinding: exige vinculación explícita de cuenta incluso cuando solo existe una cuenta
  • preferSessionLookupForAnnounceTarget: prefiere la búsqueda de sesión al resolver destinos de anuncio
OpenClaw también puede fusionar catálogos de canales externos (por ejemplo, una exportación de registro MPM). Coloca un archivo JSON en una de estas rutas:
  • ~/.openclaw/mpm/plugins.json
  • ~/.openclaw/mpm/catalog.json
  • ~/.openclaw/plugins/catalog.json
O apunta OPENCLAW_PLUGIN_CATALOG_PATHS (o OPENCLAW_MPM_CATALOG_PATHS) a uno o más archivos JSON (delimitados por coma/punto y coma/PATH). Cada archivo debe contener { "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }. El analizador también acepta "packages" o "plugins" como alias heredados de la clave "entries". Las entradas generadas del catálogo de canales y las entradas del catálogo de instalación de proveedores exponen hechos normalizados de origen de instalación junto al bloque bruto openclaw.install. Los hechos normalizados identifican si la especificación npm es una versión exacta o un selector flotante, si están presentes los metadatos de integridad esperados y si también hay disponible una ruta de origen local. Cuando se conoce la identidad de catálogo/paquete, los hechos normalizados advierten si el nombre del paquete npm analizado se desvía de esa identidad. También advierten cuando defaultChoice no es válido o apunta a un origen que no está disponible, y cuando hay metadatos de integridad npm sin un origen npm válido. Los consumidores deben tratar installSource como un campo opcional aditivo para que las entradas creadas manualmente y los adaptadores de catálogo no tengan que sintetizarlo. Esto permite que la incorporación y los diagnósticos expliquen el estado del plano de origen sin importar el runtime del Plugin. Las entradas npm externas oficiales deben preferir un npmSpec exacto más expectedIntegrity. Los nombres de paquete simples y las etiquetas de distribución siguen funcionando por compatibilidad, pero muestran advertencias del plano de origen para que el catálogo pueda avanzar hacia instalaciones fijadas y verificadas por integridad sin romper Plugins existentes. Cuando la incorporación instala desde una ruta de catálogo local, registra una entrada de índice de Plugin gestionado con source: "path" y un sourcePath relativo al espacio de trabajo cuando sea posible. La ruta absoluta de carga operacional permanece en plugins.load.paths; el registro de instalación evita duplicar rutas de estaciones de trabajo locales en la configuración duradera. Esto mantiene las instalaciones de desarrollo local visibles para los diagnósticos del plano de origen sin añadir una segunda superficie bruta de divulgación de rutas del sistema de archivos. El índice persistido de Plugins plugins/installs.json es la fuente de verdad de instalación y puede actualizarse sin cargar módulos de runtime del Plugin. Su mapa installRecords es duradero incluso cuando falta un manifiesto de Plugin o no es válido; su matriz plugins es una vista de manifiesto reconstruible.

Plugins de motor de contexto

Los Plugins de motor de contexto poseen la orquestación del contexto de sesión para ingesta, ensamblaje y Compaction. Regístralos desde tu Plugin con api.registerContextEngine(id, factory), luego selecciona el motor activo con plugins.slots.contextEngine. Usa esto cuando tu Plugin necesite reemplazar o ampliar la canalización de contexto predeterminada en lugar de solo añadir búsqueda de memoria o hooks.
import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core";

export default function (api) {
  api.registerContextEngine("lossless-claw", (ctx) => ({
    info: { id: "lossless-claw", name: "Lossless Claw", ownsCompaction: true },
    async ingest() {
      return { ingested: true };
    },
    async assemble({ messages, availableTools, citationsMode }) {
      return {
        messages,
        estimatedTokens: 0,
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
        }),
      };
    },
    async compact() {
      return { ok: true, compacted: false };
    },
  }));
}
La fábrica ctx expone valores opcionales config, agentDir y workspaceDir para la inicialización en tiempo de construcción. Si tu motor no posee el algoritmo de Compaction, mantén compact() implementado y delégalo explícitamente:
import {
  buildMemorySystemPromptAddition,
  delegateCompactionToRuntime,
} from "openclaw/plugin-sdk/core";

export default function (api) {
  api.registerContextEngine("my-memory-engine", (ctx) => ({
    info: {
      id: "my-memory-engine",
      name: "My Memory Engine",
      ownsCompaction: false,
    },
    async ingest() {
      return { ingested: true };
    },
    async assemble({ messages, availableTools, citationsMode }) {
      return {
        messages,
        estimatedTokens: 0,
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
        }),
      };
    },
    async compact(params) {
      return await delegateCompactionToRuntime(params);
    },
  }));
}

Añadir una nueva capacidad

Cuando un Plugin necesite comportamiento que no encaje en la API actual, no eludas el sistema de Plugins con un acceso privado. Añade la capacidad que falta. Secuencia recomendada:
  1. define el contrato del núcleo Decide qué comportamiento compartido debe poseer el núcleo: política, fallback, fusión de configuración, ciclo de vida, semántica de cara al canal y forma del ayudante de runtime.
  2. añade superficies tipadas de registro/runtime de Plugin Extiende OpenClawPluginApi y/o api.runtime con la superficie de capacidad tipada útil más pequeña.
  3. conecta el núcleo + consumidores de canal/funcionalidad Los canales y Plugins de funcionalidad deben consumir la nueva capacidad a través del núcleo, no importando directamente una implementación de proveedor.
  4. registra implementaciones de proveedores Los Plugins de proveedor registran entonces sus backends contra la capacidad.
  5. añade cobertura de contrato Añade pruebas para que la propiedad y la forma de registro sigan siendo explícitas con el tiempo.
Así es como OpenClaw se mantiene con criterio sin quedar codificado rígidamente según la visión de un solo proveedor. Consulta el Recetario de capacidades para ver una lista de comprobación concreta de archivos y un ejemplo desarrollado.

Lista de comprobación de capacidades

Cuando añadas una nueva capacidad, la implementación normalmente debería tocar estas superficies juntas:
  • tipos de contrato del núcleo en src/<capability>/types.ts
  • ejecutor/ayudante de runtime del núcleo en src/<capability>/runtime.ts
  • superficie de registro de la API del Plugin en src/plugins/types.ts
  • cableado del registro de Plugins en src/plugins/registry.ts
  • exposición del runtime del Plugin en src/plugins/runtime/* cuando los Plugins de funcionalidad/canal necesiten consumirlo
  • ayudantes de captura/prueba en src/test-utils/plugin-registration.ts
  • aserciones de propiedad/contrato en src/plugins/contracts/registry.ts
  • documentación de operador/Plugin en docs/
Si falta una de esas superficies, normalmente es señal de que la capacidad todavía no está completamente integrada.

Plantilla de capacidad

Patrón mínimo:
// 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,
});
Patrón de prueba de contrato:
expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]);
Eso mantiene la regla simple:
  • el núcleo posee el contrato de capacidad + la orquestación
  • los Plugins de proveedor poseen las implementaciones de proveedor
  • los Plugins de funcionalidad/canal consumen ayudantes de runtime
  • las pruebas de contrato mantienen explícita la propiedad

Relacionado