2026-10-31 更新:全文按 Codex CLI 0.166.0(2026-10-30 发布的最新正式版)重新实测。新增可直接复制的完整配置、profile 实测、model_reasoning_effort 可选值、GPT-6.1 Terra 写法、0.166.0 新增的 codex doctor --network-only,以及报错原文。
Codex 配置不生效时,先别继续往 config.toml 里堆字段。
你可能改错了层级,也可能被命令行参数覆盖,或者把只能放在用户级的 Provider 配置写进了项目目录。这篇先讲清配置文件在哪、谁覆盖谁,再给出接 AI Code With 的完整配置和排错顺序。字段和规则以 OpenAI 官方的 Config basics、Advanced Configuration 和 Configuration Reference 为准;文中每条命令都在 Codex CLI 0.166.0 上用本站 Key 实际跑过。
还没装好 Codex 的,先看《Codex 怎么用》;只想知道 Key 写在哪的,看《Codex API Key 怎么配置》。
先说结论
- 用户级配置在 ~/.codex/config.toml(Windows 是 %USERPROFILE%\.codex\config.toml)。
- 接第三方服务:在全局 config.toml 里写 model_provider 和 [model_providers.aicodewith],Key 写进 experimental_bearer_token,name 写 "aicodewith"。这些字段写进项目的 .codex/config.toml 会被忽略。
- 覆盖顺序记一句:命令行参数 > profile > 全局 config.toml(受信任项目里的 .codex/config.toml 排在命令行参数和 profile 之间)。
- profile 现在是单独的文件 ~/.codex/名称.config.toml,用 --profile 名称 选中;config.toml 里旧的 [profiles.xxx] 段会让 --profile 直接报错。
- model_reasoning_effort 的可选值由模型决定;接口实测 gpt-6.1-terra 接受 none、minimal、low、medium、high、xhigh、max。
实测环境和结果
我们在一台干净的 Linux 机器上用 npm 安装 @openai/codex@0.166.0,codex --version 输出 codex-cli 0.166.0。用独立的 CODEX_HOME 写入下文的完整配置,再逐项跑 codex exec:
| 测试 | 命令 | 结果 | 用时 |
|---|---|---|---|
| 全局配置 | codex exec "只回复:OK" | model: gpt-6.1-terra,provider: aicodewith,回复 OK | 约 2.7 秒 |
| profile 覆盖全局 | codex exec --profile deep "只回复:OK" | model 变成 gpt-6.1-sol,reasoning effort 变成 high | 约 4.5 秒 |
| 命令行参数覆盖 profile | codex exec --profile deep -m gpt-6.1-terra -c model_reasoning_effort='"low"' ... | model 回到 gpt-6.1-terra,reasoning effort 是 low | 约 2.8 秒 |
| 小任务 | 让 Codex 修 calc.py 里的 bug、新建测试并运行 | 改了 1 行,新建 test_calc.py,测试通过 | 约 12.9 秒 |
| 项目配置写 Provider | 项目 .codex/config.toml 写 model_provider 和 model_providers | 打印忽略警告,请求照常走全局 Provider | 约 4.2 秒 |
全局配置那一次的启动信息原文:
OpenAI Codex v0.166.0
--------
model: gpt-6.1-terra
provider: aicodewith
approval: never
sandbox: workspace-write [workdir, /tmp, $TMPDIR]
reasoning effort: medium
reasoning summaries: none
--------
user
只回复:OK
codex
OK
速查:config.toml 最常用的几个字段
| 字段 | 作用 | 示例 |
|---|---|---|
| model | 默认使用的模型 | model = "gpt-6.1-terra" |
| model_provider | 使用哪个 Provider,对应 [model_providers.<id>] | model_provider = "aicodewith" |
| experimental_bearer_token | 写在 Provider 段里,请求时带上的 Key | experimental_bearer_token = "sk-你的Key" |
| model_reasoning_effort | 推理强度,可选值取决于模型 | model_reasoning_effort = "medium" |
| plan_mode_reasoning_effort | Plan 模式单独的推理强度 | plan_mode_reasoning_effort = "high" |
| approval_policy | 什么时候暂停并请求你确认 | approval_policy = "on-request" |
| sandbox_mode | 执行命令时的文件和网络访问范围 | sandbox_mode = "workspace-write" |
| web_search | 联网搜索模式 | web_search = "cached" |
字段名拼错时 Codex 不一定报错,可能只是静默忽略,所以写之前最好对照一次官方参考。
config.toml 在哪里:按系统找文件
官方文档原文:「User-level configuration lives in ~/.codex/config.toml. You can also add project-scoped overrides in .codex/config.toml files.」出处:Configuration Reference。
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,避免编码问题导致 Codex 读不出配置。
Linux
路径同样是 ~/.codex/config.toml:
ls -la ~/.codex
nano ~/.codex/config.toml
Unix 系统上如果存在 /etc/codex/config.toml,它会作为系统级配置被读取,优先级低于你的用户配置。
设了 CODEX_HOME 时
CODEX_HOME 默认是 ~/.codex。如果你把它指向别的目录,config.toml、profile 文件和 auth.json 都要放到新目录里。最快的确认办法是 0.166.0 新增的网络诊断,它会直接打印实际读到的是哪个 config.toml(见后文「用 codex doctor 先查一遍」)。
改之前先备份
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"
文件不存在时,先创建一个最小配置,不要复制一份几十行的大而全模板。字段越多,出问题时越难判断是哪一行造成的。
可直接复制的完整配置(接 AI Code With)
把下面整段写进全局 ~/.codex/config.toml,只需把 sk-你的Key 换成自己的 Key:
# ~/.codex/config.toml
model_provider = "aicodewith"
model = "gpt-6.1-terra"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
[model_providers.aicodewith]
name = "aicodewith"
base_url = "https://api.aicodewith.ai/chatgpt/v1"
wire_api = "responses"
experimental_bearer_token = "sk-你的Key"
写完后检查四件事:
- model_provider 的值和 [model_providers.xxx] 里的 ID 完全一致,这里都是 aicodewith;
- base_url 来自服务商当前文档,不要凭记忆写;
- experimental_bearer_token 引号里是完整的 Key,前后没有空格;
- model 是服务商那边真实存在的模型 ID,全小写。
然后运行一条最小请求:
codex exec "只回复:OK"
启动信息里出现 provider: aicodewith 和你写的 model,并且回复 OK,就说明配置生效了。再到控制台调用记录里核对这次请求的时间和模型。
官方文档原文:model_provider 是「Provider id from model_providers (default: openai)」;wire_api 是「responses is the only supported value, and it is the default when omitted」。出处:Configuration Reference。
另外几条官方规则也要知道:
- 自定义 Provider 不能使用保留的内置 ID:openai、ollama 和 lmstudio;0.165.0 起还内置了 Google Cloud Vertex AI Provider(model_provider = "gcp",据 rust-v0.165.0 release),自己的 Provider 也别起这个名字;
- 如果只是想把内置 OpenAI Provider 指向一个代理,用 openai_base_url 就够了,不需要新建 Provider;
- Provider 和 Key 只能写在全局 ~/.codex/config.toml,写在项目 .codex/config.toml 里会被忽略(见下一节)。
环境变量和这个文件冲突时谁生效,见《Codex 环境变量怎么配》。
配置优先级:谁覆盖谁
日常记住一句就够:命令行参数 > profile > 全局 config.toml。官方文档给出的完整解析顺序(从高到低)是:
- 命令行参数(-m / --model、-c / --config 等);
- 项目配置文件 .codex/config.toml,从项目根目录到当前目录逐层加载,离当前目录越近越优先,并且只在受信任的项目里加载;
- 用 --profile 名称 选中的 profile 文件 ~/.codex/名称.config.toml;
- 用户配置 ~/.codex/config.toml;
- 登录工作区下发的云端托管默认配置(如果有);
- 系统配置 /etc/codex/config.toml(Unix,如果存在);
- 内置默认值。
我们用同一份全局配置(gpt-6.1-terra、medium)和一个 profile 文件(gpt-6.1-sol、high)实测了这个顺序:
| 启动方式 | 启动信息里的 model | reasoning effort |
|---|---|---|
| codex exec | gpt-6.1-terra | medium |
| codex exec --profile deep | gpt-6.1-sol | high |
| codex exec --profile deep -m gpt-6.1-terra -c model_reasoning_effort='"low"' | gpt-6.1-terra | low |
所以「明明改了 config.toml 却没生效」时,第一件事是检查启动命令里有没有带 --model、--config 或 --profile,第二件事是检查当前项目里有没有 .codex/config.toml 把它覆盖了。
项目配置管不了 Provider、Base URL 和认证
官方文档原文:「Codex ignores the following keys in project-local .codex/config.toml and prints a startup warning when it sees them: openai_base_url, chatgpt_base_url, apps_mcp_product_sku, model_provider, model_providers, notify, profile, profiles, experimental_realtime_ws_base_url, and otel.」出处:Advanced Configuration · Project config files。
我们在 0.166.0 上又测了一次:在受信任项目的 .codex/config.toml 里写了 model = "gpt-6.1-sol"、一个不存在的 model_provider,以及改写 aicodewith 段的 base_url 和 Key(都填成错误值)。结果 model 生效了(切到 gpt-6.1-sol),Provider、地址和 Key 全部被忽略,请求照常用全局配置成功返回,启动时打印了这条警告(路径换成了 <项目>):
warning: Ignored unsupported project-local config keys in <项目>/.codex/config.toml: model_provider, model_providers. If you want these settings to apply, manually set them in your user-level config.toml.
好处是 Key 不会跟着项目仓库被提交出去,新同事拉下仓库也不会连到别人的服务。
Profile:给不同场景准备不同配置
传入 --profile 名称 时,Codex 先加载 ~/.codex/config.toml,再叠加 ~/.codex/名称.config.toml。profile 文件里直接写顶层字段,只写和基础配置不同的部分。比如做大改动时用的 deep profile:
# ~/.codex/deep.config.toml
model = "gpt-6.1-sol"
model_reasoning_effort = "high"
使用:
codex --profile deep
codex exec --profile deep "review this change"
官方文档原文:「In Codex 0.134.0 and later, --profile no longer reads [profiles.profile-name] from config.toml, and the top-level profile = "profile-name" selector is no longer supported.」出处:Advanced Configuration · Profiles。
如果 config.toml 里还留着旧的 [profiles.old] 段,0.166.0 上 --profile old 会直接报错退出,原文是(路径换成了 ~/.codex):
Error loading config.toml: --profile `old` cannot be used while ~/.codex/config.toml contains legacy `profile = "old"` or `[profiles.old]` config; move those settings into ~/.codex/old.config.toml and remove the legacy profile selector/table. See https://developers.openai.com/codex/config-advanced#profiles for more information.
按提示把每段旧 profile 挪成单独的 ~/.codex/名称.config.toml,再删掉旧段即可。多个项目用不同模型、不同 Key 的完整写法,见《Codex 多项目怎么管理》。
model 和 model_reasoning_effort 怎么填
模型 ID
model 要写服务商那边真实存在的模型 ID,全小写,例如 gpt-6.1-terra、gpt-6.1-sol。据 rust-v0.165.0 和 rust-v0.166.0 的 release notes,GPT-6.1 Terra 已加入 Codex 内置模型目录,我们在 0.166.0 上写 gpt-6.1-terra,启动时没有出现「Model metadata not found」警告。Terra 和 Sol 怎么选、API 怎么调,见《GPT-6.1 Terra 怎么在 Codex 和 API 里用》。
临时换模型试试,用命令行参数,不改文件:
codex --model gpt-6.1-sol
codex --config model='"gpt-6.1-sol"'
官方文档原文:「--config values are parsed as TOML. When in doubt, quote the value so your shell doesn't split it on spaces.」出处:Advanced Configuration。
所以字符串外面要有一层双引号,再用单引号包住防止被 shell 拆开。
推理强度可选值
官方参考对 model_reasoning_effort 的说明是:「Reasoning effort advertised by the selected model, such as low, medium, high, xhigh, max, or ultra. Available levels depend on the model and client.」出处:Configuration Reference。也就是说能填哪些值由模型决定。
我们直接调本站接口,给 gpt-6.1-terra 传 ultra,返回 400,报错里列出了它接受的全部值:
Invalid value: 'ultra'. Supported values are: 'none', 'minimal', 'low', 'medium', 'high', 'xhigh', and 'max'.
在 Codex 0.166.0 里用 -c 分别写 xhigh、max、ultra,三次都正常回复 OK,用时都在 2 到 3 秒。但 ultra 不在接口列出的值里,写进配置文件时建议只用上面这几个值。日常小改动保持 medium,跨文件重构或难排查的问题再调到 high 或 xhigh;调高通常更慢、用更多 token。0.165.0 起,支持的模型可以在对话中途改推理强度(据 rust-v0.165.0 release),不必为此重启。
常用体验类配置项
approval_policy:什么时候让你确认
可选 on-request(需要时请求确认)、never(不再弹出确认),或用 granular 细分。旧配置里的 approval_policy = "untrusted" 已经退役,on-failure 也已弃用,文件里还有这两种写法的,需要按官方迁移说明调整。新手建议保持 on-request。
sandbox_mode:命令能访问多大范围
可选 read-only、workspace-write、danger-full-access。名字里带 danger 的那个只适合你完全清楚后果的隔离环境。
web_search:联网搜索用哪种模式
可选 disabled、cached、indexed、live,默认 cached。网页结果应当被视为不可信内容。
shell_environment_policy:哪些环境变量传给子命令
ignore_default_excludes 默认是 true,也就是默认不会自动过滤名字里带 KEY、SECRET、TOKEN 的变量。希望自动过滤的,设为 false:
[shell_environment_policy]
ignore_default_excludes = false
用 codex doctor 先查一遍
0.166.0 新增了 codex doctor --network-only,专查配置、连通性和 WebSocket(据 rust-v0.166.0 release)。用上面的完整配置跑一次,关键几行原文是(路径换成了 ~/.codex):
Codex Doctor v0.166.0
Configuration
✓ config loaded
model gpt-6.1-terra · aicodewith
config.toml ~/.codex/config.toml
config.toml parse ok
Connectivity
✓ network no proxy env vars
✓ websocket Responses WebSocket is not enabled for the active provider
✓ reachability active provider endpoints are reachable over HTTP
4 ok · 0 warn · 0 fail ok
它能确认三件事:读的是哪个 config.toml、TOML 语法有没有错、当前 Provider 和地址能不能连通。它不证明 Key 有效:同一份配置下,reachability 那一节的探测行显示的是 HTTP 401,而真实请求是成功的。Key 对不对,还要靠一条 codex exec "只回复:OK"。
备选写法:Key 放进 auth.json
AI Code With 控制台的 Codex(终端)教程用的是另一种写法:Key 放在 ~/.codex/auth.json,config.toml 里改用 requires_openai_auth = true。两种二选一即可。config.toml 这样写:
model_provider = "aicodewith"
model = "gpt-6.1-terra"
[model_providers.aicodewith]
name = "aicodewith"
base_url = "https://api.aicodewith.ai/chatgpt/v1"
wire_api = "responses"
requires_openai_auth = true
同目录下的 ~/.codex/auth.json 写 Key:
{
"OPENAI_API_KEY": "sk-你的Key"
}
requires_openai_auth = true 这一行不能省,省了 Codex 发请求时不带 Key,会返回 401。
团队协作时怎么分配配置
- 用户级 ~/.codex/config.toml:Provider、Base URL、Key、个人偏好的推理强度。这些因人而异,也包含敏感信息,不要提交到仓库。
- 项目级 .codex/config.toml:和这个项目有关、所有人都应该一致的设置,比如模型、审批策略。就算有人误写了 Provider 或 Key,Codex 也会忽略并打印警告。
- 项目规则说明:代码风格、测试命令、目录约定这类文字说明,更适合写进 AGENTS.md。
常见报错和排查
| 报错或现象 | 常见原因 | 解决方法 |
|---|---|---|
| 401 Unauthorized:请在请求中提供有效的 API Key | Key 填错、失效,或用了 auth.json 却没加 requires_openai_auth = true | 核对 experimental_bearer_token 或 auth.json,必要时重建 Key |
| 模型 xxx 不存在或未上线 | model 拼错,或写了服务商没有的模型 | 改成控制台模型列表里有的 ID,全小写 |
| Model metadata for xxx not found | 模型 ID 不在 Codex 内置目录里,常见于拼错 | 先核对拼写;新模型升级到最新版 Codex |
| Invalid value: 'ultra' | 推理强度填了模型不支持的值 | 改成报错里列出的值,如 high、xhigh |
| 改了 config.toml,模型没变 | 启动命令带了 --model / --config / --profile,或项目配置覆盖了 | 去掉临时参数,检查项目里的 .codex/config.toml |
| warning: Ignored unsupported project-local config keys | 在项目配置里写了 model_provider、model_providers 等字段 | 把这些字段移到 ~/.codex/config.toml |
| 项目 .codex/config.toml 完全不生效 | 项目未被信任 | 确认项目已受信任;默认以包含 .git 的目录为项目根 |
| --profile 报 legacy 配置错误 | config.toml 里还有旧的 [profiles.xxx] 段 | 迁移到 ~/.codex/名称.config.toml |
401 在 0.166.0 上的表现是:先打印 5 次 Reconnecting,约 9 秒后退出,最后一行原文是(cf-ray 和 request id 已省略):
ERROR: unexpected status 401 Unauthorized: {"error":"请在请求中提供有效的 API Key。"}, url: https://api.aicodewith.ai/chatgpt/v1/responses
更多 401 的情况见《Codex 401 Unauthorized 怎么解决》。
模型名拼错(我们故意写成 gpt-6.1-terr)时,0.166.0 不再重试,不到 1 秒就退出,原文是(request id 已省略):
warning: Model metadata for `gpt-6.1-terr` not found. Defaulting to fallback metadata; this can degrade performance and cause issues.
ERROR: {"error":"模型 gpt-6.1-terr 不存在或未上线,请前往 https://aicodewith.ai/zh/dashboard/pricing 查看可用模型列表"}
据 rust-v0.165.0 release,从 0.165.0 起 Provider 报告模型不存在时 Codex 会停止重试并保留原始报错,所以看到这条就直接改模型名,不用等。
配置不生效时按这个顺序查
- 运行 codex doctor --network-only,确认读的是哪个 config.toml、语法是否 ok;
- 检查启动命令有没有 --model、--config 或 --profile;
- 确认项目是否受信任,项目里有没有 .codex/config.toml,启动时有没有 Ignored unsupported project-local config keys 警告;
- 确认 Provider ID、Base URL 和模型 ID 三者对得上;
- 确认 Key:experimental_bearer_token 写对了,或者 auth.json 写法加了 requires_openai_auth = true;
- 用的是交互界面的,打开 /config 看设置当前的值和是否需要重启(0.163.0 起提供,据 rust-v0.163.0 release);
- 最后发一条 codex exec "只回复:OK",并在调用记录里核对。
常见问题
Codex 的 config.toml 默认在哪里?
用户级配置在 CODEX_HOME 下的 config.toml,CODEX_HOME 默认是 ~/.codex。Windows 上就是 %USERPROFILE%\.codex\config.toml。不确定时运行 codex doctor --network-only,它会打印实际路径。
命令行参数、profile 和 config.toml 哪个优先?
命令行参数最高,其次是受信任项目的 .codex/config.toml,再是 --profile 选中的 profile 文件,最后是全局 config.toml。我们在 0.166.0 上实测了这个顺序。
可以在 config.toml 里直接写 API Key 吗?
可以。在全局 ~/.codex/config.toml 的 Provider 段里写 experimental_bearer_token = "sk-你的Key",这是用 AI Code With 时推荐的写法。也可以按控制台教程把 Key 放进 auth.json,并在 Provider 段里加 requires_openai_auth = true。两种都只放在全局配置里,不要写进项目目录或提交到仓库。
model_reasoning_effort 能填 ultra 吗?
取决于模型。直接调接口时,gpt-6.1-terra 不接受 ultra,只接受 none、minimal、low、medium、high、xhigh、max。配置文件里建议从这几个值里选。
CLI 和 IDE 插件用的是同一份配置吗?
是的,Codex CLI 和 IDE 插件共享同一套配置层。
配置改坏了怎么恢复?
改之前做了备份的,直接用 config.toml.backup 覆盖回去。没有备份的,先把文件精简到上面的完整配置,跑通后再逐项加回去。
创建 API Key,给 Codex 配一个专用 Key →
相关阅读
- 《Codex API Key 怎么配置》
- 《Codex 环境变量怎么配》
- 《Codex 401 Unauthorized 怎么解决》
- 《Codex 多项目怎么管理》
- 《GPT-6.1 Terra 怎么在 Codex 和 API 里用》
- 《Codex 怎么用》



