開発ツールの設定
ChatGPT・Codex をサードパーティー API に接続する方法:config.toml 完全設定ガイド
~/.codex/config.toml を編集して Codex・ChatGPT CLI にカスタムプロバイダーを設定。wire_api responses 必須仕様、auth.json 設定、CC Switch の活用と障害切り分けを解説します。
config.toml を編集する前の事前準備
OpenAI Codex CLI およびデスクトップツールは、コード生成やリポジトリの自律的なリファクタリングにおいて強力なエージェント機能を提供します。config.toml 内でカスタムプロバイダーを設定することにより、Codex のすべてのトラフィックを独立した API Route ゲートウェイへルーティングし、料金ページに掲載された GPT-5 系列、Claude Sonnet、DeepSeek などのモデルを利用し、呼び出しを監査できます。日付のある Claude 料金比較はブログにあります。この記事では節約率を示しません。
設定ファイルを変更する前に、API 接続で有効な API Route キーを取得し、料金ページで利用するモデルの対応状況を確認してください。公式プロバイダーの接続仕様については標準の OpenAI Chat Completions リファレンス もあわせて参照してください。
プロトコルの要点:wire_api を responses に指定すべき理由
最近の Codex リリースにおける最も重要な仕様変更は、レガシーな Chat Completions プロトコルの完全な廃止です。config.toml 内のプロバイダー定義では、wire_api = "responses" を明示する必要があります。旧来の wire_api = "chat" を指定した場合、Codex は起動時に未サポートのプロトコルエラーを出力して異常終了します。
Codex はツールの呼び出し、エージェントステップの同期、ローカル作業環境の更新のために OpenAI のステートフルな Responses API 形式に依存しています。API Route は Responses API のプロトコル変換をネイティブにサポートしているため、中継用の外付けプロキシを挟むことなくシームレスに動作します。
| 設定キー | 指定値 / 推奨値 | 技術的な役割と注意事項 |
|---|---|---|
| model_provider | "api_route" | Codex 起動時にデフォルトでアクティブにするプロバイダーセクションを指定します。 |
| base_url | "https://global.api-route.com/v1" | ゲートウェイのエンドポイント。末尾に /v1 を含め、末尾スラッシュは付与しないでください。 |
| wire_api | "responses" | 必須のプロトコル形式。現在の Codex CLI ではレガシーな "chat" は廃止されています。 |
| requires_openai_auth | true | OpenAI 互換エンドポイント向けの Bearer 認証ヘッダーを送信するよう指示します。 |
| disable_response_storage | true | サードパーティー側でのセッションログ保存を抑止するセキュリティ設定です。 |
注意点として、セキュリティ上の制約により、プロジェクトローカルの .codex/config.toml に記述されたカスタムプロバイダーは Codex によって完全に無視されます。すべての外部プロバイダーはユーザーホームディレクトリ配下のグローバル設定に記述する必要があります。
設定手順:config.toml と auth.json の編集実務
Codex の設定ファイルは OS ごとに以下のパスに格納されています:
- macOS / Linux:
~/.codex/config.tomlおよび~/.codex/auth.json - Windows:
%USERPROFILE%\.codex\config.tomlおよび%USERPROFILE%\.codex\auth.json
まずディレクトリを作成し、エディタを開く前に既存の設定をバックアップします:
mkdir -p ~/.codex
test -f ~/.codex/config.toml && cp ~/.codex/config.toml ~/.codex/config.toml.bak
nano ~/.codex/config.toml~/.codex/config.toml の内容全体を以下のカスタム設定で置き換えます:
# ~/.codex/config.toml
model_provider = "api_route"
model = "gpt-5.6-sol"
disable_response_storage = true
[model_providers.api_route]
name = "API Route"
base_url = "https://global.api-route.com/v1"
wire_api = "responses"
requires_openai_auth = true
supports_websockets = false続いて、API Route のキーを ~/.codex/auth.json に記述します。Codex はこの JSON 内の OPENAI_API_KEY を読み込みます:
{
"OPENAI_API_KEY": "sk-your-api-route-key"
}Linux や macOS 環境では、認証情報の安全を確保するためファイルアクセス権を現在のユーザーのみに制限してください:
chmod 600 ~/.codex/config.toml
chmod 600 ~/.codex/auth.jsonLinux 特有のコマンドや詳細な解説については、Codex カスタムプロバイダー設定ガイドもご参照いただけます。
GUI 管理:CC Switch デスクトップアプリによる一括導入
TOML ファイルの手動編集を避け、視覚的な UI でプロバイダーを管理したい場合は、オープンソースツール CC Switch の利用が適しています。Codex や Claude Code などの開発環境間でプロバイダーをワンクリックで切り替えられます。
- API Route にログイン後、API 接続を開き、キー、モデル、接続ノードを選択します。
- 対象アプリケーションに Codex を指定し、接続方式を CC Switch のままにします。
- ローカルで CC Switch が起動していることを確認し、「CC Switch に一括取り込み」をクリックします。
- CC Switch 側の Codex プロバイダー一覧を開き、追加された
api-routeを「使用中」に切り替えます。 - Codex を再起動すると、画面左下に
api-routeの表示が確認できます。
CC Switch は内部で前述の標準的な config.toml および auth.json を正確に生成するため、手作業によるインデントや構文エラーを防ぐことができます。
疎通確認とエラーシューティングマトリクス
設定の完了後、ターミナルで Codex の診断コマンドを実行して接続性と応答を確認します:
codex doctor
codex "Reply in one sentence: What model are you?"起動時やリクエスト送信時にエラーが発生した場合は、以下の表をもとに切り分けを行ってください:
| エラー現象 | 考えられる原因 | 確認および対処手順 |
|---|---|---|
| Unsupported wire_api error | config.toml 内で wire_api = "chat" と誤指定 | wire_api = "responses" に更新してください。最新版の Codex は chat 形式を受け付けません。 |
| 401 Unauthorized | auth.json 内のキーの記述ミスまたは無効化 | ~/.codex/auth.json のキー名が OPENAI_API_KEY になっているか確認し、正しい API キーを再設定してください。 |
| 404 Not Found | base_url のパス間違い、または /v1 の欠落 | base_url が末尾スラッシュなしの https://global.api-route.com/v1 になっているか確認してください。 |
| 設定が反映されず公式に繋がる | プロジェクトローカルの .codex にファイルを配置 | 設定をユーザーホームの ~/.codex/config.toml に移動してください。ローカル設定はブロックされます。 |
| 403 Forbidden / モデル利用不可 | 指定した model がキーの価格グループで未開放 | /v1/models エンドポイントで利用可能なモデル一覧を確認するか、API 接続でグループ権限を見直してください。 |
テスト完了後は、利用ログでトークン消費量やレイテンシの記録を照合してください。
本番移行前の確認チェックリスト
- 元設定のバックアップ確認:トラブル時に公式エンドポイントへ即座に復帰できるよう
config.toml.bakを保管しておく。 - お試し枠による検証:新規登録時に自動付与される $0.20 のテストクレジットをアカウント作成で受け取り、クイックスタートの手順で最小リクエストを試す。
- モデル名の固定指定:
model = "..."には曖昧なエイリアスではなく、gpt-5.6-solなどの明確な識別子を記載する。 - 認証ファイルの保護:
~/.codex/auth.jsonを公開リポジトリに誤ってコミットしないよう除外設定を徹底する。 - 請求ログの定期点検:大規模な開発タスク完了後は、利用ログを開いて実際の消費額とトークン数を照合する。
以上の手順を踏むことで、Codex の高度な自律コーディング機能を損なうことなく、API Route による安全かつ大幅なコスト削減を実現できます。