企业官网建设流程全解析

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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 端点是 https://taotoken.net/api 。

你需要先去控制台创建一个 API Key。打开 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，在 API Keys 页面生成一个 key，复制出来备用。如果你对模型能力有疑问，可以先去模型对话页面 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite 试一下对话效果，确认模型响应正常再接入 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_KEY="sk-你的key"

如果你用的是 zsh，把这一行加到 ~/.zshrc；bash 就加到 ~/.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 本身只能读写文件和执行命令，但通过 MCP（Model Context Protocol），你可以给它接上外部工具。前端任务里最值得接的就是 Playwright，因为它能让 Codex 打开真实浏览器、截图、对比、迭代。

MCP 的配置写在 ~/.codex/config.toml 里。一个 Playwright MCP 的配置片段：

[mcp_servers.playwright] command = "npx" args = ["-y", "@playwright/mcp@latest"]

配好之后重启 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/mcp@latest看能不能启动。如果报浏览器未安装，跑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_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite 检查 key 状态，或者翻一下接入文档 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 里的配置示例。长期做编码和 Agent 任务的话，Coding Plan https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite 的额度模型更适合高频调用。Claude Code 用户可以参考 Anthropic 接入页 https://taotoken.net/claude-code-anthropic?utm_source=taotoken_aicg_blog_end&utm_content=claude_code_anthropic&utm_campaign=rewrite 的配置方式。

最后说一个我踩过的坑：AGENTS.md 里的约束不要一次写太多，先写最关键的几条，跑一段时间发现新问题再补。一上来写五十条，Codex 反而容易顾此失彼。边界是迭代出来的，不是设计出来的。