Manifiesto del Plugin

Esta página es solo para el manifiesto de Plugin nativo de OpenClaw.

Para diseños de paquetes compatibles, consulta Paquetes de Plugin.

Los formatos de paquete compatibles usan archivos de manifiesto diferentes:

• Paquete de Codex: .codex-plugin/plugin.json
• Paquete de Claude: .claude-plugin/plugin.json o el diseño predeterminado de componentes de Claude sin manifiesto
• Paquete de Cursor: .cursor-plugin/plugin.json

OpenClaw también detecta automáticamente esos diseños de paquete, pero no se validan contra el esquema openclaw.plugin.json descrito aquí.

Para paquetes compatibles, OpenClaw actualmente lee metadatos del paquete más las raíces de Skills declaradas, raíces de comandos de Claude, valores predeterminados de settings.json del paquete de Claude, valores predeterminados de LSP del paquete de Claude y paquetes de hooks compatibles cuando el diseño coincide con las expectativas del runtime de OpenClaw.

Cada Plugin nativo de OpenClaw debe incluir un archivo openclaw.plugin.json en la raíz del Plugin. OpenClaw usa este manifiesto para validar la configuración sin ejecutar código del Plugin. Los manifiestos faltantes o no válidos se tratan como errores de Plugin y bloquean la validación de la configuración.

Consulta la guía completa del sistema de Plugins: Plugins. Para el modelo de capacidades nativo y la guía actual de compatibilidad externa: Modelo de capacidades.

Qué hace este archivo

openclaw.plugin.json son los metadatos que OpenClaw lee antes de cargar tu código del Plugin. Todo lo siguiente debe ser lo suficientemente barato de inspeccionar sin arrancar el runtime del Plugin.

Úsalo para:

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

No lo uses para: registrar comportamiento en runtime, declarar entrypoints de código o metadatos de instalación de npm. Eso pertenece 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"],  "providerAuthEnvVars": {    "openrouter": ["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 metadatos del proveedor de generación

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

Usa estos campos solo para hechos baratos y declarativos. El transporte, las transformaciones de solicitudes, la actualizació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 guarda de mode admite:

Cada entrada de authSignals admite:

Cada guarda de providerBaseUrl admite:

Referencia de metadatos de herramientas

toolMetadata usa las mismas formas de configSignals y authSignals que los metadatos del proveedor de generación, indexadas por nombre de herramienta. contracts.tools declara propiedad. toolMetadata declara evidencia de disponibilidad barata para que OpenClaw pueda evitar importar un entorno de ejecución de Plugin solo para que su fábrica de herramientas devuelva null.

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

Si una herramienta no tiene toolMetadata, OpenClaw conserva el comportamiento existente y carga el Plugin propietario cuando el contrato de herramienta coincide con la política. Para herramientas de rutas críticas cuya fábrica depende de 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 preguntar.

Referencia de providerAuthChoices

Cada entrada de providerAuthChoices describe una opción de incorporación o autenticación. OpenClaw lee esto antes de que se cargue el entorno de ejecución del proveedor. Las listas de configuración de proveedores usan estas opciones del manifiesto, opciones de configuración derivadas del descriptor y metadatos del catálogo de instalación sin cargar el entorno de ejecución del proveedor.

Referencia de commandAliases

Usa commandAliases cuando un plugin posee un nombre de comando en tiempo de ejecución que los usuarios podrían poner por error en plugins.allow o intentar ejecutar como comando CLI raíz. OpenClaw usa estos metadatos para diagnósticos sin importar código de tiempo de ejecución del plugin.

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

referencia de activation

Usa activation cuando el plugin puede declarar de forma económica qué eventos del plano de control deberían incluirlo en un plan de activación/carga.

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

Prefiere los metadatos más acotados que ya describan la propiedad. Usa providers, channels, commandAliases, descriptores de setup o contracts cuando esos campos expresen la relación. Usa activation para indicaciones adicionales del planificador que no se puedan representar mediante esos campos de propiedad. Usa cliBackends de nivel superior para alias de tiempo de ejecución de CLI como claude-cli, codex-cli o google-gemini-cli; activation.onAgentHarnesses es solo para ids de harnesses de agente incrustados que aún no tengan un campo de propiedad.

Este bloque es solo metadatos. No registra comportamiento en tiempo de ejecución y no sustituye a register(...), setupEntry ni otros puntos de entrada de tiempo de ejecución/plugin. Los consumidores actuales lo usan como una indicación de acotación antes de una carga de plugins más amplia, por lo que la ausencia de metadatos de activación no relacionados con el arranque normalmente solo afecta al rendimiento; no debería cambiar la corrección mientras sigan existiendo los fallbacks de propiedad del manifiesto.

Cada plugin debería establecer activation.onStartup de forma intencional. Establécelo en true solo cuando el plugin deba ejecutarse durante el arranque del Gateway. Establécelo en false cuando el plugin esté inerte al arrancar y deba cargarse solo desde activadores más acotados. Omitir onStartup ya no carga implícitamente el plugin al arrancar; usa metadatos de activación explícitos para activadores de arranque, canal, configuración, harness de agente, memoria u otros activadores de activación más acotados.

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

Consumidores activos actuales:

• La planificación de arranque del Gateway usa activation.onStartup para una importación explícita al arranque
• La planificación de CLI activada por comandos recurre a los campos heredados commandAliases[].cliCommand o commandAliases[].name
• La planificación de arranque del tiempo de ejecución del agente usa activation.onAgentHarnesses para harnesses incrustados y cliBackends[] de nivel superior para alias de tiempo de ejecución de CLI
• La planificación de setup/canal activada por canal recurre a la propiedad heredada channels[] cuando faltan metadatos explícitos de activación de canal
• La planificación de plugins al arranque usa activation.onConfigPaths para superficies de configuración raíz que no son de canal, como el bloque browser del plugin de navegador incluido
• La planificación de setup/tiempo de ejecución activada por proveedor recurre a la propiedad heredada providers[] y cliBackends[] de nivel superior cuando faltan metadatos explícitos de activación de proveedor

Los diagnósticos del planificador pueden distinguir indicaciones de activación explícitas del fallback de propiedad del manifiesto. Por ejemplo, activation-command-hint significa que activation.onCommands coincidió, mientras que manifest-command-alias significa que el planificador usó en su lugar la propiedad de commandAliases. Estas etiquetas de motivo son para diagnósticos y pruebas del host; los autores de plugins deberían seguir declarando los metadatos que mejor describan la propiedad.

referencia de qaRunners

Usa qaRunners cuando un plugin contribuye uno o más runners de transporte bajo la raíz compartida openclaw qa. Mantén estos metadatos económicos y estáticos; el tiempo de ejecución del plugin sigue siendo responsable del registro real de CLI mediante una superficie ligera runtime-api.ts que exporta qaRunnerCliRegistrations.

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

referencia de setup

Usa setup cuando las superficies de setup y onboarding necesitan metadatos económicos propiedad del plugin antes de que se cargue el tiempo 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  }}

cliBackends de nivel superior sigue siendo válido y continúa describiendo backends de inferencia de CLI. setup.cliBackends es la superficie de descriptor específica de setup para flujos de plano de control/setup que deberían permanecer solo como metadatos.

Cuando están presentes, setup.providers y setup.cliBackends son la superficie preferida de búsqueda basada primero en descriptores para el descubrimiento de setup. Si el descriptor solo reduce el plugin candidato y el setup aún necesita hooks de tiempo de setup más completos, establece requiresRuntime: true y mantén setup-api como ruta de ejecución de fallback.

OpenClaw también incluye setup.providers[].envVars en búsquedas genéricas de autenticación de proveedor y variables de entorno. providerAuthEnvVars sigue siendo compatible mediante un adaptador de compatibilidad durante la ventana de obsolescencia, pero los plugins no incluidos que aún lo usan reciben un diagnóstico de manifiesto. Los plugins nuevos deberían poner los metadatos de entorno de setup/estado en setup.providers[].envVars.

OpenClaw también puede derivar opciones simples de setup desde setup.providers[].authMethods cuando no hay una entrada de setup disponible, o cuando setup.requiresRuntime: false declara que el tiempo de ejecución de setup no es necesario. Las entradas explícitas providerAuthChoices siguen siendo preferidas para etiquetas personalizadas, flags de CLI, alcance de onboarding y metadatos del asistente.

Establece requiresRuntime: false solo cuando esos descriptores sean suficientes para la superficie de setup. OpenClaw trata el false explícito como un contrato solo de descriptores y no ejecutará setup-api ni openclaw.setupEntry para la búsqueda de setup. Si un plugin solo de descriptores aún incluye una de esas entradas de tiempo de ejecución de setup, OpenClaw informa un diagnóstico aditivo y continúa ignorándola. Omitir requiresRuntime mantiene el comportamiento de fallback heredado para que los plugins existentes que agregaron descriptores sin el flag no se rompan.

Como la búsqueda de setup puede ejecutar código setup-api propiedad del plugin, los valores normalizados de setup.providers[].id y setup.cliBackends[] deben permanecer únicos entre los plugins descubiertos. La propiedad ambigua falla de forma cerrada en lugar de elegir un ganador según el orden de descubrimiento.

Cuando el tiempo de ejecución de setup sí se ejecuta, los diagnósticos del registro de setup informan desviación de descriptores si setup-api registra un proveedor o backend de CLI que los descriptores del manifiesto no declaran, o si un descriptor no tiene registro de tiempo de ejecución coincidente. Estos diagnósticos son aditivos y no rechazan plugins heredados.

referencia de setup.providers

authEvidence es para marcadores de credenciales locales propiedad del proveedor que se pueden verificar sin cargar código de tiempo de ejecución. Estas comprobaciones deben seguir siendo baratas y locales: sin llamadas de red, sin lecturas de llavero ni de gestores de secretos, sin comandos de shell y sin sondeos de API del proveedor.

Entradas de evidencia admitidas:

Campos de setup

Referencia de uiHints

uiHints es un mapa de nombres de campos de configuración a pequeñas indicaciones de renderizado.

{  "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

Usa contracts solo para metadatos estáticos de propiedad de capacidades que OpenClaw pueda leer sin importar el tiempo de ejecución del plugin.

{  "contracts": {    "agentToolResultMiddleware": ["pi", "codex"],    "externalAuthProviders": ["acme-ai"],    "speechProviders": ["openai"],    "realtimeTranscriptionProviders": ["openai"],    "realtimeVoiceProviders": ["openai"],    "memoryEmbeddingProviders": ["local"],    "mediaUnderstandingProviders": ["openai", "openai-codex"],    "imageGenerationProviders": ["openai"],    "videoGenerationProviders": ["qwen"],    "webFetchProviders": ["firecrawl"],    "webSearchProviders": ["gemini"],    "migrationProviders": ["hermes"],    "tools": ["firecrawl_search", "firecrawl_scrape"]  }}

Cada lista es opcional:

contracts.embeddedExtensionFactories se conserva para fábricas de extensiones incluidas solo del servidor de aplicaciones de Codex. Las transformaciones incluidas de resultados de herramientas deben declarar contracts.agentToolResultMiddleware y registrarse con api.registerAgentToolResultMiddleware(...) en su lugar. Los plugins externos no pueden registrar middleware de resultados de herramientas porque la costura puede reescribir salidas de herramientas de alta confianza antes de que el modelo las vea.

Los registros de tiempo de ejecución api.registerTool(...) deben coincidir con contracts.tools. La detección de herramientas usa esta lista para cargar solo los tiempos de ejecución de plugins que pueden ser propietarios de las herramientas solicitadas.

Los plugins de proveedor que implementan resolveExternalAuthProfiles deben declarar contracts.externalAuthProviders. Los plugins sin la declaración todavía se ejecutan mediante una alternativa de compatibilidad obsoleta, pero esa alternativa es más lenta y se eliminará después de la ventana de migración.

Los proveedores incluidos de embeddings de memoria deben declarar contracts.memoryEmbeddingProviders para cada id de adaptador que expongan, incluidos adaptadores integrados como local. Las rutas de CLI independientes usan este contrato de manifiesto para cargar solo el plugin propietario antes de que el tiempo de ejecución completo del Gateway haya registrado proveedores.

Referencia de mediaUnderstandingProviderMetadata

Usa mediaUnderstandingProviderMetadata cuando un proveedor de comprensión de medios tenga modelos predeterminados, prioridad de alternativa de autenticación automática o compatibilidad nativa con documentos que los ayudantes genéricos del núcleo necesiten antes de que se cargue el tiempo 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"]    }  }}

Cada entrada de proveedor puede incluir:

Referencia de channelConfigs

Usa channelConfigs cuando un plugin de canal necesite metadatos de configuración baratos antes de que se cargue el tiempo de ejecución. La detección de configuración/estado de canal de solo lectura puede usar estos metadatos directamente para canales externos configurados cuando no hay ninguna entrada de setup disponible, o cuando setup.requiresRuntime: false declara que el tiempo de ejecución de setup no es necesario.

channelConfigs son metadatos de manifiesto del plugin, no una nueva sección de configuración de usuario de nivel superior. Los usuarios todavía configuran instancias de canal en channels.<channel-id>. OpenClaw lee los metadatos del manifiesto para decidir qué plugin es propietario de ese canal configurado antes de que se ejecute el código de tiempo 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 declaran channels[] también deben declarar entradas channelConfigs coincidentes. Sin ellas, OpenClaw todavía puede cargar el plugin, pero las superficies de esquema de configuración de ruta fría, setup y UI de Control no pueden conocer la forma de las opciones propiedad del canal hasta que se ejecute el tiempo 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 que se cargue el tiempo 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 otros metadatos de catálogo de canales propiedad del paquete.

{  "channelConfigs": {    "matrix": {      "schema": {        "type": "object",        "additionalProperties": false,        "properties": {          "homeserverUrl": { "type": "string" }        }      },      "uiHints": {        "homeserverUrl": {          "label": "Homeserver URL",          "placeholder": "https://matrix.example.com"        }      },      "label": "Matrix",      "description": "Matrix homeserver connection",      "commands": {        "nativeCommandsAutoEnabled": true,        "nativeSkillsAutoEnabled": true      },      "preferOver": ["matrix-legacy"]    }  }}

Cada entrada de canal puede incluir:

Reemplazo de otro Plugin de canal

Usa preferOver cuando tu Plugin sea el propietario preferido para un id de canal que otro Plugin también puede proporcionar. Los casos comunes son un id de Plugin renombrado, un Plugin independiente que sustituye a un Plugin incluido, o una bifurcación mantenida que conserva el mismo id 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 channels.chat está configurado, OpenClaw considera tanto el id de canal como el id de 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 de runtime para que un Plugin sea propietario del canal y sus herramientas. La selección explícita del usuario sigue prevaleciendo: si el usuario habilita explícitamente ambos plugins, OpenClaw conserva esa elección y reporta diagnósticos de canales/herramientas duplicados en lugar de cambiar silenciosamente el conjunto de plugins solicitado.

Mantén preferOver limitado a ids de plugins que realmente puedan proporcionar el mismo canal. No es un campo de prioridad general y no renombra las claves de configuración del usuario.

Referencia de modelSupport

Usa modelSupport cuando OpenClaw deba inferir tu Plugin de proveedor a partir de ids de modelo abreviados como gpt-5.5 o claude-sonnet-4.6 antes de que cargue el runtime 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 providers propietario
• modelPatterns tiene prioridad sobre modelPrefixes
• si un Plugin no incluido y un Plugin incluido coinciden, gana el Plugin no incluido
• la ambigüedad restante se ignora hasta que el usuario o la configuración especifique un proveedor

Campos:

Referencia de modelCatalog

Usa modelCatalog cuando OpenClaw deba conocer los metadatos de modelos del proveedor antes de cargar el runtime del Plugin. Esta es la fuente propiedad del manifiesto para filas de catálogo fijas, alias de proveedor, reglas de supresión y modo de descubrimiento. La actualización en runtime sigue perteneciendo al código de runtime del proveedor, pero el manifiesto indica al núcleo cuándo se requiere el runtime.

{  "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 de proveedor para la planificación de catálogos de modelos. Los destinos de alias deben ser proveedores de nivel superior propiedad del mismo Plugin. Cuando una lista filtrada por proveedor usa un alias, OpenClaw puede leer el manifiesto propietario y aplicar sobrescrituras de API/URL base del alias sin cargar el runtime del proveedor. Los alias no expanden los listados de catálogo sin filtrar; las listas amplias emiten solo las filas del proveedor canónico propietario.

suppressions reemplaza el antiguo hook de runtime de proveedor suppressBuiltInModel. Las entradas de supresión se respetan solo cuando el proveedor es propiedad del Plugin o se declara como una clave modelCatalog.aliases que apunta a un proveedor propio. Los hooks de supresión de runtime ya no se llaman durante la resolución de modelos.

Campos del proveedor:

Campos del modelo:

Campos de supresión:

No pongas datos exclusivos de tiempo de ejecución en modelCatalog. Usa static solo cuando las filas del manifiesto sean lo bastante completas para que las superficies de lista filtrada por proveedor y de selector omitan el descubrimiento del registro/tiempo de ejecución. Usa refreshable cuando las filas del manifiesto sean semillas listables útiles o complementos, pero una actualización/caché pueda agregar más filas más adelante; las filas actualizables no son autoritativas por sí solas. Usa runtime cuando OpenClaw deba cargar el tiempo de ejecución del proveedor para conocer la lista.

Referencia de modelIdNormalization

Usa modelIdNormalization para una limpieza económica de id de modelo propiedad del proveedor que debe ocurrir antes de que se cargue el tiempo de ejecución del proveedor. Esto mantiene alias como nombres de modelo cortos, id heredados locales del proveedor y reglas de prefijo de proxy en el manifiesto del Plugin propietario, en lugar de en tablas centrales 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

Usa providerEndpoints para la clasificación de endpoints que la política genérica de solicitudes debe conocer antes de que se cargue el tiempo de ejecución del proveedor. El núcleo sigue siendo propietario del significado de cada endpointClass; los manifiestos de Plugin son propietarios de los metadatos de host y URL base.

Campos de endpoint:

Referencia de providerRequest

Usa providerRequest para metadatos económicos de compatibilidad de solicitudes que la política genérica de solicitudes necesita sin cargar el tiempo de ejecución del proveedor. Mantén la reescritura de cargas específica del comportamiento en hooks del tiempo de ejecución del proveedor o en helpers compartidos de familia de proveedores.

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

Campos del proveedor:

Referencia de modelPricing

Usa modelPricing cuando un proveedor necesita comportamiento de precios del plano de control antes de que se cargue el tiempo de ejecución. La caché de precios del Gateway lee estos metadatos sin importar código del tiempo 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 Plugin siguen siendo la autoridad de plugins instalados. El Índice de proveedores es el contrato interno de reserva que las futuras superficies de proveedores instalables y de selector de modelos previas a la instalación consumirán cuando un Plugin de proveedor no esté instalado.

Orden de autoridad del catálogo:

1. Configuración de 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 tiempo de ejecución ni datos de modelos en vivo específicos de una cuenta. Sus catálogos de vista previa usan la misma forma de fila de proveedor de modelCatalog que los manifiestos de Plugin, pero deben limitarse a metadatos de visualización estables salvo que campos del adaptador de tiempo de ejecución como api, baseUrl, precios o indicadores de compatibilidad se mantengan alineados intencionalmente con el manifiesto del Plugin instalado. Los proveedores con descubrimiento en vivo de /models deben escribir filas actualizadas mediante la ruta explícita de caché del catálogo de modelos, en lugar de hacer que la lista normal o el onboarding llamen a las API del proveedor.

Las entradas del Índice de proveedores también pueden llevar metadatos de Plugin instalable para proveedores cuyo Plugin se haya movido fuera del núcleo o que aún no esté instalado. 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 las etiquetas económicas de elección de autenticación bastan para mostrar una opción de configuración instalable. Una vez instalado el Plugin, su manifiesto gana y la entrada del Índice de proveedores se ignora para ese proveedor.

Las claves de capacidad heredadas de nivel superior están obsoletas. Usa openclaw doctor --fix para mover speechProviders, realtimeTranscriptionProviders, realtimeVoiceProviders, mediaUnderstandingProviders, imageGenerationProviders, videoGenerationProviders, webFetchProviders y webSearchProviders bajo contracts; la carga normal del manifiesto ya no trata esos campos de nivel superior como propiedad de capacidades.

Manifiesto frente a package.json

Los dos archivos cumplen funciones diferentes:

Si no tienes claro dónde corresponde un fragmento de metadatos, usa esta regla:

• si OpenClaw debe conocerlo antes de cargar código del Plugin, ponlo en openclaw.plugin.json
• si se trata de empaquetado, archivos de entrada o comportamiento de instalación de npm, ponlo en package.json

Campos de package.json que afectan el descubrimiento

Algunos metadatos de Plugin previos al tiempo de ejecución viven intencionalmente en package.json bajo el bloque openclaw en lugar de en openclaw.plugin.json. openclaw.bundle y openclaw.bundle.json no son contratos de Plugin de OpenClaw; los plugins nativos deben usar openclaw.plugin.json más los campos compatibles de package.json#openclaw a continuación.

Ejemplos importantes:

Los metadatos del manifiesto deciden qué opciones de proveedor/canal/configuración aparecen en la incorporación antes de que se cargue el runtime. package.json#openclaw.install indica a la incorporación cómo obtener o habilitar ese Plugin cuando el usuario elige una de esas opciones. No muevas las pistas 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 Plugin no incluidas. Los valores no válidos se rechazan; los valores más recientes pero válidos omiten plugins externos en hosts antiguos. Se asume que los plugins de origen incluidos están versionados conjuntamente con el checkout del host.

Los metadatos oficiales de instalación bajo demanda deben usar clawhubSpec cuando el Plugin se publique en ClawHub; la incorporación lo trata como 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 paquetes que aún no se han movido a ClawHub.

La fijación exacta de versión npm ya vive en npmSpec, por ejemplo "npmSpec": "@wecom/[email protected]". Las entradas oficiales del catálogo externo deben emparejar especificaciones exactas con expectedIntegrity para que los flujos de actualización fallen cerrados si el artefacto npm obtenido ya no coincide con la versión fijada. La incorporación interactiva aún ofrece especificaciones npm de registros de confianza, incluidos nombres de paquete desnudos y dist-tags, por compatibilidad. Los diagnósticos del catálogo pueden distinguir fuentes exactas, flotantes, fijadas por integridad, sin integridad, con discrepancia de nombre de paquete y de opción predeterminada no válida. También advierten cuando expectedIntegrity está presente pero no hay una fuente npm válida que pueda fijar. Cuando expectedIntegrity está presente, los flujos de instalación/actualización lo aplican; cuando se omite, la resolución del registro se registra sin una fijación de integridad.

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

Los campos de punto de entrada de runtime no anulan las comprobaciones de límite de paquete para los campos de punto de entrada de origen. Por ejemplo, openclaw.runtimeExtensions no puede hacer que una ruta openclaw.extensions que escape sea cargable.

openclaw.install.allowInvalidConfigRecovery es intencionadamente estrecho. No hace instalables configuraciones rotas arbitrarias. Hoy solo permite que los flujos de instalación se recuperen de fallos específicos obsoletos de actualización de Plugin incluido, como una ruta de Plugin incluido faltante o una entrada channels.<id> obsoleta para ese mismo Plugin incluido. Los errores de configuración no relacionados siguen bloqueando la instalación y envían a los operadores a openclaw doctor --fix.

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

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

Úsalo cuando los flujos de configuración, doctor, estado o presencia de solo lectura necesiten una sonda económica de autenticación sí/no antes de que se cargue el Plugin de canal completo. El estado de autenticación persistida no es estado de canal configurado: no uses estos metadatos para habilitar plugins automáticamente, reparar dependencias de runtime ni decidir si debe cargarse un runtime de canal. La exportación de destino debe ser una función pequeña que solo lea estado persistido; no la encamines a través del barrel completo del runtime de canal.

openclaw.channel.configuredState sigue la misma forma para comprobaciones económicas de configuración solo por env:

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

Úsalo cuando un canal pueda responder el estado configurado desde env u otras entradas pequeñas no de runtime. Si la comprobación necesita resolución completa de configuración o el verdadero runtime de canal, mantén esa lógica en el hook config.hasConfiguredState del Plugin.

Precedencia de descubrimiento (ids de Plugin duplicados)

OpenClaw descubre plugins desde varias raíces (incluidos, instalación global, workspace, rutas seleccionadas explícitamente por configuración). Si dos descubrimientos comparten el mismo id, solo se conserva el manifiesto de mayor precedencia; los duplicados de menor precedencia se descartan en lugar de cargarse junto a él.

Precedencia, de mayor a menor:

1. Seleccionado por configuración — una ruta fijada explícitamente en plugins.entries.<id>
2. Incluido — plugins enviados con OpenClaw
3. Instalación global — plugins instalados en la raíz global de plugins de OpenClaw
4. Workspace — plugins descubiertos en relación con el workspace actual

Implicaciones:

• Una copia bifurcada u obsoleta de un Plugin incluido ubicada en el workspace no ensombrecerá la compilación incluida.
• Para sobrescribir realmente un Plugin incluido con uno local, fíjalo mediante plugins.entries.<id> para que gane por precedencia en lugar de depender del descubrimiento del workspace.
• Los descartes duplicados se registran para que Doctor y los diagnósticos de inicio puedan señalar la copia descartada.
• Las sobrescrituras duplicadas seleccionadas por configuración se redactan como sobrescrituras explícitas en los diagnósticos, pero aun así advierten para que las bifurcaciones obsoletas y los ensombrecimientos accidentales sigan visibles.

Requisitos de JSON Schema

• Todo Plugin debe distribuir un JSON Schema, incluso si no acepta configuración.
• Un esquema vacío es aceptable (por ejemplo, { "type": "object", "additionalProperties": false }).
• Los esquemas se validan en el momento de lectura/escritura de configuración, no en runtime.
• Al extender o bifurcar un Plugin incluido con nuevas claves de configuración, actualiza también el configSchema de openclaw.plugin.json de ese Plugin. Los esquemas de plugins incluidos son estrictos, por lo que añadir plugins.entries.<id>.config.myNewKey en la configuración de usuario sin añadir myNewKey a configSchema.properties se rechazará antes de que se cargue el runtime del Plugin.

Ejemplo de extensión de esquema:

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

Comportamiento de validación

• Las claves channels.* desconocidas son errores, a menos que el id de canal esté declarado por un manifiesto de Plugin.
• plugins.entries.<id>, plugins.allow, plugins.deny y plugins.slots.* deben hacer referencia a ids de Plugin descubribles. Los ids desconocidos son errores.
• Si un Plugin está instalado pero tiene un manifiesto o esquema roto o faltante, la validación falla y Doctor informa el error del Plugin.
• Si existe configuración de Plugin pero el Plugin está deshabilitado, la configuración se conserva y se muestra una advertencia en Doctor + logs.

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 es solo para descubrimiento y 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 documentados del manifiesto. Evita 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 código amplio del entorno de ejecución; úsalo para metadatos estáticos del catálogo de proveedores o descriptores de descubrimiento acotados, no para ejecución en tiempo de solicitud. providerDiscoveryEntry es la grafía heredada y sigue funcionando para plugins existentes.
• Los tipos exclusivos de plugin se seleccionan mediante plugins.slots.*: kind: "memory" mediante plugins.slots.memory, kind: "context-engine" mediante plugins.slots.contextEngine (valor predeterminado legacy).
• Declara el tipo exclusivo de plugin en este manifiesto. OpenClawPluginDefinition.kind de la entrada de ejecución está obsoleto y permanece solo como alternativa de compatibilidad para plugins antiguos.
• Los metadatos de variables de entorno (setup.providers[].envVars, el elemento obsoleto providerAuthEnvVars y channelEnvVars) son solo declarativos. El estado, la auditoría, la validación de entrega de cron y otras superficies de solo lectura siguen aplicando la confianza del plugin y la política de activación efectiva antes de tratar una variable de entorno como configurada.
• Para metadatos del asistente de configuración en ejecución que requieren código del proveedor, consulta hooks de ejecución de 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 + pnpm rebuild <package>).

Relacionado