VS CodeでCodexを使う：APIキーと外部モデルの安全な設定

VS Code の Codex で APIキーや外部モデルを使うときは、「拡張機能」「認証」「モデルの接続先」を別々に考える必要があります。公式拡張が開いていても、指定したプロバイダーにリクエストが届いているとは限りません。また、モデルが返答できても、その修正が正しいとは限りません。

まず公式拡張とログイン中のアカウントを確認し、接続先とモデルを指定します。その後、小さな編集を依頼して、開いているコードを参照できるかを確かめます。最後に差分とテスト結果を確認すれば、設定の問題とコードの問題を分けて判断できます。

最初に「誰のキーか」を決める

同じ APIキーという呼び方でも、用途が異なります。

2026年9月1日に確認したOpenAIの認証ドキュメントでは、ローカルのIDE拡張にChatGPTログインとAPIキーログインの二つが案内されています。OpenAI APIキーを使う場合はPlatformの標準API料金が適用され、ChatGPTのワークスペースやクラウドに依存する機能は制限される場合があります。

ChatGPT の契約に含まれる利用枠と API 残高は同じものではありません。先に選択を整理したい場合は、Codex APIキーとChatGPTサブスクリプションの違いを確認してください。

公式 Codex拡張機能を確認する

OpenAI のCodex IDE 公式ページから Visual Studio Code のインストールリンクを開きます。Marketplace では公式ページから到達した拡張機能と発行元を確認します。名前やアイコンが似ているだけの拡張機能は、設定ファイルも秘密情報の扱いも別物です。

インストール後は、検証しても安全な Gitプロジェクトを開きます。アクティビティバーの Codex アイコンを選びます。見つからない場合はコマンドパレットで Codex: Open Codex Sidebar を実行します。

サイドバーが開けば、拡張機能は読み込まれています。続けて次の点を確認します。

• どのアカウント／ワークスペースで認証したか
• OpenAI 内蔵経路かカスタムプロバイダーか
• 選択したモデルID が実在するか
• 開いているコードの内容がリクエストに含まれたか
• 生成された変更がプロジェクトの要件を満たすか

ログインを切り替えるときに auth.json を消さない

未ログイン画面から ChatGPT または APIキーを選びます。OpenAI APIキーを使う場合は、自分が管理する Platform API keys から作成したキーを使います。

すでに別の方法でログインしている場合は、プロフィールメニューで現在の状態を確認し、Log out してから選び直します。通常の切り替えで ~/.codex/auth.json を空にしたり削除したりする必要はありません。CLI と IDE 拡張機能はログイン情報のキャッシュを共有するため、手動削除は原因の分からない認証問題を増やします。

APIキーをコード、指示文、リポジトリ、Issue、スクリーンショット、ログに貼らないでください。秘密情報を見せないまま、アカウント、プロジェクト、プロバイダーの名前とエラー本文を記録すれば診断できます。

Codex Settings と VS Code Settings を分ける

公式拡張機能には二つの設定レイヤーがあります。

• VS Code内での表示・操作は、chatgpt.*のエディター設定
• モデル、プロバイダー、権限などのエージェント動作は、Codexのconfig.toml

OpenAI の基本設定ページによると、CLI と IDE 拡張機能は同じ設定ファイルを読みます。Codex サイドバーの歯車アイコンから Codex Settings > Open config.toml を選ぶと、対象ファイルを開けます。

個人用のプロバイダー設定は、通常、次のファイルに保存します。

~/.codex/config.toml

個人用の接続先や認証設定は、共有リポジトリの.codex/config.tomlではなく、ユーザー設定で管理します。共有設定を変えると、同じプロジェクトを開く他の開発者の送信先にも影響する可能性があるためです。

カスタムプロバイダーは最小構成から始める

次の例は設定項目の関係を示すひな型です。ホスト名、環境変数名、モデルIDは、利用する提供元が案内する値に置き換えます。

# ~/.codex/config.toml
model = "EXACT_MODEL_ID"
model_provider = "org_gateway"

[model_providers.org_gateway]
name = "Organization gateway"
base_url = "https://gateway.example.com/v1"
env_key = "ORG_GATEWAY_API_KEY"
wire_api = "responses"

確認するポイントは次の通りです。

• model_provider と設定セクションのorg_gateway が完全に一致する
• 独自ID に予約済みの openai、ollama、lmstudio を使わない
• base_url は管理画面ではなく API 用のベースURL である
• env_key には秘密情報ではなく環境変数の名前を書く
• model はプロバイダーの API が返す正確なモデルID である
• エンドポイントが実際に必要な Responses、ストリーミング、ツール呼び出しを実装している

macOS / Linux の現在のシェルから VS Code を起動する場合は、例えば次のようにします。

export ORG_GATEWAY_API_KEY="<provider-key>"
code .

PowerShell の現在のセッションなら次です。

$env:ORG_GATEWAY_API_KEY = "<provider-key>"
code .

Dock、スタートメニュー、WSL、Remote SSH、開発コンテナから起動した VS Code は、別の実行環境を持つことがあります。401 が出たときは、キーを作り直す前に、実際の拡張機能プロセスが変数を受け取ったか確認します。値そのものをターミナルやチャットに表示する必要はありません。

OpenAI のカスタムモデルの接続設定ガイドには、環境変数のほか、OpenAIの認証、コマンドによる認証、認証なしのローカルサービスも記載されています。プロバイダーの契約に合う方式を一つ選びます。

「OpenAI互換」を機能ごとに確認する

OpenAI互換という説明だけでは、Codex エージェントとしての完全な互換性は分かりません。単純なテキスト生成リクエストが通っても、ストリーミングイベント、ツール呼び出し、エラー応答、モデルの別名、推論関連のメタデータ、Web検索等で差が出る場合があります。

大きな作業へ進む前に、次を別々に確認します。

1. Base URL と通信に使うAPI形式がプロバイダーによって明記されているか
2. その認証情報で指定したモデルIDを利用できるか
3. 通常応答とストリーミングが完了するか
4. 必要なツール呼び出しをモデルとエンドポイントが扱えるか
5. 利用枠、請求、データ保持、サポートをどの事業者が管理するか

config.tomlを読み込めても、確認できるのは設定の形式までです。応答が一度返れば、その接続条件で処理できたとは判断できますが、ツール呼び出しなど他のCodex機能は別に試す必要があります。

最初のタスクは小さく、差分で確認する

動作を理解している一つの関数を選び、開始前の状態を記録します。

git status --short

対象ファイルを開き、関数を選択して、例えば次のように範囲を限定します。

選択した parseConfig 関数だけを確認してください。
空文字列を受け取った場合は、既存のエラー型で返すように修正してください。
公開API、他のファイル、依存関係は変更しないでください。
変更案と、確認に使う既存テストを示してください。

回答後は VS Code の差分と Git の両方を確認します。

git diff -- path/to/file
git status --short

認証や指定モデルのエラーがないか、回答が選択した関数の実際の内容を踏まえているかを確認します。そのうえで、差分が依頼した範囲に収まり、既存テストが通ることを確かめます。文章が返っただけでは、コードが正しく修正されたとは判断できません。

エラーは症状ごとに確認先を分ける

プロバイダーが無視される、または別の設定ファイルが優先されている場合は、Codex config.toml が反映されない時の診断で設定の優先順位とAPI呼び出しの失敗を分けて確認します。

最後に、秘密情報を除いた設定記録を残します。VS Codeと拡張機能のバージョン、認証方法、プロバイダーID、接続先のホスト名、モデルID、エラーの発生時刻と本文、変更範囲、確認用コマンドがあれば、更新後に挙動が変わっても差を調べやすくなります。