Codex 是 OpenAI 推出的终端编程智能体开发者可以在命令行里直接交给它“读取项目、修改代码、执行命令”的任务。对很多团队来说真正让 Codex 落地到日常开发的关键不是 CLI 本身而是它能不能灵活接入不同的模型服务。Codex CLI 支持自定义模型提供方只要目标服务提供 OpenAI 兼容 API就可以通过一份配置文件把请求指向指定地址和模型。下面从安装、密钥准备、配置编写、运行验证到错误排查给出完整可复用的操作流程。读完就能在自己的开发机上把 Codex 接到一个独立 API 服务并用脚本批量完成配置。1. 先理解 Codex CLI 如何接入自定义 API1.1 Codex CLI 是客户端不是模型本身很多新手会误以为 Codex 内置了大模型。实际 Codex CLI 是一个交互式编程客户端负责把用户的自然语言指令、项目文件、命令行工具能力编排成请求发给负责推理的模型。模型返回后Codex 再把结果转成代码修改、命令执行等动作。这意味着模型推理可以由不同服务商提供客户端通过标准协议与它们通信。OpenAI 兼容 API 是目前事实上的标准协议。只要服务商暴露了兼容端点Codex 就能像调用官方服务一样调用它。这样做的价值在于不必为每个模型服务商单独写 SDK也不强制绑定某一个账号。团队里有人用便宜的模型跑日常问答有人用推理能力强的模型跑复杂重构都可以通过切换 provider 完成。这里要注意一个区分Codex CLI 本身可以选择使用官方账号体系。codex login会走官方账号授权之后模型请求发往官方服务。若需要接入第三方模型通常不需要登录而是通过 API Key 和自定义 base_url 访问。后面第 2 节会单独说明两种方式的差异。1.2 接入兼容 API 前先确认三个信息无论服务商是谁接入前都要拿到三个信息API 地址、模型名、API 密钥。信息作用从哪里获得Base URL请求端点地址决定请求发往哪里服务商文档或控制台通常形如https://api.example.com/v1Model Name请求中使用的模型标识服务商模型列表如deepseek-chat这类命名API Key鉴权凭证证明调用者有权限服务商控制台创建建议单独创建并设置额度这三个信息在后面的config.toml配置中都有对应字段。最容易出错的是 Base URL 是否包含/v1。不同服务商的约定不同有的地址本身已包含/v1有的需要手动补全。如果看到 404 或 endpoint not found优先检查 Base URL。另外模型名不要凭感觉写。同一个服务商可能同时提供对话模型、代码模型、推理模型模型名直接决定了请求走哪条链路。写错时服务端通常会返回model not found或model is not supported而不是通用错误。1.3 请求协议差异Responses 与 Chat CompletionsCodex 新版默认使用 Responses API也就是/responses端点。但很多第三方服务商只实现了更早的 Chat Completions 协议也就是/chat/completions端点。因此配置中通常需要显式声明wire_api。wire_api的常见取值是chat或responses。当服务商明确宣称“OpenAI 兼容 Chat Completions”时使用wire_api chat。当服务商实现了 Responses 协议或请求端点同时支持两种协议时可以保留wire_api responses。如果配置不匹配可能出现 404、400 或返回内容格式解析失败。判断方法先看服务商文档对 base_url 给出的示例是/v1/responses还是/v1/chat/completions。支持 Chat Completions 的服务商大多数能通过wire_api chat接入 Codex。这样理解后配置文件就不再是死记硬背的模板。2. 安装 Codex CLI 并准备 API 密钥2.1 环境要求与安装命令Codex CLI 基于 Node.js安装前先确认本机有可用的 Node.js 运行时。建议使用 18 或更高版本的 LTS 版本。版本过低时npm 安装依赖可能失败运行阶段也可能出现不兼容。node -v npm -v如果还没有装 Node.js使用 nvm 管理版本会更省心。安装完成后执行npm install -g openai/codex安装完成后验证codex --version如果看到版本号输出说明安装成功。若提示command not found检查 npm 全局安装目录是否在PATH中。在 macOS 或 Linux 下常见目录是/usr/local/bin或$(npm prefix -g)/bin。在 Windows 下检查 npm 全局目录是否已加入系统环境变量。如果 npm 下载缓慢可以使用国内镜像源。比如临时指定镜像源npm install -g openai/codex --registryhttps://registry.npmmirror.com镜像源只影响下载速度不影响包的内容也不改变后续配置流程。2.2 获取 API Key 的两种方式官方登录方式对应 ChatGPT 账号。执行codex login后Codex 会打开浏览器完成 OAuth 授权之后把凭据写入~/.codex/auth.json。这种方式适用于官方订阅用户。第三方模型服务通常不提供 OAuth 登录而是要求调用方在控制台创建 API Key然后通过请求头携带。Codex 的自定义 provider 配置支持从环境变量读取 API Key因此不需要把密钥写进配置文件。具体操作一般在服务商控制台注册并登录模型服务商的开发者平台。找到“API Keys”“令牌”或“访问凭证”菜单。创建 Key并为其设置额度限制如果平台支持。复制 Key临时保存到本地环境变量中避免直接粘贴到聊天窗口或博客示例中。创建 Key 时还应关注权限范围。某些平台允许限定 Key 只能访问特定模型或特定接口。如果后续出现 403可以先检查 Key 的权限。2.3 把 API Key 安全地放入环境变量config.toml中的env_key字段并不是密钥本身而是环境变量名。Codex 发起请求时会从该环境变量读取真实 Key 并放入 Authorization 请求头。这样做的好处是配置文件可以提交到仓库只要不含密钥而密钥仍留在本机或 CI 密钥库中。在 Linux 或 macOS 中临时写入环境变量export MY_API_KEYsk-your-real-key为了让每次打开终端都生效建议把 export 写入~/.bashrc、~/.zshrc或系统级密钥管理工具中echo export MY_API_KEYsk-your-real-key ~/.bashrc source ~/.bashrc在 Windows PowerShell 中$env:MY_API_KEYsk-your-real-key注意不要在生产环境的日志里打印环境变量值。后面排查时如果使用codex --verbose请确认日志输出没有泄露 Authorization 头。3. 用最小配置让 Codex 指向兼容 API3.1 config.toml 字段逐个说明Codex 的全局配置路径是~/.codex/config.toml。可以用下面这段最小配置把请求指向一个 OpenAI 兼容服务model your-model-name model_provider myprovider [model_providers.myprovider] name My Provider base_url https://api.example.com/v1 env_key MY_API_KEY wire_api chat各字段含义如下字段作用示例model默认使用的模型名your-model-namemodel_provider选择哪一个 provider 配置myprovider[model_providers.myprovider]定义 provider 配置块provider 名称必须与model_provider对应nameprovider 展示名称用于日志My Providerbase_urlAPI 请求根地址https://api.example.com/v1env_key保存 API Key 的环境变量名MY_API_KEYwire_api请求协议chat或responseschat常见的两个坑provider 配置块名称写错。model_provider myprovider和[model_providers.myprovider]必须完全一致大小写也敏感。base_url末尾多写/chat/completions。正确做法是写到根地址Codex 会按协议自动拼接端点如果根地址本身已包含/v1不要再追加。3.2 多 Provider 配置示例一个config.toml中可以定义多个 provider方便切换。比如一个配置用于在线 API一个用于本地模型服务model_provider cloud [model_providers.cloud] name Cloud Provider base_url https://api.example.com/v1 env_key CLOUD_API_KEY wire_api chat [model_providers.local] name Local Provider base_url http://127.0.0.1:11434/v1 env_key LOCAL_API_KEY wire_api chat需要切换时修改model_provider指向对应配置或通过命令行参数和环境变量覆盖。Codex 支持在配置文件中使用多个模型提供方这让“同一个 CLI、不同模型”成为可能。本地模型示例中的11434是常见本地推理服务的端口。如果你的本机服务没有运行直接切换会看到连接被拒绝。生产环境里本地服务通常不适合直接作为团队共享接入点因为算力和并发