Codex CLI 配置 Azure OpenAI GPT-5-codex 指南：config.toml 与 AGENTS.md 实战

1. Codex CLI 接 Azure OpenAI GPT-5-codex 到底解决什么问题

Codex CLI 是 OpenAI 官方开源的终端编码代理，能在命令行里读代码、改文件、跑命令。默认它走的是 OpenAI 官方账号登录，但很多团队已经在 Azure AI Foundry 上部署了 GPT-5-codex，手里有 Endpoint 和 API Key，却不知道怎么把 Codex CLI 指过去。这就是本篇要解决的核心问题：Codex CLI 配置 Azure OpenAI GPT-5-codex，让终端代理直接吃你 Azure 上的部署，而不是再单独开一个官方订阅。

先说清楚它适合谁。第一类是有 Azure 订阅、已经在 AI Foundry 里部署了 GPT-5-codex 的团队，想把现有额度用起来；第二类是企业内网环境，要求所有模型调用走自己可控的 Endpoint；第三类是想在 CI 里跑自动化改代码、生成 changelog 的开发者。这三类人共同的需求是：一份能直接复制的config.toml，加上一份能约束模型行为的AGENTS.md。

我试过把 Codex CLI 接到 Azure 上，最容易踩的坑不是模型本身，而是三个字段：base_url的路径、env_key的写法、wire_api的选择。Azure 的 v1 Responses API 要求 base_url 里必须带/openai/v1，而且 API Key 不能直接写进配置文件，只能通过环境变量名引用。这两点搞错，请求会直接 401 或者报找不到路由。

所以下面我按「部署拿参数 → 装 CLI → 写 config.toml → 写 AGENTS.md → 实际调用验证 → 排错」的顺序走一遍，每一步都给可复制的片段。你跟着做，十分钟内应该能在终端里看到 GPT-5-codex 的回复。

需要提前说明的是，Azure 侧的模型部署、订阅权限这些属于你自己的云资源操作，本篇不展开；我们聚焦在 Codex CLI 这一侧的配置。如果你暂时没有 Azure 资源，也可以用兼容 OpenAI Responses API 的网关来练手，配置结构是一样的，把 base_url 和 Key 换掉即可。

2. 前置准备：Codex CLI 安装与 Azure 参数获取

这一节把动手前需要的东西一次性备齐，避免配到一半发现缺参数。核心检索词还是Codex CLI 配置 Azure OpenAI GPT-5-codex，我们先把「原料」摆出来。

2.1 安装 Codex CLI

Codex CLI 提供 npm 和 Homebrew 两种安装方式，选一个就行。npm 方式跨平台通用：

npm install -g @openai/codex codex --version

macOS 用户如果习惯 brew：

brew install codex codex --version

装完执行codex --version能看到版本号就说明二进制就位了。如果提示 command not found，检查一下 npm 全局 bin 目录是否在 PATH 里，这是新手最常见的第一个卡点。

2.2 从 Azure AI Foundry 拿到三个关键值

进入 Azure AI Foundry，在你的项目里从模型目录选一个支持 Responses API 的模型，比如 GPT-5-codex，完成部署后记录两个值：

Endpoint 形如https://你的资源名.openai.azure.com，API Key 是一串长字符串。第三个值是你的部署名（deployment name），它不一定等于模型名gpt-5-codex，很多人在这里翻车——config.toml 里的model字段填的应该是部署名，不是模型目录里的名字。

把这三个值记在便签上：资源名、部署名、API Key。后面 config.toml 全靠它们。

2.3 关于鉴权字段的一个硬性约束

Azure 这套走的是环境变量鉴权。config.toml 里的env_key字段必须填环境变量的名字，不能把 Key 字符串直接塞进去。也就是说你写env_key = "AZURE_OPENAI_API_KEY"，然后在 shell 里export AZURE_OPENAI_API_KEY="真实key"。这个设计是为了避免密钥落盘到配置文件里被误提交。

注意：不要把真实 API Key 写进 config.toml 或 AGENTS.md，这两个文件经常会被纳入版本管理。密钥只放环境变量或 CI 的 secrets 里。

如果你用的是团队共享的网关而不是直连 Azure，同样遵循这个结构：base_url 换成网关地址，env_key 换成你设置的环境变量名，wire_api 保持 responses。这样配置模板可以复用，切换后端只改两行。

3. 可复制配置：config.toml 与 AGENTS.md 模板

这一节是全文的核心，给出能直接粘贴的config.toml和AGENTS.md。配置文件放在~/.codex/目录下，这是 Codex CLI 默认读取的位置。

3.1 创建并写入 config.toml

先进入目录再创建文件：

mkdir -p ~/.codex cd ~/.codex nano config.toml

把下面这段完整复制进去，注意替换YOUR_RESOURCE_NAME和部署名：

model = "gpt-5-codex" # 替换为你的 Azure 部署名 model_provider = "azure" model_reasoning_effort = "high" [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"

逐字段解释一下，方便你按自己环境改：

这里最关键的是base_url结尾的/openai/v1。Azure 的 v1 Responses API 不再需要单独传 api-version，但路径必须带/v1，否则请求会打到错误的路由上。wire_api = "responses"表示走 Responses 协议，和 GPT-5-codex 的能力对齐。

3.2 设置环境变量

配置文件保存后，回到终端设置环境变量。Linux、macOS、WSL 通用：

export AZURE_OPENAI_API_KEY="你的真实APIKey"

想让它长期生效，把这行加到~/.bashrc或~/.zshrc里，然后source一下。Windows PowerShell 用$env:AZURE_OPENAI_API_KEY="..."。

3.3 写一份 AGENTS.md 约束模型行为

AGENTS.md是给 Codex 的项目级说明书。Codex 会从多个位置查找并从上到下合并：~/.codex/AGENTS.md是个人全局指导，仓库根目录的AGENTS.md是项目共享约定，子目录里的则针对具体模块。合并顺序意味着越靠近当前工作目录的规则优先级越高。

在项目根目录创建AGENTS.md，示例内容如下：

# 项目约定 ## 代码风格 - Python 使用 4 空格缩进，函数必须带类型注解 - 提交信息遵循 Conventional Commits ## 技术栈 - 后端 FastAPI，前端 React + TypeScript - 所有外部调用必须走统一的 client 封装 ## 禁止事项 - 不要修改 migrations 目录下的历史文件 - 不要引入新的第三方依赖，除非在 PR 描述里说明理由 ## 测试 - 新增函数必须补单元测试，放在 tests/ 对应目录

这份文件的作用是让模型在改代码时遵守你的团队规范，而不是自由发挥。比如你写了「不要引入新依赖」，Codex 在生成代码时就会优先用现有库。全局的~/.codex/AGENTS.md可以放个人偏好，比如「回复用中文」「解释尽量简短」。

提示：AGENTS.md 是纯文本约定，不是强制约束，模型偶尔会忽略。关键规则建议同时写进 CI 检查，双保险。

4. 验证请求：跑一次真实调用确认配置生效

配置写完不验证等于没配。这一节我们实际跑一次，确认 GPT-5-codex 真的被调起来了。

4.1 命令行直接调用

在终端执行：

codex

如果配置正确，你会看到它不再要求登录，直接进入交互界面。这时输入一个简单任务，比如：

帮我写一个 Python 函数，读取当前目录下所有 .log 文件并统计行数

观察返回。如果模型开始输出代码并解释，说明config.toml的 provider 段被正确加载，环境变量也读到了。这一步能过，基本链路就通了。

4.2 用 exec 模式做非交互验证

想更明确地验证，用 exec 子命令跑一次性任务：

codex -p azure exec --full-auto "打印当前目录的文件数量"

-p azure指定使用 azure 这个 provider，exec表示非交互执行，--full-auto允许它自动执行操作。如果返回了文件数量，说明整条链路——配置读取、鉴权、请求、响应——全部打通。

4.3 在 CI 里复用同一套配置

Codex 也能作为 CI 管道的一部分。把 API Key 存到仓库 secrets 里，比如命名为AZURE_OPENAI_KEY，然后加一个 job：

jobs: update_changelog: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Update changelog via Codex run: | npm install -g @openai/codex export AZURE_OPENAI_API_KEY="${{ secrets.AZURE_OPENAI_KEY }}" codex -p azure exec --full-auto "update CHANGELOG for next release"

注意 CI 环境里没有你本地的~/.codex/config.toml，所以要么在 job 里生成一份，要么把配置提交到仓库并用环境变量覆盖敏感字段。推荐后者配合 secrets，避免密钥泄露。

4.4 成功结果长什么样

一次成功的调用，终端会先打印它准备执行的动作，然后给出结果。如果任务涉及改文件，它会列出 diff 让你确认（除非加了--full-auto）。看到结构化的输出和正确的文件统计，就说明Codex CLI 配置 Azure OpenAI GPT-5-codex这件事完成了。整个过程不需要登录官方账号，所有请求都打到你自己的 Azure Endpoint 上。

5. 本篇常见报错排查：401、local proxy failed 与 OAuth

配置过程中最容易撞上的几类报错，我按出现频率排一下，对照着查。

5.1 401 Unauthorized

最常见。原因通常是三个：环境变量没设置、变量名和env_key不一致、Key 本身失效。先确认：

echo $AZURE_OPENAI_API_KEY

如果输出为空，说明环境变量没生效，重新 export 或检查 shell 配置文件。如果变量名是AZURE_KEY但 config.toml 里写的是AZURE_OPENAI_API_KEY，那必然 401。两者必须逐字符一致。

5.2 local proxy failed 或连接被拒

这个报错通常指向 base_url 写错。检查两点：资源名是否拼对，路径是否带了/openai/v1。少写/v1会打到旧版路由上，报错信息可能五花八门。另外确认你的网络能访问该 Endpoint，企业内网可能需要走公司统一的出口。

5.3 reading choices 相关报错

如果看到类似解析choices字段失败的信息，多半是wire_api配错了。GPT-5-codex 走 Responses API，wire_api必须是responses。如果误填成 chat 相关的值，返回结构对不上，解析就会失败。改回responses即可。

5.4 OAuth 登录提示反复出现

正常情况下配好 Azure provider 后不该再要求登录。如果它仍然弹 OAuth，说明 config.toml 没被读到。检查文件路径是不是~/.codex/config.toml，文件名有没有拼错，TOML 语法有没有错误（比如少了引号）。可以用codex --help看它是否识别到了自定义 provider。

5.5 模型名找不到

报错说部署不存在，八成是model字段填错了。记住填的是部署名，不是模型目录里的gpt-5-codex。去 Azure AI Foundry 的部署列表里核对准确名称。

排查顺序建议：先echo环境变量 → 再核对 base_url 路径 → 再检查 wire_api → 最后看 model 部署名。按这个顺序走，九成问题能定位。

如果你在接入过程中遇到上面没覆盖的报错，可以去接入文档里对照字段说明，或者直接在模型对话里贴出报错信息让模型帮你分析。排障阶段用 API Keys 页面确认密钥状态也很方便。

6. 把配置沉淀成团队规范

配置跑通只是第一步，真正省时间的是把它变成团队可复用的东西。我的做法是把config.toml模板和AGENTS.md一起放进项目的docs/目录，新同学 clone 下来改两行就能用。密钥永远走环境变量或 CI secrets，绝不进仓库。

对于长期在终端里做编码、跑 Agent 任务的团队，可以考虑用 Coding Plan 把额度集中管理，避免每个人各自开订阅。模型验证阶段想快速试不同 prompt，用模型对话页面比反复改代码快得多。接入细节和字段含义，接入文档里有完整说明，遇到拿不准的参数先去那里查。

最后留一个实用技巧：AGENTS.md不要一次写太长，先从三条最关键的规则开始，跑一段时间发现模型老犯某个错，再补一条进去。规则是迭代出来的，不是一次写全的。这样你的 Codex CLI 会越来越贴合团队习惯，而不是每次都要在 prompt 里重复交代。