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

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

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

从下面这张图可以快速理解 Codex 的核心使用方式——它不是一个简单的代码补全插件，而是一个能参与完整开发流程的“本地开发代理”：

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

能力变强以后，问题也就跟着来了：它能不能随便改文件？它能不能联网？它遇到危险命令要不要先问我？它怎么知道这个项目用的是 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 的核心配置文件之一。用户级配置一般在 ~/.codex/config.toml，Windows 下通常类似 C:Users你的用户名.codexconfig.toml。如果某个项目需要单独配置，可以在项目里创建 .codex/config.toml。

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

PR0

这几行已经包含了几个关键点：model（默认模型）、model_provider（模型提供方）、approval_policy（审批策略）、sandbox_mode（沙箱模式）。

TOML 的写法比较适合手写配置。相比 JSON，它不用写一堆括号；相比 YAML，它又不容易因为缩进出问题。需要注意的是，顶层字段尽量写在表配置前面，例如：

PR1

不要把顶层字段随便插到某个表下面，否则有些配置可能会被解析成表内字段。可以把 config.toml 理解成 Codex 的启动参数区。Codex 进入项目后，会先读取这些配置，再确定自己以什么模式工作。

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

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

PR2

能力强的模型适合做复杂任务，例如：跨文件 bug 分析、大型重构、测试失败排查、架构设计、复杂代码迁移、多步骤开发任务。速度更快、成本更低的模型适合做轻任务，例如：解释代码、补注释、生成简单脚本、写 README、整理日志、局部小改动。

这和我们平时选数据结构一样。不是所有场景都用红黑树，也不是所有场景都用数组。任务复杂度不同，模型选择也应该不同。如果只是改一个变量名，用最强模型有点浪费。如果是分析一个跨多个模块的线上 bug，用太弱的模型又容易漏上下文。

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

PR3

大致可以这样理解：reasoning_effort 是推理强度，verbosity 是输出详细程度，reasoning_summary 是是否展示推理摘要。

新手不建议一开始把参数调得很复杂。先用默认值，等你发现某类任务经常不够稳，再针对性调整。我的建议是：小改动用 medium 就够，复杂重构要提高 reasoning effort，写文章或解释知识要提高 verbosity，自动化任务输出尽量简洁。配置不是越多越好，能解决问题才是好配置。

权限配置：approval_policy 和 sandbox_mode

Codex 配置里最需要认真理解的，就是权限。因为它直接决定 Codex 能不能改文件、能不能联网、能不能执行命令，以及遇到风险操作时要不要停下来问你。

两个核心字段：

PR4

这两个字段分别解决不同问题：approval_policy 是“什么时候需要问用户”，sandbox_mode 是“Codex 最大能操作到什么范围”。

approval_policy：刹车系统

approval_policy 可以理解成刹车系统。approval_policy = "on-request" 表示：当 Codex 遇到需要更高权限、可能影响系统或项目安全的操作时，会先请求用户确认。日常开发推荐这个模式，因为我们既希望 Codex 能主动干活，又不希望它完全不受控制。

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

sandbox_mode：活动范围

sandbox_mode 可以理解成活动范围。常见有三种：

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

只想让 Codex 分析项目，不想让它改文件，可以用 sandbox_mode = "read-only"。日常开发比较推荐 sandbox_mode = "workspace-write"，这表示 Codex 可以修改当前项目内的文件，但不会随便动系统其它目录。

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

PR5

danger-full-access 权限最大，但名字已经提示得很直白：danger。不是说不能用，而是要知道自己在干什么。真实项目里，不建议新手默认开这个。

两个配置一起看

组合起来看更清楚。比较稳的日常配置：

PR6

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

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

如果说 config.toml 管的是工具行为，那 AGENTS.md 管的就是项目规矩。很多时候，Codex 写得不符合预期，不是因为它不会，而是因为它不知道你的项目规则。

比如：不能随便新增依赖，修改公共接口要更新文档，改完代码要跑测试，不要修改 migrations 目录，C++ 项目要保持头文件依赖简洁，Linux 示例代码要写清楚返回值。这些都适合写进 AGENTS.md。

项目根目录可以放 AGENTS.md，示例：

PR7

这份文件就像给 Codex 准备的项目说明书。你也可以写全局的 ~/.codex/AGENTS.md，适合放个人长期偏好：

PR8

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

PR9

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

AGENTS.md 的层级加载

AGENTS.md 不是只能放一个，它可以按目录分层。假设项目结构如下：

PR10

根目录写通用规则，frontend 写前端规则，payment 写支付模块特殊规则。比如根目录写“保持原有代码风格，修改后运行测试，不做无关重构”。支付目录可以更严格：“不要修改签名算法，除非任务明确要求；不要在日志中输出 token、密钥、手机号；修改支付状态流转时，必须补充边界测试。”

这样 Codex 在支付模块工作时，会同时理解通用规则和局部规则。这个设计很适合大项目，因为大项目里不同目录规则往往不一样。前端关心组件、样式、交互；后端关心接口、数据库、鉴权；支付模块又额外关心安全和状态流转。

如果所有内容都塞进根目录一个 AGENTS.md，要么文件特别长，要么约束不够精确。更好的方式是：根目录写通用规则，模块目录写具体规则，敏感目录写更严格规则。这就是“配置靠近使用位置”。

MCP：给 Codex 扩展外部工具

Codex 本身能读写文件、执行命令，但如果想连接更多外部工具，就需要 MCP。可以把 MCP 理解为工具接入协议。通过 MCP，Codex 可以连接 GitHub、浏览器、数据库、文档系统等。

示例配置：

PR11

这段配置大致表示：启动一个名为 github 的 MCP 服务。字段含义：command 是启动命令，args 是启动参数，startup_timeout_sec 是启动超时时间，tool_timeout_sec 是工具调用超时时间。

如果需要 token，不建议直接写死在配置文件里：token = "ghp_xxxxxxxxx"，这样很危险，容易被误提交。更推荐通过环境变量：env = { GITHUB_TOKEN = "GITHUB_TOKEN" }。

MCP 的价值在于让 Codex 不只看本地代码。比如：接 GitHub 可以读 issue、PR、仓库信息；接浏览器可以检查页面效果、调试交互；接数据库可以看表结构、辅助写 SQL；接文档系统可以读取团队规范。

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

常见误区

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

config.toml 适合写结构化配置，不适合写一大段项目规范。项目规则建议放 AGENTS.md。正确分工：工具行为写 config.toml，项目规范写 AGENTS.md。

误区二：权限直接开最大

有些同学为了方便直接写 sandbox_mode = "danger-full-access" 和 approval_policy = "never"，这样确实爽，但风险也高。真实项目里更建议 sandbox_mode = "workspace-write" 和 approval_policy = "on-request"。