1. 为什么你的 Codex CLI 总是越改越乱Codex CLI 不是只能生成代码片段它可以在你选定的目录里读取仓库、编辑文件、执行命令。新功能开发、Bug 排查、前端页面实现、组件重构、接口联调、测试补齐、代码审查、文档生成、脚本自动化、项目结构理解、技术债梳理这些它都能干。但问题也恰恰出在这里能力边界太宽如果你不给它划定范围它就会在你不希望它动的地方动手。我见过太多人用 Codex CLI 的方式是打开终端敲一句“帮我优化一下这个项目”然后看着它一口气改了十几个文件跑完测试挂了一半回头 diff 都看不完。这不是模型不行是工作流没建好。越是模糊、跨模块、影响面大的任务越应该先让它规划、定位、确认边界再让它改代码。这篇文章想把我这 8 个月总结出来的 Codex CLI 高阶工作流分享出来。核心思路就四件事项目规则沉淀到 AGENTS.md个人默认配置沉淀到 ~/.codex/config.toml重复任务沉淀成 Skills外部上下文交给 MCP。再配合 Plan 模式、截图 Playwright 闭环、review/diff/sandbox 控制以及 codex exec 自动化把一套稳定提效系统跑起来。适合谁看已经在用 Codex CLI 但觉得输出不稳定、改动范围不可控、每次都要重新解释项目背景的开发者。如果你还没装 Codex CLI这篇文章的配置骨架同样适用照着搭就行。2. 前置准备TaoToken 接入与 Codex CLI 环境Codex CLI 要跑起来首先得有一个稳定的模型接入点。我目前用的是 TaoToken 的 API 服务它兼容 OpenAI 风格的接口配置到 Codex CLI 里很直接。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。你需要先去控制台创建一个 API Key。打开 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 在 API Keys 页面生成一个 key复制出来备用。如果你对模型能力有疑问可以先去模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 试一下对话效果确认模型响应正常再接入 CLI。Codex CLI 的安装方式这里不展开假设你已经装好了。接下来要做的是把 TaoToken 的接入信息写进 Codex CLI 的配置文件。Codex CLI 读取的是 ~/.codex/config.toml这个文件同时承载个人默认配置和模型接入信息。一个最小可用的 config.toml 长这样# ~/.codex/config.toml model gpt-4.1 model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY wire_api chat然后在 shell 里导出环境变量export TAOTOKEN_API_KEYsk-你的key如果你用的是 zsh把这一行加到 ~/.zshrcbash 就加到 ~/.bashrc。这样每次开终端都自动生效。注意不要把 API Key 直接写进 config.toml 明文里用 env_key 引用环境变量更安全也方便团队里每个人用自己的 key。配置完成后跑一句codex --version确认 CLI 正常再跑一句简单的codex 输出当前目录的文件列表确认模型能通。这一步通了后面的工作流才有基础。3. AGENTS.md 边界约束把项目规则固化下来AGENTS.md 是整个工作流的地基。它的作用是告诉 Codex CLI这个项目里什么能做、什么不能做、按什么规范做。没有它每次对话你都要重复解释“我们用 Tailwind”“组件放 src/components”“不要动 legacy 目录”效率极低而且容易漏。AGENTS.md 放在项目根目录Codex CLI 会自动读取。下面是我在真实项目里反复调出来的骨架你可以直接复制改# AGENTS.md ## 项目概览 - 技术栈Next.js 14 TypeScript Tailwind CSS Zustand - 包管理器pnpm - 测试Vitest Playwright ## 目录约定 - 页面路由src/app - 可复用组件src/components - 业务逻辑src/features - 工具函数src/lib - 类型定义src/types ## 编码规范 - 一律使用函数式组件 hooks - 样式只用 Tailwind不写内联 style不新增 CSS 文件 - 状态管理优先用 Zustand禁止引入 Redux - 所有导出函数必须有 TypeScript 类型标注 ## 边界约束 - 不要修改 src/legacy 目录下的任何文件 - 不要升级 package.json 里的依赖版本除非我明确要求 - 不要删除任何现有测试用例 - 不要改动 .env 和 CI 配置文件 - 单次任务修改文件数不超过 8 个超出先停下来问我 ## 验证要求 - 改完代码必须运行pnpm lint pnpm typecheck - 涉及页面改动必须运行pnpm build - 涉及交互改动必须用 Playwright 验证 ## 输出要求 - 说明改了哪些文件 - 说明哪些地方是推断的 - 说明还有哪些不确定项需要人工确认这份骨架的关键在“边界约束”和“验证要求”两段。前者防止它乱动后者保证它改完能自检。我试过把“单次任务修改文件数不超过 8 个”这条加上之后Codex 的输出明显收敛了很多不再一口气改二十个文件。AGENTS.md 不是写一次就完事。每次你发现 Codex 又犯了同样的错就把对应的约束补进去。比如它老是忘记跑 typecheck你就在验证要求里写死。这样迭代几轮AGENTS.md 就变成了团队的项目宪法。4. MCP 工具链接入 Playwright 做端到端验证AGENTS.md 管的是“规则”MCP 管的是“能力”。Codex CLI 本身只能读写文件和执行命令但通过 MCPModel Context Protocol你可以给它接上外部工具。前端任务里最值得接的就是 Playwright因为它能让 Codex 打开真实浏览器、截图、对比、迭代。MCP 的配置写在 ~/.codex/config.toml 里。一个 Playwright MCP 的配置片段[mcp_servers.playwright] command npx args [-y, playwright/mcplatest]配好之后重启 Codex CLI它就能调用 Playwright 的工具了。你可以这样验证codex 用 Playwright 打开 https://example.com 并截图保存到 ./tmp/example.png如果它能正常打开浏览器并生成截图说明 MCP 通了。接下来是完整的前端视觉闭环工作流。参考图 → 实现页面 → 启动本地服务 → 浏览器打开 → 截图对比 → 修正 → 再检查。提示词可以这样写codex -i ./references/home.png 请实现这张参考图对应的页面并使用 Playwright 做视觉验证。 要求 1. 先确认本项目如何启动本地开发服务。 2. 实现页面后启动服务。 3. 使用 Playwright 打开页面并截图。 4. 对比参考图和当前截图修正明显差异。 5. 至少检查 desktop 和 mobile 两个断点。 6. 最后输出差异说明和验证结果。 这里-i是给初始 prompt 附加图片支持 PNG、JPEG多张可以逗号分隔或重复传入。图片只负责提供视觉目标不负责替代工程上下文。如果只给一张截图它能做出大概效果如果同时给出页面多个状态和细节还原会稳定很多。更稳的做法是分两步。第一步只让它分析不改代码codex -i ./screenshots/home.png 先不要改代码。 请分析这张截图并结合当前项目结构输出 1. 页面结构 2. 组件拆分 3. 样式系统映射 4. 需要新增/复用的组件 5. 可能不清晰的截图细节 6. 实现计划 第二步再让它按计划实现codex resume --last 按照上一步计划实现页面。 要求小步修改优先复用已有组件。 完成后运行 lint、typecheck、build。 如果有样式偏差说明原因。 codex resume --last会接着上一次会话继续上下文不丢。这个“先分析再实现”的两段式是我踩过坑之后固定下来的直接让它干它容易在没理解项目结构的情况下就动手改出来的东西风格对不上。5. Skills 沉淀把重复动作变成可复用命令Skills 是 Codex CLI 里容易被忽略但极其提效的一环。它的思路很简单把重复任务沉淀成可复用的动作下次一句话就能触发。比如你经常要做“截图转页面”就可以把它写成一个 Skill。Skill 本质上是一段预定义的 prompt 模板放在 ~/.codex/skills 目录下。一个截图转页面的 Skill 示例# ~/.codex/skills/screenshot-to-page.md ## 触发词 截图转页面 ## 执行步骤 1. 读取用户提供的截图路径 2. 分析页面结构、组件拆分、样式映射 3. 输出实现计划等待确认 4. 按计划实现优先复用现有组件 5. 运行 lint、typecheck、build 6. 用 Playwright 截图对比 7. 输出差异说明配好之后你只需要说“截图转页面参考图在 ./references/home.png”Codex 就会按这套流程走。再比如 Bug 排查也可以沉淀成 Skill。把报错日志和范围告诉它越清晰越好它理解起来和改动都会越稳因为有了范围限制它不会乱改codex 日志在 ./logs/history.log。 请基于日志排查并处理这个问题。 工作方式 1. 先不要改代码。 2. 找到可能相关的页面、组件、状态管理、接口请求和样式文件。 3. 说明最可能的 2-3 个原因。 4. 如果可以运行项目请尝试复现。 5. 确认根因后再做最小修改。 6. 修改后运行相关检查。 7. 最后说明根因、改动文件、验证方式。 大重构任务更要拆开。老项目本身就复杂AI 理解起来也困难千万不要让它直接改。拆成四层理解现状 → 识别风险 → 制定迁移计划 → 分批执行。提示词codex 我准备重构当前项目的组件结构。先不要改代码。 请输出 1. 当前组件目录结构和主要职责 2. 重复代码和可抽象点 3. 高风险文件 4. 推荐的目标目录结构 5. 分阶段迁移计划 6. 每阶段的验证方式 7. 哪些地方不建议现在动 这套四层拆解跑下来重构的稳定性比直接让它改高出一个量级。6. 完整跑通从改代码到浏览器验证把前面几块拼起来就是一轮完整的跑通动作。假设你要实现一个新页面流程是这样的第一步确认 AGENTS.md 和 config.toml 都已就位MCP Playwright 已配置。跑一句codex 读取 AGENTS.md 并总结项目约束确认它能读到规则。第二步进入 Plan 模式让它收集上下文、提出问题、形成计划后再实现codex --sandbox workspace-write --ask-for-approval on-request 我要实现首页参考图在 ./references/home-desktop.png 和 ./references/home-mobile.png。 先阅读项目结构确认路由、组件目录、样式方案、设计系统和已有页面实现。 再分析截图中的布局、组件层级、间距、字体、颜色、响应式规则。 输出实现计划等我确认。 第三步确认计划后让它实现codex resume --last 按计划实现。优先复用现有组件、tokens、Tailwind 配置和项目约定不要另起一套风格。 完成后运行 lint、typecheck、build。 最后说明改了哪些文件、哪些地方是根据截图推断的、还有哪些视觉差异需要人工确认。 第四步用 Playwright 做视觉验证。如果实现效果和目标图有差距让它自动对比修复codex resume --last \ -i ./references/target.png \ -i ./screenshots/current.png \ 第一张是目标图第二张是当前实现效果。 请对比差异只修复视觉差异不要重构无关代码。 重点检查 1. 页面整体比例 2. 顶部间距 3. 标题字号和字重 4. 卡片圆角、阴影、边框 5. 按钮尺寸和位置 6. 移动端断点 7. 是否存在横向溢出 完成后运行检查并输出修改点。 第五步稳定任务用 codex exec 自动化。比如每天跑一次 lint 修复codex exec 运行 pnpm lint修复所有可自动修复的问题不要改动业务逻辑这一轮跑下来从改代码到浏览器验证形成闭环。风险任务用 review/diff/sandbox 控制稳定任务用 codex exec 自动化整个系统就转起来了。7. 常见报错与排查问题一Codex 读不到 AGENTS.md。确认文件在项目根目录且文件名大小写正确。Codex CLI 只读根目录的 AGENTS.md子目录里的不会自动加载。如果你在子目录里跑 codex先 cd 到项目根。问题二MCP Playwright 启动失败。多半是 npx 找不到包或者网络问题。先手动跑npx -y playwright/mcplatest看能不能启动。如果报浏览器未安装跑npx playwright install chromium。另外确认 config.toml 里 mcp_servers 的 command 和 args 拼写正确。问题三模型请求 401 或 403。检查 TAOTOKEN_API_KEY 环境变量是否导出成功跑echo $TAOTOKEN_API_KEY确认。如果为空说明 shell 配置没生效重新 source 一下。另外确认 config.toml 里 env_key 写的是 TAOTOKEN_API_KEY和导出的变量名一致。问题四Codex 改了不该改的文件。这是 AGENTS.md 边界约束没写全。把对应目录或文件加进“不要修改”列表再跑一次。如果已经改了用git diff看改动git checkout回滚不需要的部分。问题五Playwright 截图对比总是有差异。检查是不是字体渲染或动画导致的。可以在提示词里加“忽略字体抗锯齿差异和动画中间态”。另外确认对比的两张图尺寸一致desktop 和 mobile 分开对比。问题六codex resume --last 接不上上下文。确认上一次会话没有异常退出。如果接不上用codex resume列出历史会话手动选一个。另外注意 resume 只在同一目录下有效。问题七codex exec 自动化跑飞了。自动化任务一定要加边界。在 AGENTS.md 里写清楚自动化任务允许改动的范围或者用--sandbox read-only先跑一遍看它打算做什么确认没问题再放开写权限。如果你在接入或排障过程中卡住可以去 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 检查 key 状态或者翻一下接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里的配置示例。长期做编码和 Agent 任务的话Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 的额度模型更适合高频调用。Claude Code 用户可以参考 Anthropic 接入页 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude_code_anthropicutm_campaignrewrite 的配置方式。最后说一个我踩过的坑AGENTS.md 里的约束不要一次写太多先写最关键的几条跑一段时间发现新问题再补。一上来写五十条Codex 反而容易顾此失彼。边界是迭代出来的不是设计出来的。