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

# 从聊天到开发搭子：Codex配置实战，零基础调教你的AI编程助手

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

真正把 Codex 放进项目里用一段时间之后，你会发现它更像一个可以参与开发流程的“本地开发代理”。它能读项目、搜文件、改代码、跑测试、看日志，甚至可以通过 MCP 去连接浏览器、仓库、文档系统等工具。能力变强以后，问题也就跟着来了：它能不能随便改文件？它能不能联网？它遇到危险命令要不要先问我？它怎么知道这个项目用的是 pnpm 还是 npm？它怎么知道不要乱改数据库迁移文件？

这些问题不能靠每次聊天临时提醒解决。你每次都说“不要乱加依赖”“改完记得跑测试”“别动生产配置”，不仅麻烦，而且容易漏。所以 Codex 真正好用的关键，不只是模型本身，而是配置。

从下面这张图可以快速理解 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 也可以把个人习惯放全局，把项目规则放仓库，把特殊模块规则放子目录。这样做的好处是清晰：你的个人习惯可以长期保留，项目规则则放在项目里，不同项目加载不同规则，不需要每次都从头交代。

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 是否展示推理摘要。新手不建议一开始把参数调得很复杂，先用默认值，等你发现某类任务经常不够稳，再针对性调整。

Codex 工具评测 中一个常见的误区是：以为配置越多越好。实际上，小改动用 medium 就够，复杂重构才需要提高 reasoning effort，写文章或解释知识时提高 verbosity，自动化任务则输出尽量简洁。配置不是越多越好，能解决问题才是好配置。

权限配置：approval_policy 和 sandbox_mode

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

两个核心字段：

PR4

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

approval_policy：刹车系统

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

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

sandbox_mode：活动范围

常见有三种：read-only（只读）、workspace-write（允许写当前工作区）、danger-full-access（权限基本放开）。

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

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

PR5

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

两个配置一起看

组合起来看更清楚：比较稳的日常配置是 approval_policy = "on-request" 配合 sandbox_mode = "workspace-write"，再加上 network_access = true 和 writable_roots = ["."]。这个配置既不会让 Codex 完全不能动，也不会把系统权限全部交出去。

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

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

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

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

PR6

这份文件就像给 Codex 准备的项目说明书。你也可以写全局的 ~/.codex/AGENTS.md，适合放个人长期偏好，比如“回答先给结论再说明细节”“修改代码前先搜索上下文”“不做无关重构”等。

项目文件适合放项目特有规则，比如“本项目使用 pnpm，不要使用 npm”“前端代码在 apps/web”“后端代码在 services/api”“修改接口后更新 openapi.yaml”“提交前运行 pnpm lint 和 pnpm test”。

Codex 工具适合新手吗？ 答案是肯定的，但前提是 AGENTS.md 写得具体。“写高质量代码”这种话太虚，“修改后运行 pnpm test，不要新增依赖，不要改 migrations 目录”才是真正能执行的规则。

AGENTS.md 的层级加载

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

PR7

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

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

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

MCP：给 Codex 扩展外部工具

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

示例配置：

PR8

这段配置大致表示：启动一个名为 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"。

误区三：AGENTS.md 太空

只写一句“请写出高质量代码”基本没用，因为“高质量”不可执行。应该写成“修改后运行 pnpm test”“不要新增依赖”“不要修改 migrations 目录”“保持原有代码风格”。

误区四：AGENTS.md 太长

也不要把所有业务文档都塞进去，太长会稀释重点。更好的方式是：AGENTS.md 写规则，docs 写详细文档，需要时让 Codex 去读 docs。

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

不要把 token、key、password 直接写进仓库里的配置。真实密钥走环境变量，不要进 Git。

使用建议

Codex 配置实战 这套体系适合以下人群：

推荐：有一定开发经验、希望提升编码效率的开发者；正在维护中大型项目、需要统一代码规范的团队；对 AI 编程工具有兴趣、愿意花时间调教的进阶用户。
不推荐：只是偶尔写几行代码、对配置不感兴趣的新手（可以先从默认配置开始）；项目极其简单、不需要复杂规则的个人小工具；对权限和安全不太敏感、觉得“能用就行”的用户。

Codex 工具免费版够用吗？ 对于个人学习和小型项目，免费版通常够用。但如果你需要更强大的模型（如 GPT-5.5）、更长的上下文窗口、或者更多 MCP 服务接入，付费版会更合适。建议先用免费版跑通配置流程，确认能提升效率后再考虑升级。