Ein Plugin bündelt Skills, eine MCP-Konfiguration oder beides. Lade die Dateien in deine eigene Umgebung oder lade ein ZIP-Archiv in eine von OpenAI gehostete Umgebung hoch.
Plugin packen
Dieses Plugin kombiniert einen Skill für die Suche in der Dokumentation mit dem MCP-Server für die OpenAI-Dokumentation. Es benötigt Netzwerkzugriff, kommt aber ohne Zugangsdaten und lokale Serverabhängigkeiten aus.
docs-helper/
├── .codex-plugin/plugin.json
├── .mcp.json
└── skills/docs-search/SKILL.md
Gib das Skill-Verzeichnis und den Pfad zur MCP-Konfiguration in .codex-plugin/plugin.json an:
{
"name": "docs-helper",
"version": "1.0.0",
"description": "Find answers in OpenAI developer documentation.",
"skills": "./skills/",
"mcpServers": "./.mcp.json"
}
Alle Pfade sind relativ zum Stammverzeichnis des Plugins. Sie müssen mit ./ beginnen, innerhalb des Plugins bleiben und dürfen keine ..-Bestandteile enthalten. Das vollständige Manifestformat findest du in der Anleitung zum Packen von Plugins.
Trage den Server in .mcp.json ein. Diese Datei verwendet das Plugin-Format, das sich vom Format für agent.tools unterscheidet:
{
"mcpServers": {
"openai_docs": {
"type": "http",
"url": "https://developers.openai.com/mcp"
}
}
}
Füge die Anweisungen in skills/docs-search/SKILL.md ein:
---
name: docs-search
description: Find answers in OpenAI developer documentation.
---
Use the openai_docs MCP server to find relevant documentation.
Answer the question and link to the sources you used.
Plugins in einer selbst gehosteten Sandbox registrieren
Kopiere das Plugin nach /workspace/plugins/docs-helper und füge diesen absoluten Pfad zu environment.capability_directories hinzu. Wähle das Stammverzeichnis des Plugins. Es enthält .codex-plugin/plugin.json.
import OpenAI from "openai";
const client = new OpenAI();
const result = await client.beta.agents.sessions.create({
agent: {
model: "gpt-6-astra",
},
environment: {
type: "self_hosted",
workspace_directory: "/workspace",
capability_directories: ["/workspace/plugins/docs-helper"],
},
});
console.log(result.id);Verbinde den Executor, bevor der Agent das Plugin verwendet. Erlaube der Umgebung den Zugriff auf https://developers.openai.com/mcp.
Wenn du mehrere Plugins verwendest, gib für jedes das Stammverzeichnis an. Über ein übergeordnetes Verzeichnis lassen sich Skills in Unterverzeichnissen finden. Die MCP-Konfiguration der einzelnen Plugins in diesen Unterverzeichnissen wird dabei jedoch nicht automatisch geladen.
Plugins in eine von OpenAI gehostete Sandbox hochladen
Übergib in environment.plugins für jedes Plugin ein ZIP-Archiv. Jedes Archiv muss genau einen Plugin-Ordner enthalten, in dem .codex-plugin/plugin.json liegt. Name und Beschreibung in der Anfrage müssen mit den Angaben im Manifest übereinstimmen.
Diese Hilfsfunktion packt deinen Ordner in ein Archiv und erstellt eine Sitzung. Übergib ihr deinen API-Client und den Pfad zu docs-helper. OpenAI entpackt und registriert das Plugin automatisch.
import base64
import json
import shutil
from pathlib import Path
from tempfile import TemporaryDirectory
def upload_plugin(client, plugin_directory):
plugin_directory = Path(plugin_directory).resolve()
manifest = json.loads((plugin_directory / ".codex-plugin/plugin.json").read_text())
with TemporaryDirectory() as temporary:
archive = shutil.make_archive(
str(Path(temporary) / "plugin"),
"zip",
root_dir=plugin_directory.parent,
base_dir=plugin_directory.name,
)
return client.beta.agents.sessions.create(
agent={"model": "gpt-6-astra"},
environment={
"type": "openai_hosted",
"plugins": [
{
"type": "inline",
"name": manifest["name"],
"description": manifest["description"],
"source": {
"type": "base64",
"media_type": "application/zip",
"data": base64.b64encode(
Path(archive).read_bytes()
).decode(),
},
}
],
},
)Plugin-Setup für gehostete Umgebungen wiederverwenden
Erstelle eine Umgebungsvorlage mit der Plugin-Liste. Setze environment.environment_template_id für spätere Sitzungen auf die ID der gespeicherten Vorlage.
Lass environment.plugins weg, um die Plugin-Liste aus der Vorlage zu übernehmen. Wenn du eine Liste übergibst, ersetzt sie die Liste aus der Vorlage. Jede Sitzung erhält eine eigene Umgebung, die der Hauptagent und seine Subagenten gemeinsam nutzen.
MCP-Server authentifizieren
Für dieses Beispiel ist keine Authentifizierung nötig. Für MCP-Server anderer Plugins gilt:
- HTTP:
bearer_token_env_varliest eine Umgebungsvariable aus und sendet ihren Wert als Bearer-Token. Andere Werte inhttp_headerswerden unverändert übernommen.env_http_headerswird nicht unterstützt. - Stdio:
env_varsgibt an, welche Umgebungsvariablen an den Serverprozess übergeben werden. Installiere das ausführbare Programm und seine Abhängigkeiten in der Umgebung. Ein relativer Pfad incwdbezieht sich auf das Stammverzeichnis des Plugins.
Speichere keine Geheimnisse in Plugin-Dateien oder -Archiven. Das Plugin baut seine MCP-Verbindungen aus der Sitzungsumgebung heraus auf. Wo welche Zugangsdaten verwendet werden, erfährst du in der Dokumentation zur MCP-Authentifizierung.
Lass bei gehosteten MCP-Servern mit Stdio die Netzwerkrichtlinie weg oder setze sie auf enabled. Die Netzwerkrichtlinien disabled und restricted werden für diese Verbindungen nicht unterstützt.
Plugin testen
Sende in der Sitzung eine normale Nachricht, in der du den Agenten bittest, den Skill zu verwenden:
Erkläre mir mithilfe von docs-search, wie ich die Ausgabe der Responses API streamen kann. Füge Links zur Dokumentation hinzu.
Prüfe, ob der Durchlauf abgeschlossen ist und seine gespeicherten Elemente einen erfolgreichen Aufruf von openai_docs enthalten. Die Antwort sollte den Anweisungen des Skills folgen und die Dokumentation als Quelle angeben. Wenn das Plugin ausschließlich Skills enthält, prüfe, ob seine Ausgabe den Anweisungen entspricht. Ein MCP-Aufruf ist in diesem Fall nicht erforderlich.
Erstelle eine neue Sitzung, nachdem du Plugin-Dateien oder eine Vorlage geändert hast. Bestehende Sitzungen laden die Tools nicht erneut. Hilfe bei Verbindungsfehlern findest du in der Anleitung zur MCP-Fehlerbehebung. Lösche die Testsitzungen und stoppe die selbst gehosteten Rechenressourcen, sobald du fertig bist.