El sistema de plugins de la CLI de Codex está madurando rápidamente. Con el comando /plugins, ya es posible navegar por el mercado, instalar, activar y desactivar extensiones, lo que ha llevado a que cada vez más equipos empaqueten sus cadenas de herramientas internas como plugins de Codex reutilizables. Sin embargo, el proceso de publicación en el Marketplace oficial sigue bajo un modelo de "revisión manual". Los desarrolladores deben comprender primero la estructura del manifiesto y los métodos de depuración local antes de completar el proceso de envío para que el plugin llegue realmente a los usuarios. Este artículo detalla, paso a paso, el flujo completo: desde la creación desde cero, pruebas locales y distribución mediante Git, hasta la revisión y publicación oficial, además de resumir algunos errores comunes.
¿De qué está compuesto realmente un plugin de Codex?
Un plugin de Codex es, en esencia, un paquete que agrupa varias capacidades para que sean instalables y distribuibles. Según la documentación oficial de OpenAI, los plugins pueden incluir skills (instrucciones de tareas reutilizables), aplicaciones respaldadas por MCP (servicios que conectan herramientas externas), hooks de ciclo de vida, además de extensiones de navegador opcionales y plantillas de tareas programadas. Estos componentes no tienen que existir todos a la vez; un plugin ligero que solo contenga skills puede instalarse y utilizarse perfectamente.
Entender los límites de responsabilidad de cada componente es fundamental para escribir un manifiesto adecuado. La siguiente tabla resume la ruta de almacenamiento y la función de las cuatro categorías principales de componentes en un directorio de plugin de Codex:
| Componente | Ruta de almacenamiento | Función | ¿Es obligatorio? |
|---|---|---|---|
| plugin.json | .codex-plugin/plugin.json |
Identidad y metadatos del plugin | Sí |
| skills | skills/<skill-name>/SKILL.md |
Define instrucciones de tareas reutilizables | No |
| Servidores MCP | .mcp.json |
Configura la conexión a servicios de herramientas externas | No |
| hooks | hooks/hooks.json |
Declara comandos de hooks de ciclo de vida | No |
Vale la pena señalar que, si el plugin es solo un archivo SKILL.md para uso interno del equipo, no es necesario pasar por el proceso completo del manifiesto: basta con colocar el archivo directamente en el directorio .agents/skills/ y Codex lo detectará automáticamente sin necesidad de una lista de plugins. Esta es una forma intermedia común antes de que muchos equipos pasen de "scripts internos" a "plugins formales".
El alcance de las capacidades de un plugin es más amplio de lo que muchos imaginan. Además de los skills y las aplicaciones respaldadas por MCP, la documentación oficial menciona que los plugins pueden incluir declaraciones de capacidades necesarias para extensiones de navegador y plantillas de tareas programadas. Esto significa que un plugin puede gestionar tanto solicitudes interactivas "iniciadas por el usuario" como escenarios de automatización que requieren "ejecución periódica en segundo plano". Elegir qué componentes combinar en un mismo plugin es, en el fondo, un ejercicio de equilibrio entre la experiencia de instalación y el coste de mantenimiento: cuantos más componentes, más completo será el plugin, pero también aumentarán los materiales de revisión y los casos de prueba. Antes de enviarlo, es mejor tener claro qué nivel de capacidad necesitan realmente tus usuarios, en lugar de intentar meter todos los componentes en un mismo paquete.
Empezando por plugin.json: una guía detallada del archivo de manifiesto del plugin
El archivo plugin.json es el documento de identidad de tu plugin; es lo que determina cómo Codex lo identifica, carga y muestra. Un manifiesto funcional mínimo solo requiere tres campos:
{
"name": "my-first-plugin",
"version": "1.0.0",
"description": "Reusable greeting workflow",
"skills": "./skills/"
}
Para el campo name, te recomiendo usar un formato kebab-case estable. No cambies este identificador en versiones posteriores, ya que el mercado lo utiliza para reconocer que se trata de la misma iteración del plugin. La version debe seguir las normas de versionado semántico, ya que el mercado depende de este campo para notificar a los usuarios sobre actualizaciones. Todas las rutas referenciadas en el manifiesto deben ser relativas al directorio raíz del plugin, comenzar con ./ y no pueden salir de dicho directorio.
Además de estos tres campos básicos, skills puede apuntar a una matriz de directorios de habilidades, mientras que los campos hooks, mcpServers y apps apuntan a sus respectivos archivos de configuración: hooks/hooks.json, .mcp.json y .app.json. Este diseño de "campos que apuntan a archivos" mantiene el manifiesto ligero, permitiendo que las descripciones de habilidades y configuraciones de herramientas se mantengan en archivos independientes, lo que facilita la colaboración en equipo sin generar conflictos.
Si planeas enviar tu plugin al Marketplace oficial, necesitarás añadir un conjunto de metadatos orientados a la presentación. La siguiente tabla detalla los campos clave que se recomienda completar durante la fase de publicación:
| Campo | Tipo | Descripción |
|---|---|---|
| author / repository | Cadena | Identifica el origen del plugin, debe coincidir con la identidad verificada |
| interface.displayName | Cadena | Nombre del plugin que se muestra en la lista del mercado |
| interface.category | Cadena | Categoría del plugin, influye en la navegación del usuario |
| interface.capabilities | Matriz | Etiquetas que declaran las capacidades del plugin |
| mcpServers / apps / hooks | Objeto | Apunta a los archivos de configuración de los componentes correspondientes |
El error más común al escribir el manifiesto son las referencias de ruta incorrectas (por ejemplo, escribir rutas absolutas en el campo skills u omitir el ./ inicial), lo que hará que el plugin funcione localmente pero sea rechazado durante la revisión. Te sugiero clonar el repositorio del plugin en un directorio limpio antes de enviarlo para simular un entorno de instalación real y realizar una prueba completa.
Andamiaje local y depuración: pon tu plugin en marcha
Escribir el manifiesto desde cero no es muy eficiente. Ofrecemos la habilidad integrada $plugin-creator para configurar el andamiaje, que puedes generar de forma conversacional directamente en la CLI de Codex:
codex "Usa el andamiaje $plugin-creator para generar un plugin llamado infra-monitor"
Este comando generará automáticamente el manifiesto, una habilidad de ejemplo y una entrada en el mercado local, ahorrándote el trabajo tedioso de crear la estructura de directorios. Una vez generado, el plugin ya puede instalarse y probarse directamente en el entorno local sin necesidad de publicarlo en un repositorio remoto.
Durante la fase de depuración local, si la habilidad del plugin implica realizar invocaciones del modelo a diferentes proveedores para pruebas comparativas, un servicio proxy de API unificado puede reducir significativamente los costes de cambio de configuración. Al verificar la capacidad del servidor MCP del plugin, solemos apuntar la base_url al servicio proxy de API proporcionado por APIYI (apiyi.com). Con una sola clave API, puedes alternar entre diferentes modelos dentro del plugin, lo que facilita comparar el rendimiento de cada modelo bajo la misma lógica:
from openai import OpenAI
client = OpenAI(
api_key="your-apiyi-key",
base_url="https://api.apiyi.com/v1"
)
🎯 Consejo de depuración: Durante el desarrollo de plugins para Codex, a menudo es necesario probar repetidamente la calidad de respuesta del servidor MCP en diferentes modelos. Recomendamos utilizar la plataforma APIYI (apiyi.com) para gestionar de forma unificada la invocación del modelo, evitando tener que solicitar claves API individuales para cada modelo o mantener una lógica de invocación independiente, permitiéndote centrarte en pulir las funcionalidades del plugin.
Además de configurar manualmente las entradas del mercado local, puedes declarar la ruta del plugin local directamente en ~/.agents/plugins/marketplace.json (a nivel personal) o en .agents/plugins/marketplace.json en la raíz del repositorio (a nivel de equipo), estableciendo el campo source como local. Esto te permite completar la verificación de instalación sin tener que enviar nada a un servidor remoto.
Si tu plugin incluye una aplicación respaldada por MCP que requiere el modo desarrollador de ChatGPT para la depuración, existe otra ruta: activa el modo desarrollador en la configuración de ChatGPT, crea una aplicación respaldada por MCP, obtén el ID de la aplicación correspondiente y luego usa $plugin-creator para vincular este ID. Esto te permitirá verificar el flujo de datos entre el plugin y la aplicación en un entorno de conversación real. Este paso es mucho más cercano a la experiencia real tras el lanzamiento, por lo que te recomiendo realizarlo al menos una vez antes de enviar el plugin a revisión.
Registro en el mercado Git y distribución interna en el equipo
Una vez que el plugin ha sido validado localmente, la distribución dentro del equipo generalmente no requiere esperar una revisión oficial; basta con configurar un repositorio Git como fuente de mercado. Codex CLI ofrece un conjunto de comandos dedicados a la gestión del mercado:
| Comando | Propósito |
|---|---|
codex plugin marketplace add owner/repo |
Añade un repositorio de GitHub como fuente de mercado |
codex plugin marketplace add owner/repo --ref v2.1.0 |
Bloquea una rama o etiqueta específica para controlar el despliegue gradual |
codex plugin marketplace list |
Consulta la lista de mercados añadidos |
codex plugin marketplace upgrade |
Extrae las actualizaciones del mercado |
codex plugin marketplace remove |
Elimina una fuente de mercado |
Para equipos con repositorios de gran tamaño, también se puede utilizar el parámetro --sparse .agents/plugins para extraer solo el directorio relacionado con el plugin, evitando así que la clonación de todo el repositorio ralentice la instalación. Este modelo de mercado Git es ideal para cadenas de herramientas internas de empresas: no requiere una revisión pública y las actualizaciones del plugin solo necesitan que se envíe una nueva etiqueta (tag), permitiendo que los miembros del equipo sincronicen los cambios ejecutando un comando de actualización.
Desde una perspectiva práctica, el modelo de mercado Git tiene una ventaja oculta: permite desacoplar el ritmo de iteración del plugin del ritmo de lanzamiento interno del equipo. El código de negocio puede fusionarse varias veces al día, pero como el plugin es parte de una cadena de herramientas conversacional, una frecuencia de actualización demasiado alta podría interrumpir el modelo mental de los usuarios. Se recomienda vincular las versiones del plugin y las etiquetas a ventanas de lanzamiento fijas, por ejemplo, fusionando cambios cada una o dos semanas. Esto garantiza la velocidad de iteración de funciones sin obligar a los miembros del equipo a adaptarse constantemente a nuevas formas de interacción.
Proceso completo de envío y revisión al Marketplace oficial
La entrada de autoservicio para publicar en el Marketplace oficial aún no está completamente abierta; la documentación de OpenAI indica claramente que esta parte está "próxima a lanzarse". En la etapa actual, el envío formal para usuarios públicos sigue el proceso de revisión manual a través del portal de envío de plugins. Antes de enviar, es necesario completar la verificación de identidad: los desarrolladores individuales deben completar la "verificación individual", mientras que si se publica en nombre de una empresa, se debe completar la "verificación de negocio". Los revisores verificarán que la identidad de publicación coincida con los materiales presentados.
La lista de materiales necesarios para el envío formal es la siguiente:
| Categoría de material | Requisitos específicos |
|---|---|
| Información básica del plugin | Nombre, descripción, logotipo, categoría, URL relacionada |
| Servidor MCP | Dominio accesible públicamente, política CSP, configuración de autenticación |
| Cuenta de demostración | Acceso directo, sin requerir MFA o verificación secundaria por correo |
| Casos de prueba | Exactamente 5 escenarios positivos + 3 escenarios negativos |
| Etiquetado de herramientas | readOnlyHint, openWorldHint, destructiveHint deben coincidir con el comportamiento real |
El proceso de envío se divide en varios bloques de formulario: Info (información pública del listado), MCP (configuración de servidor y autenticación), Skills (carga del paquete de habilidades final), Prompts (ejemplos de indicación inicial), Testing (casos de prueba), Global (países y regiones disponibles), y finalmente el bloque Submit para completar las notas de publicación y confirmar las políticas. Una vez aprobada la revisión, el desarrollador elige el momento del lanzamiento en el portal, y el plugin aparecerá simultáneamente en el directorio unificado de plugins de ChatGPT y Codex.
Si el plugin incluye una aplicación respaldada por MCP, también es necesario verificar la propiedad del dominio, asegurando que el dominio donde se despliega el servidor MCP coincida con el dominio declarado por el plugin. El equipo de revisión se centrará en verificar si los resultados devueltos por la herramienta contienen datos personales o información de claves innecesarias; esto es algo que debe evitarse desde el diseño del formato de salida de la herramienta, en lugar de esperar a que sea rechazado en la revisión para realizar cambios.
Gestión de versiones y errores comunes
Una vez que el plugin está en línea, los detalles de la gestión de versiones afectan directamente la experiencia de actualización del usuario. El mercado utiliza el campo version para determinar si hay actualizaciones disponibles, por lo que es muy importante seguir estrictamente las normas de versionado semántico: usa el número de parche (patch) para corregir errores, el número menor (minor) para añadir nuevas capacidades y el número mayor (major) solo para cambios que rompan la compatibilidad.
Los plugins instalados se almacenan en la ruta local ~/.codex/plugins/cache/$MARKETPLACE_NAME/$PLUGIN_NAME/$VERSION/. Al investigar problemas del tipo "el plugin se actualizó pero el comportamiento no cambia", verificar si la caché se ha actualizado a la nueva versión suele ser más rápido que volver a depurar la lógica del código. En entornos empresariales, también te encontrarás con políticas de lista blanca forzadas por requirements.toml; el servidor MCP requiere que el nombre y la identidad coincidan, y cualquier discrepancia provocará que el servicio se deshabilite silenciosamente sin mensajes de error claros. Para estos casos, recomiendo probar la configuración de la política en un entorno de pruebas antes de pasar a producción.
La siguiente tabla resume algunos de los problemas más frecuentes reportados por los desarrolladores y cómo abordarlos:
| Problema común | Solución |
|---|---|
| Ruta del manifiesto escrita como absoluta | Cambiar a rutas relativas que comiencen con ./ |
| La invocación implícita activa un plugin no deseado | Usar @plugin-name para especificar el plugin explícitamente |
| El comportamiento no cambia tras actualizar | Verificar si el directorio de caché local del plugin se ha refrescado |
| MCP deshabilitado silenciosamente bajo políticas empresariales | Verificar que el nombre y la identidad coincidan en requirements.toml |
Antes de enviar el plugin para la revisión oficial, recomiendo ejecutar la herramienta de terceros codex-plugin-scanner. Esta herramienta evalúa el plugin basándose en dimensiones como la instalabilidad, el estado de mantenimiento, la seguridad MCP y la fuente de publicación. Especialmente para plugins destinados a clientes empresariales, detectar problemas con antelación ahorra mucho más tiempo que recibir un rechazo tras la revisión.
Otro detalle que suele pasarse por alto es la diferencia entre la invocación explícita y el descubrimiento implícito. Si no se especifica un plugin, Codex emparejará automáticamente las habilidades más relevantes según el contexto. Si tienes varios plugins con funciones similares instalados en el mismo espacio de trabajo, esta coincidencia implícita podría no seleccionar el que esperabas. Acostúmbrate a usar @plugin-name para declaraciones explícitas, especialmente en espacios de trabajo compartidos por equipos, lo que reducirá los costes de depuración por "conflictos entre plugins".
Preguntas frecuentes (FAQ) sobre el desarrollo de plugins para Codex
¿Cuál es la diferencia entre un plugin y un archivo SKILL.md independiente?
SKILL.md es un componente dentro de un plugin; cuando se usa solo, no requiere un manifiesto y puede ser descubierto automáticamente al colocarlo en el directorio .agents/skills/. Un plugin, por otro lado, empaqueta múltiples componentes como skills, servidores MCP y hooks en una unidad con identidad y gestión de versiones, ideal para escenarios que requieren distribución formal y seguimiento de actualizaciones.
¿Qué hago si necesito varias cuentas de modelos para pruebas comparativas durante el desarrollo?
Este es un problema real y común en el desarrollo de plugins, especialmente en aquellos que involucran la selección de modelos o el ajuste de la indicación. En lugar de abrir cuentas y gestionar claves para cada proveedor de modelos, es mejor usar una pasarela unificada como APIYI (apiyi.com). Puedes invocar modelos principales a través de una sola clave para realizar comparaciones A/B, centrando tus esfuerzos de depuración en la lógica del plugin y no en la gestión de cuentas.
¿Pueden coexistir la distribución en el mercado Git y la publicación en el Marketplace oficial?
Sí. Muchos equipos utilizan primero el mercado Git para validación interna y pruebas a pequeña escala, y una vez confirmada la estabilidad, proceden con el proceso de envío oficial. Ambos métodos de distribución no entran en conflicto y la estructura del manifiesto es universal.
¿Cuánto tiempo suele tardar la revisión del plugin?
La documentación oficial no especifica un periodo fijo, indicando solo que el proceso de revisión está en constante desarrollo y expansión, y no se admiten solicitudes de procesamiento urgente. Te sugiero considerar el periodo de revisión como una variable incierta en la planificación de tu proyecto. Preparar todos los materiales correctamente antes del envío para reducir la comunicación de ida y vuelta es la forma más práctica de acortar el tiempo total de lanzamiento.
Reflexiones finales
El núcleo de la dificultad en el desarrollo de plugins para Codex no reside realmente en el código en sí, sino en comprender los requisitos de la especificación del manifest y en la preparación de los materiales para el proceso de revisión; estos detalles no son tan complejos como parecen, pero es fácil que te rechacen el proyecto por un error en la ruta o un campo faltante. Te recomiendo seguir el orden: "validación con el entorno local → distribución a pequeña escala en el mercado Git → envío oficial para revisión", reservando tiempo para pruebas en entornos reales en cada paso. Si tu plugin implica la invocación del modelo múltiple o requiere cambiar frecuentemente de modelo para pruebas, el servicio proxy de API unificado que ofrece APIYI (apiyi.com) puede ahorrarte mucho tiempo de configuración, permitiéndote dedicar más energía a pulir el plugin en sí.
