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 CLICodex CLI 提供 npm 和 Homebrew 两种安装方式选一个就行。npm 方式跨平台通用npm install -g openai/codex codex --versionmacOS 用户如果习惯 brewbrew 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.comAPI 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逐字段解释一下方便你按自己环境改字段作用常见错误model指定调用的部署名填成模型目录名而非部署名model_provider引用下面的 provider 段与段名不一致model_reasoning_effort推理强度high 适合复杂任务拼写错误导致被忽略base_urlAzure 资源地址 /openai/v1漏掉 /openai/v1 路径env_key环境变量名非密钥本身直接填了 Key 字符串wire_api使用 Responses API填成 chat 导致协议不匹配这里最关键的是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 这个 providerexec表示非交互执行--full-auto允许它自动执行操作。如果返回了文件数量说明整条链路——配置读取、鉴权、请求、响应——全部打通。4.3 在 CI 里复用同一套配置Codex 也能作为 CI 管道的一部分。把 API Key 存到仓库 secrets 里比如命名为AZURE_OPENAI_KEY然后加一个 jobjobs: update_changelog: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - 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 APIwire_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 里重复交代。