Codex CLI 新手配置教程：config.toml 完整示例、第三方 API 接入与生效验证

国内用户第一次配置 Codex CLI，通常会同时遇到四个问题：找不到真正生效的 config.toml，不知道第三方接口需要哪些字段，不敢把 API Key 写进文件，以及无法区分“配置能解析”和“接口真能调用”。

本文按实际操作顺序完成整条链路：找到配置 → 复制示例 → 替换模型和地址 → 设置 Key → 严格校验 → 发送最小请求 → 按错误定位。

适用边界：Codex CLI 0.145.0，核验日期 2026-07-27。若你的 CLI 版本高于 0.145.0，仍可参照本文步骤，但建议对照官方 Changelog 确认字段是否有增减。文中的占位地址和模型不能直接使用；由于没有提供真实第三方凭据，第三方端到端调用结果为待实际环境验证。

接入前先确认：服务必须兼容 Responses API

如果使用官方服务，可以运行：

codex login

然后按照终端提示完成登录，不需要定义自定义模型提供方。

如果使用第三方 API，请先向服务方确认三项信息：

• 实际可用的模型 ID；
• API 基础地址；
• 是否兼容 OpenAI Responses API。

仅支持 Chat Completions 的接口不足以驱动本文的 Codex 配置。“能返回文本”也不是完整兼容的证明：流式事件、工具调用或推理相关字段仍可能失败。本文不为任何具体第三方服务背书，兼容性必须由服务方文档和真实请求共同证明。

如果不确定第三方服务是否真正兼容 Responses API，可以用 curl 发送一条最小请求快速判断：

curl -s -w "\nHTTP %{http_code}\n" \
  "https://api.example.com/v1/responses" \
  -H "Authorization: Bearer $CODEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"YOUR_MODEL_ID","input":"hi"}'

如果返回 404 或提示路由不存在，说明该地址可能未实现 Responses 端点。若返回 401/403 则是认证问题，200 且有正常 JSON 响应体则初步通过。注意：这只是快速判断，完整的流式、工具调用和推理字段兼容性仍需通过 Codex CLI 实际验证。## 步骤 1：找到 Codex 实际读取的配置文件

默认用户配置路径是：

~/.codex/config.toml

如果设置过 CODEX_HOME，配置文件会改为该目录下的 config.toml。请在准备运行 Codex 的终端中确认，而不是凭文件搜索结果猜路径。

PowerShell

$codexHome = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { Join-Path $HOME ".codex" }
$codexHome
New-Item -ItemType Directory -Force $codexHome | Out-Null
notepad (Join-Path $codexHome "config.toml")

Bash 或 Zsh

codex_home="${CODEX_HOME:-$HOME/.codex}"
printf '%s\n' "$codex_home"
mkdir -p "$codex_home"
${EDITOR:-vi} "$codex_home/config.toml"

Windows 原生终端和 WSL 拥有不同的用户主目录。你在哪个环境运行 codex，就应修改哪个环境中的配置。

Codex 的完整配置优先级从高到低是：

CLI 参数与 --config 覆盖
> 项目配置
> Profile 配置
> 用户配置
> 系统配置
> 内置默认值

自定义提供方还有额外限制：model_provider 和 model_providers 等本机设置不能由项目级 .codex/config.toml 覆盖。因此，下面的第三方 API 配置必须放到用户级 config.toml。

步骤 2：复制第一份可用结构

把以下内容完整复制到用户级 config.toml：

#:schema https://developers.openai.com/codex/config-schema.json

model = "YOUR_MODEL_ID"
model_provider = "example"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[model_providers.example]
name = "Example Responses API"
base_url = "https://api.example.com/v1"
env_key = "CODEX_API_KEY"
wire_api = "responses"

这里的“完整示例”是指首次连接所需字段完整，不是把 Codex 所有参数一次性塞进文件。先让最小链路工作，再增加其他配置，更容易定位错误。

本文已使用 TOML 解析器读取这段配置，并对 Codex CLI 0.145.0 的固定 JSON Schema 进行校验，两项均通过。

配置字段速览：approval_policy = "on-request" 表示执行需要越过安全边界时请求用户批准；sandbox_mode = "workspace-write" 将文件操作限制在工作区目录内。这两个字段影响 Codex 的安全行为，首次配置建议保持上述值，熟悉后再按需调整。## 步骤 3：只替换模型和 API 地址

需要替换的值只有两个：

model = "YOUR_MODEL_ID"
base_url = "https://api.example.com/v1"

• model 改为服务方明确列出的模型 ID，大小写和符号都要一致。
• base_url 改为服务方给出的基础地址。是否带 /v1 以文档为准，不能机械添加或删除。

其他字段先保持不变：

字段	含义
model_provider = "example"	选择名为 example 的提供方配置
[model_providers.example]	定义这个提供方；表名必须与上一项一致
env_key = "CODEX_API_KEY"	从名为 CODEX_API_KEY 的环境变量读取密钥
wire_api = "responses"	按 Responses API 协议发起请求
approval_policy = "on-request"	需要越过既有边界时请求批准
sandbox_mode = "workspace-write"	将日常文件操作限制在工作区边界内

不要把真实 Key 填到 env_key。它需要的是“环境变量名称”，不是密钥内容。

步骤 4：在当前终端设置 API Key

下面的方法不会回显输入，只对当前 Shell 进程及其子进程有效。设置完成后，必须从同一个终端启动 codex；关闭终端，变量就会失效。

PowerShell：隐藏输入并设置当前进程变量

$secureKey = Read-Host "输入第三方 API Key" -AsSecureString
$credential = [System.Net.NetworkCredential]::new("", $secureKey)
$env:CODEX_API_KEY = $credential.Password
Remove-Variable credential, secureKey

Bash：使用 read -rsp

read -rsp "输入第三方 API Key: " CODEX_API_KEY
echo
export CODEX_API_KEY

Zsh：使用 Zsh 的变量提示语法

read -rs "CODEX_API_KEY?输入第三方 API Key: "
echo
export CODEX_API_KEY

“不回显”只表示输入时屏幕不显示字符。Key 仍存在于当前进程内存和子进程环境中。不要把 Key 放进文章、命令参数、截图或日志，也不要把完整终端记录公开。

本教程不默认教你把 Key 永久写入启动文件。那样会产生明文文件、Shell 历史、同步备份和共享电脑风险。确需持久化时，应优先使用操作系统密钥管理方案，并限制相关文件权限。

设置完成后，建议立即验证环境变量是否生效：

• PowerShell：Get-ChildItem Env:CODEX_API_KEY（会显示变量值，仅用于验证）
• Bash/Zsh：echo $CODEX_API_KEY（会回显 Key，验证后建议清除终端历史）

如果变量为空，说明设置未在当前终端生效——请确认你在同一终端中执行了上述命令，且没有关闭过终端窗口。## 步骤 5：先做配置解析验证

确认当前 CLI 版本：

codex --version

本文实际核验的版本输出是：

codex-cli 0.145.0

然后启用严格配置模式：

codex --strict-config

它会在 config.toml 中存在当前版本不认识的字段时直接报错。进入登录、项目选择或交互界面后，可以按 Ctrl+C 结束检查。

注意：--strict-config 只证明配置可以被当前 CLI 严格加载，不能证明第三方地址、模型和密钥有效。

步骤 6：发送一条真实最小请求

在刚才设置 Key 的同一终端执行：

codex exec --strict-config --skip-git-repo-check "只回复：连接测试成功"

预期结果形态是：终端返回一条简短模型响应，并且没有认证、路由或模型错误。本文没有可用于第三方服务的真实地址和凭据，因此该结果标记为待实际环境验证，不展示伪造的成功输出。

即便这条文本请求成功，也只证明最小文本链路可用。后续使用中如果出现流式中断、工具调用失败或推理字段异常，说明第三方 Responses 实现仍可能不完整。

出错时按现象定位

错误或现象	优先检查
配置解析错误、unknown field	是否使用英文引号；参数是否写进错误的 TOML 表；字段是否属于当前版本
当前终端读取不到环境变量	是否在同一 Shell 中设置并启动 Codex；变量名是否与 env_key 一致
401	Key 错误或过期；服务方要求的认证方式是否不同
403	Key 是否具有模型权限；账户、套餐或区域是否受限
404	base_url 是否错误；/v1 是否按文档填写；是否真的存在 Responses 路由
model not found	模型 ID 是否拼写正确、是否已向当前账户开放
修改配置后没有变化	是否混用 Windows 与 WSL；是否设置了 CODEX_HOME；是否被 CLI、项目或 Profile 覆盖
文本能返回，流式或工具仍失败	第三方 Responses 兼容可能不完整，向服务方核对事件流、工具和推理字段

不要通过删除安全边界或随机替换参数来掩盖连接错误。状态码用于定位认证和路由，配置优先级用于定位“改了却不生效”，真实功能测试用于判断 Responses 兼容程度。

完成后的检查清单

• 已确认实际使用的用户配置目录，而不是只找到一个同名文件。
• model 和 base_url 来自服务方文档，没有凭空猜测。
• 服务明确支持 Responses API，而不只是 Chat Completions。
• API Key 只存在于当前终端环境变量，没有写进 TOML、参数、截图或日志。
• codex --strict-config 已通过配置解析阶段。
• codex exec 的真实请求已在自己的第三方环境中验证。
• 文本、流式、工具和推理兼容性没有被混为一谈。

完成以上步骤后，你得到的是一份适合首次使用的完整配置，而不是难以维护的全参数堆叠。以后每增加一个字段，都应先说明它解决的具体问题，再验证实际行为。

FAQ：常见问题快速索引

Q：为什么我的配置改了却不生效？

A：最常见的原因是混淆了终端环境。请回到上文「步骤 1：找到 Codex 实际读取的配置文件」，确认你修改的是 Codex 实际读取的配置文件，并检查是否设置了 CODEX_HOME 变量。

Q：Key 明明设了为什么还是报 401？

A：先用 echo $CODEX_API_KEY（Bash/Zsh）或 Get-ChildItem Env:CODEX_API_KEY（PowerShell）确认变量已设置且值正确。如果变量为空，说明当前终端未生效——请在同一终端中重新执行「步骤 4：在当前终端设置 API Key」。

Q：WSL 与 Windows 原生终端到底用哪个？

A：你在哪个终端运行 codex 命令，就应修改哪个环境中的配置。两者的用户主目录不同，配置文件互不影响。详情见「步骤 1」中的说明。

Q：codex exec 返回的不是预期响应怎么办？

A：直接跳到「出错时按现象定位」章节，按表格中的现象逐一排查。如果表格未覆盖你的情况，优先核对 base_url 和模型 ID 是否与第三方文档完全一致。

官方资料

• Codex 配置基础与优先级
• Codex 自定义模型提供方
• Codex config.toml 配置参考
• Codex 沙箱与审批默认配置
• Codex 官方 JSON Schema

参考文档

Codex CLI 参数会随版本更新。完整参数表、可复制配置示例和版本核验记录请参考：

Codex CLI 参数配置完整参考