プラグイン

プラグインには、スキルと MCP 設定のいずれか一方または両方をまとめられます。プラグインのファイルを自分の環境に読み込むか、ZIP ファイルとして OpenAI がホストする環境にアップロードします。

プラグインのパッケージ化

この例では、ドキュメント検索スキルと、OpenAI ドキュメント用の MCP サーバーを組み合わせます。ネットワークアクセスは必要ですが、認証情報やローカルサーバー用の依存関係は不要です。

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

スキルのディレクトリと MCP 設定ファイルを .codex-plugin/plugin.json に指定します。

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

パスの基準はプラグインのルートディレクトリです。各パスは ./ で始まり、プラグイン内を指す必要があります。パスの構成要素に .. は使用できません。マニフェストの形式の詳細は「プラグインのパッケージ化」を参照してください。

サーバーを .mcp.json に追加します。このファイルではプラグイン用の形式を使用します。これは agent.tools の形式とは異なります。

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

スキルの指示を 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.

セルフホスト型サンドボックスへのプラグインの登録

プラグインを /workspace/plugins/docs-helper にコピーし、その絶対パスを environment.capability_directories に追加します。指定するのは、.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

エージェントがプラグインを使用する前に、エグゼキューターを接続してください。環境から https://developers.openai.com/mcp にアクセスできるようにします。

複数のプラグインを登録する場合は、それぞれのルートディレクトリを指定します。親ディレクトリを指定すると配下のスキルは検出できますが、各プラグインの MCP 設定までは読み込まれません。

OpenAI がホストするサンドボックスへのプラグインのアップロード

environment.plugins に、プラグインごとに 1 つの ZIP ファイルを指定します。各 ZIP ファイルにはプラグインフォルダーを 1 つだけ含め、その中に .codex-plugin/plugin.json を配置してください。リクエストで指定する名前と説明は、マニフェストの名前と説明に一致する必要があります。

次のヘルパー関数は、フォルダーをパッケージ化してセッションを作成します。API クライアントと docs-helper へのパスを渡してください。OpenAI がプラグインを自動的に展開して登録します。

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

ホスト環境でのプラグイン設定の再利用

プラグインのリストを指定して環境テンプレートを作成します。以降のセッションでは、environment.environment_template_id に保存したテンプレートの ID を設定します。

environment.plugins を省略すると、テンプレートのプラグインリストが引き継がれます。リストを指定すると、そのセッションでは指定したリストがテンプレートのリストに代わって使われます。セッションごとに専用の環境が作成され、ルートエージェントとそのサブエージェントがこの環境を共有します。

MCP サーバーの認証

この例では認証は不要です。他のプラグインの MCP サーバーで認証が必要な場合は、接続方式に応じて次のように設定します。

• HTTP： bearer_token_env_var で指定した環境変数の値が Bearer トークンとして送信されます。その他の http_headers の値はリテラルとして扱われます。env_http_headers はサポートされていません。
• 標準入出力： env_vars に、サーバープロセスに渡す環境変数を列挙します。実行ファイルとその依存関係を環境にインストールしてください。相対パスで指定した cwd は、プラグインのルートディレクトリを基準に解決されます。

プラグインのファイルやアーカイブにはシークレットを含めないでください。プラグインの MCP サーバーへの接続は、セッションの環境から行われます。認証情報にアクセスできる範囲については、「MCP の認証」を参照してください。

ホスト環境で標準入出力を使う MCP サーバーに接続する場合は、ネットワークポリシーを省略するか、enabled に設定します。この接続方式では、disabled と restricted のネットワークポリシーはサポートされていません。

プラグインのテスト

通常のセッションメッセージで、スキルの使用を依頼します。

docs-search を使って、Responses API の出力をストリーミングする方法を説明してください。ドキュメントへのリンクも含めてください。

ターンが完了し、そのターンの保存済みアイテムに openai_docs の呼び出しが成功した記録があることを確認します。回答がスキルの指示に従い、参照したドキュメントを示していることも確認してください。スキルのみのプラグインでは、出力が指示に沿っていることを確認します。MCP の呼び出しは不要です。

プラグインのファイルやテンプレートを変更した後は、新しいセッションを作成してください。既存のセッションではツールが再読み込みされません。接続エラーが発生した場合は、「MCP 接続のトラブルシューティング」を参照してください。テストが終わったら、テスト用セッションを削除し、セルフホスト環境のコンピューティングリソースを停止します。