前言
作为开发者，我们经常需要在终端环境下使用AI编程助手，OpenAI Codex凭借强大的命令行代码辅助能力深受程序员喜爱，但原生仅支持直连OpenAI官方接口。国内开发者直接访问官方API，往往会遭遇网络超时、跨境支付繁琐、账号极易触发风控封号、模型可选范围有限等一系列痛点。
想要在Codex中稳定调用GPT、Claude、Gemini等海内外主流大模型，最优方案就是接入合规的OpenAI兼容API中转平台。本文以Token173中转网关为例，结合macOS（Mac Mini）实操环境，手把手教你从零完成Codex自定义API配置，包含版本选型、TOML配置文件编写、系统环境变量配置、常见报错排查、多模型多服务商切换实操，不管是个人本地调试，还是团队多项目隔离使用，都可以直接照搬落地。
一、读懂Codex底层架构原理
Codex采用可扩展的Provider多服务商架构设计，支持同时配置多套AI接口地址，可随时切换不同模型网关，核心三大概念一定要理清：
依托这套灵活架构，Codex可以无缝接入所有遵循OpenAI接口规范的中转平台、私有化部署大模型、企业内部AI网关，本次我们接入Token173实现国内直连全球大模型。
二、配置前置准备工作
2.1 确认Codex版本，匹配对应接口协议
不同Codex大版本支持的通信协议不一样，版本选错会直接出现调用失败、接口不兼容报错：
codex –version
| 0.81.0及以上 | OpenAI Responses API | responses | 原生OpenAI官方新版接口 |
| 0.80.0及以下 | Chat Completions标准接口 | chat | 绝大多数中转平台、国产大模型、Token173这类OpenAI兼容网关 |
推荐安装0.80.0稳定版，完美适配Token173标准/v1对话接口，兼容性最强：
npm uninstall -g @openai/codex
npm install -g @openai/codex@0.80.0
2.2 提前获取Token173核心配置信息
2.3 curl命令提前测试接口连通性
正式配置前，先在终端测试Token173接口是否可以正常请求，规避网络、密钥错误问题：
curl -X POST https://token173.com/v1/chat/completions \\
-H "Content-Type: application/json" \\
-H "Authorization: Bearer sk-你的Token173密钥" \\
-d '{
"model": "gpt-5.5",
"messages": [{"role": "user", "content": "用Python写快速排序"}]
}'
接口正常返回对话内容，则代表网关、密钥、网络全部正常，可以开始Codex配置。
三、Codex配置文件详细说明
3.1 配置文件存放路径
Codex使用TOML格式配置文件，分为两级配置，项目级优先级高于用户全局配置：
3.2 基础配置结构拆解
一份标准配置分为三大模块：全局默认参数、多Provider服务商配置、项目权限信任配置。
# 全局基础设置
service_tier = "fast"
model = "gpt-5.5"
model_provider = "token173"
# 定义Token173服务商配置
[model_providers.token173]
name = "Token173全球大模型中转"
base_url = "https://token173.com/v1"
wire_api = "chat"
env_key = "TOKEN173_API_KEY"
# 配置项目信任权限
[projects."/Users/macmini/工作目录/代码项目"]
trust_level = "trusted"
3.3 核心配置参数详解
| model | 默认启动使用的模型ID | gpt-5.5 |
| model_provider | 默认启用的服务商名称 | token173 |
| base_url | 中转网关接口地址 | https://token173.com/v1 |
| wire_api | 接口协议类型 | chat（适配Token173） |
| env_key | 存储API密钥的环境变量名称 | TOKEN173_API_KEY |
3.4 高频错误配置避坑
env_key = "sk-xxxx"
✅ 正确：只填写环境变量名称，密钥单独配置在系统环境变量
env_key = "TOKEN173_API_KEY"
❌ 协议类型和中转接口不匹配
Token173为标准Chat Completions接口，必须配置wire_api = "chat"，高版本Codex默认的responses协议会直接调用报错。
❌ base_url漏写/v1后缀
Codex需要标准OpenAI接口路径，必须填写https://token173.com/v1，不能只填根域名。
四、Mac Mini（Zsh终端）环境变量配置
4.1 临时配置（仅当前终端窗口生效，重启失效）
适合临时调试测试：
export TOKEN173_API_KEY="sk-你的Token173完整密钥"
4.2 永久环境变量配置（推荐生产使用）
Mac系统默认Zsh终端，写入~/.zshrc实现永久生效：
# 写入环境变量配置
echo 'export TOKEN173_API_KEY="sk-你的Token173完整密钥"' >> ~/.zshrc
# 重载配置文件生效
source ~/.zshrc
4.3 校验环境变量是否配置成功
echo $TOKEN173_API_KEY
终端正常输出sk开头密钥字符串，代表配置生效。
五、实操案例：Codex接入Token173完整步骤
5.1 创建全局配置文件夹与配置文件
mkdir -p ~/.codex
nano ~/.codex/config.toml
5.2 写入Token173完整配置内容
service_tier = "fast"
# 默认使用GPT-5.5模型
model = "gpt-5.5"
model_provider = "token173"
# Token173中转网关配置
[model_providers.token173]
name = "Token173 AI模型中转网关"
base_url = "https://token173.com/v1"
wire_api = "chat"
env_key = "TOKEN173_API_KEY"
# 信任本地项目目录，避免安全拦截
[projects."/Users/macmini/workspace"]
trust_level = "trusted"
按下Ctrl+O保存、Ctrl+X退出编辑器。
5.3 校验配置并启动Codex测试
# 校验配置文件语法
codex –config-check
# 发起对话测试接口连通性
codex "用TypeScript手写LRU缓存算法"
正常返回代码内容即代表Token173接入成功，可在终端稳定使用GPT、Claude、Gemini等模型辅助编程。
六、多服务商多模型配置模板（进阶用法）
可以同时配置Token173、本地私有化模型等多个Provider，随时切换网关与模型：
service_tier = "fast"
model = "claude-sonnet-4-6"
model_provider = "token173"
# 1、Token173中转服务商
[model_providers.token173]
name = "Token173全球大模型中转"
base_url = "https://token173.com/v1"
wire_api = "chat"
env_key = "TOKEN173_API_KEY"
# 2、本地私有化Qwen模型
[model_providers.local_qwen]
name = "本地通义千问私有化服务"
base_url = "http://localhost:8080/v1"
wire_api = "chat"
env_key = "LOCAL_QWEN_KEY"
# 切换服务商调用示例
# codex -m gemini-3.5-flash –provider token173 "帮我重构这段代码"
七、高频报错问题解决方案
7.1 自定义模型无法在选择器展示
7.2 参数不存在：–model-provider报错
Codex正确参数为–provider，错误参数无法识别：
# 正确用法
codex -m gemini-3.5-flash –provider token173 "代码优化"
7.3 wire_api = chat不再支持报错
两种解决方式：
7.4 环境变量配置后依然提示缺少API Key
7.5 接口SSL安全报错
仅本地HTTP私有化服务需要开启不安全放行，Token173为正规HTTPS域名无需配置：
[model_providers.local_qwen]
allow_insecure = true
八、调试排错实用命令
# 开启详细调试日志，查看完整请求链路
DEBUG=true codex "帮我写接口"
# 查看当前全部加载配置
codex config show
# 列出所有配置好的服务商
codex config list-providers
# 配置文件语法校验
codex config test
九、安全规范最佳实践
十、落地配置自检清单
✅ Codex已安装0.80.0兼容稳定版本
✅ Token173接口通过curl测试连通正常
✅ 全局~/.codex/config.toml配置文件创建完成
✅ base_url填写https://token173.com/v1，wire_api设置为chat
✅ env_key仅填写环境变量名，未直接写入sk密钥
✅ 环境变量写入~/.zshrc并执行source重载生效
✅ 终端可正常打印TOKEN173_API_KEY密钥
✅ 通过codex –config-check校验配置语法无误
✅ Codex对话测试可正常调用Token173模型返回结果
十一、总结
Codex接入自定义API的核心要点：先锁定适配版本、再规范TOML配置、密钥通过环境变量隔离、接口协议和中转网关保持匹配。借助Token173合规中转网关，不仅可以解决国内直连海外大模型的网络、支付、风控三大痛点，还能一键调用数百款主流AI模型，让终端Codex编程助手突破官方限制，大幅提升本地代码开发、项目调试、脚本编写效率。
只要按照本文步骤完成配置，后续只需要切换模型ID即可灵活调用GPT、Claude、Gemini等各类大模型，同时支持多项目、多网关隔离部署，兼顾安全性、灵活性与稳定性。
附录：一键部署脚本
# 1、创建Codex配置文件
mkdir -p ~/.codex
cat > ~/.codex/config.toml << 'EOF'
service_tier = "fast"
model = "gpt-5.5"
model_provider = "token173"
[model_providers.token173]
name = "Token173全球大模型中转"
base_url = "https://token173.com/v1"
wire_api = "chat"
env_key = "TOKEN173_API_KEY"
EOF
# 2、写入你的Token173密钥
echo 'export TOKEN173_API_KEY="sk-替换为你的密钥"' >> ~/.zshrc
source ~/.zshrc
# 3、测试调用
codex "用Python写一个文本批量处理脚本"
