Manifiesto del Plugin

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

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 de openclaw.plugin.json que aparece a continuación. En un paquete compatible, 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 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. Si el manifiesto falta o no es válido, se bloquea la validación de la configuración y se considera un error del Plugin.

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

Qué hace este archivo

openclaw.plugin.json contiene metadatos que OpenClaw lee antes de cargar el código de tu Plugin. Todo su contenido debe poder inspeccionarse con un coste lo bastante bajo como para no tener que iniciar el entorno de ejecución del Plugin.

Úsalo para:

• la identidad del Plugin, la validación de la configuración y las indicaciones de la interfaz de configuración
• los metadatos de autenticación, incorporación y configuración inicial (alias, habilitación automática, variables de entorno del proveedor y opciones de autenticación)
• las indicaciones de activación para las superficies del plano de control
• la asignación abreviada de familias de modelos
• las instantáneas estáticas de propiedad de capacidades (contracts)
• los metadatos del ejecutor de control de calidad que puede inspeccionar el host compartido de openclaw qa
• los metadatos de configuración específicos del canal que se combinan en las superficies de catálogo y validación

No lo uses para: registrar comportamiento en tiempo de ejecución, declarar puntos de entrada de código ni definir metadatos de instalación de npm. Estos corresponden al código de tu Plugin y a package.json.

Ejemplo mínimo

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

Ejemplo completo

{  "id": "openrouter",  "name": "OpenRouter",  "description": "OpenRouter provider plugin",  "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"  },  "channelEnvVars": {    "openrouter-chatops": ["OPENROUTER_CHATOPS_TOKEN"]  },  "providerAuthChoices": [    {      "provider": "openrouter",      "method": "api-key",      "choiceId": "openrouter-api-key",      "choiceLabel": "OpenRouter API key",      "groupId": "openrouter",      "groupLabel": "OpenRouter",      "optionKey": "openrouterApiKey",      "cliFlag": "--openrouter-api-key",      "cliOption": "--openrouter-api-key <key>",      "cliDescription": "OpenRouter API key",      "onboardingScopes": ["text-inference"]    }  ],  "uiHints": {    "apiKey": {      "label": "API key",      "placeholder": "sk-or-v1-...",      "sensitive": true    }  },  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "apiKey": {        "type": "string"      }    }  }}

Referencia de campos de nivel superior

referencia de catalog

catalog proporciona indicaciones opcionales de visualización para los exploradores de plugins. Los hosts pueden ignorar estas indicaciones. Nunca instalan ni habilitan el plugin, y no cambian 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 decidir si un proveedor de generación está disponible sin importar todos los plugins de proveedores.

Use estos campos únicamente para datos declarativos que sean económicos de evaluar. 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 de configSignals admite:

Cada restricción mode admite:

Cada entrada de authSignals admite:

Cada restricción providerBaseUrl admite:

referencia de metadatos de herramientas

toolMetadata utiliza las mismas estructuras de 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 económicas de evaluar 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 de toolMetadata también aceptan optional (marca la herramienta como no obligatoria para activar el plugin) y replaySafe (marca la ejecución de la herramienta como segura para repetirla después de 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 dependa de la autenticación o la 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 de providerAuthChoices describe una opción de incorporación o autenticación. OpenClaw la lee 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.

Referencia de commandAliases

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

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

Referencia de activation

Use activation cuando el plugin pueda declarar de forma económica qué eventos del plano de control deben incluirlo en un plan de activación o carga.

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

Prefiera los metadatos más específicos que ya describan la propiedad. Use providers, channels, commandAliases, los descriptores de configuración o contracts cuando esos campos expresen la relación. Use activation para indicaciones adicionales del planificador que no puedan representarse mediante esos campos de propiedad. Use cliBackends en el nivel superior para alias del tiempo de ejecución de la CLI como claude-cli, my-cli o google-gemini-cli; activation.onAgentHarnesses solo se utiliza para los id. de arneses de agentes integrados que aún no tengan un campo de propiedad.

Cada plugin debe establecer activation.onStartup de forma intencionada. Establézcalo en true solo cuando el plugin deba ejecutarse durante el inicio del Gateway. Establézcalo en false cuando el plugin esté inactivo al iniciarse y solo deba cargarse mediante activadores más específicos. Omitir onStartup ya no hace que el plugin se cargue implícitamente durante el inicio; use 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 utiliza activation.onStartup para la importación explícita durante el inicio.
• La planificación de la CLI activada por comandos recurre a los valores heredados commandAliases[].cliCommand o commandAliases[].name.
• La planificación del inicio del tiempo de ejecución de agentes utiliza activation.onAgentHarnesses para los arneses integrados y cliBackends[] en el nivel superior para los alias del tiempo de ejecución de la CLI.
• La planificación de configuración o canales activada 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 utiliza 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 configuración o tiempo de ejecución activada por proveedores recurre a la propiedad heredada de providers[] y cliBackends[] en el 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 de la alternativa basada en la propiedad del manifiesto. Por ejemplo, activation-command-hint significa que coincidió activation.onCommands, mientras que manifest-command-alias significa que el planificador utilizó en su lugar la propiedad de commandAliases. Estas etiquetas de motivo se usan en 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 más ejecutores de transporte bajo la raíz compartida openclaw qa. Mantenga estos metadatos ligeros y estáticos; el tiempo de ejecución del plugin sigue siendo responsable del registro real en la CLI mediante una superficie ligera runtime-api.ts que exporta los valores qaRunnerCliRegistrations correspondientes. Una adapterFactory opcional expone el transporte a escenarios compartidos de control de calidad sin cambiar el ejecutor del comando registrado.

{  "qaRunners": [    {      "commandName": "matrix",      "description": "Run the Docker-backed Matrix live QA lane against a disposable homeserver"    }  ]}

El id de 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 económicos, 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": "openai local credentials"          }        ]      }    ],    "cliBackends": ["openai-cli"],    "configMigrations": ["legacy-openai-auth"],    "requiresRuntime": false  }}

El 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 setup para los flujos del plano de control y de configuración que deben limitarse a metadatos.

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

OpenClaw también incluye setup.providers[].envVars en las consultas genéricas de autenticación del proveedor y de variables de entorno. providerAuthEnvVars continúa siendo compatible mediante un adaptador de compatibilidad durante el período de obsolescencia, pero los plugins no incluidos que aún lo utilizan reciben un diagnóstico del manifiesto. Los plugins nuevos deben incluir los metadatos de variables de entorno de configuración y estado en setup.providers[].envVars.

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 sandbox y la depuració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 de configuración sencillas 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 la configuración. Las entradas explícitas de providerAuthChoices siguen teniendo preferencia para etiquetas personalizadas, flags de la CLI, el ámbito de incorporación y los metadatos del asistente.

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

Dado que la consulta de configuración puede ejecutar código de setup-api propiedad del plugin, los valores normalizados de setup.providers[].id y setup.cliBackends[] deben ser únicos entre los plugins descubiertos. Ante una propiedad ambigua, el proceso falla de forma cerrada en lugar de elegir un ganador según el orden de descubrimiento.

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

referencia de setup.providers

authEvidence sirve para los marcadores locales de credenciales propiedad del proveedor que pueden verificarse sin cargar código del entorno de ejecución. Estas comprobaciones deben seguir siendo económicas y locales: sin llamadas de red, lecturas del llavero o del gestor de secretos, comandos de shell ni sondeos de la API del proveedor.

Entradas de evidencia compatibles:

campos de setup

referencia de uiHints

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

{  "uiHints": {    "apiKey": {      "label": "API key",      "help": "Used for OpenRouter requests",      "placeholder": "sk-or-v1-...",      "sensitive": true    }  }}

Cada indicación de campo puede incluir:

referencia de contracts

Use contracts únicamente para metadatos estáticos de propiedad 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 integradas exclusivas del servidor de aplicaciones Codex. En su lugar, las transformaciones integradas 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 solo cuando esté habilitado explícitamente y únicamente para los entornos de ejecución que declaren en contracts.agentToolResultMiddleware.

Los Plugins instalados que necesiten el nivel de políticas de confianza previas a las herramientas del host deben declarar cada identificador local registrado en contracts.trustedToolPolicies y estar habilitados explícitamente. Los Plugins integrados 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 están limitados al ámbito del 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. La detección de herramientas usa esta lista para cargar únicamente los entornos de ejecución de Plugins que pueden ser propietarios de las herramientas solicitadas.

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

Los Plugins de proveedores que implementen tanto resolveUsageAuth como fetchUsageSnapshot deben declarar en contracts.usageProviders cada identificador de proveedor detectado automáticamente. La detección de uso lee este contrato antes de cargar el código de tiempo de ejecución y, después de cargar únicamente 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 de proveedores de embeddings.

Los proveedores de trabajadores deben declarar en contracts.workerProviders cada identificador de api.registerWorkerProvider(...). 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 la misma concesión. El núcleo también conserva esa instantánea de configuración validada y la pasa junto con leaseId a inspect({ leaseId, profile }) y destroy({ leaseId, profile }), incluso después de cambiar o eliminar el perfil especificado. La destrucción es idempotente, la inspección devuelve la unión cerrada de estados active / destroyed / unknown, y el material de las claves privadas 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 con el formato exacto algorithm base64, sin nombre de host ni comentario, para que el núcleo pueda fijar la identidad del host antes de conectarse. Los proveedores que generen referencias de identidad dinámicas pueden implementar el método autoritativo resolveSshIdentity({ leaseId, profile, keyRef }); los proveedores que no lo tengan usan el solucionador genérico de secretos del núcleo. Un resultado autoritativo unknown deja huérfano un registro local activo; después de una solicitud de destrucción conservada, confirma el desmantelamiento.

contracts.gatewayMethodDispatch acepta actualmente "authenticated-request". Es una barrera de higiene de la API para rutas HTTP nativas de Plugins que despachan deliberadamente métodos del plano de control del Gateway dentro del proceso, no un entorno aislado contra Plugins nativos maliciosos. Úselo solo para superficies integradas o de operadores sometidas a una revisión estricta que ya requieran autenticación HTTP del Gateway. Una ruta autorizada continúa accesible mientras la admisión de trabajo raíz del Gateway está cerrada solo cuando también declara auth: "gateway" y el valor específico de la ruta gatewayRuntimeScopeSurface: "trusted-operator"; 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 acotados fuera del despacho el análisis y la conformación de respuestas; el trabajo sustancial o que modifique datos 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 necesiten los asistentes 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": "apiKey",          "expected": "string"        }      ]    }  }}

Cada entrada de dangerousFlags admite:

secretInputs admite:

Referencia de mediaUnderstandingProviderMetadata

Use mediaUnderstandingProviderMetadata cuando un proveedor de comprensión multimedia tenga modelos predeterminados, prioridad de respaldo de autenticación automática o compatibilidad nativa con documentos que los auxiliares genéricos del núcleo necesiten antes de que se cargue 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 que se cargue el entorno de ejecución. La detección de configuración/estado del canal de solo lectura puede usar estos metadatos directamente para canales externos configurados cuando no haya una entrada de configuración disponible 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 en channels.<channel-id>. OpenClaw lee los metadatos del manifiesto para decidir 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 incluidos que declaren channels[] también deben declarar entradas channelConfigs correspondientes. Sin ellas, OpenClaw aún puede cargar el plugin, pero las superficies de esquema de configuración en ruta fría, configuración y Control UI no pueden conocer la forma de las opciones propiedad del canal hasta que se ejecute el entorno de ejecución del plugin.

channelConfigs.<channel-id>.commands.nativeCommandsAutoEnabled y nativeSkillsAutoEnabled pueden declarar valores predeterminados estáticos auto para comprobaciones de configuración de comandos que se ejecutan antes de cargar el entorno de ejecución del canal. Los canales incluidos también pueden publicar los mismos valores predeterminados mediante package.json#openclaw.channel.commands, junto con sus demás metadatos del 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 al 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 incluido o una bifurcación mantenida que conserva el mismo identificador de canal por compatibilidad de 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 identificador del canal como el identificador 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 prevaleciendo: si el usuario habilita explícitamente ambos plugins (mediante plugins.allow o una configuración sustancial de plugins.entries), OpenClaw conserva esa elección e informa de diagnósticos de canales/herramientas duplicados en lugar de cambiar silenciosamente el conjunto de plugins solicitado.

Limite preferOver a identificadores 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

Use modelSupport cuando OpenClaw deba inferir su plugin de proveedor a partir de identificadores 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 explícitas provider/model usan los metadatos del manifiesto de providers del propietario
• modelPatterns tiene precedencia sobre modelPrefixes
• si coinciden un plugin no incluido y uno incluido, prevalece el plugin no incluido
• la ambigüedad restante se ignora hasta que el usuario o la configuración especifiquen un proveedor

Campos:

Las entradas de modelPatterns se compilan mediante compileSafeRegex, que rechaza patrones que contengan 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 simples y evite los cuantificadores anidados.

Referencia de modelCatalog

Use modelCatalog cuando OpenClaw deba conocer los metadatos de modelos del proveedor antes de cargar el entorno de ejecución del plugin. Esta es la fuente propiedad del manifiesto para filas fijas del catálogo, alias de proveedores, reglas de supresión y 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": "no disponible en Azure OpenAI Responses"      }    ],    "discovery": {      "openai": "static"    }  }}

Campos de nivel superior:

aliases participa en la búsqueda de pertenencia de proveedores 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 usa un alias, OpenClaw puede leer el manifiesto propietario y aplicar las sustituciones de la API o de la URL base del alias sin cargar el entorno de ejecución del proveedor. Los alias no amplían los listados de catálogo sin filtrar; las listas generales solo incluyen las filas del proveedor canónico propietario.

suppressions sustituye al 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 está declarado como una clave de modelCatalog.aliases cuyo destino es 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 listas filtradas por proveedor y las superficies de selección omitan el descubrimiento del registro o del entorno de ejecución. Use refreshable cuando las filas del manifiesto sean semillas o complementos enumerables ú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, controlada por el proveedor, de identificadores de modelos que debe realizarse antes de cargar el entorno de ejecución del proveedor. Esto mantiene los alias, como los nombres abreviados de modelos, los identificadores locales heredados del proveedor y las reglas de prefijos de proxy, en el manifiesto del plugin propietario en lugar de 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 controlando el significado de cada endpointClass; los manifiestos de plugins controlan los metadatos del host y de la URL base.

Los plugins de proveedores externalizados oficialmente están excluidos de la distribución del núcleo, por lo que sus manifiestos no son visibles hasta que se instalan. Sus valores de providerEndpoints también deben replicarse 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 que la réplica esté sincronizada.

Campos del punto de conexión:

Referencia de providerRequest

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

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

Campos del proveedor:

Referencia de secretProviderIntegrations

Usa secretProviderIntegrations cuando un plugin pueda publicar una configuración predefinida reutilizable de proveedor exec de SecretRef. OpenClaw lee estos metadatos antes de cargar el entorno de ejecución del plugin, guarda la propiedad del plugin en secrets.providers.<alias>.pluginIntegration y deja la resolución efectiva de secretos al entorno de ejecución de SecretRef. Las configuraciones predefinidas solo se exponen para plugins incluidos y plugins instalados detectados 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 la integración. Si se omite providerAlias, OpenClaw usa el id. de la integración como alias del proveedor SecretRef. Los alias de proveedor deben coincidir con el patrón normal de alias de proveedor SecretRef, por ejemplo, team-secrets u onepassword-work.

Cuando un operador selecciona la configuración predefinida, OpenClaw escribe una referencia de proveedor como esta:

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

Al iniciar o recargar, 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 exec a partir del manifiesto. Deshabilitar o eliminar el plugin revoca el proveedor para las SecretRefs activas. Los operadores que quieran una configuración exec independiente aún pueden escribir directamente proveedores manuales con command/args.

Actualmente solo se admiten configuraciones predefinidas con source: "exec". command debe ser ${node} y args[0] debe ser un script de resolución con ruta relativa a la raíz del plugin que comience por ./. Al iniciar o recargar, OpenClaw lo materializa 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 configuraciones predefinidas del manifiesto. Los operadores que necesiten comandos que no sean de Node pueden configurar directamente proveedores exec manuales independientes.

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

Referencia de modelPricing

Usa modelPricing cuando un proveedor necesite controlar el comportamiento de precios del plano de control antes de que se cargue 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 la fuente:

Índice de proveedores de OpenClaw

El Índice de proveedores de OpenClaw contiene metadatos de vista previa propiedad de OpenClaw para proveedores cuyos plugins quizá aún no estén instalados. No forma parte del manifiesto de un plugin. Los manifiestos de plugins siguen siendo la fuente de autoridad para los plugins instalados. El Índice de proveedores es el contrato interno de respaldo que consumirán las futuras interfaces de proveedores instalables y de selección de modelos previa a la instalación cuando no esté instalado el plugin de un 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 de habilitación, hooks del entorno de ejecución ni datos de modelos específicos de cuentas activas. Sus catálogos de vista previa usan la misma estructura de fila de proveedor de modelCatalog que los manifiestos de plugins, pero deben limitarse a metadatos de presentación estables, salvo que los campos del adaptador del entorno de ejecución, como api, baseUrl, precios o indicadores de compatibilidad, se mantengan intencionadamente alineados con el manifiesto del plugin instalado. Los proveedores que permiten la detección en vivo mediante /models deben escribir las filas actualizadas a través de 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 aún no esté instalado por otro motivo. Estos metadatos reflejan 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 son suficientes 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 heredadas de capacidades del manifiesto de nivel superior a contracts.*: speechProviders, mediaUnderstandingProviders, imageGenerationProviders y tools. Ninguna de estas claves, ni ninguna otra lista de capacidades, se lee ya como campo de nivel superior del manifiesto; la carga normal del manifiesto solo las reconoce bajo contracts.

Manifiesto frente a package.json

Los dos archivos cumplen funciones diferentes:

Si no tienes claro dónde corresponde un metadato, usa esta regla:

• si OpenClaw debe conocerlo antes de cargar el código del plugin, colócalo en openclaw.plugin.json
• si se refiere al empaquetado, los archivos de entrada o el comportamiento de instalación de npm, colócalo en package.json

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

Algunos metadatos del plugin anteriores al entorno de ejecución se encuentran intencionadamente en package.json, dentro del bloque openclaw, en lugar de 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 compatibles de package.json#openclaw 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 entorno de ejecución. package.json#openclaw.install indica al proceso de incorporación cómo obtener o habilitar ese Plugin cuando el usuario elige una de esas opciones. No traslade las indicaciones de instalación a openclaw.plugin.json.

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 los plugins externos se omitan en hosts más antiguos. Se presupone que los plugins incluidos desde el código fuente comparten versión con el checkout del host.

openclaw.install.requiredPlatformPackages está destinado a paquetes npm que exponen binarios nativos obligatorios mediante alias opcionales específicos de cada plataforma. Enumere el nombre básico del paquete npm para cada alias de plataforma compatible. Durante la instalación con npm, OpenClaw verifica únicamente el alias declarado cuyas restricciones del archivo de bloqueo coinciden con el host actual. Si npm informa de que la operación se realizó correctamente pero omite ese alias, OpenClaw vuelve a intentarlo una vez con una caché nueva y revierte la instalación si el alias sigue ausente.

openclaw.compat.pluginApi se aplica durante la instalación de paquetes para fuentes de plugins no incluidos. Úselo para indicar el límite inferior de la API del SDK o del entorno de ejecución de plugins de OpenClaw con el 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 oficial de versiones de OpenClaw eleva los límites inferiores existentes de la API de los plugins oficiales a la versión de OpenClaw, pero las versiones que solo afectan a plugins pueden conservar un límite inferior cuando el paquete admite intencionadamente hosts más antiguos. No utilice únicamente la versión del paquete como contrato de compatibilidad. peerDependencies.openclaw continúa siendo un metadato del paquete npm; OpenClaw utiliza el contrato openclaw.compat.pluginApi para tomar decisiones sobre la compatibilidad de la instalación.

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

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

Los plugins de canal deben proporcionar openclaw.setupEntry cuando los análisis de estado, lista de canales o SecretRef necesiten identificar cuentas configuradas sin cargar el entorno de ejecución completo. El punto de 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; mantenga los clientes de red, los procesos de escucha del Gateway y los entornos de ejecución del transporte en el punto de entrada principal de la extensión.

Los campos de puntos de entrada del entorno de ejecución no anulan las comprobaciones de límites del paquete correspondientes a los campos de puntos de entrada del código fuente. Por ejemplo, openclaw.runtimeExtensions no puede hacer que sea cargable una ruta de openclaw.extensions que salga del paquete.

openclaw.install.allowInvalidConfigRecovery tiene un alcance intencionadamente limitado. No permite instalar configuraciones arbitrariamente dañadas. Actualmente, solo permite que los flujos de instalación se recuperen de determinados fallos obsoletos de actualización de plugins incluidos, como la ausencia de la ruta de un Plugin incluido o una entrada obsoleta channels.<id> correspondiente a 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 es un metadato de paquete para un módulo comprobador mínimo:

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

Úselo cuando los flujos de configuración, Doctor, estado o presencia de solo lectura necesiten una comprobación rápida de autenticación de tipo sí/no antes de que se cargue el Plugin de canal completo. El estado de autenticación persistido no es el estado configurado del canal: no utilice estos metadatos para habilitar 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 persistido; no la dirija a través del barrel del entorno de ejecución completo del canal.

openclaw.channel.configuredState sigue la misma estructura para comprobaciones rápidas de configuración basadas únicamente en el entorno:

{  "openclaw": {    "channel": {      "id": "telegram",      "configuredState": {        "specifier": "./configured-state",        "exportName": "hasTelegramConfiguredState"      }    }  }}

Úselo cuando un canal pueda determinar el estado configurado a partir del entorno o de otras entradas mínimas ajenas al entorno de ejecución. Si la comprobación requiere la resolución completa de la configuración o el entorno de ejecución real del canal, mantenga esa lógica en el hook config.hasConfiguredState del Plugin.

Precedencia del descubrimiento (identificadores de Plugin duplicados)

OpenClaw descubre plugins en tres raíces, que se comprueban en este orden: los plugins incluidos que se distribuyen 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 explícita de plugins.load.paths.

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

1. Seleccionado por 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 copia bifurcada u obsoleta de un Plugin incluido que se encuentre sin seguimiento en el espacio de trabajo o en la raíz global no sustituirá a la compilación incluida.
• Para sustituir un Plugin incluido, ejecute openclaw plugin install para ese identificador, de modo que la instalación global rastreada tenga prioridad sobre la copia incluida, o fije 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.
• En los diagnósticos, las sustituciones de duplicados seleccionadas mediante configuración se describen como sustituciones explícitas, pero siguen generando una advertencia para que las bifurcaciones obsoletas y las ocultaciones accidentales permanezcan visibles.

Requisitos de JSON Schema

• Cada plugin debe incluir un esquema JSON, aunque no acepte ninguna configuración.
• Se admite un esquema vacío (por ejemplo, { "type": "object", "additionalProperties": false }).
• Los esquemas se validan al leer o escribir la configuración, no en tiempo de ejecución.
• Al ampliar o bifurcar un plugin incluido para añadir nuevas claves de configuración, actualiza al mismo tiempo el configSchema de openclaw.plugin.json 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 de 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 detectar actualmente), OpenClaw lo reduce a una advertencia.
• Las referencias a identificadores de plugins desconocidos en plugins.entries.<id>, plugins.allow y plugins.deny son advertencias («se ignoró una entrada de configuración obsoleta»), no errores, para que las actualizaciones y los plugins eliminados o renombrados no impidan el inicio del Gateway.
• Si plugins.slots.memory hace referencia a un identificador de plugin desconocido, se produce un error, excepto en el caso del plugin externo oficial conocido memory-lancedb, para el cual se muestra una advertencia.
• Si hay un plugin instalado, pero su manifiesto o esquema falta o está dañado, la validación falla y Doctor informa del error del plugin.
• Si existe configuración para un plugin, pero este está deshabilitado, la configuración se conserva y se muestra una advertencia en Doctor y en los registros.

Consulta 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 utiliza para la detección y la validación.
• Los manifiestos nativos se analizan con JSON5, por lo que se permiten 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. Evita las claves personalizadas de nivel superior.
• channels, providers, cliBackends y skills pueden omitirse cuando un plugin no los necesita.
• providerCatalogEntry debe mantenerse ligero y no debería importar grandes cantidades de código del entorno de ejecución; úsalo para metadatos estáticos del catálogo de proveedores o descriptores de detección 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).
• Declara en este manifiesto el tipo de plugin exclusivo. OpenClawPluginDefinition.kind de la entrada del entorno de ejecución está obsoleto y se conserva únicamente como mecanismo de compatibilidad para plugins antiguos.
• Los metadatos de variables de entorno (setup.providers[].envVars, el obsoleto providerAuthEnvVars y channelEnvVars) son únicamente declarativos. El estado, la auditoría, la validación de la entrega de Cron y otras superficies de solo lectura siguen aplicando la política de confianza y activación efectiva del plugin antes de considerar configurada una variable de entorno.
• Para los metadatos del asistente en tiempo de ejecución que requieren código del proveedor, consulta los enlaces del entorno de ejecución del proveedor.
• Si tu plugin depende de módulos nativos, documenta los pasos de compilación y cualquier requisito de lista de permitidos del gestor de paquetes (por ejemplo, allow-build-scripts de pnpm y pnpm rebuild <package>).

Contenido relacionado