普通人 AI 实战手册

Appearance

18 · config.toml 配置详解：一个文件管住所有旋钮 ​

前面你已经见过很多 Codex 的开关：模型、权限、沙箱、联网、MCP、记忆功能。 如果每次开工都手动调一遍，很快就会烦。

config.toml 解决的就是这件事：把一部分稳定设置写进文件，让 Codex 每次进来都按同一套旋钮工作。

config.toml 配置层级

开始前先判断：这是长期设置吗？ ​

config.toml 只适合写长期稳定设置。

如果只是这一次任务的要求，直接写在当前对话里。 如果是项目规矩，优先写进 AGENTS.md。 如果是工具行为、权限、模型、MCP 这类旋钮，才考虑 config.toml。

先用三句话判断放哪里 ​

遇到一条新规则，先不要急着写配置。 按下面三句话判断：

  1. 只对这一次任务有效：写在当前对话里。
  2. 只对这个项目长期有效：优先写进 AGENTS.md。
  3. 影响 Codex 工具行为：再考虑 config.toml。

可以直接问：

text
这条要求应该放在当前对话、AGENTS.md，还是 config.toml？
请用普通话解释原因。
暂时不要修改任何文件。

小白阶段，不要把所有东西都塞进配置文件。

01 先搞懂：config.toml 是什么，跟 AGENTS.md 分什么工 ​

先记一句话：

AGENTS.md 管“项目规矩”，config.toml 管“工具旋钮”。

举例：

  • “这个教程写给小白，要按步骤写”适合放进 AGENTS.md。
  • “默认用哪个模型、审批策略是什么、沙箱多严格”适合放进 config.toml。

你可以这样问 Codex：

text
请帮我区分当前项目里哪些内容应该写进 AGENTS.md，哪些应该写进 config.toml。
只给建议，不要修改文件。

02 文件放哪：用户级一份、项目级一份 ​

常见两层：

  1. 用户级：通常在你的个人 Codex 配置目录里，影响你所有项目。
  2. 项目级：项目里的 .codex/config.toml，只影响当前项目。

普通人先这样分：

  • 所有项目都一样的个人习惯，放用户级。
  • 只对这个网站有效的设置，放项目级。
  • 一次性任务要求，直接写在当前对话里。

实战里怎么分：一条配置该放哪 ​

如果你拿不准，就问：

text
这条配置更适合放在用户级 config.toml、项目级 config.toml，还是当前对话里？
请说明原因。

不要把临时想法写成长期配置。

03 谁压谁：优先级，外加一条新手必栽的安全限制 ​

配置不是写了就一定生效。 不同层级可能有优先级。

你需要知道：

  1. 当前对话里的明确要求，通常最直接。
  2. 项目级配置只影响当前项目。
  3. 用户级配置是默认习惯。
  4. 有些安全相关配置，项目级可能不能随便覆盖。

那条新手必栽的限制：项目配置有些键，写了也白写 ​

不要以为所有设置都能在项目里改。 涉及安全、信任、权限的内容，工具通常会更谨慎。

检查方式：

text
请检查当前 .codex/config.toml 里是否有可能不生效的配置项。
只解释原因，不要修改。

04 最常动的几个配置项：干嘛用、默认是什么 ​

小白先关注这些：

model / model_reasoning_effort / approval_policy / sandbox_mode ​

  • model：默认用哪个模型。
  • model_reasoning_effort：思考强度，影响速度和质量。
  • approval_policy：什么时候需要你确认。
  • sandbox_mode：Codex 能操作到什么范围。

不要一上来追求最强配置。 先问清楚：

text
请用小白能听懂的话解释这几个配置项：
model、model_reasoning_effort、approval_policy、sandbox_mode。
重点说它们会影响什么风险。

web_search：联网搜索，注意默认不是万能实时搜索 ​

联网搜索适合查最新资料。 但它不是每个问题都需要开。

写教程时，涉及价格、版本、规则、官方能力，最好联网核对。 改本地文章、看本地文件，通常不需要。

personality：让 Codex 换个说话风格 ​

这个更像表达偏好。 比如你希望它更直接、更详细、更像老师。

但文章质量不能只靠 personality。 真正的文章结构，还是写进 AGENTS.md 更稳。

file_opener：让引用的文件能点开 ​

这个影响文件链接体验。 如果你经常让 Codex 引用本地文件，配置好会更顺手。

一个 TOML 的小坑：根键必须写在表前面 ​

TOML 有自己的格式规则。 如果位置写错，配置可能解析失败。

所以每次改完配置都要让 Codex 检查：

text
请检查这个 config.toml 是否符合 TOML 格式。
重点看表名、键值、位置和引号。

05 [features]：实验和可选功能的总开关 ​

有些功能不是默认开启，而是放在 [features] 下面。

新手不要看到功能就全开。 先问：

text
这个 feature 是稳定功能还是实验功能？
开启后会影响什么？
如果不适合小白，请建议先不要开。

06 临时改一次 vs 切一整套：-c 和 --profile ​

有些配置只想临时试一下，不应该写进文件。

临时改一次：-c / --config ​

适合这次任务临时覆盖。 比如临时换个模型、临时开一个功能。

切一整套：--profile ​

适合做几套固定配置。 比如：

  • 日常写文章配置。
  • 安全检查配置。
  • 复杂项目配置。

小白阶段不用急着做 profile。 先把一份默认配置弄明白。

07 动手：写一份配置 → 临时覆盖 → 切 profile，全验一遍 ​

可以按这个练习：

  1. 让 Codex 读取当前是否有配置。
  2. 让它解释每一项。
  3. 只新增一个小配置。
  4. 让它检查 TOML 格式。
  5. 让它说明怎么撤回。

提示词：

text
请帮我设计一份最小 config.toml。
目标是让这个教程网站项目更安全地协作。
要求：
1. 先给配置草案
2. 每一项都解释作用
3. 不写真实密钥
4. 我确认后再创建文件

08 小结 ​

config.toml 不是炫技文件。 它是把重复设置固定下来，减少每次手动调旋钮。

小白先记住三件事：

  • AGENTS.md 写规矩。
  • config.toml 写工具设置。
  • 安全相关配置不要乱抄，先问清楚再改。