Crear plugins
Crea, prueba y distribuye plugins para ChatGPT
Esta página está dirigida a los autores de plugins. Si quieres explorar, instalar y usar plugins con ChatGPT Work en la web o con ChatGPT Work o Codex en la aplicación de escritorio de ChatGPT, consulta Plugins. Si todavía estás perfeccionando un repositorio o un flujo de trabajo personal, comienza con una habilidad local. Crea un plugin cuando quieras compartir ese flujo de trabajo entre equipos, agrupar conectores o configuraciones de MCP, empaquetar hooks del ciclo de vida o publicar un paquete estable.
Un plugin puede incluir habilidades, una aplicación respaldada por MCP o ambas cosas. Si tu plugin necesita conectarse a un servicio o exponer herramientas mediante un servidor MCP, consulta Crear una aplicación.
Para ver ejemplos públicos completos, consulta Figma, Notion y Crear aplicaciones web.
Crear un plugin con @plugin-creator
Para configurarlo de la forma más rápida, usa la habilidad integrada @plugin-creator.
Esta genera la estructura del manifiesto obligatorio .codex-plugin/plugin.json y también puede
generar una entrada de marketplace local para las pruebas. Si ya tienes una carpeta de
plugin, también puedes usar @plugin-creator para conectarla a un
marketplace local.
Crear y probar localmente un plugin que apunte a una aplicación en modo de desarrollo respaldada por un servidor MCP
También puedes usar la habilidad plugin-creator si quieres probar localmente un plugin que incluya una aplicación respaldada por un servidor MCP. El plugin seguirá necesitando una carpeta y un manifiesto locales, pero la aplicación se inicia en el modo de desarrollador de ChatGPT.
Primero, activa el modo de desarrollador en ChatGPT:
- Abre ChatGPT.
- Abre Configuración.
- Selecciona Seguridad e inicio de sesión.
- Activa Modo de desarrollador.
Después, crea la aplicación en el modo de desarrollador:
- Abre Configuración → Plugins o la página Plugins.
- Selecciona el botón con el signo más.
- Completa el cuadro de diálogo para crear una aplicación en modo de desarrollador para tu servidor MCP.
- Cuando ChatGPT la haya creado, copia el ID de la aplicación de la URL del navegador. Comienza
por
plugin_asdk_app.
Proporciona ese ID plugin_asdk_app... a @plugin-creator en un chat de ChatGPT Work
o a $plugin-creator en Codex. Por ejemplo, con ChatGPT Work:
Instrucción para Plugin Creator@plugin-creator create a Codex plugin for my ChatGPT app.
Use plugin_asdk_app_6a4c0062f3b88191855c0a80eac5d53d and name it Acme Support.
Include a personal marketplace entry so I can test it locally.La habilidad plugin-creator creará la carpeta del plugin, generará el archivo obligatorio
.codex-plugin/plugin.json y añadirá la conexión de la aplicación para la aplicación de ChatGPT. Si le pides
que cree una entrada de marketplace personal, el plugin aparecerá en tu fuente local
del Directorio de plugins para que puedas probarlo.
Después de que la habilidad plugin-creator cree el plugin:
- Revisa
.app.jsony confirma que apunte al IDplugin_asdk_app...correcto. - Revisa
.codex-plugin/plugin.jsony asegúrate de que su campoappsapunte a./.app.json. - Añade cualquier habilidad incluida en
skills/si el plugin debe incluir flujos de trabajo repetibles junto con la aplicación. - Si la habilidad creó una entrada de marketplace personal, actualiza ChatGPT e instala el plugin desde tu fuente local en el Directorio de plugins. Después, pruébalo en un chat nuevo.
Para conocer la estructura del manifiesto y la disposición de los archivos, consulta Estructura de los plugins y Reglas de rutas.
Crear tu propia lista seleccionada de plugins
Un marketplace es un catálogo de plugins en formato JSON. @plugin-creator puede generar uno
para un solo plugin, y puedes seguir añadiendo entradas al mismo marketplace
para crear tu propia lista seleccionada para un repositorio, equipo o flujo de trabajo personal.
En ChatGPT Work o Codex en la aplicación de escritorio de ChatGPT, cada marketplace aparece como una
fuente seleccionable en el Directorio de plugins. Usa
$REPO_ROOT/.agents/plugins/marketplace.json para una lista limitada a un repositorio o
~/.agents/plugins/marketplace.json para una lista personal. Añade una entrada por
plugin en plugins[], haz que cada source.path apunte a la carpeta del plugin mediante una
ruta con el prefijo ./ relativa a la raíz del marketplace y establece
interface.displayName en la etiqueta que quieres que la aplicación muestre en el selector
de marketplaces. Después, reinicia la aplicación de escritorio de ChatGPT. A continuación, abre el Directorio
de plugins, elige tu marketplace y explora o instala los plugins de esa
lista seleccionada.
No necesitas un marketplace independiente para cada plugin. Un marketplace puede mostrar un solo plugin mientras lo pruebas y después convertirse en un catálogo seleccionado más amplio a medida que añadas más plugins.
Añadir un marketplace desde la CLI
Usa codex plugin marketplace add para añadir y hacer seguimiento de una fuente de marketplace en lugar
de editar config.toml manualmente. Estos comandos permiten crear plugins y
configurar catálogos. Usa la aplicación de escritorio de ChatGPT para instalar y probar un plugin local.
codex plugin marketplace add owner/repo
codex plugin marketplace add owner/repo --ref main
codex plugin marketplace add https://github.com/example/plugins.git --sparse .agents/plugins
codex plugin marketplace add ./local-marketplace-rootLas fuentes de marketplace pueden ser abreviaturas de GitHub (owner/repo o
owner/repo@ref), URL HTTP o HTTPS de Git, URL SSH de Git o directorios raíz de
marketplaces locales. Usa --ref para fijar una referencia de Git y repite --sparse PATH para usar un
checkout disperso en repositorios de marketplace respaldados por Git. --sparse solo es válido para
fuentes de marketplace de Git.
Para inspeccionar, actualizar o eliminar los marketplaces configurados:
codex plugin marketplace list
codex plugin marketplace upgrade
codex plugin marketplace upgrade marketplace-name
codex plugin marketplace remove marketplace-namecodex plugin marketplace list muestra cada marketplace que Codex está considerando
y la ruta raíz desde la que lo resuelve, incluidos los marketplaces locales predeterminados y
las instantáneas de marketplaces configurados.
Crear un plugin manualmente
Comienza con un plugin mínimo que empaquete una habilidad.
- Crea una carpeta de plugin con un manifiesto en
.codex-plugin/plugin.json.
mkdir -p my-first-plugin/.codex-pluginmy-first-plugin/.codex-plugin/plugin.json
{
"name": "my-first-plugin",
"version": "1.0.0",
"description": "Reusable greeting workflow",
"skills": "./skills/"
}Usa un name de plugin estable en kebab-case. Codex lo usa como identificador
del plugin y espacio de nombres de sus componentes.
- Añade una habilidad en
skills/<skill-name>/SKILL.md.
mkdir -p my-first-plugin/skills/hellomy-first-plugin/skills/hello/SKILL.md
---
name: hello
description: Greet the user with a friendly message.
---
Greet the user warmly and ask how you can help.- Añade el plugin a un marketplace. Usa
@plugin-creatorpara generar uno o sigue las instrucciones de Crear tu propia lista seleccionada de plugins para conectar manualmente el plugin con Codex.
A partir de ahí, puedes añadir la configuración de MCP, conectores o metadatos del marketplace según sea necesario.
Instalar manualmente un plugin local
Usa un marketplace de repositorio o un marketplace personal, según quién deba poder acceder al plugin o a la lista seleccionada.
Repositorio
Añade un archivo de marketplace en `$REPO_ROOT/.agents/plugins/marketplace.json`
y almacena tus plugins en `$REPO_ROOT/plugins/`.
**Ejemplo de marketplace de repositorio**
Paso 1: Copia la carpeta del plugin en `$REPO_ROOT/plugins/my-plugin`.mkdir -p ./plugins
cp -R /absolute/path/to/my-plugin ./plugins/my-pluginPaso 2: Añade o actualiza `$REPO_ROOT/.agents/plugins/marketplace.json` para que
`source.path` apunte a ese directorio del plugin mediante una ruta relativa con el prefijo `./`:{
"name": "local-repo",
"plugins": [
{
"name": "my-plugin",
"source": {
"source": "local",
"path": "./plugins/my-plugin"
},
"policy": {
"installation": "AVAILABLE",
"authentication": "ON_INSTALL"
},
"category": "Productivity"
}
]
}Paso 3: Reinicia la aplicación de escritorio de ChatGPT y comprueba que aparezca el plugin.Personal
Añade un archivo de marketplace en `~/.agents/plugins/marketplace.json` y almacena
tus plugins en `~/.codex/plugins/`.
**Ejemplo de marketplace personal**
Paso 1: Copia la carpeta del plugin en `~/.codex/plugins/my-plugin`.mkdir -p ~/.codex/plugins
cp -R /absolute/path/to/my-plugin ~/.codex/plugins/my-pluginPaso 2: Añade o actualiza `~/.agents/plugins/marketplace.json` para que el campo
`source.path` de la entrada del plugin apunte a ese directorio.
Paso 3: Reinicia la aplicación de escritorio de ChatGPT y comprueba que aparezca el plugin.El archivo de marketplace apunta a la ubicación del plugin, por lo que esos directorios son
ejemplos y no requisitos fijos. Codex resuelve source.path con relación
a la raíz del marketplace, no con relación a la carpeta .agents/plugins/. Consulta
Metadatos del marketplace para conocer el formato del archivo.
Después de modificar el plugin, actualiza el directorio del plugin al que apunta la entrada del marketplace y reinicia la aplicación de escritorio de ChatGPT para que la instalación local incorpore los archivos nuevos.
Compartir un plugin local con tu espacio de trabajo
Después de crear un plugin, añádelo desde la aplicación de escritorio de ChatGPT. Selecciona ChatGPT y cambia a Work en el selector, o selecciona Codex y después abre Plugins. A continuación, puedes compartirlo con otros miembros de tu espacio de trabajo de ChatGPT.
- Abre Plugins en la aplicación de escritorio de ChatGPT.
- Ve a Creado por ti y abre la página de detalles del plugin.
- Selecciona Compartir.
- Añade miembros o grupos del espacio de trabajo, o copia un enlace para compartir.
- Elige quién tiene acceso y envía la invitación o el enlace.
Las personas con las que lo compartas podrán encontrar el plugin en Compartido contigo dentro del Directorio de plugins. Compartir un plugin local con tu espacio de trabajo no lo publica en el Directorio de plugins público. Los plugins compartidos permanecen dentro de los límites de tu espacio de trabajo y organización; las cuentas que no hayan iniciado sesión en ese espacio de trabajo no podrán acceder a ellos. Usa grupos cuando un equipo o rol deba compartir el mismo acceso al plugin. Usa un marketplace cuando quieras distribuirlo mediante un repositorio o la CLI, y usa la opción de compartir con el espacio de trabajo cuando quieras que determinados compañeros instalen un plugin desde la aplicación de escritorio de ChatGPT.
Los administradores del espacio de trabajo pueden desactivar el uso compartido de plugins desde los requisitos administrados en la nube
si añaden features.plugin_sharing = false a requirements.toml:
features.plugin_sharing = falseMetadatos del marketplace
Si mantienes un marketplace de repositorio, defínelo en
$REPO_ROOT/.agents/plugins/marketplace.json. Para un marketplace personal, usa
~/.agents/plugins/marketplace.json. Un archivo de marketplace controla el orden de los plugins
y las políticas de instalación en la aplicación de escritorio de ChatGPT. Puede representar un solo
plugin mientras lo pruebas o una lista seleccionada de plugins que quieres que la aplicación
muestre juntos bajo un mismo nombre de marketplace. Antes de añadir un plugin a un
marketplace, asegúrate de que su version, los metadatos del editor y el texto visible
en la interfaz de instalación estén listos para que otros desarrolladores los vean.
{
"name": "local-example-plugins",
"interface": {
"displayName": "Local Example Plugins"
},
"plugins": [
{
"name": "my-plugin",
"source": {
"source": "local",
"path": "./plugins/my-plugin"
},
"policy": {
"installation": "AVAILABLE",
"authentication": "ON_INSTALL"
},
"category": "Productivity"
},
{
"name": "research-helper",
"source": {
"source": "local",
"path": "./plugins/research-helper"
},
"policy": {
"installation": "AVAILABLE",
"authentication": "ON_INSTALL"
},
"category": "Productivity"
}
]
}- Usa
nameen el nivel superior para identificar el marketplace. - Usa
interface.displayNamepara el título del marketplace que se muestra en la aplicación de escritorio de ChatGPT. - Añade un objeto por plugin en
pluginspara crear una lista seleccionada que la aplicación muestra bajo el título de ese marketplace. - Dirige el
source.pathde cada entrada de plugin al directorio del plugin que quieres que Codex cargue. En las instalaciones desde repositorios, suele estar en./plugins/. En las instalaciones personales, un patrón habitual es./.codex/plugins/<plugin-name>. - Mantén
source.pathrelativo a la raíz del marketplace, haz que comience por./y mantenlo dentro de esa raíz. - Para las entradas locales,
sourcetambién puede ser una ruta como cadena de texto simple, por ejemplo"./plugins/my-plugin". - Incluye siempre
policy.installation,policy.authenticationycategoryen cada entrada de plugin. - Usa valores de
policy.installationcomoAVAILABLE,INSTALLED_BY_DEFAULToNOT_AVAILABLE. - Usa
policy.authenticationpara decidir si la autenticación se realiza durante la instalación o en el primer uso.
El marketplace controla desde dónde carga Codex el plugin. Un valor local de
source.path puede apuntar a otro lugar si tu plugin se encuentra fuera de esos
directorios de ejemplo. Un archivo de marketplace puede encontrarse en el repositorio donde
estás desarrollando el plugin o en un repositorio de marketplace independiente, y un mismo archivo de
marketplace puede apuntar a uno o varios plugins.
Las entradas del marketplace también pueden apuntar a fuentes de plugins respaldadas por Git. Usa
"source": "url" cuando el plugin se encuentre en la raíz del repositorio o
"source": "git-subdir" cuando esté en un subdirectorio:
{
"name": "remote-helper",
"source": {
"source": "git-subdir",
"url": "https://github.com/example/codex-plugins.git",
"path": "./plugins/remote-helper",
"ref": "main"
},
"policy": {
"installation": "AVAILABLE",
"authentication": "ON_INSTALL"
},
"category": "Productivity"
}Las entradas respaldadas por Git pueden usar selectores ref o sha. Si Codex no puede resolver el
origen de una entrada del marketplace, omite esa entrada de plugin en lugar de provocar un error en
todo el marketplace.
Las entradas del marketplace también pueden instalar un plugin desde un registro de paquetes de JavaScript:
{
"name": "npm-helper",
"source": {
"source": "npm",
"package": "@example/codex-plugin",
"version": "^1.2.0",
"registry": "https://registry.npmjs.org"
},
"policy": {
"installation": "AVAILABLE",
"authentication": "ON_INSTALL"
},
"category": "Productivity"
}package es obligatorio y puede incluir un ámbito del registro. version es opcional
y acepta versiones de paquetes, etiquetas de distribución e intervalos de versiones, pero no
selectores de ruta o URL.
registry es opcional y debe ser una URL HTTPS sin credenciales incrustadas,
consultas ni fragmentos. Codex descarga el paquete sin ejecutar scripts del ciclo de vida.
La CLI npm debe estar instalada, y la autenticación del registro procede
de su configuración.
Cómo usa los marketplaces la aplicación de escritorio de ChatGPT
Un marketplace de plugins es un catálogo JSON de plugins que la aplicación de escritorio de ChatGPT puede leer e instalar.
La aplicación puede leer archivos de marketplace desde:
- el marketplace seleccionado que sustenta el directorio oficial de plugins
- un marketplace de repositorio en
$REPO_ROOT/.agents/plugins/marketplace.json - un marketplace compatible con versiones anteriores en
$REPO_ROOT/.claude-plugin/marketplace.json - un marketplace personal en
~/.agents/plugins/marketplace.json
Puedes instalar cualquier plugin disponible mediante un marketplace. La aplicación instala
los plugins en
~/.codex/plugins/cache/$MARKETPLACE_NAME/$PLUGIN_NAME/$VERSION/. Para los plugins
locales, $VERSION es local, y la aplicación carga la copia instalada desde esa
ruta de caché en lugar de hacerlo directamente desde la entrada del marketplace.
Puedes activar o desactivar cada plugin de forma individual. La aplicación almacena el estado
activado o desactivado de cada plugin en ~/.codex/config.toml.
Empaquetar y distribuir plugins
Estructura de los plugins
Cada plugin tiene un manifiesto en .codex-plugin/plugin.json. También puede incluir
un directorio skills/, un directorio hooks/ para enlaces del ciclo de vida, un archivo .app.json
que apunte a uno o varios conectores, un archivo .mcp.json que
configure servidores MCP y recursos usados para presentar el plugin en las
superficies compatibles.
my-plugin/
├── .codex-plugin/
│ └── plugin.json # Required: plugin manifest
├── skills/
│ └── my-skill/
│ └── SKILL.md # Optional: skill instructions
├── hooks/
│ └── hooks.json # Optional: lifecycle hooks
├── .app.json # Optional: app or connector mappings
├── .mcp.json # Optional: MCP server configuration
└── assets/ # Optional: icons, logos, screenshotsSolo plugin.json debe estar en .codex-plugin/. Mantén skills/, hooks/,
assets/, .mcp.json y .app.json en la raíz del plugin.
Los plugins publicados suelen usar un manifiesto más completo que el ejemplo mínimo que aparece en los esqueletos de inicio rápido. El manifiesto tiene tres funciones:
- Identificar el plugin.
- Apuntar a componentes incluidos, como habilidades, conectores, servidores MCP o enlaces.
- Proporcionar metadatos para las superficies de instalación, como descripciones, iconos y enlaces legales.
Este es un ejemplo de manifiesto completo:
{
"name": "my-plugin",
"version": "0.1.0",
"description": "Bundle reusable skills and connectors.",
"author": {
"name": "Your team",
"email": "team@example.com",
"url": "https://example.com"
},
"homepage": "https://example.com/plugins/my-plugin",
"repository": "https://github.com/example/my-plugin",
"license": "MIT",
"keywords": ["research", "crm"],
"skills": "./skills/",
"mcpServers": "./.mcp.json",
"apps": "./.app.json",
"hooks": "./hooks/hooks.json",
"interface": {
"displayName": "My Plugin",
"shortDescription": "Reusable skills and connectors",
"longDescription": "Distribute skills and connectors together.",
"developerName": "Your team",
"category": "Productivity",
"capabilities": ["Read", "Write"],
"websiteURL": "https://example.com",
"privacyPolicyURL": "https://example.com/privacy",
"termsOfServiceURL": "https://example.com/terms",
"defaultPrompt": [
"Use My Plugin to summarize new CRM notes.",
"Use My Plugin to triage new customer follow-ups."
],
"brandColor": "#10A37F",
"composerIcon": "./assets/icon.png",
"logo": "./assets/logo.png",
"screenshots": ["./assets/screenshot-1.png"]
}
}.codex-plugin/plugin.json es el punto de entrada obligatorio. Los demás campos del manifiesto
son opcionales, pero los plugins publicados suelen utilizarlos.
Campos del manifiesto
Usa los campos del nivel superior para definir los metadatos del paquete y apuntar a los componentes incluidos:
name,versionydescriptionidentifican el plugin.author,homepage,repository,licenseykeywordsproporcionan metadatos del editor y de descubrimiento.skills,mcpServers,appsyhooksapuntan a componentes incluidos mediante rutas relativas a la raíz del plugin.interfacecontrola cómo presentan el plugin las superficies de instalación.
Usa el objeto interface para los metadatos de las superficies de instalación:
displayName,shortDescriptionylongDescriptioncontrolan el título y el texto descriptivo.developerName,categoryycapabilitiesañaden metadatos del editor y de capacidades.websiteURL,privacyPolicyURLytermsOfServiceURLproporcionan enlaces externos.defaultPrompt,brandColor,composerIcon,logoyscreenshotscontrolan las indicaciones iniciales y la presentación visual.
Reglas para las rutas
- Mantén las rutas del manifiesto relativas a la raíz del plugin y haz que comiencen por
./. - Guarda los recursos visuales, como
composerIcon,logoyscreenshots, en./assets/siempre que sea posible. - Usa
skillspara las carpetas de habilidades incluidas,appspara.app.json,mcpServerspara.mcp.jsonyhookspara los enlaces del ciclo de vida. - Los plugins activados pueden incluir enlaces del ciclo de vida junto con habilidades, servidores MCP y conectores.
- Si tu plugin almacena los enlaces en
./hooks/hooks.json, no necesitas una entradahooksen.codex-plugin/plugin.json; Codex comprueba automáticamente ese archivo predeterminado.
Servidores MCP y enlaces del ciclo de vida incluidos
mcpServers puede apuntar a un archivo .mcp.json que contenga un mapa directo de
servidores o un objeto mcp_servers contenedor.
Mapa directo de servidores:
{
"docs": {
"command": "docs-mcp",
"args": ["--stdio"]
}
}Mapa de servidores dentro de un contenedor:
{
"mcp_servers": {
"docs": {
"command": "docs-mcp",
"args": ["--stdio"]
}
}
}Tras la instalación, los usuarios pueden activar o desactivar un servidor MCP incluido y ajustar
la política de aprobación de herramientas desde su configuración de Codex sin editar el plugin. Usa
plugins.<plugin>.mcp_servers.<server> para la política del servidor MCP específica del plugin:
[plugins."my-plugin".mcp_servers.docs]
enabled = true
default_tools_approval_mode = "prompt"
enabled_tools = ["search"]
[plugins."my-plugin".mcp_servers.docs.tools.search]
approval_mode = "approve"Cuando tu plugin está activado, Codex puede cargar los enlaces del ciclo de vida de tu plugin junto con los enlaces del usuario, del proyecto y administrados.
Instalar o activar un plugin no implica confiar automáticamente en sus enlaces. Los enlaces incluidos con plugins no son enlaces administrados, por lo que Codex los omite hasta que el usuario revise y considere de confianza la definición actual del enlace.
El archivo predeterminado de enlaces del plugin es hooks/hooks.json:
{
"hooks": {
"SessionStart": [
{
"hooks": [
{
"type": "command",
"command": "python3 ${PLUGIN_ROOT}/hooks/session_start.py",
"statusMessage": "Loading plugin context"
}
]
}
]
}
}Si defines hooks en .codex-plugin/plugin.json, Codex usa esa entrada del
manifiesto en lugar del valor predeterminado hooks/hooks.json. El campo del manifiesto puede ser una
sola ruta, una matriz de rutas, un objeto de enlaces insertado o una matriz de objetos de
enlaces insertados.
{
"name": "repo-policy",
"hooks": ["./hooks/session.json", "./hooks/tools.json"]
}Las rutas de los enlaces siguen las mismas reglas del manifiesto que skills, apps y
mcpServers: deben comenzar por ./, resolverse de forma relativa a la raíz del plugin y permanecer
dentro de la raíz del plugin.
Los comandos de enlaces del plugin reciben las variables de entorno específicas de Codex
PLUGIN_ROOT y PLUGIN_DATA. PLUGIN_ROOT apunta a la raíz del plugin instalado
y PLUGIN_DATA apunta al directorio de datos con permiso de escritura del plugin. Codex
también establece CLAUDE_PLUGIN_ROOT y CLAUDE_PLUGIN_DATA para mantener la compatibilidad con los
enlaces de plugins existentes.
Los enlaces de plugins usan el mismo esquema de eventos que los enlaces normales. Consulta Enlaces para conocer los eventos, las entradas y las salidas compatibles, la revisión de confianza y las limitaciones actuales.
Publicar plugins públicos oficiales
Para publicar un plugin para uso público, envíalo a través del portal de envío de plugins. Consulta Enviar plugins para conocer el proceso completo de revisión y publicación.