プラグインは、スキルや MCP 構成、またはその両方をまとめたパッケージです。ファイルを自分の環境に読み込むか、ZIP を OpenAI がホストする環境にアップロードして使用します。
プラグインのパッケージ化
このプラグインは、ドキュメント検索スキルと OpenAI ドキュメント MCP を組み合わせたものです。ネットワークアクセスは必要ですが、認証情報やローカルサーバーの依存関係は不要です。
docs-helper/
├── .codex-plugin/plugin.json
├── .mcp.json
└── skills/docs-search/SKILL.md.codex-plugin/plugin.json にスキルのディレクトリと MCP 構成を宣言します。
{
"name": "docs-helper",
"version": "1.0.0",
"description": "Find answers in OpenAI developer documentation.",
"skills": "./skills/",
"mcpServers": "./.mcp.json"
}パスはプラグインのルートを基準に解決されます。./ で始まり、プラグインの内部を指す必要があり、.. 要素を含めることはできません。マニフェストの形式の詳細は、プラグインのパッケージ化を参照してください。
.mcp.json にサーバーを追加します。このファイルでは、agent.tools とは異なるプラグイン形式を使用します。
{
"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 が含まれるプラグインのルートを指定してください。
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);エージェントがプラグインを使用する前に、エグゼキューターを接続します。環境から https://developers.openai.com/mcp にアクセスできるようにしてください。
複数のプラグインを使用する場合は、それぞれのルートを指定します。親ディレクトリを指定すると、その配下のスキルは検出できますが、各子プラグインの MCP 構成は読み込まれません。
OpenAI がホストするサンドボックスへのプラグインのアップロード
environment.plugins にプラグインごとに 1 つの ZIP を指定します。各 ZIP には、.codex-plugin/plugin.json を含むプラグインフォルダーを 1 つ格納する必要があります。リクエストの名前と説明は、マニフェストと一致する必要があります。
このヘルパーはフォルダーをパッケージ化し、セッションを作成します。API クライアントと docs-helper へのパスを渡してください。OpenAI がプラグインを自動的に展開して登録します。
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(),
},
}
],
},
)ホスト環境のプラグイン設定の再利用
プラグインのリストを指定して、環境テンプレートを作成します。以降のセッションでは、environment.environment_template_id に保存したテンプレートの ID を設定します。
environment.plugins を省略すると、テンプレートのプラグインリストを引き継ぎます。リストを指定すると、そのリストに置き換わります。セッションごとに専用の環境が用意され、そのセッションのルートエージェントとサブエージェントが共有します。
MCP サーバーの認証
この例では認証は不要です。ほかのプラグインの MCP サーバーでは、次のように設定します。
- HTTP：
bearer_token_env_varは環境変数を読み取り、その値を Bearer トークンとして送信します。その他のhttp_headersの値はリテラルとして扱われます。env_http_headersはサポートされていません。 - Stdio：
env_varsには、サーバープロセスに渡す環境変数を列挙します。実行ファイルとその依存関係を環境にインストールしてください。cwdが相対パスの場合は、プラグインのルートを基準に解決されます。
プラグインのファイルやアーカイブにシークレットを含めないでください。プラグインの MCP 接続は、セッションの環境から行われます。認証情報の利用範囲については、MCP 認証を参照してください。
ホスト環境の stdio MCP では、ネットワークポリシーを省略するか、enabled に設定してください。これらの接続では、disabled と restricted のネットワークポリシーはサポートされていません。
プラグインのテスト
スキルの使用を依頼する通常のセッションメッセージを送信します。
Use docs-search to explain how to stream Responses API output. Include links to the documentation.
ターンが完了し、その保存済みアイテムに openai_docs の呼び出しの成功が記録されていることを確認します。回答はスキルの指示に従い、ドキュメントを引用している必要があります。スキルのみのプラグインの場合は、出力が指示に沿っているかを確認してください。MCP の呼び出しは不要です。
プラグインのファイルやテンプレートを変更した後は、新しいセッションを作成してください。既存のセッションではツールは再読み込みされません。接続エラーについては、MCP のトラブルシューティングを参照してください。完了したら、テストセッションを削除し、セルフホスト型のコンピューティングリソースを停止してください。