Codex ハーネス

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

要件

• 同梱の codex Plugin が利用可能な OpenClaw。
• config で plugins.allow を使用している場合は、codex を含めます。
• Codex app-server 0.125.0 以降。同梱 Plugin はデフォルトで互換性のある Codex app-server バイナリを管理するため、PATH 上のローカル codex コマンドは通常のハーネス起動に影響しません。
• openclaw models auth login --provider openai-codex、agent の Codex ホーム内の app-server アカウント、または明示的な Codex API キー認証プロファイルを通じて Codex 認証が利用可能であること。

​

クイックスタート

openclaw models auth login --provider openai-codex

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

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

​

設定

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

​

Codex ランタイムを検証する

Runtime: OpenAI Codex

/codex status
/codex models

​

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

• Codex 経由の OpenAI agent ターンには openai/gpt-* を使用します。
• config で openai-codex/gpt-* は使用しないでください。openclaw doctor --fix を実行して、レガシー ref と古いセッションルート固定を修復します。
• agentRuntime.id: "codex" は通常の OpenAI 自動モードでは任意ですが、Codex が利用不可の場合にデプロイを fail closed させたいときに有用です。
• agentRuntime.id: "pi" は、それが意図したものである場合に、プロバイダーまたはモデルを直接 PI 動作にします。
• /codex ... はチャットからネイティブ Codex app-server 会話を制御します。
• ACP/acpx は別の外部ハーネス経路です。ユーザーが ACP/acpx または外部ハーネスアダプターを求めた場合にのみ使用します。

​

デプロイパターン

​

基本的な Codex デプロイ

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

​

混在プロバイダーデプロイ

{
  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.5",
      },
    ],
  },
}

​

Fail-closed Codex デプロイ

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

​

App-server ポリシー

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

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            mode: "guardian",
            serviceTier: "priority",
          },
        },
      },
    },
  },
}

​

コマンドと診断

• /codex status は app-server 接続、モデル、アカウント、レート制限、 MCP サーバー、および Skills を確認します。
• /codex models はライブ Codex app-server モデルを一覧表示します。
• /codex threads [filter] は最近の Codex app-server スレッドを一覧表示します。
• /codex resume <thread-id> は現在の OpenClaw セッションを既存の Codex スレッドに接続します。
• /codex compact は Codex app-server に接続中のスレッドの compact を要求します。
• /codex review は接続中のスレッドに対して Codex ネイティブレビューを開始します。
• /codex diagnostics [note] は、接続中のスレッドについて Codex フィードバックを送信する前に確認します。
• /codex account はアカウントとレート制限の状態を表示します。
• /codex mcp は Codex app-server MCP サーバーの状態を一覧表示します。
• /codex skills は Codex app-server Skills を一覧表示します。

​

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

codex resume <thread-id>

1. エージェントの順序付き OpenAI 認証プロファイル。できれば auth.order.openai 配下を使用します。既存の openai-codex:* プロファイル ID は引き続き有効です。
2. そのエージェントの Codex ホーム内にある app-server の既存アカウント。
3. ローカル stdio app-server 起動の場合のみ、app-server アカウントが存在せず OpenAI 認証が まだ必要なときに、CODEX_API_KEY、次に OPENAI_API_KEY。

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

• OPENCLAW_CODEX_APP_SERVER_BIN
• OPENCLAW_CODEX_APP_SERVER_ARGS
• OPENCLAW_CODEX_APP_SERVER_MODE=yolo|guardian
• OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY
• OPENCLAW_CODEX_APP_SERVER_SANDBOX

​

ネイティブ Codex Plugin

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

​

Computer Use

​

ランタイム境界

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

​

トラブルシューティング

​

関連

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