Administración de plugins

Antes de empezar

Los administradores del espacio de trabajo pueden importar un marketplace de plugins desde GitHub y mantener sus plugins actualizados desde el repositorio. Un marketplace es un catálogo JSON que enumera los plugins que se importarán.

Esta página explica la importación y la sincronización del espacio de trabajo. Para configurar marketplaces directamente en los clientes locales mediante config.toml administrado desde la nube o del sistema, consulta Configurar marketplaces de plugins y valores predeterminados. Para habilitar o deshabilitar plugins en un proyecto específico, consulta Habilitar o deshabilitar un plugin para un repositorio.

Utiliza una cuenta de GitHub que pueda leer el repositorio del marketplace y cualquier otro repositorio al que haga referencia. Se admiten repositorios públicos y privados de GitHub. Completa cualquier aprobación de la organización de GitHub necesaria para acceder a los repositorios antes de realizar la importación.

Revisa el contenido del repositorio antes de importarlo. Los plugins nuevos comienzan con la instalación Available y la autenticación durante la instalación. Los marketplaces nuevos tienen habilitada la sincronización diaria automática. La importación procesa todas las entradas válidas, y las sincronizaciones futuras añaden automáticamente cualquier plugin nuevo del repositorio.

Configurar la sincronización de un marketplace

1. Abre Admin > Plugins y selecciona Add > Import marketplace.
2. En Source, introduce la URL del repositorio, como https://github.com/example/team-plugins. Utiliza únicamente la URL del repositorio, sin la URL de una rama o carpeta.
3. Si el marketplace se encuentra en un subdirectorio, introduce ese directorio en Path. Por ejemplo, utiliza team-tools para team-tools/.agents/plugins/marketplace.json. Deja Path vacío para utilizar la raíz del repositorio. No introduzcas el nombre del archivo de manifiesto.
4. Opcionalmente, introduce una Branch, tag, or commit. Déjalo vacío para utilizar la rama predeterminada del repositorio. Utiliza una rama para recibir confirmaciones futuras; una confirmación fija permanece en esa revisión.
5. Selecciona Import marketplace y autoriza el acceso a GitHub cuando se te solicite. La importación inicial puede tardar hasta una hora en marketplaces muy grandes. Las sincronizaciones diarias posteriores suelen tardar unos minutos.
6. Revisa Import results y, a continuación, abre cada plugin importado para configurar su política de instalación y las aplicaciones necesarias.

Para solicitar una actualización sin esperar a la sincronización diaria, abre el marketplace en Admin > Plugins > Marketplaces y selecciona Sync now.

Formatos compatibles

El directorio seleccionado debe contener uno de estos archivos:

En un marketplace, las entradas pueden hacer referencia a plugins nativos con .codex-plugin/plugin.json, plugins compatibles con Claude, paquetes de Agent Plugins 1.0 o paquetes de skills compatibles.

En un marketplace de Codex, utiliza rutas locales para los plugins del mismo repositorio:

{
  "name": "team-plugins",
  "interface": {
    "displayName": "Team plugins"
  },
  "plugins": [
    {
      "name": "team-tools",
      "source": {
        "source": "local",
        "path": "./plugins/team-tools"
      }
    }
  ]
}

La ruta es relativa a la raíz seleccionada del marketplace, no a .agents/plugins/.

Un marketplace compatible con Claude puede utilizar una cadena de ruta para cada plugin local:

{
  "name": "team-plugins",
  "plugins": [
    {
      "name": "team-tools",
      "source": "./plugins/team-tools"
    }
  ]
}

Las entradas de un marketplace de Codex también admiten source: "url" para un plugin situado en la raíz de un repositorio de GitHub y source: "git-subdir" para un plugin en un subdirectorio de GitHub. Por ejemplo:

{
  "name": "team-tools",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/example/team-tools.git",
    "path": "./plugins/team-tools",
    "ref": "main"
  }
}

Los orígenes de Git pueden seleccionar un ref o un sha de confirmación completo de 40 caracteres. La cuenta de GitHub que concede la autorización debe poder leer todos los repositorios referenciados. Actualmente, la importación del espacio de trabajo solo admite repositorios de GitHub.

Configurar el acceso al espacio de trabajo

La importación y la sincronización desde GitHub no aplican políticas de instalación o autenticación del repositorio, incluidas AVAILABLE, INSTALLED_BY_DEFAULT, NOT_AVAILABLE, ON_INSTALL y ON_USE. Los administradores del espacio de trabajo configuran estas opciones para cada plugin. Sincronizar una actualización o trasladar un plugin existente a la administración mediante GitHub conserva sus políticas del espacio de trabajo.

Utiliza Installation policy para elegir Available o Installed para cada rol admisible. También deben estar habilitadas las aplicaciones necesarias, y los miembros deben tener acceso al servicio conectado. Importar un plugin no concede acceso a una aplicación ni conecta las cuentas de los miembros. Consulta Controles de plugins para obtener información sobre los controles de roles, aplicaciones y acciones.

Trasladar un plugin existente a la administración mediante GitHub

Añade pluginId a la entrada del marketplace correspondiente al plugin existente:

{
  "name": "team-tools",
  "pluginId": "plugin_0123456789abcdef0123456789abcdef",
  "source": {
    "source": "local",
    "path": "./plugins/team-tools"
  }
}

Abre el plugin desde Admin > Plugins y copia el ID que aparece después de /admin/plugins/ en su URL. Coloca pluginId junto a name y source en la entrada del marketplace. El plugin existente debe encontrarse en el mismo espacio de trabajo.

Esto traslada un plugin cargado o no administrado de otro modo a la administración mediante GitHub. El plugin conserva su ID, su uso compartido y sus políticas del espacio de trabajo. Las futuras actualizaciones proceden de GitHub; las cargas de archivos ya no pueden sustituir el plugin administrado. Un plugin ya administrado por otro origen de GitHub no se puede asumir de este modo.

Plugins exclusivos para escritorio

Cualquier plugin importado que declare MCP servers en mcp.json o .mcp.json se marca como Desktop only y solo funciona en la aplicación de escritorio de ChatGPT. Esto incluye servidores que utilizan una URL HTTPS remota. La misma restricción se aplica a otras formas compatibles de configuración de MCP, como las declaraciones de servidor insertadas.

Hacer referencia a una aplicación existente con .app.json

Añade .app.json en la raíz del plugin. El nombre de archivo incluye un punto inicial; app.json sin el punto no es compatible.

{
  "apps": {
    "team-tools": {
      "id": "asdk_app_example",
      "required": true
    }
  }
}

Sustituye asdk_app_example por el ID de la aplicación existente. Los ID de aplicación compatibles comienzan por asdk_app_, connector_ o templated_apps_. Utiliza el ID de la aplicación, no un ID de plugin_.... Por ejemplo, una URL de plugin que contenga plugin_asdk_app_example representa la aplicación asdk_app_example.

La clave team-tools asigna un nombre a la referencia dentro de este archivo. Establece required en true cuando el plugin dependa de la aplicación. Puedes añadir más entradas para hacer referencia a otras aplicaciones existentes.

En un plugin nativo, establece apps en ./.app.json dentro de .codex-plugin/plugin.json. Este es un manifiesto completo para este ejemplo:

{
  "name": "team-tools",
  "version": "1.0.0",
  "description": "Use the team's approved tools.",
  "author": {
    "name": "Example team"
  },
  "apps": "./.app.json",
  "interface": {
    "displayName": "Team tools",
    "shortDescription": "Use approved team tools",
    "longDescription": "Connect to the team's existing app.",
    "developerName": "Example team",
    "category": "Productivity",
    "capabilities": ["Read"]
  }
}

Mantén los archivos con esta estructura:

team-plugins/
├── .agents/plugins/marketplace.json
└── plugins/team-tools/
    ├── .codex-plugin/plugin.json
    └── .app.json

La referencia no crea una aplicación ni concede permisos. Los administradores deben hacer que la aplicación esté disponible para los roles previstos, y los miembros deben completar cualquier autenticación necesaria. Se siguen aplicando los permisos existentes de la aplicación, los controles de acciones y el acceso al servicio.

Mantener actualizados los plugins

Los marketplaces nuevos buscan actualizaciones diariamente. Abre Admin > Plugins > Marketplaces, selecciona el marketplace y elige Sync now para solicitar una actualización sin esperar a la sincronización automática.

La sincronización puede añadir nuevas entradas del marketplace y actualizar los plugins existentes. Revisa los cambios del repositorio antes de fusionarlos, ya que la sincronización automática importará cualquier plugin nuevo.

Después de una sincronización, revisa el estado y el informe guardado. Completed — N errors significa que el proceso terminó, pero algunos plugins no se pudieron procesar. Si una actualización de un plugin existente no es válida, se conserva su última versión funcional. Corrige en GitHub el problema indicado y selecciona Sync now para volver a intentarlo.

Eliminar una entrada del repositorio no elimina su copia importada del espacio de trabajo. Se marca como No longer in source. Eliminar el marketplace en ChatGPT elimina todos los plugins importados desde él.

Volver a conectar o cambiar el acceso a GitHub

Para volver a conectar el acceso a GitHub, confirma primero que la cuenta de GitHub utilizada para la importación todavía tenga acceso al repositorio y a cualquier repositorio referenciado. A continuación, el administrador que importó originalmente el marketplace debe abrir el plugin de GitHub en ChatGPT y volver a conectar su cuenta, ya que la sincronización del marketplace utiliza la conexión de GitHub de ese administrador.

Para transferir la propiedad a un nuevo administrador, el nuevo administrador del espacio de trabajo debe abrir Admin > Plugins > Add > Import marketplace e importar el mismo marketplace utilizando los mismos valores de Source, Path y Branch, tag, or commit. Las sincronizaciones futuras utilizarán su conexión de GitHub.

No elimines el marketplace únicamente para volver a conectarlo o cambiar su propietario: al eliminarlo, también se eliminan sus plugins importados.