Codex 配置自定义 AI API 完整指南从零到一接入你的专属模型前言作为一名开发者我们经常需要在终端环境中使用 AI 编程助手。OpenAI 的 Codex 是一个非常强大的命令行 AI 编程工具但默认情况下它只能调用 OpenAI 官方的 API。那么问题来了如果我们有自己的 API 服务比如部署了国产大模型、使用了代理服务、或者公司内部的 AI 平台如何让 Codex 接入这些自定义的 API 呢本文将通过一个真实的配置案例详细讲解如何在 macOS特别是 Mac Mini环境下配置 Codex使其能够调用自定义的 AI API。整个过程涉及配置文件编写、环境变量设置、版本兼容性问题排查等希望能帮助到遇到类似问题的开发者。一、理解 Codex 的架构在开始配置之前我们需要理解 Codex 的基本架构。Codex 采用了一种灵活的 Provider 机制允许用户定义多个 AI 服务提供商并在它们之间切换。核心概念Provider提供商一个 AI 服务的具体实现包含 API 地址、认证方式等Model模型Provider 提供的具体模型名称Wire APICodex 与 Provider 之间的通信协议类型这种设计让 Codex 不仅限于 OpenAI 的服务理论上可以接入任何兼容 OpenAI API 格式的服务。二、配置前的准备工作2.1 确认 Codex 版本这是最关键的一步不同版本的 Codex 对 API 协议的支持完全不同codex--version版本支持的 API 类型wire_api 参数0.81.0 及以上Responses API“responses”0.80.0 及以下Chat Completions API“chat”重要提示如果你的 API 服务只支持标准的 Chat Completions 格式大多数国产模型和代理服务都是这种建议安装 0.80.0 版本npminstall-gopenai/codex0.80.02.2 确认 API 服务状态在配置 Codex 之前先用 curl 测试一下你的 API 服务是否正常工作# 测试基础连通性curl-XPOST http://localhost:8080/v1/chat/completions\-HContent-Type: application/json\-HAuthorization: Bearer YOUR_API_KEY\-d{ model: your-model-name, messages: [{role: user, content: Hello}], max_tokens: 50 }如果这个请求能正常返回说明你的 API 服务是可用的。三、配置文件详解3.1 配置文件位置Codex 的配置文件采用 TOML 格式默认位置在用户级配置~/.codex/config.toml项目级配置项目根目录/.codex/config.toml项目级配置会覆盖用户级配置这为不同项目使用不同的 AI 服务提供了便利。3.2 基础配置结构一个完整的配置文件包含三个部分全局设置默认模型和 ProviderProvider 定义项目特定设置可选# 全局设置 service_tier fast model your-model-name model_provider your-provider-name # Provider 定义 [model_providers.your-provider-name] name 显示名称 base_url http://localhost:8080/v1 wire_api chat # 或 responses env_key YOUR_API_KEY_ENV_NAME # 项目特定设置可选 [projects./path/to/your/project] trust_level trusted3.3 配置项详细说明配置项说明示例model默认使用的模型名称qwen3.6-plusmodel_provider默认使用的 Provider 名称my-custom-providerbase_urlAPI 服务地址http://localhost:8080/v1wire_apiAPI 协议类型chat或responsesenv_key存放 API Key 的环境变量名MY_API_KEY3.4 常见配置错误及修正错误 1将 API Key 直接写在 env_key 字段# ❌ 错误 env_key sk-your-actual-api-key # ✅ 正确 env_key MY_API_KEY错误 2协议类型不匹配# 如果 API 只支持 Chat Completions wire_api chat # 而不是 responses错误 3base_url 格式问题# 本地服务通常用 http 而不是 https base_url http://localhost:8080/v1 # 正确 base_url https://localhost:8080/v1 # 可能导致 SSL 错误四、Mac Mini 环境变量配置4.1 临时设置仅当前终端会话exportYOUR_API_KEYsk-your-actual-api-key4.2 永久设置推荐由于 Mac Mini 默认使用 Zsh我们需要将环境变量写入~/.zshrcechoexport YOUR_API_KEYsk-your-actual-api-key~/.zshrcsource~/.zshrc4.3 验证环境变量echo$YOUR_API_KEY五、实战案例配置本地 Qwen API假设我们有一个运行在本地 8080 端口的 Qwen 模型服务以下是完整的配置步骤5.1 创建配置文件mkdir-p~/.codexnano~/.codex/config.toml5.2 写入配置内容service_tier fast # 设置默认使用 Qwen 模型 model qwen3.6-plus model_provider red_claw # 定义 Provider [model_providers.red_claw] name RedClaw Qwen Service base_url http://localhost:8080/v1 wire_api chat env_key REDCLAW_API_KEY # 项目信任配置可选 [projects./Users/macmini/workspace/my-project] trust_level trusted5.3 设置环境变量echoexport REDCLAW_API_KEYsk-yien-1620bbcc7f4349c1bcf5b82f6e3756c1~/.zshrcsource~/.zshrc5.4 测试配置codex你好请介绍一下自己六、常见问题及解决方案6.1 问题自定义模型不显示在选择器中现象运行codex时模型选择器只显示官方模型看不到自己配置的模型。原因配置文件没有被正确加载或者配置格式有误。解决方案# 检查配置文件是否存在ls-la~/.codex/config.toml# 查看当前加载的配置codex config show# 检查配置语法codex --config-check6.2 问题--model-provider参数不存在现象error: unexpected argument --model-provider found原因Codex 没有这个命令行参数。解决方案通过配置文件设置默认 Provider而不是通过命令行参数。或者使用正确的参数名# 正确的参数是 --providercodex-mmodel-name--providerprovider-nameprompt6.3 问题wire_api 版本不匹配现象wire_api chat is no longer supported原因新版 Codex 不再支持chat协议。解决方案方案一将配置中的wire_api改为responses方案二降级 Codex 到 0.80.0 版本npmuninstall-gopenai/codexnpminstall-gopenai/codex0.80.06.4 问题SSL 证书错误本地服务现象SSL certificate problem: self signed certificate原因本地服务使用 HTTPS 但没有有效的 SSL 证书。解决方案[model_providers.your-provider] # ... 其他配置 allow_insecure true # 仅用于本地开发6.5 问题环境变量不生效现象配置了环境变量但 Codex 仍然提示找不到 API Key。解决方案# 1. 确认环境变量已设置echo$YOUR_API_KEY# 2. 重新加载配置文件source~/.zshrc# 3. 重启终端# Mac 上按 CmdQ 退出终端重新打开# 4. 检查是否有空格或特殊字符# 确保 API Key 没有多余的空格七、调试技巧7.1 开启调试模式# 开启详细日志DEBUGtrue codex你的问题# 查看网络请求详情RUST_LOGdebug codex你的问题7.2 查看配置加载情况# 显示当前所有配置codex config show# 列出可用的 Providerscodex config list-providers# 测试配置文件codex configtest7.3 网络抓包如果还是无法定位问题可以用 Wireshark 或 tcpdump 抓包分析# 监控本地 8080 端口的流量sudotcpdump-ilo0 port8080-A八、最佳实践建议8.1 安全性建议永远不要将 API Key 写在配置文件中始终使用环境变量定期轮换 API Key对不同项目使用不同的 API Key便于审计和权限管理将.codex/目录加入.gitignore避免意外提交敏感信息8.2 多 Provider 管理如果你有多个 AI 服务可以在配置文件中定义多个 Provider# 默认使用本地 Qwen model qwen3.6-plus model_provider local_qwen # 定义本地 Qwen [model_providers.local_qwen] name Local Qwen base_url http://localhost:8080/v1 wire_api chat env_key QWEN_API_KEY # 定义云端 GPT [model_providers.cloud_gpt] name Cloud GPT base_url https://api.openai.com/v1 wire_api responses env_key OPENAI_API_KEY # 定义代理服务 [model_providers.proxy_service] name API Proxy base_url https://your-proxy.com/v1 wire_api chat env_key PROXY_API_KEY8.3 项目级配置示例为不同项目创建独立的配置文件# 项目 A 使用本地 Qwenmkdir-p/path/to/projectA/.codexcat/path/to/projectA/.codex/config.tomlEOF model qwen-max model_provider local_qwen [model_providers.local_qwen] base_url http://localhost:8080/v1 wire_api chat env_key QWEN_API_KEY EOF# 项目 B 使用云端 GPTmkdir-p/path/to/projectB/.codexcat/path/to/projectB/.codex/config.tomlEOF model gpt-4 model_provider cloud_gpt [model_providers.cloud_gpt] base_url https://api.openai.com/v1 wire_api responses env_key OPENAI_API_KEY EOF九、完整配置清单最后提供一个完整的配置检查清单确保没有遗漏Codex 版本已确认0.80.0 推荐API 服务已启动并可访问~/.codex/config.toml文件已创建model和model_provider已正确设置Provider 配置块已添加base_url使用正确的协议本地用 httpwire_api类型与 API 服务匹配env_key填的是环境变量名不是 API Key环境变量已在~/.zshrc中设置已执行source ~/.zshrc使配置生效echo $YOUR_ENV_KEY能正确显示 API Keycodex config show显示正确的配置codex test能正常响应十、总结配置 Codex 调用自定义 AI API 的核心要点可以总结为版本先行确认 Codex 版本选择合适的wire_api类型配置分离API Key 用环境变量其他配置用 TOML 文件协议匹配确保wire_api与你的 API 服务类型一致路径正确base_url格式要正确本地服务注意 http vs https调试有方善用DEBUGtrue和codex config show排查问题虽然配置过程中可能会遇到各种问题版本不匹配、参数名错误、环境变量不生效等但只要按照本文的步骤逐一排查最终都能顺利解决。希望这篇指南能帮助你成功配置 Codex享受到在终端中使用自定义 AI 模型的便利。如果你在配置过程中遇到其他问题欢迎在评论区留言交流附录快速配置模板# 一键配置脚本请根据实际情况修改cat~/.codex/config.tomlEOF model your-model model_provider custom [model_providers.custom] base_url http://localhost:8080/v1 wire_api chat env_key CUSTOM_API_KEY EOFechoexport CUSTOM_API_KEYyour-actual-api-key~/.zshrcsource~/.zshrc# 测试codexHello, world!