Codex CLIは、~/.codex/config.tomlにプロバイダ定義を数行書くだけで、接続先を自社テナントのAzure OpenAI(Microsoft Foundryのデプロイ)へ切り替えられます。つまずくのは、base_urlのパスをどこまで書くか、キーをどう渡すか、Entra IDを使えるかの3点です。本稿は2026年10月16日時点の最新版であるCodex CLI 0.163.0(macOS版)を、Azure OpenAI v1の応答を模したローカルサーバーにつなぎ、設定ごとにCodexが実際に送ったURL・認証ヘッダー・エラー文を記録しました。Azure側の仕様はMicrosoft Learnの手順ページ(2026年9月3日更新)に合わせています。
まとめ:Codex×Azure OpenAI連携で押さえる設定と認証の要点
結論から並べます。設定ファイルの書き方で迷う箇所は、Azure v1を模した模擬サーバーにCodex 0.163.0をつないで挙動を確かめました(Azure本体での疎通は対象外です)。
- base_urlは
https://リソース名.openai.azure.com/openai/v1まで書きます。Codexはこの末尾に/responsesを足して送るだけなので、/openai/v1を省くと/responsesへ送られて404になります。 modelにはデプロイ名を書きます。モデルIDと同じ名前でデプロイしておくと、Codexが内蔵するモデル情報がそのまま効きます。wire_apiに書ける値はresponsesだけです。chatは設定の読み込み段階で拒否されます。env_keyには環境変数の名前を書きます。キー本体を書くと、その文字列を変数名として探しにいき失敗します。- Microsoftの手順はEntra IDを「利用不可」としていますが、Codexには外部コマンドでBearerトークンを取得する
auth設定があり、azのトークンを渡す構成を組めます。こちらはMicrosoftの動作保証外です。 - Microsoft公式のGitHub Actions例が使う
--full-autoは、0.163.0では「unexpected argument」で終了コード2になります。--sandbox workspace-writeに置き換えます。OpenAIの非対話モードの文書も、この指定は使えなくなったと明記しています。 - 既定設定のままだと、APIキーを入れた環境変数がCodexの実行するコマンドからも読めます。
ignore_default_excludes = falseを足して遮断してください。
Codex CLIをAzure OpenAIへつなぐ前の準備
設定ファイルを書く前に、Azure側のデプロイとCodex本体の版をそろえます。ここを曖昧にすると、設定が正しくても404や性能低下の原因を切り分けられません。エージェントとしての機能や料金はCodexそのものを解説した記事に譲ります。
Foundryでのモデルのデプロイとデプロイ名の決め方
Microsoftの手順は、Foundryのモデルカタログからgpt-6-astra、gpt-6-sol、gpt-5.3-codex、gpt-5.2-codex、gpt-5.1-codex-max、gpt-5-codex、gpt-5などの推論モデルを選んでデプロイし、エンドポイントURLとAPIキーを控える流れです。同ページは、Codex CLI 0.152.1と0.153.0をgpt-6-astraで、0.155.1をgpt-6-solとgpt-6-lunaで検証済みとしています。ただし「最低要件ではなく検証済みの版」という位置づけです。どの系統を選ぶかはモデル一覧を用途別に整理した記事、国内リージョンで使えるかは東日本・西日本のモデル提供状況を確認した記事で確かめてください。
デプロイ名は、モデルIDと同じ名前にすることを勧めます。0.163.0でmodel = "gpt-6-astra"を指定すると警告は出ませんでした。一方、codex-devのような独自名や、内蔵のモデル一覧から外れたgpt-5.3-codexを指定すると、Model metadata for `codex-dev` not found. Defaulting to fallback metadata; this can degrade performance and cause issues.と表示されます。CodexはAzureに渡すmodelの値でコンテキスト長などの内蔵情報を引くため、名前が一致しないと汎用の既定値で動きます。
動作要件とCodex CLIのインストール
Microsoftの手順が挙げる前提は、Microsoft FoundryのContributor権限と、macOS 12以降、Ubuntu 20.04以降またはDebian 10以降、WSL2を構成したWindows 11、メモリ4GB以上(推奨8GB)、Git 2.23以降(任意)です。インストールはnpm install -g @openai/codexかbrew install --cask codexで行い、codex --versionで版を確かめます。最新版は2026年10月15日(UTC)公開の0.163.0です。
Windowsについては、Microsoftの手順がWSL2前提で書かれている点に注意してください。Codex本体はWindowsネイティブでも動作し、WSL2が必須なのはあくまでこの手順の前提です。ネイティブで使う場合の違いはWindows版Codexの使い方をまとめた記事で扱っています。
config.tomlの書き方:model_providersとv1エンドポイント
書くのはトップレベルの3行と、プロバイダ定義のブロック1つです。Microsoftの手順のサンプルをもとに、デプロイ名をモデルIDに合わせると次の形になります。
# ~/.codex/config.toml
model = "gpt-6-astra" # Azureのデプロイ名
model_provider = "azure"
model_reasoning_effort = "medium"
[model_providers.azure]
name = "Azure OpenAI"
base_url = "https://YOUR_RESOURCE_NAME.openai.azure.com/openai/v1"
env_key = "AZURE_OPENAI_API_KEY"
wire_api = "responses"
保存したら、env_keyに書いた名前で環境変数を作り、非対話モードで1回呼んで疎通を確かめます。
export AZURE_OPENAI_API_KEY="<Azureのキー>"
codex exec "say hi"
各キーの役割と、間違えたときに出る症状を実測でまとめました。CLIのコマンド体系そのものはCodex CLIのオプション一覧をまとめた記事に譲ります。
| キー | 書く値 | 間違えたときの症状(0.163.0) |
|---|---|---|
| model | デプロイ名 | 名前が内蔵一覧に無いと警告 |
| model_provider | 定義したプロバイダID | 既定のOpenAIへ接続される |
| base_url | …/openai/v1まで | 404を5回再試行して終了 |
| env_key | 環境変数の名前 | Missing environment variable |
| wire_api | responses | chatは読み込みエラー |
base_urlに/openai/v1まで書く理由:送信先URLの実測
Codexはbase_urlの末尾に/responsesを付けたURLへPOSTします。base_urlの書き方を3通り変えて、模擬サーバーが受け取ったパスを記録した結果が次の表です。認証はどの場合もAuthorization: Bearer キーのヘッダーで送られ、Azure固有のapi-keyヘッダーは使われませんでした。
| base_urlの末尾 | Codexが送ったパス | 結果 |
|---|---|---|
| …azure.com/openai/v1 | /openai/v1/responses | 応答を受信 |
| …azure.com/openai | /openai/responses | v1のパスにならない(模擬サーバーでは404) |
| …azure.com | /responses | 404 |
404が返ったとき、CodexはReconnecting... 1/5から5/5まで再試行し、同じリクエストを計6回送ってから終了しました。固まったように見えても、設定の誤りで待たされているだけのことがあります。ホスト名はopenai.azure.com形式のほか、v1 APIの文書が明記するservices.ai.azure.com形式も受け付けます。ただしCodex 0.163.0のソースは、base_urlにopenai.azure.などの文字列を含むかどうかで接続先をAzureと判定し、判定できたときだけサーバー側の会話圧縮(remote compaction)を有効にします。services.ai.azure.comはこの判定の対象に含まれていないため、Codexで使うならopenai.azure.com形式を選ぶのが無難です。ホスト名による挙動の違いは、本稿の模擬サーバーでは検証していません。
OpenAI側の文書にある旧形式(api-version付き)との違い
紛らわしいのは、公式の設定例が2つあることです。Microsoftの手順はv1形式ですが、OpenAIのCodexの高度な設定の文書にあるAzureの例は、base_urlを/openaiで止め、query_params = { api-version = "2025-04-01-preview" }を足す旧形式のままです。この形式でCodexが送ったパスは/openai/responses?api-version=2025-04-01-previewでした。
新しく設定するならv1形式を選んでください。v1 GAではapi-versionが必須パラメーターではなくなり、日付付きの版を追いかける運用が要りません。旧形式を残す理由があるのは、版を固定する社内規定がある場合に限られます。版指定の体系はapi-versionの体系とv1への移行を整理した記事で扱いました。
wire_apiはresponsesだけ:chatは読み込み時に拒否
0.163.0でwire_api = "chat"を書くと、Codexは起動前にError loading config.toml: `wire_api = "chat"` is no longer supported. How to fix: set `wire_api = "responses"` in your provider config.と表示して終了しました。Chat Completions形式で動いていた古い設定は、そのままでは起動すらしません。
設定リファレンスも、サポートする値はresponsesのみで省略時の既定もresponsesと定めています。実際に行を消しても接続できました。それでも明示しておくほうが、別の人が設定を読んだときに迷いません。Responses APIを直接呼ぶ書き方はAzure OpenAI APIの実装手順を扱った記事を参照してください。
再試行回数とタイムアウトの調整項目
プライベートエンドポイント経由などで応答が遅い環境では、プロバイダ定義に再試行とタイムアウトを足します。OpenAIの文書の例では次の値が使われています。
[model_providers.azure]
# 前の例のブロックに3行を足す(この見出し行は2回書かない)
request_max_retries = 4 # HTTPの再試行回数(5xx・通信エラーが対象)
stream_max_retries = 10 # 応答失敗時の再接続回数(既定5。404も対象)
stream_idle_timeout_ms = 300000 # 無応答で切るまでの時間(5分)
前の節で見た404の再試行回数を決めるのはstream_max_retries(既定5)です。request_max_retriesを0にしてもReconnecting... 1/5から5/5までの再試行は変わらず、stream_max_retries = 10にすると404のときの送信は11回に増えました。設定ミスの確認中はstream_max_retriesを1〜2に下げておくと、失敗までの待ち時間が短くなります。
401・404・環境変数エラーの切り分け
Codexが表示するメッセージと原因の対応を、実測とMicrosoftのトラブルシューティング表から一覧にしました。上から順に確認すると、原因が早く絞れます。
| 表示されたメッセージ | 原因 | 直し方 |
|---|---|---|
Missing environment variable: `AZURE_OPENAI_API_KEY` |
変数が未設定 | 同じシェルでexport |
Missing environment variable: `キーの文字列` |
env_keyにキー本体 | 変数名に戻す |
| unexpected status 404 … url: …/responses | base_urlのパス不足 | /openai/v1を付ける |
| 401 Unauthorized・403 Forbidden | キー誤り・権限不足 | キーとデプロイの権限 |
provider auth cannot be combined with env_key |
authとenv_keyを併記 | どちらか一方にする |
URLのパスが正しいのに404が続くなら、modelに書いたデプロイ名を疑ってください。Azure側に無い名前を渡しても、接続先URLは同じ形になるためです。
VS Code拡張だけで401になるときの確認
OpenAIのCodex拡張機能は、CLIと同じconfig.tomlを読みます。プロバイダ定義を二重に書く必要はありません。401が拡張機能だけで起きるなら、環境変数が拡張機能に届いていません。Microsoftの手順は、アプリランチャーから起動すると変数が引き継がれないことがあるとして、変数を設定した端末からcode .で起動するよう案内しています。WSLの場合は、Windowsホスト側にも同じ変数を設定します。
同じ手順の中で、CLIの節はAZURE_OPENAI_API_KEY、VS Code拡張の節はOPENAI_API_KEYをexportする例になっている点も見落とせません。Codexが読むのはenv_keyに書いた名前の変数だけです。設定ファイルと同じ名前でexportしてください。
Entra IDでAPIキーを配らずにCodexを認証する設定
Microsoftのトラブルシューティング表には「Entra ID support is currently not available for Codex.」と書かれています。ところがCodex側には、外部コマンドの標準出力をBearerトークンとして使う[model_providers.<id>.auth]が公式の設定項目として用意されています。Azure OpenAIのv1 APIは、Entra IDのトークン(スコープはhttps://ai.azure.com/.default)をBearerで受け付けます。この2つを組み合わせると、azコマンドのトークンをCodexに渡せます。
[model_providers.azure]
name = "Azure OpenAI (Entra ID)"
base_url = "https://YOUR_RESOURCE_NAME.openai.azure.com/openai/v1"
wire_api = "responses"
# env_key は書かない(authと併記すると読み込みエラー)
[model_providers.azure.auth]
command = "az"
args = ["account", "get-access-token", "--scope", "https://ai.azure.com/.default", "--query", "accessToken", "-o", "tsv"]
timeout_ms = 10000 # 既定は5000。azの初回応答が遅い環境向け
refresh_interval_ms = 300000 # 5分ごとに取り直す(既定値)
Codexが実際にこの設定どおり動くかは、azの代わりに固定のトークンを返すスクリプトを置いて確かめました。Codexは指定した引数のままコマンドを実行し、出力されたトークンをAuthorization: Bearerヘッダーに載せて/openai/v1/responsesへ送りました。このとき同じトークンで/openai/v1/models?client_version=0.163.0へのモデル一覧取得も試み、404でもエラーを記録しただけで本処理は続きました。env_keyと併記した設定はprovider auth cannot be combined with env_keyで起動しません。
利用者側の準備は、az loginでサインインし、Azure OpenAIリソースに対する推論用ロールを割り当ててもらうことです。Microsoftのキーレス接続ガイドは、チャット補完の用途に「Cognitive Services OpenAI User」を挙げています。--scopeの指定方法はaz account get-access-tokenのリファレンスに従っています。
採用は検証用の少人数から始めてください。今回確かめたのはCodexが送るリクエストの形までで、Azure本体へこのトークンで接続した結果ではありません。Microsoftが非対応と書いている以上、障害時にサポートへ持ち込めない前提で運用することになります。キー配布を避けたい組織では、テスト用リソースで1回疎通させてから展開範囲を決めるのが現実的な進め方です。
GitHub ActionsでCodexを動かす設定と公式サンプルの修正点
Microsoftの手順に載っているワークフローは、最後の行がcodex -p azure exec --full-auto "update CHANGELOG for next release"です。0.163.0でこの行を実行するとerror: unexpected argument '--full-auto' foundと表示され、終了コード2で止まりました。-p azureを外しても結果は同じです。OpenAIの非対話モードの文書も「--full-auto is no longer supported」と書き、--sandbox workspace-writeか、承認を自動審査に回す--approve-for-meへの置き換えを案内しています。加えて、サンプルの手順にはランナー上にconfig.tomlを置くステップが無く、そのままではAzureへの接続先を知る手段がありません。
修正版は次のとおりです。設定ファイルをジョブ内で書き出し、自動編集の許可は--sandbox workspace-writeで与えます。macOS版でこの指定で起動すると、Codexはsandbox: workspace-writeと表示して処理を進めました。Linuxのランナーではサンドボックスにunprivileged user namespaceが必要で、Ubuntu 24.04以降はAppArmorがこれを制限するため、OpenAI公式のcodex-actionと同じくsysctlで制限を外すステップを入れています。codex execは承認を求めない設定(approval: never)で動くため、作業ディレクトリ内の書き込みはこれで足ります。
jobs:
update_changelog:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Codexの設定を書き出す
run: |
mkdir -p ~/.codex
cat > ~/.codex/config.toml <<'EOF'
model = "gpt-6-astra"
model_provider = "azure"
[model_providers.azure]
name = "Azure OpenAI"
base_url = "https://YOUR_RESOURCE_NAME.openai.azure.com/openai/v1"
env_key = "AZURE_OPENAI_API_KEY"
wire_api = "responses"
[shell_environment_policy]
ignore_default_excludes = false
EOF
- name: サンドボックス用にuser namespaceの制限を外す
run: sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
- name: Update changelog via Codex
env:
AZURE_OPENAI_API_KEY: ${{ secrets.AZURE_OPENAI_KEY }}
run: |
npm install -g @openai/codex
codex exec --sandbox workspace-write "update CHANGELOG for next release"
キーはリポジトリのシークレットに置き、ステップのenvで渡します。なおOpenAIは、キーをシェルに渡す代わりにキーを預かるプロキシを立てる公式のopenai/codex-actionをGitHub Actionsで使うよう勧めています。入力responses-api-endpointの説明にはAzureの…/openai/v1/responsesが例として示されており、上のsysctlもこのアクションが自動で設定します。最後のshell_environment_policyは、次の章で説明するキー漏れ対策です。
Cursor・Cline・Dify・Claude CodeをAzureへ向ける違い
Codex以外のツールでも、接続先をAzureへ向けられます。ただし入力欄と認証方式がそろっていないので、社内標準を決める前に差を把握しておく必要があります。
Cursor・Cline・Difyの接続欄とEntra ID対応
3つのツールの公式ドキュメントを2026年10月16日に確認した内容です。
| ツール | Azureへの向け方 | Entra ID | 制約 |
|---|---|---|---|
| Cursor | Settings › ModelsでAzureにキー | 記載なし | タブ補完は対象外 |
| Cline | OpenAI CompatibleにBase URL | チェックボックスで可 | az login等の既存認証を使用 |
| Dify | Azure OpenAIプラグイン | Service Principalで可 | デプロイ名と基盤モデルを別入力 |
Cursorは公式ヘルプが「Custom API keys only work with chat models. Tab completion continues using Cursor's built-in models.」と明記しています。補完の通信まで自社テナントに閉じる要件があるなら、Cursorでは満たせません。ClineはOpenAI Compatibleプロバイダの設定に「Use Azure Identity Authentication」があり、ログイン処理は行わずaz loginなどで済ませた認証をそのまま使います。
Difyは公式プラグインの設定定義で、Deployment Name、API Base URL、API Version、Base Modelを入力させます。認証はAPI KeyとMicrosoft Entra ID (Service Principal)から選べます。API Base URLが/openai/v1で終わればAPI Versionは任意で、v1以外のURLで空欄にすると2025-04-01-previewが使われます。埋め込みモデルも使うなら、生成用とは別にもう1件登録します。
Claude CodeはAzure OpenAIではなくFoundryのClaudeを使う
Claude CodeはAzure OpenAIのデプロイを接続先にできません。Azureで使う道は、Microsoft Foundry上のClaudeモデルです。Claude Codeの公式手順は、CLAUDE_CODE_USE_FOUNDRY=1で有効化し、ANTHROPIC_FOUNDRY_RESOURCEにリソース名を入れるか、ANTHROPIC_FOUNDRY_BASE_URLにhttps://{resource}.services.ai.azure.com/anthropicを設定する方式です。
Claude CodeはEntra ID認証を公式にサポートしています。ANTHROPIC_FOUNDRY_API_KEYとANTHROPIC_FOUNDRY_AUTH_TOKENを未設定にすると、Azure SDKの既定の資格情報チェーンでEntra ID認証を行います。Azure OpenAIのクォータを確保していても、Claude Codeを使うにはFoundry側でClaudeの提供枠を別に用意してください。
社内配布の判断基準とキー漏れを防ぐ設定
接続できることと、社内に配ってよいことは別の問題です。社内審査で問われやすい2つの論点を、実測した既定値の挙動とあわせて示します。
Codexが実行するコマンドにAPIキーが見える既定値
Codexは、モデルの指示でシェルコマンドを実行します。そのコマンドに渡す環境変数を決めるのがshell_environment_policyで、文書には「ignore_default_excludes defaults to true, so Codex doesn't automatically remove variable names containing KEY, SECRET, or TOKEN.」とあります。既定では、名前にKEYを含むAZURE_OPENAI_API_KEYも子プロセスに渡るということです。
模擬サーバーからCodexにprintenv AZURE_OPENAI_API_KEY相当のコマンドを実行させると、既定設定では子プロセスから12文字のキー全体を読み取れました(記録では1文字ずつ伏字にして長さだけ出力)。次の2行を足して同じ操作をすると、出力は空になりました。
[shell_environment_policy]
ignore_default_excludes = false
既定のサンドボックスではコマンドの外部ネットワーク接続は切られていますが、読めた値はコマンドの出力としてモデルへ送られ、作業ディレクトリ内のファイルやログにも書き込めます。network_access = trueやdanger-full-accessを許可した環境では、リポジトリ内の文書やIssueに仕込まれた指示で外部へ持ち出される経路も開きます。配布用のconfig.tomlには、この設定を最初から入れておくべきです。なお送信内容を見ると、CodexはstoreをfalseにしてResponses APIを呼んでいました。応答を保存しない指定ですが、Azure側の不正使用監視によるログ保持とは別の仕組みです。ログ保持を止める条件はオプトアウト申請の条件と手順を扱った記事、ネットワークやフィルタの設定はAzure OpenAIのセキュリティ設計を扱った記事で整理しています。
全社配布を見送る条件と少人数検証で確かめること
次のどれかに当たるなら、全社配布は止めて5人程度の検証に留めてください。
- キーの発行・失効・退職時の回収を回す担当が決まっていない(authコマンドによるEntra ID認証を検証していない場合)
- 不正使用監視のログ保持を止める申請が通らないまま、機微なコードを扱う部署へ広げようとしている
danger-full-accessや、承認とサンドボックスを両方外す--dangerously-bypass-approvals-and-sandboxを既定にしないと業務が回らないと現場が主張している
検証で見るのは応答の品質ではありません。キーかトークンの運用が回るか、workspace-writeのサンドボックスで作業が止まらないか、月次の消費が見積もりに収まるかの3点です。基盤設計から社内展開までを外部と組んで進めるなら、生成AI開発・AI受託開発で構成の設計と実装を請けています。
よくある質問
Codexのconfig.tomlはどこに置きますか?
ホームディレクトリ直下の.codexフォルダに置きます(~/.codex/config.toml)。VS Code拡張も同じファイルを読みます。環境変数CODEX_HOMEを設定すると、そのフォルダのconfig.tomlが読まれます。本稿の実測では、ケースごとにCODEX_HOMEを切り替えて設定を分けました。
Azure OpenAIのapi-versionは指定が必要ですか?
base_urlを/openai/v1で終わらせる場合は不要です。Microsoftの手順も、v1 APIではapi-versionを渡す必要がない代わりにbase_urlへ/v1を含めるよう書いています。指定が要るのは、/openaiで止める旧形式を使う場合だけです。
Entra IDでCodexを認証できますか?
Microsoftの手順は2026年10月16日時点でも「利用不可」としています。ただしCodexの[model_providers.azure.auth]にaz account get-access-tokenを指定すると、キーの代わりにEntra IDのトークンを送る構成を組めます。Microsoftの動作保証外なので、テスト用リソースで疎通を確かめてから使ってください。
Codexのデスクトップアプリでも同じ設定でAzureを使えますか?
Microsoftの手順が対象にしているのは、Codex CLIとVS Code拡張の2つです。ChatGPTデスクトップアプリをAzure OpenAIへ向ける手順は、同ページに記載がありません。Azureで運用するなら、手順が公開されているCLIか拡張機能を選ぶのが確実です。
Cursorのタブ補完もAzureのデプロイに向けられますか?
向けられません。Cursorの公式ヘルプは、持ち込んだキーが効くのはチャットのモデルだけで、タブ補完はCursor内蔵のモデルを使い続けると明記しています。エディタ内の生成をすべて自社テナントに閉じる要件があるなら、CodexのVS Code拡張かClineを候補にしてください。