Le système de plugins de Codex CLI prend rapidement forme. La commande /plugins permet désormais de parcourir, d'installer, d'activer et de désactiver des plugins par marché, et de plus en plus d'équipes emballent leurs chaînes d'outils internes sous forme de plugins Codex réutilisables. Cependant, l'accès à la publication en libre-service sur la Marketplace officielle est actuellement en phase de "validation". Les développeurs doivent d'abord comprendre la structure du manifeste et les méthodes de débogage local avant de suivre le processus de soumission pour que leur plugin soit réellement accessible aux utilisateurs. Cet article détaille, étape par étape, le parcours complet : de la création initiale et des tests locaux à la distribution via Git et la validation officielle, tout en soulignant les pièges courants à éviter.
De quoi se compose un plugin Codex ?
Un plugin Codex est essentiellement un regroupement de plusieurs capacités dans une unité installable et distribuable. Selon la documentation officielle d'OpenAI, les plugins peuvent inclure des skills (instructions de tâches réutilisables), des applications basées sur MCP (services connectant des outils externes), des hooks de cycle de vie, ainsi que des extensions de navigateur et des modèles de tâches planifiées optionnels. Ces composants ne doivent pas nécessairement tous être présents ; un plugin léger ne contenant que des skills peut être installé et utilisé normalement.
Comprendre les responsabilités de chaque composant est la condition préalable à la rédaction d'un manifeste conforme. Le tableau ci-dessous récapitule les chemins d'accès et les rôles des quatre composants principaux dans un répertoire de plugin Codex :
| Composant | Chemin d'accès | Rôle | Obligatoire |
|---|---|---|---|
| plugin.json | .codex-plugin/plugin.json |
Identité et méta-informations du plugin | Oui |
| skills | skills/<skill-name>/SKILL.md |
Définition des instructions de tâches réutilisables | Non |
| Serveurs MCP | .mcp.json |
Configuration de la connexion aux services d'outils externes | Non |
| hooks | hooks/hooks.json |
Déclaration des commandes de hooks de cycle de vie | Non |
Il est intéressant de noter que si le plugin n'est qu'un fichier SKILL.md réutilisé en interne par l'équipe, il n'est pas nécessaire de passer par le processus complet du manifeste : placez simplement le fichier dans le répertoire .agents/skills/ et Codex le détectera automatiquement. C'est une étape intermédiaire courante pour de nombreuses équipes passant de "scripts internes" à des "plugins officiels".
Le champ d'application des capacités d'un plugin est plus large que beaucoup ne l'imaginent. Outre les skills et les applications basées sur MCP, la documentation officielle mentionne que les plugins peuvent inclure des déclarations de capacités nécessaires aux extensions de navigateur, ainsi que des modèles de tâches planifiées. Cela signifie qu'un plugin peut gérer à la fois des requêtes interactives "déclenchées par l'utilisateur" et des scénarios d'automatisation "exécutés périodiquement en arrière-plan". Choisir quels composants combiner dans un même plugin revient essentiellement à trouver un équilibre entre l'expérience d'installation et les coûts de maintenance : plus il y a de composants, plus le plugin est complet, mais plus les documents de validation et les cas de test augmentent. Il est préférable de bien réfléchir aux besoins réels de vos utilisateurs finaux avant la soumission, plutôt que de tout entasser dans un seul paquet.
Commencer par plugin.json : tout sur le fichier manifeste de votre plugin
Le fichier plugin.json est la carte d'identité de votre plugin ; c'est lui qui détermine comment Codex l'identifie, le charge et l'affiche. Un manifeste minimaliste ne nécessite que trois champs :
{
"name": "my-first-plugin",
"version": "1.0.0",
"description": "Flux de travail de salutation réutilisable",
"skills": "./skills/"
}
Pour le champ name, nous recommandons d'utiliser une convention kebab-case stable. Ne modifiez pas cet identifiant lors des mises à jour, sinon la place de marché ne pourra pas reconnaître qu'il s'agit d'une nouvelle version du même plugin. Le champ version doit suivre les règles du versionnage sémantique ; la place de marché s'appuie sur ce champ pour savoir si une mise à jour doit être proposée à l'utilisateur. Tous les chemins référencés dans le manifeste doivent être relatifs à la racine du plugin, commencer par ./ et ne pas sortir de ce répertoire racine.
Au-delà de ces trois champs de base, skills peut également pointer vers un tableau de répertoires de compétences, tandis que les champs hooks, mcpServers et apps pointent respectivement vers les fichiers de configuration hooks/hooks.json, .mcp.json et .app.json. Cette conception "un champ par fichier" permet de garder le manifeste léger. Les descriptions détaillées des compétences et les configurations des outils sont maintenues dans des fichiers séparés, ce qui facilite le travail collaboratif et évite les conflits lors de modifications simultanées sur différents composants.
Si vous prévoyez de soumettre votre plugin à la place de marché officielle, vous devrez ajouter un ensemble de métadonnées destinées à l'affichage. Le tableau suivant liste les champs clés recommandés lors de la phase de publication :
| Champ | Type | Description |
|---|---|---|
| author / repository | Chaîne | Identifie la source du plugin, doit correspondre à l'identité vérifiée |
| interface.displayName | Chaîne | Nom du plugin affiché dans la liste de la place de marché |
| interface.category | Chaîne | Catégorie du plugin, influence le parcours de navigation |
| interface.capabilities | Tableau | Étiquettes déclarant les capacités du plugin |
| mcpServers / apps / hooks | Objet | Pointe vers les fichiers de configuration des composants correspondants |
L'erreur la plus courante lors de la rédaction du manifeste est une mauvaise référence de chemin — par exemple, utiliser un chemin absolu pour le champ skills ou oublier le ./ initial. Cela peut faire fonctionner le plugin localement, mais entraîner un rejet lors de la soumission. Nous vous conseillons de cloner à nouveau votre dépôt dans un répertoire propre avant la soumission pour simuler un environnement d'installation réel et effectuer un test complet.
Échafaudage local et débogage : lancez votre plugin
Écrire le manifeste à la main n'est pas très efficace. Officiellement, la compétence $plugin-creator est intégrée pour gérer l'échafaudage, ce qui permet de générer la structure via une conversation dans la CLI Codex :
codex "Utilise l'échafaudage $plugin-creator pour générer un plugin nommé infra-monitor"
Cette commande génère automatiquement le manifeste, un exemple de compétence et une entrée pour la place de marché locale, vous épargnant la corvée de créer manuellement la structure des répertoires. Une fois généré, le plugin peut être installé et testé directement dans votre environnement local, sans avoir besoin d'être publié sur un dépôt distant.
Lors de la phase de débogage local, si les compétences de votre plugin impliquent des tests comparatifs entre différents grands modèles de langage, une passerelle API unifiée peut réduire considérablement les coûts de changement de configuration. Lors de la vérification des capacités du serveur MCP de votre plugin, nous orientons généralement la base_url vers le service proxy API fourni par APIYI (apiyi.com). Une seule clé suffit pour basculer entre différents modèles au sein du plugin, facilitant ainsi la comparaison des performances des modèles sur une même logique :
from openai import OpenAI
# Initialisation du client avec le service proxy APIYI
client = OpenAI(
api_key="votre-clé-apiyi",
base_url="https://api.apiyi.com/v1"
)
🎯 Conseil de débogage : Le développement de plugins Codex nécessite souvent des tests répétés de la qualité des réponses du serveur MCP avec différents modèles. Nous vous recommandons d'utiliser la plateforme APIYI (apiyi.com) pour gérer de manière centralisée l'invocation du modèle, évitant ainsi de demander des clés séparées pour chaque modèle ou de maintenir des logiques d'appel indépendantes, vous permettant de vous concentrer sur le peaufinage des fonctionnalités de votre plugin.
En plus de créer manuellement des entrées pour la place de marché locale, vous pouvez déclarer le chemin du plugin local directement dans ~/.agents/plugins/marketplace.json (niveau utilisateur) ou dans .agents/plugins/marketplace.json à la racine du dépôt (niveau équipe), en définissant le champ source sur local. Cela pointe vers votre répertoire local sans nécessiter de transfert distant pour valider l'installation.
Si votre plugin inclut une application basée sur MCP nécessitant le mode développeur de ChatGPT pour le débogage, une autre voie est disponible : activez le mode développeur dans les paramètres de ChatGPT, créez une application basée sur MCP pour obtenir l'ID d'application correspondant, puis associez cet ID via $plugin-creator. Vous pourrez alors vérifier le flux de données entre le plugin et l'application dans un environnement de conversation réel. Cette étape est beaucoup plus proche de l'expérience réelle après la mise en ligne, et nous vous recommandons de la suivre intégralement avant de soumettre votre plugin à examen.
Enregistrement sur le marché Git et distribution en équipe
Une fois que votre plugin a été validé localement, il n'est généralement pas nécessaire d'attendre une validation officielle pour le distribuer au sein de votre équipe : il suffit de configurer une source de marché via un dépôt Git. La CLI Codex propose un ensemble de commandes dédiées à la gestion de ce marché :
| Commande | Usage |
|---|---|
codex plugin marketplace add owner/repo |
Ajoute un dépôt GitHub comme source de marché |
codex plugin marketplace add owner/repo --ref v2.1.0 |
Verrouille une branche ou un tag spécifique pour gérer les déploiements progressifs |
codex plugin marketplace list |
Affiche la liste des marchés ajoutés |
codex plugin marketplace upgrade |
Récupère les mises à jour du marché |
codex plugin marketplace remove |
Supprime une source de marché |
Pour les équipes travaillant sur des dépôts volumineux, vous pouvez utiliser le paramètre --sparse .agents/plugins afin de ne récupérer que le répertoire lié au plugin, évitant ainsi de ralentir l'installation avec un clonage complet. Ce modèle de marché Git est idéal pour les chaînes d'outils en entreprise : aucune validation publique n'est requise, et pour mettre à jour un plugin, il suffit de pousser un nouveau tag, puis de demander aux membres de l'équipe d'exécuter la commande upgrade.
D'un point de vue pratique, ce modèle offre un avantage caché : il permet de découpler le rythme d'itération du plugin de celui des publications internes de l'équipe. Le code métier peut être fusionné plusieurs fois par jour, mais comme le plugin fait partie d'une chaîne d'outils conversationnelle, une fréquence de mise à jour trop élevée pourrait perturber le modèle mental des utilisateurs. Il est conseillé de lier les versions des plugins à des fenêtres de publication fixes (par exemple, une fusion hebdomadaire ou bimensuelle). Cela garantit une bonne cadence d'itération sans forcer les membres de l'équipe à s'adapter constamment à de nouvelles interactions.
Processus complet de soumission au Marketplace officiel
L'accès en libre-service au Marketplace officiel n'est pas encore totalement ouvert ; la documentation d'OpenAI indique clairement que cette fonctionnalité est "à venir". Actuellement, la soumission officielle pour les utilisateurs publics passe par un processus de revue manuelle via le portail de soumission des plugins. Avant de soumettre, vous devez effectuer une vérification d'identité : les développeurs individuels doivent passer par une "vérification individuelle", tandis qu'une publication au nom d'une entreprise nécessite une "vérification professionnelle". Les examinateurs vérifieront que l'identité de l'éditeur correspond aux documents fournis.
Voici la liste des éléments requis pour une soumission officielle :
| Catégorie | Exigences spécifiques |
|---|---|
| Informations de base | Nom, description, logo, catégorie, URL associées |
| Serveur MCP | Domaine accessible publiquement, politique CSP, configuration d'authentification |
| Compte de démonstration | Accès direct, sans MFA ni double authentification par e-mail |
| Cas de test | Exactement 5 scénarios positifs + 3 scénarios négatifs |
| Marquage des outils | readOnlyHint, openWorldHint, destructiveHint doivent correspondre aux comportements réels |
Le processus de soumission est divisé en plusieurs sections : Info (informations publiques), MCP (configuration du serveur et authentification), Skills (téléchargement du package final), Prompts (exemples d'invites de démarrage), Testing (cas de test), Global (pays et régions disponibles), et enfin la section Submit pour remplir les notes de publication et confirmer les politiques. Une fois la validation obtenue, le développeur choisit lui-même le moment de la publication via le portail, et le plugin apparaîtra dans le répertoire unifié de ChatGPT et Codex.
Si le plugin inclut une application basée sur MCP, une vérification supplémentaire de la propriété du domaine est requise pour garantir que le domaine déployé par le serveur MCP correspond à celui déclaré par le plugin. L'équipe de révision vérifiera particulièrement si les résultats renvoyés par les outils contiennent des données personnelles ou des clés d'API superflues. Il est préférable d'anticiper ce point lors de la conception des formats de sortie des outils plutôt que de devoir modifier le code après un refus de l'équipe de validation.
Gestion des versions et pièges courants
Une fois votre plugin déployé, la gestion des versions impacte directement l'expérience de mise à jour des utilisateurs. Le marché utilise le champ version pour détecter les mises à jour disponibles. Il est donc crucial de suivre strictement la sémantique de versioning : utilisez le numéro de patch pour les corrections de bugs, le numéro mineur pour les nouvelles fonctionnalités, et le numéro majeur uniquement pour les changements destructeurs.
Les plugins installés sont mis en cache localement dans ~/.codex/plugins/cache/$MARKETPLACE_NAME/$PLUGIN_NAME/$VERSION/. Si vous rencontrez un problème où "le plugin est mis à jour mais son comportement ne change pas", vérifier si le cache a bien été rafraîchi vers la nouvelle version est souvent plus rapide que de redéboguer la logique du code. En environnement d'entreprise, vous pourriez rencontrer des politiques de liste blanche imposées par requirements.toml. Le serveur MCP doit faire correspondre à la fois le nom et l'identité ; toute incohérence entraînera une désactivation silencieuse du service sans message d'erreur explicite. Pour ce type de problème, je vous conseille de tester vos configurations de politique dans un environnement de test avant de passer en production.
Le tableau suivant résume les pièges les plus fréquemment signalés par les développeurs et comment les gérer :
| Problème courant | Solution |
|---|---|
| Chemin du manifeste écrit en absolu | Utilisez des chemins relatifs commençant par ./ |
| Appel implicite déclenchant un plugin non prévu | Utilisez @plugin-name pour spécifier explicitement le plugin |
| Comportement inchangé après mise à jour | Vérifiez si le répertoire de cache local du plugin a été rafraîchi |
| Échec silencieux du MCP sous politique d'entreprise | Vérifiez la correspondance entre le nom et l'identité dans requirements.toml |
Avant de soumettre officiellement votre plugin à la validation, je vous recommande d'utiliser l'outil tiers codex-plugin-scanner. Il évalue votre plugin selon des critères d'installabilité, d'état de maintenance, de sécurité MCP et de source de publication. C'est particulièrement utile pour les plugins destinés aux entreprises : détecter les problèmes en amont permet de gagner un temps précieux par rapport à un rejet lors de la révision.
Un autre détail souvent négligé est la différence entre l'appel explicite et la découverte implicite. Si aucun plugin n'est spécifié, Codex fait correspondre automatiquement les compétences les plus pertinentes selon le contexte. Si plusieurs plugins aux fonctionnalités similaires sont installés dans le même espace de travail, cette correspondance implicite pourrait ne pas sélectionner celui que vous attendiez. Prendre l'habitude d'utiliser @plugin-name pour déclarer explicitement le plugin, surtout dans les espaces de travail partagés, réduit considérablement les coûts de débogage liés aux "conflits entre plugins".
FAQ sur le développement de plugins Codex
Quelle est la différence entre un plugin et un simple fichier SKILL.md ?
SKILL.md est un composant intégré au plugin. Utilisé seul, il ne nécessite pas de manifeste et peut être découvert automatiquement en le plaçant dans le répertoire .agents/skills/. Le plugin, quant à lui, regroupe plusieurs composants (skills, serveur MCP, hooks, etc.) dans un ensemble identifié, versionnable et gérable, idéal pour les scénarios nécessitant une distribution officielle et un suivi des mises à jour.
Comment faire pour comparer plusieurs comptes de modèles pendant la phase de développement ?
C'est un problème courant, surtout pour les plugins impliquant le choix d'un modèle ou l'optimisation d'une invite. Plutôt que d'ouvrir des comptes et de gérer des clés pour chaque fournisseur, utilisez une passerelle unifiée comme APIYI (apiyi.com). Vous pourrez ainsi appeler les principaux modèles avec une seule clé pour effectuer vos tests A/B, vous permettant de vous concentrer sur la logique du plugin plutôt que sur la gestion des comptes.
La distribution via Git Market et la publication sur le Marketplace officiel peuvent-elles coexister ?
Oui. De nombreuses équipes utilisent le Git Market pour la validation interne et les tests en petit comité avant de passer par le processus de soumission officiel. Les deux méthodes de distribution ne sont pas incompatibles et la structure du manifeste est identique.
Combien de temps prend la validation d'un plugin ?
La documentation officielle ne donne pas de délai fixe, précisant simplement que le processus de validation est en cours de développement et d'expansion, sans possibilité de traitement accéléré. Je vous conseille de considérer le cycle de validation comme une variable incertaine dans votre planning de projet. Préparez tous les documents nécessaires avant la soumission pour éviter les allers-retours, c'est le moyen le plus efficace de réduire le temps global avant la mise en ligne.
Quelques mots pour conclure
La difficulté principale du développement de plugins Codex ne réside pas tant dans le code lui-même que dans la compréhension des exigences du manifeste et la préparation des documents pour le processus de validation. Ces détails ne sont pas aussi complexes qu'ils en ont l'air, mais il suffit d'une erreur de chemin ou d'un champ manquant pour que votre soumission soit rejetée. Je vous conseille de suivre cet ordre : « validation avec l'échafaudage local → distribution restreinte sur le marché Git → soumission officielle pour examen », en prévoyant à chaque étape du temps pour des tests en conditions réelles. Si votre plugin implique l'invocation du modèle ou nécessite des changements fréquents de modèles pour vos tests, le service proxy API proposé par APIYI (apiyi.com) peut vous faire gagner un temps précieux sur la configuration de l'environnement, vous permettant ainsi de vous concentrer davantage sur le peaufinage de votre plugin.
