Codex 配置自定义 AI API 完整指南：从零到一接入 Token173 中转模型，国内稳定直连 GPT/Claude/Gemini

前言

作为开发者，我们经常需要在终端环境下使用AI编程助手，OpenAI Codex凭借强大的命令行代码辅助能力深受程序员喜爱，但原生仅支持直连OpenAI官方接口。国内开发者直接访问官方API，往往会遭遇网络超时、跨境支付繁琐、账号极易触发风控封号、模型可选范围有限等一系列痛点。

想要在Codex中稳定调用GPT、Claude、Gemini等海内外主流大模型，最优方案就是接入合规的OpenAI兼容API中转平台。本文以Token173中转网关为例，结合macOS（Mac Mini）实操环境，手把手教你从零完成Codex自定义API配置，包含版本选型、TOML配置文件编写、系统环境变量配置、常见报错排查、多模型多服务商切换实操，不管是个人本地调试，还是团队多项目隔离使用，都可以直接照搬落地。

一、读懂Codex底层架构原理

Codex采用可扩展的Provider多服务商架构设计，支持同时配置多套AI接口地址，可随时切换不同模型网关，核心三大概念一定要理清：

1. Provider（服务商）：对应一套独立API配置，包含中转网关BaseURL、鉴权环境变量、接口通信协议；
2. Model（模型）：当前服务商下可调用的具体模型ID，比如gpt-5.5、claude-sonnet-4-6、gemini-3.5-flash；
3. Wire API：Codex与上游网关的通信协议，分为chat（标准对话兼容接口）、responses（OpenAI新版Responses接口）。

依托这套灵活架构，Codex可以无缝接入所有遵循OpenAI接口规范的中转平台、私有化部署大模型、企业内部AI网关，本次我们接入Token173实现国内直连全球大模型。

二、配置前置准备工作

2.1 确认Codex版本，匹配对应接口协议

不同Codex大版本支持的通信协议不一样，版本选错会直接出现调用失败、接口不兼容报错：

codex --version

推荐安装0.80.0稳定版，完美适配Token173标准/v1对话接口，兼容性最强：

npm uninstall -g @openai/codex
npm install -g @openai/codex@0.80.0

2.2 提前获取Token173核心配置信息

1. 打开官网https://token173.com注册登录，进入控制台「API令牌管理」；
2. 新建密钥，复制sk-开头的完整API Key，切勿带空格、不要泄露；
3. 中转网关地址：https://token173.com/v1；
4. 提前记录需要调用的模型ID，例如gpt-5.5、claude-sonnet-4-6、gemini-3.5-flash；

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格式配置文件，分为两级配置，项目级优先级高于用户全局配置：

1. 用户全局配置（所有项目通用）：~/.codex/config.toml
2. 项目独立配置（仅当前文件夹生效）：项目根目录/.codex/config.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 核心配置参数详解

3.4 高频错误配置避坑

1. ❌ 错误：直接把sk密钥写入env_key

env_key = "sk-xxxx"

✅ 正确：只填写环境变量名称，密钥单独配置在系统环境变量

env_key = "TOKEN173_API_KEY"

2. ❌ 协议类型和中转接口不匹配
   Token173为标准Chat Completions接口，必须配置wire_api = "chat"，高版本Codex默认的responses协议会直接调用报错。

3. ❌ 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 自定义模型无法在选择器展示

1. 执行codex config show查看当前加载配置，确认配置文件路径正确；
2. 使用codex --config-check校验TOML语法，检查是否存在换行、符号错误；
3. 确认Provider名称、model名称无中英文空格、特殊符号。

7.2 参数不存在：–model-provider报错

Codex正确参数为--provider，错误参数无法识别：

# 正确用法
codex -m gemini-3.5-flash --provider token173 "代码优化"

7.3 wire_api = chat不再支持报错

两种解决方式：

1. 降级Codex至0.80.0稳定版，适配Token173标准chat接口；
2. 升级Codex后将配置修改为wire_api = "responses"，同时确认网关兼容新版Responses协议。

7.4 环境变量配置后依然提示缺少API Key

1. 执行source ~/.zshrc重载环境变量；
2. 完全退出终端重新打开，避免旧进程环境缓存；
3. 检查密钥前后是否存在多余空格、换行符。

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

九、安全规范最佳实践

1. 严禁将API密钥写入config.toml配置文件，统一通过系统环境变量存放；
2. 将.codex目录加入.gitignore，防止配置文件被提交到公开代码仓库导致密钥泄露；
3. 不同业务项目建议使用独立API密钥，方便额度管控、泄露后单独吊销；
4. 定期在Token173后台轮换API密钥，降低密钥泄露带来的资金风险；
5. 多项目场景优先使用项目级配置，实现不同项目网关、模型隔离。

十、落地配置自检清单

✅ 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写一个文本批量处理脚本"