ネイティブ Codex プラグイン

ネイティブ Codex Plugin 対応により、Codex モードの OpenClaw エージェントは、OpenClaw のターンを処理する同じ Codex スレッド内で、Codex app-server 独自のアプリおよび Plugin 機能を使用できます。Plugin 呼び出しはネイティブ Codex トランスクリプト内に保持され、Codex app-server がアプリを基盤とする MCP 実行を管理します。OpenClaw は Codex Plugin を合成された codex_plugin_* OpenClaw 動的ツールに変換しません。

基本の Codex ハーネスが動作した後に、このページを使用してください。

要件

• エージェントランタイムはネイティブ Codex ハーネスでなければなりません。
• plugins.entries.codex.enabled が true である必要があります。
• plugins.entries.codex.config.codexPlugins.enabled が true である必要があります。
• 対象の Codex app-server から、想定されるマーケットプレイス、Plugin、およびアプリのインベントリを参照できる必要があります。
• 移行でサポートされるのは、移行元の Codex ホームでソースからインストール済みであることが確認された openai-curated Plugin のみです。
• 手動で構成する workspace-directory Plugin には、plugin/list が marketplaceKinds を受け付け、パスを含まないワークスペース概要に remotePluginId を含める Codex app-server が必要です。Plugin はすでにインストールされ、有効になっている必要があり、その Plugin が所有するアプリに app/list からアクセスできる必要があります。

codexPlugins は OpenClaw プロバイダーでの実行、ACP 会話バインディング、その他のハーネスには影響しません。これらの経路では、ネイティブの apps 構成を持つ Codex app-server スレッドが作成されないためです。

OpenAI 側の Codex アカウント、アプリの可用性、ワークスペースのアプリおよび Plugin 制御は、サインイン中の Codex アカウントに基づきます。OpenAI アカウントと管理モデルについては、ChatGPT プランで Codex を使用するを参照してください。

クイックスタート

移行元の Codex ホームからの移行をプレビューします。

openclaw migrate codex --dry-run

--verify-plugin-apps を追加すると、移行時に移行元の app/list を呼び出し、ネイティブ有効化を計画する前に、所有するすべてのアプリが存在し、有効で、アクセス可能であることを要求します。

openclaw migrate codex --dry-run --verify-plugin-apps

計画に問題がなければ、移行を適用します。

openclaw migrate apply codex --yes

移行では、対象となる Plugin の明示的な codexPlugins エントリを書き込み、選択した Plugin に対して Codex app-server の plugin/install を呼び出します。移行後の構成は次のようになります。

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          codexPlugins: {            enabled: true,            allow_destructive_actions: true,            plugins: {              "google-calendar": {                enabled: true,                marketplaceName: "openai-curated",                pluginName: "google-calendar",              },            },          },        },      },    },  },}

移行の対象は引き続き openai-curated に限定されます。既存の workspace-directory Plugin を使用するには、plugin/list が返すマーケットプレイス修飾済みの正確な summary.id を使用して、手動で追加します。たとえば、Codex が example-plugin@workspace-directory を返す場合は、表示名ではなく、その完全な値を構成します。

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          codexPlugins: {            enabled: true,            plugins: {              "example-plugin": {                enabled: true,                marketplaceName: "workspace-directory",                pluginName: "example-plugin@workspace-directory",              },            },          },        },      },    },  },}

OpenClaw は workspace-directory Plugin に対して plugin/install を呼び出したり、認証を開始したりしません。OpenClaw ポリシーを追加または有効化する前に、Codex でインストール、有効化、認証を行ってください。レスポンスに正確なマーケットプレイス、Plugin ID、詳細 ID、またはアプリ準備状況の証拠が含まれていない場合、OpenClaw はアプリを非表示のままにします。Codex が明示的なワークスペース plugin/list リクエストを拒否した場合、OpenClaw は有効な各ワークスペース Plugin について marketplace_missing を報告し、独立して検出された curated Plugin は引き続き利用可能にします。

codexPlugins を変更すると、新しい Codex 会話には更新されたアプリセットが自動的に反映されます。現在の会話を更新するには、/new または /reset を実行します。Plugin の有効化または無効化を変更しても、Gateway の再起動は必要ありません。

チャットから Plugin を管理する

/codex plugins を使用すると、Codex ハーネスを操作している同じチャットから、構成済みのネイティブ Codex Plugin を確認または変更できます。

/codex plugins/codex plugins list/codex plugins disable google-calendar/codex plugins enable google-calendar

/codex plugins は /codex plugins list のエイリアスです。この一覧には、plugins.entries.codex.config.codexPlugins.plugins に構成された各 Plugin のキー、オンまたはオフの状態、Codex Plugin 名、およびマーケットプレイスが表示されます。

enable/disable は ~/.openclaw/openclaw.json にのみ書き込みます。~/.codex/config.toml を編集したり、新しい Codex Plugin をインストールしたりすることはありません。実行できるのは、所有者または operator.admin スコープを持つ Gateway クライアントのみです。

構成済みの Plugin を有効にすると、グローバルな codexPlugins.enabled スイッチも有効になります。移行で auth_required が返されたため curated Plugin が無効として書き込まれた場合は、OpenClaw で有効にする前に Codex でアプリを再認可してください。workspace-directory エントリの場合、ここで有効にしても OpenClaw ポリシーのみが変更されます。Plugin とアプリは、Codex ですでに有効になっている必要があります。

ネイティブ Plugin のセットアップの仕組み

この統合では、3 つの状態を追跡します。

openai-curated Plugin では、移行が永続的なインストールおよび適格性判定の手順になります。

• 計画中に、OpenClaw は移行元 Codex の plugin/read の詳細を読み取り、移行元 Codex app-server のアカウントが ChatGPT サブスクリプションアカウントであることを確認します。ChatGPT 以外のアカウント、またはアカウントのレスポンスがない場合、アプリを基盤とする Plugin は codex_subscription_required としてスキップされます。
• デフォルトでは、移行時に移行元の app/list 呼び出しはスキップされます。アカウント条件を満たしたアプリを基盤とする移行元 Plugin は、移行元アプリへのアクセス可能性を検証せずに計画され、アカウント検索の通信エラーが発生した場合は codex_account_unavailable としてスキップされます。
• --verify-plugin-apps を使用すると、移行時に移行元の app/list の新しいスナップショットを取得し、ネイティブ有効化を計画する前に、所有するすべてのアプリが存在し、有効で、アクセス可能であることを要求します。この場合、アカウント検索の通信エラーが発生しても即座にはスキップされず、移行元アプリのインベントリ条件による判定に移ります。

workspace-directory Plugin のセットアップは OpenClaw の外部で行われます。OpenClaw は、有効なワークスペースエントリが少なくとも 1 つ構成されている場合にのみ、そのマーケットプレイスを照会し、正確な summary.id で各 Plugin を解決し、既存の plugin/read 所有権チェックと app/list 準備状況チェックを再利用します。インストールされていない、無効、アクセス不能、または未認証の Plugin はアプリを公開しません。OpenClaw はインストールや認証を試みません。

ランタイムのアプリインベントリは、移行された curated Plugin と手動で構成されたワークスペース Plugin の両方に対する、対象セッションのアクセス可能性チェックです。Codex ハーネスのセッションセットアップでは、有効かつアクセス可能な Plugin アプリから制限的なスレッドアプリ構成を計算します。この構成はターンごとに再計算されないため、/codex plugins enable/disable が影響するのは新しい Codex 会話のみです。現在の会話に変更を反映するには、/new または /reset を使用します。

V1 のサポート範囲

• 移行対象となるのは、移行元 Codex app-server のインベントリにすでにインストールされている openai-curated Plugin のみです。
• ランタイムでは、plugin/list が marketplaceKinds を実装し、パスを含まないワークスペース概要に対して remotePluginId を返す app-server ビルド上で、明示的な workspace-directory エントリもサポートされます。これらのエントリはマーケットプレイス修飾済みの正確な summary.id を使用し、すでにインストールされ、有効で、アプリにアクセス可能である必要があります。ワークスペース一覧リクエストが拒否された場合、既存の Plugin ごとの marketplace_missing 診断が生成されます。マーケットプレイス、Plugin、詳細、またはアプリの証拠が不足している場合、ワークスペースアプリは公開されません。デフォルトの一覧リクエストから得られる curated インベントリは引き続き使用できます。
• アプリを基盤とする移行元 Plugin は、移行時のサブスクリプション条件を満たす必要があります。--verify-plugin-apps は、移行元アプリのインベントリ条件を追加します。サブスクリプション条件を満たさないアカウント、および検証モードでアクセス不能、無効、不足している移行元アプリ、またはアプリインベントリ更新エラーがある場合、有効な構成エントリではなく、スキップされた手動対応項目として報告されます。読み取れない Plugin の詳細は、アプリインベントリ条件の判定前にスキップされます。
• 移行では、明示的な Plugin ID（marketplaceName および pluginName）を書き込みます。ローカルの marketplacePath キャッシュパスは書き込みません。
• codexPlugins.enabled が唯一のグローバル有効化スイッチです。任意のインストール権限を付与する plugins["*"] ワイルドカードや構成キーはありません。
• curated 以外のマーケットプレイス、キャッシュ済みの Plugin バンドル、フック、Codex 構成ファイルは、自動的には有効化されず、手動確認用として移行レポートに保持されます。ランタイムは手動で構成された workspace-directory エントリを受け付けますが、その他のマーケットプレイスは引き続きサポートされません。

アプリインベントリと所有権

OpenClaw は app-server の app/list を通じて Codex のアプリインベントリを読み取り、メモリ内に 1 時間キャッシュし、古いエントリまたは不足しているエントリを非同期で更新します。キャッシュはプロセスローカルです。CLI または Gateway を再起動すると破棄され、OpenClaw は次回の app/list 読み取り時に再構築します。

移行とランタイムでは、別々のキャッシュキーを使用します。

• 移行元の移行検証では、移行元の Codex ホームと起動オプションを使用します。これは --verify-plugin-apps を指定した場合にのみ実行され、その計画実行に対して移行元の app/list を強制的に新規走査します。
• 対象ランタイムのセットアップでは、スレッドアプリ構成を構築するときに、対象エージェントの Codex app-server ID を使用します。curated Plugin の有効化では、その対象キャッシュキーを無効化し、plugin/install 後に強制更新します。workspace-directory のセットアップでは、この有効化経路は実行されません。

Plugin アプリが公開されるのは、安定した所有権により、OpenClaw がそのアプリを構成済みの Plugin に対応付けられる場合のみです。対応付けには、Plugin の詳細に含まれる正確なアプリ ID、既知の MCP サーバー名、または一意で安定したメタデータが使用されます。表示名だけに基づく所有権や曖昧な所有権は、次回のインベントリ更新で所有権が証明されるまで除外されます。

接続済みアカウントのアプリ

所有者が運用するエージェントでは、対応する Plugin パッケージを必要とせず、Codex アカウントにすでに接続されているすべてのアプリを使用するよう選択できます。

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          codexPlugins: {            enabled: true,            allow_all_plugins: true,            allow_destructive_actions: "auto",          },        },      },    },  },}

allow_all_plugins: true は、新しいネイティブ Codex スレッドの確立時に完全な app/list スナップショットを取得し、そのアカウントでアクセス可能とマークされたアプリのみを許可します。アプリをグローバルにインストール、認証、有効化することはありません。既存のスレッドでは永続化されたアプリセットが維持されます。新たに接続または取り消されたアプリを反映するには、/new、/reset を使用するか、Gateway を再起動します。

アカウントのアプリは、グローバルな codexPlugins.allow_destructive_actions の値を継承します。この値には true、false、"auto"、または "ask" を指定できます。アプリ ID が重複する場合、Plugin ごとの明示的なポリシーがグローバルポリシーを上書きします。インベントリの取得に失敗した場合、無制限のデフォルトへフォールバックせず、安全側に閉じます。

スレッドアプリ構成

OpenClaw は Codex スレッドに制限的な config.apps パッチを注入します。 _default は無効化され、有効に設定されたプラグインが所有するアプリ、または allow_all_plugins によって許可されたアクセス可能なアカウントアプリのみが有効になります。

各アプリの destructive_enabled は、有効なグローバルまたは プラグイン単位の allow_destructive_actions ポリシーから決まります。true、"auto"、"ask" は いずれも destructive_enabled: true を設定し、false は false を設定します。Codex は引き続き、 ネイティブのアプリツール注釈にある破壊的ツールのメタデータを適用します。 _default は open_world_enabled: false で無効化され、有効なプラグインアプリには open_world_enabled: true が設定されます。OpenClaw はプラグイン単位のオープンワールドポリシーを 個別に設定する機能を公開せず、プラグイン単位の破壊的ツール名の拒否リストも管理しません。

許可されたアプリでは、ツール承認モードのデフォルトは自動であるため、非破壊的な 読み取りツールは同一スレッド内の承認プロンプトなしで実行されます。破壊的ツールは引き続き、 各アプリの destructive_enabled ポリシーによって制御されます。

破壊的アクションのポリシー

設定済みの Codex プラグインでは、破壊的なプラグインの確認要求はデフォルトで許可されますが、 安全でないスキーマや所有者が曖昧な場合は安全側に倒して拒否されます。

• グローバルの allow_destructive_actions のデフォルトは true です。
• プラグイン単位の allow_destructive_actions は、そのプラグインについて グローバルポリシーを上書きします。
• false: OpenClaw は決定論的な拒否応答を返します。
• true: OpenClaw は、真偽値の承認フィールドなど、承認応答にマッピングできる 安全なスキーマのみを自動承認します。
• "auto": OpenClaw は破壊的なプラグインアクションを Codex に公開し、その後、 所有者が確認された MCP の承認確認要求を OpenClaw のプラグイン承認に変換してから、 Codex の承認応答を返します。
• "ask": OpenClaw は "auto" と同じ Codex の書き込み／破壊的操作のゲートを使用し、 スレッド開始前に、そのアプリに対する Codex のツール単位の永続的な承認上書きを消去します。 また、永続的な承認によって後続の書き込みアクションのプロンプトが抑制されないよう、 1 回限りの承認または拒否のみを提示します。"ask" を使用する許可済みアプリごとに、 OpenClaw はそのアプリに対して Codex の人間による承認レビュアーを選択し、 Codex の承認確認要求が OpenClaw に送信されるようにします。その他のアプリと アプリ以外のスレッド承認では、設定済みのレビュアーとポリシーが維持されます。
• プラグイン識別情報の欠落、所有者の曖昧さ、ターン ID の欠落または不一致、 あるいは安全でない確認要求スキーマがある場合、プロンプトを表示せず拒否します。

トラブルシューティング

ワークスペースプラグインがインストール済みだが表示されない場合: ワークスペースの plugin/list の結果で、設定された正確な ID がインストール済みかつ有効として報告されていることを確認し、 続いて app/list で、所有するすべてのアプリが同じ Codex アカウントからアクセス可能として報告されていることを 確認します。アカウントのアプリ一覧で現在そのアプリが無効と報告されていても、OpenClaw はアクセス可能なアプリを スレッド用に有効化できます。Gateway がアプリ一覧をキャッシュした後にその状態を変更した場合は、 1 時間ごとのキャッシュ更新を待つか Gateway を再起動してから、/new または /reset を使用します。 OpenClaw はワークスペースプラグインの修復や認証を行いません。明示的なワークスペース一覧要求が拒否された場合、 有効な各ワークスペースエントリは marketplace_missing を報告します。無関係な管理対象エントリは、 デフォルトの一覧応答を使用して引き続き処理されます。

plugin_detail_unavailable の場合、パスを持たないワークスペース概要には remotePluginId を含める必要があります。そのセレクター、または後続の plugin/read の結果が 利用できない場合、OpenClaw は所有するアプリを非表示のままにします。 plugin_activation_failed の場合、管理対象プラグインでは、マーケットプレイス、認証、または インストール後の更新の失敗が報告されることがあります。ワークスペースプラグインがまだ有効でない場合、 このコードが報告されます。OpenClaw の外部でインストール、有効化、認証を行ってください。

設定を変更したがエージェントからプラグインが見えない場合: /codex plugins list を実行して設定状態を確認してから、/new または /reset を実行します。既存の Codex スレッドバインディングは、OpenClaw が新しいハーネスセッションを確立するか、 古いバインディングを置き換えるまで、開始時のアプリ設定を保持します。

破壊的アクションが拒否される場合: グローバルおよびプラグイン単位の allow_destructive_actions の値を確認します。true、"auto"、"ask" の場合でも、 安全でない確認要求スキーマや曖昧なプラグイン識別情報は、引き続き安全側に倒して拒否されます。

関連項目

• Codex ハーネス
• Codex ハーネスリファレンス
• Codex ハーネスランタイム
• 設定リファレンス
• 移行 CLI