🔌 技術調査 - codex-plugin-cc

概要

Claude Code を日常的に使っている開発者にとって、「別の AI にもコードをチェックさせたい」と感じる場面は少なくありません。codex-plugin-cc は、そのニーズに応える OpenAI 公式の Claude Code プラグインです。

2026年3月31日に Apache 2.0 ライセンスでオープンソース公開されました。Claude Code のセッション内から、OpenAI Codex のコードレビュー機能とタスク委譲（rescue）機能をスラッシュコマンドで利用できます。

既存の Codex CLI のインストール・認証・設定をそのまま引き継ぐため、追加の環境構築は最小限で済みます。ツールを切り替えることなく、Claude Code 上で Codex の機能を活用できます。

関連技術との関係

codex-plugin-cc はローカルの Codex CLI を通じてリクエストを委譲します。独立したランタイムは持ちません。

特徴

• 3 つのコア機能: 通常レビュー・adversarial（敵対的）レビュー・タスク委譲をスラッシュコマンドで提供
• フォアグラウンド・バックグラウンド実行: --wait / --background フラグによる実行モード選択（実装上は常にフォアグラウンド実行となる可能性あり。詳細は利用方法セクションを参照）
• ジョブ管理: バックグラウンドジョブの状態確認・結果取得・キャンセルをコマンドで操作可能
• レビューゲート: Claude が変更を確定する前に Codex レビューを自動実行するオプション機能
• 既存設定の継承: ローカルの Codex CLI の認証・設定・MCP セットアップをそのまま利用
• App Server Broker パターン: 単一の Codex プロセスへの接続を多重化し、複数ジョブの並行実行でも起動オーバーヘッドが発生しない
• 戦略的な競合連携: Claude Code が市場シェアを持つ環境へ OpenAI が公式にプラグインを提供

類似ツールとの比較

Claude Code 上で Codex を使う理由

ユースケース別推奨

構造

codex-plugin-cc の内部構造を C4 model に基づき、3 段階の抽象度で描きます。システムコンテキスト図で外部アクターとの関係を俯瞰し、コンテナ図でプラグイン内の主要コンポーネントを分類し、コンポーネント図で個々のファイル粒度まで詳細化しています。

システムコンテキスト図

コンテナ図

コンポーネント図

スラッシュコマンド群

サブエージェント・スキル群

ライフサイクルフック群

Companion スクリプト群

ジョブ状態ストア

データ

概念モデル

情報モデル

構築方法

前提条件

バージョン確認

# Node.js バージョン確認
node --version
# 出力例: v22.x.x (18.18 以上であること)

# Codex CLI バージョン確認 (インストール後)
codex --version

プラグイン経由インストール（推奨）

Claude Code セッション内で以下を順番に実行します。

# Step 1: OpenAI マーケットプレイスを追加
/plugin marketplace add openai/codex-plugin-cc

# Step 2: Codex プラグインをインストール
/plugin install codex@openai-codex

# Step 3: プラグインをリロード
/reload-plugins

# Step 4: セットアップを確認
/codex:setup

/codex:setup は Node.js・npm・Codex CLI の存在と認証状態を検証します。npm が利用可能な場合、Codex CLI が未インストールであれば自動インストールを提案します。

Codex CLI 手動インストール（任意）

npm install -g @openai/codex

認証

# Claude Code セッション内で実行
!codex login

同一マシン上で Codex に認証済みの場合、そのアカウントがそのまま使用されます。/codex:setup が未認証を報告した場合のみ !codex login を実行してください。

インストール確認

セットアップ成功後に以下を確認します。

• /codex:review などのスラッシュコマンドが利用可能になっていること
• /agents に codex:codex-rescue サブエージェントが表示されていること

利用方法

スラッシュコマンド一覧

/codex:setup

環境の検証とレビューゲートの設定を行います。

# 基本実行（検証のみ）
/codex:setup

# レビューゲートを有効化
/codex:setup --enable-review-gate

# レビューゲートを無効化
/codex:setup --disable-review-gate

/codex:review

差分に対して標準的な Codex コードレビューを実行します。

制約: /codex:review はファイルパスやフォーカステキストを引数に取れません。常に Git ワーキングツリー全体の差分（または --base 指定時のブランチ間差分）をレビュー対象とします。特定ファイルのみをレビューしたい場合は /codex:rescue で委譲してください。

# 基本実行
/codex:review

# ベースブランチを指定して比較
/codex:review --base main

# フォアグラウンドで完了まで待機
/codex:review --wait

# バックグラウンドで実行
/codex:review --background

# ベースブランチ指定 + バックグラウンド実行
/codex:review --base main --background

注意（README と実装の乖離）: README では --wait / --background による実行モード選択が記載されていますが、現時点の実装では常に runForegroundCommand() を呼び出します。実際のバックグラウンド実行は Claude Code 側の Bash(..., run_in_background: true) で実現されます。

Claude Code のスラッシュコマンド定義側で差分サイズを推定し、実行モードを推奨する仕組みが組み込まれています。

通常レビューのプロンプト構造

通常レビューでは、以下の観点でコードを評価します。

• バグ・論理エラー・境界条件の見落とし
• パフォーマンスのボトルネック
• セキュリティ上の懸念
• コードの可読性・保守性
• テストカバレッジの不足

verdict は以下の基準で判定されます。

/codex:adversarial-review

設計上の決定と前提に意図的に異議を唱え、脆弱性や見落としを洗い出す批判的レビューを実行します。通常レビューでは見逃しやすいエッジケースやセキュリティリスクの検出に適しています。

# 基本実行
/codex:adversarial-review

# ベースブランチ指定 + フォーカステキスト
/codex:adversarial-review --base main キャッシュとリトライの設計が適切か検証してください

# バックグラウンドで競合状態を調査
/codex:adversarial-review --background 競合状態とアプローチの妥当性を調査してください

# 待機モードで権限とテナント境界を確認
/codex:adversarial-review --wait 認証・権限・テナント分離の境界を確認してください

# ロールバック安全性の検証
/codex:adversarial-review ロールバック安全性を検証し不可逆な状態変更を特定してください

adversarial レビューのプロンプト構造

adversarial レビューでは、以下の攻撃面を優先的に検査します。

• 認証・権限・テナント分離・信頼境界
• データ損失・破損・重複・不可逆な状態変更
• ロールバック安全性・リトライ・部分的失敗・冪等性のギャップ
• 競合状態・順序の前提・古い状態・再入可能性
• 空状態・null・タイムアウト・劣化した依存の振る舞い

各 finding は以下の 4 点を回答します。

• 何が起こりうるか
• なぜ脆弱か
• 影響の大きさ
• リスク低減の具体策

/codex:rescue

複雑なデバッグや実装タスクを Codex サブエージェントに委譲します。

実行経路: /codex:rescue は他のスラッシュコマンドと異なり、codex-companion.mjs のディスパッチャーを経由しません。Claude Code が agents/codex-rescue.md で定義されたサブエージェントを直接起動し、そのエージェントがスキル経由で Codex CLI を呼び出します。

# 基本実行
/codex:rescue

# バックグラウンドで実行
/codex:rescue --background

# モデルを指定して実行
/codex:rescue --model o3

# 推論レベルを指定
/codex:rescue --effort high

# 前回のタスクを継続
/codex:rescue --resume

--effort レベルの目安

バックグラウンド実行の仕組み

codex-companion.mjs が detached: true オプション付きで Node.js の child_process を spawn します。lib/job-control.mjs がジョブのライフサイクル管理を、lib/tracked-jobs.mjs がファイルシステム経由の状態ファイルのアトミック更新を担います。

親プロセス（Claude Code セッション）が終了してもジョブは継続実行されます。次回セッション開始時に /codex:status で結果を取得できます。

/codex:status, /codex:result, /codex:cancel

# ジョブ一覧の表示
/codex:status

# 完了ジョブの結果取得
/codex:result <job-id>

# 実行中ジョブのキャンセル
/codex:cancel <job-id>

実行モードの選択フロー

運用

起動・停止

プラグインは Claude Code のセッションと同じライフサイクルで動作します。セッション開始時にブローカープロセスが自動起動し、終了時に停止します。

$STATE_DIR は $CLAUDE_PLUGIN_DATA/state/<workspace-slug>-<hash>/ です（CLAUDE_PLUGIN_DATA 未設定時は OS の tmpdir 配下）。

状態確認

# 実行中・直近のジョブ一覧を表示
/codex:status

# 完了したジョブの最終出力を表示
/codex:result <job-id>

ログ確認

更新

# Codex CLI の更新
npm update -g @openai/codex

# プラグイン自体の更新
/plugin update codex

ジョブ管理

バックグラウンドジョブのライフサイクルは queued → running → completed / failed / cancelled の順に遷移します。

# 実行中のジョブを停止
/codex:cancel <job-id>

注意: README では --background / --wait フラグが記載されていますが、実際のバックグラウンド実行は Claude Code 側の仕組みで実現されます。

ジョブ履歴は最新 50 件に自動整理されます。手動でリセットする場合は $STATE_DIR/ 配下のジョブファイルを削除します。

レビューゲートの操作

# レビューゲートを有効化
/codex:setup --enable-review-gate

# レビューゲートを無効化
/codex:setup --disable-review-gate

レビューゲートを有効にすると、Claude の停止前に stop-review-gate-hook.mjs が実行されます。Codex のレビュー結果が BLOCK: で始まる場合、セッションが継続されます。タイムアウト（15 分）時はデフォルトでブロックします。

設定ファイル

# ~/.codex/config.toml（ユーザー設定: 全プロジェクト共通）
model = "gpt-5.4-mini"
model_reasoning_effort = "xhigh"

# .codex/config.toml（プロジェクト設定: 信頼済みプロジェクトのみ有効）
openai_base_url = "https://your-endpoint.example.com/v1"

ベストプラクティス

フォアグラウンドとバックグラウンドの使い分け

コマンドの使い分け: review vs rescue

/codex:review と /codex:adversarial-review は Git 差分全体をレビューする用途に特化しています。以下のケースでは /codex:rescue が適しています。

CI/CD 連携

• Codex CLI は ~/.codex/config.toml の認証情報を引き継ぎ
• CI 環境では環境変数またはプロジェクト単位の .codex/config.toml を使用
• プロジェクト設定は信頼済みプロジェクトのみで有効

レビューゲートの運用

• レビューゲートは Claude と Codex のループを発生させる可能性あり
• 有効化はアクティブに監視できるセッションのみに限定
• 使用量の急激な消費に注意

スレッドの継続性

# 前回のスレッドを継続
/codex:rescue --resume

# 新規スレッドで開始
/codex:rescue --fresh

再開可能なスレッドがある場合、継続か新規開始かを確認するプロンプトが表示されます。

トラブルシューティング

頻出エラーと対処

診断手順

# 1. 環境の確認
/codex:setup

# 2. 認証の確認と再認証
!codex login

# 3. ジョブの状態確認
/codex:status

# 4. 特定ジョブのログ確認
cat $STATE_DIR/<job-id>.log

# 5. プラグインの再読み込み
/reload-plugins

Git 差分が大きい場合のエラー

ワーキングツリーに未追跡ファイルや大量の変更がある状態で /codex:review や /codex:adversarial-review を実行すると、Git 差分の取得時に ENOBUFS（バッファオーバーフロー）が発生する場合があります。

レビューゲートループの緊急停止

レビューゲートが Claude と Codex の無限ループを引き起こした場合、以下の手順で停止します。

# ブローカープロセスを強制停止
kill $(cat $STATE_DIR/broker.json | python3 -c "import sys,json; print(json.load(sys.stdin)['pid'])")

# ブローカー状態ファイルを削除して再起動を防止
rm $STATE_DIR/broker.json

# レビューゲートを無効化（次回セッション用）
/codex:setup --disable-review-gate

バージョン整合性の確認

# Node.js のバージョン確認（18.18.0 以上が必要）
node --version

# Codex CLI のバージョン確認
codex --version

# codex-plugin-cc のバージョン確認
/plugin list

まとめ

codex-plugin-cc は、Claude Code のセッション内から OpenAI Codex のコードレビューとタスク委譲を利用するための公式プラグインです。異なる AI モデルによる二重チェックを、ツール切り替えなしで実現できる点が最大の特徴です。

本記事では、App Server Broker による低オーバーヘッドな多重化アーキテクチャ、レビューゲートによる自動品質チェック、そしてトラブルシューティングまでを網羅的に解説しました。まずは /codex:setup でセットアップし、日常のコードレビューに /codex:review を組み込むところから始めてみてください。

この記事が少しでも参考になった、あるいは改善点などがあれば、ぜひリアクションやコメント、SNSでのシェアをいただけると励みになります！

参考リンク

• 公式ドキュメント

  • Codex Plugins - OpenAI Developers
  • Introducing Codex Plugin for Claude Code - OpenAI Developer Community

• GitHub

  • openai/codex-plugin-cc
  • plugins/codex directory
  • marketplace.json
  • hooks.json
  • codex-companion.mjs
  • review-output.schema.json
  • state.mjs
  • tracked-jobs.mjs
  • job-control.mjs
  • stop-review-gate-hook.mjs
  • codex-plugin-cc README.md

• 記事

  • openai/codex-plugin-cc - DeepWiki
  • OpenAI Releases Official Claude Code Plugin — What codex-plugin-cc Means - SmartScope