Plug-ins

Ein Plug-in bündelt Skills, MCP-Konfiguration oder beides. Lade seine Dateien in deine eigene Umgebung oder lade ein ZIP-Archiv in eine von OpenAI gehostete Umgebung hoch.

Das Plug-in paketieren

Dieses Plug-in kombiniert einen Skill zur Dokumentationssuche mit dem MCP-Server für die OpenAI-Dokumentation. Es benötigt Netzwerkzugriff, aber weder Zugangsdaten noch lokale Serverabhängigkeiten.

docs-helper/
├── .codex-plugin/plugin.json
├── .mcp.json
└── skills/docs-search/SKILL.md

Gib das Skill-Verzeichnis und die MCP-Konfiguration in .codex-plugin/plugin.json an:

1234567{
  "name": "docs-helper",
  "version": "1.0.0",
  "description": "Find answers in OpenAI developer documentation.",
  "skills": "./skills/",
  "mcpServers": "./.mcp.json"
}

Pfade werden relativ zum Stammverzeichnis des Plug-ins aufgelöst. Sie müssen mit ./ beginnen, innerhalb des Plug-ins bleiben und dürfen keine ..-Komponenten enthalten. Das vollständige Manifestformat findest du unter Dein Plug-in paketieren.

Füge den Server zu .mcp.json hinzu. Diese Datei verwendet das Plug-in-Format, das sich von agent.tools unterscheidet:

12345678{
  "mcpServers": {
    "openai_docs": {
      "type": "http",
      "url": "https://developers.openai.com/mcp"
    }
  }
}

Füge die Anweisungen zu skills/docs-search/SKILL.md hinzu:

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

Plug-ins in einer selbst gehosteten Sandbox registrieren

Kopiere das Plug-in nach /workspace/plugins/docs-helper und füge diesen absoluten Pfad zu environment.capability_directories hinzu. Wähle das Stammverzeichnis des Plug-ins aus, das .codex-plugin/plugin.json enthält.

1
2
3
4
5
6
7
8
9
10
11
12
13
14import 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);

1
2
3
4
5
6
7
8
9
10
11
12
13from openai import OpenAI

client = OpenAI()

result = client.beta.agents.sessions.create(
    agent={"model": "gpt-6-astra"},
    environment={
        "type": "self_hosted",
        "workspace_directory": "/workspace",
        "capability_directories": ["/workspace/plugins/docs-helper"],
    },
)
print(result.id)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23import (
	"context"
	"fmt"

	"github.com/openai/openai-go/v3"
)

ctx := context.Background()
client := openai.NewClient()
result, err := client.Beta.Agents.Sessions.New(ctx,
	openai.BetaAgentSessionNewParams{
		Agent: openai.BetaAgentSessionNewParamsAgent{Model: openai.String("gpt-6-astra")},
		Environment: openai.EnvironmentParamUnion{
			OfParamSelfHosted: &openai.EnvironmentParamSelfHosted{
				WorkspaceDirectory:    "/workspace",
				CapabilityDirectories: []string{"/workspace/plugins/docs-helper"},
			},
		},
	})
if err != nil {
	panic(err)
}
fmt.Println(result.ID)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.EnvironmentParam;
import com.openai.models.beta.agents.sessions.SessionCreateParams;
import java.util.List;

OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var result =
    client
        .beta()
        .agents()
        .sessions()
        .create(
            SessionCreateParams.builder()
                .agent(SessionCreateParams.Agent.builder().model("gpt-6-astra").build())
                .environment(
                    EnvironmentParam.SelfHosted.builder()
                        .workspaceDirectory("/workspace")
                        .capabilityDirectories(List.of("/workspace/plugins/docs-helper"))
                        .build())
                .build());
System.out.println(result.id());

1
2
3
4
5
6
7
8
9
10
11
12require "openai"

client = OpenAI::Client.new
result = client.beta.agents.sessions.create(
  agent: { model: "gpt-6-astra" },
  environment: {
    type: "self_hosted",
    workspace_directory: "/workspace",
    capability_directories: ["/workspace/plugins/docs-helper"]
  }
)
puts result.id

Verbinde den Executor, bevor der Agent das Plug-in verwendet. Erlaube der Umgebung den Zugriff auf https://developers.openai.com/mcp.

Gib bei mehreren Plug-ins jedes Stammverzeichnis einzeln an. Über ein übergeordnetes Verzeichnis lassen sich Skills in Unterverzeichnissen finden, die MCP-Konfigurationen der einzelnen untergeordneten Plug-ins werden jedoch nicht geladen.

Plug-ins in eine von OpenAI gehostete Sandbox hochladen

Gib in environment.plugins ein ZIP-Archiv pro Plug-in an. Jedes ZIP-Archiv muss einen Plug-in-Ordner enthalten, in dem sich .codex-plugin/plugin.json befindet. Name und Beschreibung in der Anfrage müssen mit dem Manifest übereinstimmen.

Diese Hilfsfunktion packt deinen Ordner in ein Archiv und erstellt eine Sitzung. Übergib deinen API-Client und den Pfad zu docs-helper. OpenAI entpackt und registriert das Plug-in automatisch.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37import 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(),
                        },
                    }
                ],
            },
        )

Ein gehostetes Plug-in-Setup wiederverwenden

Erstelle eine Umgebungsvorlage mit der Plug-in-Liste. Setze für spätere Sitzungen environment.environment_template_id auf die ID der gespeicherten Vorlage.

Lasse environment.plugins weg, um die Plug-in-Liste der Vorlage zu übernehmen. Wenn du eine Liste angibst, ersetzt sie die Liste aus der Vorlage. Jede Sitzung erhält eine eigene Umgebung, die sich der Hauptagent und seine Subagenten teilen.

MCP-Server authentifizieren

Das Beispiel benötigt keine Authentifizierung. Für andere MCP-Server aus Plug-ins gilt:

• HTTP: bearer_token_env_var liest eine Umgebungsvariable und sendet ihren Wert als Bearer-Token. Andere Werte in http_headers werden wörtlich übernommen. env_http_headers wird nicht unterstützt.
• Stdio: env_vars listet Umgebungsvariablen auf, die an den Serverprozess übergeben werden sollen. Installiere die ausführbare Datei und ihre Abhängigkeiten in der Umgebung. Ein relativer Pfad in cwd wird vom Stammverzeichnis des Plug-ins aus aufgelöst.

Speichere keine Geheimnisse in Plug-in-Dateien oder -Archiven. MCP-Verbindungen von Plug-ins werden aus der Umgebung der Sitzung heraus hergestellt. Informationen zum Geltungsbereich von Zugangsdaten findest du unter MCP-Authentifizierung.

Lasse bei gehosteten Stdio-MCPs die Netzwerkrichtlinie weg oder setze sie auf enabled. Die Netzwerkrichtlinien disabled und restricted werden für diese Verbindungen nicht unterstützt.

Ein Plug-in testen

Sende eine normale Sitzungsnachricht, in der du um die Verwendung des Skills bittest:

Use docs-search to explain how to stream Responses API output. Include links to the documentation.

Prüfe, ob der Turn abgeschlossen wurde 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. Prüfe bei einem Plug-in, das nur Skills enthält, ob seine Ausgabe den Anweisungen entspricht. Ein MCP-Aufruf ist nicht erforderlich.

Erstelle eine neue Sitzung, nachdem du Plug-in-Dateien oder eine Vorlage geändert hast. Bestehende Sitzungen laden die Werkzeuge nicht neu. Hilfe bei Verbindungsfehlern findest du unter MCP-Fehlerbehebung. Lösche Testsitzungen und stoppe selbst gehostete Rechenressourcen, wenn du fertig bist.