Codex config.toml 配置指南：位置、Provider、模型与优先级

Codex 配置不生效时，先别继续往 config.toml 里堆字段。

你可能改错了层级，也可能被 CLI 临时参数覆盖，或者把只能放在用户级的 Provider 配置写进了项目目录。这篇指南先讲清配置文件在哪、谁覆盖谁，再给出最小可用的 Provider 模板和排错顺序。所有字段和规则都以 OpenAI 官方的 Config basics、Advanced Configuration 和 Configuration Reference 为准。

如果你还没装好 Codex，先看《Codex 安装教程》；如果你打算用环境变量传 Key，配套阅读《Codex 环境变量怎么配》。

速查：config.toml 最常用的几个字段

这些字段都来自官方 Config basics 和 Advanced Configuration 页面。字段名拼错时 Codex 不一定报错，可能只是静默忽略，所以写之前最好对照一次官方参考。

config.toml 在哪里：按系统找文件

官方文档说明，Codex 的本地状态放在 CODEX_HOME 下，默认是用户目录里的 .codex 文件夹；用户级配置文件就是其中的 config.toml。另外，项目里也可以放 .codex/config.toml，作为项目级配置。

macOS

用户级配置路径是 ~/.codex/config.toml，也就是 /Users/你的用户名/.codex/config.toml。.codex 是隐藏目录，在访达里看不到时，可以直接用终端打开：

ls -la ~/.codex
open -e ~/.codex/config.toml

Windows

用户级配置在 %USERPROFILE%\.codex\config.toml，例如 C:\Users\你的用户名\.codex\config.toml。在 PowerShell 里查看和编辑：

Get-ChildItem "$env:USERPROFILE\.codex"
notepad "$env:USERPROFILE\.codex\config.toml"

用记事本保存时请确认编码是 UTF-8。AI Code With 的 Windows 配置脚本就是专门用"UTF-8 无 BOM"写入文件的，避免编码问题导致 Codex 读不出配置。

Linux

路径同样是 ~/.codex/config.toml：

ls -la ~/.codex
nano ~/.codex/config.toml

另外，Unix 系统上如果存在 /etc/codex/config.toml，它会作为系统级配置被读取，优先级低于你的用户配置。

改之前先备份

macOS / Linux：

cp ~/.codex/config.toml ~/.codex/config.toml.backup

Windows PowerShell：

Copy-Item "$env:USERPROFILE\.codex\config.toml" "$env:USERPROFILE\.codex\config.toml.backup"

文件不存在时，先创建一个最小配置，不要复制一份几十行的"大而全模板"。字段越多，出问题时越难判断是哪一行造成的。

配置优先级：谁覆盖谁

这是 config.toml 最容易踩坑的地方。官方文档给出的解析顺序（从高到低）是：

1. 命令行参数和 --config 临时覆盖；
2. 项目配置文件 .codex/config.toml，从项目根目录到当前目录逐层加载，离当前目录越近的越优先，并且只在受信任的项目里加载；
3. 用 --profile 名称 选中的 profile 文件 ~/.codex/名称.config.toml；
4. 用户配置 ~/.codex/config.toml；
5. 登录工作区下发的云端托管默认配置（如果有）；
6. 系统配置 /etc/codex/config.toml（Unix，如果存在）；
7. 内置默认值。

所以，当你发现"明明改了 config.toml 却没生效"，第一件事是检查启动命令里有没有带 --model 或 --config，第二件事是检查当前项目里有没有 .codex/config.toml 把它覆盖了。

模型切换：先用一次性参数验证

当前 CLI 支持临时指定模型：

codex --model <模型 ID>

也可以临时覆盖任意配置项：

codex --config model='"<模型 ID>"'

官方说明 --config 的值按 TOML 解析，所以字符串外面要有一层双引号，再用单引号包住防止被 shell 拆开。引号写错是最常见的问题。

临时覆盖很适合用来判断：到底是配置文件写错了，还是模型本身不可用。如果 --model 能跑通，而写进 config.toml 跑不通，问题就在文件本身或优先级上。

Profile：给不同场景准备不同配置

如果你经常在"日常编码"和"深度审查"两种模式之间切换，可以用 profile。官方文档说明，传入 --profile 名称 时，Codex 会先加载 ~/.codex/config.toml，再叠加 ~/.codex/名称.config.toml：

codex --profile deep-review
codex exec --profile deep-review "review this change"

profile 文件里直接写顶层字段，只写和基础配置不同的部分即可。需要注意的是，官方文档写明：从 Codex 0.134.0 开始，--profile 不再读取 config.toml 里的 [profiles.名称] 段，顶层的 profile = "名称" 也不再支持。如果你的旧配置还这么写，需要迁移到单独的 profile 文件。

自定义 Provider 的最小结构

官方示例里，自定义 Provider 的结构是这样的：

model = "<模型 ID>"
model_provider = "custom"

[model_providers.custom]
name = "My Provider"
base_url = "https://<服务商给出的地址>/v1"
env_key = "PROVIDER_API_KEY"
wire_api = "responses"

写完后检查四件事：

• model_provider 的值和 [model_providers.xxx] 里的 ID 完全一致；
• base_url 来自服务商当前文档，不要凭记忆写；
• env_key 只写环境变量的名字，不是 Key 本身；
• model 是服务商 API 里真实存在的模型 ID。

另外几条官方规则也要知道：

• 自定义 Provider 不能使用保留的内置 ID：openai、ollama 和 lmstudio；
• 如果只是想把内置 OpenAI Provider 指向一个代理，用 openai_base_url 就够了，不需要新建 Provider；
• 设置 requires_openai_auth = true 时，Codex 使用 OpenAI 认证（ChatGPT 登录或 API Key），并忽略 env_key；
• experimental_bearer_token 可以直接写 Token，但官方明确不推荐，建议用 env_key。

环境变量怎么设置、在不同系统里怎么持久化，见《Codex 环境变量怎么配：macOS、Linux、Windows 与排错》。

为什么项目配置"写了却没生效"

官方文档说明，Codex 会从项目根目录一路走到当前工作目录，加载沿途找到的每个 .codex/config.toml，但只在项目受信任时才加载。项目不受信任时，项目里的 .codex/ 配置、hooks 和规则都会被忽略。

更重要的是，项目级配置不能覆盖下面这些和凭据、认证相关的字段：openai_base_url、chatgpt_base_url、model_provider、model_providers、notify、profile、profiles、otel 等。Codex 遇到它们会忽略并在启动时打印警告。

所以如果你把 model_provider = "xxx" 写进项目的 .codex/config.toml，它不会生效。Provider、Base URL 这类配置，应该放在用户级的 ~/.codex/config.toml 里。

常用配置项怎么选

approval_policy：什么时候让你确认

approval_policy 控制 Codex 在执行它生成的命令前，什么时候暂停并请你确认。官方示例里用的是 on-request，表示在需要时请求确认；never 则表示不再弹出确认。新手建议保持需要确认的设置，等你清楚 Codex 平时会执行哪些命令，再考虑放宽。官方文档还提到，旧配置里的 approval_policy = "untrusted" 已经退役，如果你的文件里还有这一行，需要按官方迁移说明调整。

sandbox_mode：命令能访问多大范围

sandbox_mode 决定 Codex 执行命令时能访问多少文件和网络。官方示例是 workspace-write，也就是允许在工作区内写入。除此之外，官方还提供了命名的权限配置，内置的有 :read-only、:workspace 和 :danger-full-access 三种。名字里带 danger 的那个，顾名思义只适合你完全清楚后果的隔离环境。

web_search：联网搜索用哪种模式

官方文档说明，本地会话默认开启联网搜索，并且默认使用缓存模式。可选值有四个：cached 是默认值，从 OpenAI 维护的搜索缓存返回结果；indexed 只在搜索索引放行时才访问外网；live 获取最新的网页数据，效果和命令行的 --search 一样；disabled 则完全关闭搜索工具。官方特别提醒，网页结果应当被视为不可信内容。

model_reasoning_effort：推理强度

model_reasoning_effort 用来调整模型的推理强度，前提是当前模型支持。官方示例值是 medium。日常小改动保持默认即可，跨文件重构或难排查的问题再调高；调高通常意味着更慢、消耗更多 token。

shell_environment_policy：哪些环境变量传给子命令

Codex 运行命令时，会把环境变量传给它启动的子进程。官方提供了 shell_environment_policy 来控制传哪些。需要注意一个默认行为：ignore_default_excludes 默认是 true，这意味着默认不会自动过滤名字里带 KEY、SECRET、TOKEN 的变量。如果你希望自动过滤这类敏感变量，需要把它设为 false：

[shell_environment_policy]
ignore_default_excludes = false

[shell_environment_policy.filters]
"PATH" = "include"
"HOME" = "include"

如果你的终端里设置了各种 API Key，又担心 Codex 执行的命令能读到它们，这一项值得认真配置。

从零写一份配置的完整步骤

如果你的 ~/.codex 里还没有 config.toml，可以按下面的顺序来，每一步都能单独验证：

1. 先不写配置，直接跑通官方登录。运行 codex，按提示登录，确认能正常对话。这一步证明安装和网络都没问题。
2. 只加一行 model。在 config.toml 里写一行 model = "<模型 ID>"，重启 Codex，用 /status 看当前模型是否变了。
3. 再加 Provider。如果要接第三方服务，加上 model_provider 和对应的 [model_providers.xxx] 段，并设置好 env_key 对应的环境变量。
4. 发最小请求。只让 Codex 回答一句话，确认请求能成功返回。
5. 核对调用记录。到服务商后台看这次请求的时间、模型和 Key 是否对得上。
6. 最后再调体验类选项。审批策略、沙箱、联网搜索这些，等基础链路稳定后再逐项调整。

这样做的好处是，每加一项都知道它有没有生效；一旦出错，回退一步就能定位问题。

用 AI Code With 的配置

AI Code With 的 Codex（终端）文档提供了一套现成的配置：Codex 专用接口 https://api.aicodewith.ai/chatgpt/v1，走 Responses 路线，使用 requires_openai_auth = true，并把你的 Key 写进 ~/.codex/auth.json。文档里分别给出了 Windows PowerShell 脚本和 macOS / Linux 的 shell 脚本。

不过，AI Code With 的示例里有个别字段没有出现在 OpenAI 最新的 Configuration Reference 中。因此不建议永久复制整段配置，更稳的做法是：

1. 先理解上面讲的 Provider 配置结构；
2. 注册 AI Code With 账号，创建一个专门给 Codex 用的 API Key；
3. 打开当前的 Codex 配置页，核对当天的接口地址、模型和认证字段；
4. 删除当前 Codex 版本不识别的字段；
5. 启动 codex 发一条最小请求验证；
6. 在平台里检查调用记录，确认请求真的走到了这条路线。

创建 API Key →

团队协作时怎么分配配置

多人协作的项目里，配置文件该放哪，可以按一个简单原则来分：和个人凭据、Provider 有关的放用户级，和项目约定有关的放项目级。

• 用户级 ~/.codex/config.toml：模型 Provider、Base URL、认证方式、个人偏好的推理强度。这些内容因人而异，也可能包含敏感信息，不应该提交到仓库。
• 项目级 .codex/config.toml：和这个项目本身有关、所有人都应该一致的设置。提交前确认里面没有任何 Key 或私有地址。
• 项目规则说明：代码风格、测试命令、目录约定这类文字说明，更适合写进 AGENTS.md，而不是 config.toml。

这样分开之后，新同事拉下仓库，只需要配好自己的用户级配置就能开始工作，不会因为别人的 Provider 设置而连到错误的服务。

常见报错对照表

遇到 401 和 429，分别看《Codex 401 Unauthorized 怎么解决》和《Codex 429 Too Many Requests 怎么解决》。

配置不生效时按这个顺序查

1. 先看 ~/.codex/config.toml 的内容是不是你以为的那样；
2. 检查当前启动命令有没有 --model、--config 或 --profile；
3. 确认项目是否受信任，项目里有没有 .codex/config.toml；
4. 确认 Provider ID、Base URL 和模型 ID 三者对得上；
5. 确认认证方式：codex login status，或者 env_key 对应的环境变量；
6. 最后发一条最小请求验证，并在调用记录里核对。

常见问题

Codex 的 config.toml 默认在哪里？

用户级配置在 CODEX_HOME 下的 config.toml，CODEX_HOME 默认是 ~/.codex。Windows 上就是 %USERPROFILE%\.codex\config.toml。

项目里的 .codex/config.toml 和用户配置哪个优先？

项目配置优先级更高，但只在受信任的项目里加载，而且不能覆盖 Provider、Base URL、profile 等和认证相关的字段。

可以在 config.toml 里直接写 API Key 吗？

官方提供了 experimental_bearer_token，但明确不推荐。建议用 env_key 指向环境变量，或者用 requires_openai_auth = true 走 OpenAI 认证。

CLI 和 IDE 插件用的是同一份配置吗？

是的。官方文档说明 Codex CLI 和 IDE 插件共享同一套配置层。

怎么临时换一个模型试试？

用 codex --model <模型 ID>，或者 codex --config model='"<模型 ID>"'。临时参数优先级最高，不会改动你的配置文件。

配置改坏了怎么恢复？

如果改之前做了备份，直接用 config.toml.backup 覆盖回去。没有备份的话，先把文件精简到只剩 model 和 model_provider 等最少字段，跑通后再逐项加回去。

免费注册，用自己的 Key 配置 Codex →

相关阅读

• 《Codex 环境变量怎么配》
• 《Codex API Key 怎么配置》
• 《Codex auth.json 是什么》
• 《Codex 怎么收费》

资料来源

• OpenAI：Config basics
• OpenAI：Advanced Configuration
• OpenAI：Configuration Reference
• AI Code With：Codex（终端）