Plugins

Un plugin regroupe des skills, une configuration MCP ou les deux. Chargez ses fichiers dans votre propre environnement ou importez une archive ZIP dans un environnement hébergé par OpenAI.

Créez le package du plugin

Ce plugin combine une skill de recherche documentaire avec le MCP de la documentation OpenAI. Il nécessite un accès réseau, mais aucun identifiant ni aucune dépendance de serveur local.

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

Déclarez le répertoire de la skill et la configuration MCP dans .codex-plugin/plugin.json :

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

Les chemins sont résolus à partir de la racine du plugin. Ils doivent commencer par ./, rester à l’intérieur du plugin et ne contenir aucun composant ... Consultez Créez le package de votre plugin pour connaître le format complet du manifeste.

Ajoutez le serveur à .mcp.json. Ce fichier utilise le format des plugins, qui diffère de celui de agent.tools :

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

Ajoutez les instructions à skills/docs-search/SKILL.md :

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

Enregistrez des plugins dans un bac à sable auto-hébergé

Copiez le plugin dans /workspace/plugins/docs-helper et ajoutez ce chemin absolu à environment.capability_directories. Sélectionnez la racine du plugin, qui contient .codex-plugin/plugin.json.

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

Connectez l’exécuteur avant que l’agent utilise le plugin. Autorisez l’environnement à accéder à https://developers.openai.com/mcp.

Pour plusieurs plugins, indiquez chaque répertoire racine. Un répertoire parent permet de découvrir les skills imbriquées, mais ne charge pas la configuration MCP de chaque plugin enfant.

Importez des plugins dans un bac à sable hébergé par OpenAI

Fournissez une archive ZIP par plugin dans environment.plugins. Chaque archive ZIP doit contenir un dossier de plugin dans lequel se trouve .codex-plugin/plugin.json. Le nom et la description fournis dans la requête doivent correspondre à ceux du manifeste.

Cette fonction utilitaire crée une archive de votre dossier et une session. Passez-lui votre client API et le chemin vers docs-helper. OpenAI extrait et enregistre automatiquement le plugin.

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(),
                        },
                    }
                ],
            },
        )

Réutilisez une configuration de plugins hébergée

Créez un modèle d’environnement avec la liste des plugins. Pour les sessions suivantes, définissez environment.environment_template_id sur l’ID du modèle enregistré.

Omettez environment.plugins pour hériter de la liste des plugins du modèle. Si vous fournissez une liste, elle remplace celle du modèle. Chaque session dispose de son propre environnement, partagé par l’agent racine et ses sous-agents.

Configurez l’authentification des serveurs MCP

Cet exemple ne nécessite aucune authentification. Pour les autres serveurs MCP des plugins :

• HTTP : bearer_token_env_var lit une variable d’environnement et envoie sa valeur sous forme de token bearer. Les autres valeurs de http_headers sont littérales ; env_http_headers n’est pas pris en charge.
• Stdio : env_vars liste les variables d’environnement à transmettre au processus du serveur. Installez l’exécutable et ses dépendances dans l’environnement. Un chemin relatif dans cwd est résolu à partir de la racine du plugin.

N’incluez aucun secret dans les fichiers et archives des plugins. Les connexions MCP des plugins s’exécutent depuis l’environnement de la session. Consultez Authentification MCP pour connaître les limites d’utilisation des identifiants.

Pour les MCP stdio hébergés, omettez la politique réseau ou définissez-la sur enabled. Les politiques réseau disabled et restricted ne sont pas prises en charge pour ces connexions.

Testez un plugin

Envoyez un message de session ordinaire demandant l’utilisation de la skill :

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

Vérifiez que le tour est terminé et que ses éléments enregistrés incluent un appel réussi à openai_docs. La réponse doit suivre les instructions de la skill et citer la documentation. Pour un plugin contenant uniquement des skills, vérifiez que sa sortie respecte les instructions ; un appel MCP n’est pas nécessaire.

Créez une nouvelle session après avoir modifié les fichiers d’un plugin ou un modèle. Les sessions existantes ne rechargent pas les outils. En cas d’erreur de connexion, consultez Dépannage MCP. Une fois les tests terminés, supprimez les sessions de test et arrêtez les ressources de calcul auto-hébergées.