结论先说
- 用户级配置在
~/.codex/config.toml(~/.codex就是CODEX_HOME,默认位置)。桌面 App、命令行和 IDE 扩展读的是同一套配置层。 - 项目级配置放仓库里的
.codex/config.toml,但官方写明:只有你信任该项目时才会加载。 - 优先级从高到低共七层:命令行参数与
--config→ 项目配置 → profile 文件 → 用户配置 → 云端托管配置 → 系统配置 → 内置默认值。 - profiles 是独立文件:
~/.codex/名字.config.toml,用codex --profile 名字选择。官方强调:文件里直接写顶层键,不要再套[profiles.名字]。 - TOML 规则:根级键必须写在所有表(
[xxx])之前,否则会读错位置。

图:本站根据 Codex 官方 Config basics 整理的示意图
本文根据 Codex 官方文档的 Config basics、Advanced Config、Sample Configuration 和 Configuration Reference 整理,资料核对于 2026-11-13。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 OpenAI 官方网站。MCP 的配置写法见 /guides/codex-mcp-config,权限与沙箱的取值见 /guides/codex-permissions-sandbox,本文不重复。
适用于谁
- 想知道 Codex 的配置文件在哪、能改什么的人;
- 全局设置、项目设置、命令行参数冲突,不知道听谁的人;
- 想给「日常」「代码审查」「CI」准备不同配置一键切换的人。
一、文件在哪
- 用户级:
~/.codex/config.toml。在 Windows 上对应用户目录下的.codex文件夹。如果在 WSL 里跑命令行,它用的是 Linux 的家目录,与 Windows 那份不共用,见 /guides/codex-app-vs-cli-which-better。 - 项目级: 仓库里的
.codex/config.toml。Codex 会从项目根目录走到当前工作目录,把沿途每一个.codex/config.toml都读进来,同一个键以离你当前目录最近的那份为准。项目里相对路径(比如model_instructions_file)按这个.codex文件夹计算。 - 系统级: Unix 下是
/etc/codex/config.toml,有才读。 - IDE 扩展里打开: 右上角齿轮 → Codex Settings > Open config.toml。
CODEX_HOME下还有auth.json(文件方式存凭据时)、history.jsonl(开启历史时)和日志缓存等。
项目配置里「被忽略」的键
出于安全,官方列出了项目里的 .codex/config.toml 不能改的键,Codex 看到会忽略并在启动时警告:openai_base_url、chatgpt_base_url、apps_mcp_product_sku、model_provider、model_providers、notify、profile、profiles、experimental_realtime_ws_base_url 和 otel。也就是说,换接口地址、换模型提供方、通知命令这类涉及凭据和外发的设置,只能写在你自己的用户级配置里。
二、谁覆盖谁:七层优先级
官方给的顺序(越靠前越优先):
- 命令行参数和
--config覆盖; - 项目配置文件(
.codex/config.toml,从项目根到当前目录,越近越优先,仅限信任的项目); - 用
--profile选的 profile 文件; - 用户配置
~/.codex/config.toml; - 为已登录工作区下发的云端托管配置;
- 系统配置;
- 内置默认值。
实用做法是官方建议的:共用默认值写进 config.toml,profile 文件只写有差别的几项。如果你的电脑由公司管理,管理员还可以用 requirements.toml 强制限制,比如禁止 approval_policy = "never" 或 sandbox_mode = "danger-full-access",这类限制不能被你的配置绕开。
项目被标为不信任时,Codex 跳过项目里的 .codex/ 层,包括配置、钩子和规则,用户和系统层照常加载。
三、常用键怎么写
下面的键和写法都来自官方 Config basics 或示例配置。
toml
model = "gpt-6.1-sol" # 默认模型(需账号可用)
model_reasoning_effort = "medium" # 推理强度
approval_policy = "on-request" # 何时请求审批,默认值
sandbox_mode = "read-only" # 沙箱,示例配置里的默认值
web_search = "cached" # 联网搜索:cached(默认) | indexed | live | disabled
notify = ["python3", "/path/to/notify.py"] # 回合结束时调用外部程序
几处细节:
model_reasoning_effort官方写的是「模型支持时才生效」,可选档位随模型而异,换法见 /guides/codex-switch-model-reasoning-effort。web_search默认"cached"。官方写明使用完全访问沙箱(如--yolo)时默认变成live。project_doc_max_bytes默认 32768,是读取 AGENTS.md 并放进首轮指令的上限字节数;project_doc_fallback_filenames可以在没有 AGENTS.md 时指定备用文件名,读取规则见 /guides/codex-agents-md-how-it-reads。[history]表里的persistence默认save-all,设成none就不再保存本地会话记录;max_bytes限制历史文件大小,超出会删最旧的。[features]表用来开关功能,写法是功能名 = true;命令行临时开启用codex --enable 功能名。[tui]表控制终端界面,比如notifications、status_line、terminal_title。[projects."/绝对路径"]下的trust_level取trusted或untrusted,决定上面说的项目层加不加载。[shell_environment_policy]控制转发给子命令的环境变量。官方写明ignore_default_excludes默认是 true,即不自动过滤名字含 KEY、SECRET、TOKEN 的变量;想要自动过滤要设成 false。
官方的示例配置文件按块组织:核心模型、推理与详略、指令覆盖、通知、审批与沙箱、登录、项目文档、历史、界面、联网搜索、多 Agent 角色、技能、沙箱表、环境变量策略、功能开关、记忆、模型提供方、应用与连接器、profiles、项目信任、OpenTelemetry、Windows。你可以把它当字典,只复制要用的键,不用整份照搬。
四、profiles:一键切换整套设置
官方原话大意:用 --profile 名字 时,Codex 先读 ~/.codex/config.toml,再叠上 ~/.codex/名字.config.toml。名字可以有字母、数字、连字符和下划线。
例如新建 ~/.codex/deep-review.config.toml:
toml
model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
approval_policy = "on-request"
使用:
bash
codex --profile deep-review
codex exec --profile deep-review "review this change"
因为 profile 层在项目和命令行之下、用户配置之上,它只需要写与基础配置不同的部分。
旧写法已失效。 官方写明从 Codex 0.134.0 起,--profile 不再读取 config.toml 里的 [profiles.名字],顶层 profile = "名字" 选择器也不再支持。如果你照着旧教程写了这些,要把设置搬到 ~/.codex/名字.config.toml,再删掉旧表和旧选择器。

图:本站根据 Codex 官方 Config basics 整理的示意图
五、临时改一次,不动文件
官方推荐:有专门参数就用专门参数(如 --model),否则用 -c / --config:
bash
codex --model gpt-6.1-sol
codex --config sandbox_workspace_write.network_access=true
codex -c log_dir=./.codex-log
要点:键可以用点号表示嵌套;值按 TOML 解析,所以字符串要带引号(官方示例是 model='"gpt-6.1-sol"'),为了不被 shell 拆开最好整体加引号;解析不了时当字符串处理。
常见问题
Q:改了 config.toml 没生效?
先看有没有被更高层覆盖:命令行参数、项目配置、profile 文件都比它优先;再确认这个键是不是被写在了某个 [表] 的下面,根级键要写在表之前。
Q:项目里的配置为什么没读?
多半是项目没被信任,或写的是上面那些被忽略的键。
Q:Codex 额度不够用,是不是靠改配置能解决?
配置只能改模型和推理强度这类选择,额度随套餐,以官方页面当前显示为准。需要更高额度可看 ChatGPT Plus 充值说明。
相关教程
- /guides/codex-mcp-config:MCP 服务器配置
- /guides/codex-permissions-sandbox:权限与沙箱
- /guides/codex-cli-commands-cheatsheet:命令速查
参考资料
- Codex 官方文档:Config basics — https://learn.chatgpt.com/docs/config-file/config-basic
- Codex 官方文档:Advanced Config — https://learn.chatgpt.com/docs/config-file/config-advanced
- Codex 官方文档:Sample Configuration — https://learn.chatgpt.com/docs/config-file/config-sample
0 条评论
还没有评论,来抢沙发~