Codex Control Plane MCP

Codex Control Plane MCP

英語 | Русский

長時間タスクに対応する、信頼性の高い Codex Desktop 自動化です。

codex-control-plane-mcp は Codex Desktop と codex-app-server を、 MCP クライアントが安全に操作できる永続的なワーカーに変えます。タスクを送信すると、 すぐに operationId または workflowId を受け取り、作業が終わるまでポーリングし、 必要に応じて Plan Mode を承認してから、最終レポートを読み取れます。

このサーバーは、シンプルなラッパーでは呼び出し側に任されがちな煩雑な処理を担います。たとえば、 アプリサーバーの起動、スレッドとターンの作成、リトライの安全性、プロンプトの重複防止、 Plan Mode、承認、ローカル履歴、診断、修復などです。

OpenClaw と Hermes は主要なクライアントですが、MCP 呼び出しを何時間も開いたままにせず、 Codex Desktop に長時間実行される作業をさせたいローカルオーケストレーターなら、 どれでもこのサーバーを利用できます。

概要

MCP client / orchestrator
  -> submit a task or start a Plan Mode workflow
  <- receive operationId or workflowId immediately
  -> poll status
  -> answer approvals or approve the plan
  <- read final report, diagnostics, threadId, and turnId

これにより、シンプルな契約が実現します。

• 数時間に及ぶ MCP 呼び出しは不要です。
• クライアントのリトライ後に Codex のターンが重複することはありません。
• タスクを無確認で送信して放置することはありません。
• 操作、ワークフロー、ターン、フック、診断を記録するローカル SQLite データベースを利用できます。

Codex を直接呼び出すだけでは不十分なのはなぜですか？

機能	シンプルな Codex ラッパー	Codex Control Plane MCP
数時間に及ぶタスク	ブロッキング／不安定	永続的な非同期操作
クライアントのタイムアウトからの復旧	手動	リトライに安全な client_request_id
ターンの重複防止	なし	アクティブなプロンプトを検出
Plan Mode のワークフロー	人手／手動	ポーリング可能なワークフロー状態
承認と質問	ブロッキング／不透明	保留中のインタラクション API
再起動後の復旧	その場しのぎ	永続化された操作状態
診断	ログのみ	ヘルス、診断、修復ツール

詳しい判断ガイドについては、 docs/THIN_WRAPPERS.md をご覧ください。

現在のサポート状況

• ライブ環境での完全な対象：Codex Desktop と codex-app-server を使用する Windows。
• Linux と macOS：現時点ではプロトコルのチェックのみです。
• ローカル優先：公開ネットワークサービスとしての公開は想定していません。

セキュリティモデル

これは、信頼できる Codex Desktop 環境向けのローカル優先のコントロールプレーンです。

認証なしでネットワークサービスとして公開しないでください。

初回実行時に推奨される設定：

• 信頼できないリポジトリでは read-only を使用してください。
• 新しいワークフローをテストする際は、on-request 承認を使用してください。
• Plan Mode は read-only サンドボックスでは実行されません。呼び出し元が read-only を要求した場合、MCP はそのターンを workspace-write に引き上げ、 ステータス出力でその調整を報告します。
• state/、logs/、.env、.codex/ は非公開にしてください。

主な機能

• Codex の書き込み操作向けの永続的な非同期キューです。
• 再試行に安全な client_request_id の処理です。
• 実行中の重複プロンプトを検出します。
• 競合する MCP プロセスに対する SQLite リースとハートビートです。
• thread/start または turn/start 中に MCP が再起動した後の復旧です。
• 2 つ目のターンを作成せずに、実行中のターンにコンテキストを追加するための永続的な turn/steer です。
• 既存のスレッドを分岐するための永続的な thread/fork です。初期メッセージの有無は問いません。
• Plan Mode のワークフロー：プランの開始、ポーリング、承認、実行、最終レポートの読み取りです。
• Plan Mode の実行時の最低要件は workspace-write です。MCP が read-only リクエストを引き上げた場合、ステータスに runtimePolicyAdjusted が表示されます。
• app-server の review/start を通じたコードレビューのワークフローと、ポーリングおよび最終レポートの取得です。
• output_schema を使用した構造化された最終レポートです。
• アーカイブ、アーカイブ解除、ポーリング可能な圧縮を行うスレッドのライフサイクルツールです。
• Codex Desktop のスレッド目標とのワークフロー目標の同期です。
• turn/start で開始するターン向けの画像およびローカル画像入力です。
• 保留中の承認と質問を、ポーリング可能な MCP の状態として公開します。
• threadId／turnId、operationId、または workflowId によるターンの中断です。
• モデル、権限プロファイル、サンドボックスの準備状況、フック、スキル、プロバイダーの機能、アカウントの状態、使用量の範囲、レート制限の状態、対応する app-server メソッドのランタイムインベントリーです。
• ヘルスチェック、診断、問題分析、修復のドライランです。
• 検索、要約、フォールバック読み取りに対応する、SQLite 内の MCP 管理フック履歴です。
• 差分、警告、モデルの再ルーティング、トークン使用量を記録する、秘匿化された app-server 進捗ジャーナルです。
• 自動化コードで分岐処理できる構造化 MCP エラーです。

書き込み操作と制御操作は codex-app-server を経由します。このサーバーは、Codex 内部の SQLite データベースやトランスクリプトファイルを変更しません。

インストール

推奨：

pipx install codex-control-plane-mcp

または、直接実行します：

uvx codex-control-plane-mcp

GitHub から：

python -m pip install "codex-control-plane-mcp @ git+https://github.com/aresyn/codex-control-plane-mcp.git"

ローカル開発の場合：

git clone https://github.com/aresyn/codex-control-plane-mcp.git
cd codex-control-plane-mcp
py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
python -m pytest -q

MCP クライアントの設定

インストール後、設定を生成します：

codex-control-plane-mcp-admin init --state-db .\state\codex-mcp-state.sqlite3 --projects-root C:\Users\you\Projects

最小構成の stdio エントリー：

{
  "mcpServers": {
    "codex-control-plane": {
      "command": "codex-control-plane-mcp",
      "args": []
    }
  }
}

Claude Desktop、Cursor、VS Code 形式の MCP クライアント、ローカルのチェックアウト、インストール済みパッケージ、中央ワーカーモード向けの、コピーして貼り付けられる設定例は examples/mcp-client-configs.md にあります。

MCP stdio サーバーを実行します：

codex-control-plane-mcp

または、モジュールとして実行します：

py -m codex_control_plane_mcp.server

旧 openclaw-codex-mcp コマンドと openclaw-codex-mcp-hooks コマンドは、1 回のリリース系列に限り互換性エイリアスとして引き続き利用できます。

Central worker mode

デフォルトの inline モードは、引き続き最もシンプルなセットアップです。1 つの MCP プロセスで操作を送信し、実行できます。OpenClaw、Hermes、または複数の MCP クライアントを使うセットアップでは、代わりにセントラルワーカーを使用してください。

推奨されるローカル構成：

• すべての MCP クライアントで同じ CODEX_HOME と CODEX_MCP_STATE_DB を使用します。
• OpenClaw のゲートウェイエントリーは CODEX_MCP_EXECUTION_MODE=client を設定して実行します。
• 長時間稼働する codex-control-plane-mcp-worker プロセスを 1 つ起動し、codex-app-server、リース、キュースロット、リソースロックを管理します。
• クライアントは codex_submit_task を呼び出してから、ステータスをポーリングします。キューに入れられた操作をクライアント自身が実行することはありません。

ワーカーコマンド：

$env:CODEX_MCP_EXECUTION_MODE = "worker"
codex-control-plane-mcp-worker

稼働中のゲートウェイを切り替える前に役立つ、安全な監視モード：

codex-control-plane-mcp-worker --observe

同時実行のデフォルト設定：

CODEX_MCP_MAX_ACTIVE_TURNS_GLOBAL=4
CODEX_MCP_MAX_ACTIVE_TURNS_PER_PROJECT=3
CODEX_MCP_MAX_ACTIVE_TURNS_PER_AGENT=3
CODEX_MCP_MAX_ACTIVE_TURNS_PER_THREAD=1
CODEX_MCP_MAX_ACTIVE_WRITE_TURNS_PER_PROJECT=1
CODEX_MCP_MAX_APP_SERVER_PENDING_REQUESTS=8

同じプロジェクト内の書き込みターンでは、codex_submit_task に resource_keys を渡してください。これらを指定しない場合、workspace-write および danger-full-access ターンは、プロジェクト全体を対象とする書き込みロックを取得します。互いに重複しないキーを指定すると、ワーカーは複数の書き込みターンを並行して実行できます。

新しいステータスツール：

• codex_get_worker_status
• codex_get_queue_status
• codex_get_concurrency_status
• codex_get_worker_command_status

codex_get_operation_status は、queueState、workerState、slotState、resourceLockState も返します。実行中のターンでは、slotState.claimed=true となり、ワーカー ID、スロットタイプ、取得時刻を含む slotClaim が返されます。codex_get_queue_status では、キューに入っている作業と、実行中のターン操作、補助操作、アクティブなターンスロット、ロック競合がそれぞれ区別されます。

ワークフローが空き容量を待機している場合、codex_get_workflow_status は、ネストされた操作のキュー状態を workflowOperationQueueState に反映します。スロットが不足している場合は nextRecommendedAction="wait_for_worker_slot" を、書き込みロックが競合している場合は nextRecommendedAction="wait_for_resource_lock" を使用してください。いずれかのアクションが返された場合は、同じ作業に対して別の操作を作成しないでください。

First setup

管理ヘルパーを使うと、より詳細なクライアント設定を生成し、フックをインストールして、プロトコルのスモークテストを実行できます。

codex-control-plane-mcp-admin init --state-db .\state\codex-mcp-state.sqlite3 --projects-root C:\Users\you\Projects

このコマンドは、MCP クライアントの設定にコピーできる JSON ブロックを出力します。シークレットや非公開のプロンプトは出力されません。

Codex フックだけをインストールすることもできます。

codex-control-plane-mcp-hooks install --state-db .\state\codex-mcp-state.sqlite3
codex-control-plane-mcp-hooks status
codex-control-plane-mcp-hooks doctor

インストーラーは ~/.codex/hooks.json をバックアップし、既存のフックとハンドラーをマージし、stateDb を絶対パスとして保存します。また、プロンプト、表示されるエージェントの進行状況テキスト、最終回答、ターンのステータスを MCP 状態 DB に書き込みます。ツールの呼び出しとコマンドの出力は、デフォルトでは記録されません。フックをインストールまたは変更した後は、Codex を再起動してください。

codex-app-server 経由で開始されたターンでは、サーバーは受け付けたプロンプト、表示されるアシスタントのメッセージ、ターンのステータスを同じ SQLite 履歴に記録します。これにより、app-server がユーザーフックをそれ自体では実行しない場合でも、検索とステータスの読み取りが引き続き有用になります。

Main workflows

永続的なタスクを送信します。

codex_submit_task
  -> operationId
codex_get_operation_status(operationId)
  -> queued / running / waiting_for_approval / completed / failed

呼び出し元がトランスポートのタイムアウト後に再試行する場合は、同じ client_request_id を使用してください。再試行すると、新しいターンを作成する代わりに、既存の操作が返されます。

スクリーンショットやその他の画像の証拠を添付します。

codex_submit_task(
  operation_type="start_chat",
  message="Analyze this screen.",
  input_items=[
    {"type": "localImage", "path": ".\\screens\\error.png", "detail": "low"},
    {"type": "image", "url": "https://example.com/screenshot.png", "detail": "high"}
  ]
)

画像入力は、新しいターンを開始する操作タイプでのみ受け付けられます。対象は start_chat、send_message、execute_plan、および初期メッセージを指定した fork_thread です。MCP はパスまたは URL を codex-app-server に送信しますが、操作ステータスと診断情報に含まれるのは、タイプ、詳細、サイズ、拡張子、ハッシュなどの安全なメタデータのみです。バイナリ形式の画像データ、生の URL、完全なローカル画像パスは、公開ステータスペイロードには保存されません。

実行中のターンを制御します。

codex_submit_task(operation_type="steer_turn", thread_id=..., expected_turn_id=..., message=...)
  -> operationId
codex_get_operation_status(operationId)
  -> follows the target turn until completed / failed / interrupted

steer_turn は、対象のターンがアクティブな間だけ使用してください。完了済みのスレッドには、代わりに send_message を使用してください。

スレッドをフォークします。

codex_submit_task(operation_type="fork_thread", source_thread_id=...)
  -> operationId
codex_get_operation_status(operationId)
  -> completed, threadId=<forkedThreadId>

フォーク先ですぐに作業を開始します。

codex_submit_task(operation_type="fork_thread", source_thread_id=..., message=...)
  -> operationId
codex_get_operation_status(operationId)
  -> follows the first turn in the forked thread

再試行可能なフォーク要求には client_request_id を使用してください。指定しない場合、呼び出しのたびに新しいフォーク要求として扱われます。操作ステータスの threadId はフォークされたスレッドを示し、ソーススレッドは forkState.sourceThreadId に示されます。

スレッドのライフサイクルを管理します。

codex_archive_thread(thread_id)
  -> completed
codex_unarchive_thread(thread_id)
  -> completed
codex_start_thread_compaction(thread_id)
  -> actionId
codex_get_thread_compaction_status(actionId)
  -> running / completed / unknown_after_app_server_exit

アーカイブとアーカイブ解除は、app-server の thread/archive と thread/unarchive に対応する監査アクションです。スレッドでターンが実行中の場合や、 保留中のインタラクションがある場合は実行できません。コンパクションは thread/compact/start が非同期であるため、独自の軽量な actionId を使用します。 公開 API の thread/delete は意図的に公開していません。

構造化された最終レポートを要求します。

codex_submit_task(operation_type="start_chat", message=..., output_schema={...})
codex_approve_plan(workflowId, output_schema={...})
  -> operationId / executionOperationId
codex_get_operation_status(operationId)
codex_get_workflow_status(workflowId)
  -> finalReport.text + finalReport.structured

output_schema は app-server の turn/start に渡され、ステータス出力ではスキーマ ハッシュによって追跡されます。オブジェクトスキーマには Codex が要求する厳密な形式を 使用してください。additionalProperties を false に設定します。MCP は最終的なアシスタント メッセージを読み取り可能なテキストとして保存し、Codex が有効な JSON を返した場合は、 JSON オブジェクトの出力を finalReport.structured に解析します。プレーンテキストも引き続き 使用でき、finalReport.text で利用できます。

MCP は、隠された思考の連鎖を抽出したり、生のツールペイロードやコマンド出力を最終レポートに 保存したりしません。

プランモードを実行します。

codex_start_plan_workflow
  -> workflowId
codex_get_workflow_status(workflowId)
  -> wait_plan / review_plan / execute_plan
codex_approve_plan(workflowId)
  -> executionOperationId
codex_get_workflow_status(workflowId)
  -> finalReport

プランモードには、ランタイムの最低要件があります。公開されているデフォルトの書き込み ポリシーは引き続き read-only と on-request ですが、Windows ではプランモードに書き込み可能な ワークスペースが必要です。呼び出し元またはサーバーのデフォルトが read-only に解決される 場合、MCP は codex-app-server に workspace-write を送信し、ワークフローと操作のステータスに requestedSandbox、effectiveSandbox、runtimePolicyAdjusted を返します。

クライアントに目標がある場合は、ワークフローの目標を Codex Desktop に反映します。

codex_start_plan_workflow(goal="Review the migration plan", goal_completion_action="clear")
codex_get_workflow_status(workflowId, refresh_live_goal=true)
  -> threadGoal.syncState + threadGoal.currentGoal

MCP は、クライアントが goal を渡した場合にのみスレッドの目標を書き込みます。 管理対象の目標は、完了後にデフォルトで clear を使用します。ワークフロー終了後も目標を 表示したままにするには、set_complete または leave を使用します。通常のワークフローの ポーリングはパッシブです。MCP に app-server の目標メソッドをライブで呼び出させる場合にのみ、 refresh_live_goal=true を使用してください。

Codex のコードレビューを実行します。

codex_start_review_workflow(thread_id=..., target_type="base_branch", base_branch="main")
  -> workflowId
codex_get_workflow_status(workflowId)
  -> wait_review / read_review_report

または、MCP にローカルのチェックアウト用のサースレッドを作成させます。

codex_start_review_workflow(cwd=..., target_type="uncommitted_changes")
  -> workflowId
codex_get_workflow_status(workflowId)
  -> reviewThreadId + reviewTurnId + finalReport

レビューのワークフロー自体がファイルを書き込むことはありません。選択された Codex の サンドボックスと承認ポリシー内で実行されます。トランスポートのタイムアウト後に呼び出し元が 開始リクエストを再試行する可能性がある場合は、client_request_id を使用してください。

承認や質問に対応します。

codex_list_pending_interactions
codex_answer_pending_interaction

次のコマンドで診断を開始します。

codex_get_runtime_capabilities
codex_health_summary
codex_collect_diagnostics
codex_analyze_issue
codex_repair_issue

修復アクションでは、デフォルトで dry_run=true が設定されます。

ステータスツールと診断ツールは、MCP がブロッカー、失敗状態、古い実行、保留中の インタラクション、重複したプロンプト、認証の問題、レート制限、または安全でない復旧ループを 検出した場合、agentGuidance と agentGuidanceText も返します。エージェントは再試行または 停止を決定する前に、agentGuidance.instructions に従う必要があります。 agentGuidance.loopGuard.allowed=false の場合は、自動復旧を停止し、診断情報を収集して人に 確認してください。ガイダンスで代替ワークフローの開始が明示されていない限り、タイムアウト後に 新しい client_request_id を作成しないでください。

プランモードのワークフローが壊れた場合は、 retry_workflow_with_runtime_policy を使用してください。このツールは選択したサンドボックスと 承認ポリシーで新しいワークフローを作成し、workflowRetryState を介して古いワークフローと 関連付けます。古い終端ターンを再開することはありません。

codex_health_summary は、デフォルトで現在の準備状態を示します。古い行や孤立した行は historicalDebt に報告されますが、ワーカー、キュー、app-server が現在正常であれば、新しい オーケストレーションを異常とは見なしません。この負債には、新しい作業をブロックするのではなく、 対象を絞ったクリーンアップを使用してください。

ステータスペイロードでは、鮮度を示すシグナルが分離されるようになりました。

• operationRowAgeSeconds：永続化された操作行の経過時間。
• turnFreshness.lastProgressAgeSeconds：最後のターン進捗イベントからの経過時間。
• workerFreshness.heartbeatAgeSeconds：ワーカーのハートビートからの経過時間。
• 互換性のための stalenessSeconds フィールドでは、stalenessMeaning="operation_row_age" が設定されます。 公開ステータスペイロードは、エージェントが安全に扱えます。オペレーションとワークフローのステータスでは、生のrequestの代わりにrequestSummaryを返します。これには、ID、ランタイムポリシー、スケジューリングの意図、入力項目の状態、出力スキーマのハッシュ、リソースキー、テキストのハッシュが含まれます。完全なプロンプト、完全な指示、生のタイトル、生の画像URL／パス、正確なトークン数、生のコマンド出力、プライベートパスは含まれません。相関には、保存しておいた自身のタスクテキストとrequestSummary.*.sha256を使用してください。

codex_get_queue_statusがwait_for_worker_slotを推奨するのは、実際にキューに入った作業がスロット不足でブロックされている場合のみです。実行中のターンがあっても、queueSummary.queued == 0の場合、キューアクションはnoneです。

ランタイム機能

オーケストレーションの前、または再接続後にcodex_get_runtime_capabilitiesを使用してください。必要に応じてMCPが管理するapp-serverを起動し、短時間で完了するベストエフォートのインベントリメソッドを呼び出して、5分間キャッシュされるスナップショットを返します。

clientモードでは、クライアントプロセスはライブインベントリのために独自のapp-serverを起動しません。ワーカーが管理するパッシブなスナップショットがある場合は、それを返します。refresh=trueを指定すると、ワーカーコマンドをキューに追加してrefreshCommandIdを返します。更新されたインベントリを取得するには、codex_get_worker_command_statusをポーリングしてください。

レスポンスには以下が含まれます。

• モデル数、デフォルトモデル、非表示フラグ、入力モダリティ、推論レベル、サービスティア数。
• idとdescriptionによる権限プロファイル。
• Windowsサンドボックスの準備状況。
• ウェブ検索、画像生成、名前空間ツールに関するプロバイダー機能。
• 生のフックコマンドや絶対パスのスキルパスを含まない、フックとスキルの数。
• 伏せ字処理されたアカウントステータス、大まかな使用量の範囲、運用上のレート制限状態。
• コンパクトなソース、バージョン、ハッシュを含む、サポート対象のapp-serverスキーマメソッド。

アカウントインベントリは、オーケストレーターに表示しても安全です。Codexが認証済みかどうか、アカウントとプランの種類、メールアドレスが登録されているか、使用量データが利用可能か、レート制限またはクレジットに関する問題が確認されているかを報告します。生のメールアドレス、アカウント識別子、クレジット残高、利用上限、正確な使用額、日ごとの使用量、正確なトークン数は返しません。

いずれかのインベントリメソッドがタイムアウトまたは失敗しても、ツールはruntimeCapabilities.status="partial"と、methodResults内の機械可読な警告を含めてok=trueを返します。キャッシュをバイパスするには、refresh=trueを設定してください。codex_health_summaryは、最後に収集されたスナップショットからruntimeCapabilitiesの一部を表示しますが、単独ではapp-serverを起動しません。クライアントがアカウント、使用量、レート制限のステータスを必要としない場合は、include_account=falseを渡してください。

進捗ジャーナル

codex_get_turn_statusとcodex_get_operation_statusは、デフォルトでコンパクトなprogressEventsブロックを含みます。これは、アシスタントのテキスト差分、計画の差分、推論サマリーのテキスト、トークン使用量、モデルの再ルーティング、警告など、app-serverから確認できる進捗を記録します。

このジャーナルは、オーケストレーションとトラブルシューティングに役立ちます。非公開の思考過程を抽出するものではありません。また、デフォルトでは、生のツールペイロード、コマンド出力、完全な統合差分を保存しません。差分イベントは、変更行数や差分サイズなど、安全な件数に要約されます。

クライアントが従来のメッセージのみのステータス形式を必要とする場合は、progress_events=0を使用してください。返される進捗テキストの上限を設定するには、progress_max_charsを使用してください。

公開ステータスでは、トークン使用量は正確なトークン数ではなく、大まかな範囲で返されます。生の監査用データには、デバッグ用に伏せ字処理されたイベントペイロードが保持される場合がありますが、オーケストレーターはtokenUsage.totalTokensBandおよび関連する範囲フィールドを公開契約として扱う必要があります。

ツールの構成

安定したオーケストレーションツール：

• codex_submit_task
• codex_get_operation_status
• codex_start_plan_workflow
• codex_start_review_workflow
• codex_get_workflow_status
• codex_approve_plan
• codex_list_pending_interactions
• codex_answer_pending_interaction
• codex_interrupt_turn
• codex_archive_thread
• codex_unarchive_thread
• codex_start_thread_compaction
• codex_get_thread_compaction_status
• codex_get_runtime_capabilities
• codex_health_summary
• codex_collect_diagnostics
• codex_repair_issue

互換性ツールと読み取りツール：

• codex_start_chat
• codex_send_message
• codex_execute_plan
• codex_list_projects
• codex_list_project_chats
• codex_list_active_chats
• codex_search_chats
• codex_get_chat_status
• codex_get_chat
• codex_get_turn_status
• codex_restart_app_server
• codex_get_app_server_status
• codex_get_diagnostic_logs
• codex_analyze_issue

新しいクライアントでは、永続的な操作とワークフローを使用してください。低レベルの書き込みツールも、互換性のために引き続き利用できます。

読み取りと診断の呼び出しには、エージェントのループ向けに上限が設定されています。codex_list_projects は、デフォルトでコンパクトなキャッシュ済み出力を返します。codex_search_chats は、全件更新を待たずに timeBudgetExhausted=true を返すことがあります。また、チャットの読み取りでは、従来の KB フォールバックよりも、追跡されたターンとフックの履歴が優先されます。診断はスコープを優先します。次のアクションには scopedFindings を使用し、backgroundFindings は過去のコンテキストとして扱います。

スキーマ、エラー形式、安定したツールグループ、バージョニングのルールについては、docs/API_CONTRACT.md を参照してください。

結果の契約

すべてのツールは outputSchema を宣言し、MCP の structuredContent を返します。

成功：

{"ok": true}

ドメインまたはツールのエラー：

{
  "ok": false,
  "error": {
    "code": "CODEX_ERROR_CODE",
    "message": "Human readable message",
    "details": {},
    "retryable": false
  }
}

起動時および再接続時には codex_health_summary を呼び出してください。version ブロックには、serverName、serverVersion、contractVersion、toolSurfaceHash、guideHash、guideVersion、推奨される起動ツールと書き込みツール、および安定ツールと互換性ツールの一覧が含まれます。

エージェントは、この README を読まなくても運用契約を確認できます。tools/list には、次の情報が含まれます。

• codexMcpGuide：機能、フロー、グローバルルール、ランタイム制限をまとめた、簡潔で機械可読なガイド。
• toolGroups：優先して使用するツールの順序付きグループ。
• recommendedStartupTool="codex_health_summary"。
• recommendedPrimaryWriteTool="codex_submit_task"。

すべてのツールには、役割、後続ツール、冪等性のルール、受動的な読み取りかどうか、mayStartTurn フラグを示す annotations.codexMcp もあります。クライアントライブラリがトップレベルの tools/list フィールドを隠す場合は、codex_get_agent_contract(detail="compact") または codex_get_agent_contract(detail="full", include_examples=true) を呼び出してください。

設定

設定は環境変数、または CODEX_CONTROL_PLANE_MCP_CONFIG で参照される JSON ファイルから読み込めます。旧名称の OPENCLAW_CODEX_MCP_CONFIG もフォールバックとして引き続き受け付けます。

共通の環境変数：

• CODEX_HOME：Codex のホームディレクトリです。デフォルトは %USERPROFILE%\.codex です。
• CODEX_PROJECTS_ROOT：カタログツールと読み取りツールがスキャンするプロジェクトのルートです。
• CODEX_ALLOWED_ROOTS：セミコロン区切りのパス許可リストです。
• CODEX_PROJECTS_REGISTRY：任意の JSON プロジェクトレジストリです。
• CODEX_MCP_STATE_DB：ローカルの MCP 状態 DB です。
• CODEX_CONTROL_PLANE_MCP_LOG：ログファイルのパスです。
• CODEX_MCP_HOOK_HISTORY_ENABLED：SQLite のフック履歴を有効にします。デフォルトは true です。
• CODEX_MCP_HOOK_HISTORY_MAX_TEXT_CHARS：フックで取得するメッセージごとのテキスト上限です。
• CODEX_KB_HISTORY_PROJECTS_ROOT：任意の旧形式の正規化済み KB 履歴ルートです。
• CODEX_BINARY_PATH：任意の明示的な Codex バイナリのパスです。
• CODEX_MCP_DEFAULT_SANDBOX：デフォルトの書き込みサンドボックスです。デフォルトは read-only です。
• CODEX_MCP_DEFAULT_APPROVAL_POLICY：デフォルトの書き込み承認ポリシーです。デフォルトは on-request です。
• CODEX_MCP_DEFAULT_MODEL：app-server に渡されるデフォルトの Codex モデルです。
• CODEX_MCP_DEFAULT_EFFORT：デフォルトの作業レベルです。
• CODEX_MCP_MAX_IMAGE_INPUT_ITEMS：codex_submit_task ごとの画像添付ファイルの最大数です。デフォルトは 10 です。
• CODEX_MCP_MAX_IMAGE_INPUT_BYTES：ローカル画像入力 1 件あたりの最大バイト数です。デフォルトは 20000000 です。
• CODEX_MCP_TURN_STALL_TIMEOUT_SECONDS：ターンの停止を報告するまでの非アクティブ時間です。デフォルトは 900 です。
• CODEX_MCP_STALLED_TURN_ACTION：停止したターンに対するポリシーです。デフォルトは diagnose_only です。
• CODEX_MCP_APPROVAL_RESPONSE_TIMEOUT_SECONDS：保留中のやり取りのタイムアウトです。
• DEEPSEEK_ENV_PATH：DeepSeek の要約設定に使用する任意の .env ファイルです。
• DEEPSEEK_SUMMARY_ENABLED：リモート要約呼び出しを有効または無効にします。

書き込みポリシーの値はデフォルトであり、厳格な制限ではありません。信頼できるワークフローで異なる設定が必要な場合、クライアント呼び出しで sandbox または approval_policy を明示的に渡せます。

Plan Mode は純粋な受け渡し動作の例外です。Windows では read-only は Plan Mode に対して制限が厳しすぎる設定として扱われ、workspace-write に引き上げられます。workspace-write など、より許容的な呼び出しごとの値はそのまま渡されます。

例：

$env:CODEX_CONTROL_PLANE_MCP_CONFIG = Join-Path (Get-Location) "examples\codex-control-plane-mcp.config.json"
$env:CODEX_MCP_DEFAULT_SANDBOX = "read-only"
$env:CODEX_MCP_DEFAULT_APPROVAL_POLICY = "on-request"
py -m codex_control_plane_mcp.server

examples/codex-control-plane-mcp.config.json を参照してください。

信頼性モデル

このサーバーは、よくあるローカルオーケストレーションの障害に対応するよう設計されています。

• タスク送信後の MCP クライアントのタイムアウト。
• 同じ client_request_id を使った送信の繰り返し。
• 冪等性キーを指定せず、同じアクティブなプロンプトで送信を繰り返すケース。
• app-server の thread/start と turn/start の間での MCP プロセスの再起動。
• 2 つの MCP プロセスによる、同じ SQLite 状態 DB の共有。
• ターンの実行中における app-server の終了。
• 古い app-server 世代に紐づく保留中の承認。
• app-server またはトランスクリプトに欠落があっても、フック履歴にはプロンプト、表示されたエージェントのテキスト、最終回答、完了ステータスが記録されているケース。

これらのケースは、永続的なオペレーション、ワークフロー、ターン、フック、保留中のやり取りの状態に保存されます。終端ステータスは明示されます。 unknown_after_app_server_exit は成功として扱われません。

安全性

• ライブのスモークテスト用プロンプトには MCP LIVE TEST / DO NOT MODIFY FILES を含める必要があります。
• 修復では dry_run=true がデフォルトです。
• app-server を強制的に再起動すると、アクティブなターンが不明または孤立した状態になる場合があります。restart_app_server_idle を優先してください。

チェック

高速なローカルチェック：

python -m pytest -q
python -m compileall -q openclaw_codex_mcp codex_control_plane_mcp tests scripts
git diff --check

プロトコルのみの MCP スモークテスト：

python .\scripts\mcp_live_smoke.py --scenario protocol

実際の Codex Desktop／app-server を使った安全なライブスモークテスト：

python .\scripts\mcp_live_smoke.py --scenario safe-operation --cwd <PROJECT_ROOT>

ライブ回帰テスト全体：

python .\scripts\mcp_live_smoke.py --scenario full --safe-restart --cwd <PROJECT_ROOT>

開発および長時間のライブテスト用の外部 MCP クライアント：

python .\scripts\external_mcp_client.py daemon-start
python .\scripts\external_mcp_client.py daemon-restart-mcp --reason after_code_change
python .\scripts\external_mcp_client.py run-live-test --scenario full --archive-report

Codex Desktop を再起動せずに、現在のチェックアウトを実際の MCP クライアントとしてテストする場合は、外部クライアントを使用してください。独立したデーモンを実行し、独自の MCP stdio サブプロセスを維持するため、コード変更後はそのサブプロセスだけを再起動できます。ライブテストの調査結果は corrective_action_plan.md に記録されます。以前のレポートは --archive-report でアーカイブできます。

デーモンのコマンドと利用可能なライブシナリオについては、docs/EXTERNAL_MCP_CLIENT.md を参照してください。

docs/RELEASE_CHECKLIST.md を参照してください。一般公開時の位置づけについては、docs/PUBLICATION_GUIDE.md を参照してください。

パッケージング

ローカルでビルドします：

python -m pip install build
python -m build

wheel には、MCP サーバー、フックインストーラー、管理ヘルパー、およびバンドルされた Codex フックモジュールが含まれています。

通常のインストール方法は次のとおりです：

pipx install codex-control-plane-mcp

または：

uvx codex-control-plane-mcp

コントリビューション

診断情報を含む issue を作成する前に、CONTRIBUTING.md と SECURITY.md をお読みください。

このリポジトリに適した GitHub トピック：

python、mcp、mcp-server、model-context-protocol、openai-codex、 codex、codex-desktop、agent-tools、ai-agents、developer-tools、 automation、orchestration、agentic-workflows、long-running-tasks、 openclaw、hermes、hermes-agent。