用了3个月 Codex CLI，我把这些最佳实践整理成了保姆级指南

从"能用"到"好用"，中间隔着一份 AGENTS.md、一套 Profile 配置，和一条永远不会跑在主分支上的 worktree

从"能用"到"好用"，中间隔着一份 AGENTS.md、一套 Profile 配置，和一条永远不会跑在主分支上的 worktree。这篇文章不讲安装登录，只讲日常高强度使用时真正影响效率和安全性的东西——每一条都经过实战验证，可以直接抄作业。

1AGENTS.md：投入产出比最高的一件事

如果说整篇文章你只能记住一条，那就是：写好 AGENTS.md。

AGENTS.md 是 Codex 的长期记忆文件，放在项目根目录，每次会话自动加载。它相当于给代理一份"项目入职手册"，让它知道技术栈、编码规范、常用命令和禁区。

一个好的 AGENTS.md 应该长这样：

<span leaf=""># 项目约定</span><span leaf=""><br></span><span leaf=""><br></span><span leaf="">## 技术栈</span><span leaf=""><br></span><span leaf="">- TypeScript + Node.js 20</span><span leaf=""><br></span><span leaf="">- Fastify 框架</span><span leaf=""><br></span><span leaf="">- PostgreSQL + Drizzle ORM</span><span leaf=""><br></span><span leaf="">- Vitest 测试框架</span><span leaf=""><br></span><span leaf=""><br></span><span leaf="">## 规范</span><span leaf=""><br></span><span leaf="">- 所有函数必须有返回类型注解，禁止 any</span><span leaf=""><br></span><span leaf="">- 错误处理统一用 Result&lt;T, E&gt; 模式，不要裸抛异常</span><span leaf=""><br></span><span leaf="">- API 响应格式：{ data, error }</span><span leaf=""><br></span><span leaf="">- 测试文件放在源文件同级目录：foo.ts → foo.test.ts</span><span leaf=""><br></span><span leaf=""><br></span><span leaf="">## 常用命令</span><span leaf=""><br></span><span leaf="">- pnpm dev：启动开发服务器</span><span leaf=""><br></span><span leaf="">- pnpm test：运行测试</span><span leaf=""><br></span><span leaf="">- pnpm lint：代码检查</span><span leaf=""><br></span><span leaf="">- pnpm build：构建生产包</span><span leaf=""><br></span><span leaf=""><br></span><span leaf="">## 禁止事项</span><span leaf=""><br></span><span leaf="">- 不要未经询问添加新依赖</span><span leaf=""><br></span><span leaf="">- 不要修改 Prisma schema 除非有迁移指令</span><span leaf=""><br></span><span leaf="">- 不要用 console.log，使用 /lib/logger.ts 中的 logger</span>

三条原则：

命令清单比自然语言有效

写"跑 pnpm test:unit"比写"记得跑单元测试"更不容易被误解。
说清"不要做什么"

负面约束比正面引导更省 token，也更安全。
保持简短

AGENTS.md 每次会话都进上下文，越长越贵越容易淹没重点。

进阶技巧：分层 AGENTS.md。Codex 支持级联加载，项目根目录放全局约定，子目录放局部规则：

<span leaf="">project/</span><span leaf=""><br></span><span leaf="">├── AGENTS.md &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;← 全局约定</span><span leaf=""><br></span><span leaf="">├── src/</span><span leaf=""><br></span><span leaf="">│ &nbsp; ├── api/</span><span leaf=""><br></span><span leaf="">│ &nbsp; │ &nbsp; └── AGENTS.md &nbsp;← API 层规则</span><span leaf=""><br></span><span leaf="">│ &nbsp; └── db/</span><span leaf=""><br></span><span leaf="">│ &nbsp; &nbsp; &nbsp; └── AGENTS.md &nbsp;← 数据库规则</span>

Codex 会从项目根到当前工作目录，按顺序合并所有 AGENTS.md。更深的文件优先级更高。这意味着你可以把规则贴近代码——API 层写接口约定，数据库层写迁移规则，互不干扰。

2审批与沙箱：两条独立的轴，别搞混了

这是 Codex 区别于多数终端代理的核心设计，也是新手最容易踩坑的地方。

审批策略决定"要不要问你"，沙箱模式决定"操作能改什么、能不能联网"。它们是两条独立的轴：

| 审批策略

含义

适合场景


`untrusted`

每个命令、每次写都问

不熟的仓库、危险操作

| | on-failure |

命令在沙箱跑，失败才问

日常开发（推荐）

| | on-request |

只有模型主动请求时才问

信任的、范围明确的任务

| | never |

从不问，全自动

必须配合强沙箱或外部隔离

| 沙箱模式

文件访问

网络访问

适合场景


`read-only`

只读

禁用

探索、问答、审查

| | workspace-write |

只能写工作区

默认禁用

日常改代码

| | danger-full-access |

任意位置

开放

容器/VM 内的全自动

日常推荐的甜点档：codex --full-auto 等价于 on-failure 审批 + workspace-write 沙箱。命令在可写工作区里跑，只在失败时打断你，写操作自动放行。这是"在本地放心让它干活"的常用组合。

安全红线：

永远不要在主分支上用 full-auto。用 git worktree 创建隔离的工作目录，出问题直接删掉重来。
需要联网时（装依赖、拉数据），在配置里显式放开，而不是直接上 danger-full-access。
项目级 .codex/config.toml 默认不被信任。第一次在新仓库启用需手动设置 trust_level = "Trusted"。

3config.toml 配置：一个文件管一切

Codex 的配置文件是 ~/.codex/config.toml，TOML 格式。以下是一份经过实战检验的推荐配置：

<span leaf=""># 基础设置</span><span leaf=""><br></span><span leaf="">model = "gpt-5-codex"</span><span leaf=""><br></span><span leaf="">model_reasoning_effort = "high"</span><span leaf=""><br></span><span leaf="">approval_policy = "on-failure"</span><span leaf=""><br></span><span leaf="">sandbox_mode = "workspace-write"</span><span leaf=""><br></span><span leaf=""><br></span><span leaf=""># 隐藏内部推理过程，减少终端噪音</span><span leaf=""><br></span><span leaf="">hide_agent_reasoning = true</span><span leaf=""><br></span><span leaf=""><br></span><span leaf=""># 允许沙箱内联网</span><span leaf=""><br></span><span leaf="">[sandbox_workspace_write]</span><span leaf=""><br></span><span leaf="">network_access = true</span><span leaf=""><br></span><span leaf=""><br></span><span leaf=""># 启用 Web 搜索</span><span leaf=""><br></span><span leaf="">[tools]</span><span leaf=""><br></span><span leaf="">web_search = true</span><span leaf=""><br></span><span leaf=""><br></span><span leaf=""># 通知：任务完成时播放提示音（macOS）</span><span leaf=""><br></span><span leaf="">notify = ["bash", "-lc", "afplay /System/Library/Sounds/Ping.aiff"]</span>

关于 model_reasoning_effort，这是最推荐的调参点：

| 强度

适合任务


`minimal`

格式化输出、加注释等几乎不需要想的杂活

| | low |

快速问答、小 bug 修复

| | medium

（默认）

日常编码

| | high |

难调试、架构改动、大范围重构

经验法则：先用 medium 跑，卡住再升 high，比一开始就拉满更省。临时切换不需要改配置文件：

<span leaf="">codex -c model_reasoning_effort=high "为什么这个并发测试会偶发死锁"</span>

4Profile：一套配置，多个人格

同一份 config.toml 里可以定义多个 Profile，按场景一键切换：

<span leaf=""># 审查模式：高推理、只读、每步都问</span><span leaf=""><br></span><span leaf="">[profiles.review]</span><span leaf=""><br></span><span leaf="">model = "gpt-5-codex"</span><span leaf=""><br></span><span leaf="">model_reasoning_effort = "high"</span><span leaf=""><br></span><span leaf="">approval_policy = "untrusted"</span><span leaf=""><br></span><span leaf="">sandbox_mode = "read-only"</span><span leaf=""><br></span><span leaf=""><br></span><span leaf=""># 快速模式：小模型、低推理、全自动</span><span leaf=""><br></span><span leaf="">[profiles.quick]</span><span leaf=""><br></span><span leaf="">model = "gpt-5-mini"</span><span leaf=""><br></span><span leaf="">model_reasoning_effort = "low"</span><span leaf=""><br></span><span leaf="">approval_policy = "never"</span><span leaf=""><br></span><span leaf="">sandbox_mode = "workspace-write"</span><span leaf=""><br></span><span leaf=""><br></span><span leaf=""># 分析模式：只读不写，深度推理</span><span leaf=""><br></span><span leaf="">[profiles.analyze]</span><span leaf=""><br></span><span leaf="">model = "gpt-5-codex"</span><span leaf=""><br></span><span leaf="">model_reasoning_effort = "high"</span><span leaf=""><br></span><span leaf="">sandbox_mode = "read-only"</span><span leaf=""><br></span><span leaf="">approval_policy = "never"</span>

使用时用 -p 切换：

<span leaf="">codex -p review "审查这次改动，找潜在的竞态条件"</span><span leaf=""><br></span><span leaf="">codex -p quick &nbsp;"给这个函数加个 docstring"</span><span leaf=""><br></span><span leaf="">codex -p analyze "分析这个模块的架构，给出重构建议"</span>

Profile 适合"同一台机器、不同心意"的场景。团队可以共享一份配置，各自按需切换。

5结构化 Prompt：给 Codex 一份需求文档

Codex 不是"猜意图"工具。Prompt 越结构化，输出质量越高。对比一下：

❌ 普通写法：“加一个用户资料编辑功能”

✅ 结构化写法：

<span leaf="">任务：添加用户资料编辑功能</span><span leaf=""><br></span><span leaf=""><br></span><span leaf="">需求：</span><span leaf=""><br></span><span leaf="">1. API 端点：PUT /api/users/:id</span><span leaf=""><br></span><span leaf="">2. 输入校验：name（字符串，1-100字符），bio（字符串，最长500字符）</span><span leaf=""><br></span><span leaf="">3. 权限控制：用户只能编辑自己的资料</span><span leaf=""><br></span><span leaf="">4. 前端：表单组件位于 /settings/profile</span><span leaf=""><br></span><span leaf=""><br></span><span leaf="">测试：</span><span leaf=""><br></span><span leaf="">- API 端点单元测试</span><span leaf=""><br></span><span leaf="">- 完整流程集成测试</span><span leaf=""><br></span><span leaf=""><br></span><span leaf="">约束：</span><span leaf=""><br></span><span leaf="">- 使用 /lib/auth.ts 中已有的认证中间件</span><span leaf=""><br></span><span leaf="">- 遵循 /lib/api-response.ts 中已有的响应格式</span>

这种写法产出的代码，一次通过率远高于模糊指令。

其他 Prompt 技巧：

用 @ 引用文件

@src/utils/auth.ts 里的 token 校验逻辑有 bug，帮我修，比描述文件内容更准确。
分步迭代

第一轮要架构建议，第二轮要实现细节，第三轮要性能优化。每轮都在同一会话里，Codex 保持上下文。
先 Dry Run

用 suggest 模式让它先出方案，确认方向对了再切 auto-edit 执行。

6Git 工作流集成：从 Issue 到 PR 一条龙

Codex 的 Git 集成是它最强的特性之一。几个高频工作流：

Issue → PR 一键流：

<span leaf="">codex "实现 issue&nbsp;#142&nbsp;描述的功能。完成后创建 PR"</span>

Codex 读取 issue、实现功能、创建分支、提交、推送、开 PR，一条命令搞定。

CI 修复循环：

<span leaf="">codex "PR&nbsp;#87&nbsp;的 CI 挂了。读错误日志，修掉问题"</span>

自动 PR 描述：

<span leaf="">codex "看 main..HEAD 的 diff，写一个清晰的 PR 描述"</span>

冲突解决：

<span leaf="">codex "git merge main 有冲突，帮我解决，优先保留当前分支的业务逻辑"</span>

7自动化：codex exec 让 CI 也能用

codex exec 是非交互模式，适合脚本和 CI/CD：

<span leaf=""># 在 CI 中自动修复 lint 错误</span><span leaf=""><br></span><span leaf="">codex exec --approval-mode full-access \</span><span leaf=""><br></span><span leaf="">&nbsp; "运行 eslint，自动修复所有可修复的问题" \</span><span leaf=""><br></span><span leaf="">&nbsp; --json | jq -r '.result'</span>

--json 输出 JSONL 事件流，方便程序化处理。--output-schema 可以要求输出符合指定 JSON Schema。

CI 集成示例（GitHub Actions）：

<span leaf="">- name: Auto-fix lint errors</span><span leaf=""><br></span><span leaf="">&nbsp; run: |</span><span leaf=""><br></span><span leaf="">&nbsp; &nbsp; codex exec --approval-mode full-access \</span><span leaf=""><br></span><span leaf="">&nbsp; &nbsp; &nbsp; "运行 eslint，自动修复所有可修复的问题，提交结果"</span><span leaf=""><br></span><span leaf="">&nbsp; env:</span><span leaf=""><br></span><span leaf="">&nbsp; &nbsp; OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}</span>

8MCP 工具扩展：让 Codex 长出更多手

Codex 支持 MCP（Model Context Protocol），在 config.toml 中配置：

<span leaf="">[mcp_servers.context7]</span><span leaf=""><br></span><span leaf="">command = "npx"</span><span leaf=""><br></span><span leaf="">args = ["-y", "@upstash/context7-mcp@latest"]</span><span leaf=""><br></span><span leaf=""><br></span><span leaf="">[mcp_servers.figma]</span><span leaf=""><br></span><span leaf="">command = "npx"</span><span leaf=""><br></span><span leaf="">args = ["-y", "mcp-remote", "http://127.0.0.1:3845/sse"]</span>

目前 Codex 仅支持 stdio 通信的 MCP 服务器。SSE 类型的需要通过 mcp-remote 或 mcp-proxy 适配。配置后在会话中用 /mcp 查看状态。

9常见陷阱与排错

| 问题

排查方向

配置不生效

五层优先级：CLI 参数 > Profile > 项目配置 > 用户配置 > 系统配置。用 codex --debug-config 排查

| |

AGENTS.md 没被读取

检查文件是否在项目根目录（.git 所在位置）。Codex 从 cwd 往上找，直到 git root

| |

用量超限

简单任务切 gpt-5-mini 或降低 model_reasoning_effort。长会话用 /compact 压缩历史

| |

项目配置被忽略

新仓库的项目级配置默认不信任，需在 config.toml 中设置 trust_level = "Trusted"

| |

Windows 兼容性

CLI 版推荐通过 WSL 使用。如必须原生 Windows，确保 Node.js ≥ 18

10日常工作流总结

把上面所有内容串起来，一个高效的 Codex 日常应该是这样的：

项目初始化：写好 AGENTS.md，定义技术栈、规范、命令、禁区
配置 baseline：config.toml 设好模型、推理强度、审批策略、沙箱模式
按场景切 Profile：审查用 review，快活用 quick，分析用 analyze
在 git worktree 里干活：git worktree add ../feature-x feature-x，然后 cd 进去开 –full-auto
结构化 Prompt：给任务、给需求、给测试、给约束
用 Git 集成收尾：让 Codex 写 PR 描述、修 CI、解冲突
重复流程固化：用 codex exec + –json 把机械流程写进脚本

结语

Codex CLI 的能力可以拆成五层：模型层选大脑、上下文层喂知识、工具层给手脚、安全层画边界、自动化层固流程。

高阶用法的关键不是"写更长的 Prompt"，而是把这五层分清楚：事实放 AGENTS.md，场景切换交给 Profile，安全边界放审批与沙箱，机械流程交给 exec 与脚本。

工具的天花板不在于工具本身，而在于使用者的工作流设计。当你不再需要思考"该用什么模式、该写什么 Prompt"的时候，Codex 才真正从一个工具变成了你的协作伙伴。

如果这篇文章对你有帮助，欢迎点赞、在看、转发三连 ❤️

想了解更多 AI 编程实践，关注这个公众号，我们下期见。

文章目录

用了3个月 Codex CLI，我把这些最佳实践整理成了保姆级指南