Codex ハーネス

公式の codex plugin は、組み込みの OpenClaw ハーネスの代わりに Codex app-server を通じて埋め込み OpenAI エージェントターンを実行します。Codex は、 低レベルのエージェントセッション（ネイティブのスレッド再開、ネイティブのツール継続、 ネイティブの Compaction、app-server 実行）を管理します。OpenClaw は引き続き、チャット チャネル、セッションファイル、モデル選択、OpenClaw 動的ツール、承認、 メディア配信、および表示されるトランスクリプトのミラーを管理します。

openai/gpt-5.6-sol などの正規の OpenAI モデル参照を使用してください。従来の Codex GPT 参照は設定せず、OpenAI エージェントの認証順序は auth.order.openai に 指定してください。従来の Codex 認証プロファイル ID と従来の Codex 認証順序エントリは、 openclaw doctor --fix によって修復されます。

プロバイダー／モデルのランタイムポリシーが未設定または auto の場合、openai/* プレフィックスだけで このハーネスが選択されることはありません。OpenAI が Codex を暗黙的に選択できるのは、 作成者によるリクエストのオーバーライドがない、公式の HTTPS Platform Responses または ChatGPT Responses の 完全一致ルートに限られます。 OpenAI の暗黙的なエージェントランタイムを参照してください。 Platform と ChatGPT のどちらにルーティングされるかが判明する前に Codex が認証を管理する場合でも、OpenClaw は すべての候補ルートに Codex 互換性の宣言を要求します。ネイティブの 認証所有権だけで、このルートチェックが回避されることはありません。

OpenClaw サンドボックスが有効でない場合、OpenClaw は Codex app-server スレッドを Codex ネイティブコードモードを有効にして開始します（コードモード限定はデフォルトで無効のままです）。これにより、 ネイティブのワークスペース／コード機能を、app-server の item/tool/call ブリッジを通じてルーティングされる OpenClaw 動的ツールと併用できます。有効な OpenClaw サンドボックスまたは制限付きツールポリシーは、 実験的なサンドボックス exec-server パスを明示的に有効化しない限り、ネイティブコードモードを 完全に無効にします。

デフォルトの tools.exec.host: "auto" を使用し、OpenClaw サンドボックスが有効でない場合、 Codex はペアリング済み Node 上でコマンドを実行するための node_exec ツールと node_process ツールも受け取ります。 ネイティブシェルは Codex app-server のホストとワークスペース上に残ります （デフォルトの stdio デプロイでは Gateway ローカル）。node_exec は 名前または ID で Node を選択し、OpenClaw の Node 承認ポリシーを引き続き適用します。

この Codex ネイティブ機能は、 汎用 OpenClaw 実行向けのオプトイン QuickJS-WASI ランタイムであり、異なる exec 入力形式を使用する OpenClaw コードモードとは別のものです。モデル／プロバイダー／ランタイムの 全体的な分離については、 エージェントランタイムから確認してください。openai/gpt-5.6-sol はモデル 参照、codex はランタイム、Telegram、Discord、Slack、その他の チャネルは通信面です。

要件

• 公式の @openclaw/codex plugin がインストールされていること。設定で許可リストを使用している場合は、 plugins.allow に codex を含めてください。
• Codex app-server 0.143.0 以降。plugin は互換性のある バイナリをデフォルトで管理するため、PATH 上の codex コマンドは通常の 起動に影響しません。
• openclaw models auth login --provider openai を通じた Codex 認証、エージェントの Codex ホームにすでに存在する app-server アカウント、または明示的な Codex API キー認証プロファイル。

認証の優先順位、環境の分離、カスタム app-server コマンド、 モデル検出、および設定フィールドの完全な一覧については、 Codex ハーネスリファレンスを参照してください。

クイックスタート

公式 plugin をインストールしてから、Codex OAuth でサインインします。

openclaw plugins install @openclaw/codexopenclaw models auth login --provider openai

codex plugin を有効にし、OpenAI エージェントモデルを選択します。

{  plugins: {    entries: {      codex: {        enabled: true,      },    },  },  agents: {    defaults: {      model: "openai/gpt-5.6-sol",    },  },}

設定で plugins.allow を使用している場合は、そこに codex も追加します。

{  plugins: {    allow: ["codex"],    entries: {      codex: {        enabled: true,      },    },  },}

plugin の設定を変更した後は、Gateway を再起動してください。チャットにすでに セッションがある場合は、次のターンで現在の設定からハーネスが解決されるように、先に /new または /reset を実行してください。

Codex Desktop および CLI とスレッドを共有する

デフォルトの appServer.homeScope: "agent" は、各 OpenClaw エージェントを オペレーターのネイティブ Codex 状態から分離します。所有者が Codex Desktop および Codex CLI に表示されるものと 同じネイティブスレッドを検査、管理できるようにするには、ユーザーの Codex ホームを 明示的に有効化します。

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          appServer: {            homeScope: "user",          },        },      },    },  },}

ユーザーホームモードは、ローカルの管理対象 stdio プロセスまたは共有 Unix ソケット トランスポートをサポートします。設定されている場合は $CODEX_HOME、それ以外の場合は ~/.codex を使用し、 そのホームのネイティブ Codex 認証、設定、plugin、スレッドストアも使用します。OpenClaw は この app-server に OpenClaw 認証プロファイルを注入しません。

所有者のターンでは codex_threads ツールが使用可能になります。ネイティブスレッドの一覧表示、検索、読み取り、フォーク、名前変更、 アーカイブ、復元が可能です。OpenClaw で続行するにはスレッドをフォークします。フォークは現在の OpenClaw セッションに接続され、 ほかのネイティブ Codex クライアントからも引き続き 表示されます。アーカイブには、そのスレッドがほかの場所で閉じられていることの明示的な 確認が必要です。監督機能も有効な場合、トランスクリプトフィールドと変更操作には、 対応する supervision.allowRawTranscripts または supervision.allowWriteControls の明示的な有効化が必要です。

独立した管理対象 stdio App Server を通じて、同じスレッドを同時に再開または書き込まないでください。 Codex がライブライターを調整するのは単一の App Server 内であり、別々のプロセス間ではありません。 通常のユーザーホーム stdio セッションでは、フォークが安全に共存するための方法です。

appServer.homeScope: "user" だけではフリートカタログを制御しません。plugin が有効な間は ネイティブセッション検出が有効になります。Codex を無効にせずに OpenClaw サイドバーから削除するには、 sessionCatalog.enabled: false を設定してください。カタログは別個の監督接続を使用します。明示的な appServer 接続設定がない場合、通常のハーネスがエージェントスコープのままである一方、その接続はデフォルトで管理対象の ユーザーホーム stdio を使用します。明示的な appServer 設定は両方のパスで使用されます。通常のハーネスでも ネイティブ状態を共有する場合は、上記のように homeScope: "user" を明示的に設定してください。

Codex セッションを監督する

同じ codex plugin で、Gateway コンピューターおよび明示的に有効化されたペアリング済み Node 上の アーカイブされていない Codex セッションを一覧表示できます。保存済みまたはアイドル状態の Gateway ローカルセッションから、 保持範囲が限定された永続化済みのユーザーおよびアシスタント履歴をミラーする、モデル固定のチャットを 作成できます。その非公開バインディングは、ネイティブスナップショット、正規ブランチ、および後続のターンに 監督接続を使用しますが、通常の Codex セッションはエージェントスコープのままです。最初の正規開始では、 Codex がスナップショットのフォークに対して返すモデルとプロバイダーを正確に使用します。 その後の再開では、選択を Codex のネイティブ設定に委ねます。外側の OpenClaw モデルとフォールバックチェーンが それを置き換えることはありません。保存済みおよびアイドル状態の行は、ほかに実行中のランナーがないことを明示的に 確認した後でアーカイブできます。アクティブなソースからブランチを作成したり、アーカイブしたりすることはできませんが、既存の 監督対象チャットは引き続き開けます。ペアリング済み Node のセッションはメタデータのみのままです。

設定、ブランチ作成ルール、ペアリング済み Node の制限、メタデータ公開、およびトラブルシューティングについては、 Codex セッションを監督するを参照してください。

設定

サブスクリプション優先／API キーバックアップの順序には auth.order.openai を推奨します。 既存の従来の Codex 認証プロファイル ID と従来の Codex 認証順序は、 doctor 専用のレガシー状態です。新しい従来の Codex GPT 参照を書き込まないでください。

{  auth: {    order: {      openai: ["openai:user@example.com", "openai:api-key-backup"],    },  },}

Codex 互換の有効ルートでは、上記の両方のプロファイルが同じ Codex 実行の 候補として残ります。プロファイルの順序で選択されるのは資格情報であり、ランタイムではありません。 認証順序を変更しても、カスタム、Completions、HTTP、または リクエストでオーバーライドされたルートが Codex 互換になることはありません。

Compaction

Codex バックエンドのエージェントには compaction.model または compaction.provider を 設定しないでください。Codex はネイティブの app-server スレッド状態を通じて Compaction を実行するため、 OpenClaw は実行時にこれらのローカル要約機能のオーバーライドを無視し、 エージェントが Codex を使用する場合は openclaw doctor --fix がそれらを削除します。

Lossless は、Codex ターンの周辺での組み立て、取り込み、および 保守用のコンテキストエンジンとして引き続きサポートされます。設定には agents.defaults.compaction.provider ではなく、 plugins.slots.contextEngine: "lossless-claw" および plugins.entries.lossless-claw.config.summaryModel を使用します。Codex がアクティブなランタイムの場合、openclaw doctor --fix は 古い compaction.provider: "lossless-claw" 形式を Lossless コンテキストエンジンスロットに移行しますが、Compaction の管理は引き続きネイティブ Codex が行います。 ネイティブ app-server ハーネスは、プロンプト前の組み立てを必要とするコンテキストエンジンをサポートします。 codex-cli を含む汎用 CLI バックエンドは、そのホスト機能を提供しません。

Codex バックエンドのエージェントでは、/compact により、バインドされたスレッド上でネイティブ Codex app-server の Compaction が開始されます。OpenClaw は完了を待たず、 OpenClaw のタイムアウトを課さず、共有 app-server を再起動せず、 コンテキストエンジンや公開 OpenAI 要約機能にフォールバックしません。ネイティブ Codex スレッドの バインディングが存在しない、または古い場合、コマンドは Compaction バックエンドを暗黙的に 切り替えるのではなく、フェイルクローズします。

このページの残りでは、デプロイ形態、フェイルクローズルーティング、ガーディアン 承認ポリシー、ネイティブ Codex plugin、および Computer Use について説明します。オプションの 完全な一覧、デフォルト、列挙値、検出、環境分離、タイムアウト、および app-server トランスポートフィールドについては、 Codex ハーネスリファレンスを参照してください。

Codex ランタイムを確認する

Codex が使用されると想定しているチャットで /status を使用します。Codex バックエンドの OpenAI エージェントターンには、次のように表示されます。

ランタイム: OpenAI Codex

次に Codex app-server の状態を確認します。

/codex status/codex models

/codex status は、app-server の接続状態、アカウント、レート制限、MCP サーバー、Skills を報告します。/codex models は、ハーネスとアカウントで利用可能な Codex app-server のライブカタログを一覧表示します。/status が予想外の場合は、 トラブルシューティングを参照してください。

ルーティングとモデル選択

プロバイダー参照とランタイムポリシーは分離してください。

• 正規の OpenAI モデル選択には openai/gpt-* を使用します。プレフィックスだけで Codex が選択されることはありません。
• ランタイムが未設定または auto の場合、作成者によるリクエストのオーバーライドがない、 公式の HTTPS Platform Responses または ChatGPT Responses の完全一致ルートだけが、 Codex を暗黙的に選択できます。
• 設定でレガシー Codex GPT 参照を使用しないでください。openclaw doctor --fix を実行して、 レガシー参照と古いセッションルートの固定を修復してください。
• agentRuntime.id: "codex" は、互換性のあるルートで Codex を フェイルクローズ要件にします。互換性のない有効ルートを互換にするものではありません。
• agentRuntime.id: "openclaw" は、意図的に使用する場合に、プロバイダーまたはモデルで 組み込み OpenClaw ランタイムを有効にします。
• /codex ... は、チャットからネイティブ Codex app-server の会話を制御します。
• ACP/acpx は、独立した外部ハーネス経路です。ユーザーが ACP/acpx または外部ハーネスアダプターを要求した場合にのみ使用してください。

agents.defaults.imageModel も同じプレフィックス分離に従います。通常の OpenAI ルートには openai/gpt-* を使用し、画像理解を制限付きの Codex app-server ターンで 実行する必要がある場合にのみ codex/gpt-* を使用します。Doctor はレガシー Codex GPT 参照を openai/gpt-* に書き換えます。

デプロイパターン

基本的な Codex デプロイ

有効な公式 HTTPS ルートによって Codex を暗黙的に選択できる OpenAI モデルには、 クイックスタート設定を使用します。

{  plugins: {    entries: {      codex: {        enabled: true,      },    },  },  agents: {    defaults: {      model: "openai/gpt-5.6-sol",    },  },}

複数プロバイダーのデプロイ

Claude をデフォルトのエージェントとして維持し、名前付き Codex エージェントを追加します。

{  plugins: {    entries: {      codex: {        enabled: true,      },    },  },  agents: {    defaults: {      model: "anthropic/claude-opus-4-6",    },    list: [      {        id: "main",        default: true,        model: "anthropic/claude-opus-4-6",      },      {        id: "codex",        name: "Codex",        model: "openai/gpt-5.6-sol",      },    ],  },}

main エージェントは通常のプロバイダー経路を使用します。codex エージェントは、 有効な OpenAI ルートに互換性が維持されている場合、Codex app-server を使用します。 これをフェイルクローズ要件にする場合は、モデルスコープの明示的な agentRuntime.id: "codex" を追加してください。

フェイルクローズ Codex デプロイ

対象となる公式 HTTPS OpenAI 完全一致ルートでは、バンドル済み plugin が利用可能な場合、 Codex に解決できます。明記されたフェイルクローズルールには、 明示的なランタイムポリシーを追加します。

{  models: {    providers: {      openai: {        agentRuntime: {          id: "codex",        },      },    },  },  agents: {    defaults: {      model: "openai/gpt-5.6-sol",    },  },  plugins: {    entries: {      codex: {        enabled: true,      },    },  },}

Codex を強制した場合、有効ルートが Codex 互換として宣言されていない、 plugin が無効、app-server が古すぎる、または app-server を起動できないと、 OpenClaw は早期に失敗します。

App-server ポリシー

デフォルトでは、plugin は OpenClaw が管理する Codex バイナリをローカルで stdio トランスポートにより起動します。別の実行ファイルを意図的に実行する場合にのみ appServer.command を設定してください。WebSocket トランスポートは、 app-server がすでに別の場所で稼働している場合にのみ使用します。

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          appServer: {            transport: "websocket",            url: "ws://gateway-host:39175",            authToken: "${CODEX_APP_SERVER_TOKEN}",          },        },      },    },  },}

ローカル stdio app-server セッションのデフォルトは、信頼されたローカルオペレーターの 体制である approvalPolicy: "never"、approvalsReviewer: "user"、 sandbox: "danger-full-access" です。ローカル Codex の要件でこの 暗黙的な YOLO 体制が許可されない場合、OpenClaw は代わりに許可された Guardian 権限を選択します。セッションで OpenClaw サンドボックスが有効な場合、 OpenClaw は Codex のホスト側サンドボックスに依存せず、そのターンでは Codex ネイティブ Code Mode、ユーザー MCP サーバー、アプリベースの plugin 実行を 無効にします。代わりにシェルアクセスは、通常の exec/process ツールが利用可能な場合、 sandbox_exec や sandbox_process などの OpenClaw サンドボックス対応 動的ツールを経由します。

サンドボックスからの脱出や追加権限より前に Codex ネイティブ自動レビューを行うには、 正規化された OpenClaw exec モードを使用します。

{  tools: {    exec: {      mode: "auto",    },  },  plugins: {    entries: {      codex: {        enabled: true,      },    },  },}

Codex app-server セッションでは、tools.exec.mode: "auto" は Codex Guardian がレビューする承認に対応します。ローカル要件でこれらの値が許可される場合、 通常は approvalPolicy: "on-request"、approvalsReviewer: "auto_review"、 sandbox: "workspace-write" です。tools.exec.mode: "auto" では、 OpenClaw はレガシーで安全でない Codex の approvalPolicy: "never" または sandbox: "danger-full-access" オーバーライドを保持しません。意図的に 承認なしの Codex 体制にするには tools.exec.mode: "full" を使用してください。 レガシーの plugins.entries.codex.config.appServer.mode: "guardian" プリセットも引き続き 機能しますが、正規化された OpenClaw サーフェスは tools.exec.mode: "auto" です。

ホストの exec 承認および ACPX 権限とのモードレベルの比較については、 権限モードを参照してください。すべての app-server フィールド、認証順序、環境分離、タイムアウト動作については、 Codex ハーネスリファレンスを参照してください。

コマンドと診断

codex plugin は、OpenClaw テキストコマンドをサポートするすべてのチャンネルで、 /codex をスラッシュコマンドとして登録します。

ネイティブの実行と制御には、所有者または operator.admin Gateway クライアントが必要です。これには、スレッドの接続または再開、 ターンの送信または停止、モデル、ファストモード、権限状態の変更、 Compaction またはレビュー、接続の解除が含まれます。その他の認可済み送信者は、 状態、ヘルプ、アカウント、モデル、スレッド、MCP サーバー、Skills、接続の 読み取り専用検査コマンドを引き続き使用できます。

一般的な形式：

• /codex status は、app-server の接続状態、モデル、アカウント、レート 制限、MCP サーバー、Skills を確認します。
• /codex models は、利用可能な Codex app-server モデルを一覧表示します。
• /codex threads [filter] は、最近の Codex app-server スレッドを一覧表示します。
• /codex resume <thread-id> は、現在の OpenClaw セッションを 既存の Codex スレッドに接続します。
• /codex bind [thread-id] [--cwd <path>] [--model <model>] [--provider <provider>] は、 現在のチャットを接続します。
• /codex detach（または /codex unbind）は、現在の接続を解除します。
• /codex binding は、現在の接続について説明します。
• /codex stop はアクティブなターンを停止し、/codex steer <text> はそれを誘導します。
• /codex model <model>、/codex fast [on|off|status]、 /codex permissions [default|yolo|status] は、会話ごとの状態を変更します。
• /codex compact は、接続されたスレッドの Compaction を Codex app-server に要求します。
• /codex review は、接続されたスレッドの Codex ネイティブレビューを開始します。
• /codex diagnostics [note] は、接続されたスレッドの Codex フィードバックを 送信する前に確認を求めます。
• /codex account は、アカウントとレート制限の状態を表示します。
• /codex mcp は、Codex app-server の MCP サーバー状態を一覧表示します。
• /codex skills は、Codex app-server の Skills を一覧表示します。
• /codex plugins list、/codex plugins enable <name>、 /codex plugins disable <name> は、設定済みのネイティブ Codex plugins を管理します。
• /codex computer-use [status|install] は、Codex Computer Use を管理します。
• /codex help は、完全なコマンドツリーを一覧表示します。

ほとんどのサポート報告では、バグが発生した会話で /diagnostics [note] を実行することから始めます。これにより、Gateway 診断レポートが 1 件作成され、Codex ハーネスセッションの場合は、関連する Codex フィードバックバンドルを送信するための承認が求められます。プライバシーモデルとグループチャットでの動作については、診断のエクスポートを参照してください。Gateway 診断バンドル全体を含めず、現在接続されているスレッドの Codex フィードバックのみをアップロードしたい場合に限り、/codex diagnostics [note] を使用してください。

Codex スレッドをローカルで調査する

問題のある Codex 実行を調査する最速の方法は、多くの場合、ネイティブ Codex スレッドを直接開くことです。

codex resume <thread-id>

完了した /diagnostics の返信、/codex binding、または /codex threads [filter] からスレッド ID を取得します。

アップロードの仕組みとランタイムレベルの診断境界については、Codex ハーネスランタイムを参照してください。

認証順序

デフォルトのエージェントごとのホームでは、認証は次の順序で選択されます。

1. エージェント用に順序付けされた OpenAI 認証プロファイル。可能であれば auth.order.openai の配下に配置します。以前のレガシー Codex 認証プロファイル ID とレガシー Codex 認証順序を移行するには、openclaw doctor --fix を実行します。
2. そのエージェントの Codex ホームにある app-server の既存アカウント。
3. ローカルの stdio app-server 起動の場合のみ、app-server アカウントが存在せず、OpenAI 認証が引き続き必要なときは、CODEX_API_KEY、次に OPENAI_API_KEY。

OpenClaw が ChatGPT サブスクリプション形式の Codex 認証プロファイルを検出すると、生成される Codex 子プロセスから CODEX_API_KEY と OPENAI_API_KEY を削除します。これにより、Gateway レベルの API キーを埋め込みや OpenAI モデルの直接利用に使用できる状態を維持しながら、ネイティブ Codex app-server のターンが誤って API 経由で課金されることを防ぎます。明示的な Codex API キープロファイルとローカル stdio の環境変数キーへのフォールバックでは、継承された子プロセス環境ではなく app-server ログインを使用します。WebSocket app-server 接続には Gateway 環境変数の API キーフォールバックは渡されません。明示的な認証プロファイルまたはリモート app-server 自体のアカウントを使用してください。

サブスクリプションプロファイルが Codex の使用量上限に達した場合、Codex からリセット時刻が報告されれば OpenClaw はそれを記録し、同じ Codex 実行について、順序付けされた次の認証プロファイルを試します。リセット時刻を過ぎると、選択されている openai/gpt-* モデルや Codex ランタイムを変更することなく、サブスクリプションプロファイルが再び使用可能になります。

ネイティブ Codex Plugin が設定されている場合、OpenClaw は Plugin が所有するアプリを Codex スレッドに公開する前に、接続された app-server を介してそれらの Plugin をインストールまたは更新します。app/list は引き続きアプリ ID、アクセシビリティ、メタデータの信頼できる情報源ですが、スレッドごとの有効化判断は OpenClaw が担います。ポリシーによって一覧内のアクセス可能なアプリが許可されている場合、app/list が現在そのアプリを無効と報告していても、OpenClaw は thread/start.config.apps[appId].enabled = true を送信します。この経路では未知の ID に対するアプリのインストールを作り出しません。OpenClaw は plugin/install を持つマーケットプレイス Plugin のみを有効化し、その後インベントリを更新します。

環境の分離

ローカルの stdio app-server 起動では、OpenClaw は CODEX_HOME をエージェントごとのディレクトリに設定します。これにより、Codex の設定、認証およびアカウントファイル、Plugin のキャッシュおよびデータ、ネイティブスレッドの状態が、デフォルトではオペレーター個人の ~/.codex を読み書きしません。OpenClaw は通常のプロセス HOME を維持します。Codex 実行のサブプロセスは引き続きユーザーホームの設定とトークンを見つけることができ、Codex は共有された $HOME/.agents/skills および $HOME/.agents/plugins/marketplace.json のエントリを検出する場合があります。appServer.homeScope: "user" を使用すると、OpenClaw は代わりにネイティブユーザーの Codex ホームとその既存アカウントを使用し、OpenClaw 認証プロファイルを注入しません。

デプロイで追加の環境分離が必要な場合は、それらの変数を appServer.clearEnv に追加します。

{  plugins: {    entries: {      codex: {        enabled: true,        config: {          appServer: {            clearEnv: ["CODEX_API_KEY", "OPENAI_API_KEY"],          },        },      },    },  },}

appServer.clearEnv は、生成された Codex app-server 子プロセスにのみ影響します。OpenClaw はローカル起動の正規化中に、このリストから CODEX_HOME と HOME を削除します。CODEX_HOME は選択されたエージェントまたはユーザーのスコープを指したままになり、HOME は継承されたままになるため、サブプロセスは通常のユーザーホーム状態を使用できます。

動的ツールとウェブ検索

Codex の動的ツールは、デフォルトで searchable 読み込みを使用します。OpenClaw は、Codex ネイティブのワークスペース操作と重複する動的ツールを公開しません。 read、write、edit、apply_patch、exec、process、update_plan、 tool_call、tool_describe、tool_search、および tool_search_code が該当します。メッセージング、メディア、Cron、ブラウザー、Node、Gateway、heartbeat_respond など、残りのほとんどの OpenClaw 統合ツールは、openclaw 名前空間の Codex ツール検索を通じて利用できるため、初期モデルコンテキストを小さく保てます。

OpenClaw の computer ツールを含む、catalogMode: "direct-only" とマークされたツールは、代わりに openclaw_direct 名前空間を使用します。Codex はその名前空間を DirectModelOnly として扱うため、これらのツールはネストされたコードモードの tools.* 呼び出しを経由せず、通常スレッドとコードモード専用スレッドでモデルから直接参照可能な状態を維持します。

検索が有効で、管理対象プロバイダーが選択されていない場合、ウェブ検索はデフォルトで Codex のホスト型 web_search ツールを使用します。ネイティブのホスト型検索と OpenClaw の管理対象 web_search 動的ツールは相互排他的であり、管理対象検索がネイティブのドメイン制限を回避できないようにします。ホスト型検索が利用できない場合、明示的に無効化されている場合、または選択された管理対象プロバイダーに置き換えられている場合、OpenClaw は管理対象ツールを使用します。本番環境の app-server トラフィックはユーザー定義の web 名前空間を拒否するため、OpenClaw は Codex のスタンドアロン web.run 拡張機能を無効のままにします。tools.web.search.enabled: false は両方の経路を無効にし、ツールが無効な LLM 専用実行も同様です。Codex は "cached" を設定として扱い、制限のない app-server ターンでは実際の外部アクセスとして解決します。ネイティブの allowedDomains が設定されている場合、自動的な管理対象フォールバックはフェイルクローズし、許可リストを回避できないようにします。永続的な実効検索ポリシーの変更では、次のターンの前に紐付けられた Codex スレッドをローテーションします。一時的なターン単位の制限では、一時的な制限付きスレッドを使用し、後で再開できるように既存の紐付けを維持します。

sessions_yield とメッセージツール専用のソース返信は、ターン制御の契約であるため直接処理されます。sessions_spawn は検索可能なまま維持されるため、Codex のネイティブ spawn_agent が主要な Codex サブエージェントサーフェスとして機能します。一方、OpenClaw または ACP への明示的な委任も、openclaw 動的ツール名前空間を通じて引き続き利用できます。Heartbeat のコラボレーション指示は、ツールがまだ読み込まれていない場合、Heartbeat ターンを終了する前に heartbeat_respond を検索するよう Codex に指示します。

遅延動的ツールを検索できないカスタム Codex app-server に接続する場合、またはツールペイロード全体をデバッグする場合に限り、codexDynamicToolsLoading: "direct" を設定してください。

設定フィールド

サポートされている最上位の Codex Plugin フィールド：

サポートされている appServer フィールド：

appServer.networkProxy は Codex サンドボックスの 契約を変更するため、明示的な設定です。有効にすると、生成された 権限プロファイルが Codex 管理ネットワークを開始できるよう、OpenClaw は Codex スレッド設定に features.network_proxy.enabled と default_permissions も設定します。 デフォルトでは、OpenClaw はプロファイル本体から衝突耐性のある openclaw-network-<fingerprint> プロファイル名を生成します。安定したローカル名が 必要な場合にのみ profileName を使用してください。

{  plugins: {    entries: {      codex: {        config: {          appServer: {            sandbox: "workspace-write",            networkProxy: {              enabled: true,              domains: {                "api.openai.com": "allow",                "blocked.example.com": "deny",              },              unixSockets: {                "/tmp/proxy.sock": "allow",                "/tmp/blocked.sock": "none",              },              allowUpstreamProxy: true,              proxyUrl: "http://127.0.0.1:3128",            },          },        },      },    },  },}

通常の app-server ランタイムが danger-full-access になる場合、 networkProxy を有効にすると、生成される権限プロファイルでワークスペース形式のファイルシステムアクセスが使用されます。Codex が管理するネットワーク強制はサンドボックス化されたネットワークであるため、フルアクセスプロファイルでは送信トラフィックを保護できません。 ドメインエントリには allow または deny を使用し、Unix ソケットエントリには Codex の allow または none の値を使用します。

動的ツール呼び出しのタイムアウト

OpenClaw が所有する動的ツール呼び出しは、 appServer.requestTimeoutMs とは別に制限されます。Codex の item/tool/call リクエストでは、デフォルトで OpenClaw の 90 秒のウォッチドッグが使用されます。呼び出しごとの正の timeoutMs 引数により、そのツールの予算を延長または短縮でき、上限は 600000 ms です。 image_generate ツールは、ツール呼び出しで独自のタイムアウトが指定されていない場合は agents.defaults.imageGenerationModel.timeoutMs を使用し、それ以外の場合は画像生成用のデフォルトである 120 秒を使用します。メディア理解用の image ツールは、 tools.media.image.timeoutSeconds またはメディア用のデフォルトである 60 秒を使用します。画像理解では、このタイムアウトはリクエスト自体に適用され、それ以前の準備作業によって短縮されません。タイムアウト時、OpenClaw は対応している場合にツールのシグナルを中止し、失敗した動的ツール応答を Codex に返します。これにより、セッションを processing のまま残さずにターンを続行できます。 このウォッチドッグは外側の動的 item/tool/call 予算です。プロバイダー固有のリクエストタイムアウトは、その呼び出し内で実行され、独自のタイムアウトセマンティクスを維持します。

Codex がターンを受け入れた後、および OpenClaw がターンにスコープされた app-server リクエストに応答した後、ハーネスは Codex が現在のターンを進行させ、最終的に turn/completed でネイティブターンを完了することを期待します。app-server が appServer.turnCompletionIdleTimeoutMs の間、何も出力しない場合、OpenClaw はベストエフォートで Codex のターンを中断し、診断用タイムアウトを記録して、OpenClaw のセッションレーンを解放します。これにより、後続のチャットメッセージが停止したネイティブターンの後ろでキューに入ることを防ぎます。同じターンのほとんどの非終端通知は、Codex によってターンがまだ動作中であることが証明されるため、この短いウォッチドッグを解除します。

ツールのハンドオフでは、より長いツール後アイドル予算を使用します。具体的には、OpenClaw が item/tool/call 応答を返した後、commandExecution などのネイティブツール項目が完了した後、未加工の custom_tool_call_output 完了後、およびツール後の未加工アシスタント進行、未加工推論完了、または推論進行の後です。このガードは、設定されている場合は appServer.postToolRawAssistantCompletionIdleTimeoutMs を使用し、それ以外の場合はデフォルトで 5 分です。同じ予算によって、Codex が次の現在ターンイベントを発行する前の無音の合成時間に対する進行ウォッチドッグも延長されます。レート制限の更新など、グローバルな app-server 通知はターンアイドルの進行をリセットしません。推論完了、commentary agentMessage 完了、およびツール前の未加工推論またはアシスタント進行の後には、自動最終応答が続く可能性があるため、セッションレーンを即座に解放する代わりに、進行後の応答ガードを使用します。

最終または非 commentary の完了済み agentMessage 項目と、ツール前の未加工アシスタント完了のみが、アシスタント出力の解放を作動させます。その後 Codex が turn/completed なしで何も出力しなくなった場合、OpenClaw はベストエフォートでネイティブターンを中断し、セッションレーンを解放します。別のターン監視がこの解放競合に勝った場合でも、ネイティブリクエスト、項目、動的ツール完了のいずれもアクティブでなく、アシスタント出力の解放が最新の完了済み項目に属したままで、それ以降の項目完了がなければ、OpenClaw は完了済みの最終アシスタント項目を受け入れます。これにより、ターンを再実行せずに、完了したツール作業後の最終回答を保持できます。アシスタントの部分的な差分、古い以前の応答、および空の後続完了は対象になりません。

リプレイ可能で安全な stdio app-server の障害は、新しい app-server 試行で 1 回再試行されます。これには、アシスタント、ツール、アクティブな項目、または副作用の証拠がないターン完了アイドルタイムアウトが含まれます。安全でないタイムアウトでは、停止した app-server クライアントを破棄して OpenClaw のセッションレーンを解放し、自動的にリプレイする代わりに、古いネイティブスレッドのバインディングも消去します。完了監視のタイムアウトでは、Codex 固有のタイムアウト文言が表示されます。リプレイ可能で安全な場合は応答が不完全な可能性があることを示し、安全でない場合は再試行前に現在の状態を確認するようユーザーに伝えます。公開タイムアウト診断には、最後の app-server 通知メソッド、未加工アシスタント応答項目の ID／種類／ロール、アクティブなリクエスト／項目数、作動中の監視状態などの構造化フィールドが含まれます。最後の通知が未加工アシスタント応答項目である場合は、長さを制限したアシスタントテキストのプレビューも含まれます。未加工のプロンプトやツール内容は含まれません。

ローカルテスト用の環境変数オーバーライド

• OPENCLAW_CODEX_APP_SERVER_BIN は、 appServer.command が未設定の場合に管理対象バイナリを迂回します。
• OPENCLAW_CODEX_APP_SERVER_ARGS
• OPENCLAW_CODEX_APP_SERVER_MODE=yolo|guardian
• OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY
• OPENCLAW_CODEX_APP_SERVER_SANDBOX

OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1 は削除されました。代わりに plugins.entries.codex.config.appServer.mode: "guardian" を使用するか、1 回限りのローカルテストには OPENCLAW_CODEX_APP_SERVER_MODE=guardian を使用してください。繰り返し可能なデプロイには設定が推奨されます。これにより、Plugin の動作を Codex ハーネス設定の残りの部分と同じレビュー済みファイルに保持できるためです。

ネイティブ Codex Plugin

ネイティブ Codex Plugin のサポートでは、OpenClaw ハーネスターンと同じ Codex スレッド内で、Codex app-server 自体のアプリおよび Plugin 機能を使用します。OpenClaw は Codex Plugin を合成された codex_plugin_* OpenClaw 動的ツールに変換しません。

codexPlugins は、ネイティブ Codex ハーネスを選択したセッションにのみ影響します。 組み込みハーネスの実行、通常の OpenAI プロバイダー実行、ACP 会話バインディング、その他のハーネスには影響しません。

最小限の移行済み設定:

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

スレッドアプリ設定は、OpenClaw が Codex ハーネスセッションを確立したとき、または古い Codex スレッドバインディングを置き換えたときに計算されます。ターンごとには再計算されません。codexPlugins を変更した後は、/new、/reset を使用するか、Gateway を再起動して、今後の Codex ハーネスセッションが更新されたアプリセットで開始されるようにしてください。

移行の適格性、アプリインベントリ、破壊的アクションのポリシー、情報要求、およびネイティブ Plugin の診断については、 ネイティブ Codex Pluginを参照してください。

OpenAI 側のアプリおよび Plugin へのアクセスは、サインイン中の Codex アカウントによって制御されます。また、Business および Enterprise/Edu ワークスペースでは、ワークスペースのアプリ制御によっても管理されます。OpenAI のアカウントとワークスペース制御の概要については、 ChatGPT プランで Codex を使用する を参照してください。

Computer Use

Computer Use には専用のセットアップガイドがあります: Codex Computer Use。

要約すると、OpenClaw はデスクトップ制御アプリを同梱せず、デスクトップアクション自体も実行しません。Codex app-server を準備し、 computer-use MCP サーバーが利用可能であることを検証してから、Codex モードのターン中のネイティブ MCP ツール呼び出しを Codex に委ねます。

ランタイム境界

Codex ハーネスが変更するのは、低レベルの組み込みエージェント実行機構のみです。

• OpenClaw 動的ツールはサポートされています。Codex は OpenClaw にそれらのツールの実行を依頼するため、OpenClaw は引き続き実行経路に含まれます。
• Codex ネイティブのシェル、パッチ、MCP、ネイティブアプリツールは Codex が所有します。 OpenClaw は、サポートされているリレーを通じて選択されたネイティブイベントを監視またはブロックできますが、ネイティブツールの引数は書き換えません。
• ネイティブの Compaction は Codex が所有します。OpenClaw は、チャネル履歴、検索、/new、/reset、および将来のモデルまたはハーネス切り替えのためにトランスクリプトのミラーを保持しますが、Codex の Compaction を OpenClaw またはコンテキストエンジンの要約機能で置き換えることはありません。
• メディア生成、メディア理解、TTS、承認、メッセージングツールの出力は、引き続き対応する OpenClaw のプロバイダー／モデル設定を通じて処理されます。
• tool_result_persist は OpenClaw が所有するトランスクリプトのツール結果に適用され、Codex ネイティブのツール結果レコードには適用されません。

フックレイヤー、サポート対象の V1 サーフェス、ネイティブ権限処理、キュー制御、Codex フィードバックのアップロード機構、および Compaction の詳細については、 Codex ハーネスランタイムを参照してください。

トラブルシューティング

Codex が通常の /model プロバイダーとして表示されない: 新しい設定では想定される動作です。openai/gpt-* モデルを選択し、 plugins.entries.codex.enabled を有効にして、plugins.allow が codex を除外していないか確認してください。

OpenClaw が Codex ではなく組み込みハーネスを使用する: 有効なルートが公式の HTTPS Platform Responses または ChatGPT Responses の正確なルートであり、作成者によるリクエストオーバーライドがなく、Codex Plugin がインストールされ有効になっていることを確認してください。openai/gpt-* プレフィックスだけでは不十分です。テスト中に厳密に検証するには、プロバイダーまたはモデルの agentRuntime.id: "codex" を設定してください。Codex の強制時は、ルートまたはハーネスに互換性がない場合、フォールバックせずに失敗します。

OpenAI Codex ランタイムが API キー経路にフォールバックする: モデル、ランタイム、選択されたプロバイダー、および障害を示す、機密情報を削除した Gateway の抜粋を収集してください。影響を受ける共同作業者に、OpenClaw ホストで次の読み取り専用コマンドを実行するよう依頼してください:

(  pattern='openai/gpt-5\.[45]|openai[-]codex|agentRuntime(\.id)?|harnessRuntime|Runtime: OpenAI Codex|legacy OpenAI Codex prefix|resolveSelectedOpenAIRuntimeProvider|candidateProvider[": ]+openai|status[": ]+401|Incorrect API key|No API key|api-key path|API-key path|OAuth'   if ls /tmp/openclaw/openclaw-*.log >/dev/null 2>&1; then    grep -E -i -n "$pattern" /tmp/openclaw/openclaw-*.log 2>/dev/null || true  else    journalctl --user -u openclaw-gateway --since today --no-pager 2>/dev/null \      | grep -E -i "$pattern" || true  fi) | sed -E \    -e 's/(Authorization: Bearer )[A-Za-z0-9._~+\/-]+/\1[REDACTED]/Ig' \    -e 's/(Bearer )[A-Za-z0-9._~+\/-]+/\1[REDACTED]/Ig' \    -e 's/(api[_ -]?key[=: ]+)[^ ,}"]+/\1[REDACTED]/Ig' \    -e 's/(OPENAI_API_KEY[=: ]+)[^ ,}"]+/\1[REDACTED]/Ig' \    -e 's/sk-[A-Za-z0-9_-]{12,}/sk-[REDACTED]/g' \    -e 's/[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/[EMAIL-REDACTED]/g' \  | tail -200

有用な抜粋には通常、openai/gpt-5.6-sol または openai/gpt-5.6-luna、 Runtime: OpenAI Codex、agentRuntime.id または harnessRuntime、 candidateProvider: "openai"、および 401、Incorrect API key、または No API key の結果が含まれます。修正後の実行では、単純な OpenAI API キー障害ではなく、OpenAI OAuth 経路が示されるはずです。

従来の Codex モデル参照設定が残っている: openclaw doctor --fix を実行してください。 Doctor は従来のモデル参照を openai/* に書き換え、古いセッションおよびエージェント全体のランタイム固定を削除し、既存の認証プロファイルのオーバーライドを保持します。

app-server が拒否される: Codex app-server 0.143.0 以降を使用してください。 0.143.0-alpha.2 や 0.143.0+custom など、同一バージョンのプレリリースまたはビルドサフィックス付きバージョンは拒否されます。OpenClaw は安定版の 0.143.0 プロトコル下限を検査するためです。

/codex status に接続できない: codex Plugin が有効になっていること、許可リストが設定されている場合は plugins.allow にその Plugin が含まれていること、およびカスタムの appServer.command、url、authToken、または ヘッダーが有効であることを確認してください。

モデル検出が遅い: plugins.entries.codex.config.discovery.timeoutMs を小さくするか、検出を無効にしてください。 Codex ハーネスリファレンスを参照してください。

WebSocket トランスポートが即座に失敗する: appServer.url、 authToken、ヘッダー、およびリモートの app-server が同じ Codex app-server プロトコルバージョンを使用していることを確認してください。

ネイティブシェルまたはパッチツールが Native hook relay unavailable によってブロックされる: Codex スレッドが、OpenClaw に登録されなくなったネイティブフックリレー ID を依然として使用しようとしています。これはネイティブ Codex フックの トランスポートの問題であり、ACP バックエンド、プロバイダー、GitHub、シェルコマンドの 障害ではありません。影響を受けるチャットで /new または /reset を使用して新しいセッションを開始し、 無害なコマンドを再試行してください。一度は成功しても次のネイティブツール 呼び出しが再び失敗する場合は、/new を一時的な回避策としてのみ扱ってください。Codex app-server または OpenClaw Gateway を再起動した後、プロンプトを新しいセッションにコピーすることで、 古いスレッドを破棄し、ネイティブフックの登録を 再作成します。

Codex 以外のモデルが組み込みハーネスを使用する: プロバイダーまたは モデルランタイムポリシーによって別のハーネスにルーティングされない限り、想定どおりです。通常の OpenAI 以外の プロバイダー参照は、auto モードでも通常のプロバイダーパスを使用します。

Computer Use はインストール済みだがツールが実行されない: 新しいセッションで /codex computer-use status を確認してください。ツールが Native hook relay unavailable を報告する場合は、前述のネイティブフックリレーの復旧手順を使用してください。 Codex Computer Useを参照してください。

関連項目

• Codex ハーネスリファレンス
• Codex ハーネスランタイム
• Codex の監督
• ネイティブ Codex Plugin
• Codex Computer Use
• エージェントランタイム
• モデルプロバイダー
• OpenAI プロバイダー
• OpenAI Codex ヘルプ
• エージェントハーネス Plugin
• Plugin フック
• 診断のエクスポート
• ステータス
• テスト