Codex CLI 配置全攻略：API Key、base_url 与 config.toml 详解

1. 为什么值得花时间搞定 Codex CLI 的配置Codex CLI 是 OpenAI 推出的一个命令行 AI 编程助手它能在终端里直接读写代码、执行命令、理解项目上下文把“对话式编程”搬进了命令行。很多人第一次接触它卡住的地方不是不会用而是根本连不上——要么是 API Key 没配对要么是 base_url 没写对要么是 config.toml 的格式出了岔子。我自己前前后后帮同事排查过不下二十次配置问题发现 90% 的报错都集中在三个地方Key 的获取方式、base_url 的填写规则、以及 config.toml 的层级结构。这篇内容就是把我踩过的坑、验证过的方案完整梳理一遍。不管你是刚拿到 API Key 的新手还是想接入自定义 Provider 的老手都能在这里找到可以直接抄的配置。我会从最基础的 Key 获取讲起一路讲到多 Provider 切换、config.toml 的完整字段说明、以及那些官方文档里不会写的排查技巧。读完你至少能做到独立完成 Codex CLI 的安装与配置遇到 401、400 这类报错能自己定位原因并且能根据自己的需求灵活切换不同的模型服务。需要提前说明的是Codex CLI 本身是一个开源工具它的配置逻辑并不复杂复杂的是各家模型服务商的接口规范差异。理解了这套配置的“骨架”你换任何一家服务都能快速适配。2. 配置前的整体思路与方案选型2.1 先搞清楚 Codex CLI 的配置到底在管什么Codex CLI 的配置本质上只解决两件事去哪里请求base_url和用什么身份请求API Key。这两件事组合起来就构成了一个“Provider”服务提供方。你可以把它想象成寄快递base_url 是快递公司的收件地址API Key 是你的寄件凭证。地址写错了包裹送不到凭证不对前台不给你寄。Codex CLI 默认走的是 OpenAI 官方的接口地址但它的设计允许你通过 config.toml 覆盖这个地址指向任何兼容 OpenAI 接口规范的服务。这就是为什么很多人会用它来接入其他模型服务——只要对方的接口格式和 OpenAI 一致就能无缝替换。配置文件的位置通常在用户主目录下的.codex/config.tomlWindows 上则是%USERPROFILE%\.codex\config.toml。这个路径很关键因为 Codex CLI 启动时会优先读取这个文件读不到就会用默认值或者直接报错。我见过太多人把配置文件放错目录然后对着“no api key for provider”的报错发呆。2.2 为什么推荐用 config.toml 而不是环境变量Codex CLI 支持两种配置方式环境变量和 config.toml。环境变量的好处是临时、灵活适合快速测试但它的缺点也很明显——不持久、容易冲突、多 Provider 切换时非常麻烦。你想想如果你同时要用三个不同的服务每次切换都要改环境变量、重启终端这个体验有多糟糕。config.toml 的优势在于结构化和可持久化。你可以在一个文件里定义多个 Provider每个 Provider 有自己的 base_url、API Key 环境变量引用、模型名称等参数。切换的时候只需要改一行model_provider的值不用动其他任何东西。而且这个文件是纯文本方便版本管理和备份。提示如果你只是临时测试用环境变量没问题但只要你打算长期使用强烈建议直接上 config.toml。后面讲的多 Provider 切换、模型参数微调都依赖这个文件。2.3 自定义 base_url 的适用场景不是所有人都需要自定义 base_url。如果你只用 OpenAI 官方服务默认配置就够了。但以下几种情况你必须自己配你用的是兼容 OpenAI 接口的第三方服务接口地址和官方不同你在团队内部署了统一的模型网关需要走内部地址你需要根据网络环境选择不同的接入点你想在同一个 CLI 里切换多个不同的模型服务。这些场景的共同点是请求的目标地址不是 OpenAI 官方的https://api.openai.com/v1。这时候base_url 就成了配置的核心。填错了轻则 404重则 401报错信息还往往语焉不详让人摸不着头脑。3. API Key 获取与 config.toml 核心字段详解3.1 API Key 的正确获取姿势API Key 的获取方式取决于你用哪家服务。如果是 OpenAI 官方流程是登录平台账号进入 API Keys 管理页面创建一个新的 Secret Key复制保存。这里有个关键点——Key 只在创建时显示一次关掉页面就再也看不到了。我见过不止一个人创建完 Key 没复制回头找不到只能重新建一个。如果你用的是第三方兼容服务获取方式类似但入口位置各不相同。有的在控制台的“API 管理”里有的在“密钥管理”里有的甚至需要先创建应用才能生成 Key。不管哪家拿到 Key 之后都要妥善保存不要直接写在代码里更不要提交到公开仓库。注意API Key 本质上就是你的账户凭证泄露了别人就能用你的额度。我个人的习惯是把它存在环境变量里config.toml 里只引用变量名不写明文。这样即使配置文件被看到Key 本身也不会暴露。具体做法是在 shell 的配置文件比如.bashrc、.zshrc或 Windows 的环境变量设置里加一行export OPENAI_API_KEY你的Key然后在 config.toml 里这样引用api_key_env OPENAI_API_KEY这样 Codex CLI 启动时会自动从环境变量里读取 Key配置文件里看不到明文安全性高很多。3.2 config.toml 的完整字段说明config.toml 的字段不算多但每一个都有讲究。下面这张表是我整理的常用字段涵盖了绝大多数使用场景字段名作用是否必填常见取值示例model指定默认使用的模型是gpt-4o、gpt-4o-minimodel_provider指定默认使用的 Provider 名称是openai、customapi_key_env从哪个环境变量读取 Key是OPENAI_API_KEYbase_url接口请求的基础地址自定义时必填https://api.openai.com/v1wire_api接口协议类型否chat、responsesquery_params附加的查询参数否api-version2024-02-01这里重点说两个容易出错的字段。第一个是base_url它的值必须是完整的接口前缀不能只写域名。比如你要写https://api.openai.com/v1而不是https://api.openai.com。少了/v1这个路径请求就会打到错误的端点返回 404 或者 401。第二个是wire_api它决定了 Codex CLI 用哪种协议格式发请求。大多数兼容服务用的是chat也就是 Chat Completions 接口少数新服务可能用responses。填错了会导致请求体格式不匹配报 400 错误。3.3 一个最小可用的配置示例先看一个最简单的配置只配一个 OpenAI 官方 Providermodel gpt-4o model_provider openai [model_providers.openai] name OpenAI base_url https://api.openai.com/v1 api_key_env OPENAI_API_KEY wire_api chat这个配置的意思是默认用gpt-4o模型走名为openai的 Provider接口地址是官方地址Key 从OPENAI_API_KEY环境变量读取协议用chat。保存到~/.codex/config.toml之后直接在终端运行codex就能用了。如果你要接入自定义服务只需要把base_url换成对方的地址api_key_env换成对应的环境变量名其他基本不用动。这就是 config.toml 的灵活性所在——结构不变只换值。4. 自定义 Provider 的完整实操流程4.1 从零开始安装与环境准备在配置之前先确认 Codex CLI 已经装好。安装方式取决于你的系统常见的是通过包管理器或者直接下载二进制文件。装完之后运行codex --version能输出版本号就说明安装成功。接下来创建配置目录。如果~/.codex目录不存在手动建一个mkdir -p ~/.codex然后把 config.toml 放进去。这一步看起来简单但很多人会忽略目录是否存在导致配置文件写了却没生效。Codex CLI 不会自动创建这个目录它只会去读读不到就用默认配置或者报错。环境变量也要提前设好。以 Linux/macOS 为例在.zshrc或.bashrc里加上 export 语句然后source一下让配置生效。Windows 用户可以在“系统属性 - 环境变量”里添加或者用 PowerShell 的$env:语法临时设置。4.2 配置自定义 base_url 的三种典型场景场景一接入兼容 OpenAI 接口的第三方服务。这是最常见的需求。假设某服务的接口地址是https://api.example.com/v1Key 存在EXAMPLE_API_KEY环境变量里配置如下model example-model model_provider example [model_providers.example] name Example Service base_url https://api.example.com/v1 api_key_env EXAMPLE_API_KEY wire_api chat场景二走内部网关。团队内部通常有一个统一的模型网关所有请求都走这个地址。配置逻辑一样只是 base_url 换成内网地址Key 换成网关分配的凭证。场景三多 Provider 并存。这是 config.toml 最强大的地方。你可以定义多个 Provider然后通过改model_provider的值来切换model gpt-4o model_provider openai [model_providers.openai] name OpenAI base_url https://api.openai.com/v1 api_key_env OPENAI_API_KEY wire_api chat [model_providers.backup] name Backup Service base_url https://api.backup.com/v1 api_key_env BACKUP_API_KEY wire_api chat想切换到 backup 的时候只需要把model_provider改成backup模型名改成 backup 支持的模型重启 CLI 即可。不用改环境变量不用重装非常干净。4.3 参数计算与选择base_url 到底该填到哪一层这是最容易出错的地方我单独拿出来讲。base_url 的填写规则是填到接口版本号那一层不要带具体的端点路径。举个例子OpenAI 官方的完整请求地址是https://api.openai.com/v1/chat/completions。其中https://api.openai.com/v1是 base_url/chat/completions是 Codex CLI 自己会拼接的端点路径。如果你把 base_url 写成https://api.openai.com/v1/chat/completionsCLI 再拼一次就变成了.../chat/completions/chat/completions直接 404。同理如果某服务的地址是https://api.example.com/openai/v1/chat/completions那 base_url 就应该是https://api.example.com/openai/v1。判断方法很简单找到地址里/chat/completions之前的部分那就是 base_url。有些服务还会在 URL 里带查询参数比如?api-version2024-02-01。这种情况 base_url 里不要带参数而是用query_params字段单独配置[model_providers.azure] name Azure base_url https://your-resource.openai.azure.com/openai/deployments/your-deployment api_key_env AZURE_API_KEY wire_api chat query_params { api-version 2024-02-01 }这样 CLI 发请求时会自动把参数拼到 URL 后面不用你手动处理。5. 常见报错与排查技巧实录5.1 401 报错Key 到底哪里出了问题401 是最常见的报错意思是“身份验证失败”。可能的原因有四种Key 本身错了、Key 没被正确读取、Key 对应的账户没权限、base_url 指向的服务不认这个 Key。排查顺序建议这样先确认环境变量里确实有值用echo $OPENAI_API_KEY看一下注意不要在不安全的环境里执行然后确认 config.toml 里的api_key_env拼写和实际变量名完全一致大小写敏感再确认 base_url 和 Key 是配套的——你不能拿 A 服务的 Key 去请求 B 服务的地址。我遇到过一个很隐蔽的情况Key 复制的时候末尾多了一个空格肉眼完全看不出来但服务端校验就是不过。后来用cat -A才看到那个$前面有个空格。所以复制 Key 之后建议用trim处理一下或者手动检查首尾。5.2 400 报错配置格式与协议不匹配400 通常意味着请求发出去了但服务端觉得格式不对。常见原因有两个wire_api填错了或者模型名称不被支持。如果服务用的是 Chat Completions 接口wire_api必须是chat如果用的是新的 Responses 接口就填responses。填错的话请求体的结构会对不上服务端直接返回 400。模型名称也要确认有些服务对模型名大小写敏感或者需要用特定的前缀。还有一种情况是 config.toml 本身的语法错误。TOML 格式对缩进和引号有要求比如字符串必须用引号包起来布尔值不能加引号。一个标点错了整个文件就解析失败。Codex CLI 在解析失败时往往只报一个笼统的错误不会告诉你具体哪一行有问题。这时候可以用在线的 TOML 校验工具先检查一遍。5.3 “no api key for provider” 的定位方法这个报错的意思是CLI 找到了 Provider 的定义但没找到对应的 Key。原因通常是api_key_env指向的环境变量不存在或者变量存在但当前 shell 会话没加载。排查步骤先确认 config.toml 里api_key_env的值比如是OPENAI_API_KEY然后在终端里echo $OPENAI_API_KEY看有没有输出。如果没有说明环境变量没设或者没生效。如果是刚加的 export 语句记得source一下配置文件或者重开一个终端。Windows 用户要特别注意环境变量分“用户变量”和“系统变量”设置之后需要重启终端才能生效。如果用的是 PowerShell临时设置用$env:OPENAI_API_KEYxxx永久设置要用setx命令。5.4 常见问题速查表报错信息最可能的原因快速修复方法401 UnauthorizedKey 错误或未读取检查环境变量和 api_key_env 拼写400 Bad Requestwire_api 或模型名不对确认协议类型和模型名称404 Not Foundbase_url 路径错误检查是否多写或少写 /v1no api key for provider环境变量不存在设置并 source 环境变量config.toml 解析失败TOML 语法错误用在线工具校验格式连接超时base_url 地址不可达确认网络和地址正确性5.5 几个官方文档不会写的实操心得第一个心得改完 config.toml 一定要重启 CLI。Codex CLI 在启动时读取配置运行中不会热加载。你改了文件但没重启会发现怎么改都没效果然后开始怀疑人生。我早期就因为这个浪费了半小时。第二个心得保留一份能用的最小配置作为回退。当你尝试新 Provider 失败时能快速切回可用的配置不至于完全用不了。我的做法是在 config.toml 里始终保留一个官方 Provider 的定义即使平时不用。第三个心得用codex --help看当前生效的配置。有些版本的 CLI 支持打印当前配置能帮你确认到底读的是哪个文件、哪些值生效了。如果版本不支持就手动确认文件路径和内容。第四个心得多 Provider 场景下模型名和 Provider 要配套。你不能把model设成gpt-4o却把model_provider指向一个只支持其他模型的服务。这种不匹配会导致请求发出去但模型不存在报错信息往往很模糊。6. 多环境切换与配置管理进阶6.1 用 Profile 管理不同场景的配置如果你需要在不同项目、不同环境之间切换每次都手动改 config.toml 太累了。Codex CLI 支持 Profile 机制可以在一个文件里定义多套配置通过--profile参数选择。[profiles.work] model gpt-4o model_provider openai [profiles.personal] model example-model model_provider example用的时候加--profile work或--profile personalCLI 会自动加载对应的配置。这样工作和个人场景完全隔离互不干扰。6.2 配置文件的版本管理与备份config.toml 是纯文本非常适合用 Git 管理。但要注意不要把 API Key 明文写进去。用环境变量引用的方式配置文件里只有变量名这样即使仓库公开也不怕。我的做法是建一个 dotfiles 仓库把 config.toml 放进去Key 通过环境变量注入。换电脑的时候clone 仓库、设置环境变量、装好 CLI五分钟就能恢复完整环境。6.3 团队协作中的配置规范如果是团队使用建议统一 config.toml 的结构只让每个人改自己的环境变量。比如团队约定所有 Provider 的命名规则、base_url 的填写规范、wire_api 的取值这样排查问题时大家说的是同一套语言。另外团队内部可以维护一份“可用 Provider 列表”记录每个 Provider 的地址、支持的模型、注意事项。新人入职直接照着配不用从头摸索。7. 我个人的配置习惯与最后几句实在话配置这件事说难不难说简单也不简单。核心就三个点Key 放对环境变量、base_url 填到正确层级、config.toml 语法别出错。把这三件事做扎实90% 的报错都不会出现。我自己的 config.toml 里常年保留三个 Provider一个官方、一个备用、一个内部网关。平时用官方官方不稳定时切备用团队任务走内部网关。切换只改一行model_provider其他什么都不用动。这套配置我用了大半年没出过问题。最后分享一个小技巧每次改完配置先跑一个最简单的请求验证比如让 CLI 解释一段代码或者生成一个函数。确认通了再去干正事。这样能把配置问题和业务问题分开排查起来快很多。