メインコンテンツへスキップ
Codex は OpenAI 公式のコーディングエージェントで、CLI(ターミナル)とデスクトップアプリがあり、どちらも同じ ~/.codex/config.toml を使います。AIHubMix に接続すれば、1 つの API キーだけで GLM・Claude・Gemini・DeepSeek など各社のモデルを呼び出せます(特定ベンダーに縛られません)。本記事では 2 つの方法を扱います:基本方式(固定の単一モデル、最短で開始)と、カスタムモデル方式(model_catalog_json カタログファイルで /model リストからいつでも切り替え)。

インストール

公式サイトからダウンロード(macOS 版)

https://openai.com/en/codex/

コマンドラインでインストール

基本設定

設定ファイルで設定する

  1. ~/.codex/config.toml 設定ファイルを編集し、以下の設定を追加します:
  1. env_key で指定した環境変数に AIHubMix の API キーを設定します(= の両側にスペースを入れないよう注意):
~/.zshrc / ~/.bashrc に書いて永続化することを推奨します。Key は AIHubMix コンソール で取得してください。
カスタム provider は、デフォルトでは ~/.codex/auth.json の OPENAI_API_KEY を読み込みません。キーは env_key で指定した環境変数で渡してください。そうしないとリクエストにキーが付かず、401 が返ります。
Codex 0.134.0 以降、profile = "..." と [profiles.xxx] はサポートされなくなりました。古い設定のままだと、起動時に legacy profile = "..." config is no longer supported というエラーになります。本記事の旧版に沿って設定していた場合は、この 2 つを削除し、上記の書き方に変更してください。複数の設定を使い分けたい場合は、異なる項目を ~/.codex/<名前>.config.toml に([profiles.xxx] の下ではなく、トップレベルのキーとして)書き、codex --profile <名前> で起動します。
model は AIHubMix 上の他のモデル ID に変更できます。GLM や Claude など OpenAI 以外のモデルを指定すると、Codex は Model metadata for ... not found と表示してデフォルト設定にフォールバックします。その場合は、下記のカスタムモデル方式を使ってください。

cc-switch で設定する

  1. CC-Switch を起動し、プロバイダーを追加します。
CC-Switch のプロバイダー追加画面
  1. プリセット一覧から「AiHubMix」を選択します。
CC-Switch のプリセット一覧で AiHubMix を選択
  1. 「API Key」欄にキーを入力し、「追加」をクリックして設定を保存します。
CC-Switch で API Key を入力して保存
  1. ホーム画面に戻り、プロバイダー一覧で「AiHubMix」を選んで「有効化」をクリックすれば使用できます。
CC-Switch で AiHubMix プロバイダーを有効化

Codex を使う

ターミナルで使う

  1. ターミナルを開いてプロジェクトディレクトリに移動し、codex コマンドを実行します。
  1. 必要に応じて権限を設定します。後から /permissions でいつでも変更できます。
  2. 用途に合わせて使用するモデルを選択します。下部のステータスバーに現在のモデルが表示され、/model で切り替えられます。
Codex 起動後、下部のステータスバーに現在のモデルが表示された画面
  1. 自然言語で指示を入力し、正常に応答が返ってくれば設定は完了です。
Codex CLI が自然言語の指示に応答している画面

Codex デスクトップアプリで使う

  1. Codex デスクトップアプリを開き、作業ディレクトリを選択します。
  2. 入力欄にタスクを入力し、正常に応答が返ってくれば設定は完了です。
Codex デスクトップアプリでタスクを入力し、正常に応答した画面

実用的なコマンドリファレンス

すべてのオプションは codex --help で確認できます。よく使うコマンドとオプションは以下の通りです:

Codex でカスタムモデルを使用する

Codex はデフォルトでは /model リストに OpenAI 公式モデルのみを表示します。AIHubMix 上の任意のモデル(GLM、Claude、Gemini、DeepSeek、Kimi、Qwen……)をリストから直接選びたい場合は、公式がサポートする「カスタムモデル」の仕組みを利用できます。ローカルの JSON ファイル(model_catalog_json)で選択可能なモデルを宣言し、[model_providers.aihubmix] でリクエストを AIHubMix に向けます。
公式ドキュメント:Advanced Configuration · Custom model providers

2 つの接続方式

本ページ前半の「基本設定」は基本方式、本節はカスタムモデル方式です。違いは以下の通りなので、必要に応じて選んでください。 全体の流れはわずか 4 ステップです:カタログファイルを生成 → config.toml を変更 → 環境変数を設定 → 再起動してモデルを選択。

ステップ 1:モデルカタログファイルを生成する

カタログファイルは { "models": [ ... ] } 構造で、配列の各要素が /model で選択可能なモデルを 1 つ記述します。まず固定の 1 モデルでフィールドを説明し、その後で上位 30 件を一括生成するスクリプトを示します。

1.1 まず形式を理解する:1 モデルを固定する

以下はCodex で解析できることを検証済みの最小完全カタログ(glm-5.2 という 1 モデルのみ)です。そのまま ~/.codex/model-catalogs/custom-models.json として保存すれば使えます。モデルを増やしたい場合は、models 配列に同じ構造のエントリを追加していきます。
フィールド説明(通常変更するもの):
その他のフィールドは必須で、値も固定です:base_instructions、availability_nux、upgrade、supports_reasoning_summaries、support_verbosity、default_verbosity、apply_patch_tool_type、truncation_policy、supports_parallel_tool_calls、experimental_supported_tools。新しい Codex(codex-cli 0.130.0 以降。0.162.1 でも再検証済み)は厳密に解析するため、どれか 1 つでも欠けるとカタログ全体が破棄され、内蔵カタログに戻ります。エラーは missing field base_instructions のような形で、症状としては「/model にカスタムモデルが 1 つも表示されない」となります。したがって上記の例からこれ以上フィールドを削ることはできません。
base_instructions について:これはそのモデルのシステムプロンプトです。例では一文をプレースホルダーとして使っており、モデルは正常に動作します。ネイティブの Codex に最も近いコーディング性能を得たい場合は、codex debug models --bundled 内の任意の内蔵モデルの完全な base_instructions に置き換えてください(次節の一括スクリプトはまさにこれを行っています)。
公式カタログは snake_case フィールド(display_name、supported_in_api、visibility)を使用します。次の 2 種類のエラーはいずれもカタログ全体を破棄させ、/model にモデルが表示されなくなります:必須フィールドの欠落は missing field ... を、displayName、hidden のような camelCase の旧形式や認識されない値の使用は unknown variant ... を引き起こします。本記事のフィールドセットに従えば回避できます。

1.2 上位 30 件を一括生成する

複数のエントリを手書きするとフィールドを漏らしやすいです。AIHubMix モデルリスト接口 の上位 30 件の LLM を一括でカタログに書き込むには、以下のスクリプトを使います。これは内蔵モデルをテンプレートとしてクローンするため、必須フィールド(正しい base_instructions を含む)が最初から完全に揃い、どの Codex バージョンでも欠けません。curl、python3、インストール済みの codex CLI が必要です:
スクリプトは各モデル固有のフィールド(slug、display_name、description、context_window など)のみを上書きし、推論レベルを low / medium / high に限定します。残りの必須フィールドはすべて内蔵テンプレートからクローンされます。これはまさに 1.1 のフィールドセットで、base_instructions だけが完全な公式プロンプトになっています。
生成されるファイルは大きめです(各エントリが完全な base_instructions を含むため、約 1~2 MB)が、正常な現象です。実行後は codex debug models で正しく解析できるか検証してください(ステップ 5 を参照)。
スクリプト内の image_generation フィルター行は意図的に残しています:type=llm の返却にはごく少数ですが image_generation タグも併せ持つモデル(gemini-3.1-flash-image など)があり、対話には適さないため、スクリプトは自動的にスキップしてから上位 30 件を取得します。

ステップ 2:config.toml を変更する

~/.codex/config.toml を編集し、ルートレベルに model_catalog_json を追加し、aihubmix provider を定義します:
wire_api は現在 responses のみをサポートしており(省略した場合のデフォルトも responses)、chat はサポートされなくなりました。Codex は OpenAI の Responses API(/v1/responses)のみを使用します。AIHubMix は Responses API にネイティブ対応しているため、https://aihubmix.com/v1 を直接指定するだけでよく、自前で変換プロキシを立てる必要はありません。
ついでにデフォルトモデルとデフォルト推論レベルを指定したい場合(起動時にそのまま使え、毎回手動でクリックする必要がない)は、より完全なこの設定を使えます:
model にはカタログに存在するモデルを指定します。1.1 の手書きカタログなら glm-5.2 です。1.2 のスクリプトを使った場合、カタログには API の現時点の上位 30 モデルが入り、この一覧は変わります。先に codex debug models | grep -o '"slug":"[^"]*"' で中身を確認し、その中から選んでください(本記事では claude-opus-5-5 を使用)。 設定後の config.toml はおおよそ以下のようになります(赤枠が本ステップの重要項目:ルートレベルの model / model_provider / model_catalog_json、および [model_providers.aihubmix] セクション): config.toml の model_catalog_json と aihubmix プロバイダ設定

ステップ 3:環境変数を設定する

上記 env_key で指定した環境変数を設定します(= の両側にスペースを入れないよう注意):
~/.zshrc / ~/.bashrc に書いて永続化することを推奨します。Key は AIHubMix コンソール で取得してください。

ステップ 4:再起動してモデルを選択する

Codex App / TUI を再起動してカタログファイルを有効にし、次のようにします:
/model を入力するとカタログで宣言した全モデルがリスト表示され、方向キーで選択、Enter で確定します: Codex の /model セレクターに表示された AIHubMix カスタムモデル一覧 モデルを選択すると、/model はさらに推論レベル(effort)を選ばせます。必要に応じて low / medium / high を選んでください。 claude-opus-5-5 の推論レベルを選ぶ画面

ステップ 5:有効になったか検証する

  1. Codex に入って /model を入力し、カタログで宣言したモデルが表示されることを確認し、そのうちの 1 つ(claude-opus-5-5 など)に切り替えます。
  2. 適当な質問をして経路が通っていることを検証します。注意:「あなたはどのモデルですか」では判断しないでください。base_instructions には「You are Codex… based on GPT-5」と書かれており、すべてのモデルがこれに従って自分を GPT-5 と名乗るため、聞いても実際のモデルは見分けられません。実際に呼び出されたモデルを確認するには、AIHubMix コンソール の「ログ」ページでそのリクエスト記録の model_id を見てください。これが真実です。
切り替えに成功すると上部に Model changed to ... と表示され、下部のステータスバーにも現在のモデルとコンテキストウィンドウが表示されます(下図は claude-opus-5-5 に切り替え、ウィンドウ 950K): claude-opus-5-5 に切り替えた後の Codex セッションとステータスバー

カスタムモデルのよくある質問

  • 起動時に legacy profile = "..." config is no longer supported と表示されて失敗する。 Codex 0.134.0 以降、profile = と [profiles.xxx] はサポートされなくなりました。この 2 つを削除し、前述の「基本設定」の通りに設定を書き直してください。
  • 旧スクリプトで生成したカタログを使っている。 旧スクリプトは内蔵テンプレートの code mode をオフにしていませんでした。Codex のアップデートで先頭の内蔵モデルが gpt-6 シリーズのモデルに変わったため、生成されたカタログは解析こそできるものの、リクエストに標準の tools リストが含まれません。ステップ 1 の新しいスクリプトでカタログを再生成してください。
  • /model にカスタムモデルが表示されない? 順番に確認してください:
    1. まず codex debug models を実行。missing field ...(最も多い、必須フィールドの欠落)や unknown variant ...(フィールド名 / 値の誤り)が出る場合、カタログ全体の解析に失敗して破棄されています。ステップ 1 の「内蔵テンプレートをクローンする」スクリプトで再生成すれば解決します。
    2. model_catalog_json が config.toml のルートレベルにあり、[model_providers.*] セクション内にないことを確認;
    3. JSON が snake_case の公式フィールドを使い、visibility が list であることを確認;
    4. codex debug models ですでに全モデルが見えているのに、**デスクトップ版(Desktop App)**では 1~2 個しか残らず、現在のモデルが「カスタム」と表示される場合、これはデスクトップ版の既知のバグです:ローカルカタログの上にさらに公式 slug ホワイトリストのフィルターをかけ、非公式モデルをセレクターから削除してしまいます(GitHub Issue #19694、#15138 を参照)。この場合でもモデルは実際には config.toml の model = "..." に従って正常に呼び出されており(AIHubMix のログで確認可能)、名前が表示されないだけです。正しく表示させるにはターミナルの codex CLI / TUI を使ってください。デスクトップ版は config.toml に直接 model = "使いたいモデル" を固定で書くしかなく、公式の修正を待つ必要があります。
  • カタログは「マージ」ではなく「置換」です。 model_catalog_json はモデルリスト全体を置換し、追加はしません(実測:カタログにモデルを 2 つだけ入れると、codex debug models ではその 2 つしか残らず、内蔵の gpt-5.x がすべて消えます)。両方欲しい場合は、それらをまとめてカスタムカタログに書いてください。
  • リクエストでプロトコルエラー / 接続できない。 たいていは provider の base_url または wire_api が合っていません。AIHubMix では必ず wire_api = "responses" + base_url = "https://aihubmix.com/v1" にします。Chat Completions のみ対応のサードパーティに接続する場合はローカル変換プロキシが必要ですが、AIHubMix ユーザーにこのステップは不要です。
  • “Reconnecting” が続いた後、エラーになる。 まず最後のエラー行を確認してください。401 Unauthorized は、リクエストがキーなしで送信されたことを意味します:provider セクションで env_key を設定していること、そして Codex を起動するターミナルでその環境変数が設定されていることを確認してください(新しいターミナルを開くか、source ~/.zshrc を実行)。auth.json にしか保存されていないキーは、カスタム provider では使われません。
  • 解析で missing field ...(missing field base_instructions など)が出る。 エントリに必須フィールドが欠けています。新しい Codex は厳密に解析するため、base_instructions、availability_nux、upgrade、supports_reasoning_summaries、support_verbosity、default_verbosity、apply_patch_tool_type、truncation_policy、supports_parallel_tool_calls、experimental_supported_tools などはすべて存在する必要があります。ステップ 1 の「内蔵テンプレートをクローンする」スクリプトで一括で補えます。
  • 解析で unknown variant が出る。 カタログ JSON に Codex が認識しないフィールド名や値があります(displayName/hidden などの camelCase 旧形式によく見られます)。本記事の snake_case フィールドセットに変更すれば解決します。

参考記事


最終更新日:2026-10-15