Plugin guides
Codex セッションを監視する
Codex 監督は、公式 codex Plugin のオプトイン機能です。Gateway
コンピューターおよびオプトインしたペアリング済みコンピューター上の、アーカイブされていない Codex Desktop と CLI のソースセッションを、通常のセッションサイドバーと Chat ペインに表示します。
初回リリースでは、意図的に所有範囲を限定しています。
- 保存済みまたはアイドル状態のローカルセッションでは、範囲が制限された永続化済みのユーザーとアシスタントの履歴から、モデルが固定された OpenClaw Chat を作成できます。最初のメッセージでネイティブスナップショットフォークを作成し、その後、Codex App Server がそのフォーク用に選択したモデルとプロバイダーを正確に使用して、完全な Codex ハーネススレッドを開始します。以降のターンでは、正規のネイティブスレッドに永続化されたペアを復元し、監督バインディングによって OpenClaw が別のランタイム、モデル、フォールバックに置き換えることを防ぎます。別のネイティブ Codex コントロールから、その永続化されたペアを変更することは引き続き可能です。作成済みのブランチは、既存の Chat を開きます。
- 別の Codex プロセスから検出された保存済みセッションは、ライブアクティビティが不明です。ブランチを作成することはできますが、アーカイブできるのは、他の Codex クライアントが使用していないことをオペレーターが確認した後だけです。
- アクティブなソースは引き続き表示されますが、現在のターンが完了するまでブランチの作成もアーカイブもできません。監督対象の Chat がすでに存在する場合は、Chat を開くを引き続き使用できます。
- ペアリング済み Node 上のセッションは、範囲が制限されたカーソルページネーション付き App Server 読み取りを通じて、永続化されたトランスクリプトを公開します。リモートでの継続には、将来のストリーミング Node ブリッジが必要です。リモートアーカイブには、さらにランナー所有権リースまたは同等のフェンシングが必要です。
- アーカイブ済みセッションは一覧表示されません。保存済みまたはアイドル状態のローカルセッションをアーカイブできるのは、他の Codex クライアントが使用していないことをオペレーターが確認した後だけです。
始める前に
- Gateway に公式
@openclaw/codexPlugin をインストールします。OpenClaw macOS アプリでは、Codex 機能を有効にするとインストールできます。CLI でインストールする場合は、openclaw plugins install @openclaw/codexを実行できます。 - セッションを一覧表示する各コンピューターに Codex Desktop または Codex CLI をインストールし、サインインします。
- リモートコンピューターを OpenClaw Node としてペアリングします。各コンピューターでローカルにオプトインする必要があります。Gateway だけで監督を有効にしても、別の Node は認可されません。
- 所有者が管理する Gateway を使用します。セッションタイトル、作業ディレクトリ、Git ブランチから、機密性の高いプロジェクト情報が漏れる可能性があります。
監督を有効にする
ガイド付きの openclaw onboard と macOS の初回実行セットアップでは、ネイティブ Codex のインストールを検出し、選択した推論バックエンドの有効化に成功した後、Codex 監督のインストールと有効化を試みます。Codex がプライマリバックエンドである必要はありません。この状況に応じた Plugin の有効化が成功すると、監督を使用できるようになります。App Server の可用性は、監督が最初に接続するときに確認されます。Codex Plugin が明示的に無効化されている場合やポリシーでブロックされている場合は、状況に応じた有効化は行われません。また、既存の明示的な
supervision.enabled: false はエージェント向けの監督ツールを無効にします。オペレーターカタログは、Codex Plugin がアクティブである限り登録されたままです。
既存のインストールでも、同じ機能を手動で有効にできます。
openclaw.json で codex Plugin とその監督機能を有効にします。
{ plugins: { entries: { codex: { enabled: true, config: { supervision: { enabled: true, }, }, }, }, },}plugins.allow が存在する場合は、codex を含めます。Plugin の有効化設定を変更した後は、Gateway を再起動します。
明示的な appServer 接続設定がない場合、監督はネイティブユーザーの Codex ホームに対して、独立した管理対象 stdio 監督接続を使用します。通常の Codex ハーネスは、デフォルトではエージェントスコープのままです。これにより、通常の OpenClaw ターンでネイティブ Codex の状態を共有することなく、両方のアプリでネイティブセッションを表示できます。ハーネスでもその状態を共有する必要がある場合は、appServer.homeScope: "user" を明示的に設定します。監督は、明示的な appServer 接続設定をローカルのユーザーホームのデフォルトに置き換えず、その設定に従います。
Codex サイドバーグループから引き継いだ Chat は、通常のハーネスセッションではありません。その非公開の監督バインディングは、ソースの読み取り、正規ブランチの作成、履歴の注入、および以降のすべてのターンに監督接続を使用します。デフォルトのローカル接続では、他のセッションのデフォルトを変更することなく、ネイティブユーザーの Codex ホーム、認証、プロバイダー設定が維持されます。
デフォルトのローカル監督接続では、ストアがネイティブ Codex クライアントと共有されます。OpenClaw は、別のクライアントが同じライブ App Server プロセスを共有しているとは想定しません。また、ネイティブのステータス所有権はプロセスローカルです。そのため、監督用 App Server が notLoaded と報告するスレッドを、アイドル状態ではなく、保存済み / アクティビティ不明として扱います。
セッションを表示する各ヘッドレス Node ホストでも、同じオプトインを適用します。ネイティブ OpenClaw macOS アプリは、Codex カタログをペアリング済み Gateway に通知するときに、同じローカル設定を読み取ります。ペアリング済みのネイティブ Mac カタログがサポートするのは、デフォルトまたは明示的な appServer.transport: "stdio" と、未設定または明示的な appServer.homeScope: "user" の組み合わせだけです。その stdio プロセスでは、command、args、clearEnv が適用されます。Mac の設定で "unix"、
"websocket"、または homeScope: "agent" が選択されている場合、アプリはカタログ機能もコマンドも通知しません。また、古い直接呼び出しは、ユーザーの Codex ホームを公開したり、別のローカル stdio App Server を起動したりせず、失敗します。
新しく通知された Node コマンドにより、Node の承認済みコマンド範囲が変更されます。 Gateway ホストから更新を承認します。
openclaw nodes pendingopenclaw nodes approve <requestId>アーカイブされていない Codex セッションは、メインの Control UI サイドバーにもホスト別にグループ化されて表示されます。いずれかを選択すると、永続化されたトランスクリプトを確認できます。ビューアーは最新の Codex thread/turns/list API を itemsView: "full" で使用し、リクエストごとに最大 20 ターンを読み込みます。古いトランスクリプト項目を読み込むでは、最新ページから取得した不透明な App Server カーソルを使用します。読み込まれたページは時系列順にレンダリングされます。ビューアーが無制限の thread/read 履歴を読み込むことはありません。20 MiB の転送安全上限を超えるページは、Node や Gateway の接続を危険にさらす代わりにフェイルクローズします。
通常のセッションサイドバーで Codex グループを開きます。同じセッションがホスト別にグループ化されて一覧表示されます。さらにセッションを読み込むを選択すると、古い行がある各ホストから次のページが追加されます。追加された行は、サイドバーの定期更新後も維持されます。ネイティブ検索ではトランスクリプトのプレビューも一致対象となるため、クエリを App Server に送信するのではなく、返される各検索ページでホストごとに有限数のネイティブページをスキャンします。
ホストの可用性とスレッドのステータスは別のものです。オフラインまたは利用不可はホストの更新状態を表します。利用できないホストは新しいセッション行を返さず、スレッドのネイティブステータスを offline に変更することもありません。セッション行では、idle、active、notLoaded、エラーなどの Codex ステータスを使用します。障害が発生したホストによって、正常なホストからの結果が非表示になることはありません。
オペレーター CLI を使用する
ターミナル CLI では、同じアーカイブされていないカタログと、Gateway ローカルのブランチおよびアーカイブ操作を利用できます。
openclaw codex sessions [--search <text>] [--host <id>] [--limit <count>] [--cursor <cursor>] [--json] [--url <url>] [--token <token>] [--timeout <ms>] [--expect-final]openclaw codex continue <thread-id> [--json] [--url <url>] [--token <token>] [--timeout <ms>] [--expect-final]openclaw codex archive <thread-id> --confirm-no-other-runner [--json] [--url <url>] [--token <token>] [--timeout <ms>] [--expect-final]openclaw codex sessions のオプション:
--search <text>は、セッションのタイトルを大文字と小文字を区別せずに検索します。--host <id>は、応答をgateway:localやnode:<node-id>などの安定した単一のカタログホストに限定します。--limit <count>はホストごとの行数を 1～100 に設定します。デフォルトは 50 です。--cursor <cursor>は単一ホストの次のページを取得するため、--hostが必要です。--jsonは、構造化された Gateway 応答を出力します。
3 つのコマンドはすべて、Gateway クライアントから --url、--token、--timeout <ms> を継承します。セッション一覧のタイムアウトはデフォルトで 75,000 ms に設定されており、コールド状態のペアリング済み Node のカタログでも処理を完了できます。continue と archive のデフォルトは 30,000 ms です。また、共有の --expect-final スイッチも公開されていますが、この単項監視 RPC の動作は変更されません。
各コマンドには、Gateway の operator.write スコープが必要です。
各サブコマンドでは、標準の -h, --help 出力を使用できます。
アーカイブ済みセッションのみを対象にするオプションや、アーカイブ済みセッションを含めるオプションはありません。sessions はペアリング済みホストを一覧表示できますが、continue と archive の対象は常に gateway:local です。ペアリング済みホストの行は一覧表示専用です。Archive では常に --confirm-no-other-runner が必要です。
これらのシェルコマンドは、チャット内の /codex ランタイムコマンドとは異なります。
/codex threads [filter] は、現在の会話接続で利用可能な App Server スレッドを一覧表示します。
/codex sessions --host <node> は、監視フリートのカタログではなく、1 つの Node 上にある再開可能な Codex
CLI セッションファイルを一覧表示します。/codex resume と /codex bind は、安全な監視対象ブランチを作成する代わりに現在の会話をアタッチします。また、モデルが固定された監視対象 Chat では、これらの
バインディング変更は拒否されます。/codex continue または /codex archive というランタイム
コマンドはありません。
ローカルセッションから分岐する
Gateway コンピューターから、保存済みまたはアイドル状態の行で Continue as branch を選択します。 OpenClaw は通常のチャットエントリを作成し、ソースの最後に永続化された終了ターン（完了、中断、または 失敗）までの、上限付きのユーザーとアシスタントの履歴をミラーリングし、保留中のハーネスブランチを記録して、 チャットを開きます。汎用モデルピッカーはロックされますが、この時点では具体的なモデルもプロバイダーも まだ選択されていません。ソースは再開されず、正規のハーネススレッドもまだ開始されません。 この操作を繰り返すと、別のブランチを作成する代わりに既存のチャットが開きます。
ミラーでは、3 つの制限すべてに収まる最新の可視末尾が保持されます。ユーザーまたはアシスタントの
メッセージは最大 200 件、UTF-8 テキストの合計は 512 KiB、メッセージごとは 64 KiB です。
サイズ超過のメッセージはマーカー付きで切り詰められ、上限に達すると古いメッセージは省略されます。
画像またはローカル画像の入力は、リテラルの [Image attachment] プレースホルダーになります。
画像データとローカルパスはコピーされません。
最初の通常のチャットメッセージを送信して作業を開始します。Codex ハーネスは、実際の承認、情報取得、
イベント、および配信の各ハンドラーをインストールします。監視接続上で一時的なネイティブフォークを使用し、
モデルやプロバイダーのオーバーライドを指定せずにソーススナップショットを固定します。Codex App Server は
現在のネイティブ設定から両方を選択し、実際の選択結果を返します。同じ接続上で OpenClaw は、その返された
ペアを正確に使用し、cwd とランタイムポリシーの下で正規の appServer ソースの完全なハーネススレッドを
開始し、上限付きの可視履歴を注入して、一時フォークをアーカイブします。正規スレッドでは、OpenClaw
ハーネスの全ツールサーフェスを使用できます。これは可視履歴のブランチであり、完全なネイティブロールアウトの
クローンではありません。ソースの推論、ツール呼び出し、およびツール結果は省略されます。このターンと以降の
すべてのターンは、別の OpenClaw モデルランタイムや通常のエージェントホームハーネスではなく、監視対象の
Codex 接続上に留まります。
返された選択結果は、ソースが過去に使用していたモデルの証明にはなりません。現在のネイティブ設定が、 ソースの最後のターンに記録されたモデルと異なる場合、Codex は通常のモデル差異警告を出力します。OpenClaw は 返されたペアを正規スレッドの開始に使用します。Codex はその正規スレッドのネイティブモデルとプロバイダーを 永続化し、その後の再開時には OpenClaw がモデルとプロバイダーのオーバーライドを省略するため、それらが 維持されます。正規スレッドが別のネイティブ Codex コントロールを通じて変更された場合、OpenClaw は Codex が 永続化した選択を受け入れます。OpenClaw が外側のモデルやフォールバックチェーンで置き換えることはありません。
監督対象でモデルがロックされた Chat は、削除、モデルの切り替え、/new
または /reset の使用、Gateway のセッションリセットアクションの呼び出し、汎用の
セッションをフォーク アクションの使用ができません。/codex model <model>、/codex bind、/codex resume（--bind here を指定した Node セッションを含む）を変更目的で実行すること、および
/codex detach または /codex unbind も、ロックされたネイティブバインディングを置き換えるか
クリアするため拒否されます。/codex model クエリと /codex fast、
/codex permissions、/codex threads は引き続き使用できます。別のモデルまたは新しいスレッドが
必要な場合は、別の通常セッションを開始してください。
この Chat では監督を有効なままにしてください。監督が無効化された場合、または保存された 接続バインディングが利用不能または不整合になった場合、そのターンは通常のエージェントホームセッションへ 移行せず、フェイルクローズします。
codex Plugin を無効化またはアンインストールしても、その所有権は解放されず、
Chat が別のモデルを使用できるようにもなりません。ロックされた Chat は保持されますが
利用不能になります。同じ Plugin を再インストールまたは再有効化し、Gateway を再起動して
再開してください。この意図的なフェイルクローズ動作により、保持データのクリーンアップや
Plugin の一時的な停止によって、ネイティブバインディングが通知なく孤立することを防ぎます。
codex_threads エージェントツールも同じ境界に従います。別のフォークをアタッチしたり、
Chat にバインドされたネイティブスレッドをアーカイブしたりすることはできません。リスト表示とメタデータのみの
読み取りは引き続き使用できます。生のトランスクリプトの読み取りには allowRawTranscripts が必要です。
生のアクセスが無効な場合、ネイティブ検索にはトランスクリプトのプレビューが含まれるため、
codex_threads はリスト検索も拒否します。ただし、Control UI とオペレーター CLI では、
範囲を制限したタイトルのみの検索を引き続き利用できます。名前変更、アーカイブ解除、デタッチされたフォーク、
および所有していない無関係なスレッドのアーカイブには、
allowWriteControls が必要です。どちらのオプションもロックされたバインディングを回避しません。
OpenClaw は、ソーススレッドを一覧表示しているだけの場合や保留中の Chat を表示しているだけの場合、 承認リクエストを購読したり応答したりしません。最初のターンで別の正規ハーネススレッドを 開始することで、競合するロールアウト書き込み元を作成せずに、別の Codex プロセスが 引き続きソースを所有できます。
元の CLI または VS Code のソースは、ネイティブクライアントと
OpenClaw カタログに引き続き表示されます。正規ブランチはネイティブ Codex スレッドとして保存されますが、
そのソース種別は appServer です。Codex Desktop または別のネイティブクライアントが
そのソース種別を除外する場合があるため、ブランチ自体がすべての
ネイティブ履歴ビューに表示されるとは限りません。
OpenClaw の App Server がアクティブと報告する行から、新しいブランチを開始することはできません。現在の ターンが終了するのを待って、カタログを更新してください。Codex App Server は 1 つのプロセス内で変更操作を直列化しますが、プロセス間で排他的な ランナーまたは承認所有者リースは提供しません。
保存済み / アクティビティ不明 の行では、Chat ミラーと最初のターンのスナップショットの ピン留めに、最後に終端状態として永続化されたターンまでの Codex の状態が使用されます。ソース スレッドが再開、中断、またはアーカイブされることはありません。別のプロセスに 進行中のターンがある場合、その最新の処理中の作業がブランチに含まれないことがあります。
ローカルセッションをアーカイブする
保存済みまたはアイドル状態の Gateway ローカル行で アーカイブ を選択し、そのスレッドまたはそこから
生成された子孫を他の Codex クライアントや OpenClaw ランナーが使用していないことを確認します。
OpenClaw はプロセスローカルのステータスを新たに読み取り、idle または notLoaded の場合にのみ
処理を続行し、ネイティブ Codex のアーカイブ操作を呼び出して、非アーカイブ一覧から
セッションを削除します。ネイティブ Codex は、そのスレッドから生成された子孫のアーカイブも試みます。
新たな読み取りでセッションがアクティブまたはエラー状態と報告された場合、ペアリングされた Node に 属する場合、または新しく作成された監督対象 Chat にそのソースからの保留中のブランチが 残っている間は、アーカイブを利用できません。ソースをアーカイブする前に、Chat の最初の メッセージを送信して正規ブランチを実体化してください。また、アクティブなバインディングが 対象のスレッドそのもの、またはアーカイブされていない生成済み子孫のいずれかを所有していることを OpenClaw が把握している場合も、アーカイブはブロックされます。OpenClaw は試験的な Codex 子孫クエリをすべてのページにわたって追跡します。無効な応答、 リクエストの失敗、カーソルまたはスレッドの重複、安全上限の超過が発生すると、 アーカイブは拒否されます。
読み取り、子孫の列挙、アーカイブの各リクエストは単一の条件付き操作ではないため、 その間にターンが開始される可能性があります。また、App Server のステータスは 独立したプロセス間で共有されません。したがって、確認操作が、不明なクライアントと この競合状態に対する安全境界となります。確認する前に、他のすべてのクライアントを終了するか、 それらが使用していないことを別の方法で検証してください。アーカイブされたスレッドは、Codex Desktop、Codex CLI、または所有者に承認されたネイティブスレッド管理フローで復元してください。 アーカイブを解除すると再表示されます。
codex unarchive <thread-id>ペアリングされた Node の制限を理解する
ペアリングされた Node は、バージョン管理された読み取り専用の
codex.appServer.threads.list.v1 コマンドと
codex.appServer.thread.turns.list.v1 コマンドを公開します。Gateway が受信するのは、正規化された
メタデータと、明示的にリクエストされた範囲制限付きのトランスクリプトページであり、生の App Server
エンドポイントではありません。現在の Node 呼び出し
トランスポートはリクエスト/レスポンス専用であるため、Codex ハーネスに必要な長時間存続するイベント、
承認、ストリーミングのライフサイクルを伝送できません。
このため、リモートスレッドがアイドル状態でも、リモート行は引き続き表示されますが、 続行 または アーカイブ は提供されません。継続用の Node 側ストリーミングランナーブリッジと、 アーカイブ用の安全なランナー所有権境界が実装されるまでは、そのコンピューター上の Codex を 使用してください。
メタデータと権限
カタログの行には、次の情報が含まれる場合があります。
- スレッドおよびセッションの識別子
- タイトルおよび作業ディレクトリ
- 現在のステータスおよびアクティブな待機フラグ
- 作成、更新、およびアクティビティのタイムスタンプ
- ソース、モデルプロバイダー、Codex CLI のバージョン、および Git ブランチ
カタログのプロジェクションには、トランスクリプトのプレビュー、ターン、ロールアウトパス、
Codex ホームパス、Git リモート、コミット SHA、および生の App Server エラーは含まれません。フリート集約では標準の node.invoke パスが使用されるため、
両方の Node コマンドが読み取り専用であっても、カタログへのアクセスと Control UI でのトランスクリプトの読み取りには、
Gateway の operator.write スコープが必要です。
supervision.allowRawTranscripts と supervision.allowWriteControls は、
自律エージェントおよびスタンドアロン MCP ツールを制御します。どちらもデフォルトは false です。
監督が有効な場合、生のトランスクリプトが許可されていない限り、codex_threads は
一覧およびメタデータのみの読み取り結果からトランスクリプトのプレビューとターンを除外します。
ターンを含む読み取りはフェイルクローズします。フォーク、名前変更、アーカイブ、およびアーカイブ解除には、
すべて書き込み制御が必要です。これらのオプションは、認証済みの Control UI での
トランスクリプト表示を制限せず、バインディング、ホスト、ステータス、または確認のチェックを迂回しません。
互換性ツール
公式の codex Plugin は、既存のエージェントおよびスタンドアロン MCP クライアント向けに、
リリース済みの 5 つの Supervisor ツール名を維持します。
codex_endpoint_probecodex_sessions_listcodex_session_readcodex_session_sendcodex_session_interrupt
codex_sessions_list はデフォルトでロード済みのセッションのみを対象とし、loaded_only
パラメーターはありません。include_stored: true を設定すると、Codex の状態データベースから、
アーカイブされていない保存済み行も読み取ります。オプションの max_stored_sessions 上限はデフォルトで 200 であり、
エンドポイントごとに 1〜1,000 行を受け付けます。ロード済み行には上限を適用しません。
生のトランスクリプト権限がない場合、一覧結果ではトランスクリプト由来の名前、
プレビュー、および詳細なエンドポイントエラーが省略されます。
codex_session_read には allowRawTranscripts が必要です。include_turns: true
を指定すると、さらに Codex にターンを要求します。
codex_session_send と codex_session_interrupt には、
allowWriteControls が必要です。送信では mode: "auto" | "start" | "steer" を受け付けますが、
"start" は常に拒否され、"auto" と "steer" はどちらも、
読み取り可能なアクティブターンをステアリングする場合にのみ使用できます。アイドル状態のスレッドは拒否され、Codex
Sessions を使用するよう案内されます。そこでは、続行前に完全なハーネスが承認ハンドラーとツールハンドラーをインストールします。
中断にも同様に、読み取り可能なアクティブターンが必要です。これらのツールは、
アイドル状態のソーススレッドを再開または開始しません。
openclaw doctor --fix は、廃止された codex-supervisor エントリ、そのエンドポイントおよび権限フィールド、
ならびに Plugin の許可・拒否ポリシー参照を、明示的な正規設定を上書きせずに公式の
codex Plugin へ移動します。スタンドアロンの互換性 MCP アダプターは、引き続きその
Plugin から同じ 5 つのツールをロードします。レガシーポリシーの環境変数は、その信頼済み
アダプター内でのみ適用されます。
監督設定のすべてのフィールドについては、 Codex ハーネスリファレンスを参照してください。
トラブルシューティング
セッションが表示されない： @openclaw/codex がインストールされており、Plugin と
supervision.enabled の両方が有効で、現在の Plugin 許可リストが
codex を許可しており、セッションがアーカイブされていないことを確認してください。有効化設定を変更した後は、
Gateway または Node を再起動してください。
続行が無効： マッピングされていない行がアクティブである、ペアリング済み Node に属している、 そのホストがオフラインである、または別のアクションが保留中です。Gateway ローカルの保存済み行およびアイドル行では、 安全でない同一スレッドの引き継ぎではなく、ブランチとして続行が提供されます。すでに監督対象の Chat がある行では、 Chat を開くが提供されます。
アーカイブが無効： 他のランナーが存在しないことを確認した後、保存済みまたはアクティビティ不明の行と、 Gateway ローカルのアイドル行をアーカイブできます。アクティブ、エラー、オフライン、 ペアリング済み Node、ブランチ保留中、および既知の同一バインディング所有者がいる行は、 アーカイブ操作に対して読み取り専用のままです。
アーカイブ済みセッションが消えた： これは想定された動作です。監督ページには、
アーカイブ済み項目のビューがありません。codex unarchive <thread-id> を実行するか、Codex Desktop を使用して
再度表示してください。
古い codex-supervisor 設定が残っている： openclaw doctor --fix を実行してください。Doctor は、
明示的な Codex 設定を上書きせずに、廃止された Plugin エントリと関連する Plugin ポリシー参照を
plugins.entries.codex.config.supervision に移動します。
