先说结论
Codex 版本决定 API 协议：0.80.0 及以下用 chat，0.81.0 及以上用 responses，选错直接报错不工作。
API Key 必须通过环境变量传入，写在配置文件中是安全大忌，且 env_key 字段只填变量名。
多 provider 配置可以实现本地模型和云端模型按项目切换，但注意项目级配置会覆盖全局配置，维护成本不低。
从配置细节和版本兼容性切入，聚焦实际部署中的坑和选型权衡，而不是复述步骤清单。
Codex 是个好工具，但想把它接到自己家的模型上，过程并不那么丝滑。
我看了不少配置教程，但真正动手时，第一个卡住的问题就是版本。
版本问题：第一个拦路虎
Codex 的两个版本对 API 协议的支持完全不同。0.80.0 及以下用chat协议，0.81.0 及以上用responses协议。如果你的 API 服务是标准的 Chat Completions（大多数国产模型和本地部署的都是这种），却装了新版 Codex，那你用wire_api = "chat"就会看到wire_api = chat is no longer supported的错误。
解法有两种：要么降级 Codex 到 0.80.0，要么让 API 服务兼容 responses 协议。对个人开发者来说，降级更简单，但牺牲的是新版本的功能更新。这里没有绝对正确答案，取决于你的 API 服务方支不支持新协议。
配置文件：不是随便写写就能用
配置文件是 TOML 格式，放在~/.codex/config.toml。结构分三块：全局设置、provider 定义、可选的项目设置。
最容易犯的错误是把 API Key 直接写在env_key字段里，比如env_key = "sk-your-key"。正确的做法是只填环境变量名，比如env_key = "MY_API_KEY"，然后在.zshrc里export MY_API_KEY="sk-your-key"。
另一个坑是base_url的协议。本地服务一般用http，如果用https且没有有效证书，就会报 SSL 错误。文章里提到加allow_insecure = true可以绕过，但只建议本地开发用，生产环境千万别。
环境变量：安全与便利的平衡
环境变量设置看似简单，但经常不生效。常见原因：忘记source ~/.zshrc、终端没有重启、Key 里有多余空格。用echo $YOUR_KEY验证一下最保险。
这里有一个取舍：把 Key 写进配置文件确实方便，但极度不安全。尤其多人协作或开源项目，一旦泄露后果严重。所以文章的建议是对的：永远用环境变量，把.codex/目录加入.gitignore。
多 Provider：灵活但维护不易
配置文件可以定义多个 provider，比如一个本地 Qwen，一个云端 GPT，一个代理服务。切换时只需改model_provider字段，或者通过项目级配置覆盖。
听起来很灵活，但实际维护起来有一定成本。每个 provider 都要配 base_url、wire_api、env_key，如果 API 变更频繁，配置文件会变得臃肿。而且项目级配置会覆盖全局，一旦不同项目用不同版本，容易搞混。
调试与常见坑
文章提供了不少调试技巧，比如用DEBUG=true开启详细日志、codex config show查看当前配置、codex config test测试配置。这些在实际排查时很有用。
还有一个小坑：--model-provider参数不存在，正确参数是--provider。文档里没写清楚的话，只能靠试错。
最后说两句
配置 Codex 接自定义 API，本质上是在版本兼容性、安全性、灵活性之间找平衡。没有一步到位的完美方案，只有根据自己场景做的取舍。
如果你主要用本地模型，建议降级到 0.80.0 版本，省心。如果必须用新版，那就要确保你的 API 服务支持 responses 协议，或者自己写一个协议转换中间件。后者虽然灵活，但开发和维护成本不低。
说到底，工具是拿来用的，不是拿来折腾的。选一条让自己最舒服的路就行。
最后留一个讨论点
如果你要在个人项目中使用 Codex，你会选择本地部署的模型还是云端付费 API？为什么？
