Codex配置实战教程：5分钟调教AI编程助手，提升开发效率

# Codex配置实战教程：5分钟调教AI编程助手，提升开发效率

最近用 AI 写代码的人越来越多，但很多同学对 Codex 的理解还停留在一个层面：把它当成一个能帮你补代码、解释代码的聊天工具。

这个理解不能说错，但有点浅。

如果只是让 Codex 写一个函数、解释一段报错，那它确实像一个普通的 AI 助手。但真正把它放进项目里用一段时间之后，你会发现 Codex 更像一个可以参与开发流程的“本地开发代理”。它能读项目、搜文件、改代码、跑测试、看日志，甚至可以通过 MCP 去连接浏览器、仓库、文档系统等工具。

从下面这张图可以快速理解 Codex 的核心工作方式——它不再是简单的代码补全，而是能理解整个项目上下文、执行多步骤开发任务的智能代理：

{image}

能力变强以后，问题也就跟着来了：

它能不能随便改文件？
它能不能联网？
它遇到危险命令要不要先问我？
它怎么知道这个项目用的是 pnpm 还是 npm？
它怎么知道不要乱改数据库迁移文件？
它怎么知道我的代码风格是什么？

这些问题不能靠每次聊天临时提醒解决。你每次都说“不要乱加依赖”“改完记得跑测试”“别动生产配置”，不仅麻烦，而且容易漏。

所以 Codex 真正好用的关键，不只是模型本身，而是配置。

本文就从 config.toml、AGENTS.md、权限策略、沙箱模式和 MCP 这几块，把 Codex 的配置体系梳理一遍。目标不是堆概念，而是让你知道：每个配置到底管什么，什么时候该配，怎么配才不容易翻车。

为什么 Codex 需要配置？

传统编辑器插件大多只负责提示和补全，比如补全变量名、生成一小段代码、解释某个函数。它们一般不会主动修改一堆文件，也不会自己执行命令。

Codex 不一样。

你可以直接给它一个任务：

> 帮我修复登录失败时错误提示不准确的问题，并补充测试。

正常情况下，它可能会做这些事：

搜索 login、auth、error 相关代码
阅读接口实现和测试目录
找到最小修改点
修改错误提示逻辑
补充测试用例
运行测试命令
根据测试结果继续修复
最后总结改了哪些文件

这已经不是简单的“代码生成”了，而是一个小型开发流程。

但开发流程一旦自动化，就必须考虑边界。因为自动化能力越强，误操作成本也越高。

比如：

它为了修 bug，顺手重构了一堆无关代码
它为了跑项目，直接安装了新依赖
它以为 dist 是临时目录，结果删掉了重要文件
它不知道项目规范，把 npm 和 pnpm 混着用
它不知道测试命令，改完代码就直接结束

这些问题不是模型“笨”，很多时候是因为项目规则没有明确告诉它。

从工程角度看，配置的作用就是把临时口头约定变成稳定规则。

这和 Linux 权限管理有点像。普通用户不能随便改系统目录，危险操作要提权，进程访问资源要经过权限检查。不是为了麻烦，而是为了防止错误操作影响整个系统。

Codex 也一样。

它需要知道：

哪些文件能读？
哪些目录能写？
哪些命令能直接执行？
哪些操作必须问用户？
这个项目的开发规范是什么？
当前目录有没有特殊约束？

没有配置时，Codex 只能靠当前对话里的临时上下文。配置写清楚后，它每次进入项目都能先拿到规则，再开始工作。

Codex 配置体系整体认识

Codex 配置里最重要的两个文件是：

config.toml
AGENTS.md

这两个文件不要混着理解。

config.toml 更偏工具层，控制模型、权限、沙箱、MCP 服务、默认行为等。
AGENTS.md 更偏项目层，告诉 Codex 项目规范、代码风格、测试方式、目录规则等。

💡一句话总结：

config.toml 决定 Codex 能做什么
AGENTS.md 决定 Codex 应该怎么做

比如你想设置默认模型、是否允许联网、能不能写工作区，这些属于 config.toml。

比如你想告诉 Codex “本项目使用 C++17”“改完运行 make test”“不要做无关重构”，这些属于 AGENTS.md。

常见层级可以这样看：

~/.codex/config.toml 用户级工具配置
项目目录/.codex/config.toml 项目级工具配置
~/.codex/AGENTS.md 用户级长期指令
项目根目录/AGENTS.md 项目级开发规范
子目录/AGENTS.md 模块级补充规范

这套设计和 Git 配置很像。Git 有系统级、用户级、仓库级配置；Codex 也可以把个人习惯放全局，把项目规则放仓库，把特殊模块规则放子目录。

这样做的好处是清晰。

你的个人习惯可以长期保留：

修改前先阅读上下文
不要主动引入新依赖
能跑测试就跑测试
回答先给结论再展开

项目规则则放在项目里：

本项目使用 pnpm
后端接口改动要更新文档
数据库迁移文件不要随便改
提交前运行 pnpm test

不同项目加载不同规则，不需要每次都从头交代。

config.toml：工具行为的控制中心

config.toml 是 Codex 的核心配置文件之一。

用户级配置一般在：
PR0

Windows 下通常类似：
PR1

如果某个项目需要单独配置，可以在项目里创建：
PR2

一个比较基础的配置如下：
PR3

这几行已经包含了几个关键点：

model：默认模型
model_provider：模型提供方
approval_policy：审批策略
sandbox_mode：沙箱模式

TOML 的写法比较适合手写配置。相比 JSON，它不用写一堆括号；相比 YAML，它又不容易因为缩进出问题。

需要注意的是，顶层字段尽量写在表配置前面，例如：
PR4

不要把顶层字段随便插到某个表下面，否则有些配置可能会被解析成表内字段。

可以把 config.toml 理解成 Codex 的启动参数区。Codex 进入项目后，会先读取这些配置，再确定自己以什么模式工作。

模型配置：不是越强越好，而是要匹配任务

模型配置通常写在 config.toml 顶层：
PR5

能力强的模型适合做复杂任务，例如：

跨文件 bug 分析
大型重构
测试失败排查
架构设计
复杂代码迁移
多步骤开发任务

速度更快、成本更低的模型适合做轻任务，例如：

解释代码
补注释
生成简单脚本
写 README
整理日志
局部小改动

这和我们平时选数据结构一样。不是所有场景都用红黑树，也不是所有场景都用数组。任务复杂度不同，模型选择也应该不同。

如果只是改一个变量名，用最强模型有点浪费。如果是分析一个跨多个模块的线上 bug，用太弱的模型又容易漏上下文。

还可以配一些推理和输出参数：
PR6

大致可以这样理解：

reasoning_effort：推理强度
verbosity：输出详细程度
reasoning_summary：是否展示推理摘要

新手不建议一开始把参数调得很复杂。先用默认值，等你发现某类任务经常不够稳，再针对性调整。

💡我的建议：

小改动：medium 就够
复杂重构：提高 reasoning effort
写文章或解释知识：提高 verbosity
自动化任务：输出尽量简洁

配置不是越多越好，能解决问题才是好配置。

权限配置：approval_policy 和 sandbox_mode

Codex 配置里最需要认真理解的，就是权限。

因为它直接决定 Codex 能不能改文件、能不能联网、能不能执行命令，以及遇到风险操作时要不要停下来问你。

两个核心字段：
PR7

这两个字段分别解决不同问题：

approval_policy：什么时候需要问用户
sandbox_mode：Codex 最大能操作到什么范围

approval_policy：刹车系统

approval_policy 可以理解成刹车系统。

PR8

这个配置表示：当 Codex 遇到需要更高权限、可能影响系统或项目安全的操作时，会先请求用户确认。

日常开发推荐这个模式。

因为我们既希望 Codex 能主动干活，又不希望它完全不受控制。

还有一种模式是：
PR9

这个表示 Codex 不会主动请求审批。它更适合提前确定好边界的自动化环境，比如临时容器、CI、一次性脚本。普通个人项目不建议默认用它。

sandbox_mode：活动范围

sandbox_mode 可以理解成活动范围。

常见有三种：

read-only：只读
workspace-write：允许写当前工作区
danger-full-access：权限基本放开

只想让 Codex 分析项目，不想让它改文件，可以用：
PR10

日常开发比较推荐：
PR11

这表示 Codex 可以修改当前项目内的文件，但不会随便动系统其它目录。

如果需要允许联网和限制可写目录，可以这样写：
PR12

danger-full-access 权限最大，但名字已经提示得很直白：danger。

不是说不能用，而是要知道自己在干什么。真实项目里，不建议新手默认开这个。

两个配置一起看

组合起来看更清楚：

🧱比较稳的日常配置：
PR13

这个配置既不会让 Codex 完全不能动，也不会把系统权限全部交出去。

AGENTS.md：项目规矩写在这里

如果说 config.toml 管的是工具行为，那 AGENTS.md 管的就是项目规矩。

很多时候，Codex 写得不符合预期，不是因为它不会，而是因为它不知道你的项目规则。

比如：

不能随便新增依赖
修改公共接口要更新文档
改完代码要跑测试
不要修改 migrations 目录
C++ 项目要保持头文件依赖简洁
Linux 示例代码要写清楚返回值

这些都适合写进 AGENTS.md。

项目根目录可以放：
PR14

示例：
PR15

这份文件就像给 Codex 准备的项目说明书。

你也可以写全局的：
PR16

全局文件适合放个人长期偏好：
PR17

项目文件适合放项目特有规则：
PR18

AGENTS.md 的关键不是写得多，而是写得具体。

“写高质量代码”这种话太虚。“修改后运行 pnpm test，不要新增依赖，不要改 migrations 目录”才是真正能执行的规则。

AGENTS.md 的层级加载

AGENTS.md 不是只能放一个，它可以按目录分层。

假设项目结构如下：
PR19

根目录写通用规则，frontend 写前端规则，payment 写支付模块特殊规则。

比如根目录：
PR20

支付目录可以更严格：
PR21

这样 Codex 在支付模块工作时，会同时理解通用规则和局部规则。

这个设计很适合大项目。

因为大项目里不同目录规则往往不一样。前端关心组件、样式、交互；后端关心接口、数据库、鉴权；支付模块又额外关心安全和状态流转。

如果所有内容都塞进根目录一个 AGENTS.md，要么文件特别长，要么约束不够精确。

更好的方式是：

这就是“配置靠近使用位置”。

MCP：给 Codex 扩展外部工具

Codex 本身能读写文件、执行命令，但如果想连接更多外部工具，就需要 MCP。

可以把 MCP 理解为工具接入协议。通过 MCP，Codex 可以连接 GitHub、浏览器、数据库、文档系统等。

示例配置：
PR22

这段配置大致表示：启动一个名为 github 的 MCP 服务。

字段含义：

command：启动命令
args：启动参数
startup_timeout_sec：启动超时时间
tool_timeout_sec：工具调用超时时间

如果需要 token，不建议直接写死在配置文件里：
PR23

这样很危险，容易被误提交。

更推荐通过环境变量：
PR24

MCP 的价值在于让 Codex 不只看本地代码。

比如：

接 GitHub：读 issue、PR、仓库信息
接浏览器：检查页面效果、调试交互
接数据库：看表结构、辅助写 SQL
接文档系统：读取团队规范

但 MCP 不是越多越好。

每接一个工具，就多一份权限风险。我的建议是按需接入：确实能提升效率再配，不熟悉的服务不要随便开，敏感权限一定要控制好。

常见误区

误区一：把所有东西都写进 config.toml

config.toml 适合写结构化配置，不适合写一大段项目规范。

项目规则建议放 AGENTS.md。

正确分工：

工具行为写 config.toml
项目规范写 AGENTS.md

误区二：权限直接开最大

有些同学为了方便直接写：
PR28

这样确实爽，但风险也高。

真实项目里更建议：
PR29

误区三：AGENTS.md 太空

只写一句：
PR30

基本没用。

因为“高质量”不可执行。

应该写成：
PR31

误区四：AGENTS.md 太长

也不要把所有业务文档都塞进去。

太长会稀释重点。

更好的方式是：

AGENTS.md 写规则
docs 写详细文档
需要时让 Codex 去读 docs

误区五：把密钥写进配置文件

不要把 token、key、password 直接写进仓库里的配置。

真实密钥走环境变量，不要进 Git。

行业趋势：为什么 AI 编程工具配置越来越重要

AI 编程工具正在经历一个明显的转变：从“代码补全”走向“开发代理”。

2023 年，主流 AI 编程工具的核心能力还是补全下一行代码、生成函数体。到了 2024 年，GitHub Copilot、Codex、Cursor 等工具都在往“理解项目上下文、执行多步骤任务”的方向演进。

这个转变背后有两个驱动力：

第一，模型能力提升。 GPT-4 之后的模型对代码的理解深度、上下文窗口长度、推理能力都有了质的飞跃。模型不再只是“猜你接下来要写什么”，而是能理解“这个项目的架构是什么”“这个 bug 可能的原因有哪些”。
第二，开发者需求变化。 随着项目复杂度增加，开发者越来越需要工具能处理重复性开发工作，而不是只做简单的代码补全。修 bug、写测试、重构、迁移代码——这些才是真正消耗时间的地方。

但能力越强，风险边界就越需要明确。这就是为什么配置体系变得如此重要。

如果你正在筛选类似工具，可以参考「