上周三我想把 Codex CLI 接到项目里替代部分 Claude Code 的工作流，结果光一个 config.yaml 就来回改了三遍才跑通。问题出在两个地方：provider 的枚举值拼写（openai 和你以为的 openai-compatible 行为完全不一样），以及 api_key 到底读环境变量还是读配置文件——官方文档对这俩的优先级描述基本等于没写。这篇把我踩的坑和最终能用的最小配置模板都贴出来，省得你也折腾半天。

这篇适合谁

  • 刚装好 Codex CLI，跑第一条命令就报 401 Incorrect API key provided 的
  • 想把 Codex CLI 接到非 OpenAI 官方端点（Azure、聚合网关等），不确定 provider 怎么填的
  • 从 Claude Code 或 Cursor 切过来，习惯了改 base_url 就能用，结果发现 Codex 的配置逻辑不太一样
  • 想在团队里统一 config.yaml 模板，避免每个人踩一遍同样的坑

整体流程

前置条件：Codex CLI 要求 Node.js ≥ 22，安装前先确认版本：

node --version   # 需要 v22.0.0 或更高

如果版本不够，用 nvm 升级：nvm install 22 && nvm use 22。

  1. 安装 Codex CLI（一行 npm 命令）
  2. 理解配置文件结构（全局 ~/.codex/config.yaml）
  3. 正确填写 provider 字段（这是第一个坑）
  4. 搞清楚 api_key 的读取优先级（这是第二个坑）
  5. 贴一个最小可用模板，直接抄
  6. 验证能跑通
graph TD
 A[npm install -g @openai/codex] --> B[创建 ~/.codex/config.yaml]
 B --> C{provider 字段怎么填?}
 C -->|直连 OpenAI| D[provider: openai]
 C -->|第三方端点| E[provider: openai 但改 baseURL]
 E --> F{api_key 从哪读?}
 D --> F
 F -->|环境变量| G[export OPENAI_API_KEY=sk-xxx]
 F -->|config.yaml 里写死| H[providers.openai.apiKey]
 G --> I[codex 'your task']
 H --> I

先说结论

坑点 你以为的写法 实际正确写法
provider 接第三方端点 provider: openai-compatible 不存在这个枚举值，用 openai + 自定义 baseURL
provider 接 Azure provider: azure 不存在独立的 azure 枚举值，用 openai + 自定义 baseURL 指向 Azure 端点
api_key 优先级 配置文件优先 环境变量 > 配置文件，且环境变量名必须匹配 envKey 字段
baseURL 末尾斜杠 加不加都行 不加 /v1 后缀，Codex 自己拼

第一步：安装

npm install -g @openai/codex

装完跑一下确认在 PATH 里：

codex --help

如果报 Cannot find module '@openai/codex'，大概率是 npm 全局目录没加进 PATH。macOS 用 nvm 的人经常遇到这个。

第二步：provider 字段——第一个大坑

打开（或新建）~/.codex/config.yaml，你会看到一个 providers 段。我一开始想当然写了个 openai-compatible，因为 Cline 和 Cherry Studio 都有这个选项嘛。结果 Codex CLI 直接忽略了整个配置块，fallback 到默认行为，然后因为没读到我配的 baseURL 就去请求 api.openai.com，网络不通，报了个：

APIConnectionError: Connection error.

这个报错信息完全没提示是 provider 写错了，我排查了快一个小时才定位到。

正确做法：Codex CLI 的 provider 枚举值目前只认这几个——openai、anthropic、gemini、ollama 等官方名称，没有 openai-compatible 或 azure 这样的独立枚举值。想接第三方端点（包括 Azure OpenAI、各类聚合网关），provider 还是写 openai，然后在对应 provider 块里覆盖 baseURL 指向你的实际端点。

providers:
  openai:
    baseURL: https://your-gateway-or-azure-endpoint/v1
    envKey: OPENAI_API_KEY

Azure OpenAI 补充说明：Azure 的端点格式通常是 https://<resource-name>.openai.azure.com/openai/deployments/<deployment-name>，且模型名需要填写你在 Azure 门户里创建的部署名，而不是 OpenAI 的原始 model ID（比如部署名可能是 my-gpt4o 而不是 gpt-4o）。如果觉得这套映射麻烦，走支持 Azure 的聚合网关再转 OpenAI 兼容格式会省事一些。

baseURL 不要带末尾斜杠，也不要自己再拼 /chat/completions，Codex 内部会处理路径。

第三步：api_key 优先级——第二个大坑

这个坑更隐蔽。config.yaml 里有个 envKey 字段，它的意思是"去读哪个环境变量的值作为 API Key"，而不是"在这里填 Key 的值"。

优先级实测结果（建议用 codex --version 确认你当前版本，不同版本行为可能有差异）：

  1. 环境变量（envKey 指定的那个变量名）—— 最高优先级
  2. 配置文件里的 apiKey 字段（如果你硬写了的话）—— 次优先级
  3. 都没有 → 报错 OPENAI_API_KEY is not set

我踩的坑是：我在 .zshrc 里 export 了一个过期的 Key，然后在 config.yaml 里又写了一个新 Key。结果 Codex 读的是环境变量里那个过期的，直接 401：

AuthenticationError: 401 Incorrect API key provided

我改了三遍 config.yaml 都没用，最后才反应过来是环境变量在"抢"优先级。

建议：二选一，别混用。要么只用环境变量（团队协作时每个人自己管自己的 Key），要么只写 config.yaml（个人机器图方便）。混用迟早出事。

最小可用 config.yaml 模板

直接抄这个，改两个值就能跑：

model: o4-mini
approvalMode: auto-edit

字段名说明：配置文件中推荐使用 camelCase 的 approvalMode，命令行参数对应 --approval-mode。

上面是最基础的。如果要接第三方端点，把 baseURL 换成你实际可用的端点地址：

model: o4-mini
approvalMode: auto-edit
providers:
  openai:
    baseURL: https://your-gateway-endpoint/v1
    envKey: OPENAI_API_KEY

然后终端里 export Key：

export OPENAI_API_KEY='your-key-here'

验证：

codex 'list all files in current directory'

看到它开始分析文件列表就说明通了。

不同场景怎么选

个人开发者，只用 OpenAI 官方模型：最简配置，不写 providers 块，直接 export 环境变量就行。默认 o4-mini 够用，输入 $1.10/M tokens 输出 $4.40/M tokens，一天写代码下来也就几毛钱。

想用 Claude 或 DeepSeek 等非 OpenAI 模型：需要通过支持 OpenAI 兼容格式的聚合 API 网关接入。OpenRouter 等平台均支持，改 baseURL 指向对应网关，model 字段填该平台的模型 ID（以平台文档为准）。provider 还是写 openai。

团队统一配置：把 config.yaml 模板提交到团队 wiki，envKey 统一用 OPENAI_API_KEY，每个人自己管自己的环境变量。这样 config.yaml 可以 git 共享，Key 不会泄露。

CI/CD 自动化：加 --approval-mode full-auto，非交互模式。--quiet 参数是否可用取决于你安装的版本，建议先跑 codex --help 确认支持的 flag 列表。Linux 环境建议套 Docker 做沙箱隔离。

codex --approval-mode full-auto \
  'add type hints to all functions in utils.py'

踩坑记录 / 常见问题 FAQ

Q: Codex CLI 的 config.yaml 改了但不生效怎么办？

先确认路径对不对——必须是 ~/.codex/config.yaml，不是 ~/.codex/config.yml（后缀别写错）。然后检查 YAML 缩进，providers 下面的字段要缩进两格。我有一次就是 baseURL 没缩进，整个 providers 块被当成无效内容跳过了，也不报错。

Q: 报 401 但我确定 Key 是对的？

先跑 echo $OPENAI_API_KEY 看看终端实际读到的值是不是你以为的那个——.zshrc 里如果有旧 Key，它的优先级高于 config.yaml 里写的值。另外注意复制 Key 时前后别多空格，这个肉眼看不出来但会 401。

Q: provider 能不能写 azure？

不能直接写 azure 作为 provider 枚举值——Codex CLI 的 schema 里没有这个独立值。接 Azure OpenAI 的正确方式是：provider 写 openai，baseURL 填你的 Azure 端点，envKey 填存放 Azure API Key 的环境变量名。注意 Azure 的 model 字段要填部署名而不是 OpenAI 原始 model ID，这是 Azure 接入最容易踩的额外坑。

Q: full-auto 模式安全吗？会不会把文件搞坏？

macOS 下有 Apple Seatbelt 沙箱保护，Linux 下建议用 Docker。但即便有沙箱，我也不建议在生产目录直接 full-auto。日常开发用 auto-edit 就够了——文件修改自动执行，但跑命令还是会问你一声。

Q: Codex CLI 和 Claude Code 怎么选？

看你主力模型是什么。如果主力是 o4-mini 等 OpenAI 模型，Codex CLI 原生支持体验最好。如果主力是 Claude 系列，Claude Code 的上下文理解和多文件编辑目前还是强一截。两个工具可以配合着用，根据任务类型手动切换。

小结

整个配置就两个核心认知：provider 没有 openai-compatible 或 azure 这样的独立枚举值（想接第三方端点就用 openai + 自定义 baseURL），api_key 环境变量优先级高于配置文件。搞清楚这两点，五分钟就能跑通。

我现在的日常工作流是 Codex CLI 处理快速任务（加类型注解、写测试、重命名变量这种），复杂的多文件重构还是交给 Claude Code。两个工具配合着用，比单押一个效率高不少。

# arcgis # flask # python # AI
Logo
AI Agent技术社区

Agent 垂直技术社区，欢迎活跃、内容共建。

更多推荐

cover

【花雕动手做】行空板 K10 系列实验之人工智能调用语音合成（TTS）模块

avatar AI Agent技术社区
cover

苏州企业AI Agent智能体从概念到落地：2026年开发者必须关注的技术范式与工程实践

avatar AI Agent技术社区
cover

GitHub 狂揽 4万+ Star！这个项目直接让你省下 60–95% 的 Token

avatar AI Agent技术社区