Codex 配置自定义 AI API 完整指南：从0到1接入你的专属模型，2026年本地模型 / 第三方中转一站式配置

如今 AI 编程工具早已成为研发提效的标配OpenAI Codex CLI 凭借强大的代码理解、生成与调试能力被大量开发者用于项目开发、脚本编写与自动化运维。很多使用者都会遇到一个问题默认直连官方接口网络不稳定、无法自由切换本地部署模型、也不方便使用国内合规第三方中转平台。Codex CLI 原生支持多服务商扩展机制借助Provider配置能力我们可以自由对接本地私有大模型、国产开源模型以及国内合规API中转服务。本文从环境准备、核心参数解读、多场景配置、高阶分组管理到排错方案手把手带大家从零完成 Codex 自定义 API 全流程部署兼顾新手与运维人员使用需求。一、前期环境准备在开始配置自定义接口前需要先完成基础软件安装与目录初始化全平台通用。1. 安装 Codex CLI 客户端Codex 依赖 Node.js 运行环境要求版本 ≥22打开终端执行全局安装命令npminstall-gopenai/codex安装完成后输入以下命令校验是否部署成功codex--version2. 初始化配置目录Codex 所有自定义规则、接口信息都会统一存放在专属配置目录中默认路径为~/.codex主配置文件为config.tom。执行命令创建目录与空配置文件mkdir-p~/.codextouch~/.codex/config.toml补充Codex 配置存在明确的加载优先级由高至低依次为命令行临时参数 分组(Profile)配置 全局顶层配置 程序默认配置。我们可以利用这一特性针对不同项目、不同模型灵活切换配置无需反复修改文件。二、核心配置参数详解config.toml是整个自定义接入的核心文件所有接口适配都围绕三个关键参数展开也是新手最容易出错的地方。配置字段参数说明base_urlAPI 服务根地址地址末尾必须携带/v1后缀不可额外拼接路由wire_api通信协议字段分为chat和responses两种格式由接口后端决定env_key环境变量名称用于读取 API 密钥禁止明文写入配置文件重点版本兼容提醒高频踩坑点Codex 不同版本对通信协议强制区分版本分界线为0.80.0版本 ≤ 0.80.0仅兼容传统对话接口wire_api固定填写chat版本 ≥ 0.81.0默认使用全新 Responses 接口wire_api固定填写responses。目前国内绝大多数开源模型、本地部署推理服务、第三方中转平台仅适配chat协议。如果你的 Codex 为新版有两种解决方案方案一降级至兼容版本执行命令npm install -g openai/codex0.80.0方案二选用支持 Responses 协议的后端服务。行业内部分工具为了降低适配难度也会推荐使用 0.57.0 经典稳定版可根据自身业务选择。三、多场景实战配置结合国内使用环境划分本地私有模型、Token173第三方中转、多服务商快速切换三大主流场景附上完整可直接复用的配置代码。场景一接入本地部署模型Ollama / vLLM适用于内网开发、数据隔离、私有化部署场景本地服务默认使用http协议注意区分协议类型。1. Ollama 本地模型配置默认端口 11434toml modelqwen3.6-plusmodel_providerlocal_qwen[model_providers.local_qwen]nameLocal Qwenbase_urlhttp://localhost:11434/v1wire_apichatenv_keyQWEN_API_KEY关键注意事项 - 本地服务使用 http 协议填写 https 会触发 SSL 证书错误 - base_url 仅保留至 /v1不要拼接 /chat/completions 等子路由 - 本地无鉴权服务时env_key 可随意自定义变量名。 #### 2. vLLM 推理服务配置支持 Responses 协议 bash toml model Qwen3.6-27B model_provider vllm [model_providers.vllm] name Local vLLM base_url http://localhost:8000/v1 wire_api responses env_key VLLM_API_KEY提示使用该配置时需保证 vLLM 服务已开启工具调用能力Codex 对模型函数调用有硬性要求。 ### 场景二接入 Token173 国内中转服务 国内开发者直连海外官方接口普遍存在延迟高、连接失败、风控拦截等问题Token173 作为聚合中转平台全面兼容 OpenAI 标准协议可无缝对接 Codex。 完整配置示例 bash toml model_provider token173 model gpt-5 [model_providers.token173] name Token173 中转服务 base_url https://token173.com/v1 wire_api chat env_key TOKEN173_API_KEY request_max_retries 4 stream_max_retries 10配置完成后在终端声明环境变量写入你的 Token173 平台密钥 bash export TOKEN173_API_KEY你的SK密钥场景三多服务商一键切换配置当你需要在海外官方接口、Token173中转、本地模型之间频繁切换时可以在同一个配置文件中定义多个Provider修改顶部字段即可快速切换toml# 默认使用Token173中转model_providertoken173modelgpt-5# 配置1Token173 中转[model_providers.token173]nameToken173base_urlhttps://token173.com/v1wire_apichatenv_keyTOKEN173_API_KEY# 配置2OpenAI 官方接口[model_providers.openai]nameOpenAI Officialbase_urlhttps://api.openai.com/v1wire_apiresponsesenv_keyOPENAI_API_KEY# 配置3本地模型[model_providers.local_qwen]nameLocal Qwenbase_urlhttp://localhost:8080/v1wire_apichatenv_keyQWEN_API_KEY## 四、Profile 分组高阶用法 针对不同业务场景正式生产、本地调试可以使用 Profile 分组功能独立管理多套配置不用反复修改全局文件。 示例配置 bash toml # 默认加载生产分组 profile production # 通用服务商配置 [model_providers.token173] name Token173 base_url https://token173.com/v1 wire_api chat env_key TOKEN173_API_KEY # 生产环境分组 [profiles.production] model_provider token173 model gpt-5.4 model_reasoning_effort high approval_policy on-request # 本地调试分组 [profiles.local_dev] model_provider local_qwen model qwen3.6-plus sandbox_mode workspace-write启动命令按需指定分组 bash # 加载生产环境配置 cod --profile production # 加载本地调试配置 cod --profile local_dev五、环境变量规范安全最佳实践严禁将 API 密钥明文写入配置文件这是开发安全基本准则。所有密钥统一通过系统环境变量注入。Linux / macOSbash / zsh编辑环境变量配置文件# zsh 用户vim~/.zshrc# bash 用户vim~/.bashrc写入变量exportTOKEN173_API_KEY你的密钥exportQWEN_API_KEY本地模型密钥保存后生效source~/.zshrc验证变量是否加载成功echo$TOKEN173_API_KEYWindows PowerShell临时设置当前会话生效$env:TOKEN173_API_KEY你的密钥六、常见问题与排错方案整理国内使用过程中高频报错、原因及对应解决办法快速定位问题报错信息故障原因解决方案missing api key环境变量未加载、变量名不匹配重新执行source命令或重启终端核对env_key字段SSL 连接错误本地服务误用 https 协议本地接口统一使用http协议wire_api no longer supportedCodex 版本与接口协议不兼容降级至 0.80.0 版本或更换对应协议后端模型列表为空 / 调用无响应base_url 路由填写错误仅保留xxx/v1不要追加额外接口路径流式输出频繁中断中转网络波动调高stream_max_retries重试次数优先使用国内Token173专线七、总结Codex CLI 强大的自定义扩展能力让它不再局限于 OpenAI 官方服务。整套配置的核心逻辑可以总结为三点优先匹配Codex 版本与 wire_api 协议这是配置生效的前提严格规范base_url格式本地服务用http、线上中转使用https结尾固定为/v1遵循安全规范密钥统一使用环境变量注入杜绝明文泄露。结合 Token173 等中转平台搭配本地私有化模型我们可以根据业务自由切换服务端兼顾网络稳定性、数据安全性与使用成本。掌握这套配置方案后Codex 可以完全适配国内各类研发场景成为全场景通用的 AI 编程工具。