プラグインをビルドする¶
このページはプラグイン作成者向けです。Web 版 ChatGPT の Work モード、または ChatGPT デスクトップアプリの Work モードや Codex でプラグインを参照、インストール、使用する方法については、プラグインを参照してください。1 つのリポジトリまたは個人のワークフローをまだ反復中の場合は、ローカルスキルから始めてください。チーム間でワークフローを共有したい場合、コネクターや MCP 設定をまとめたい場合、ライフサイクルフックをパッケージ化したい場合、または安定したパッケージを公開したい場合は、プラグインをビルドしてください。
プラグインには、スキル、MCP ベースのアプリ、またはその両方を含めることができます。プラグインでサービスへの接続や MCP サーバー経由でのツールの公開が必要な場合は、アプリをビルドするを参照してください。
完全な公開例については、Figma、Notion、Web アプリをビルドするを確認してください。
@plugin-creator でプラグインを作成する¶
最もすばやくセットアップするには、組み込みの @plugin-creator スキルを使用します。
必要な .codex-plugin/plugin.json マニフェストをスキャフォールディングし、テスト用のローカルマーケットプレイスエントリも生成できます。すでにプラグインフォルダーがある場合でも、@plugin-creator を使用してローカルマーケットプレイスに組み込めます。
MCP サーバーがバックエンドとなる開発モードアプリを指すプラグインをローカルで作成してテストする¶
MCP サーバーをバックエンドとするアプリを含むプラグインをローカルでテストしたい場合も、plugin-creator スキルを使用できます。プラグインには引き続きローカルのプラグインフォルダーとマニフェストが必要ですが、アプリ自体は ChatGPT の開発者モードで起動します。
まず、ChatGPT で開発者モードを有効にします。
- ChatGPTを開きます。
- 設定を開きます。
- セキュリティとログインを選択します。
- 開発者モードをオンにします。
次に、開発者モードでアプリを作成します。
- 設定 → プラグインまたはプラグインページを開きます。
- プラスボタンを選択します。
- モーダルの指示に従って、MCP サーバー用の開発者モードアプリを作成します。
- ChatGPT が作成したら、ブラウザーの URL からアプリ ID をコピーします。ID は
plugin_asdk_appで始まります。
その plugin_asdk_app... ID を、ChatGPT の Work モードの @plugin-creator または Codex の $plugin-creator に渡します。たとえば、Work モードでは次のようにします。
{`@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 アプリ用のアプリ連携を追加します。個人用マーケットプレイスエントリの作成を依頼すると、テスト用にプラグインがプラグインディレクトリのローカルソースの下に表示されます。
plugin-creator スキルがプラグインを作成したら、次の手順を実行します。
.app.jsonを確認し、正しいplugin_asdk_app...ID を指していることを確認します。.codex-plugin/plugin.jsonを確認し、そのappsフィールドが./.app.jsonを指していることを確認します。- プラグインにアプリとともに反復可能なワークフローを含める場合は、
skills/の下にバンドルするスキルを追加します。 - スキルが個人用マーケットプレイスエントリを作成した場合は、ChatGPT を更新し、プラグインディレクトリのローカルソースからプラグインをインストールします。その後、新しいチャットでテストします。
マニフェストの構造とファイルレイアウトについては、プラグインの構造とパスの規則を参照してください。
独自のキュレーション済みプラグインリストをビルドする¶
マーケットプレイスは、プラグインの JSON カタログです。@plugin-creator は 1 つのプラグイン用のカタログを生成できます。同じマーケットプレイスにエントリを追加し続けることで、リポジトリ、チーム、または個人のワークフロー向けに独自のキュレーション済みリストを作成できます。
ChatGPT デスクトップアプリの Work モードまたは Codex では、各マーケットプレイスがプラグインディレクトリで選択可能なソースとして表示されます。リポジトリにスコープされたリストには $REPO_ROOT/.agents/plugins/marketplace.json、個人用リストには ~/.agents/plugins/marketplace.json を使用します。plugins[] の下にプラグインごとに 1 つのエントリを追加し、各 source.path が ./ プレフィックス付きのマーケットプレイスルートからの相対パスでプラグインフォルダーを指すようにします。interface.displayName には、マーケットプレイスピッカーでアプリに表示させるラベルを設定します。その後、ChatGPT デスクトップアプリを再起動します。次に、プラグインディレクトリを開き、マーケットプレイスを選択して、そのキュレーション済みリストにあるプラグインを参照またはインストールします。
プラグインごとに別々のマーケットプレイスを用意する必要はありません。テスト中は 1 つのプラグインだけを公開し、その後プラグインを追加して、より大きなキュレーション済みカタログに成長させることができます。
CLI からマーケットプレイスを追加する¶
codex plugin marketplace add を使用すると、config.toml を手動で編集する代わりに、マーケットプレイスソースを追加して追跡できます。これらのコマンドは、プラグインの作成とカタログのセットアップをサポートします。ローカルプラグインのインストールとテストには、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-name
codex plugin marketplace list は、Codex が検討している各マーケットプレイスと、そのマーケットプレイスが解決されるルートパスを出力します。これには、ローカルのデフォルトマーケットプレイスと、設定済みのマーケットプレイススナップショットが含まれます。
プラグインを手動で作成する¶
まず、1 つのスキルをパッケージ化する最小限のプラグインから始めます。
.codex-plugin/plugin.jsonにマニフェストを配置したプラグインフォルダーを作成します。
my-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の下にスキルを追加します。
my-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 設定、コネクター、またはマーケットプレイスメタデータを追加できます。
ローカルプラグインを手動でインストールする¶
プラグインまたはキュレーション済みリストにアクセスできるユーザーに応じて、リポジトリマーケットプレイスまたは個人用マーケットプレイスを使用します。
<Tabs id="codex-plugins-local-install" param="install-scope" defaultTab="workspace" tabs={[ { id: "workspace", label: "リポジトリ", }, { id: "global", label: "個人", }, ]}
`$REPO_ROOT/.agents/plugins/marketplace.json` にマーケットプレイスファイルを追加し、プラグインを `$REPO_ROOT/plugins/` の下に保存します。 **リポジトリマーケットプレイスの例** 手順 1: プラグインフォルダーを `$REPO_ROOT/plugins/my-plugin` にコピーします。 手順 2: `$REPO_ROOT/.agents/plugins/marketplace.json` を追加または更新し、`source.path` が `./` プレフィックス付きの相対パスでそのプラグインディレクトリを指すようにします。 手順 3: ChatGPT デスクトップアプリを再起動し、プラグインが表示されることを確認します。
マーケットプレイスファイルはプラグインの場所を指すため、これらのディレクトリは例であり、固定要件ではありません。Codex は source.path を .agents/plugins/ フォルダーではなく、マーケットプレイスルートを基準に解決します。ファイル形式については、マーケットプレイスメタデータを参照してください。
プラグインを変更した後は、マーケットプレイスエントリが指しているプラグインディレクトリを更新し、ChatGPT デスクトップアプリを再起動して、ローカルインストールが新しいファイルを取得できるようにします。
ローカルプラグインをワークスペースと共有する¶
プラグインを作成したら、ChatGPT デスクトップアプリから追加します。ChatGPT を選択して Work モードに切り替えるか、Codex を選択してから、プラグインを開きます。その後、ChatGPT ワークスペースの他のメンバーと共有できます。
- ChatGPT デスクトップアプリでプラグインを開きます。
- あなたが作成に移動し、プラグインの詳細ページを開きます。
- 共有を選択します。
- ワークスペースメンバーまたはワークスペースグループを追加するか、共有リンクをコピーします。
- アクセスできるユーザーを選択し、招待またはリンクを送信します。
共有相手は、プラグインディレクトリのあなたと共有の下でプラグインを見つけることができます。ローカルプラグインをワークスペースと共有しても、公開プラグインディレクトリには公開されません。共有プラグインはワークスペースと組織の境界内に留まり、そのワークスペースにサインインしていないアカウントはアクセスできません。チームまたは役割で同じプラグインアクセスを共有する場合は、グループを使用します。リポジトリまたは CLI で配布する場合はマーケットプレイスを使用し、選択したチームメイトに ChatGPT デスクトップアプリからプラグインをインストールしてもらう場合はワークスペース共有を使用します。
ワークスペース管理者は、requirements.toml に 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を使用してマーケットプレイスを識別します。 interface.displayNameには、ChatGPT デスクトップアプリに表示するマーケットプレイスのタイトルを指定します。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 カタログです。
アプリは次の場所からマーケットプレイスファイルを読み込めます。
- 公式プラグインディレクトリを提供するキュレーション済みマーケットプレイス
$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 サーバーを設定する .mcp.json ファイル、サポートされる各画面でプラグインを表示するためのアセットを含めることもできます。
.codex-plugin/ に含めるのは plugin.json だけです。skills/、hooks/、assets/、.mcp.json、.app.json はプラグインルートに配置します。
公開されたプラグインでは通常、クイックスタートのスキャフォールドに登場する最小限の例よりも豊富なマニフェストを使用します。マニフェストには 3 つの役割があります。
- プラグインを識別します。
- スキル、コネクター、MCP サーバー、フックなどのバンドルされたコンポーネントを指します。
- 説明、アイコン、法的リンクなど、インストール画面用のメタデータを提供します。
完全なマニフェスト例を次に示します。
{
"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 サーバー、コネクターとともにライフサイクルフックを含めることができます。
- フックを
./hooks/hooks.jsonに保存する場合、.codex-plugin/plugin.jsonにhooksエントリを指定する必要はありません。Codex がそのデフォルトファイルを自動的に確認します。
バンドルされた MCP サーバーとライフサイクルフック¶
mcpServers は、直接のサーバーマップまたはラップされた mcp_servers オブジェクトを含む .mcp.json ファイルを指すことができます。
直接のサーバーマップ:
ラップされたサーバーマップ:
インストール後、ユーザーはプラグインを編集せずに、バンドルされた MCP サーバーを有効または無効にし、Codex 設定からツールの承認ポリシーを調整できます。プラグインスコープの MCP サーバーポリシーには 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 の代わりに、そのマニフェストエントリを使用します。マニフェストフィールドには、単一のパス、パスの配列、インラインフックオブジェクト、またはインラインフックオブジェクトの配列を指定できます。
フックのパスには、skills、apps、mcpServers と同じマニフェストパスの規則が適用されます。./ で始まり、プラグインルートを基準に解決され、プラグインルート内に収める必要があります。
プラグインフックのコマンドは、Codex 固有の環境変数 PLUGIN_ROOT と PLUGIN_DATA を受け取ります。PLUGIN_ROOT はインストール済みプラグインのルートを指し、PLUGIN_DATA はプラグインの書き込み可能なデータディレクトリを指します。Codex は既存のプラグインフックとの互換性のために、CLAUDE_PLUGIN_ROOT と CLAUDE_PLUGIN_DATA も設定します。
プラグインフックは通常のフックと同じイベントスキーマを使用します。サポートされるイベント、入力、出力、信頼性の確認、現在の制限については、フックを参照してください。
公式の公開プラグインを公開する¶
プラグインを一般向けに公開するには、プラグイン申請ポータルから送信します。審査と公開の完全な手順については、プラグインを申請するを参照してください。