Codex CLIのプラグインシステムは急速に進化しており、/plugins コマンドを使ってマーケットプレイスごとの閲覧、インストール、有効化・無効化ができるようになりました。今や多くのチームが、社内のツールチェーンを再利用可能なCodexプラグインとしてパッケージ化しています。しかし、公式マーケットプレイスのセルフサービス登録窓口は現在「審査制」となっており、開発者はマニフェストの構造やローカルでのデバッグ方法を理解し、審査プロセスを通過しなければ、プラグインをユーザーに届けることができません。本記事では、ゼロからの構築、ローカルテスト、Gitマーケットプレイスでの配布、そして公式審査を経て公開するまでの全工程を実戦形式で解説し、陥りやすい注意点をまとめました。
Codexプラグインの構成要素
Codexプラグインとは、本質的にいくつかの機能をパッケージ化し、インストールや配布を可能にしたユニットです。OpenAIの公式ドキュメントによると、プラグインには「skills（再利用可能なスキル定義）」、「MCP-backed app（外部ツールと連携するサービス）」、「ライフサイクルhooks」、そしてオプションのブラウザ拡張機能や定期実行タスクのテンプレートを含めることができます。これらのコンポーネントはすべて必須というわけではなく、skillsのみを含む軽量なプラグインであっても、問題なくインストールして利用可能です。
各コンポーネントの役割を理解することが、適切なマニフェストを作成する前提となります。以下の表は、Codexプラグインディレクトリにおける4つの主要コンポーネントのパスと役割をまとめたものです。
| コンポーネント | 格納パス | 役割 | 必須か |
|---|---|---|---|
| plugin.json | .codex-plugin/plugin.json |
プラグインの識別情報とメタデータ | 必須 |
| skills | skills/<skill-name>/SKILL.md |
再利用可能なタスク指示の定義 | 任意 |
| MCP servers | .mcp.json |
外部ツールサービス接続の設定 | 任意 |
| hooks | hooks/hooks.json |
ライフサイクル・フックコマンドの宣言 | 任意 |
注目すべき点として、もしプラグインがチーム内で再利用するだけのSKILL.mdファイルであれば、マニフェストのプロセスをすべて踏む必要はありません。ファイルを直接 .agents/skills/ ディレクトリに配置すれば、Codexが自動的に検知するため、プラグインリストは不要です。これは多くのチームが「社内スクリプト」から「正式なプラグイン」へ移行する際の中間形態としてよく見られます。
プラグインの機能範囲は、多くの人が想像するよりも広範です。最も一般的なskillsやMCP-backed app以外にも、公式ドキュメントにはブラウザ拡張機能に必要な能力宣言や、再利用可能な定期実行タスクのテンプレートが含まれています。これは、プラグインが「ユーザーが能動的にトリガーする」インタラクティブなリクエストだけでなく、「周期的にバックグラウンドで実行される」自動化シナリオにも対応できることを意味します。どのコンポーネントを組み合わせて一つのプラグインにするかは、インストール体験とメンテナンスコストのトレードオフです。コンポーネントが多いほど機能は充実しますが、審査用の資料やテストケースも増加します。提出前に、すべての機能を詰め込むのではなく、ターゲットユーザーが本当に必要としている能力は何かを明確にすることをお勧めします。
plugin.json から始める：プラグインマニフェストファイルの詳細解説
plugin.json はプラグインの「身分証明書」であり、Codex がどのようにプラグインを認識し、読み込み、表示するかを決定します。最小限の構成で動作させるために必要なフィールドは、以下の3つだけです。
{
"name": "my-first-plugin",
"version": "1.0.0",
"description": "再利用可能な挨拶ワークフロー",
"skills": "./skills/"
}
name フィールドには、安定した kebab-case（ケバブケース）での命名を推奨します。一度決めた識別子は、その後のバージョンアップでも変更しないでください。変更してしまうと、マーケットプレイス側で同一プラグインの更新として正しく認識されなくなります。version はセマンティックバージョニングに従う必要があり、マーケットプレイスはこのフィールドを基にユーザーへアップデートを通知します。マニフェスト内で参照されるすべてのパスは、プラグインのルートディレクトリからの相対パス（./ で始まるもの）である必要があり、ルートディレクトリの外へ出ることはできません。
これら3つの基本フィールドに加え、skills には複数のスキルディレクトリを配列で指定することも可能です。また、hooks、mcpServers、apps フィールドは、それぞれ hooks/hooks.json、.mcp.json、.app.json といった設定ファイルを指し示します。「フィールドがファイルを指す」という設計により、マニフェスト自体を簡潔に保つことができます。具体的なスキルの説明やツールの設定は独立したファイルで管理されるため、複数人での開発時にコンポーネントごとの並行作業がしやすく、競合も発生しにくくなります。
公式マーケットプレイスへの公開を検討している場合は、表示用のメタデータを追加する必要があります。以下の表は、公開時に補完すべき重要なフィールドをまとめたものです。
| フィールド | 型 | 説明 |
|---|---|---|
| author / repository | 文字列 | プラグインのソース元。認証済みIDと一致させることを推奨 |
| interface.displayName | 文字列 | マーケットプレイスで表示されるプラグイン名 |
| interface.category | 文字列 | プラグインのカテゴリ。ユーザーのブラウジングに影響 |
| interface.capabilities | 配列 | プラグインが持つ能力タグの宣言 |
| mcpServers / apps / hooks | オブジェクト | 各コンポーネントの設定ファイルへのパス |
マニフェスト作成時に最も陥りやすい罠は、パスの指定ミスです。例えば skills フィールドに絶対パスを書いてしまったり、先頭の ./ を忘れたりすると、ローカルでは動くのに審査提出時には「無効なマニフェスト」と判定される原因になります。提出前には、クリーンなディレクトリでプラグインリポジトリを再度クローンし、実際のインストール環境をシミュレートしてテストを行うことを強くお勧めします。
ローカルでのスキャフォールディングとデバッグ：プラグインを動かしてみよう
マニフェストをゼロから手書きするのは効率的ではありません。公式には $plugin-creator スキルが用意されており、Codex CLI で対話的にスキャフォールディング（雛形作成）を行うことができます。
codex "infra-monitor という名前のプラグインを $plugin-creator スキャフォールディングで生成して"
このコマンドを実行すると、マニフェスト、サンプルスキル、ローカルマーケットプレイス用のエントリが自動生成され、手作業によるディレクトリ構造作成の手間が省けます。生成後、プラグインはすぐにローカル環境でインストール・テストが可能であり、リモートリポジトリへの公開は不要です。
ローカルデバッグの段階で、プラグイン内のスキルが異なるベンダーの大規模言語モデルを呼び出して比較テストを行う場合、統一された API ゲートウェイを利用すると環境切り替えのコストを大幅に削減できます。MCP サーバーの機能を検証する際、通常は base_url を APIYI (apiyi.com) が提供する API 中継サービスに向けることで、1つの API キーで複数のモデルを切り替えながら、同一のプラグインロジックでの挙動の違いを効率的に比較できます。
from openai import OpenAI
client = OpenAI(
api_key="your-apiyi-key",
base_url="https://api.apiyi.com/v1"
)
🎯 デバッグのアドバイス: Codex プラグイン開発では、MCP サーバーが異なるモデルでどのような応答を返すかを繰り返しテストする必要があります。APIYI (apiyi.com) プラットフォームを利用して多モデル呼び出しを一元管理すれば、モデルごとに個別のキーを取得したり、呼び出しロジックを個別にメンテナンスしたりする必要がなくなり、プラグイン本来の機能磨きに集中できます。
ローカルマーケットプレイスのエントリを手動で作成する以外にも、~/.agents/plugins/marketplace.json（個人用）やリポジトリルートの .agents/plugins/marketplace.json（チーム用）でローカルパスを直接宣言することも可能です。source フィールドを local に設定すれば、リモートへプッシュすることなくインストール検証が完了します。
もしプラグインに ChatGPT 開発者モードとの連携が必要な MCP-backed app が含まれている場合は、別の手段もあります。ChatGPT の設定で開発者モードを有効にし、MCP-backed app を作成して app ID を取得します。その後、$plugin-creator でその ID を紐付けることで、実際の対話環境でプラグインとアプリ間のデータフローを検証できます。これは純粋なコマンドラインデバッグよりも公開後の実環境に近いため、審査提出前には必ず一度通しておくことを強く推奨します。
Git への登録とチーム内配布
プラグインのローカル検証が完了した後、チーム内での配布であれば公式の審査を待つ必要はなく、Git リポジトリを使ってマーケットプレイスのソースを構築するだけで十分です。Codex CLI には、マーケットプレイス管理専用のコマンドが用意されています。
| コマンド | 用途 |
|---|---|
codex plugin marketplace add owner/repo |
GitHub リポジトリをマーケットプレイスのソースとして追加 |
codex plugin marketplace add owner/repo --ref v2.1.0 |
特定のブランチやタグを固定し、段階的リリースを制御 |
codex plugin marketplace list |
追加済みのマーケットプレイス一覧を表示 |
codex plugin marketplace upgrade |
マーケットプレイスの更新を取得 |
codex plugin marketplace remove |
マーケットプレイスのソースを削除 |
コードリポジトリの規模が大きいチームでは、--sparse .agents/plugins パラメータを使用してプラグイン関連のディレクトリのみを取得することで、リポジトリ全体のクローンによるインストール速度の低下を防ぐことができます。この Git マーケットプレイス方式は、企業内のツールチェーンに最適です。公開審査を通す必要がなく、プラグインの更新は新しいタグをプッシュするだけで済み、チームメンバーは upgrade コマンドを一度実行するだけで同期が完了します。
実践的な観点から見ると、Git マーケットプレイス方式には隠れたメリットがあります。それは、プラグインのイテレーション（反復）サイクルと、チーム内のリリースサイクルを切り離せることです。業務コードは1日に何度もマージされることがありますが、プラグインは対話型ツールチェーンの一部であるため、更新頻度が高すぎるとユーザーのメンタルモデルを乱す可能性があります。プラグインのバージョンとタグを固定のリリーススケジュール（例：週次や隔週のマージ）に紐付けることをお勧めします。これにより、機能の進化速度を維持しつつ、チームメンバーが新しい操作感に頻繁に適応しなければならない状況を避けられます。
公式 Marketplace への提出と審査プロセス
公式 Marketplace のセルフサービス型公開機能は、現時点では完全には開放されておらず、OpenAI のドキュメントにも「近日公開」と明記されています。現段階で一般ユーザー向けに正式提出する場合は、プラグイン提出ポータルを通じた手動審査プロセスが必要です。提出前に本人確認を完了させる必要があり、個人開発者の場合は「個人認証（individual verification）」、企業名義で公開する場合は「法人認証（business verification）」が必要です。審査担当者は、公開主体と提出書類の内容が一致しているかを確認します。
正式提出に必要な資料リストは以下の通りです：
| 資料カテゴリ | 具体的な要件 |
|---|---|
| プラグイン基本情報 | 名称、説明、ロゴ、カテゴリ、関連 URL |
| MCP サーバー | 公開アクセス可能なドメイン、CSP ポリシー、認証設定 |
| デモ用アカウント | 直接ログイン可能であること（MFA やメールによる二次認証は不可） |
| テストケース | 正常系 5 件 + 異常系 3 件 |
| ツールアノテーション | readOnlyHint、openWorldHint、destructiveHint が実際の挙動と一致していること |
提出プロセスは、Info（公開リスト情報）、MCP（サーバーと認証設定）、Skills（最終的なスキルパッケージのアップロード）、Prompts（開始時のプロンプト例）、Testing（テストケース）、Global（利用可能な国と地域）という複数のフォームセクションに分かれています。最後に Submit セクションでリリースノートを記入し、ポリシーへの同意を確認します。審査通過後、開発者がポータル上で公開タイミングを選択すると、プラグインは ChatGPT および Codex の共通プラグインディレクトリに表示されます。
プラグインに MCP ベースのアプリが含まれる場合は、MCP サーバーがデプロイされているドメインと、プラグインで宣言されているドメインが一致していることを証明するため、ドメイン所有権の追加検証が必要です。審査チームは、ツールが返す結果に不要な個人データや API キー情報が含まれていないかを重点的にチェックします。この点は、審査で差し戻されてから修正するのではなく、ツール出力の設計段階で事前に回避しておくべきです。
バージョン管理とよくある落とし穴
プラグインを公開した後、バージョン管理の詳細はユーザーのアップグレード体験に直結します。マーケットプレイスは version フィールドに基づいて更新の有無を判断するため、セマンティックバージョニング（Semantic Versioning）のルールを厳守することが重要です。バグ修正にはパッチバージョン、新機能の追加にはマイナーバージョン、そして破壊的変更がある場合にのみメジャーバージョンを上げてください。
インストール済みのプラグインは、ローカルパス ~/.codex/plugins/cache/$MARKETPLACE_NAME/$PLUGIN_NAME/$VERSION/ にキャッシュされます。「プラグインを更新したのに挙動が変わらない」といった問題が発生した際は、コードのロジックを再デバッグする前に、キャッシュが新しいバージョンに更新されているかを確認する方が、原因を素早く特定できることがよくあります。また、企業環境では requirements.toml による厳格なホワイトリストポリシーが適用されることがあります。MCPサーバーは名前とIDの両方が一致している必要があり、どちらか一方が異なるとサービスが警告なしに無効化されます。このような問題は、本番環境にデプロイする前に、テスト環境でポリシー設定を一通り確認することをお勧めします。
以下の表は、開発者から多く寄せられる落とし穴と、その対処法をまとめたものです。
| よくある問題 | 対処法 |
|---|---|
| manifest のパスが絶対パスになっている | ./ で始まる相対パスに統一する |
| 暗黙的な呼び出しで意図しないプラグインが起動する | @plugin-name を使用して明示的に指定する |
| 更新後の挙動が反映されない | ローカルのプラグインキャッシュディレクトリが更新されているか確認する |
| 企業ポリシー下で MCP がサイレント無効化される | requirements.toml 内の名前とIDが一致しているか照合する |
公式審査に提出する前に、サードパーティ製のツールである codex-plugin-scanner を実行することをお勧めします。このツールは、インストール可能性、メンテナンス状況、MCPの安全性、配布元などの観点からプラグインを評価します。特に企業顧客向けに配布するプラグインの場合、審査で差し戻される前に問題を早期発見しておくことで、時間を大幅に節約できます。
もう一つ見落としがちなのが、明示的な呼び出しと暗黙的な発見の違いです。Codex はプラグインが明示的に指定されていない場合、コンテキストに基づいて最も関連性の高いスキルを自動的にマッチングします。同じワークスペースに機能が似たプラグインが複数インストールされていると、この暗黙的なマッチングによって意図しないプラグインが選ばれる可能性があります。特にチームで共有するワークスペースでは、@plugin-name を使って明示的に宣言する習慣をつけることで、「プラグイン同士の干渉」によるトラブルシューティングのコストを削減できます。
Codex プラグイン開発に関するよくある質問（FAQ）
プラグインと単体の SKILL.md ファイルにはどのような違いがありますか？
SKILL.md はプラグインを構成するコンポーネントの一つです。単体で使用する場合は manifest は不要で、.agents/skills/ ディレクトリに配置するだけで自動的に認識されます。一方、プラグインはスキル、MCPサーバー、フックなどの複数のコンポーネントを、IDを持ちバージョン管理可能な一つのパッケージとしてまとめたもので、正式な配布や更新履歴の追跡が必要なシナリオに適しています。
開発段階で複数のモデルアカウントを使って比較テストを行いたい場合はどうすればよいですか？
これはプラグイン開発、特にモデルの選択やプロンプトの調整を行う際に頻繁に直面する課題です。各モデルベンダーごとに個別にアカウントを開設し、APIキーを管理するよりも、APIYI (apiyi.com) のような統合ゲートウェイを利用することをお勧めします。一つのキーで主要なモデルを呼び出してA/Bテストを行えるため、アカウント管理ではなくプラグインのロジックそのもののデバッグに集中できます。
Git マーケットプレイスでの配布と公式 Marketplace への公開は共存できますか？
はい、可能です。多くのチームは、まず Git マーケットプレイスで内部検証や小規模な先行公開を行い、安定性を確認してから公式への提出プロセスに進みます。これら2つの配布方法は競合せず、manifest の構造も共通です。
プラグインの審査にはどのくらい時間がかかりますか？
公式ドキュメントには現時点で固定の期間は示されておらず、審査プロセスは継続的に構築・拡充中であるとされています。また、優先審査（特急対応）もサポートされていません。審査期間をプロジェクトスケジュールの不確定要素として考慮し、提出前に必要な資料をすべて揃えておくことで、不足資料のやり取りによる手戻りを減らすことが、リリースまでの時間を短縮する最も現実的な方法です。
最後に
Codexプラグイン開発における核心的な難しさは、実はコードそのものよりも、manifestの仕様要件の理解や審査プロセスに向けた資料準備にあります。これらの細部は想像以上に複雑ではありませんが、パスの書き方やフィールドの欠落といった些細なミスで差し戻されることがよくあります。
開発を進める際は、「ローカル環境でのスキャフォールド検証 → Gitマーケットプレイスでの小規模な配布 → 公式審査への提出」という順序で行い、各ステップで実際の環境でのテスト時間を確保することをお勧めします。もし開発するプラグインが複数のモデル呼び出しを伴う場合や、頻繁にテストモデルを切り替える必要がある場合は、APIYI (apiyi.com) が提供する統一されたAPI中継サービスを活用してみてください。環境構築の手間を大幅に省き、プラグイン自体のブラッシュアップにより多くの時間を割けるようになります。
