Codex接入自定义AI模型：一条命令搞定？先看清版本和协议的代价

先说结论

• 接入自定义API的核心不是写配置，而是先确认Codex版本与后端服务支持的协议（chat vs responses）是否匹配，版本选错直接导致连不通。

• 配置文件和环境变量的分离是安全基础，但实际部署中，环境变量加载、路径格式（http/https）、项目级覆盖这些细节，消耗的调试时间可能比写配置本身还多。

• 这套方案适合需要灵活切换多个AI服务（如本地模型、云端GPT、代理）的开发者，但对于只想快速用上一个固定服务的个人项目，直接写死参数可能更省心，尽管牺牲了可维护性。

从版本兼容性和协议匹配这个最容易踩坑的细节切入，讨论接入自定义模型时，那些看似简单的配置背后，实际需要付出的排查成本和适用边界。

终端里敲codex就能直接问AI，这效率确实诱人。但默认只连OpenAI，如果你的模型跑在本地，或者用的是国产大模型、公司内网服务，怎么办？第一反应可能是找配置文档，照着写几行TOML。但真动手时，第一个报错往往是：wire_api = chat is no longer supported。

问题不在配置语法，而在版本。Codex 0.81.0及以上，只认Responses API；0.80.0及以下，才支持更通用的Chat Completions API。大多数自定义服务，包括很多开源模型部署，默认都是Chat Completions格式。版本选错，后面所有配置都白搭。

更麻烦的是，这个版本差异不会在安装时提示你。你得先codex --version，再对照后端服务支持的协议。如果服务方不提供Responses API，你就得降级Codex。降级意味着放弃新版本可能有的功能更新或性能优化。这里没有完美方案，只有取舍。

假设版本搞定了，接下来是写配置。~/.codex/config.toml这个文件，结构不复杂：定义Provider，填base_url、wire_api、env_key。但细节能卡住半天。比如base_url，本地服务用http://localhost:8080/v1，写成https就可能触发SSL证书错误，除非加allow_insecure = true——这又带来安全警告。

env_key字段更是个陷阱。它应该填环境变量名，比如MY_API_KEY，而不是直接把API Key写进去。但新手很容易顺手写成Key本身，结果运行时提示认证失败。安全规范要求Key不进配置文件，可环境变量怎么设，又是另一个问题。Mac上得改~/.zshrc，改完要source，甚至重启终端。这些步骤漏一个，Key就传不过去。

如果按这个思路走一遍，接入一个本地Qwen服务，步骤大概是：先确认Codex是0.80.0，然后curl测试API是否通，接着创建TOML文件，写Provider配置，设环境变量，最后codex "你好"测试。流程清晰，但每一步都可能出岔子。模型列表不显示自定义模型？可能是配置文件没加载，用codex config show查。参数错误？--model-provider不存在，得用--provider。这些报错信息不会直接告诉你解决办法，得靠经验或搜索。

这套配置机制的优点很明显：灵活。你可以在一个文件里定义多个Provider，比如本地Qwen、云端GPT、代理服务，然后通过model_provider切换。项目级配置还能覆盖全局，不同工程用不同模型。对于需要频繁切换AI服务的中大型团队，这种集中管理能省不少事。

但代价呢？配置文件多了，维护成本就上去了。每个新项目可能都要配一遍，或者复制模板。环境变量得确保每台开发机都设对，团队协作时容易漏。而且，Codex本身在快速迭代，今天稳定的配置，明天版本一升，可能又得调。

所以，值不值得折腾？如果你们团队已经部署了内部AI平台，需要把Codex集成进开发流水线，那这个配置投入是必要的。长期看，统一接口能提升工具链效率。但如果只是个人项目，想快速调一下本地模型，也许更简单的做法是：写个shell脚本，直接用curl调用API，把结果格式化输出。少一层抽象，就少一层调试。

说到底，Codex的自定义接入，解决的是“一个工具对接多个AI源”的问题，没解决的是“零配置开箱即用”。它给了你灵活性，但要求你付出配置和兼容性管理的成本。在动手前，先想清楚：你需要的是灵活切换，还是快速接通？答案不同，投入的路径就不同。

最后留一个讨论点

如果你要接入一个公司内网的AI服务，你会优先选择降级Codex到0.80.0来适配通用的Chat Completions API，还是要求后端服务升级支持Responses API？为什么？