1. 为什么一个 config.yaml 能让人改三遍Codex CLI 是 OpenAI 推出的命令行编码代理能在终端里直接读写项目文件、跑命令、改代码。它和 Claude Code 定位类似但配置走的是~/.codex/config.yaml这套 YAML 体系。问题就出在这Codex CLI 的配置项命名和大多数同类工具不一样provider字段的枚举值、api_key的读取优先级官方文档写得非常含糊导致很多人第一次接入非官方端点时会反复填错。这篇聚焦两个具体坑一是provider到底能填什么二是api_key从环境变量读还是从配置文件读、谁优先。我会给出可复制的最小config.yaml、逐项覆盖顺序的验证命令以及把 endpoint 改到 TaoToken 后的连通性检查动作。适合刚装好 Codex CLI 就跑出 401 的人、想把 Codex 接到聚合网关的人、以及从 Claude Code 或 Cursor 切过来以为改个 base_url 就完事的人。先说清楚一个前提Codex CLI 要求 Node.js ≥ 22。装之前先确认版本不然后面所有配置都白搭。node --version # 需要 v22.0.0 或更高版本不够就用 nvm 升级nvm install 22 nvm use 22装 Codex CLI 本身一行命令npm install -g openai/codex装完确认在 PATH 里codex --help如果报Cannot find module openai/codex大概率是 npm 全局目录没加进 PATHmacOS 用 nvm 的人经常遇到。这一步过了才轮到 config.yaml 登场。2. 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-endpoint/v1 envKey: OPENAI_API_KEY这里有个细节baseURL不要带末尾斜杠也不要自己再拼/chat/completionsCodex 内部会处理路径。我试过在末尾加/结果请求路径变成双斜杠某些网关会直接 404。Azure OpenAI 的情况更绕。Azure 的端点格式通常是https://resource-name.openai.azure.com/openai/deployments/deployment-name而且model字段要填你在 Azure 门户里创建的部署名不是 OpenAI 的原始 model ID比如部署名可能是my-gpt4o而不是gpt-4o。如果觉得这套映射麻烦走支持 Azure 的聚合网关再转 OpenAI 兼容格式会省事一些。provider 字段的对照关系可以这样记你以为的写法实际正确写法接第三方端点provider: openai-compatible不存在用provider: openai 自定义baseURL接 Azureprovider: azure不存在用provider: openai 自定义baseURL指向 Azure 端点baseURL 末尾加斜杠不加Codex 自己拼路径3. api_key 优先级环境变量和配置文件谁说了算这个坑更隐蔽。config.yaml里有个envKey字段它的意思是去读哪个环境变量的值作为 API Key而不是在这里填 Key 的值。很多人第一次看到envKey会以为是把 Key 写进去结果填了个sk-xxx进去Codex 拿这个字符串当环境变量名去找当然找不到。优先级实测结果建议用codex --version确认你当前版本不同版本行为可能有差异环境变量envKey指定的那个变量名——最高优先级配置文件里的apiKey字段如果你硬写了的话——次优先级都没有 → 报错OPENAI_API_KEY is not set我踩的坑是在.zshrc里 export 了一个过期的 Key然后在config.yaml里又写了一个新 Key。结果 Codex 读的是环境变量里那个过期的直接 401AuthenticationError: 401 Incorrect API key provided我改了三遍 config.yaml 都没用最后才反应过来是环境变量在抢优先级。建议二选一别混用。要么只用环境变量团队协作时每个人自己管自己的 Key要么只写 config.yaml个人机器图方便。混用迟早出事。下面是一个可以直接抄的最小可用模板改两个值就能跑model: o4-mini approvalMode: auto-edit providers: openai: baseURL: https://taotoken.net/api/v1 envKey: OPENAI_API_KEY字段名说明配置文件中推荐使用 camelCase 的approvalMode命令行参数对应--approval-mode。baseURL这里填的是 TaoToken 的 API 地址末尾不带斜杠也不带/chat/completions。然后终端里 export Keyexport OPENAI_API_KEYyour-key-here如果你想把 Key 写进配置文件而不是环境变量可以这样providers: openai: baseURL: https://taotoken.net/api/v1 apiKey: sk-your-key-here但记住只要环境变量里存在OPENAI_API_KEY它就会覆盖配置文件里的apiKey。所以要么把.zshrc里的旧 export 删掉要么就别在配置文件里写apiKey。4. 验证请求从 401 到跑通的全过程配置写完之后验证分三步走。第一步确认 Codex 读到了哪个配置codex --version第二步用一个最简单的任务测试连通性codex list all files in current directory看到它开始分析文件列表就说明通了。如果这一步报 401先跑echo $OPENAI_API_KEY看看终端实际读到的值是不是你以为的那个。.zshrc里如果有旧 Key它的优先级高于 config.yaml 里写的值。另外注意复制 Key 时前后别多空格这个肉眼看不出来但会 401。第三步如果 401 排除了但报APIConnectionError或local proxy failed那就是 baseURL 的问题。检查两件事baseURL 是不是写成了https://taotoken.net/api/v1注意/v1后缀以及末尾有没有多余的斜杠。TaoToken 的 API 地址是https://taotoken.net/api在 Codex 里需要补上/v1后缀因为 Codex 内部会在这个 baseURL 后面拼/chat/completions。跑通之后你可以用codex add type hints to all functions in utils.py这种真实任务验证模型能力。如果返回的是正常的代码修改建议说明整条链路——Codex CLI → config.yaml → TaoToken 端点 → 模型——全部打通。对于需要长期跑编码任务的场景可以考虑用 Coding Plan 来管理调用配额避免每次手动 export Key。如果只是想先验证模型对话效果可以直接在模型对话页面测试。5. 常见报错排查401、local proxy failed、reading choices报错一401 Incorrect API key provided这是最高频的。排查顺序先echo $OPENAI_API_KEY确认环境变量值再检查 config.yaml 里有没有同时写了apiKey和envKey。如果两个都写了环境变量赢。如果环境变量是空的Codex 会去读 config.yaml 里的apiKey。两个都没有报OPENAI_API_KEY is not set。报错二APIConnectionError: Connection error或local proxy failed这个通常不是 Key 的问题是 baseURL 写错了。检查 provider 字段是不是写成了openai-compatible或azure——这两个枚举值不存在Codex 会忽略整个 providers 块fallback 到默认的api.openai.com。正确写法是provider: openai 自定义baseURL。另外确认 baseURL 带了/v1后缀且末尾没有斜杠。报错三Error reading choices或返回体解析失败这个报错说明请求发出去了但返回的 JSON 结构不符合 Codex 的预期。常见原因是 baseURL 指向的端点不是 OpenAI 兼容格式或者模型名填错了。Codex 期望的返回体里有choices数组如果你的网关返回的是别的结构就会报这个。检查model字段填的是不是网关支持的模型 ID。报错四OAuth 相关报错如果你之前用codex auth走过 OAuth 登录流程后来又改了 config.yaml 走 API Key可能会遇到 OAuth token 和 API Key 冲突的情况。解决方法是清掉~/.codex/下的 auth 缓存文件重新用 API Key 方式配置。报错五config.yaml 改了但不生效先确认路径对不对——必须是~/.codex/config.yaml不是~/.codex/config.yml后缀别写错。然后检查 YAML 缩进providers下面的字段要缩进两格。我有一次就是baseURL没缩进整个 providers 块被当成无效内容跳过了也不报错。6. 把 endpoint 改到 TaoToken 后的连通性检查如果你决定把 Codex CLI 的 endpoint 改到 TaoToken完整的配置三件套是Base URL、Key、Model ID。Base URL 填https://taotoken.net/api/v1Key 从 API Keys 页面获取Model ID 填你实际要用的模型名。完整的 config.yaml 长这样model: o4-mini approvalMode: auto-edit providers: openai: baseURL: https://taotoken.net/api/v1 envKey: OPENAI_API_KEY然后 export Keyexport OPENAI_API_KEYyour-taotoken-key连通性检查分两步。第一步用 curl 直接测端点curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $OPENAI_API_KEY \ -H Content-Type: application/json \ -d {model:o4-mini,messages:[{role:user,content:ping}]}如果返回体里有choices数组说明端点和 Key 都没问题。第二步跑 Codex CLI 的真实任务codex list all files in current directory两步都通了就说明 Codex CLI → TaoToken → 模型这条链路完全打通。后续如果要换模型只改model字段就行baseURL 和 Key 不用动。对于团队协作场景建议把 config.yaml 模板提交到团队 wikienvKey统一用OPENAI_API_KEY每个人自己管自己的环境变量。这样 config.yaml 可以 git 共享Key 不会泄露。CI/CD 自动化场景加--approval-mode full-auto走非交互模式Linux 环境建议套 Docker 做沙箱隔离。codex --approval-mode full-auto \ add type hints to all functions in utils.py整个配置就两个核心认知provider 没有openai-compatible或azure这样的独立枚举值想接第三方端点就用openai 自定义baseURLapi_key 环境变量优先级高于配置文件混用迟早出事。搞清楚这两点五分钟就能跑通。我现在的日常工作流是 Codex CLI 处理快速任务加类型注解、写测试、重命名变量这种复杂的多文件重构还是交给 Claude Code两个工具配合着用比单押一个效率高不少。
