Codex config.toml 完整详解:文件在哪、有哪几层、常用键怎么写、profiles 怎么切换

Codex 的 config.toml 放在哪、有哪些层、谁覆盖谁?按官方文档整理:用户级在 ~/.codex,项目级在 .codex/config.toml,七层优先级,常用键和 profiles 的写法。

NNathaniel bigo··原创首发·AI 辅助撰写
12 分钟读完
资料核对于 2026-11-13 · 依据官方文档与公开资料整理 Plus 账号

结论先说

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

config.toml 七层优先级:命令行、项目、profile、用户、云端托管、系统、内置默认

图:本站根据 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。也就是说,换接口地址、换模型提供方、通知命令这类涉及凭据和外发的设置,只能写在你自己的用户级配置里。

二、谁覆盖谁:七层优先级

官方给的顺序(越靠前越优先):

  1. 命令行参数和 --config 覆盖;
  2. 项目配置文件(.codex/config.toml,从项目根到当前目录,越近越优先,仅限信任的项目);
  3. 用 --profile 选的 profile 文件;
  4. 用户配置 ~/.codex/config.toml;
  5. 为已登录工作区下发的云端托管配置;
  6. 系统配置;
  7. 内置默认值。

实用做法是官方建议的:共用默认值写进 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,再删掉旧表和旧选择器。

config.toml 常用键速查与 profile 文件命名规则

图:本站根据 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 充值说明。

相关教程

参考资料

  • 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

Nathaniel 的更多内容

  1. 01

    LangGraph 流式输出(Streaming)详解:逐字 Token 流、节点进度与自定义事件写法

    多步智能体如果等全部节点跑完才返回,网页前端就会白屏干等十几秒。本文按 LangGraph 官方文档讲清 updates、messages、custom 与 values 四种 stream_mode 的区别,以及组合订阅逐字打字机输出加工具内部实时进度的完整代码。

    其他 AI 工具0
  2. 02

    LangGraph 持久化与长期记忆怎么配:Checkpointer、Store 与 PostgreSQL 实战

    在生产环境跑 LangGraph,单靠 InMemorySaver 一重启就会丢失全部对话。本文按官方文档讲清线程内短期检查点(Checkpointer)与跨线程长期记忆(Store)的分工,以及用 langgraph-checkpoint-postgres 对接 PostgreSQL 的完整步骤。

    其他 AI 工具0
  3. 03

    LangGraph 多智能体怎么写:Supervisor 主管包与 Subgraph 隔离子图实战

    在 LangGraph 里把单个图扩展成多智能体协作有两条官方路线:快速原型用预置包 langgraph-supervisor,大型生产系统用原生子图(Subgraph)嵌套。本文讲清两种写法的完整代码、私有状态隔离防 Token 膨胀技巧以及检查点传播规则。

    其他 AI 工具0
  4. 04

    LangGraph 人工介入审批怎么写:interrupt 暂停图运行与 Command 恢复实战

    企业之所以选 LangGraph,很大程度看中它能安全挂起等待人工审批(Human-in-the-Loop)。本文按官方最新规范讲清 interrupt() 动态暂停、Checkpointer 必备条件、Command(resume=...) 恢复执行,以及防止副作用重复运行的重入规则。

    其他 AI 工具0
  5. 05

    多 Agent 协作平台怎么选:Dify、扣子(Coze)、n8n 与 LangGraph 多智能体机制对比

    搜「多agent协作平台」时,Dify、扣子、n8n 和 LangGraph 都宣称支持多智能体,但底层的调度方式完全不同。本文跳过基础安装,专门从多 Agent 角色跳转、子代理工具调用、上下文隔离与私有化部署四个维度帮你一次选准。

    其他 AI 工具0
  6. 06

    企业微信有官方 MCP 和 CLI 吗:@wecom/cli 安装初始化、长连接机器人与接入教程

    搜「企业 微信 有 mcp 吗」不用再东拼西凑民间群机器人脚本了:企业微信官方已推出 @wecom/cli 命令行工具并内置 stdio 模式的 MCP Server。本文按官方开发者文档讲清安装、智能机器人长连接初始化、业务命令与接入 Claude Code 步骤。

    Claude其他 AI 工具0

同产品的其他教程

  1. 01

    AutoGen 现在怎么样了?微软官方演进路线与 Microsoft Agent Framework 入门

    搜 AutoGen 新教程常被 0.2、0.4、社区分支和 Semantic Kernel 绕晕。按微软官方文档,微软已将 AutoGen 与 Semantic Kernel 两支团队合并推出统一的开源框架 Microsoft Agent Framework。本文讲清现状与 Python 快速上手。

    ChatGPT其他 AI 工具0
  2. 02

    多 Agent 的成本为什么翻倍、怎么控制:Token 膨胀根源与五项降本措施

    刚把单智能体拆成多 Agent,用量往往暴涨好几倍。Anthropic 工程报告统计单智能体约为聊天的 4 倍 Token,多智能体可达约 15 倍。本文拆解固定前缀重复加载、历史搬运、工具链定义与缓存失效四大根源,并给出五条实操控费办法。

    ChatGPTClaude0
  3. 03

    多 Agent 协同开发怎么落地:「一个写、一个审」双代理工作流搭建指南

    多 Agent 协同开发里投入产出比最高的模式就是「一个写、一个审」。本文依据 Anthropic 与 OpenAI 官方编码最佳实践,讲清为什么同会话自审容易漏问题,以及用只读子代理、跨模型交叉审查(Claude Code + Codex)和自动化闭环落地的具体方法。

    ClaudeCodex0
  4. 04

    多 Agent 编排模式详解:编排者-工作者、交接(Handoffs)、并行与评估循环怎么选

    搜「multi-agent orchestration 中文」会被各家框架的不同术语绕晕。本文对照 Anthropic《Building effective agents》与 OpenAI 智能体指南,把编排者-工作者、去中心化交接、并行分片投票与生成-评估循环四种标准编排拓扑讲透。

    ChatGPTClaude0
  5. 05

    多智能体(Multi-Agent)是什么、什么时候该用:Anthropic 与 OpenAI 官方判断标准

    多智能体不是代理越多越聪明。本文依据 Anthropic 研究系统架构文章与 OpenAI 官方智能体指南,讲清确定性工作流、单智能体与多智能体的区别,以及哪三类瓶颈才值得上多智能体协同。

    ChatGPTClaude0
  6. 06

    codebase-memory 类 MCP 是什么、怎么用:基于语法树图谱的本地代码索引原理与配置

    codebase-memory-mcp(DeusData/codebase-memory-mcp)是一类本地代码图谱 MCP 服务器:用 Tree-sitter 把仓库解析成函数与调用关系的 SQLite 图库,帮编码助手查调用链并省下读整份文件的额度。

    ClaudeCodex0

0 条评论

登录 后参与评论

还没有评论,来抢沙发~