Español

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.

Habilidad de creación de plugins en ChatGPT

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.

Cómo invocar la habilidad plugin-creator

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:

  1. Abre ChatGPT.
  2. Abre Configuración.
  3. Selecciona Seguridad e inicio de sesión.
  4. Activa Modo de desarrollador.

Después, crea la aplicación en el modo de desarrollador:

  1. Abre Configuración → Plugins o la página Plugins.
  2. Selecciona el botón con el signo más.
  3. Completa el cuadro de diálogo para crear una aplicación en modo de desarrollador para tu servidor MCP.
  4. 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:

  1. Revisa .app.json y confirma que apunte al ID plugin_asdk_app... correcto.
  2. Revisa .codex-plugin/plugin.json y asegúrate de que su campo apps apunte a ./.app.json.
  3. Añade cualquier habilidad incluida en skills/ si el plugin debe incluir flujos de trabajo repetibles junto con la aplicación.
  4. 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.

Marketplace local personalizado en el Directorio de 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-root

Las 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-name

codex 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.

  1. Crea una carpeta de plugin con un manifiesto en .codex-plugin/plugin.json.
mkdir -p my-first-plugin/.codex-plugin

my-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.

  1. Añade una habilidad en skills/<skill-name>/SKILL.md.
mkdir -p my-first-plugin/skills/hello

my-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.
  1. Añade el plugin a un marketplace. Usa @plugin-creator para 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-plugin
Paso 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-plugin
Paso 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.

  1. Abre Plugins en la aplicación de escritorio de ChatGPT.
  2. Ve a Creado por ti y abre la página de detalles del plugin.
  3. Selecciona Compartir.
  4. Añade miembros o grupos del espacio de trabajo, o copia un enlace para compartir.
  5. 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 = false

Metadatos 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 name en el nivel superior para identificar el marketplace.
  • Usa interface.displayName para el título del marketplace que se muestra en la aplicación de escritorio de ChatGPT.
  • Añade un objeto por plugin en plugins para crear una lista seleccionada que la aplicación muestra bajo el título de ese marketplace.
  • Dirige el source.path de 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.path relativo a la raíz del marketplace, haz que comience por ./ y mantenlo dentro de esa raíz.
  • Para las entradas locales, source también puede ser una ruta como cadena de texto simple, por ejemplo "./plugins/my-plugin".
  • Incluye siempre policy.installation, policy.authentication y category en cada entrada de plugin.
  • Usa valores de policy.installation como AVAILABLE, INSTALLED_BY_DEFAULT o NOT_AVAILABLE.
  • Usa policy.authentication para 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, screenshots

Solo 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, version y description identifican el plugin.
  • author, homepage, repository, license y keywords proporcionan metadatos del editor y de descubrimiento.
  • skills, mcpServers, apps y hooks apuntan a componentes incluidos mediante rutas relativas a la raíz del plugin.
  • interface controla cómo presentan el plugin las superficies de instalación.

Usa el objeto interface para los metadatos de las superficies de instalación:

  • displayName, shortDescription y longDescription controlan el título y el texto descriptivo.
  • developerName, category y capabilities añaden metadatos del editor y de capacidades.
  • websiteURL, privacyPolicyURL y termsOfServiceURL proporcionan enlaces externos.
  • defaultPrompt, brandColor, composerIcon, logo y screenshots controlan 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, logo y screenshots, en ./assets/ siempre que sea posible.
  • Usa skills para las carpetas de habilidades incluidas, apps para .app.json, mcpServers para .mcp.json y hooks para 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 entrada hooks en .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.