config.toml 是什么，和 AGENTS.md 有什么区别

学到这里，你已经知道 AGENTS.md 是项目规则。

现在要讲另一个很重要的文件：

config.toml

它不是写项目规范的地方，而是写 Codex 自身运行配置的地方。

前置教程：第一次给项目添加 AGENTS.md
如果你还没有理解 AGENTS.md 的作用，先看前置教程。否则很容易把项目规则和运行配置混在一起。

这一篇你会学到什么

• config.toml 是什么。
• 它适合配置哪些东西。
• 它和 AGENTS.md 的区别。
• 它和当前对话提示词的区别。
• 什么应该写用户级配置，什么应该写项目级配置。
• 新手不要一开始乱改哪些配置。

核心结论

config.toml 管 Codex 怎么运行，AGENTS.md 管 Codex 在项目里怎么做事。

这句话关键。

很多人把所有东西都塞进一个文件，后面排查问题会很痛苦。

config.toml 通常配置什么

常见内容包括：

类型	例子
默认模型	默认使用哪个模型
模型 provider	OpenAI、OpenAI 兼容服务商、国内大模型服务商
Base URL	模型接口地址
API Key 获取方式	从环境变量或 .env 读取
审批策略	什么时候需要你确认
沙箱策略	Codex 能读写哪些地方
MCP	连接外部工具或数据源
功能开关	是否启用某些可选能力
子代理配置	后面高阶教程会讲

这些都属于 Codex 自身的工作方式，不属于某个业务需求。

AGENTS.md 通常配置什么

AGENTS.md 写的是项目怎么做。

比如：

• 这个项目用 Astro。
• 文档在 src/content/docs。
• 修改文档后运行 npm run build。
• 教程必须写成中文喂饭级步骤。
• 不要提交真实 API Key。
• 任务结束时汇报修改文件和检查结果。

这些是人也能读懂的项目规则。

四种信息应该放在哪里

这是新手最容易混的地方。

你想表达的内容	应该放哪里
这次任务只改登录页	当前对话提示词
这个项目所有教程都要中文喂饭级	AGENTS.md
默认使用某个模型 provider	config.toml
某个项目需要特定 MCP 或沙箱偏好	项目级 .codex/config.toml
API Key 的真实值	环境变量或 ~/.codex/.env，不要写进仓库
构建命令是 npm run build	AGENTS.md
每次都要先审批危险操作	config.toml

一个错误示例

不要在 AGENTS.md 里写：

默认模型使用 deepseek-chat。
Base URL 是 https://api.example.com/v1。
API Key 是 sk-xxxx。

问题有三个：

1. 模型配置应该进 config.toml。
2. API Key 真实值不能写进项目文档。
3. 如果这个文件提交到 Git，密钥就泄露了。

更合理的做法是：

• config.toml 写 provider、Base URL、模型名、环境变量名。
• .env 或系统环境变量保存真实 API Key。
• AGENTS.md 只写项目做事规则。

一个正确分工示例

config.toml 可以负责：

model = "example-model"
model_provider = "example-provider"

[model_providers.example-provider]
name = "example-provider"
base_url = "https://api.example.com/v1"
env_key = "EXAMPLE_API_KEY"

AGENTS.md 可以负责：

AGENTS.md

## 常用检查

- 修改前端页面后，优先运行 npm run build。

## 写作规则

- 所有教程默认使用简体中文。

当前对话可以负责：

这次只修改首页 hero 区域，不要改文档页布局。

这样分层就清楚了。

用户级 config.toml 在哪里

常见位置是：

Windows：

C:\Users\你的用户名\.codex\config.toml

macOS / Linux：

~/.codex/config.toml

这个文件适合放你个人长期使用的默认配置。

比如：

• 你默认用哪个模型。
• 你默认使用哪个 provider。
• 你偏好的审批策略。
• 你常用的 MCP 服务。

项目级 config.toml 在哪里

项目级通常放在项目里：

.codex/config.toml

它适合放当前项目专用的 Codex 配置。

比如：

• 这个项目需要一个特定 MCP。
• 这个项目需要更严格的沙箱。
• 这个项目需要不同的子代理角色。

但是新手阶段先不要用项目级配置。

原因是：

• 项目级配置只在受信任项目里加载。
• 如果目录里有多层 .codex/config.toml，离当前工作目录更近的会覆盖更远的。
• 某些安全敏感配置不能被项目级配置随便覆盖。
• 你可能不知道到底是哪一层配置生效。

所以新手建议：

先用用户级 ~/.codex/config.toml。
项目级 .codex/config.toml 留到你真正需要项目专属配置时再用。

不要一开始乱改这些

新手不要一上来就大改：

• 沙箱权限。
• 审批策略。
• 网络访问策略。
• Hooks。
• MCP 工具权限。
• 子代理角色。

这些不是不能改，而是要知道为什么改。

如果你只是想接入国内大模型，通常先处理：

• model
• model_provider
• [model_providers.xxx]
• base_url
• env_key
• .env 或环境变量

够了。

判断你是否理解了

看下面几句话：

说法	是否正确
config.toml 负责 Codex 运行配置	对
AGENTS.md 负责项目规则和工作约定	对
API Key 真实值可以写进项目级 .codex/config.toml 并提交	错
临时任务限制应该优先写在当前对话里	对
新手应该一开始就把沙箱权限全部放开	错

验收结果

读完后你应该能说清楚：

1. config.toml 管什么。
2. AGENTS.md 管什么。
3. 当前对话提示词管什么。
4. 用户级配置和项目级配置的区别。
5. 为什么不要把密钥写进仓库。

下一篇看：用户级 config.toml 和项目级 .codex/config.toml 怎么选。