Codex config.toml 配置指南:位置、Provider、模型与优先级(2026 年 10 月 · Codex 0.166 实测)

按 Codex CLI 0.166.0 实测更新:config.toml 在各系统的位置,第三方 Provider 用全局 experimental_bearer_token 的完整配置,profile 文件写法,model_reasoning_effort 可选值和 GPT-6.1 Terra,CLI 参数、profile、全局配置谁覆盖谁,附 401、模型不存在、旧 profiles 段等报错原文和排查顺序。

11 分钟阅读
Codex config.toml 配置指南:位置、Provider、模型与优先级(2026 年 10 月 · Codex 0.166 实测)
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 怎么配置》。

创建 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 秒
命令行参数覆盖 profilecodex 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 秒

全局配置那一次的启动信息原文:

text
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 段里,请求时带上的 Keyexperimental_bearer_token = "sk-你的Key"
model_reasoning_effort推理强度,可选值取决于模型model_reasoning_effort = "medium"
plan_mode_reasoning_effortPlan 模式单独的推理强度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 是隐藏目录,在访达里看不到时,可以用终端打开:

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

Windows

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

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

用记事本保存时请确认编码是 UTF-8,避免编码问题导致 Codex 读不出配置。

Linux

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

bash
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:

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

Windows PowerShell:

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

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

可直接复制的完整配置(接 AI Code With)

把下面整段写进全局 ~/.codex/config.toml,只需把 sk-你的Key 换成自己的 Key:

toml
# ~/.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,全小写。

然后运行一条最小请求:

bash
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。官方文档给出的完整解析顺序(从高到低)是:

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

我们用同一份全局配置(gpt-6.1-terra、medium)和一个 profile 文件(gpt-6.1-sol、high)实测了这个顺序:

启动方式启动信息里的 modelreasoning effort
codex execgpt-6.1-terramedium
codex exec --profile deepgpt-6.1-solhigh
codex exec --profile deep -m gpt-6.1-terra -c model_reasoning_effort='"low"'gpt-6.1-terralow

所以「明明改了 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 全部被忽略,请求照常用全局配置成功返回,启动时打印了这条警告(路径换成了 <项目>):

text
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:

toml
# ~/.codex/deep.config.toml
model = "gpt-6.1-sol"
model_reasoning_effort = "high"

使用:

bash
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):

text
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 里用》。

临时换模型试试,用命令行参数,不改文件:

bash
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,报错里列出了它接受的全部值:

text
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:

toml
[shell_environment_policy]
ignore_default_excludes = false

用 codex doctor 先查一遍

0.166.0 新增了 codex doctor --network-only,专查配置、连通性和 WebSocket(据 rust-v0.166.0 release)。用上面的完整配置跑一次,关键几行原文是(路径换成了 ~/.codex):

text
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 这样写:

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:

json
{
  "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 KeyKey 填错、失效,或用了 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 已省略):

text
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 已省略):

text
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 会停止重试并保留原始报错,所以看到这条就直接改模型名,不用等。

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

  1. 运行 codex doctor --network-only,确认读的是哪个 config.toml、语法是否 ok;
  2. 检查启动命令有没有 --model、--config 或 --profile;
  3. 确认项目是否受信任,项目里有没有 .codex/config.toml,启动时有没有 Ignored unsupported project-local config keys 警告;
  4. 确认 Provider ID、Base URL 和模型 ID 三者对得上;
  5. 确认 Key:experimental_bearer_token 写对了,或者 auth.json 写法加了 requires_openai_auth = true;
  6. 用的是交互界面的,打开 /config 看设置当前的值和是否需要重启(0.163.0 起提供,据 rust-v0.163.0 release);
  7. 最后发一条 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 →

相关阅读

资料来源

相关文章

UI SDK 是什么、怎么用?Vercel + shadcn 给 Agent 的行为库,在 Claude Code / Codex / Cursor 里安装与实测(0.1.0-beta.1)

UI SDK 是什么、怎么用?Vercel + shadcn 给 Agent 的行为库,在 Claude Code / Codex / Cursor 里安装与实测(0.1.0-beta.1)

UI SDK 是 Vercel 在 2026 年 11 月 12 日发布的、给 Agent 用的行为(behaviors)库,版本 0.1.0-beta.1。行为写在与框架无关的 @ui-sdk/core 里,再由 React、Vue、Svelte、Solid 和 Web Components 适配器渲染。本文按官方文档整理它是什么、怎么安装、怎么给 Claude Code / Codex / Cursor 装 skill,并记录我们在测试机上的真实命令、耗时和输出。

AWS Emulator 是什么、怎么装?让 Claude Code / Codex 在本地测 AWS 应用(1.0.322 实测)

AWS Emulator 是什么、怎么装?让 Claude Code / Codex 在本地测 AWS 应用(1.0.322 实测)

AWS Emulator 是 AWS 官方 2026 年 11 月 12 日(北京时间)正式发布的本地 AWS 模拟器,没有额外服务费、源码开放,不需要 AWS 账号,覆盖 200 多个服务。本文在 Debian 13 上实测 1.0.322:安装命令、AWS CLI 指向本地 endpoint 建 S3 桶和 DynamoDB 表、常见报错,以及让 Claude Code、Codex、Cursor 对着模拟器写代码跑测试的接法。

T3 Code 是什么、怎么装?接入 Claude Code 和 Codex、配置第三方 API Key 与常见报错(0.1.9 实测)

T3 Code 是什么、怎么装?接入 Claude Code 和 Codex、配置第三方 API Key 与常见报错(0.1.9 实测)

T3 Code 是 pingdotgg 开源的编码 Agent 控制台,本身不带模型,调用你机器上已装好的 Claude Code、Codex、Cursor 等 CLI。本文在 Linux 上实测 T3 Code 0.1.9:讲清安装命令,Claude Code 和 Codex 先各自接上 AICodeWith API Key、再由 T3 Code 调用的配置方法,用 t3 thread 命令行跑通两端的过程,以及我们实际遇到的报错和解法。