Codex CLI配置指南：config.toml报错全解析

Codex CLI 近期的更新让不少旧版 config.toml 配置在启动时直接报错。profile = "..." 行、wire_api = "chat" 或 approval_policy = "untrusted" 现在都会阻止启动，另有一些错误则静默失败。最常见的原因是从早期指南中复制了过时的配置。本文整理了一份在 Codex CLI 0.162.1 上可用的自定义供应商配置，编辑后需要运行的检查命令，以及 Codex 在出错时打印的具体信息。

核心配置：最小可用版本

配置文件位于 ~/.codex/config.toml（Windows 下为 C:\Users\<you>\.codex\config.toml），Codex 只在启动时读取它。以下是与自定义供应商配合的最小配置：

**TOML 表头的作用域规则**：TOML 中的 `[table]` 行不是分组标记，而是一个「当前表」的切换指令——从该行开始，直到下一个表头出现之前，所有裸键都属于这个表。这意味着如果误把 `model = ...` 写在 `[model_providers.aihubmix]` 之下，它会变成 `model_providers.aihubmix.model`，顶层 `model` 缺失，Codex 会回退到内置默认模型，而且通常不报错。同理，`env_key`、`base_url` 必须位于供应商表内，`model`、`model_provider`、`model_reasoning_effort` 必须位于任何表头之前。这也是本文强调「顶层键必须写在第一个 `[table]` 行之前」的原因。

**wire_api 与 Responses API**：`wire_api` 指定 Codex 与供应商通信所用的请求/响应协议。`responses` 指 OpenAI 的 Responses API，请求体包含 `input` 数组、`instructions` 等字段，支持推理摘要与工具调用的结构化输出；`chat` 指更早的 Chat Completions API（`messages` 数组）。Codex 新版只在 Responses 语义下实现推理强度、计划工具等特性，因此彻底移除了 `chat` 选项。仅提供 Chat Completions 的第三方供应商必须在前置一层做协议转换代理，把 Responses 请求翻译为 Chat Completions 再翻译回来。
# ~/.codex/config.toml
model = "gpt-6-sol"
model_provider = "aihubmix"
model_reasoning_effort = "high"

[model_providers.aihubmix]
name = "AIHubMix"
base_url = "https://aihubmix.com/v1"
wire_api = "responses"
env_key = "AIHUBMIX_API_KEY"

API Key 通过环境变量传入。macOS/Linux 在 ~/.zshrc 或 ~/.bashrc 中 export AIHUBMIX_API_KEY=sk-...，Windows PowerShell 用 setx AIHUBMIX_API_KEY "sk-..."，然后打开新终端。

三条导致多数失败的规则

• model_provider 必须与表名一致，且表名不能是 openai、ollama 或 lmstudio，这些是 Codex 内置供应商保留的 ID。
• env_key 是变量的名称，不是 Key 本身。codex login 保存在 auth.json 中的凭据永远不会发送给自定义供应商。
• 顶层键必须写在第一个 [table] 行之前。在 TOML 中，表头之后的所有内容都属于该表。

验证配置是否生效

编辑完成后用两条命令检查：

codex exec "say ok"     # 一次非交互请求
codex doctor            # 安装、配置与认证检查

codex exec 会在请求前打印实际生效的设置：model:、provider:、approval:、sandbox: 和 reasoning effort:。这是确认哪个值最终胜出的最快方式。测试中发现，即使配置写了 on-request，非交互运行仍会显示 approval: never——因为没人可问。

Profiles 与项目级配置

Profile 的格式已经改变。现在每个 profile 是独立文件 ~/.codex/<name>.config.toml，只写与默认配置不同的键，且放在顶层：

# ~/.codex/review.config.toml
model_reasoning_effort = "xhigh"
sandbox_mode = "read-only"

通过 codex --profile review 调用。旧的 [profiles.x] 表已不再支持。

项目级 .codex/config.toml 只有在用户配置中标记为可信项目时才会被读取：

[projects."/Users/you/code/my-app"]
trust_level = "trusted"

即便如此，Codex 仍会从项目文件中丢弃 model_provider、model_providers、openai_base_url、profile、notify 等键，防止仓库重定向你的请求。供应商配置应始终放在用户级 ~/.codex/config.toml 中。

优先级顺序

从高到低：CLI 标志与 -c key=value 覆盖、项目 .codex/config.toml（离工作目录最近者优先）、--profile 文件、~/.codex/config.toml、/etc/codex/config.toml、内置默认值。

一个容易踩坑的点：项目文件优先级高于 profile。测试中用户配置、profile 和可信项目分别设置了不同的 model，codex exec --profile fast 最终运行的是项目里的模型，只采纳了 profile 的推理强度；而 -m 标志可以覆盖两者。

沙箱与审批策略

键	取值
sandbox_mode	read-only, workspace-write, danger-full-access
approval_policy	on-request, never, 或粒度化表

workspace-write 允许在工作目录、/tmp 和 $TMPDIR 中写入，但默认无网络，需要在 [sandbox_workspace_write] 下设置 network_access = true。never 只是停止弹窗审批，不会放宽沙箱范围。

沙箱模式与审批策略是两个正交维度：sandbox_mode 决定进程在操作系统层面能做什么（可写哪些路径、能否联网），approval_policy 决定 Codex 在执行动作前是否暂停询问人类。因此把 approval_policy 设为 never 只是取消了交互确认，沙箱边界原封不动；反过来，把 sandbox_mode 设为 danger-full-access 也不会自动获得审批，只是不再有沙箱限制。常见误区是以为 never 等于「放开权限」，实际上在 read-only 下它仍然无法写文件。粒度化审批表允许按命令类型（如 exec、apply_patch）分别设定策略，适合需要精细控制的自动化流程。

代理设置

Codex 没有代理配置键，而是遵循环境变量：

export HTTPS_PROXY=http://127.0.0.1:7890
export NO_PROXY=localhost,127.0.0.1
export CODEX_CA_CERTIFICATE=/path/to/corp-root-ca.pem   # 仅限 TLS 检查型代理

OpenAI 文档只记录了 CODEX_CA_CERTIFICATE，未记录代理变量。但在 0.162.1 上实测，发往自定义供应商的请求确实经过 HTTPS_PROXY、小写 https_proxy 和 ALL_PROXY，且 NO_PROXY 中的主机被正确跳过。

常见报错与修复

legacy profile = "..." config is no longer supported

config.toml 中仍残留 profile = "..." 选择器。把 profile 移入独立文件并删除该行。若残留 [profiles.x] 表，带 --profile x 会报 --profile x cannot be used while ... contains legacy ... config；不带标志时该表被静默忽略。

wire_api = "chat" is no longer supported

改为 responses。只提供 Chat Completions 接口的供应商需要一层转换代理。

model_providers contains reserved built-in provider IDs

重命名名为 openai、ollama 或 lmstudio 的供应商。若要重新指向内置 OpenAI 供应商，应设置顶层 openai_base_url。

approval_policy = "untrusted" is no longer supported

删除该行或改用 on-request。on-failure 已弃用但仍被接受。

Missing environment variable: AIHUBMIX_API_KEY

env_key 指定的变量不在 Codex 启动时的环境中。打开新终端或 source ~/.zshrc。

401 Unauthorized after "Reconnecting..."

请求没有携带 Key。检查 env_key；auth.json 对自定义供应商不适用。

Model metadata for ... not found

这是对 Codex 目录外模型的警告，非 OpenAI 模型出现属正常现象。请求仍可工作，配置模型目录后该警告消失。

Ignored unsupported project-local config keys

项目文件设置了仅限用户级的键，通常是 model_provider。移到 ~/.codex/config.toml。

missing field base_instructions

模型目录条目不完整，整个文件被拒绝。重新生成目录，不要手工编辑。

模型目录（model catalog）机制：Codex 内置一份模型元数据目录，记录每个模型的上下文窗口、推理能力、base_instructions 等内部字段，/model 列表和请求构造都依赖它。当配置的模型名不在目录中时，Codex 会打印 Model metadata for ... not found 警告，用一套通用默认值继续发请求——所以非 OpenAI 模型能跑但可能表现异常。顶层 model_catalog_json 指向自定义目录文件时，它会整体替换内置目录而非合并，因此每个条目必须字段完整；缺失 base_instructions 这类必填字段会导致整个文件被拒绝。稳妥做法是用脚本克隆内置条目再改写模型名，而不是手写。

尚未验证的部分

原文作者明确标注了三处未测试内容：PAC 文件（Codex 无对应设置，第三方文章描述的行为未验证）、桌面应用模型选择器（可能隐藏目录模型，参见 openai/codex#19694，仅测试了 CLI）、以及所有错误测试均未发送真实请求（每个用一次性 CODEX_HOME 和不可达的 base_url）。

自定义模型出现在 /model 中

/model 默认只列出 OpenAI 的模型，除非顶层 model_catalog_json 指向一个目录文件。目录会替换内置列表，且每个条目需要完整的内部字段集，因此最好用脚本生成——AIHubMix 的 Codex CLI 指南提供了一个脚本，克隆内置条目以覆盖其前 30 个模型。用 codex debug models 验证。

要点回顾

• 配置文件只在启动时读取，改完必须重启 Codex。
• wire_api 唯一合法值是 responses，profile 选择器已移入独立文件。
• 项目级配置优先级高于 profile，但无法覆盖供应商设置。
• 自定义供应商的认证只走环境变量，codex login 的凭据不适用。
• 代理依赖标准环境变量，无专用配置键。