Praxisleitfaden zur Codex-Plugin-Entwicklung: 7 entscheidende Schritte vom Aufbau bis zur Markteinführung

Das Plugin-System der Codex CLI entwickelt sich rasant weiter. Mit dem Befehl /plugins lassen sich Plugins bereits nach Marktplatz gruppieren, installieren sowie aktivieren oder deaktivieren. Immer mehr Teams verpacken ihre internen Toolchains in wiederverwendbare Codex-Plugins. Da der offizielle Marktplatz für Self-Service-Uploads jedoch noch einem „Prüfverfahren“ unterliegt, müssen Entwickler zunächst die Manifest-Struktur und die lokale Fehlersuche verstehen sowie den Prüfungsprozess durchlaufen, bevor das Plugin für Benutzer verfügbar wird. Dieser Artikel erläutert den gesamten Ablauf von der Erstellung über das lokale Testen und die Verteilung via Git bis hin zur offiziellen Prüfung und Veröffentlichung und fasst dabei die häufigsten Fallstricke zusammen.

Woraus besteht ein Codex-Plugin?

Ein Codex-Plugin bündelt im Wesentlichen verschiedene Funktionen in eine installierbare und verteilbare Einheit. Laut der offiziellen OpenAI-Dokumentation können Plugins Skills (wiederverwendbare Anweisungsbeschreibungen), MCP-gestützte Apps (Dienste zur Anbindung externer Tools), Lebenszyklus-Hooks sowie optionale Browser-Erweiterungen und Vorlagen für zeitgesteuerte Aufgaben enthalten. Diese Komponenten müssen nicht alle gleichzeitig vorhanden sein; ein leichtgewichtiges Plugin, das nur Skills enthält, kann ebenfalls problemlos installiert und genutzt werden.

Das Verständnis der Zuständigkeitsbereiche jeder Komponente ist die Voraussetzung für ein korrektes Manifest. Die folgende Tabelle zeigt die Speicherpfade und Funktionen der vier Kernkomponenten eines Codex-Plugins:

Komponente	Speicherpfad	Funktion	Erforderlich
plugin.json	.codex-plugin/plugin.json	Identität und Metadaten des Plugins	Ja
Skills	skills/<skill-name>/SKILL.md	Definition wiederverwendbarer Aufgabenbefehle	Nein
MCP-Server	.mcp.json	Konfiguration der externen Tool-Dienstverbindung	Nein
Hooks	hooks/hooks.json	Deklaration von Lebenszyklus-Hook-Befehlen	Nein

Wichtig: Wenn ein Plugin lediglich aus SKILL.md-Dateien besteht, die innerhalb eines Teams geteilt werden, ist kein vollständiger Manifest-Prozess erforderlich. Legen Sie die Datei einfach in das Verzeichnis .agents/skills/ ab; Codex erkennt diese automatisch, ohne dass ein Plugin-Manifest benötigt wird. Dies ist eine häufige Zwischenstufe für viele Teams, bevor sie von „internen Skripten“ zu „offiziellen Plugins“ übergehen.

Der Funktionsumfang eines Plugins ist weitreichender, als viele vermuten. Neben Skills und MCP-gestützten Apps erwähnt die offizielle Dokumentation, dass Plugins auch Fähigkeitsdeklarationen für Browser-Erweiterungen sowie Vorlagen für wiederkehrende Aufgaben enthalten können. Das bedeutet, dass ein Plugin sowohl interaktive Anfragen, die vom Benutzer ausgelöst werden, als auch automatisierte Szenarien, die „periodisch im Hintergrund“ ausgeführt werden, abdecken kann. Die Entscheidung, welche Komponenten in einem Plugin kombiniert werden, ist letztlich eine Abwägung zwischen Installationserfahrung und Wartungsaufwand – je mehr Komponenten, desto vollständiger die Funktionalität, aber desto umfangreicher werden auch die Prüfunterlagen und Testfälle. Überlegen Sie sich daher vor der Einreichung genau, welche Fähigkeiten Ihre Zielgruppe wirklich benötigt, anstatt alle Komponenten in ein einziges Paket zu packen.

Starten mit plugin.json: Die Plugin-Manifest-Datei im Detail

Die plugin.json ist der Personalausweis Ihres Plugins. Sie legt fest, wie Codex das Plugin erkennt, lädt und anzeigt. Ein minimal funktionsfähiges Manifest benötigt nur drei Felder:

{
  "name": "my-first-plugin",
  "version": "1.0.0",
  "description": "Wiederverwendbarer Begrüßungs-Workflow",
  "skills": "./skills/"
}

Für das Feld name empfiehlt sich eine stabile kebab-case-Benennung. Diese Kennung sollte bei späteren Versions-Updates nicht geändert werden, da der Marktplatz das Plugin sonst nicht mehr als dasselbe identifizieren kann. Die version folgt den Regeln der semantischen Versionierung; der Marktplatz nutzt dieses Feld, um den Nutzer auf notwendige Updates hinzuweisen. Alle im Manifest referenzierten Pfade müssen relativ zum Plugin-Stammverzeichnis sein, mit ./ beginnen und dürfen das Plugin-Verzeichnis nicht verlassen.

Neben diesen drei Basisfeldern kann skills auch auf ein Array mehrerer Skill-Verzeichnisse verweisen. Die Felder hooks, mcpServers und apps verweisen jeweils auf die entsprechenden Konfigurationsdateien hooks/hooks.json, .mcp.json und .app.json. Dieses Design, bei dem Felder auf Dateien verweisen, hält das Manifest schlank. Spezifische Skill-Beschreibungen und Tool-Konfigurationen werden in separate Dateien ausgelagert, was die parallele Bearbeitung verschiedener Komponenten in Teams erleichtert, ohne Konflikte zu erzeugen.

Wenn Sie planen, das Plugin im offiziellen Marktplatz einzureichen, müssen Sie eine Reihe von Metadaten für die Präsentation ergänzen. Die folgende Tabelle listet die wichtigsten Felder auf, die während der Veröffentlichungsphase ausgefüllt werden sollten:

Feld	Typ	Beschreibung
author / repository	String	Identifiziert die Quelle des Plugins; sollte mit der verifizierten Identität übereinstimmen
interface.displayName	String	Der im Marktplatz angezeigte Plugin-Name
interface.category	String	Plugin-Kategorie, beeinflusst den Suchpfad der Nutzer
interface.capabilities	Array	Deklariert die Fähigkeits-Tags des Plugins
mcpServers / apps / hooks	Objekt	Verweist auf die Konfigurationsdateien der jeweiligen Komponenten

Der häufigste Fehler beim Schreiben des Manifests sind falsche Pfadreferenzen – zum Beispiel, wenn das Feld skills einen absoluten Pfad enthält oder das führende ./ fehlt. Dies führt dazu, dass das Plugin lokal funktioniert, aber bei der Prüfung als ungültiges Manifest abgelehnt wird. Es empfiehlt sich, das Plugin-Repository vor der Einreichung in einem sauberen Verzeichnis neu zu klonen, um eine reale Installationsumgebung für einen vollständigen Test zu simulieren.

Lokales Scaffolding und Debugging: Das Plugin zum Laufen bringen

Das manuelle Schreiben des Manifests von Grund auf ist ineffizient. Offiziell wird der integrierte Skill $plugin-creator bereitgestellt, um das Scaffolding zu übernehmen. Dies kann direkt über die Codex CLI dialogbasiert generiert werden:

codex "Generiere ein Plugin namens infra-monitor mit dem $plugin-creator Scaffolding"

Dieser Befehl erstellt automatisch das Manifest, einen Beispiel-Skill und einen lokalen Marktplatzeintrag, was Ihnen die mühsame Arbeit an der Verzeichnisstruktur erspart. Nach der Generierung kann das Plugin sofort in der lokalen Umgebung installiert und getestet werden, ohne dass es in ein Remote-Repository hochgeladen werden muss.

Wenn während der lokalen Debugging-Phase Skills innerhalb des Plugins den Modellaufruf verschiedener Anbieter zu Vergleichszwecken erfordern, kann ein einheitliches API-Gateway den Aufwand für den Wechsel der Umgebungskonfiguration erheblich reduzieren. Bei der Überprüfung der MCP-Server-Fähigkeiten eines Plugins setzen wir den base_url normalerweise auf den API-Proxy-Dienst von APIYI (apiyi.com). Mit einem einzigen Schlüssel können Sie innerhalb des Plugins zwischen verschiedenen Modellen wechseln, um deren Performance bei gleicher Plugin-Logik direkt zu vergleichen:

from openai import OpenAI

client = OpenAI(
    api_key="your-apiyi-key",
    base_url="https://api.apiyi.com/v1"
)

🎯 Debugging-Tipp: Während der Entwicklung von Codex-Plugins müssen Sie häufig die Antwortqualität des MCP-Servers bei verschiedenen Modellen testen. Wir empfehlen, den Modellaufruf zentral über die Plattform APIYI (apiyi.com) zu verwalten. So vermeiden Sie es, für jedes Modell eigene Schlüssel zu beantragen und separate Aufruflogiken zu pflegen, und können sich voll auf die Optimierung der Plugin-Funktionen konzentrieren.

Neben der manuellen Erstellung von lokalen Marktplatzeinträgen können Sie den lokalen Plugin-Pfad auch direkt in ~/.agents/plugins/marketplace.json (auf persönlicher Ebene) oder in der .agents/plugins/marketplace.json im Stammverzeichnis des Repositorys (auf Teamebene) deklarieren. Setzen Sie das Feld source einfach auf local, um auf das lokale Verzeichnis zu verweisen – so lässt sich die Installationsprüfung ohne Remote-Push abschließen.

Falls Ihr Plugin eine MCP-gestützte App enthält, die für das Debugging den Entwicklermodus von ChatGPT erfordert, gibt es einen weiteren Weg: Aktivieren Sie den Entwicklermodus in den ChatGPT-Einstellungen, erstellen Sie eine MCP-gestützte App, um die entsprechende App-ID zu erhalten, und verknüpfen Sie diese ID über den $plugin-creator. So können Sie den Datenfluss zwischen Plugin und App in einer echten Konversationsumgebung validieren. Dieser Schritt ist wesentlich näher an der realen Erfahrung nach dem Live-Gang als ein reines Debugging über die lokale Kommandozeile; wir empfehlen, diesen Prozess vor der Einreichung zur Prüfung mindestens einmal vollständig zu durchlaufen.

Git-Marktplatz-Registrierung und interne Verteilung

Sobald Plugins lokal erfolgreich validiert wurden, ist für die teaminterne Verteilung in der Regel keine offizielle Prüfung erforderlich; ein Git-Repository als Marktplatz-Quelle reicht völlig aus. Die Codex CLI bietet eine Reihe spezieller Befehle für die Marktplatzverwaltung:

Befehl	Zweck
codex plugin marketplace add owner/repo	Fügt ein GitHub-Repository als Marktplatz-Quelle hinzu
codex plugin marketplace add owner/repo --ref v2.1.0	Sperrt einen bestimmten Branch oder Tag für kontrollierte Canary-Releases
codex plugin marketplace list	Listet alle hinzugefügten Marktplätze auf
codex plugin marketplace upgrade	Ruft Marktplatz-Updates ab
codex plugin marketplace remove	Entfernt eine Marktplatz-Quelle

Für Teams mit großen Code-Repositories kann der Parameter --sparse .agents/plugins verwendet werden, um nur das plugin-relevante Verzeichnis abzurufen. Dies verhindert, dass ein vollständiger Repository-Klon die Installationsgeschwindigkeit verlangsamt. Dieses Git-Marktplatz-Modell eignet sich hervorragend für unternehmensinterne Toolchains – es ist keine öffentliche Prüfung erforderlich, Plugin-Updates erfordern lediglich das Pushen eines neuen Tags, und Teammitglieder können die Synchronisierung mit einem einzigen upgrade-Befehl durchführen.

Aus praktischer Sicht hat das Git-Marktplatz-Modell noch einen versteckten Vorteil: Es entkoppelt die Iterationsgeschwindigkeit der Plugins vom internen Release-Zyklus des Teams. Während der Geschäftscode mehrmals täglich zusammengeführt werden kann, kann eine zu hohe Update-Frequenz bei Plugins – als Teil der konversationellen Toolchain – das mentale Modell der Nutzer stören. Es empfiehlt sich, Plugin-Versionen und Tags an feste Release-Fenster zu binden, z. B. durch Zusammenführung der Änderungen alle ein bis zwei Wochen. Dies sichert die Geschwindigkeit der Funktionsiteration, ohne dass sich Teammitglieder ständig an neue Interaktionsweisen anpassen müssen.

Der vollständige Prozess zur Einreichung beim offiziellen Marketplace

Der Self-Service-Zugang zum offiziellen Marketplace ist bis dato noch nicht vollständig geöffnet. Die OpenAI-Dokumentation weist explizit darauf hin, dass dieser Bereich "in Kürze verfügbar" sein wird. Derzeit erfolgt die offizielle Einreichung für öffentliche Nutzer über den manuellen Prüfungsprozess des Plugin-Einreichungsportals. Vor der Einreichung muss eine Identitätsprüfung abgeschlossen werden – Einzelentwickler müssen eine individuelle Verifizierung durchlaufen, während für eine Veröffentlichung im Namen eines Unternehmens eine geschäftliche Verifizierung erforderlich ist. Die Prüfer gleichen dabei die Identität des Herausgebers mit den eingereichten Unterlagen ab.

Für die offizielle Einreichung ist folgende Materialliste erforderlich:

Materialkategorie	Spezifische Anforderungen
Plugin-Basisinformationen	Name, Beschreibung, Logo, Kategorie, relevante URLs
MCP-Server	Öffentlich zugängliche Domain, CSP-Richtlinien, Authentifizierungskonfiguration
Demo-Konto	Direkter Login möglich, keine MFA oder E-Mail-Zwei-Faktor-Authentifizierung erforderlich
Testfälle	Exakt 5 positive Szenarien + 3 negative Szenarien
Tool-Annotationen	readOnlyHint, openWorldHint, destructiveHint müssen mit dem tatsächlichen Verhalten übereinstimmen

Der Einreichungsprozess ist in mehrere Formularbereiche unterteilt: Info (öffentliche Listungsinformationen), MCP (Server- und Authentifizierungskonfiguration), Skills (Hochladen des finalen Skill-Pakets), Prompts (Beispiele für Eingabeaufforderungen), Testing (Testfälle), Global (verfügbare Länder und Regionen) und schließlich der Submit-Bereich, in dem Release-Hinweise ausgefüllt und Richtlinien bestätigt werden. Nach erfolgreicher Prüfung wählt der Entwickler den Veröffentlichungszeitpunkt selbst im Portal aus, und das Plugin erscheint synchron im einheitlichen Plugin-Verzeichnis von ChatGPT und Codex.

Wenn das Plugin eine MCP-gestützte App enthält, ist eine zusätzliche Überprüfung der Domain-Inhaberschaft erforderlich, um sicherzustellen, dass die Domain, auf der der MCP-Server bereitgestellt wird, mit der im Plugin deklarierten Domain übereinstimmt. Das Prüfungsteam achtet besonders darauf, ob die Tool-Ergebnisse überflüssige personenbezogene Daten oder Schlüsselinformationen enthalten. Dies sollte bereits beim Entwurf des Tool-Ausgabeformats vermieden werden, anstatt erst nach einer Ablehnung durch die Prüfung nachzubessern.

Versionsmanagement und häufige Fallstricke

Nachdem ein Plugin veröffentlicht wurde, beeinflussen Details im Versionsmanagement direkt das Upgrade-Erlebnis der Nutzer. Der Marktplatz nutzt das Feld version, um zu prüfen, ob Updates verfügbar sind. Daher ist die strikte Einhaltung der semantischen Versionierung wichtig: Nutzen Sie Patch-Versionen für Fehlerbehebungen, Minor-Versionen für neue Funktionen und Major-Versionen nur bei grundlegenden, inkompatiblen Änderungen.

Installierte Plugins werden lokal unter ~/.codex/plugins/cache/$MARKETPLACE_NAME/$PLUGIN_NAME/$VERSION/ zwischengespeichert. Wenn Sie Probleme wie „Plugin wurde aktualisiert, aber das Verhalten hat sich nicht geändert“ untersuchen, ist die Überprüfung, ob der Cache bereits auf die neue Version aktualisiert wurde, oft schneller, als den Code neu zu debuggen. In Unternehmensumgebungen stoßen Sie zudem häufig auf die durch requirements.toml erzwungene Whitelist-Richtlinie. Der MCP-Server erfordert, dass Name und Identität übereinstimmen; jede Abweichung führt dazu, dass der Dienst stillschweigend deaktiviert wird, ohne dass eine klare Fehlermeldung erscheint. Es empfiehlt sich, solche Richtlinienkonfigurationen erst in einer Testumgebung auszuführen, bevor sie in die Produktion gehen.

Die folgende Tabelle fasst einige häufig von Entwicklern gemeldete Fallstricke und deren Lösungen zusammen:

Häufiges Problem	Lösung
Manifest-Pfad als absoluter Pfad angegeben	Auf relative Pfade mit ./ umstellen
Impliziter Aufruf löst unerwartetes Plugin aus	Explizite Angabe des Plugins mit @plugin-name
Verhalten nach Update nicht wirksam	Lokales Plugin-Cache-Verzeichnis auf Aktualisierung prüfen
MCP-Ausfall unter Unternehmensrichtlinien	Abgleich von Name und Identität in requirements.toml prüfen

Bevor Sie das Plugin offiziell zur Prüfung einreichen, sollten Sie das Drittanbieter-Tool codex-plugin-scanner ausführen. Es bewertet das Plugin hinsichtlich Installierbarkeit, Wartungsstatus, MCP-Sicherheit und Veröffentlichungsquelle. Besonders bei Plugins für Unternehmenskunden spart das frühzeitige Erkennen von Problemen mehr Zeit, als eine Ablehnung durch die Prüfung zu riskieren.

Ein weiteres Detail, das oft übersehen wird, ist der Unterschied zwischen explizitem Aufruf und impliziter Erkennung. Wenn kein Plugin explizit angegeben ist, wählt Codex basierend auf dem Kontext automatisch die relevanteste Fähigkeit aus. Wenn im selben Arbeitsbereich mehrere Plugins mit ähnlichen Funktionen installiert sind, wählt diese implizite Übereinstimmung möglicherweise nicht das von Ihnen gewünschte Plugin aus. Gewöhnen Sie sich an, Plugins explizit mit @plugin-name zu deklarieren, besonders in gemeinsam genutzten Arbeitsbereichen, um den Aufwand bei der Fehlersuche durch „sich überschneidende Plugins“ zu minimieren.

Codex-Plugin-Entwicklung: Häufige Fragen (FAQ)

Was ist der Unterschied zwischen einem Plugin und einer einzelnen SKILL.md-Datei?
SKILL.md ist eine Komponente innerhalb eines Plugins. Bei isolierter Verwendung ist kein Manifest erforderlich; die Datei wird automatisch erkannt, wenn sie im Verzeichnis .agents/skills/ abgelegt wird. Ein Plugin hingegen bündelt mehrere Komponenten wie Skills, MCP-Server und Hooks zu einer identifizierbaren, versionierbaren Einheit, die sich für die offizielle Verteilung und Update-Nachverfolgung eignet.

Was tun, wenn ich in der Entwicklungsphase mehrere Modell-Accounts für Vergleichstests benötige?
Dies ist ein häufiges Problem bei der Plugin-Entwicklung, insbesondere bei Plugins, die eine Modellauswahl oder die Optimierung von Eingabeaufforderungen erfordern. Anstatt für jeden Modellanbieter separate Konten zu eröffnen und Schlüssel zu verwalten, ist es effizienter, ein einheitliches Gateway wie APIYI (apiyi.com) zu nutzen. Über einen einzigen Schlüssel können Sie gängige Modelle für A/B-Vergleiche aufrufen und sich auf die Logik des Plugins konzentrieren, statt auf die Kontoverwaltung.

Können die Git-Marktplatz-Verteilung und die offizielle Marketplace-Veröffentlichung koexistieren?
Ja. Viele Teams nutzen den Git-Marktplatz für interne Validierungen und kleine Betatests. Sobald die Stabilität bestätigt ist, erfolgt der offizielle Einreichungsprozess. Beide Verteilungsmethoden stehen nicht im Konflikt zueinander, und die Manifest-Struktur ist identisch.

Wie lange dauert die Prüfung eines Plugins?
In der offiziellen Dokumentation gibt es derzeit keinen festen Zeitrahmen; es wird lediglich darauf hingewiesen, dass der Prüfungsprozess kontinuierlich ausgebaut wird und keine beschleunigte Bearbeitung möglich ist. Es ist ratsam, den Prüfungszeitraum als unsichere Variable in die Projektplanung einzubeziehen. Bereiten Sie alle Unterlagen vor der Einreichung vollständig vor, um Rückfragen zu vermeiden – dies ist der effektivste Weg, um die Zeit bis zur Veröffentlichung zu verkürzen.

Fazit

Die größte Herausforderung bei der Entwicklung von Codex-Plugins liegt weniger im Code selbst, sondern im Verständnis der Manifest-Spezifikationen und der Vorbereitung der Unterlagen für den Prüfungsprozess. Diese Details sind zwar nicht so kompliziert wie gedacht, führen aber oft dazu, dass ein Projekt aufgrund eines falschen Pfades oder eines fehlenden Feldes abgelehnt wird. Ich empfehle, schrittweise vorzugehen: „Lokale Validierung über das Grundgerüst → Verteilung in kleinem Rahmen über den Git-Marktplatz → Offizielle Einreichung zur Prüfung“. Planen Sie für jeden Schritt ausreichend Zeit für Tests in einer realen Umgebung ein. Falls Ihr Plugin mehrere Modellaufrufe erfordert oder Sie häufig zwischen verschiedenen Testmodellen wechseln müssen, kann der einheitliche API-Proxy-Dienst von APIYI (apiyi.com) Ihnen viel Zeit bei der Einrichtung der Umgebung sparen, sodass Sie sich voll und ganz auf den Feinschliff Ihres Plugins konzentrieren können.