Manifiesto del Plugin

Esta página trata sobre el manifiesto nativo de plugins de OpenClaw, openclaw.plugin.json. Para conocer las estructuras de paquetes compatibles (Codex, Claude, Cursor), consulte Paquetes de plugins.

Los formatos de paquetes compatibles utilizan sus propios archivos de manifiesto:

• Paquete de Codex: .codex-plugin/plugin.json
• Paquete de Claude: .claude-plugin/plugin.json, o la estructura predeterminada de componentes de Claude sin manifiesto
• Paquete de Cursor: .cursor-plugin/plugin.json

OpenClaw detecta automáticamente estas estructuras, pero no las valida con el esquema openclaw.plugin.json que aparece a continuación. En los paquetes compatibles, OpenClaw lee los metadatos del paquete, las raíces de Skills declaradas, las raíces de comandos de Claude, los valores predeterminados de settings.json de Claude, los valores predeterminados de LSP de Claude y los paquetes de hooks compatibles, cuando la estructura coincide con las expectativas del entorno de ejecución de OpenClaw.

Cada plugin nativo de OpenClaw debe incluir openclaw.plugin.json en la raíz del plugin. OpenClaw lo lee para validar la configuración sin ejecutar el código del plugin. La ausencia de un manifiesto o un manifiesto no válido bloquea la validación de la configuración y se trata como un error del plugin.

Consulte Plugins para obtener la guía completa del sistema de plugins y Modelo de capacidades para conocer el modelo de capacidades nativo y las directrices actuales de compatibilidad externa.

Función de este archivo

openclaw.plugin.json contiene metadatos que OpenClaw lee antes de cargar el código del plugin. Todo su contenido debe poder inspeccionarse con un coste suficientemente bajo sin iniciar el entorno de ejecución del plugin.

Se utiliza para:

• identidad del plugin, validación de la configuración e indicaciones para la interfaz de configuración
• metadatos de autenticación, incorporación y configuración (alias, activación automática, variables de entorno del proveedor y opciones de autenticación)
• indicaciones de activación para las superficies del plano de control
• propiedad abreviada de familias de modelos
• instantáneas estáticas de propiedad de capacidades (contracts)
• vinculaciones de datos y verbos de acción de los widgets del panel
• servidores MCP estáticos que deben existir mientras el plugin esté habilitado
• metadatos del ejecutor de control de calidad que puede inspeccionar el host compartido openclaw qa
• metadatos de configuración específicos del canal que se combinan en las superficies de catálogo y validación

No se utiliza para: registrar hooks nativos del entorno de ejecución, declarar puntos de entrada del código del plugin ni especificar metadatos de instalación de npm. Estos elementos corresponden al código del plugin y a package.json.

Ejemplo mínimo

{  "id": "voice-call",  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {}  }}

Ejemplo completo

{  "id": "openrouter",  "name": "OpenRouter",  "description": "Plugin de proveedor OpenRouter",  "version": "1.0.0",  "providers": ["openrouter"],  "modelSupport": {    "modelPrefixes": ["router-"]  },  "modelIdNormalization": {    "providers": {      "openrouter": {        "prefixWhenBare": "openrouter"      }    }  },  "providerEndpoints": [    {      "endpointClass": "openrouter",      "hostSuffixes": ["openrouter.ai"]    }  ],  "providerRequest": {    "providers": {      "openrouter": {        "family": "openrouter"      }    }  },  "cliBackends": ["openrouter-cli"],  "syntheticAuthRefs": ["openrouter-cli"],  "setup": {    "providers": [      {        "id": "openrouter",        "envVars": ["OPENROUTER_API_KEY"]      }    ]  },  "providerAuthAliases": {    "openrouter-coding": "openrouter"  },  "providerAuthChoices": [    {      "provider": "openrouter",      "method": "api-key",      "choiceId": "openrouter-api-key",      "choiceLabel": "Clave de API de OpenRouter",      "groupId": "openrouter",      "groupLabel": "OpenRouter",      "optionKey": "openrouterApiKey",      "cliFlag": "--openrouter-api-key",      "cliOption": "--openrouter-api-key <key>",      "cliDescription": "Clave de API de OpenRouter",      "onboardingScopes": ["text-inference"]    }  ],  "uiHints": {    "apiKey": {      "label": "Clave de API",      "placeholder": "sk-or-v1-...",      "sensitive": true    }  },  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "apiKey": {        "type": "string"      }    }  }}

Referencia de campos de nivel superior

Referencia del servidor MCP

mcpServers permite que un plugin nativo incluya un servidor MCP, incluida una aplicación MCP, sin exigir que los operadores dupliquen su definición estática de proceso en openclaw.json:

{  "mcpServers": {    "example": {      "transport": "stdio",      "command": "node",      "args": ["./mcp-server.js"]    }  }}

OpenClaw incluye estos servidores únicamente mientras el plugin propietario está habilitado. Las rutas relativas command, args, cwd y workingDirectory se resuelven desde la raíz del plugin. La configuración del usuario sigue siendo vinculante: mcp.servers.<name> puede reemplazar un valor predeterminado del plugin o establecer enabled: false para omitirlo. La representación de aplicaciones MCP y las llamadas a herramientas del servidor siguen requiriendo la configuración habitual de aplicaciones MCP y la política de herramientas efectiva; declarar un servidor no elude ninguno de estos límites.

Referencia del panel

dashboard permite que un plugin habilitado exponga RPC existentes del Gateway a widgets del panel con los permisos correspondientes, sin añadir políticas del plugin al núcleo. Los enlaces de datos deben indicar un método que el mismo plugin registre con operator.read; los verbos de acción deben indicar un método que registre con operator.write. Una discrepancia provoca el rechazo del plugin durante el registro.

{  "dashboard": {    "dataBindings": [      {        "id": "items.list",        "method": "example.items.list",        "description": "List example items."      }    ],    "actionVerbs": [      {        "id": "refresh",        "method": "example.items.refresh",        "description": "Refresh example items.",        "paramShape": {          "type": "object",          "additionalProperties": false,          "properties": {            "force": { "type": "boolean" }          }        }      }    ]  }}

Los identificadores del manifiesto son locales al plugin. Los permisos de los widgets usan <plugin-id>.<id>, como example.items.list y example.refresh. Para mantener inequívoco el espacio de nombres de permisos persistentes, OpenClaw convierte % y . del segmento del identificador del plugin en %25 y %2E; los identificadores de plugin habituales conservan la forma natural. paramShape es un esquema JSON opcional que se aplica al objeto de parámetros de la acción antes de que OpenClaw invoque el RPC del plugin.

Referencia del catálogo

catalog proporciona indicaciones de visualización opcionales a los exploradores de plugins. Los hosts pueden ignorar estas indicaciones. Nunca instalan ni habilitan el plugin, y no modifican su comportamiento en tiempo de ejecución ni su nivel de confianza.

{  "catalog": {    "featured": true,    "order": 10  }}

Referencia de metadatos de proveedores de generación

Los campos de metadatos de proveedores de generación describen señales estáticas de autenticación para los proveedores declarados en la lista contracts.*GenerationProviders correspondiente. OpenClaw lee estos campos antes de cargar el entorno de ejecución del proveedor, de modo que las herramientas del núcleo puedan determinar si un proveedor de generación está disponible sin importar todos los plugins de proveedores.

Estos campos deben usarse únicamente para datos declarativos de bajo coste. El transporte, las transformaciones de solicitudes, la renovación de tokens, la validación de credenciales y el comportamiento real de generación permanecen en el entorno de ejecución del plugin.

{  "contracts": {    "imageGenerationProviders": ["example-image"]  },  "imageGenerationProviderMetadata": {    "example-image": {      "aliases": ["example-image-oauth"],      "authProviders": ["example-image"],      "configSignals": [        {          "rootPath": "plugins.entries.example-image.config",          "overlayPath": "image",          "mode": {            "path": "mode",            "default": "local",            "allowed": ["local"]          },          "requiredAny": ["workflow", "workflowPath"],          "required": ["promptNodeId"]        }      ],      "authSignals": [        {          "provider": "example-image"        },        {          "provider": "example-image-oauth",          "providerBaseUrl": {            "provider": "example-image",            "defaultBaseUrl": "https://api.example.com/v1",            "allowedBaseUrls": ["https://api.example.com/v1"]          }        }      ]    }  }}

Cada entrada de metadatos admite:

Cada entrada configSignals admite:

Cada restricción mode admite:

Cada entrada authSignals admite:

Cada restricción providerBaseUrl admite:

Referencia de metadatos de herramientas

toolMetadata utiliza las mismas estructuras configSignals y authSignals que los metadatos de proveedores de generación, indexadas por nombre de herramienta. contracts.tools declara la propiedad. toolMetadata declara evidencias de disponibilidad de bajo coste para que OpenClaw pueda evitar importar el entorno de ejecución de un plugin solo para que su fábrica de herramientas devuelva null.

{  "setup": {    "providers": [      {        "id": "example",        "envVars": ["EXAMPLE_API_KEY"]      }    ]  },  "contracts": {    "tools": ["example_search"]  },  "toolMetadata": {    "example_search": {      "authSignals": [        {          "provider": "example"        }      ],      "configSignals": [        {          "rootPath": "plugins.entries.example.config",          "overlayPath": "search",          "required": ["apiKey"]        }      ]    }  }}

Las entradas toolMetadata también aceptan optional (marca la herramienta como no obligatoria para la activación del plugin) y replaySafe (marca la ejecución de la herramienta como segura para repetirla tras un turno incompleto del modelo), además de los campos compartidos configSignals/authSignals anteriores.

Si una herramienta no tiene toolMetadata, OpenClaw conserva el comportamiento existente y carga el plugin propietario cuando el contrato de la herramienta coincide con la política. Para las herramientas de rutas críticas cuya fábrica depende de la autenticación/configuración, los autores de plugins deben declarar toolMetadata en lugar de hacer que el núcleo importe el entorno de ejecución para consultarlo.

Referencia de providerAuthChoices

Cada entrada providerAuthChoices describe una opción de incorporación o autenticación. OpenClaw lee esta información antes de cargar el entorno de ejecución del proveedor. Las listas de configuración de proveedores utilizan estas opciones del manifiesto, las opciones de configuración derivadas de descriptores y los metadatos del catálogo de instalación sin cargar el entorno de ejecución del proveedor.

Cuando appGuidedDiscovery es verdadero, el método de autenticación del proveedor correspondiente debe exponer appGuidedSetup.detect y appGuidedSetup.prepare. La detección debe ser de solo lectura: no debe iniciar sesión, obtener modelos, descargar ni escribir la configuración. La preparación vuelve a comprobar el modelo exacto seleccionado y devuelve una propuesta de configuración; OpenClaw prueba en vivo esa propuesta de forma aislada y solo la confirma después de que tenga éxito.

Referencia de commandAliases

Utilice commandAliases cuando un plugin sea propietario de un nombre de comando del entorno de ejecución que los usuarios puedan poner por error en plugins.allow o intentar ejecutar como comando raíz de la CLI. OpenClaw utiliza estos metadatos para los diagnósticos sin importar el código del entorno de ejecución del plugin.

{  "commandAliases": [    {      "name": "dreaming",      "kind": "runtime-slash",      "cliCommand": "memory"    }  ]}

Referencia de activation

Utilice activation cuando el plugin pueda declarar con poco coste qué eventos del plano de control deben incluirlo en un plan de activación/carga.

Este bloque contiene metadatos del planificador, no es una API de ciclo de vida. No registra el comportamiento del entorno de ejecución, no reemplaza a register(...) ni garantiza que el código del plugin ya se haya ejecutado. El planificador de activación utiliza estos campos para reducir los plugins candidatos antes de recurrir a los metadatos existentes de propiedad del manifiesto, como providers, channels, commandAliases, setup.providers, contracts.tools y los hooks.

Utilice preferentemente los metadatos más específicos que ya describan la propiedad. Utilice providers, channels, commandAliases, los descriptores de configuración o contracts cuando esos campos expresen la relación. Utilice activation para indicaciones adicionales del planificador que no puedan representarse mediante esos campos de propiedad. Utilice cliBackends de nivel superior para los alias del entorno de ejecución de la CLI, como claude-cli, my-cli o google-gemini-cli; activation.onAgentHarnesses solo se utiliza para los identificadores del arnés de agente incorporado que aún no tengan un campo de propiedad.

Cada plugin debe configurar activation.onStartup intencionadamente. Establézcalo en true solo cuando el plugin deba ejecutarse durante el inicio del Gateway. Establézcalo en false cuando el plugin esté inactivo durante el inicio y solo deba cargarse mediante activadores más específicos. Omitir onStartup ya no carga implícitamente el plugin durante el inicio; utilice metadatos de activación explícitos para el inicio, el canal, la configuración, el arnés de agente, la memoria u otros activadores de activación más específicos.

{  "activation": {    "onStartup": false,    "onProviders": ["openai"],    "onCommands": ["models"],    "onChannels": ["web"],    "onRoutes": ["gateway-webhook"],    "onConfigPaths": ["browser"],    "onCapabilities": ["provider", "tool"]  }}

Consumidores activos actuales:

• La planificación del inicio del Gateway usa activation.onStartup para la importación explícita durante el inicio.
• La planificación de la CLI desencadenada por comandos recurre a los valores heredados commandAliases[].cliCommand o commandAliases[].name.
• La planificación del inicio del entorno de ejecución del agente usa activation.onAgentHarnesses para los arneses integrados y cliBackends[] de nivel superior para los alias de entorno de ejecución de la CLI.
• La planificación de la configuración/canal desencadenada por canales recurre a la propiedad heredada de channels[] cuando faltan metadatos explícitos de activación de canales.
• La planificación de plugins durante el inicio usa activation.onConfigPaths para superficies de configuración raíz que no sean de canales, como el bloque browser del plugin de navegador incluido.
• La planificación de la configuración/entorno de ejecución desencadenada por proveedores recurre a la propiedad heredada de providers[] y cliBackends[] de nivel superior cuando faltan metadatos explícitos de activación de proveedores.

Los diagnósticos del planificador pueden distinguir las indicaciones explícitas de activación del recurso a la propiedad del manifiesto. Por ejemplo, activation-command-hint significa que activation.onCommands coincidió, mientras que manifest-command-alias significa que el planificador utilizó en su lugar la propiedad de commandAliases. Estas etiquetas de motivos están destinadas a los diagnósticos y las pruebas del host; los autores de plugins deben seguir declarando los metadatos que mejor describan la propiedad.

Referencia de qaRunners

Use qaRunners cuando un plugin aporte uno o varios ejecutores de transporte bajo la raíz compartida openclaw qa. Mantenga estos metadatos ligeros y estáticos; el entorno de ejecución del plugin sigue siendo responsable del registro real en la CLI mediante una superficie ligera runtime-api.ts que exporta elementos qaRunnerCliRegistrations coincidentes. Un adapterFactory opcional expone el transporte a escenarios de control de calidad compartidos sin cambiar el ejecutor del comando registrado.

{  "qaRunners": [    {      "commandName": "matrix",      "description": "Ejecutar el carril de control de calidad en vivo de Matrix respaldado por Docker contra un servidor doméstico desechable"    }  ]}

El id. adapterFactory debe coincidir con commandName. No exporte registros para comandos ausentes del manifiesto.

Referencia de setup

Use setup cuando las superficies de configuración e incorporación necesiten metadatos ligeros propiedad del plugin antes de que se cargue el entorno de ejecución.

{  "setup": {    "providers": [      {        "id": "openai",        "authMethods": ["api-key"],        "envVars": ["OPENAI_API_KEY"],        "authEvidence": [          {            "type": "local-file-with-env",            "fileEnvVar": "OPENAI_CREDENTIALS_FILE",            "requiresAllEnv": ["OPENAI_PROJECT"],            "credentialMarker": "openai-local-credentials",            "source": "credenciales locales de openai"          }        ]      }    ],    "cliBackends": ["openai-cli"],    "configMigrations": ["legacy-openai-auth"],    "requiresRuntime": false  }}

cliBackends de nivel superior sigue siendo válido y continúa describiendo los backends de inferencia de la CLI. setup.cliBackends es la superficie de descriptores específica de la configuración para los flujos del plano de control/configuración que deben limitarse a los metadatos.

Cuando están presentes, setup.providers y setup.cliBackends constituyen la superficie preferida de búsqueda basada primero en descriptores para el descubrimiento de la configuración. Si el descriptor solo acota el plugin candidato y la configuración aún necesita enlaces más completos del entorno de ejecución durante la configuración, establezca requiresRuntime: true y mantenga setup-api como ruta de ejecución alternativa.

OpenClaw incluye setup.providers[].envVars en las búsquedas genéricas de autenticación de proveedores y variables de entorno. Coloque allí los metadatos de entorno de configuración y estado.

Use providerUsageAuthEnvVars cuando una credencial de facturación o de nivel organizativo deba activar resolveUsageAuth sin convertirse en una credencial de inferencia. Estos nombres se incorporan al bloqueo de dotenv del espacio de trabajo, la eliminación en procesos secundarios de ACP, el filtrado de secretos del entorno aislado y la eliminación general de secretos. El entorno de ejecución del proveedor sigue leyendo y clasificando el valor dentro de resolveUsageAuth.

OpenClaw también puede derivar opciones sencillas de configuración a partir de setup.providers[].authMethods cuando no hay ninguna entrada de configuración disponible o cuando setup.requiresRuntime: false declara innecesario el entorno de ejecución de configuración. Las entradas explícitas de providerAuthChoices siguen siendo preferibles para etiquetas personalizadas, indicadores de la CLI, el ámbito de incorporación y los metadatos del asistente.

Establezca requiresRuntime: false solo cuando esos descriptores sean suficientes para la superficie de configuración. OpenClaw trata un false explícito como un contrato basado únicamente en descriptores y no ejecutará setup-api ni openclaw.setupEntry para la búsqueda de configuración. Si un plugin basado únicamente en descriptores todavía incluye una de esas entradas del entorno de ejecución de configuración, OpenClaw genera un diagnóstico adicional y continúa ignorándola. Si se omite requiresRuntime, se conserva el comportamiento alternativo heredado para no interrumpir los plugins existentes que añadieron descriptores sin el indicador.

Dado que la búsqueda de configuración puede ejecutar código setup-api propiedad del plugin, los valores normalizados de setup.providers[].id y setup.cliBackends[] deben ser únicos entre los plugins descubiertos. En caso de propiedad ambigua, el proceso se cierra de forma segura en lugar de elegir un ganador según el orden de descubrimiento.

Cuando se ejecuta el entorno de configuración, los diagnósticos del registro de configuración informan de divergencias respecto de los descriptores si setup-api registra un proveedor o un backend de la CLI que los descriptores del manifiesto no declaran, o si un descriptor no tiene un registro correspondiente en el entorno de ejecución. Estos diagnósticos son adicionales y no rechazan los plugins heredados.

Referencia de setup.providers

authEvidence se utiliza para marcadores de credenciales locales propiedad del proveedor que pueden verificarse sin cargar código del entorno de ejecución. Estas comprobaciones deben mantenerse ligeras y locales: sin llamadas de red, sin lecturas del llavero o del gestor de secretos, sin comandos de shell y sin sondeos de la API del proveedor.

Entradas de indicios compatibles:

Campos de setup

Referencia de uiHints

uiHints es un mapa de nombres de campos de configuración a pequeñas indicaciones de representación. Las claves pueden usar puntos para campos de configuración anidados, pero ningún segmento de ruta puede ser __proto__, constructor ni prototype; la configuración rechaza esos nombres.

{  "uiHints": {    "apiKey": {      "label": "Clave de API",      "help": "Se usa para las solicitudes de OpenRouter",      "placeholder": "sk-or-v1-...",      "sensitive": true    }  }}

Cada indicación de campo puede incluir:

Referencia de contracts

Use contracts únicamente para metadatos estáticos de pertenencia de capacidades que OpenClaw pueda leer sin importar el entorno de ejecución del plugin.

{  "contracts": {    "agentToolResultMiddleware": ["openclaw", "codex"],    "trustedToolPolicies": ["workflow-budget"],    "externalAuthProviders": ["acme-ai"],    "embeddingProviders": ["openai-compatible"],    "speechProviders": ["openai"],    "realtimeTranscriptionProviders": ["openai"],    "realtimeVoiceProviders": ["openai"],    "memoryEmbeddingProviders": ["local"],    "mediaUnderstandingProviders": ["openai"],    "imageGenerationProviders": ["openai"],    "videoGenerationProviders": ["qwen"],    "musicGenerationProviders": ["stability-audio"],    "documentExtractors": ["example-docs"],    "webContentExtractors": ["firecrawl"],    "webFetchProviders": ["firecrawl"],    "webSearchProviders": ["gemini"],    "workerProviders": ["example-worker"],    "usageProviders": ["acme-ai"],    "migrationProviders": ["hermes"],    "gatewayMethodDispatch": ["authenticated-request"],    "tools": ["firecrawl_search", "firecrawl_scrape"]  }}

Cada lista es opcional:

contracts.embeddedExtensionFactories se conserva para las fábricas de extensiones incluidas que son exclusivas del servidor de aplicaciones de Codex. Las transformaciones incluidas de resultados de herramientas deben declarar contracts.agentToolResultMiddleware y registrarse con api.registerAgentToolResultMiddleware(...). Los plugins instalados pueden usar el mismo punto de integración de middleware únicamente cuando esté habilitado explícitamente y solo para los entornos de ejecución que declaren en contracts.agentToolResultMiddleware.

Los plugins instalados que necesiten el nivel de políticas previas a las herramientas en el que confía el host deben declarar cada identificador local registrado en contracts.trustedToolPolicies y habilitarse explícitamente. Los plugins incluidos conservan la ruta existente de políticas de confianza, pero los plugins instalados con identificadores de políticas no declarados se rechazan antes del registro. Los identificadores de políticas tienen como ámbito el plugin que los registra, por lo que dos plugins pueden declarar y registrar workflow-budget; un mismo plugin no puede registrar dos veces el mismo identificador local.

Los registros de api.registerTool(...) en tiempo de ejecución deben coincidir con contracts.tools. El descubrimiento de herramientas usa esta lista para cargar únicamente los entornos de ejecución de plugins que pueden poseer las herramientas solicitadas.

Los plugins de proveedores que implementen resolveExternalAuthProfiles deben declarar contracts.externalAuthProviders; se ignoran los hooks de autenticación externa no declarados.

Los plugins de proveedores que implementen tanto resolveUsageAuth como fetchUsageSnapshot deben declarar cada identificador de proveedor detectado automáticamente en contracts.usageProviders. El descubrimiento de uso lee este contrato antes de cargar el código de ejecución y, después de cargar únicamente a los propietarios declarados, verifica ambos hooks.

Los proveedores generales de embeddings deben declarar contracts.embeddingProviders para cada adaptador registrado con api.registerEmbeddingProvider(...). Use el contrato general para la generación reutilizable de vectores, incluidos los proveedores que consume la búsqueda en memoria. contracts.memoryEmbeddingProviders es una compatibilidad obsoleta específica de memoria y se conserva únicamente mientras los proveedores existentes migran al punto de integración genérico para proveedores de embeddings.

Los proveedores de trabajadores deben declarar cada identificador api.registerWorkerProvider(...) en contracts.workerProviders. El núcleo conserva la intención duradera antes de llamar a provision; los proveedores validan su configuración antes de la asignación externa y las llamadas repetidas con el mismo identificador de operación deben adoptar el mismo arrendamiento. El núcleo también conserva esa instantánea de la configuración validada y la pasa con leaseId a inspect({ leaseId, profile }) y destroy({ leaseId, profile }), incluso después de que se modifique o elimine el perfil indicado. La destrucción es idempotente, la inspección devuelve la unión cerrada de estados active / destroyed / unknown, y el material de la clave privada SSH solo se referencia mediante SecretRef. Los extremos SSH aprovisionados también deben incluir un hostKey público procedente de una salida de aprovisionamiento de confianza exactamente como algorithm base64, sin nombre de host ni comentario, para que el núcleo pueda fijar el host antes de conectarse. Los proveedores que generen referencias de identidad dinámicas pueden implementar el resolveSshIdentity({ leaseId, profile, keyRef }) autoritativo; los proveedores que no lo hagan usan el solucionador genérico de secretos del núcleo. Un unknown autoritativo deja huérfano un registro local activo; después de una solicitud de destrucción conservada, confirma el desmontaje.

contracts.gatewayMethodDispatch actualmente acepta "authenticated-request". Es una barrera de higiene de API para rutas HTTP de plugins nativos que despachan intencionadamente métodos del plano de control del Gateway dentro del proceso, no un entorno aislado contra plugins nativos maliciosos. Úselo únicamente para superficies integradas o del operador sometidas a una revisión rigurosa que ya requieran autenticación HTTP del Gateway. Una ruta autorizada sigue siendo accesible mientras la admisión de trabajo raíz del Gateway está cerrada solo cuando también declara auth: "gateway" y el gatewayRuntimeScopeSurface: "trusted-operator" específico de la ruta; las rutas hermanas ordinarias del mismo plugin permanecen detrás del límite de admisión. Esto mantiene accesibles el estado de suspensión y la reanudación sin conceder a todo el plugin una omisión de la admisión. Mantenga el análisis y la conformación de respuestas acotados fuera del despacho; el trabajo sustancial o que produzca modificaciones debe pasar por el despacho de métodos del Gateway, que es responsable de aplicar la admisión y el ámbito.

Referencia de configContracts

Use configContracts para el comportamiento de configuración propiedad del manifiesto que necesitan los ayudantes genéricos del núcleo sin importar el entorno de ejecución del plugin: detección de indicadores peligrosos, destinos de migración de SecretRef y delimitación de rutas de configuración heredadas.

{  "configContracts": {    "compatibilityMigrationPaths": ["legacyProvider"],    "compatibilityRuntimePaths": ["legacyProvider.webhook"],    "dangerousFlags": [      {        "path": "accounts.*.allowUnverifiedSenders",        "equals": true      }    ],    "secretInputs": {      "bundledDefaultEnabled": false,      "paths": [        {          "path": "routes.*.secret",          "expected": "string",          "ownerKind": "route"        }      ]    }  }}

Cada entrada de dangerousFlags admite:

secretInputs admite:

Referencia de mediaUnderstandingProviderMetadata

Use mediaUnderstandingProviderMetadata cuando un proveedor de comprensión multimedia tenga modelos predeterminados, una prioridad de reserva para la autenticación automática o compatibilidad nativa con documentos que los ayudantes genéricos del núcleo necesiten antes de cargar el entorno de ejecución. Las claves también deben declararse en contracts.mediaUnderstandingProviders.

{  "contracts": {    "mediaUnderstandingProviders": ["example"]  },  "mediaUnderstandingProviderMetadata": {    "example": {      "capabilities": ["image", "audio"],      "defaultModels": {        "image": "example-vision-latest",        "audio": "example-transcribe-latest"      },      "autoPriority": {        "image": 40      },      "nativeDocumentInputs": ["pdf"],      "documentModels": {        "pdf": {          "textExtraction": "example-doc-text-latest",          "image": "example-doc-vision-latest"        }      }    }  }}

Cada entrada de proveedor puede incluir:

Referencia de channelConfigs

Use channelConfigs cuando un plugin de canal necesite metadatos de configuración de bajo coste antes de cargar el entorno de ejecución. La detección de configuración o estado de canales en modo de solo lectura puede utilizar estos metadatos directamente para canales externos configurados cuando no haya disponible una entrada de configuración o cuando setup.requiresRuntime: false declare innecesario el entorno de ejecución de configuración.

channelConfigs son metadatos del manifiesto del plugin, no una nueva sección de configuración de usuario de nivel superior. Los usuarios siguen configurando instancias de canal bajo channels.<channel-id>. OpenClaw lee los metadatos del manifiesto para determinar qué plugin posee ese canal configurado antes de que se ejecute el código del entorno de ejecución del plugin.

Para un plugin de canal, configSchema y channelConfigs describen rutas diferentes:

• configSchema valida plugins.entries.<plugin-id>.config
• channelConfigs.<channel-id>.schema valida channels.<channel-id>

Los plugins no integrados que declaren channels[] también deben declarar entradas channelConfigs coincidentes. Sin ellas, OpenClaw aún puede cargar el plugin, pero las superficies del esquema de configuración de la ruta fría, de configuración y de la interfaz de control no pueden conocer la forma de las opciones propiedad del canal ni las indicaciones de interfaz destinadas únicamente a la visualización hasta que se ejecute el entorno de ejecución del plugin.

channelConfigs.<channel-id>.commands.nativeCommandsAutoEnabled y nativeSkillsAutoEnabled pueden declarar valores predeterminados estáticos de auto para las comprobaciones de configuración de comandos que se ejecutan antes de cargar el entorno de ejecución del canal. Los canales integrados también pueden publicar los mismos valores predeterminados mediante package.json#openclaw.channel.commands, junto con los demás metadatos de catálogo de canales propiedad del paquete.

{  "channelConfigs": {    "matrix": {      "schema": {        "type": "object",        "additionalProperties": false,        "properties": {          "homeserverUrl": { "type": "string" }        }      },      "uiHints": {        "homeserverUrl": {          "label": "URL del servidor doméstico",          "placeholder": "https://matrix.example.com"        }      },      "label": "Matrix",      "description": "Conexión con el servidor doméstico de Matrix",      "commands": {        "nativeCommandsAutoEnabled": true,        "nativeSkillsAutoEnabled": true      },      "preferOver": ["matrix-legacy"]    }  }}

Cada entrada de canal puede incluir:

Sustitución de otro plugin de canal

Use preferOver cuando su plugin sea el propietario preferido de un identificador de canal que también pueda proporcionar otro plugin. Los casos habituales son un identificador de plugin renombrado, un plugin independiente que sustituye a uno integrado o una bifurcación mantenida que conserva el mismo identificador de canal por compatibilidad con la configuración.

{  "id": "acme-chat",  "channels": ["chat"],  "channelConfigs": {    "chat": {      "schema": {        "type": "object",        "additionalProperties": false,        "properties": {          "webhookUrl": { "type": "string" }        }      },      "preferOver": ["chat"]    }  }}

Cuando se configura channels.chat, OpenClaw tiene en cuenta tanto el id del canal como el id del plugin preferido. Si el plugin de menor prioridad solo se seleccionó porque está incluido o habilitado de forma predeterminada, OpenClaw lo deshabilita en la configuración efectiva del entorno de ejecución para que un único plugin sea propietario del canal y de sus herramientas. La selección explícita del usuario sigue teniendo prioridad: si el usuario habilita explícitamente ambos plugins (mediante plugins.allow o una configuración plugins.entries sustancial), OpenClaw conserva esa elección y notifica diagnósticos de duplicación de canales o herramientas, en lugar de cambiar silenciosamente el conjunto de plugins solicitado.

Limite preferOver a los ids de plugins que realmente puedan proporcionar el mismo canal. No es un campo de prioridad general ni cambia el nombre de las claves de configuración del usuario.

Referencia de modelSupport

Utilice modelSupport cuando OpenClaw deba inferir el plugin del proveedor a partir de ids abreviados de modelos como gpt-5.6-sol o claude-sonnet-4.6 antes de que se cargue el entorno de ejecución del plugin.

{  "modelSupport": {    "modelPrefixes": ["gpt-", "o1", "o3", "o4"],    "modelPatterns": ["^computer-use-preview"]  }}

OpenClaw aplica esta precedencia:

• las referencias provider/model explícitas utilizan los metadatos del manifiesto providers propietario
• modelPatterns tienen prioridad sobre modelPrefixes
• si coinciden un plugin no incluido y uno incluido, tiene prioridad el plugin no incluido
• la ambigüedad restante se ignora hasta que el usuario o la configuración especifiquen un proveedor

Campos:

Las entradas modelPatterns se compilan mediante compileSafeRegex, que rechaza los patrones que contienen repeticiones anidadas (por ejemplo, (a+)+$). Los patrones que no superan la comprobación de seguridad se omiten silenciosamente, al igual que las expresiones regulares sintácticamente no válidas. Mantenga los patrones sencillos y evite los cuantificadores anidados.

Referencia de modelCatalog

Utilice modelCatalog cuando OpenClaw deba conocer los metadatos de los modelos del proveedor antes de cargar el entorno de ejecución del plugin. Esta es la fuente propiedad del manifiesto para las filas fijas del catálogo, los alias de proveedores, las reglas de supresión y el modo de detección. La actualización en tiempo de ejecución sigue correspondiendo al código del entorno de ejecución del proveedor, pero el manifiesto indica al núcleo cuándo se requiere dicho entorno.

{  "providers": ["openai"],  "modelCatalog": {    "providers": {      "openai": {        "baseUrl": "https://api.openai.com/v1",        "api": "openai-responses",        "models": [          {            "id": "gpt-5.4",            "name": "GPT-5.4",            "input": ["text", "image"],            "reasoning": true,            "contextWindow": 256000,            "maxTokens": 128000,            "cost": {              "input": 1.25,              "output": 10,              "cacheRead": 0.125            },            "status": "available",            "tags": ["default"]          }        ]      }    },    "aliases": {      "azure-openai-responses": {        "provider": "openai",        "api": "azure-openai-responses"      }    },    "suppressions": [      {        "provider": "azure-openai-responses",        "model": "gpt-5.3-codex-spark",        "reason": "not available on Azure OpenAI Responses"      }    ],    "discovery": {      "openai": "static"    }  }}

Campos de nivel superior:

aliases participa en la búsqueda de propiedad del proveedor para planificar el catálogo de modelos. Los destinos de los alias deben ser proveedores de nivel superior que pertenezcan al mismo plugin. Cuando una lista filtrada por proveedor utiliza un alias, OpenClaw puede leer el manifiesto propietario y aplicar las sustituciones de API o URL base del alias sin cargar el entorno de ejecución del proveedor. Los alias no amplían las listas de catálogos sin filtrar; las listas generales solo emiten las filas del proveedor canónico propietario.

suppressions sustituye el antiguo enlace suppressBuiltInModel del entorno de ejecución del proveedor. Las entradas de supresión solo se respetan cuando el proveedor pertenece al plugin o se declara como una clave modelCatalog.aliases que apunta a un proveedor propio. Los enlaces de supresión del entorno de ejecución ya no se invocan durante la resolución de modelos.

Campos del proveedor:

Campos del modelo:

Campos de supresión:

No coloque datos exclusivos del entorno de ejecución en modelCatalog. Use static solo cuando las filas del manifiesto sean lo bastante completas como para que las superficies de lista y selección filtradas por proveedor omitan la detección del registro y del entorno de ejecución. Use refreshable cuando las filas del manifiesto sean datos iniciales enumerables o complementos útiles, pero una actualización o caché pueda añadir más filas posteriormente; las filas actualizables no son autoritativas por sí solas. Use runtime cuando OpenClaw deba cargar el entorno de ejecución del proveedor para conocer la lista.

Referencia de modelIdNormalization

Use modelIdNormalization para la normalización sencilla de los id. de modelo propiedad del proveedor que debe realizarse antes de cargar el entorno de ejecución del proveedor. Esto mantiene en el manifiesto del plugin propietario los alias, como nombres cortos de modelos, id. heredados locales del proveedor y reglas de prefijos de proxy, en lugar de incluirlos en las tablas principales de selección de modelos.

{  "providers": ["anthropic", "openrouter"],  "modelIdNormalization": {    "providers": {      "anthropic": {        "aliases": {          "sonnet-4.6": "claude-sonnet-4-6"        }      },      "openrouter": {        "prefixWhenBare": "openrouter"      }    }  }}

Campos del proveedor:

Referencia de providerEndpoints

Use providerEndpoints para la clasificación de puntos de conexión que la política genérica de solicitudes debe conocer antes de cargar el entorno de ejecución del proveedor. El núcleo sigue siendo propietario del significado de cada endpointClass; los manifiestos de los plugins son propietarios de los metadatos del host y de la URL base.

Los plugins de proveedores externalizados oficialmente se excluyen de la distribución principal, por lo que sus manifiestos no son visibles hasta que se instalan. Sus providerEndpoints también deben reflejarse en scripts/lib/official-external-provider-catalog.json para que la clasificación de puntos de conexión siga funcionando sin el plugin; una prueba de contrato garantiza esta correspondencia.

Campos del punto de conexión:

Referencia de providerRequest

Use providerRequest para los metadatos sencillos de compatibilidad de solicitudes que necesita la política genérica de solicitudes sin cargar el entorno de ejecución del proveedor. Mantenga la reescritura de cargas útiles específica del comportamiento en los hooks del entorno de ejecución del proveedor o en los asistentes compartidos de la familia de proveedores.

{  "providerRequest": {    "providers": {      "vllm": {        "family": "vllm",        "openAICompletions": {          "supportsStreamingUsage": true        }      }    }  }}

Campos del proveedor:

Referencia de secretProviderIntegrations

Use secretProviderIntegrations cuando un plugin pueda publicar un preajuste reutilizable de proveedor de ejecución SecretRef. OpenClaw lee estos metadatos antes de cargar el entorno de ejecución del plugin, almacena la propiedad del plugin en secrets.providers.<alias>.pluginIntegration y deja la resolución real de secretos al entorno de ejecución de SecretRef. Los preajustes solo se exponen para plugins incluidos e instalados que se detectan en las raíces administradas de instalación de plugins, como las instalaciones desde git y ClawHub.

{  "secretProviderIntegrations": {    "secret-store": {      "providerAlias": "team-secrets",      "displayName": "Team secrets",      "source": "exec",      "command": "${node}",      "args": ["./bin/resolve-secrets.mjs"]    }  }}

La clave del mapa es el id. de integración. Si se omite providerAlias, OpenClaw usa el id. de integración como alias del proveedor SecretRef. Los alias de proveedores deben coincidir con el patrón normal de alias de proveedores SecretRef, por ejemplo, team-secrets o onepassword-work.

Cuando un operador selecciona el preajuste, OpenClaw escribe una referencia de proveedor como la siguiente:

{  "secrets": {    "providers": {      "team-secrets": {        "source": "exec",        "pluginIntegration": {          "pluginId": "acme-secrets",          "integrationId": "secret-store"        }      }    }  }}

Durante el inicio o la recarga, OpenClaw resuelve ese proveedor cargando los metadatos actuales del manifiesto del plugin, comprobando que el plugin propietario esté instalado y activo, y materializando el comando de ejecución a partir del manifiesto. Deshabilitar o eliminar el plugin revoca el proveedor para las SecretRefs activas. Los operadores que quieran una configuración de ejecución independiente pueden seguir escribiendo directamente proveedores manuales command/args.

Actualmente solo se admiten preajustes source: "exec". command debe ser ${node} y args[0] debe ser un script de resolución ./ relativo a la raíz del plugin. OpenClaw lo materializa durante el inicio o la recarga como el ejecutable actual de Node y la ruta absoluta del script dentro del plugin. Las opciones de Node como --require, --import, --loader, --env-file, --eval y --print no forman parte del contrato de preajustes del manifiesto. Los operadores que necesiten comandos que no sean de Node pueden configurar directamente proveedores de ejecución manuales independientes.

OpenClaw obtiene trustedDirs para los preajustes del manifiesto a partir de la raíz del plugin y, para los preajustes ${node}, del directorio actual del ejecutable de Node. Los trustedDirs definidos en el manifiesto se ignoran. Otras opciones del proveedor de ejecución, como timeoutMs, noOutputTimeoutMs, maxOutputBytes, jsonOnly, env, passEnv y allowInsecurePath, se transfieren a la configuración normal del proveedor de ejecución SecretRef.

Referencia de modelPricing

Use modelPricing cuando un proveedor necesite controlar el comportamiento de precios del plano de control antes de cargar el entorno de ejecución. La caché de precios del Gateway lee estos metadatos sin importar el código del entorno de ejecución del proveedor.

{  "providers": ["ollama", "openrouter"],  "modelPricing": {    "providers": {      "ollama": {        "external": false      },      "openrouter": {        "openRouter": {          "passthroughProviderModel": true        },        "liteLLM": false      }    }  }}

Campos del proveedor:

Campos de origen:

Índice de proveedores de OpenClaw

El Índice de proveedores de OpenClaw son metadatos de vista previa propiedad de OpenClaw para proveedores cuyos plugins quizá aún no estén instalados. No forma parte de un manifiesto de plugin. Los manifiestos de los plugins siguen siendo la autoridad para los plugins instalados. El Índice de proveedores es el contrato de respaldo interno que utilizarán las futuras superficies de proveedores instalables y de selección de modelos previa a la instalación cuando no esté instalado un plugin de proveedor.

Orden de autoridad del catálogo:

1. Configuración del usuario.
2. modelCatalog del manifiesto del plugin instalado.
3. Caché del catálogo de modelos procedente de una actualización explícita.
4. Filas de vista previa del Índice de proveedores de OpenClaw.

El índice de proveedores no debe contener secretos, estado habilitado, hooks de runtime ni datos activos de modelos específicos de una cuenta. Sus catálogos de vista previa usan la misma forma de fila de proveedor modelCatalog que los manifiestos de plugins, pero deben limitarse a metadatos de visualización estables, salvo que campos del adaptador de runtime como api, baseUrl, precios o indicadores de compatibilidad se mantengan intencionadamente alineados con el manifiesto del plugin instalado. Los proveedores con detección activa de /models deben escribir las filas actualizadas mediante la ruta explícita de caché del catálogo de modelos, en lugar de hacer que el listado normal o la incorporación llamen a las API del proveedor.

Las entradas del índice de proveedores también pueden incluir metadatos de plugins instalables para proveedores cuyo plugin se haya trasladado fuera del núcleo o que aún no esté instalado por algún otro motivo. Estos metadatos siguen el patrón del catálogo de canales: el nombre del paquete, la especificación de instalación de npm, la integridad esperada y etiquetas sencillas de opciones de autenticación bastan para mostrar una opción de configuración instalable. Una vez instalado el plugin, prevalece su manifiesto y se ignora la entrada del índice de proveedores correspondiente a ese proveedor.

openclaw doctor --fix migra un conjunto pequeño y cerrado de claves de capacidades heredadas del nivel superior del manifiesto a contracts.*: speechProviders, mediaUnderstandingProviders, imageGenerationProviders y tools. Ninguna de ellas (ni ninguna otra lista de capacidades) se lee ya como campo del nivel superior del manifiesto; la carga normal de manifiestos solo las reconoce bajo contracts.

Manifiesto frente a package.json

Los dos archivos cumplen funciones diferentes:

Si no se sabe con certeza dónde corresponde un elemento de metadatos, debe aplicarse esta regla:

• si OpenClaw debe conocerlo antes de cargar el código del plugin, debe colocarse en openclaw.plugin.json
• si está relacionado con el empaquetado, los archivos de entrada o el comportamiento de instalación de npm, debe colocarse en package.json

Campos de package.json que afectan a la detección

Algunos metadatos de plugins anteriores al runtime se encuentran intencionadamente en package.json, bajo el bloque openclaw, en lugar de en openclaw.plugin.json. openclaw.bundle y openclaw.bundle.json no son contratos de plugins de OpenClaw; los plugins nativos deben usar openclaw.plugin.json junto con los campos package.json#openclaw compatibles que se indican a continuación.

Ejemplos importantes:

Los metadatos del manifiesto determinan qué opciones de proveedor, canal y configuración aparecen durante la incorporación antes de cargar el runtime. package.json#openclaw.install indica a la incorporación cómo obtener o habilitar ese plugin cuando se selecciona una de esas opciones. No deben trasladarse las indicaciones de instalación a openclaw.plugin.json.

Para openclaw.channel.cliAddOptions, debe usarse la sintaxis de opciones largas de Commander, como --initial-sync-limit <n>. Debe establecerse valueType: "int" para analizar un entero no negativo o valueType: "list" para dividir una entrada delimitada por comas, puntos y comas o saltos de línea en cadenas antes de que la reciba el adaptador de configuración del plugin. Debe omitirse valueType para transmitir sin cambios el valor analizado por Commander.

openclaw.install.minHostVersion se aplica durante la instalación y la carga del registro de manifiestos para fuentes de plugins no incluidos. Los valores no válidos se rechazan; los valores válidos pero más recientes hacen que se omitan los plugins externos en hosts anteriores. Se presupone que los plugins de origen incluidos tienen la misma versión que el checkout del host.

openclaw.install.requiredPlatformPackages está destinado a paquetes npm que exponen los binarios nativos necesarios mediante alias opcionales específicos de cada plataforma. Debe indicarse el nombre simple del paquete npm para cada alias de plataforma compatible. Durante la instalación de npm, OpenClaw solo verifica el alias declarado cuyas restricciones del archivo de bloqueo coincidan con el host actual. Si npm informa de que la operación se completó correctamente, pero omite ese alias, OpenClaw vuelve a intentarlo una vez con una caché nueva y revierte la instalación si el alias continúa ausente.

openclaw.compat.pluginApi se aplica durante la instalación de paquetes para fuentes de plugins no incluidos. Debe usarse para indicar el límite inferior de la API del SDK/runtime de plugins de OpenClaw con la que se compiló el paquete. Puede ser más estricto que minHostVersion cuando un paquete de plugin necesita una API más reciente, pero mantiene una indicación de instalación inferior para otros flujos. De forma predeterminada, la sincronización de versiones oficiales de OpenClaw eleva los límites inferiores existentes de la API de los plugins oficiales a la versión de OpenClaw, pero las versiones exclusivas de plugins pueden mantener un límite inferior cuando el paquete admite intencionadamente hosts anteriores. No debe usarse únicamente la versión del paquete como contrato de compatibilidad. peerDependencies.openclaw sigue siendo un metadato de paquete npm; OpenClaw utiliza el contrato openclaw.compat.pluginApi para tomar decisiones de compatibilidad de instalación.

Los metadatos oficiales de instalación bajo demanda deben usar clawhubSpec cuando el plugin esté publicado en ClawHub; la incorporación lo considera la fuente remota preferida y registra los datos del artefacto de ClawHub después de la instalación. npmSpec sigue siendo la alternativa de compatibilidad para los paquetes que todavía no se han trasladado a ClawHub.

La fijación exacta de versiones de npm ya se encuentra en npmSpec; por ejemplo, "npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3". Las entradas oficiales de catálogos externos deben asociar especificaciones exactas con expectedIntegrity para que los flujos de actualización fallen de forma segura si el artefacto de npm obtenido ya no coincide con la versión fijada. Para mantener la compatibilidad, la incorporación interactiva sigue ofreciendo especificaciones de npm procedentes de registros de confianza, incluidos nombres de paquetes simples y etiquetas de distribución. Los diagnósticos del catálogo pueden distinguir entre fuentes exactas, variables, fijadas por integridad, sin integridad, con discrepancia del nombre del paquete y con una opción predeterminada no válida. También advierten cuando expectedIntegrity está presente, pero no existe una fuente de npm válida que pueda fijar. Cuando expectedIntegrity está presente, los flujos de instalación y actualización lo aplican; cuando se omite, la resolución del registro se registra sin una fijación de integridad.

Los plugins de canales deben proporcionar openclaw.setupEntry cuando las exploraciones de estado, lista de canales o SecretRef necesiten identificar cuentas configuradas sin cargar el runtime completo. La entrada de configuración debe exponer los metadatos del canal, además de adaptadores de configuración, estado y secretos seguros para la configuración; los clientes de red, los listeners del Gateway y los runtimes de transporte deben mantenerse en el punto de entrada principal de la extensión.

Los campos del punto de entrada del entorno de ejecución no anulan las comprobaciones de los límites del paquete para los campos del punto de entrada de origen. Por ejemplo, openclaw.runtimeExtensions no puede hacer que se pueda cargar una ruta openclaw.extensions que salga del paquete.

openclaw.install.allowInvalidConfigRecovery es intencionadamente limitado. No permite instalar configuraciones dañadas arbitrarias. Actualmente, solo permite que los flujos de instalación se recuperen de determinados fallos de actualización obsoletos de plugins incluidos, como la ausencia de una ruta de un plugin incluido o una entrada channels.<id> obsoleta para ese mismo plugin incluido. Los errores de configuración no relacionados siguen bloqueando la instalación y remiten a los operadores a openclaw doctor --fix.

openclaw.channel.persistedAuthState son metadatos de paquete para un pequeño módulo de comprobación:

{  "openclaw": {    "channel": {      "id": "whatsapp",      "persistedAuthState": {        "specifier": "./auth-presence",        "exportName": "hasAnyWhatsAppAuth"      }    }  }}

Se usa cuando los flujos de configuración, Doctor, estado o comprobación de presencia de solo lectura necesitan una consulta rápida de autenticación de tipo sí/no antes de que se cargue el plugin completo del canal. El estado de autenticación persistente no es el estado configurado del canal: no se deben usar estos metadatos para activar plugins automáticamente, reparar dependencias del entorno de ejecución ni decidir si debe cargarse el entorno de ejecución de un canal. La exportación de destino debe ser una función pequeña que solo lea el estado persistente; no se debe encaminar a través del barrel completo del entorno de ejecución del canal.

openclaw.channel.configuredState admite comprobaciones rápidas de configuración. Se deben preferir los metadatos declarativos de entorno cuando las variables de entorno sean suficientes:

{  "openclaw": {    "channel": {      "id": "telegram",      "configuredState": {        "env": {          "allOf": ["TELEGRAM_BOT_TOKEN"]        }      }    }  }}

Se usa env.allOf cuando se requieren todas las variables enumeradas y env.anyOf cuando basta con cualquier variable no vacía. Si una pequeña comprobación ajena al entorno de ejecución necesita más que metadatos de entorno, se usan specifier y exportName, como se muestra para persistedAuthState; cuando está presente env, OpenClaw lo usa sin cargar ese módulo. Si la comprobación necesita la resolución completa de la configuración o el entorno de ejecución real del canal, esa lógica debe mantenerse en el hook config.hasConfiguredState del plugin.

Precedencia de descubrimiento (identificadores de plugin duplicados)

OpenClaw descubre plugins en tres raíces, comprobadas en este orden: los plugins incluidos distribuidos con OpenClaw, la raíz de instalación global (~/.openclaw/extensions) y la raíz del espacio de trabajo actual (<workspace>/.openclaw/extensions), además de cualquier entrada plugins.load.paths explícita.

Si dos descubrimientos comparten el mismo id, solo se conserva el manifiesto con la mayor precedencia; los duplicados con menor precedencia se descartan en lugar de cargarse junto a él. Precedencia, de mayor a menor:

1. Seleccionado por la configuración — una ruta fijada explícitamente en plugins.entries.<id>
2. Instalación global que coincide con un registro de instalación rastreado — un plugin instalado mediante openclaw plugin install/openclaw plugin update que el seguimiento de instalaciones de OpenClaw reconoce para ese mismo identificador, incluso cuando el identificador también pertenece a un plugin incluido
3. Incluido — plugins distribuidos con OpenClaw
4. Espacio de trabajo — plugins descubiertos en relación con el espacio de trabajo actual
5. Cualquier otro candidato descubierto

Implicaciones:

• Una bifurcación o copia obsoleta de un plugin incluido que se encuentre sin rastrear en el espacio de trabajo o en la raíz global no sustituirá a la compilación incluida.
• Para sustituir un plugin incluido, se debe ejecutar openclaw plugin install para ese identificador, de modo que la instalación global rastreada tenga prioridad sobre la copia incluida, o fijar una ruta específica mediante plugins.entries.<id> para que prevalezca por la precedencia de selección mediante configuración.
• Los descartes de duplicados se registran para que Doctor y los diagnósticos de inicio puedan señalar la copia descartada.
• Las sustituciones de duplicados seleccionadas por la configuración se describen como sustituciones explícitas en los diagnósticos, pero aun así generan una advertencia para que las bifurcaciones obsoletas y las sustituciones accidentales sigan siendo visibles.

Requisitos de JSON Schema

• Todos los plugins deben incluir un JSON Schema, aunque no acepten ninguna configuración.
• Se acepta un esquema vacío (por ejemplo, { "type": "object", "additionalProperties": false }).
• Los esquemas se validan al leer o escribir la configuración, no durante la ejecución.
• Al ampliar o bifurcar un plugin incluido con nuevas claves de configuración, se debe actualizar al mismo tiempo el openclaw.plugin.json configSchema de ese plugin. Los esquemas de los plugins incluidos son estrictos, por lo que añadir plugins.entries.<id>.config.myNewKey a la configuración del usuario sin añadir myNewKey a configSchema.properties se rechazará antes de que se cargue el entorno de ejecución del plugin.

Ejemplo de ampliación del esquema:

{  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "myNewKey": {        "type": "string"      }    }  }}

Comportamiento de la validación

• Las claves channels.* desconocidas son errores, salvo que el identificador del canal esté declarado en el manifiesto de un plugin. Si el mismo identificador también aparece en plugins.allow, plugins.entries o plugins.installs (un plugin al que se hace referencia pero que no se puede descubrir actualmente), OpenClaw lo rebaja a una advertencia.
• Las referencias de plugins.entries.<id>, plugins.allow y plugins.deny a identificadores de plugins desconocidos son advertencias ("se ignora una entrada de configuración obsoleta"), no errores, para que las actualizaciones y los plugins eliminados o renombrados no bloqueen el inicio del Gateway.
• La referencia de plugins.slots.memory a un identificador de plugin desconocido es un error, excepto en el caso del plugin externo oficial conocido memory-lancedb, que genera una advertencia.
• Si un plugin está instalado, pero tiene un manifiesto o esquema dañado o ausente, la validación falla y Doctor informa del error del plugin.
• Si existe configuración del plugin, pero este está desactivado, la configuración se conserva y se muestra una advertencia en Doctor y en los registros.

Consulte la referencia de configuración para ver el esquema completo de plugins.*.

Notas

• El manifiesto es obligatorio para los plugins nativos de OpenClaw, incluidas las cargas desde el sistema de archivos local. El entorno de ejecución sigue cargando el módulo del plugin por separado; el manifiesto solo se usa para el descubrimiento y la validación.
• Los manifiestos nativos se analizan con JSON5, por lo que se aceptan comentarios, comas finales y claves sin comillas, siempre que el valor final siga siendo un objeto.
• El cargador de manifiestos solo lee los campos de manifiesto documentados. Se deben evitar las claves personalizadas de nivel superior.
• channels, providers, cliBackends y skills pueden omitirse cuando un plugin no los necesita.
• providerCatalogEntry debe seguir siendo ligero y no debe importar grandes cantidades de código del entorno de ejecución; se debe usar para metadatos estáticos del catálogo de proveedores o descriptores de descubrimiento específicos, no para la ejecución durante las solicitudes.
• Los tipos de plugins exclusivos se seleccionan mediante plugins.slots.*: kind: "memory" mediante plugins.slots.memory (valor predeterminado: memory-core), y kind: "context-engine" mediante plugins.slots.contextEngine (valor predeterminado: legacy).
• El tipo de plugin exclusivo se declara en este manifiesto. El OpenClawPluginDefinition.kind del punto de entrada del entorno de ejecución está obsoleto y se conserva únicamente como alternativa de compatibilidad para plugins antiguos.
• Los metadatos de variables de entorno de setup.providers[].envVars son únicamente declarativos. El estado, la auditoría, la validación de entregas de Cron y otras superficies de solo lectura siguen aplicando la confianza del plugin y la política de activación efectiva antes de considerar configurada una variable de entorno.
• Para consultar los metadatos del asistente del entorno de ejecución que requieren código del proveedor, consulte los hooks del entorno de ejecución del proveedor.
• Si el plugin depende de módulos nativos, se deben documentar los pasos de compilación y los requisitos de listas de permitidos del gestor de paquetes (por ejemplo, pnpm allow-build-scripts + pnpm rebuild <package>).

Contenido relacionado