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

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

設定完了の基準を、画面ではなく証拠に置きます。公式拡張を確認する、認証の owner を確認する、provider/model を明示する、小さな編集で context を確認する、diff とテストで残す。この五つを順番に進めます。

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

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

OpenAI の認証ドキュメントでは、ローカル IDE extension に ChatGPT sign-in と API key sign-in の二つがあると説明されています。OpenAI API key の利用は Platform の標準 API 料金に属し、ChatGPT workspace や cloud に依存する機能は制限される場合があります。

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

公式 Codex extension を確認する

OpenAI のCodex IDE 公式ページから Visual Studio Code のインストールリンクを開きます。Marketplace では公式ページから到達した extension と publisher を確認します。名前や icon が似ているだけの extension は、設定ファイルも secret の扱いも別物です。

インストール後は、検証しても安全な Git project を開きます。Activity Bar の Codex icon を選びます。見つからない場合は Command Palette で Codex: Open Codex Sidebar を実行します。

ここで sidebar が開けば、extension の loading は確認できました。ただし次の項目はまだ未確認です。

• どの account / workspace で認証したか
• OpenAI 内蔵経路か custom provider か
• 選択した model ID が実在するか
• 開いている code context が request に含まれたか
• 生成された変更が project の期待を満たすか

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

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

すでに別の方法で login している場合は、profile menu で現在の状態を確認し、Log out してから選び直します。通常の切り替えで ~/.codex/auth.json を空にしたり削除したりする必要はありません。CLI と IDE extension は login cache を共有するため、手動削除は原因の分からない認証問題を増やします。

API key を code、prompt、repository、issue、screenshot、log に貼らないでください。秘密情報を見せないまま、account、project、provider の名前と error text を記録すれば診断できます。

Codex Settings と VS Code Settings を分ける

公式 extension には二つの設定レイヤーがあります。

• VS Code 内での表示・操作は chatgpt.* editor settings
• model、provider、permissions 等の agent 動作は Codex config.toml

OpenAI の基本設定ページによると、CLI と IDE extension は同じ config layer を読みます。Codex sidebar の gear から Codex Settings > Open config.toml を選ぶと、対象ファイルを開けます。

個人の provider を設定する場所は通常次です。

text
~/.codex/config.toml

repository の .codex/config.toml に provider、個人 endpoint、credential の経路を保存しないでください。project が開かれただけで、開発者の request の送信先を変えるべきではありません。

Custom provider は最小構成から始める

次の例は field の関係を示す placeholder です。hostname、変数名、model ID は、利用する provider が公開している正確な値へ置き換えます。

toml
# ~/.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 と table の org_gateway が完全に一致する
• custom ID に予約済みの openai、ollama、lmstudio を使わない
• base_url は dashboard ではなく API 用の root URL である
• env_key には secret ではなく環境変数の名前を書く
• model は provider の API が返す正確な model ID である
• endpoint が実際に必要な Responses、streaming、tool call を実装している

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

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

PowerShell の現在の session なら次です。

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

Dock、Start menu、WSL、Remote SSH、dev container から起動した VS Code は、別の environment を持つことがあります。401 が出たときは、key を作り直す前に、実際の extension process が変数を受け取ったか確認します。値そのものを terminal や chat に表示する必要はありません。

OpenAI のcustom model provider 説明には、environment variable のほか、OpenAI auth、command auth、認証なしの local service も記載されています。provider の契約に合う方式を一つ選びます。

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

OpenAI-compatible という説明だけでは、Codex agent としての完全な互換性は分かりません。単純な text request が通っても、stream event、tool call、error response、model alias、reasoning metadata、web search 等で差が出る場合があります。

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

1. Base URL と wire API が provider によって明記されているか
2. credential がその model ID を利用できるか
3. normal response と stream が完了するか
4. 必要な tool call を model と endpoint が扱えるか
5. quota、billing、retention、support の owner は誰か

config.toml が parse されたことは configuration shape の証拠です。一回の応答はその request path の証拠です。すべての Codex 機能の証拠ではありません。

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

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

bash
git status --short

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

text
選択した parseConfig 関数だけを確認してください。
空文字列を既存の error type で返すようにします。
public API、他のファイル、dependency は変更しません。
提案する変更と、実行すべき既存 test を示してください。

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

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

認証 error がないこと、configured provider/model の error がないこと、回答が選択した関数の実在する名前を扱うこと、diff が許可範囲に収まること、既存 test が通ることを分離して確認します。chat が返答しただけでは code の正しさは証明できません。

エラーは最初に失敗した層へ戻す

provider が無視される、または別の config layer が勝っている場合は、Codex config.toml が反映されない時の診断で layer と call failure を分けて確認します。

最後に、secret を除いた記録を残します。VS Code と extension の version、auth method、provider ID、Base URL の hostname、model ID、発生時刻、error text、diff の範囲、test command です。次の update で挙動が変わっても、どの owner が変化したかを確認でき、設定全体を最初からやり直さずに済みます。