プラグインを構築する
ChatGPT 向けのプラグインを作成、テスト、配布します
このページはプラグイン作成者向けです。Web 版 ChatGPT Work、または ChatGPT デスクトップアプリの ChatGPT Work や Codex でプラグインを探し、インストールして使用する方法については、プラグインをご覧ください。まだ 1 つのリポジトリや個人用ワークフローを試行錯誤している段階なら、まずローカルスキルから始めてください。チーム間でそのワークフローを共有したい場合、コネクタや MCP 設定をまとめたい場合、ライフサイクルフックをパッケージ化したい場合、または安定したパッケージを公開したい場合は、プラグインを構築します。
プラグインには、スキル、MCP を基盤とするアプリ、またはその両方を含めることができます。プラグインでサービスへの接続や MCP server 経由でのツール公開が必要な場合は、 アプリを構築するをご覧ください。
完全な公開例については、 Figma、 Notion、 Web アプリを構築するをご確認ください。
@plugin-creator でプラグインを作成する
最もすばやくセットアップするには、組み込みの @plugin-creator スキルを使用します。
このスキルは、必須の .codex-plugin/plugin.json マニフェストをひな形から作成し、テスト用のローカルマーケットプレイスエントリも生成できます。プラグインフォルダーがすでにある場合でも、
@plugin-creator を使用してローカルマーケットプレイスに接続できます。
MCP-server を基盤とする開発モードアプリを参照するプラグインをローカルで作成してテストする
MCP-server を基盤とするアプリを含むプラグインをローカルでテストしたい場合も、plugin-creator スキルを使用できます。プラグインには引き続きローカルのプラグインフォルダーとマニフェストが必要ですが、アプリ自体は ChatGPT の開発者モードで起動します。
まず、ChatGPT で開発者モードを有効にします。
- ChatGPT を開きます。
- **Settings(設定)**を開きます。
- **Security and login(セキュリティとログイン)**を選択します。
- **Developer mode(開発者モード)**をオンにします。
次に、開発者モードでアプリを作成します。
- **Settings → Plugins(設定 → プラグイン)**またはプラグインページを開きます。
- プラスボタンを選択します。
- モーダルの項目を入力し、MCP server 用の開発者モードアプリを作成します。
- ChatGPT がアプリを作成したら、ブラウザーの URL からアプリ ID をコピーします。この ID は
plugin_asdk_appで始まります。
その plugin_asdk_app... ID を、ChatGPT Work のチャットでは @plugin-creator に、
Codex では $plugin-creator に渡します。たとえば ChatGPT Work では、次のように入力します。
Plugin Creator のプロンプト@plugin-creator create a Codex plugin for my ChatGPT app.
Use plugin_asdk_app_6a4c0062f3b88191855c0a80eac5d53d and name it Acme Support.
Include a personal marketplace entry so I can test it locally.plugin-creator スキルは、プラグインフォルダーと必須の
.codex-plugin/plugin.json を作成し、ChatGPT アプリ用の接続設定を追加します。個人用マーケットプレイスエントリの作成を依頼した場合、テスト用として Plugins Directory のローカルソース配下にプラグインが表示されます。
plugin-creator スキルがプラグインを作成したら、次の手順を実行します。
.app.jsonを確認し、正しいplugin_asdk_app...ID を参照していることを確かめます。.codex-plugin/plugin.jsonを確認し、そのappsフィールドが./.app.jsonを参照していることを確かめます。- アプリと一緒に反復可能なワークフローをプラグインへ含める場合は、バンドルするスキルを
skills/配下に追加します。 - スキルによって個人用マーケットプレイスエントリが作成された場合は、ChatGPT を更新し、 Plugins Directory のローカルソースからプラグインをインストールします。その後、新しいチャットでテストします。
マニフェストの形式とファイル配置については、プラグインの構造と パスの規則をご覧ください。
独自に選定したプラグインリストを作成する
マーケットプレイスは、プラグインの JSON カタログです。@plugin-creator では単一のプラグイン用カタログを生成できます。同じマーケットプレイスにエントリを追加し続けることで、リポジトリ、チーム、または個人用ワークフロー向けに独自に選定したリストを作成できます。
ChatGPT デスクトップアプリの ChatGPT Work または Codex では、各マーケットプレイスが
Plugins Directory で選択可能なソースとして表示されます。リポジトリ単位のリストには
$REPO_ROOT/.agents/plugins/marketplace.json、個人用リストには
~/.agents/plugins/marketplace.json を使用します。plugins[] 配下にプラグインごとに 1 つのエントリを追加し、各 source.path にはマーケットプレイスのルートを基準とする ./ で始まるパスでプラグインフォルダーを指定します。また、
interface.displayName には、アプリのマーケットプレイス選択画面に表示するラベルを設定します。その後、ChatGPT デスクトップアプリを再起動します。Plugins Directory を開き、マーケットプレイスを選択すると、その選定済みリスト内のプラグインを閲覧またはインストールできます。
プラグインごとに別々のマーケットプレイスを用意する必要はありません。テスト中は 1 つのマーケットプレイスで単一のプラグインを公開し、プラグインの追加に合わせて、より大きな選定済みカタログへ拡張できます。
CLI からマーケットプレイスを追加する
config.toml を手動で編集する代わりに、codex plugin marketplace add を使用してマーケットプレイスソースを追加、追跡します。これらのコマンドは、プラグインの作成とカタログのセットアップに対応しています。ローカルプラグインのインストールとテストには、ChatGPT デスクトップアプリを使用します。
codex plugin marketplace add owner/repo
codex plugin marketplace add owner/repo --ref main
codex plugin marketplace add https://github.com/example/plugins.git --sparse .agents/plugins
codex plugin marketplace add ./local-marketplace-rootマーケットプレイスソースには、GitHub の省略表記(owner/repo または
owner/repo@ref)、HTTP または HTTPS の Git URL、SSH Git URL、ローカルマーケットプレイスのルートディレクトリを使用できます。Git ref を固定するには --ref を使用し、Git を基盤とするマーケットプレイスリポジトリで
sparse checkout を使用するには --sparse PATH を繰り返し指定します。--sparse は
Git マーケットプレイスソースにのみ有効です。
設定済みマーケットプレイスを確認、更新、または削除するには、次のコマンドを使用します。
codex plugin marketplace list
codex plugin marketplace upgrade
codex plugin marketplace upgrade marketplace-name
codex plugin marketplace remove marketplace-namecodex plugin marketplace list は、Codex が参照対象としている各マーケットプレイスと、その解決元となるルートパスを出力します。これには、ローカルのデフォルトマーケットプレイスと設定済みマーケットプレイスのスナップショットが含まれます。
プラグインを手動で作成する
まずは、1 つのスキルをパッケージ化する最小構成のプラグインを作成します。
.codex-plugin/plugin.jsonにマニフェストを持つプラグインフォルダーを作成します。
mkdir -p my-first-plugin/.codex-pluginmy-first-plugin/.codex-plugin/plugin.json
{
"name": "my-first-plugin",
"version": "1.0.0",
"description": "Reusable greeting workflow",
"skills": "./skills/"
}プラグインの name には、kebab-case の安定した名前を使用します。Codex はこれをプラグインの識別子およびコンポーネントの名前空間として使用します。
skills/<skill-name>/SKILL.md配下にスキルを追加します。
mkdir -p my-first-plugin/skills/hellomy-first-plugin/skills/hello/SKILL.md
---
name: hello
description: Greet the user with a friendly message.
---
Greet the user warmly and ask how you can help.- プラグインをマーケットプレイスに追加します。
@plugin-creatorでマーケットプレイスを生成するか、 独自に選定したプラグインリストを作成するの手順に従って、プラグインを Codex に手動で接続します。
その後、必要に応じて MCP 設定、コネクタ、またはマーケットプレイスのメタデータを追加できます。
ローカルプラグインを手動でインストールする
プラグインまたは選定済みリストへアクセスできる対象に応じて、リポジトリのマーケットプレイスまたは個人用マーケットプレイスを使用します。
リポジトリ
`$REPO_ROOT/.agents/plugins/marketplace.json` にマーケットプレイスファイルを追加し、プラグインを `$REPO_ROOT/plugins/` 配下に保存します。
**リポジトリマーケットプレイスの例**
ステップ 1:プラグインフォルダーを `$REPO_ROOT/plugins/my-plugin` にコピーします。mkdir -p ./plugins
cp -R /absolute/path/to/my-plugin ./plugins/my-pluginステップ 2:`$REPO_ROOT/.agents/plugins/marketplace.json` を追加または更新し、
`source.path` が `./` で始まる相対パスでそのプラグインディレクトリを指すようにします。{
"name": "local-repo",
"plugins": [
{
"name": "my-plugin",
"source": {
"source": "local",
"path": "./plugins/my-plugin"
},
"policy": {
"installation": "AVAILABLE",
"authentication": "ON_INSTALL"
},
"category": "Productivity"
}
]
}ステップ 3:ChatGPT デスクトップアプリを再起動し、プラグインが表示されることを確認します。個人用
`~/.agents/plugins/marketplace.json` にマーケットプレイスファイルを追加し、プラグインを `~/.codex/plugins/` 配下に保存します。
**個人用マーケットプレイスの例**
ステップ 1:プラグインフォルダーを `~/.codex/plugins/my-plugin` にコピーします。mkdir -p ~/.codex/plugins
cp -R /absolute/path/to/my-plugin ~/.codex/plugins/my-pluginステップ 2:`~/.agents/plugins/marketplace.json` を追加または更新し、プラグインエントリの `source.path` がそのディレクトリを指すようにします。
ステップ 3:ChatGPT デスクトップアプリを再起動し、プラグインが表示されることを確認します。マーケットプレイスファイルはプラグインの場所を参照するため、これらのディレクトリは固定要件ではなく例です。Codex は source.path を .agents/plugins/ フォルダーではなく、マーケットプレイスのルートを基準に解決します。ファイル形式については、
マーケットプレイスのメタデータをご覧ください。
プラグインを変更した後は、マーケットプレイスエントリが参照するプラグインディレクトリを更新し、 ChatGPT デスクトップアプリを再起動して、ローカルインストールに新しいファイルを反映させます。
ローカルプラグインをワークスペースで共有する
プラグインを作成したら、ChatGPT デスクトップアプリから追加します。ChatGPT を選択して切り替え画面で Work に切り替えるか、Codex を選択してから、**Plugins(プラグイン)**を開きます。その後、 ChatGPT ワークスペースの他のメンバーと共有できます。
- ChatGPT デスクトップアプリで **Plugins(プラグイン)**を開きます。
- **Created by you(自分が作成)**に移動し、プラグインの詳細ページを開きます。
- **Share(共有)**を選択します。
- ワークスペースのメンバーまたはグループを追加するか、共有リンクをコピーします。
- アクセスできるユーザーを選択し、招待またはリンクを送信します。
共有相手は、Plugins Directory の **Shared with you(共有アイテム)**からプラグインを見つけられます。ローカルプラグインをワークスペースで共有しても、公開 Plugins Directory には公開されません。共有プラグインはワークスペースと組織の境界内に留まり、そのワークスペースにサインインしていないアカウントはアクセスできません。チームや役割ごとに同じプラグインへのアクセスを共有する場合は、グループを使用します。リポジトリや CLI で配布する場合はマーケットプレイスを使用し、選択したチームメンバーに ChatGPT デスクトップアプリからプラグインをインストールしてもらう場合は、ワークスペース共有を使用します。
ワークスペース管理者は、requirements.toml に
features.plugin_sharing = false を追加することで、クラウドで管理される要件からプラグイン共有を無効にできます。
features.plugin_sharing = falseマーケットプレイスのメタデータ
リポジトリのマーケットプレイスを管理する場合は、
$REPO_ROOT/.agents/plugins/marketplace.json で定義します。個人用マーケットプレイスには、
~/.agents/plugins/marketplace.json を使用します。マーケットプレイスファイルは、
ChatGPT デスクトップアプリでのプラグインの順序とインストールポリシーを制御します。テスト中は 1 つのプラグインのみを表すことも、1 つのマーケットプレイス名の配下にまとめてアプリに表示したい選定済みプラグインリストを表すこともできます。プラグインをマーケットプレイスへ追加する前に、その version、公開者メタデータ、インストール画面の文言を他の開発者に提示できる状態にしてください。
{
"name": "local-example-plugins",
"interface": {
"displayName": "Local Example Plugins"
},
"plugins": [
{
"name": "my-plugin",
"source": {
"source": "local",
"path": "./plugins/my-plugin"
},
"policy": {
"installation": "AVAILABLE",
"authentication": "ON_INSTALL"
},
"category": "Productivity"
},
{
"name": "research-helper",
"source": {
"source": "local",
"path": "./plugins/research-helper"
},
"policy": {
"installation": "AVAILABLE",
"authentication": "ON_INSTALL"
},
"category": "Productivity"
}
]
}- マーケットプレイスの識別には、トップレベルの
nameを使用します。 - ChatGPT デスクトップアプリに表示するマーケットプレイスのタイトルには、
interface.displayNameを使用します。 - アプリがそのマーケットプレイスのタイトル配下に表示する選定済みリストを作成するには、
plugins配下にプラグインごとに 1 つのオブジェクトを追加します。 - 各プラグインエントリの
source.pathには、Codex に読み込ませるプラグインディレクトリを指定します。リポジトリへのインストールでは、多くの場合./plugins/配下に配置します。個人用インストールでは、./.codex/plugins/<plugin-name>が一般的なパターンです。 source.pathはマーケットプレイスのルートからの相対パスにし、./で始め、そのルート内に収めます。- ローカルエントリでは、
sourceに"./plugins/my-plugin"のような単純な文字列パスを指定することもできます。 - 各プラグインエントリには、必ず
policy.installation、policy.authentication、categoryを含めます。 policy.installationには、AVAILABLE、INSTALLED_BY_DEFAULT、NOT_AVAILABLEなどの値を使用します。- 認証をインストール時に行うか初回使用時に行うかは、
policy.authenticationで指定します。
マーケットプレイスは、Codex がプラグインを読み込む場所を制御します。プラグインが例示したディレクトリの外にある場合、ローカルの source.path で別の場所を指定できます。マーケットプレイスファイルは、プラグインを開発しているリポジトリ内にも、独立したマーケットプレイスリポジトリ内にも配置でき、
1 つのマーケットプレイスファイルから 1 つまたは複数のプラグインを参照できます。
マーケットプレイスエントリは、Git を基盤とするプラグインソースを参照することもできます。プラグインがリポジトリのルートにある場合は "source": "url"、サブディレクトリにある場合は
"source": "git-subdir" を使用します。
{
"name": "remote-helper",
"source": {
"source": "git-subdir",
"url": "https://github.com/example/codex-plugins.git",
"path": "./plugins/remote-helper",
"ref": "main"
},
"policy": {
"installation": "AVAILABLE",
"authentication": "ON_INSTALL"
},
"category": "Productivity"
}Git を基盤とするエントリでは、ref または sha セレクターを使用できます。Codex がマーケットプレイスエントリのソースを解決できない場合、マーケットプレイス全体を失敗させるのではなく、そのプラグインエントリをスキップします。
マーケットプレイスエントリでは、JavaScript パッケージレジストリからプラグインをインストールすることもできます。
{
"name": "npm-helper",
"source": {
"source": "npm",
"package": "@example/codex-plugin",
"version": "^1.2.0",
"registry": "https://registry.npmjs.org"
},
"policy": {
"installation": "AVAILABLE",
"authentication": "ON_INSTALL"
},
"category": "Productivity"
}package は必須で、レジストリスコープを含めることができます。version は省略可能で、パッケージバージョン、配布タグ、バージョン範囲を指定できますが、パスや URL のセレクターは指定できません。
registry は省略可能です。埋め込み認証情報、クエリ、フラグメントを含まない HTTPS URL である必要があります。
Codex はライフサイクルスクリプトを実行せずにパッケージをダウンロードします。
npm CLI がインストールされている必要があり、レジストリ認証にはその設定が使用されます。
ChatGPT デスクトップアプリでのマーケットプレイスの使用方法
プラグインマーケットプレイスは、ChatGPT デスクトップアプリが読み取り、インストールできるプラグインの JSON カタログです。
アプリは、次の場所からマーケットプレイスファイルを読み取れます。
- 公式 Plugins Directory を支える選定済みマーケットプレイス
$REPO_ROOT/.agents/plugins/marketplace.jsonにあるリポジトリのマーケットプレイス$REPO_ROOT/.claude-plugin/marketplace.jsonにある従来互換のマーケットプレイス~/.agents/plugins/marketplace.jsonにある個人用マーケットプレイス
マーケットプレイスを通じて公開されているプラグインは、どれでもインストールできます。アプリはプラグインを
~/.codex/plugins/cache/$MARKETPLACE_NAME/$PLUGIN_NAME/$VERSION/ にインストールします。ローカルプラグインでは $VERSION は local となり、アプリはマーケットプレイスエントリから直接ではなく、そのキャッシュパスにあるインストール済みコピーを読み込みます。
各プラグインは個別に有効または無効にできます。アプリは各プラグインのオン/オフ状態を ~/.codex/config.toml に保存します。
プラグインをパッケージ化して配布する
プラグインの構造
すべてのプラグインには、.codex-plugin/plugin.json にマニフェストがあります。また、
skills/ ディレクトリ、ライフサイクルフック用の hooks/ ディレクトリ、1 つ以上のコネクタを参照する
.app.json ファイル、MCP servers を設定する .mcp.json ファイル、対応画面でプラグインを表示するためのアセットを含めることもできます。
my-plugin/
├── .codex-plugin/
│ └── plugin.json # Required: plugin manifest
├── skills/
│ └── my-skill/
│ └── SKILL.md # Optional: skill instructions
├── hooks/
│ └── hooks.json # Optional: lifecycle hooks
├── .app.json # Optional: app or connector mappings
├── .mcp.json # Optional: MCP server configuration
└── assets/ # Optional: icons, logos, screenshots.codex-plugin/ に配置するのは plugin.json だけです。skills/、hooks/、
assets/、.mcp.json、.app.json はプラグインのルートに配置します。
公開するプラグインでは通常、クイックスタートのひな形に示されている最小構成の例よりも詳細なマニフェストを使用します。マニフェストには 3 つの役割があります。
- プラグインを識別します。
- スキル、コネクタ、MCP servers、フックなど、バンドルされたコンポーネントを参照します。
- 説明、アイコン、法的情報へのリンクなど、インストール画面のメタデータを提供します。
完全なマニフェストの例を次に示します。
{
"name": "my-plugin",
"version": "0.1.0",
"description": "Bundle reusable skills and connectors.",
"author": {
"name": "Your team",
"email": "team@example.com",
"url": "https://example.com"
},
"homepage": "https://example.com/plugins/my-plugin",
"repository": "https://github.com/example/my-plugin",
"license": "MIT",
"keywords": ["research", "crm"],
"skills": "./skills/",
"mcpServers": "./.mcp.json",
"apps": "./.app.json",
"hooks": "./hooks/hooks.json",
"interface": {
"displayName": "My Plugin",
"shortDescription": "Reusable skills and connectors",
"longDescription": "Distribute skills and connectors together.",
"developerName": "Your team",
"category": "Productivity",
"capabilities": ["Read", "Write"],
"websiteURL": "https://example.com",
"privacyPolicyURL": "https://example.com/privacy",
"termsOfServiceURL": "https://example.com/terms",
"defaultPrompt": [
"Use My Plugin to summarize new CRM notes.",
"Use My Plugin to triage new customer follow-ups."
],
"brandColor": "#10A37F",
"composerIcon": "./assets/icon.png",
"logo": "./assets/logo.png",
"screenshots": ["./assets/screenshot-1.png"]
}
}.codex-plugin/plugin.json は必須のエントリポイントです。その他のマニフェストフィールドは省略可能ですが、公開プラグインでは一般的に使用されます。
マニフェストのフィールド
トップレベルのフィールドを使用して、パッケージのメタデータを定義し、バンドルされたコンポーネントを参照します。
name、version、descriptionはプラグインを識別します。author、homepage、repository、license、keywordsは、公開者と検索用のメタデータを提供します。skills、mcpServers、apps、hooksは、プラグインのルートからの相対パスでバンドルされたコンポーネントを参照します。interfaceは、インストール画面でのプラグインの表示方法を制御します。
インストール画面のメタデータには、interface オブジェクトを使用します。
displayName、shortDescription、longDescriptionは、タイトルと説明文を制御します。developerName、category、capabilitiesは、公開者と機能のメタデータを追加します。websiteURL、privacyPolicyURL、termsOfServiceURLは、外部リンクを提供します。defaultPrompt、brandColor、composerIcon、logo、screenshotsは、開始時のプロンプトと視覚表現を制御します。
パスの規則
- マニフェスト内のパスはプラグインのルートからの相対パスにし、
./で始めます。 composerIcon、logo、screenshotsなどの視覚アセットは、可能な限り./assets/配下に保存します。- バンドルされたスキルフォルダーには
skills、.app.jsonにはapps、.mcp.jsonにはmcpServers、ライフサイクルフックにはhooksを使用します。 - 有効なプラグインには、スキル、MCP servers、コネクタと一緒にライフサイクルフックを含めることができます。
- プラグインのフックを
./hooks/hooks.jsonに保存する場合、.codex-plugin/plugin.jsonにhooksエントリを追加する必要はありません。Codex がそのデフォルトファイルを自動的に確認します。
バンドルされた MCP servers とライフサイクルフック
mcpServers は、サーバーマップを直接含むか、mcp_servers オブジェクトでラップした
.mcp.json ファイルを参照できます。
直接のサーバーマップ:
{
"docs": {
"command": "docs-mcp",
"args": ["--stdio"]
}
}ラップされたサーバーマップ:
{
"mcp_servers": {
"docs": {
"command": "docs-mcp",
"args": ["--stdio"]
}
}
}インストール後、ユーザーはプラグインを編集せずに、Codex の設定からバンドルされた MCP server を有効または無効にし、ツールの承認ポリシーを調整できます。プラグイン単位の MCP server ポリシーには、plugins.<plugin>.mcp_servers.<server> を使用します。
[plugins."my-plugin".mcp_servers.docs]
enabled = true
default_tools_approval_mode = "prompt"
enabled_tools = ["search"]
[plugins."my-plugin".mcp_servers.docs.tools.search]
approval_mode = "approve"プラグインが有効な場合、Codex はユーザー、プロジェクト、管理対象のフックと一緒に、プラグインからライフサイクルフックを読み込めます。
プラグインをインストールまたは有効化しても、そのフックが自動的に信頼されるわけではありません。プラグインにバンドルされたフックは管理対象外のフックであるため、ユーザーが現在のフック定義を確認して信頼するまで、Codex はそれらをスキップします。
プラグインフックのデフォルトファイルは hooks/hooks.json です。
{
"hooks": {
"SessionStart": [
{
"hooks": [
{
"type": "command",
"command": "python3 ${PLUGIN_ROOT}/hooks/session_start.py",
"statusMessage": "Loading plugin context"
}
]
}
]
}
}.codex-plugin/plugin.json で hooks を定義すると、Codex はデフォルトの
hooks/hooks.json の代わりに、そのマニフェストエントリを使用します。マニフェストのフィールドには、単一のパス、パスの配列、インラインの hooks オブジェクト、またはインラインの hooks オブジェクトの配列を指定できます。
{
"name": "repo-policy",
"hooks": ["./hooks/session.json", "./hooks/tools.json"]
}フックのパスには、skills、apps、mcpServers と同じマニフェストのパス規則が適用されます。
./ で始め、プラグインのルートを基準に解決し、プラグインのルート内に収めます。
プラグインのフックコマンドには、Codex 固有の環境変数
PLUGIN_ROOT と PLUGIN_DATA が渡されます。PLUGIN_ROOT はインストール済みプラグインのルートを指し、PLUGIN_DATA はプラグインの書き込み可能なデータディレクトリを指します。Codex は、既存のプラグインフックとの互換性を保つため、CLAUDE_PLUGIN_ROOT と CLAUDE_PLUGIN_DATA も設定します。
プラグインのフックは、通常のフックと同じイベントスキーマを使用します。対応するイベント、入力、出力、信頼性レビュー、現在の制限については、フックをご覧ください。
公式の公開プラグインを公開する
プラグインを一般公開するには、プラグイン申請ポータルから提出します。審査と公開プロセスの詳細については、プラグインを提出するをご覧ください。