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.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.
Canalización de carga
Al iniciar, OpenClaw hace aproximadamente esto:- descubre raíces candidatas de Plugin
- lee manifiestos de bundles nativos o compatibles y metadatos del paquete
- rechaza candidatos no seguros
- normaliza la configuración de Plugin (
plugins.enabled,allow,deny,entries,slots,load.paths) - decide la habilitación de cada candidato
- 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
- llama a los hooks nativos
register(api)y recopila los registros en el registro de Plugin - 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.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
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.onStartuppara 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
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 elPluginMetadataSnapshot 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:
PluginLoaderCacheStatey 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
- 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
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
- módulo de Plugin -> registro en el registro
- runtime del core -> consumo del registro
Callbacks de vinculación de conversación
Los plugins que vinculan una conversación pueden reaccionar cuando se resuelve una aprobación. Usaapi.onConversationBindingResolved(...) para recibir un callback después de que una solicitud de vinculación
sea aprobada o denegada:
status:"approved"o"denied"decision:"allow-once","allow-always"o"deny"binding: la vinculación resuelta para solicitudes aprobadasrequest: el resumen de la solicitud original, indicio de desvinculación, id del remitente y metadatos de conversación
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 obsoletaproviderAuthEnvVars,providerAuthAliases,providerAuthChoicesychannelEnvVars. - Hooks en tiempo de configuración:
catalog(discoveryheredado) másapplyConfigDefaults. - 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.
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, comoProviderPlugin.capabilities y suppressBuiltInModel, no se enumeran
intencionalmente aquí.
| # | Hook | Qué hace | Cuándo usarlo |
|---|---|---|---|
| 1 | catalog | Publica la configuración del proveedor en models.providers durante la generación de models.json | El proveedor es propietario de un catálogo o de valores predeterminados de URL base |
| 2 | applyConfigDefaults | Aplica los valores predeterminados de configuración global propiedad del proveedor durante la materialización de la configuración | Los 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) |
| 3 | normalizeModelId | Normaliza alias de ids de modelo heredados o de vista previa antes de la búsqueda | El proveedor es propietario de la limpieza de alias antes de la resolución canónica del modelo |
| 4 | normalizeTransport | Normaliza api / baseUrl de la familia del proveedor antes del ensamblado genérico del modelo | El proveedor es propietario de la limpieza de transporte para ids de proveedor personalizados en la misma familia de transporte |
| 5 | normalizeConfig | Normaliza models.providers.<id> antes de la resolución de tiempo de ejecución/proveedor | El 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 |
| 6 | applyNativeStreamingUsageCompat | Aplica reescrituras de compatibilidad de uso de streaming nativo a los proveedores de configuración | El proveedor necesita correcciones de metadatos de uso de streaming nativo controladas por el endpoint |
| 7 | resolveConfigApiKey | Resuelve la autenticación con marcador de entorno para proveedores de configuración antes de cargar la autenticación de tiempo de ejecución | El 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 |
| 8 | resolveSyntheticAuth | Expone autenticación local/autohospedada o respaldada por configuración sin persistir texto plano | El proveedor puede operar con un marcador de credencial sintético/local |
| 9 | resolveExternalAuthProfiles | Superpone perfiles de autenticación externa propiedad del proveedor; el valor predeterminado de persistence es runtime-only para credenciales propiedad de CLI/aplicación | El proveedor reutiliza credenciales de autenticación externa sin persistir tokens de actualización copiados; declara contracts.externalAuthProviders en el manifiesto |
| 10 | shouldDeferSyntheticProfileAuth | Reduce la precedencia de los marcadores de posición de perfiles sintéticos almacenados frente a autenticación respaldada por entorno/configuración | El proveedor almacena perfiles de marcador de posición sintéticos que no deberían ganar precedencia |
| 11 | resolveDynamicModel | Sincroniza una alternativa para ids de modelo propiedad del proveedor que aún no están en el registro local | El proveedor acepta ids de modelo ascendentes arbitrarios |
| 12 | prepareDynamicModel | Calentamiento asíncrono, luego resolveDynamicModel se ejecuta de nuevo | El proveedor necesita metadatos de red antes de resolver ids desconocidos |
| 13 | normalizeResolvedModel | Reescritura final antes de que el ejecutor integrado use el modelo resuelto | El proveedor necesita reescrituras de transporte, pero sigue usando un transporte del núcleo |
| 14 | contributeResolvedModelCompat | Aporta marcas de compatibilidad para modelos de proveedor detrás de otro transporte compatible | El proveedor reconoce sus propios modelos en transportes proxy sin tomar el control del proveedor |
| 15 | normalizeToolSchemas | Normaliza esquemas de herramientas antes de que el ejecutor integrado los vea | El proveedor necesita limpieza de esquemas de la familia de transporte |
| 16 | inspectToolSchemas | Expone diagnósticos de esquemas propiedad del proveedor después de la normalización | El proveedor quiere advertencias de palabras clave sin enseñar al núcleo reglas específicas del proveedor |
| 17 | resolveReasoningOutputMode | Selecciona el contrato de salida de razonamiento nativo frente al etiquetado | El proveedor necesita razonamiento/salida final etiquetados en lugar de campos nativos |
| 18 | prepareExtraParams | Normalización de parámetros de solicitud antes de los contenedores genéricos de opciones de streaming | El proveedor necesita parámetros de solicitud predeterminados o limpieza de parámetros por proveedor |
| 19 | createStreamFn | Reemplaza por completo la ruta de streaming normal con un transporte personalizado | El proveedor necesita un protocolo de cable personalizado, no solo un contenedor |
| 20 | wrapStreamFn | Contenedor de streaming después de aplicar los contenedores genéricos | El proveedor necesita contenedores de compatibilidad de encabezados/cuerpo/modelo de solicitud sin un transporte personalizado |
| 21 | resolveTransportTurnState | Adjunta encabezados o metadatos de transporte nativos por turno | El proveedor quiere que los transportes genéricos envíen identidad de turno nativa del proveedor |
| 22 | resolveWebSocketSessionPolicy | Adjunta encabezados WebSocket nativos o una política de enfriamiento de sesión | El proveedor quiere que los transportes WS genéricos ajusten encabezados de sesión o la política de alternativa |
| 23 | formatApiKey | Formateador de perfil de autenticación: el perfil almacenado se convierte en la cadena apiKey de tiempo de ejecución | El proveedor almacena metadatos de autenticación adicionales y necesita una forma de token de tiempo de ejecución personalizada |
| 24 | refreshOAuth | Sobrescritura de actualización OAuth para endpoints de actualización personalizados o política de error de actualización | El proveedor no encaja con los actualizadores compartidos de pi-ai |
| 25 | buildAuthDoctorHint | Sugerencia de reparación añadida cuando falla la actualización OAuth | El proveedor necesita orientación de reparación de autenticación propiedad del proveedor después de un fallo de actualización |
| 26 | matchesContextOverflowError | Coincidencia de desbordamiento de ventana de contexto propiedad del proveedor | El proveedor tiene errores de desbordamiento sin procesar que las heurísticas genéricas pasarían por alto |
| 27 | classifyFailoverReason | Clasificación de razones de conmutación por error propiedad del proveedor | El proveedor puede asignar errores sin procesar de API/transporte a límite de tasa/sobrecarga/etc. |
| 28 | isCacheTtlEligible | Política de caché de prompts para proveedores proxy/backhaul | El proveedor necesita control de TTL de caché específico de proxy |
| 29 | buildMissingAuthMessage | Reemplazo del mensaje genérico de recuperación por autenticación faltante | El proveedor necesita una sugerencia de recuperación por autenticación faltante específica del proveedor |
| 30 | augmentModelCatalog | Filas de catálogo sintéticas/finales añadidas después del descubrimiento | El proveedor necesita filas sintéticas de compatibilidad futura en models list y selectores |
| 31 | resolveThinkingProfile | Conjunto de niveles /think específicos del modelo, etiquetas de visualización y valor predeterminado | El proveedor expone una escala de pensamiento personalizada o una etiqueta binaria para modelos seleccionados |
| 32 | isBinaryThinking | Hook de compatibilidad del interruptor de razonamiento activado/desactivado | El proveedor expone solo pensamiento binario activado/desactivado |
| 33 | supportsXHighThinking | Hook de compatibilidad de razonamiento xhigh | El proveedor quiere xhigh solo en un subconjunto de modelos |
| 34 | resolveDefaultThinkingLevel | Hook de compatibilidad del nivel /think predeterminado | El proveedor es propietario de la política /think predeterminada para una familia de modelos |
| 35 | isModernModelRef | Coincidencia de modelo moderno para filtros de perfiles en vivo y selección de smoke | El proveedor es propietario de la coincidencia de modelos preferidos para vivo/smoke |
| 36 | prepareRuntimeAuth | Intercambia una credencial configurada por el token/clave de tiempo de ejecución real justo antes de la inferencia | El proveedor necesita un intercambio de tokens o una credencial de solicitud de corta duración |
| 37 | resolveUsageAuth | Resolver las credenciales de uso/facturación para /usage y superficies de estado relacionadas | El proveedor necesita análisis personalizado de tokens de uso/cuota o una credencial de uso diferente |
| 38 | fetchUsageSnapshot | Obtener y normalizar snapshots de uso/cuota específicos del proveedor después de resolver la autenticación | El proveedor necesita un endpoint de uso específico del proveedor o un analizador de payload |
| 39 | createEmbeddingProvider | Crear un adaptador de embeddings propiedad del proveedor para memoria/búsqueda | El comportamiento de embeddings de memoria pertenece al Plugin del proveedor |
| 40 | buildReplayPolicy | Devolver una política de reproducción que controle el manejo de transcripciones para el proveedor | El proveedor necesita una política de transcripción personalizada (por ejemplo, eliminación de bloques de razonamiento) |
| 41 | sanitizeReplayHistory | Reescribir el historial de reproducción después de la limpieza genérica de transcripciones | El proveedor necesita reescrituras de reproducción específicas del proveedor más allá de los ayudantes de compaction compartidos |
| 42 | validateReplayTurns | Validación final de turnos de reproducción o reformateo antes del runner integrado | El transporte del proveedor necesita una validación de turnos más estricta después del saneamiento genérico |
| 43 | onModelSelected | Ejecutar efectos secundarios posteriores a la selección propiedad del proveedor | El 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
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 bajoextensions/; esta página ilustra las formas en lugar de
reflejar la lista.
Pass-through catalog providers
Pass-through catalog providers
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.OAuth and usage endpoint providers
OAuth and usage endpoint providers
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.Replay and transcript cleanup families
Replay and transcript cleanup families
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.Catalog-only providers
Catalog-only providers
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.Anthropic-specific stream helpers
Anthropic-specific stream helpers
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 medianteapi.runtime. Para TTS:
textToSpeechdevuelve la carga útil de salida TTS normal del núcleo para superficies de archivo/nota de voz.- Usa la configuración central
messages.ttsy la selección de proveedor. - Devuelve búfer de audio PCM + frecuencia de muestreo. Los plugins deben remuestrear/codificar para los proveedores.
listVoiceses 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.
api.registerSpeechProvider(...).
- 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
edgede Microsoft se normaliza al id de proveedormicrosoft. - 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.
- 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.*
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.
api.runtime.subagent:
providerymodelson 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.allowedModelspara restringir plugins de confianza a objetivos canónicosprovider/modelespecí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.
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
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 conapi.registerHttpRoute(...).
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: devuelvetruecuando la ruta gestionó la solicitud.
api.registerHttpHandler(...)se eliminó y provocará un error de carga del plugin. Usaapi.registerHttpRoute(...)en su lugar.- Las rutas de Plugin deben declarar
authexplícitamente. - Los conflictos exactos de
path + matchse rechazan salvo quereplaceExisting: true, y un plugin no puede reemplazar la ruta de otro plugin. - Las rutas solapadas con distintos niveles de
authse rechazan. Mantén las cadenas de continuaciónexact/prefixsolo 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 aoperator.write, incluso si el llamador envíax-openclaw-scopes - los modos HTTP confiables que transportan identidad (por ejemplo
trusted-proxyogateway.auth.mode = "none"en un ingreso privado) respetanx-openclaw-scopessolo cuando el encabezado está presente explícitamente - si
x-openclaw-scopesestá ausente en esas solicitudes de rutas de plugin que transportan identidad, el ámbito de runtime vuelve aoperator.write
- la autenticación bearer con secreto compartido (
- 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íticoopenclaw/plugin-sdk
al crear plugins nuevos. Subrutas principales:
| Subruta | Propósito |
|---|---|
openclaw/plugin-sdk/plugin-entry | Primitivas de registro de Plugin |
openclaw/plugin-sdk/channel-core | Ayudantes de entrada/compilación de canal |
openclaw/plugin-sdk/core | Ayudantes compartidos genéricos y contrato paraguas |
openclaw/plugin-sdk/config-schema | Esquema Zod raíz de openclaw.json (OpenClawSchema) |
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.index.js— entrada de plugin incluidoapi.js— barrel de ayudantes/tiposruntime-api.js— barrel solo de runtimesetup-entry.js— entrada de plugin de configuración
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 esquemadescribeMessageTool(...) 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:
presentationpara bloques de presentación semántica (text,context,divider,buttons,select)delivery-pinpara solicitudes de entrega fijada
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 comodirect,groupochannelantes 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.
- Usa
inferTargetChatTypepara decisiones de categoría que deben ocurrir antes de buscar pares/grupos. - Usa
looksLikeIdpara comprobaciones de “tratar esto como un id de destino explícito/nativo”. - Usa
resolveTargetpara 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
targeto 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 deopenclaw/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
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[]
Catálogos de proveedores
Los plugins de proveedor pueden definir catálogos de modelos para inferencia conregisterProvider({ 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
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 entornoprofile: proveedores que aparecen cuando existen perfiles de autenticaciónpaired: proveedores que sintetizan varias entradas de proveedor relacionadaslate: última pasada, después de otros proveedores implícitos
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:
discoverysigue funcionando como alias heredado, pero emite una advertencia de obsolescencia- si se registran
catalogydiscovery, OpenClaw usacatalog augmentModelCatalogestá obsoleto; los proveedores incluidos deben publicar filas suplementarias medianteregisterModelCatalogProvider
Inspección de canal de solo lectura
Si tu plugin registra un canal, prefiere implementarplugin.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 resolvey los flujos de reparación de doctor/config no deberían necesitar materializar credenciales de runtime solo para describir la configuración.
inspectAccount(...):
- Devuelve solo estado descriptivo de la cuenta.
- Preserva
enabledyconfigured. - Incluye campos de origen/estado de credenciales cuando corresponda, como:
tokenSource,tokenStatusbotTokenSource,botTokenStatusappTokenSource,appTokenStatussigningSecretSource,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_unavailablecuando una credencial esté configurada mediante SecretRef pero no esté disponible en la ruta de comando actual.
Paquetes de paquetes
Un directorio de plugin puede incluir unpackage.json con openclaw.extensions:
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
singleAccountKeysToMovenamedAccountPromotionKeysresolveSingleAccountPromotionTarget(...)
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:
Metadatos del catálogo de canales
Los Plugins de canal pueden anunciar metadatos de configuración/descubrimiento medianteopenclaw.channel y
pistas de instalación mediante openclaw.install. Esto mantiene el catálogo del núcleo sin datos.
Ejemplo:
openclaw.channel más allá del ejemplo mínimo:
detailLabel: etiqueta secundaria para superficies de catálogo/estado más completasdocsLabel: sobrescribe el texto del enlace de documentaciónpreferOver: ids de Plugin/canal de menor prioridad que esta entrada de catálogo debe superarselectionDocsPrefix,selectionDocsOmitLabel,selectionExtras: controles de texto de la superficie de selecciónmarkdownCapable: marca el canal como compatible con markdown para decisiones de formato de salidaexposure.configured: oculta el canal de las superficies de listado de canales configurados cuando se establece enfalseexposure.setup: oculta el canal de los selectores interactivos de configuración cuando se establece enfalseexposure.docs: marca el canal como interno/privado para las superficies de navegación de documentaciónshowConfigured/showInSetup: alias heredados que todavía se aceptan por compatibilidad; prefiereexposurequickstartAllowFrom: incluye el canal en el flujo estándar de inicio rápidoallowFromforceAccountBinding: exige vinculación explícita de cuenta incluso cuando solo existe una cuentapreferSessionLookupForAnnounceTarget: prefiere la búsqueda de sesión al resolver destinos de anuncio
~/.openclaw/mpm/plugins.json~/.openclaw/mpm/catalog.json~/.openclaw/plugins/catalog.json
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 conapi.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.
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:
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:- 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.
- añade superficies tipadas de registro/runtime de Plugin
Extiende
OpenClawPluginApiy/oapi.runtimecon la superficie de capacidad tipada útil más pequeña. - 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.
- registra implementaciones de proveedores Los Plugins de proveedor registran entonces sus backends contra la capacidad.
- añade cobertura de contrato Añade pruebas para que la propiedad y la forma de registro sigan siendo explícitas con el tiempo.
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/
Plantilla de capacidad
Patrón mínimo:- 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
- Arquitectura de Plugins — modelo público de capacidades y formas
- Subrutas del SDK de Plugins
- Configuración del SDK de Plugins
- Crear Plugins