> ## Documentation Index > Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt > Use this file to discover all available pages before exploring further. # Codex CLI × AIHubMix 連携チュートリアル > Codex CLI で AIHubMix を利用：1 つの API キーで /model リストから GLM・Claude・Gemini・DeepSeek などを自由に切り替え。config.toml 設定、model_catalog_json モデルカタログ生成スクリプト、トラブルシューティング FAQ を収録。 [Codex CLI](https://openai.com/codex/) は OpenAI 公式のターミナル用コーディングツールです。AIHubMix に接続すれば、1 つの API キーだけでターミナルから GLM・Claude・Gemini・DeepSeek など各社のモデルを呼び出し、自由に切り替えられます（特定ベンダーに縛られません）。本記事では 2 つの方法を扱います：**基本方式**（profile + 固定の単一モデル、最短で開始）と、**カスタムモデル方式**（`model_catalog_json` カタログファイルで `/model` リストからいつでも切り替え）。 # OpenAI Codex CLI 統合 AiHubMixは、OpenAI [Codex CLI](https://github.com/openai/codex)とのシームレスな統合を提供し、コマンドライン環境で高度なAIプログラミングアシスタントを利用できるようにします。簡単な設定手順で、ターミナルから直接自然言語を使用して、さまざまなプログラミングおよびシステム操作タスクを実行できます。 使用する前に、以下のコマンドを実行してインストールまたは更新してください。 ```bash theme={null} npm install -g @openai/codex ``` ## 設定手順 ### 1. 環境変数設定 Shell設定ファイル（例：`.zshrc`または`.bashrc`）を開き、以下の環境変数を追加します。 ```bash theme={null} export OPENAI_BASE_URL="https://aihubmix.com/v1" export OPENAI_API_KEY="sk-***" # あなたのAiHubMix APIキーに置き換えてください ``` ここの`OPENAI_API_KEY`はAiHubMixの[キー](https://aihubmix.com/token)を使用する必要があります。変数名が`OPENAI_API_KEY`のままであるのは、OpenAIネイティブクライアントとの互換性を保つためです。 ### 2. 設定変更の適用 ターミナルで以下のコマンドを実行し、環境変数を有効にします。 ```bash theme={null} source ~/.zshrc # zshを使用している場合 # または source ~/.bashrc # bashを使用している場合 ``` ### 3. Codex CLIの起動 プロジェクトディレクトリに移動し、`codex`コマンドを実行します。 ```bash theme={null} cd /あなたのプロジェクトパス codex ``` ターミナルで codex コマンドを実行して起動した画面 ### 4. 自然言語でタスクを実行 これで、自然言語でCodex CLIに指示を入力できます。例： ```bash theme={null} # 入力例 AnimatedTextについて説明してください ``` Codex CLI が自然言語の指示に応答している画面 ## 高度な設定 * デフォルトモデルは`codex-mini-latest`で、これはコーディングタスク用に微調整された`o4-mini`です。`~/.codex/config.json`で変更できます。 * 現在、OpenAIのモデルのみをサポートしています。モデルリストは[Responses APIドキュメント](https://platform.openai.com/docs/api-reference/responses)で確認できます。 * `~/.codex/instructions.md`ファイルを編集することで、システムプロンプトをカスタマイズし、AIアシスタントの動作を調整できます。 ## 実用的なコマンドリファレンス ### ヘルプコマンド ```bash theme={null} codex -h ``` ### 完全なコマンドオプション ```bash theme={null} Usage $ codex [options] Options -h, --help ヘルプ情報を表示して終了 -m, --model 使用するモデルを指定 (デフォルト: codex-mini-latest) -i, --image 画像入力を含むファイルのパス -v, --view 以前保存したセッション履歴を表示 -q, --quiet 非対話モード、アシスタントの最終出力のみを表示 -a, --approval-mode 承認ポリシーを上書き: 'suggest', 'auto-edit', または 'full-auto' --auto-edit ファイル編集を自動承認; コマンドの確認は引き続きプロンプト表示 --full-auto サンドボックス環境での編集とコマンドを自動承認 --no-project-doc リポジトリ内の'codex.md'ファイルを自動的に含めない --project-doc 指定されたMarkdownファイルをコンテキストとして含める --full-stdout コマンド出力のstdout/stderrを切り詰めない 危険なオプション --dangerously-auto-approve-everything すべての確認プロンプトをスキップし、コマンドを直接実行（サンドボックス保護なし） 一時的なローカルテスト環境でのみ使用 実験的オプション -f, --full-context 「完全コンテキスト」モードで起動し、リポジトリ全体をコンテキストにロード 一度の操作で一括編集を適用 --modelパラメータとのみ互換性あり 例 $ codex "ASCIIアートを出力するPythonプログラムを書いて実行してください" $ codex -q "ビルドの問題を修正してください" ```

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

Codex はデフォルトでは `/model` リストに OpenAI 公式モデルのみを表示します。AIHubMix 上の任意のモデル（GLM、Claude、Gemini、DeepSeek、Kimi、Qwen……）をリストから直接選びたい場合は、公式がサポートする「カスタムモデル」の仕組みを利用できます。ローカルの JSON ファイル（`model_catalog_json`）で選択可能なモデルを宣言し、`[model_providers.aihubmix]` でリクエストを AIHubMix に向けます。 > 公式ドキュメント：[Advanced Configuration · OSS mode / local providers](https://developers.openai.com/codex/config-advanced) ### 2 つの接続方式 本ページ前半の「環境変数設定」は**基本方式**、本節は**カスタムモデル方式**です。違いは以下の通りなので、必要に応じて選んでください。 | | 基本方式（profile + 単一モデル） | カスタムモデル方式（本節） | | ------- | -------------------------------------- | --------------------------------------- | | 設定内容 | `config.toml` に `model = "xxx"` を固定で書く | 加えて `model_catalog_json` のカタログファイルを管理する | | モデル切り替え | 設定ファイルを変更して再起動 | `/model` リストで直接クリックして、いつでも切り替え | | 適したシーン | ある 1 つのモデルを長期固定で使う | 複数モデルを頻繁に比較 / 切り替えたい | | 複雑さ | 低 | 中 | 全体の流れはわずか 4 ステップです：**カタログファイルを生成 → `config.toml` を変更 → 環境変数を設定 → 再起動してモデルを選択**。 ### ステップ 1：モデルカタログファイルを生成する カタログファイルは `{ "models": [ ... ] }` 構造で、配列の各要素が `/model` で選択可能なモデルを 1 つ記述します。まず**固定の 1 モデル**でフィールドを説明し、その後で**上位 30 件を一括生成**するスクリプトを示します。 #### 1.1 まず形式を理解する：1 モデルを固定する 以下は**Codex で解析できることを検証済み**の最小完全カタログ（`glm-5.2` という 1 モデルのみ）です。そのまま `~/.codex/model-catalogs/custom-models.json` として保存すれば使えます。モデルを増やしたい場合は、`models` 配列に同じ構造のエントリを追加していきます。 ```json theme={null} { "models": [ { "slug": "glm-5.2", "display_name": "GLM 5.2", "description": "GLM 5.2 (via AIHubMix)", "context_window": 1000000, "max_context_window": 1000000, "supported_reasoning_levels": [ { "effort": "low", "description": "Fast responses" }, { "effort": "medium", "description": "Balanced" }, { "effort": "high", "description": "Deeper reasoning" } ], "shell_type": "shell_command", "visibility": "list", "supported_in_api": true, "priority": 0, "availability_nux": null, "upgrade": null, "base_instructions": "You are Codex, a coding agent.", "supports_reasoning_summaries": true, "support_verbosity": false, "default_verbosity": null, "apply_patch_tool_type": null, "truncation_policy": { "mode": "tokens", "limit": 10000 }, "supports_parallel_tool_calls": true, "experimental_supported_tools": [] } ] } ``` フィールド説明（通常変更するもの）： | フィールド | 役割 | API から | | --------------------------------------- | ------------------------------------------------------------ | ---------------- | | `slug` | モデル ID。Codex がリクエスト発行に使用し、接口が返す `model_id` と必ず一致させる | `model_id` | | `display_name` | `/model` リストに表示される名前 | `model_name` | | `context_window` / `max_context_window` | コンテキストウィンドウ。**省略すると非常に小さい保守的なデフォルト値に戻る**ため、接口の実際の値で記入することを推奨 | `context_length` | | `supported_reasoning_levels` | 推論レベル。モデル切り替え後も `/model` で effort を選択可能 | — | | `visibility` | `list` に設定して初めてセレクターに表示される | — | | `priority` | リストの並び順。数字が小さいほど前に表示 | — | **その他のフィールドは必須で、値も固定です**：`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` で検証済み）は厳密に解析するため、**どれか 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 モデルリスト接口](https://aihubmix.com/api/v1/models?type=llm) の上位 30 件の LLM を一括でカタログに書き込むには、以下のスクリプトを使います。これは**内蔵モデルをテンプレートとしてクローンする**ため、必須フィールド（正しい `base_instructions` を含む）が最初から完全に揃い、どの Codex バージョンでも欠けません。`curl`、`python3`、インストール済みの `codex` CLI が必要です： ```bash theme={null} mkdir -p ~/.codex/model-catalogs # 1) 内蔵モデルを 1 つテンプレートとして取得：base_instructions などすべての必須フィールドが揃っている codex debug models --bundled > /tmp/_tpl.json # 2) AIHubMix モデルリストを取得 curl -s "https://aihubmix.com/api/v1/models?type=llm" > /tmp/_aihubmix.json # 3) テンプレートをクローンしてエントリを 1 つずつ生成し、各モデル固有のフィールドのみ上書き python3 - <<'PY' > ~/.codex/model-catalogs/custom-models.json import json, sys tpl = json.load(open("/tmp/_tpl.json"))["models"][0] # 任意の内蔵モデルをテンプレートに api = json.load(open("/tmp/_aihubmix.json"))["data"] # 画像生成モデル（types に image_generation を含む）をスキップし、上位 30 件を取得 api = [m for m in api if "image_generation" not in (m.get("types") or "")][:30] out = [] for i, m in enumerate(api): e = dict(tpl) # テンプレートの全フィールドをクローン ctx = m.get("context_length") or 200000 e["slug"] = m["model_id"] # 接口の model_id と必ず一致 e["display_name"] = m.get("model_name") or m["model_id"] e["description"] = (m.get("model_name") or m["model_id"]) + " (via AIHubMix)" e["context_window"] = ctx e["max_context_window"] = ctx e["visibility"] = "list" e["supported_in_api"] = True e["priority"] = i e["availability_nux"] = None e["upgrade"] = None out.append(e) json.dump({"models": out}, sys.stdout, ensure_ascii=False, indent=2) PY ``` スクリプトは各モデル固有のフィールド（`slug`、`display_name`、`description`、`context_window` など）のみを上書きし、残りの必須フィールドはすべて内蔵テンプレートからクローンされます。これはまさに 1.1 のフィールドセットで、`base_instructions` だけが完全な公式プロンプトになっています。 > 生成されるファイルは大きめです（各エントリが完全な `base_instructions` を含むため、約 1～2 MB）が、正常な現象です。実行後は `codex debug models` で正しく解析できるか検証してください（ステップ 5 を参照）。 > スクリプト内の `image_generation` フィルター行は意図的に残しています：`type=llm` の返却にはごく少数ですが `image_generation` タグも併せ持つモデル（`gpt-image-2` など）があり、対話には適さないため、スクリプトは自動的にスキップしてから上位 30 件を取得します。 ### ステップ 2：`config.toml` を変更する `~/.codex/config.toml` を編集し、**ルートレベル**に `model_catalog_json` を追加し、`aihubmix` provider を定義します： ```toml theme={null} # ⚠️ model_catalog_json は必ずルートレベルに書き、[model_providers.*] セクション内には置かないこと model_provider = "aihubmix" model_catalog_json = "~/.codex/model-catalogs/custom-models.json" [model_providers.aihubmix] name = "Aihubmix" base_url = "https://aihubmix.com/v1" wire_api = "responses" env_key = "AIHUBMIX_API_KEY" ``` `wire_api = "responses"` が鍵で、**書き漏らしたり `chat` と書いたりすると接続できません**。新しい Codex は OpenAI の Responses API（`/v1/responses`）のみを使用します。AIHubMix はすでに Responses API にネイティブ対応しているため、`https://aihubmix.com/v1` を直接指定するだけでよく、自前で変換プロキシを立てる必要はありません。 ついでに**デフォルトモデル**と**デフォルト推論レベル**を指定したい場合（起動時にそのまま使え、毎回手動でクリックする必要がない）は、より完全なこの設定を使えます： ```toml theme={null} model = "glm-5.2" # 起動時のデフォルトモデル。カタログファイルに存在する必要あり model_provider = "aihubmix" model_catalog_json = "~/.codex/model-catalogs/custom-models.json" model_reasoning_effort = "high" # デフォルト推論レベル：minimal / low / medium / high [model_providers.aihubmix] name = "Aihubmix" base_url = "https://aihubmix.com/v1" wire_api = "responses" env_key = "AIHUBMIX_API_KEY" ``` 設定後の `config.toml` はおおよそ以下のようになります（赤枠が本ステップの重要項目：ルートレベルの `model` / `model_provider` / `model_catalog_json`、および `[model_providers.aihubmix]` セクション）： config.toml の model_catalog_json と aihubmix プロバイダ設定 ### ステップ 3：環境変数を設定する 上記 `env_key` で指定した環境変数を設定します（`=` の両側にスペースを入れないよう注意）： ```bash theme={null} export AIHUBMIX_API_KEY=sk-xxx ``` `~/.zshrc` / `~/.bashrc` に書いて永続化することを推奨します。Key は [AIHubMix コンソール](https://aihubmix.com/token) で取得してください。 ### ステップ 4：再起動してモデルを選択する Codex App / TUI を再起動してカタログファイルを有効にし、次のようにします： ```bash theme={null} codex # 対話画面で /model を入力すると、前のステップで宣言した 30 個のモデルが表示され、切り替えられる ``` `/model` を入力するとカタログで宣言した全モデルがリスト表示され、方向キーで選択、Enter で確定します： Codex の /model セレクターに表示された AIHubMix カスタムモデル一覧 モデルを選択すると、`/model` はさらに推論レベル（effort）を選ばせます。必要に応じて `low` / `medium` / `high` を選んでください。 ### ステップ 5：有効になったか検証する 1. Codex に入って `/model` を入力し、カタログで宣言したモデルが表示されることを確認し、そのうちの 1 つ（`glm-5.2` など）に切り替えます。 2. 適当な質問をして経路が通っていることを検証します。注意：**「あなたはどのモデルですか」では判断しないでください**——`base_instructions` には「You are Codex... based on GPT-5」と書かれており、すべてのモデルがこれに従って自分を GPT-5 と名乗るため、聞いても実際のモデルは見分けられません。実際に呼び出されたモデルを確認するには、[AIHubMix コンソール](https://aihubmix.com/token) の「ログ」ページでそのリクエスト記録の `model_id` を見てください。これが真実です。 切り替えに成功すると上部に `Model changed to ...` と表示され、下部のステータスバーにも現在のモデルとコンテキストウィンドウが表示されます（下図は `glm-5.2` に切り替え、ウィンドウ 258K）： glm-5.2 に切り替えた後の Codex セッションとステータスバー ## カスタムモデルのよくある質問 * **`/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](https://github.com/openai/codex/issues/19694)、[#15138](https://github.com/openai/codex/issues/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" 再接続。** 一部のネットワーク / プロキシ環境では WebSocket（WSS）が通らないため、provider セクションに `supports_websockets = false` を追加して強制的に HTTP を使わせることができます。 * **解析で `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 フィールドセットに変更すれば解決します。 ## 参考記事 * 公式ドキュメント：[Advanced Configuration](https://developers.openai.com/codex/config-advanced) ｜ [Configuration Reference](https://developers.openai.com/codex/config-reference) * 公式内蔵カタログ形式の参考：[codex-rs/models-manager/models.json](https://github.com/openai/codex/blob/main/codex-rs/models-manager/models.json) * コミュニティガイド：[Codex config.toml：6 行で任意のカスタム provider を接続](https://www.morphllm.com/codex-provider-configuration) *** 最終更新日：2026-06-25