Manifiesto del Plugin

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

Para diseños de paquete compatibles, consulta paquetes de Plugins.

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 entorno de ejecución de OpenClaw.

Todo 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 ausentes o no válidos se tratan como errores de Plugin y bloquean la validación de 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 es el metadato que OpenClaw lee antes de cargar el código de tu Plugin. Todo lo siguiente debe ser lo bastante barato de inspeccionar sin iniciar el entorno de ejecución 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, activación automática, variables de entorno de 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 de canal fusionados en 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 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"],  "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 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 principales puedan decidir si un proveedor de generación está disponible sin importar todos los 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 guardia de mode admite:

Cada entrada de authSignals admite:

Cada guardia 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, con clave por nombre de herramienta. contracts.tools declara la propiedad. toolMetadata declara evidencia barata de disponibilidad 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"]        }      ]    }  }}

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 ruta crítica cuya fábrica depende de autenticación/configuración, los autores de Plugin 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 de descriptores 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 de tiempo de ejecución que los usuarios podrían poner por error en plugins.allow o intentar ejecutar como comando raíz de CLI. 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 con bajo costo qué eventos del plano de control deben incluirlo en un plan de activación/carga.

Este bloque es metadatos del planificador, no una API de ciclo de vida. No registra comportamiento de tiempo de ejecución, no reemplaza register(...) y no promete que el código del plugin ya se haya ejecutado. El planificador de activación usa estos campos para acotar 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 específicos que ya describan la propiedad. Usa providers, channels, commandAliases, descriptores de configuración o contracts cuando esos campos expresen la relación. Usa activation para sugerencias adicionales del planificador que no puedan representarse mediante esos campos de propiedad. Usa cliBackends de nivel superior para alias de tiempo de ejecución de CLI como claude-cli, my-cli o google-gemini-cli; activation.onAgentHarnesses es solo para ids. de arnés de agente embebidos que aún no tienen un campo de propiedad.

Este bloque es solo metadatos. No registra comportamiento de tiempo de ejecución y no reemplaza register(...), setupEntry ni otros puntos de entrada de tiempo de ejecución/plugin. Los consumidores actuales lo usan como sugerencia de acotación antes de una carga de plugins más amplia, por lo que la falta de metadatos de activación que no sean de arranque normalmente solo cuesta rendimiento; no debería cambiar la corrección mientras sigan existiendo los respaldos de propiedad del manifiesto.

Cada plugin debe definir 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 por activadores más específicos. Omitir onStartup ya no carga el plugin implícitamente al arrancar; usa metadatos de activación explícitos para arranque, canal, configuración, arnés de agente, 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 de arranque del Gateway usa activation.onStartup para la importación explícita al arrancar
• La planificación de CLI activada por comandos recurre al comportamiento heredado de commandAliases[].cliCommand o commandAliases[].name
• La planificación de arranque de tiempo de ejecución del agente usa activation.onAgentHarnesses para arneses embebidos y cliBackends[] de nivel superior para alias de tiempo de ejecución de CLI
• La planificación de configuración/canal activada por canal recurre a la propiedad heredada de channels[] cuando faltan metadatos explícitos de activación de canal
• La planificación de plugins de 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 configuración/tiempo de ejecución activada por proveedor recurre a la propiedad heredada de providers[] y cliBackends[] de nivel superior cuando faltan metadatos explícitos de activación de proveedor

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

Referencia de qaRunners

Usa qaRunners cuando un plugin aporta uno o más ejecutores de transporte bajo la raíz compartida openclaw qa. Mantén estos metadatos baratos y estáticos; el tiempo de ejecución del plugin sigue siendo dueño 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 configuración inicial y onboarding necesiten metadatos baratos propiedad del plugin antes de que se cargue el runtime.

{  "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 CLI. setup.cliBackends es la superficie descriptora específica de setup para flujos de plano de control/setup que deben mantenerse solo como metadatos.

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

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 desuso, pero los plugins no agrupados que todavía lo usan reciben un diagnóstico de manifiesto. Los plugins nuevos deben colocar los metadatos de entorno de setup/estado en setup.providers[].envVars.

OpenClaw también puede derivar opciones simples de setup a partir de setup.providers[].authMethods cuando no hay ninguna entrada de setup disponible, o cuando setup.requiresRuntime: false declara que el runtime de setup no es necesario. Las entradas explícitas de 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 valor explícito false 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 distribuye una de esas entradas de runtime de setup, OpenClaw informa un diagnóstico aditivo y continúa ignorándola. Omitir requiresRuntime conserva el comportamiento alternativo legacy 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 runtime 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 ningún registro de runtime correspondiente. Estos diagnósticos son aditivos y no rechazan plugins legacy.

referencia de setup.providers

authEvidence es para marcadores de credenciales locales propiedad del proveedor que se pueden verificar sin cargar código de runtime. Estas comprobaciones deben seguir siendo baratas y locales: sin llamadas de red, sin lecturas del llavero o 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 sugerencias de renderizado.

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

Cada sugerencia de campo puede incluir:

referencia de contracts

Usa contracts solo para metadatos estáticos de propiedad de capacidades que OpenClaw puede leer sin importar el runtime 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"],    "webFetchProviders": ["firecrawl"],    "webSearchProviders": ["gemini"],    "migrationProviders": ["hermes"],    "gatewayMethodDispatch": ["authenticated-request"],    "tools": ["firecrawl_search", "firecrawl_scrape"]  }}

Cada lista es opcional:

contracts.embeddedExtensionFactories se conserva para factories de extensión incluidas y exclusivas 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 instalados pueden usar la misma unión de middleware solo cuando está habilitada explícitamente y solo para los runtimes que declaran en contracts.agentToolResultMiddleware.

Los plugins instalados que necesiten el nivel de política previa a herramientas confiable para el host deben declarar cada id local registrado en contracts.trustedToolPolicies y estar habilitados explícitamente. Los plugins incluidos mantienen la ruta de política confiable existente, pero los plugins instalados con ids de política no declarados se rechazan antes del registro. Los ids de política tienen alcance al plugin que los registra, por lo que dos plugins pueden declarar y registrar workflow-budget; un solo plugin no puede registrar el mismo id local dos veces.

Los registros de runtime api.registerTool(...) deben coincidir con contracts.tools. La detección de herramientas usa esta lista para cargar solo los runtimes de plugin que pueden poseer las herramientas solicitadas.

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

Los proveedores generales de embeddings deben declarar contracts.embeddingProviders para cada adaptador registrado con api.registerEmbeddingProvider(...). Usa el contrato general para la generación reutilizable de vectores, incluidos los proveedores consumidos por la búsqueda en memoria. contracts.memoryEmbeddingProviders es compatibilidad específica de memoria obsoleta y permanece solo mientras los proveedores existentes migran a la unión genérica de proveedores de embeddings.

contracts.gatewayMethodDispatch acepta actualmente "authenticated-request". Es una barrera de higiene de API para rutas HTTP nativas de plugins que despachan intencionalmente métodos del plano de control de Gateway dentro del proceso, no un sandbox contra plugins nativos maliciosos. Úsalo solo para superficies incluidas/de operador revisadas con rigor que ya requieren autenticación HTTP de Gateway.

Referencia de mediaUnderstandingProviderMetadata

Usa mediaUnderstandingProviderMetadata cuando un proveedor de comprensión multimedia tiene modelos predeterminados, prioridad de fallback de autenticación automática o compatibilidad nativa con documentos que los helpers genéricos de core necesitan antes de que se cargue el runtime. 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 necesita metadatos de configuración económicos antes de que se cargue el runtime. La detección de configuración/estado de canal de solo lectura puede usar estos metadatos directamente para canales externos configurados cuando no hay una entrada de configuración disponible, o cuando setup.requiresRuntime: false declara que el runtime de configuración no es necesario.

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 metadatos del manifiesto para decidir qué plugin posee ese canal configurado antes de que se ejecute el código de runtime 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 el esquema de configuración de ruta fría, la configuración y las superficies de Control UI no pueden conocer la forma de opciones propiedad del canal hasta que se ejecute el runtime del plugin.

channelConfigs.<channel-id>.commands.nativeCommandsAutoEnabled y nativeSkillsAutoEnabled pueden declarar valores predeterminados auto estáticos para comprobaciones de configuración de comandos que se ejecutan antes de que se cargue el runtime 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:

Reemplazar 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 reemplaza a un plugin incluido, o un fork mantenido 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 de runtime efectiva para que un plugin posea el canal y sus herramientas. La selección explícita del usuario sigue prevaleciendo: si el usuario habilita explícitamente ambos plugins, OpenClaw preserva esa elección e informa 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 claves de configuración de 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 se cargue el tiempo de ejecución del Plugin.

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

OpenClaw aplica esta precedencia:

• las refs explícitas provider/model usan los metadatos del manifiesto providers propietario
• modelPatterns tiene prioridad sobre modelPrefixes
• si un Plugin no incluido en el paquete y un Plugin incluido en el paquete coinciden, gana el Plugin no incluido
• la ambigüedad restante se ignora hasta que el usuario o la configuración especifique un proveedor

Campos:

Las entradas de modelPatterns se compilan mediante compileSafeRegex, que rechaza patrones que contienen repetición anidada (por ejemplo (a+)+$). Los patrones que fallan la comprobación de seguridad se omiten silenciosamente, igual que una regex sintácticamente inválida. Mantén los patrones simples y evita cuantificadores anidados.

referencia de modelCatalog

Usa modelCatalog cuando OpenClaw deba conocer los metadatos de modelos del proveedor antes de cargar el tiempo de ejecución 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 tiempo de ejecución sigue perteneciendo al código de tiempo de ejecución del proveedor, pero el manifiesto indica al núcleo cuándo se requiere el tiempo de ejecución.

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

Campos de nivel superior:

aliases participa en la búsqueda de propiedad del proveedor para 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 anulaciones de API/URL base del alias sin cargar el tiempo de ejecución del proveedor. Los alias no expanden listados de catálogo sin filtrar; las listas amplias emiten solo las filas del proveedor canónico propietario.

suppressions reemplaza el antiguo punto de extensión suppressBuiltInModel del tiempo de ejecución del proveedor. 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 propietario. Los puntos de extensión de supresión en tiempo de ejecución ya no se llaman durante la resolución de modelos.

Campos del proveedor:

Campos del modelo:

Campos de supresión:

No pongas datos solo 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 selector omitan el descubrimiento de registro/tiempo de ejecución. Usa refreshable cuando las filas del manifiesto sean semillas o suplementos listables útiles pero una actualización/caché pueda añadir más filas más tarde; las filas actualizables no son autoritativas por sí mismas. Usa runtime cuando OpenClaw deba cargar el tiempo de ejecución del proveedor para conocer la lista.

referencia de modelIdNormalization

Usa modelIdNormalization para limpieza barata de ids 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, ids heredados locales al 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 útiles específica del comportamiento en los ganchos del tiempo de ejecución del proveedor o en helpers compartidos de familias de proveedores.

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

Campos del proveedor:

Referencia de secretProviderIntegrations

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

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

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

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

{  "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 desde el manifiesto. Deshabilitar o eliminar el Plugin revoca el proveedor para SecretRefs activos. Los operadores que quieran una configuración exec independiente aún pueden escribir proveedores manuales de command/args directamente.

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

OpenClaw deriva trustedDirs para preajustes de manifiesto desde la raíz del Plugin y, para preajustes ${node}, desde el directorio del ejecutable actual de Node. Los trustedDirs definidos por el manifiesto se ignoran. Otras opciones de proveedor exec como timeoutMs, 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 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 del Plugin instalado. El Índice de proveedores es el contrato interno de respaldo que las futuras superficies de selección de modelos e instalación previa de proveedores instalables 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 desde 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, ganchos de tiempo de ejecución ni datos de modelos específicos de una cuenta en vivo. Sus catálogos de vista previa usan la misma forma de fila de proveedor modelCatalog que los manifiestos de Plugin, pero deben permanecer limitados 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 el listado normal o el onboarding llamen a las APIs 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 aún no esté instalado por otro motivo. Estos metadatos reflejan el patrón del catálogo de canales: nombre del paquete, especificación de instalación npm, integridad esperada y 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 prevalece y la entrada del Índice de proveedores se ignora para ese proveedor.

Las claves de capacidad de nivel superior heredadas 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 distintas:

Si no tienes claro dónde corresponde una pieza de metadatos, usa esta regla:

• si OpenClaw debe conocerla antes de cargar el código del Plugin, ponla en openclaw.plugin.json
• si trata sobre empaquetado, archivos de entrada o comportamiento de instalación npm, ponla 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 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 admitidos de package.json#openclaw que aparecen abajo.

Ejemplos importantes:

Los metadatos del manifiesto deciden qué opciones de proveedor/canal/configuración aparecen en la incorporación antes de que 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 sugerencias 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 integradas. Los valores no válidos se rechazan; los valores más nuevos pero válidos omiten plugins externos en hosts antiguos. Se asume que los plugins de fuente integrados tienen la misma versión que el checkout del host.

openclaw.install.requiredPlatformPackages es para paquetes npm que exponen binarios nativos requeridos mediante alias opcionales específicos de plataforma. Lista el nombre básico del paquete npm para cada alias de plataforma compatible. Durante la instalación npm, OpenClaw verifica solo el alias declarado cuyas restricciones de lockfile coinciden con el host actual. Si npm informa éxito pero omite ese alias, OpenClaw reintenta una vez con una caché nueva y revierte la instalación si el alias sigue faltando.

openclaw.compat.pluginApi se aplica durante la instalación de paquetes para fuentes de Plugin no integradas. Úsalo para el piso de API del SDK/runtime de plugins de OpenClaw contra el que se compiló el paquete. Puede ser más estricto que minHostVersion cuando un paquete de Plugin necesita una API más nueva pero mantiene una sugerencia de instalación más baja para otros flujos. La sincronización de versiones oficiales de OpenClaw incrementa por defecto los pisos de API de plugins oficiales existentes a la versión de lanzamiento de OpenClaw, pero los lanzamientos solo de Plugin pueden mantener un piso más bajo cuando el paquete admite intencionalmente hosts más antiguos. No uses solo la versión del paquete como contrato de compatibilidad. peerDependencies.openclaw sigue siendo metadato de paquete npm; OpenClaw usa el contrato openclaw.compat.pluginApi para decisiones de compatibilidad de instalación.

Los metadatos oficiales de instalación bajo demanda deben usar clawhubSpec cuando el Plugin se publica en ClawHub; la incorporación lo trata como la fuente remota preferida y registra datos del artefacto de ClawHub después de instalar. npmSpec sigue siendo la alternativa de compatibilidad para paquetes que aún no se han movido a ClawHub.

El anclaje exacto de versión npm ya vive en npmSpec, por ejemplo "npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3". Las entradas oficiales de 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 anclada. La incorporación interactiva aún ofrece especificaciones npm de registro confiable, incluidos nombres de paquete básicos y dist-tags, por compatibilidad. Los diagnósticos de catálogo pueden distinguir fuentes exactas, flotantes, ancladas por integridad, sin integridad, con discordancia de nombre de paquete y de elección predeterminada no válida. También advierten cuando expectedIntegrity está presente pero no hay una fuente npm válida que pueda anclar. Cuando expectedIntegrity está presente, los flujos de instalación/actualización lo aplican; cuando se omite, la resolución del registro se registra sin un anclaje de integridad.

Los plugins de canal deben proporcionar openclaw.setupEntry cuando el estado, la lista de canales o los escaneos de SecretRef necesiten identificar cuentas configuradas sin cargar el runtime completo. La entrada de configuración debe exponer metadatos de canal además de adaptadores de configuración, estado y secretos seguros para configuración; mantén los clientes de red, escuchas de Gateway y 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ímites de paquete para campos de punto de entrada de origen. Por ejemplo, openclaw.runtimeExtensions no puede hacer que una ruta de openclaw.extensions que escapa sea cargable.

openclaw.install.allowInvalidConfigRecovery es intencionalmente limitado. 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 plugins integrados, como una ruta de Plugin integrado faltante o una entrada channels.<id> obsoleta para ese mismo Plugin integrado. 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 es metadato de paquete para un módulo comprobador pequeño:

{  "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 cargue el Plugin de canal completo. El estado de autenticación persistido no es estado de canal configurado: no uses estos metadatos para habilitar plugins automáticamente, reparar dependencias de runtime ni decidir si debe cargar un runtime de canal. La exportación de destino debe ser una función pequeña que solo lea estado persistido; no la enrutes a través del barrel del runtime de canal completo.

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 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 runtime real del 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. Para el orden bruto de escaneo del sistema de archivos, consulta Orden de escaneo de Plugin. 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 anclada explícitamente en plugins.entries.<id>
2. Integrado — 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 integrado ubicada en el workspace no sombreará la compilación integrada.
• Para reemplazar realmente un Plugin integrado con uno local, ánclalo mediante plugins.entries.<id> para que gane por precedencia en lugar de depender del descubrimiento del workspace.
• Los descartes de duplicados se registran para que Doctor y los diagnósticos de inicio puedan señalar la copia descartada.
• Los reemplazos duplicados seleccionados por configuración se redactan como reemplazos explícitos en los diagnósticos, pero aun así advierten para que las bifurcaciones obsoletas y los sombreados accidentales sigan visibles.

Requisitos de JSON Schema

• Cada Plugin debe incluir un JSON Schema, aunque no acepte configuración.
• Un esquema vacío es aceptable (por ejemplo, { "type": "object", "additionalProperties": false }).
• Los esquemas se validan al leer/escribir la configuración, no en tiempo de ejecución.
• Al extender o bifurcar un Plugin incluido con nuevas claves de configuración, actualiza el configSchema de openclaw.plugin.json de ese Plugin al mismo tiempo. Los esquemas de Plugins incluidos son estrictos, por lo que agregar plugins.entries.<id>.config.myNewKey en la configuración del usuario sin agregar myNewKey a configSchema.properties será rechazado antes de que se cargue el runtime del Plugin.

Extensión de esquema de ejemplo:

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

Comportamiento de validación

• Las claves channels.* desconocidas son errores, a menos que el id del canal esté declarado por el manifiesto de un Plugin.
• plugins.entries.<id>, plugins.allow, plugins.deny y plugins.slots.* deben hacer referencia a ids de Plugin detectables. Los ids desconocidos son errores.
• Si un Plugin está instalado pero tiene un manifiesto o esquema roto o ausente, 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 + registros.

Consulta la Referencia de configuración para ver el esquema completo de plugins.*.

Notas

• El manifiesto es obligatorio para Plugins nativos de OpenClaw, incluidas las cargas desde el sistema de archivos local. El runtime sigue cargando el módulo del Plugin por separado; el manifiesto solo sirve para descubrimiento + 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 debe importar código amplio de runtime; úsalo para metadatos estáticos del catálogo de proveedores o descriptores de descubrimiento acotados, no para ejecución en tiempo de solicitud.
• Los tipos de Plugin exclusivos se seleccionan mediante plugins.slots.*: kind: "memory" a través de plugins.slots.memory, kind: "context-engine" a través de plugins.slots.contextEngine (valor predeterminado legacy).
• Declara el tipo de Plugin exclusivo en este manifiesto. OpenClawPluginDefinition.kind en la entrada de runtime está obsoleto y permanece solo como alternativa de compatibilidad para Plugins antiguos.
• Los metadatos de variables de entorno (setup.providers[].envVars, el providerAuthEnvVars obsoleto 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 runtime que requieren código de proveedor, consulta Hooks de runtime 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, pnpm allow-build-scripts + pnpm rebuild <package>).

Relacionado