Azure OpenAIとCodexの連携設定｜config.tomlの書き方と互換の限界

OpenAIのCodexは、接続先を自社テナントのAzure OpenAIへ切り替えて動かせます。設定そのものはconfig.tomlに十数行を書くだけです。詰まるのはその先で、エンドポイントにどのパスまで含めるか、認証はキーだけなのか、CursorやCline、Difyでも同じことができるのかが判断を分けます。2026年8月17日時点の一次情報を実測し、AIコーディングツールとLLMアプリ基盤をAzure OpenAIへ向ける設定項目、互換で外れる機能、社内配布の判断基準を整理しました。

まとめ：Azure OpenAI連携で先に決める接続先と認証と互換範囲

Codexを自社のAzure OpenAIへ向ける作業は、三つの決定に還元できます。第一に接続先の書式です。v1エンドポイントならホスト名にopenaiとv1を足したパスまで書き切る必要があり、省くと404が返ります。第二が認証方式で、Codexは2026年8月17日時点でAPIキー方式のみに対応し、Microsoft Entra IDは使えません。第三が互換範囲。タブ補完のようにツール側の内蔵モデルへ固定される機能が残ります。

ツールごとの差もはっきりしています。Codex CLIとVS Code拡張は設定ファイル一枚を共有し、Clineは管理画面にAzure API Versionの欄とEntra IDのトグルを持ち、Difyはデプロイ名と基盤モデルを別々に登録させます。Cursorが差し替えられるのはチャット系のモデルだけです。Claude CodeはAzure枠の受け皿がAzure OpenAIではなくMicrosoft Foundryになります。サービス自体の位置づけはAzure OpenAI Serviceの全体像を扱った記事にまとめました。

Codexの接続先をAzure OpenAIへ向ける仕組みと前提条件の確認

Codexは接続先を差し替えられる設計で、既定のOpenAI直販ではなく任意のプロバイダ定義を読ませられます。Azure OpenAIもこの定義の一つです。エージェント本体の機能や料金はCodexそのものを解説した記事に譲り、ここでは接続条件だけを見ます。

Codexが読む設定ファイルの置き場所と環境変数という二つの入口

接続先を決める材料は二つです。ホームディレクトリ配下の~/.codex/config.tomlと、そこから参照される環境変数になります。設定ファイルに書くのは使うプロバイダ、エンドポイント、APIキーを読み出す環境変数名で、キーの実体は書きません。

設定ファイルはドキュメントやリポジトリに貼られやすく、キーを直書きすると流出経路が増えます。Microsoftの手順でも、キーを文字列としてそのまま渡せない仕様が明記されました。VS Code拡張も同じファイルを読むため、二重管理は要りません。

Windows 11でWSL2が前提になる制約とVS Code拡張の読み込み経路

動作要件は公式に明記されています。macOSは12以降、LinuxはUbuntu 20.04以降またはDebian 10以降、WindowsはWindows 11でWSL2を構成した環境が前提です。メモリは4GBが最小で8GBが推奨、Gitは2.23以降が求められます。

Windows環境で報告が多いのが、WSL2とVS Code拡張の組み合わせで出る401です。WSL内で環境変数を設定していても、拡張機能がWindowsホスト側を見に行くことがあります。公式の回避策は、ホスト側にも同じ変数を設定したうえでWSLの端末からcode .で起動する方法でした。アプリランチャーからの起動では変数を引き継げません。

モデル名ではなくデプロイ名を渡すAzure側の命名ルールと事故例

Azure OpenAIでは、APIに渡すmodelの値がモデル名ではなくデプロイ名です。デプロイ時に任意の名前を付けられるため、gpt-5-codexをcodex-devという名前でデプロイしていれば、設定に書くのは後者になります。

ここが事故の温床です。公式サンプルはモデル名がそのまま書かれているため、別名でデプロイした組織では「設定は合っているのに404が返る」状態になります。用途を表す固定名でデプロイし、中身のモデルだけ入れ替える方式が破綻しにくい構成です。どの系統をどの用途に割り当てるかはモデル一覧を用途別に整理した記事を参照してください。

config.tomlに書くmodel_providers設定とv1エンドポイント指定

書くのはトップレベルの三行と、プロバイダ定義のブロック一つです。トップレベルで使うデプロイ名とプロバイダ名、推論の強度を指定し、ブロック側で接続先と認証を定義します。CLIのコマンド体系そのものはCodex CLIの基本操作をまとめた記事に譲ります。

base_urlにopenaiとv1を含める指定と省略時に出る404の切り分け

接続先はbase_urlに書きます。v1エンドポイントの形式はhttps://リソース名.openai.azure.com/openai/v1で、ホスト名だけでは足りません。公式のトラブルシューティングも、ENOTFOUNDや404が出たときの確認先としてリソース名・ドメイン・v1の有無を挙げています。

受け付けられるホスト形式が一つではない点も知っておくと迷いが減ります。v1 APIの文書には、openai.azure.com形式に加えてservices.ai.azure.com形式も受け付けると明記されました。払い出されたエンドポイントがどちらでも、末尾のパスさえ揃えれば接続できます。日付付きの版指定の扱いはapi-versionの体系を整理した記事で個別に扱いました。

wire_apiをresponsesにする理由と既定値に任せてよい条件

プロバイダ定義には、どの通信形式でやり取りするかを示すwire_apiというキーがあります。Azure OpenAI向けの公式サンプルではresponsesが指定され、これはOpenAIのResponses APIを指します。Azure側の文書でも、Azure OpenAIモデルにはこのAPIの利用が推奨されました。

Codex側の既定値も同じ方向に寄り、明示しなくても動く構成が増えています。ただし古いバージョンが手元に残る可能性を考えると、公式サンプル通りに明示するほうが安全です。設定を減らすことより、症状が出たときにどこを疑うかが分かる状態のほうが、運用コストは下がります。

env_keyに環境変数名しか書けない仕様と401が出たときの確認順

認証はenv_keyで指定した名前の環境変数から読まれます。公式手順で使われている名前はAZURE_OPENAI_API_KEYです。ここにキーの文字列そのものは書けず、書いた場合は401または403で弾かれます。原因の切り分けは次の順で進めてください。

1. 設定ファイルのenv_keyに、キー本体ではなく環境変数名が書かれているか
2. その名前と、実際にexportした環境変数の名前が一字一句一致しているか
3. 使っているキーがそのデプロイにアクセスできる権限を持っているか
4. VS Code拡張で起きているなら、Windowsホスト側にも同じ変数が設定されているか

公式ドキュメント内でも、CLIの節ではAZURE_OPENAI_API_KEYを使い、VS Code拡張の節ではOPENAI_API_KEYをexportする例が並びます。名前はどちらでも構いません。唯一の条件は、設定ファイルに書いた名前と実際の変数名を揃えることです。

model_reasoning_effortとプロファイル切り替えの使い分け

公式サンプルにはmodel_reasoning_effort = "medium"が含まれます。値を上げれば複雑な改修の成功率は上がる一方、トークン消費と待ち時間が増えます。小さなバグ修正まで高い値で回すと、費用が積み上がる割に成果は変わりません。プロバイダ定義は複数書けるため、社内向けのAzure接続とOpenAI直販を別プロファイルで持ち、GitHub Actionsからはプロファイル名を指定して非対話モードで走らせる運用も取れます。

Cursor・Cline・DifyをAzure OpenAIへ向ける設定項目の差

Azure OpenAIに向けられるのはCodexだけではありません。ただし各ツールが求める入力欄は揃っておらず、版指定の要否や認証方式で差が出ます。ここを把握しないまま社内標準を決めると、ツールを増やすたびに同じ調査をやり直すことになります。

CursorのBYOKでAzureを選ぶ手順とタブ補完が対象外になる線引き

Cursorは自前のキーを持ち込むBYOKに対応し、公式ヘルプが挙げる対応プロバイダにAzure OpenAIが含まれます。設定画面でAzureを選び、キーとエンドポイント、デプロイ名、APIバージョンにあたる情報を入れて検証する流れです。

ただし範囲には明確な線が引かれています。公式ヘルプは、持ち込んだキーが効くのはチャットのモデルに限られ、タブ補完はCursor内蔵のモデルを使い続けると述べました。通信をすべて自社テナントに閉じ込める期待は、この設定では満たせません。エディタとしての全体像はCursorの基礎を扱った記事で確認できます。

Clineで指定するエンドポイントとAzure API Versionの入力欄

ClineはOpenAI互換エンドポイントを指定する形でAzureに接続します。公式ドキュメントのBase URLの例はリソース名を含むホスト形式で、これに加えてAzure API Versionの欄が用意されました。この欄はAzure Foundry利用時のみ必要で、非Azureのエンドポイントでは空のままにするよう案内されています。

差が出るのは認証です。Clineには管理画面にAzure Identity認証のトグルがあり、有効にすると静的なAPIキーではなくEntra IDのトークン認証で通せます。キーを配布せずに済む構成を最初から取れる点で、キー認証のみのCodexとは前提が変わります。組織単位の設定を管理者が配れる仕組みもある構造です。

Difyのモデルプロバイダーでデプロイ名と基盤モデルを二つ登録

DifyはコーディングエージェントではなくLLMアプリの構築基盤ですが、接続先をAzure OpenAIへ向ける需要は同じ文脈で出ます。Marketplaceに用意されたAzure OpenAIプラグインを入れ、設定画面で次の項目を登録します。

• Model Type：テキスト生成か埋め込みかの種別
• Deployment Name：Azure側で付けたデプロイ名
• API Endpoint URL：リソースのエンドポイント
• 認証方式とAPI Version：形式に応じて指定
• Base Model：デプロイ中身の基盤モデル

デプロイ名と基盤モデルを別々に登録させる点がDifyの特徴です。Azure側の命名を自由にしたまま、Dify内部では正しいトークン計算やパラメータ制御を効かせる設計と読めます。この二つを取り違えると、接続には成功するのに挙動が噛み合いません。

四ツールを横断して比べた必須項目とEntra ID対応の可否一覧

ここまでの実測を横に並べると、社内標準を決めるときに見るべき差が三列に収まります。2026年8月17日時点の各公式ドキュメントの記載にもとづく整理です。

この表の含意は単純です。キーを一切配らない構成を全ツールで揃えたいなら、現時点ではCodexが足を引っ張ります。逆にキー運用を許容できるなら、四つとも同じテナントに寄せられます。

Claude CodeがAzure OpenAIを指せない理由とFoundryの位置

「claude code azure openai」という組み合わせで調べる人は少なくありませんが、期待される構成はそのままの形では成立しません。理由は認証や設定ではなく、動かしているモデルが別だからです。

Claude Codeが対応するプロバイダ一覧とAzure枠の実体

公式ドキュメントが挙げる展開先は、Anthropic直販、Amazon Bedrock、Claude Platform on AWS、Google Cloudのエージェント基盤、Microsoft Foundryの5系統です。Azureに対応する枠はMicrosoft Foundryで、認証はAPIキーまたはMicrosoft Entra IDが使えます。ゲートウェイを挟む場合の変数も系統ごとに分かれ、Foundry向けはANTHROPIC_FOUNDRY_BASE_URLでした。

つまりClaude CodeにもAzureで動かす道はありますが、それはAzure OpenAIのデプロイを指すこととは別です。Claude CodeはClaudeモデルの応答形式を前提に組まれており、OpenAI系モデルの応答とは中身が噛み合いません。すでにAzure OpenAIのクォータを確保していても、同じ枠でClaude Codeは動きません。

Azure OpenAIとFoundryのどちらに寄せるかを先に決める判断

ここは言い切ります。Azure上でClaude Codeを使いたいなら、Azure OpenAIとは別にMicrosoft Foundry側でClaudeモデルの提供枠を確保するのが唯一の筋です。既存のAzure OpenAI投資の範囲でコーディングエージェントを賄うなら、選ぶのはCodexかCursorかCline。この二択を曖昧にしたまま検証を始めると、クォータ申請と社内審査を二重に回す羽目になります。両方を使うなら課金の集計軸を先に決め、ツールごとにデプロイを分けてください。ログ保持や監視まで含めた設計はAzure OpenAIのセキュリティ設計を扱った記事で整理しました。

OpenAI互換をうたう接続で実際に外れる機能と現場での回避策

「OpenAI互換」はクライアントライブラリがそのまま使えることを意味しますが、機能が完全に一致することは意味しません。どこが欠けるかを知らずに移行計画を立てると、検証の終盤で手戻りが出ます。

Responses APIとChat Completionsで割れる機能の境目

Azure OpenAIのv1では、Azure OpenAIモデルにResponses APIの利用が推奨される一方、v1のchat completions構文に対応する他社モデルへの呼び出しも通ります。CodexがResponses APIを前提とするのは、エージェント動作に要る状態管理がこちらに寄るためです。

Responses API側にはリモートのMCPサーバ連携、非同期のバックグラウンド実行、暗号化された推論アイテムといった機能が加わりました。Chat Completionsの構文で書かれた既存コードをそのまま持ち込んでも、これらは使えません。呼び出し側の書き方はAzure OpenAI APIの実装手順を扱った記事にまとめました。

互換の穴を埋めるゲートウェイの導入が割に合う組織規模の見極め

互換の差を吸収する層として、LLMゲートウェイを自前で置く選択肢があります。ここは条件を付けて言い切ります。利用者が十数人規模で、使うツールが二つ以内ならゲートウェイは過剰です。各ツールの設定を手順書化して配るほうが、構築と保守の総量は小さく収まります。

効いてくるのは、部門をまたいで数十人以上が使い、ツールが三つ以上に増え、部門別の使用量集計や上限設定が求められる段階です。設定差を吸収する層が一つあれば、モデル差し替えのたびに全端末を配り直す作業から解放されます。痛みが出る前に作れば、使われない中間層を保守し続けることになります。

社内ガバナンス下で開発ツールを配る構成の判断基準と見送る場面

技術的に接続できることと、社内に配ってよいことは別です。ここでは審査で問われる論点と、配布を見送るべき条件を具体的な形で示します。

APIキーを配らずデプロイ単位で権限を切る設計と現時点の限界

理想は、開発者にキーを配らず、Entra IDの認証で個人単位に権限を寄せる構成です。v1 APIはこの方向に整備され、トークンプロバイダを使う方式ではスコープにai.azure.comの既定値を指定し、Cognitive Services OpenAI Userのロールを割り当てる手順が示されました。ClineのAzure Identity認証も同じ枠組みです。

制約は、Codexがまだこの列に並んでいないことです。公式のトラブルシューティング表には、Entra IDのサポートは現時点で利用できないと明記されています。Codexを配るなら、キーの発行と失効、環境変数の管理、退職時の回収までを人手の運用として設計してください。この一行を読み飛ばして稟議を書くと、実装段階で前提が崩れます。

ログ保持とオプトアウト申請が開発ツール利用で問われる審査論点

審査で必ず出るのが、入力したコードがどこに残るかという問いです。Azure OpenAIには不正使用監視のためのログ保持があり、条件を満たせば申請で停止できます。開発ツールではソースコードがプロンプトに載るため、この論点は通常のチャット用途より重く扱われます。

ツール側の通信がすべて自社テナントに向くとは限らない点もあわせて確認してください。Codexには承認モードの概念があり、外部通信に承認を挟む段階と、承認を省く全権モードが分かれています。全権モードを既定にして配ると、サンドボックス外での実行を止める手段がありません。

全社配布を見送るべき条件と少人数の検証に留める判断の分かれ目

見送るべき条件は三つです。第一に、キーの発行・失効・回収を回す担当が決まっていない場合。Codexはキー認証しか選べないため、この運用が空白なら配布はできません。第二に、ログ保持の停止申請が通らない状態で機微なコードを扱う部署へ広げる場合です。第三に、承認モードの既定を全権にしないと業務が回らないという主張が現場から出る場合になります。

いずれかに当たるなら、全社配布は止めて五人程度の検証チームに留めてください。検証で見るべきは応答品質ではありません。キー運用が回るか、承認モードを絞っても生産性が保てるか、月次の消費が見積もりに収まるかの三点です。基盤設計から社内展開までを外部と組んで進めるなら、生成AI開発・AI受託開発で構成の設計と実装を請けています。

よくある質問

Azure OpenAIとCodexの連携について、設定と運用の両面で寄せられることの多い質問をまとめました。

Codex CLIとVS Code拡張で設定を分ける必要はありますか？

分ける必要はありません。VS Code拡張はCLI向けの設定ファイルをそのまま読むため、プロバイダ定義を二重に書かずに済みます。注意点は環境変数の見え方だけです。WSLを使っている場合、拡張機能がWindowsホスト側を参照することがあるため、ホスト側にも同じ名前でキーを設定し、WSLの端末からVS Codeを起動してください。

api-versionを指定しないと動かない場面はありますか？

v1エンドポイントを使い、GA範囲の機能だけを呼ぶ限りは不要です。公式にも、v1 GAではapi-versionが必須パラメータではなくなったと記載されています。日付付きの版指定が要るのは、v1に載っていない旧来のパスを叩く場合や、ツール側が古い形式しか受け付けない場合です。

Entra IDでCodexを認証させる方法はありませんか？

2026年8月17日時点で、Codex自体にEntra ID対応はありません。公式のトラブルシューティング表に、現時点では利用できないと明記されています。どうしてもキーを配りたくないなら、Entra ID認証を受け付ける中間のゲートウェイを自社で置く回避策になります。運用負荷は増えるため、利用人数が少ないうちは割に合いません。

Cursorのタブ補完もAzureのデプロイに向けられますか？

向けられません。公式ヘルプは、持ち込んだキーが効くのはチャットのモデルに限られ、タブ補完はCursor内蔵のモデルを使い続けると明記しています。補完機能の通信まで自社テナントに閉じる要件があるなら、Cursorは満たせないと判断してください。エージェント的な生成をテナント内に閉じるまでなら成立します。

Difyで埋め込みモデルもAzureに向けるにはどうしますか？

生成用とは別に、もう一度モデルを登録します。Difyのモデルプロバイダー設定はモデル種別ごとに登録する方式のため、テキスト生成のデプロイと埋め込みのデプロイをそれぞれ追加してください。登録時にはデプロイ名と基盤モデルの両方を指定します。埋め込みの次元数はモデルで変わるため、既存のベクトルストアがあるなら再作成の要否も確認してください。

関連記事

• Codex CLIとは？インストール・使い方・プロキシ設定・主要コマンドを解説：CLI側の導入とコマンド体系をまとめています
• Azure OpenAI APIの使い方｜リソース作成からPython・REST呼び出しまでの実装手順：SDKから直接呼ぶときの実装手順です
• Azure OpenAIのapi-versionとは？v1 APIへの移行とバージョン固定の判断：版指定の体系と固定方針を個別に扱っています
• Azure OpenAI Serviceのモデル一覧と選び方：どのモデルをデプロイするかの判断材料になります
• Azure OpenAIのセキュリティ設計：社内審査で問われる遮断・認証・フィルタの設定：審査で問われる設定項目を網羅しています