OpenAI Plugins: ejemplos, formatos portables y límites de conexión
Arquitectura de plugins OpenAI: identidad portable y configuración específica
Comprende ubicaciones fijas, selección de configuración sin mezcla y responsabilidades distintas de .app.json y MCP.
Qué aprenderás
- La identidad portable define el paquete
- El objeto OpenAI sustituye, no combina
- Instrucciones y conexiones cumplen funciones diferentes
Antes de empezar
- Conocimientos básicos de JSON y rutas
- Comprender habilidades y permisos de servicios externos
Distinguir ejemplos y guía actual sin confundir metadatos con evidencia de ejecución.
Conclusiones clave
- Identidad y componentes portables permanecen canónicos.
- El objeto OpenAI inline sustituye toda la configuración compatible.
- Configurar una conexión no demuestra autenticación real.
La identidad portable define el paquete
La guía actual usa plugin.json en la raíz con un esquema Agent Plugins como entrada portable. Las habilidades se descubren en skills y los servidores incluidos en mcp.json. Una declaración skills o mcpServers de la configuración Codex no sustituye ni amplía esas ubicaciones fijas.
Los ejemplos heredados sin raíz portable reconocida usan las declaraciones del manifiesto compatible. Por eso mover el archivo antiguo a la raíz no completa una migración. Deben revisarse juntos esquema, descubrimiento de componentes y ubicación de metadatos, conservando el flujo deseado.
El objeto OpenAI sustituye, no combina
Cuando extensions.com.openai es un objeto en el manifiesto portable, la página oficial dice que sustituye por completo la configuración de .codex-plugin/plugin.json. No se combinan. Si falta el objeto, la configuración compatible puede aportar esos ajustes, mientras la identidad portable sigue siendo canónica.
Esto importa en migraciones parciales: un objeto inline que contiene solo interface no hereda automáticamente apps o hooks del archivo anterior. Examina el objeto completo seleccionado y prueba las capacidades esperadas. JSON válido todavía puede omitir la conexión necesaria.
Instrucciones y conexiones cumplen funciones diferentes
En el ejemplo compatible Figma, skills apunta a flujos y apps a .app.json, que vincula una integración con un identificador registrado. El archivo .mcp.json describe endpoint y recurso OAuth. Son observaciones de configuración, no prueba de que un anfitrión abra o deduplique ambas conexiones.
El modelo didáctico ilustra identidad, ubicaciones fijas y selección de un objeto completo. Excluye carga real, autenticación, políticas y ejecución de herramientas. Úsalo para razonar sobre migraciones y después valida el paquete real en el anfitrión compatible elegido.
Cómo elegir
| Criterio | Opción A | Opción B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
Pasos de implementación
- 1
Identifica formato portable o solo compatible.
- 2
Determina el único objeto OpenAI seleccionado.
- 3
Comprueba componentes fijos aparte de sus ajustes.
- 4
Prueba el paquete en el anfitrión previsto.
Ejemplo para copiar
{
"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
"name": "synthetic-notes",
"version": "0.1.0",
"description": "Ejercicio de notas sintéticas",
"extensions": {
"com.openai": {
"interface": {
"displayName": "Notas Sintéticas"
}
}
}
}Preguntas frecuentes
¿Se mezclan ajustes inline y compatibles?
No. La guía indica sustitución del objeto completo.
¿La configuración compatible redirige habilidades portables?
No. Los paquetes portables reconocidos usan skills y mcp.json fijos.
Fuentes
- OpenAI Plugins / plugins/figma/.codex-plugin/plugin.jsonFuente verificada 2026-09-14
- OpenAI Plugins / plugins/figma/.app.jsonFuente verificada 2026-09-14
- OpenAI Plugins / plugins/figma/.mcp.jsonFuente verificada 2026-09-14
- OpenAI — Package your plugin (checked 2026-09-14)Fuente verificada 2026-09-14