GitHub からワークスペースにプラグインをインポートし、リポジトリの変更に合わせて最新の状態に保つことができます。マーケットプレイスは、インポートするプラグインを一覧にした JSON ファイルです。
事前準備
インポートにはワークスペースの管理者権限が必要です。マーケットプレイスのリポジトリと、そこから参照されるすべてのリポジトリを読み取れる GitHub アカウントを使用してください。GitHub の公開リポジトリとプライベートリポジトリの両方に対応しています。GitHub の組織でアクセスの承認が必要な場合は、インポート前に承認を受けてください。
インポート前にリポジトリの内容を確認してください。次のデフォルト設定は、メンバーが利用できるプラグインに影響します。
- 新しいプラグインは利用可能に設定され、メンバーがインストールできます。認証が必要な場合は、メンバーがインストール時に認証を行います。
- インポートでは、有効なエントリをすべて処理します。新しいマーケットプレイスは毎日自動で同期され、リポジトリに新しいプラグインがあればワークスペースに追加されます。
このガイドでは、ワークスペースにプラグインをインポートする方法を説明します。ローカルクライアントについては、プラグインのマーケットプレイスとデフォルト設定で、クラウドで管理する設定やシステムの config.toml の設定を確認してください。特定のプロジェクトについては、リポジトリでのプラグインの有効化と無効化を参照してください。
マーケットプレイスの同期設定
- 管理 > プラグインを開き、追加 > マーケットプレイスをインポートを選択します。
- ソースに、
https://github.com/example/team-pluginsのようなリポジトリの URL を入力します。ブランチやフォルダを指す URL は使わず、リポジトリ自体の URL のみを指定してください。 - マーケットプレイスがサブディレクトリにある場合は、パスにそのディレクトリを入力します。たとえば、
team-toolsと入力するのは、ファイルがteam-tools/.agents/plugins/marketplace.jsonにある場合です。リポジトリのルートを使用する場合は、パスを空欄にします。マニフェストのファイル名は入力しないでください。 - 必要に応じて、ブランチ、タグ、またはコミットを入力します。空欄にすると、リポジトリのデフォルトブランチが使われます。ブランチを指定すると、その後の更新を受け取れます。特定のコミットを指定すると、選択したバージョンに固定されます。
- マーケットプレイスをインポートを選択し、画面の指示に従って GitHub へのアクセスを許可します。特に大規模なマーケットプレイスでは、初回のインポートに最大 1 時間かかることがあります。その後の毎日の同期は、通常数分で完了します。
- インポート結果を確認し、インポートしたプラグインをそれぞれ開いて、インストールポリシーと必要なアプリを設定します。
対応形式
選択したディレクトリには、次のいずれかのファイルが必要です。
| ファイル | 形式 |
|---|---|
.agents/plugins/marketplace.json |
plugins 配列を持つ Codex マーケットプレイス |
.claude-plugin/marketplace.json |
plugins 配列を持つ Claude 互換マーケットプレイス |
.claude-plugin/plugin.json |
マーケットプレイスのマニフェストがない場合に使用する単体の Claude プラグイン |
マーケットプレイスの各エントリでは、.codex-plugin/plugin.json を持つネイティブプラグイン、Claude 互換プラグイン、Agent Plugins 1.0 パッケージ、またはサポート対象のスキルパッケージを参照できます。
Codex マーケットプレイスでは、同じリポジトリにあるプラグインをローカルパスで指定します。
{
"name": "team-plugins",
"interface": {
"displayName": "Team plugins"
},
"plugins": [
{
"name": "team-tools",
"source": {
"source": "local",
"path": "./plugins/team-tools"
}
}
]
}パスは、選択したマーケットプレイスのルートを基準とする相対パスです。.agents/plugins/ は基準ディレクトリではありません。
Claude 互換マーケットプレイスでは、各ローカルプラグインのパスを文字列で指定できます。
{
"name": "team-plugins",
"plugins": [
{
"name": "team-tools",
"source": "./plugins/team-tools"
}
]
}Codex マーケットプレイスのエントリでは、GitHub リポジトリのルートにあるプラグインには source: "url" を、サブディレクトリにあるプラグインには source: "git-subdir" を指定することもできます。サブディレクトリを指定する例を示します。
{
"name": "team-tools",
"source": {
"source": "git-subdir",
"url": "https://github.com/example/team-tools.git",
"path": "./plugins/team-tools",
"ref": "main"
}
}Git をソースにする場合は、ref またはコミットの sha（40 文字すべて）を指定できます。アクセスを許可する GitHub アカウントには、参照先のすべてのリポジトリを読み取る権限が必要です。現在、ワークスペースへのインポートに対応しているのは GitHub リポジトリのみです。
ワークスペースのアクセス設定
各プラグインのインストールと認証の設定は、ワークスペースで行います。インポートや同期を行っても、リポジトリ側のインストール設定や認証設定は適用されません。これらの設定には、AVAILABLE、INSTALLED_BY_DEFAULT、NOT_AVAILABLE、ON_INSTALL、ON_USE があります。更新を同期した場合や、プラグインの管理を GitHub に移行した場合も、ワークスペースの既存の設定は維持されます。
インストールポリシーで、対象のロールごとに利用可能またはインストール済みを選択します。プラグインに必要なアプリも有効にし、メンバーが接続先のサービスにアクセスできることを確認してください。プラグインをインポートしても、メンバーにアプリへのアクセス権が付与されたり、メンバーのアカウントが接続されたりすることはありません。アクセス権と許可するアクションの設定については、プラグインの管理設定を参照してください。
既存プラグインの GitHub 管理への移行
pluginId を、既存のプラグインに対応するマーケットプレイスのエントリに追加します。
{
"name": "team-tools",
"pluginId": "plugin_0123456789abcdef0123456789abcdef",
"source": {
"source": "local",
"path": "./plugins/team-tools"
}
}管理 > プラグインから対象のプラグインを開き、URL の /plugins/ に続く ID をコピーします。マーケットプレイスのエントリでは、pluginId を name や source と同じ階層に置きます。既存のプラグインは同じワークスペース内にある必要があり、エントリの name は既存のプラグイン名と一致している必要があります。
この方法で、まだ GitHub で管理していないワークスペースのプラグインを GitHub 管理に移行できます。プラグインの ID、共有設定、ワークスペースの設定は維持されます。移行後は GitHub から更新を取得するため、アーカイブをアップロードしてプラグインを置き換えることはできません。すでに別の GitHub ソースで管理されているプラグインには、この方法は使えません。
デスクトップ専用プラグイン
デスクトップ専用と表示されるプラグインは、Web 版の ChatGPT では実行できません。インポートしたプラグインが MCP サーバーを宣言している場合、このラベルが付くことがあります。リモートの HTTPS URL を持つサーバーも対象です。.app.json への参照を追加しただけでは、ラベルは外れません。
.app.json による既存アプリの参照
.app.json をプラグインのルートに追加します。ファイル名の先頭にはドットが必要です。ドットのない app.json はサポートされていません。
{
"apps": {
"team-tools": {
"id": "asdk_app_example",
"required": true
}
}
}asdk_app_example を既存のアプリの ID に置き換えます。使用できるアプリ ID は asdk_app_、connector_、templated_apps_ のいずれかで始まります。ここではアプリ ID を指定してください。plugin_... 形式の ID は使用できません。たとえば、プラグインの URL に plugin_asdk_app_example が含まれている場合、対応するアプリの ID は asdk_app_example です。
キー team-tools は、このファイル内での参照名です。プラグインがそのアプリに依存する場合は、required を true に設定します。ほかの既存アプリを参照するには、エントリを追加します。
ネイティブプラグインの場合は、apps の値を ./.app.json に設定します。この設定は .codex-plugin/plugin.json に記述します。この例のマニフェスト全体を以下に示します。
{
"name": "team-tools",
"version": "1.0.0",
"description": "Use the team's approved tools.",
"author": {
"name": "Example team"
},
"apps": "./.app.json",
"interface": {
"displayName": "Team tools",
"shortDescription": "Use approved team tools",
"longDescription": "Connect to the team's existing app.",
"developerName": "Example team",
"category": "Productivity",
"capabilities": ["Read"]
}
}ファイルは次の構成で配置してください。
team-plugins/
├── .agents/plugins/marketplace.json
└── plugins/team-tools/
├── .codex-plugin/plugin.json
└── .app.jsonこのファイルは既存のアプリを参照するものです。アプリの作成やアクセス権の付与は行いません。アプリを必要とするロールで利用できるように設定し、認証が必要な場合はメンバーに認証を依頼してください。アプリの権限、許可されるアクション、接続先サービスのアクセス権は引き続き適用されます。
プラグインの更新
新しいマーケットプレイスでは、毎日自動で更新の有無を確認します。自動同期を待たずに更新をリクエストするには、管理 > プラグイン > マーケットプレイスを開き、対象のマーケットプレイスを選んで今すぐ同期を選択します。
同期すると、マーケットプレイスから新しいプラグインを追加したり、既存のプラグインを更新したりできます。自動同期では新しいプラグインもインポートされるため、リポジトリの変更内容はマージする前に確認してください。
同期のたびに、ステータスと保存されたレポートを確認してください。同期が完了していても、個々のプラグインでエラーが発生している場合があります。更新内容が無効な場合、既存のプラグインでは最後に正常に動作したバージョンが維持されます。GitHub で問題を修正してから、今すぐ同期を選択して再試行してください。
マーケットプレイスからプラグインのエントリを削除しても、ワークスペース内のプラグインは残り、ソースから削除済みと表示されます。一方、ChatGPT でマーケットプレイスを削除すると、そこからインポートしたプラグインもすべて削除されます。
GitHub への再接続と所有者の変更
マーケットプレイスの同期には、インポートを行った管理者の GitHub 接続が使われます。
再接続するには、まず、その管理者の GitHub アカウントでマーケットプレイスのリポジトリとすべての参照先リポジトリを引き続き読み取れることを確認します。その後、同じ管理者が ChatGPT で GitHub プラグインを開き、自分のアカウントを再接続します。
所有者を変更するには、新しいワークスペース管理者が管理 > プラグイン > 追加 > マーケットプレイスをインポートから、マーケットプレイスを再度インポートします。ソース、パス、ブランチ、タグ、またはコミットには、前回と同じ値を指定してください。以降の同期には、新しい管理者の GitHub 接続が使われます。
再接続や所有者の変更は、マーケットプレイスを残したまま行ってください。マーケットプレイスを削除すると、そこからインポートしたプラグインも削除されます。