企业官网建设流程全解析

最早把 Codex 请进我的开发日常，其实是被一次“重复解释”逼的。那时候我每天在终端里和它对话七八次，每次都得先告诉它“我们这个项目用 pnpm，不要动 src 以外的文件，跑测试要用 npm run test:unit”……第一天还行，第二天就开始烦躁：这些约定为什么不能让工具自己知道？

后来我才反应过来，我一直在把它当“聊天窗口”用，而它真正应该打开的，是开发工作流这一层价值。顺着这个思路，我把 Codex 从“一次对话一个临时任务”的状态里拽了出来，逐步搭出一套可复用的工作流：AGENTS.md 管项目记忆，Skill 管高频动作，脚本管数据沉淀，再通过第三方模型接入和报错排查把底座打扎实。这篇记录，就是这套工作流的完整复盘，适合那些已经用过几次 AI 编程工具、但总觉得每次都在“重复劳动”的开发者。

1. 先搞清楚 Codex 是什么：命令行 Agent 与网页问答的差别

1.1 两个入口，两套心智

Codex 这些年被提得太多了，术语也容易混淆。早些年它指 OpenAI 的代码生成模型，现在已经慢慢演化成产品名，大家挂在嘴边的“用 Codex 开发”，基本是指 2025 年陆续铺开的 Codex CLI 和 Codex 桌面版。CLI 以 npm 包形式发布，装好后在终端里敲codex就能进入对话；桌面版是带界面的客户端，后台是同一个引擎。

我强调这两个入口的差别，是因为很多人的第一印象是“在 Codex 官网登录，网页上聊聊天”。那是网页版 AI 助手的思路，严格说不是 Codex 的工作方式。真正的 Codex 形态是本地 Agent：它被安装进你的开发环境，能直接读你的仓库文件，能执行 shell 命令，能自己跑测试然后根据结果修代码。你给它一个任务，它做完了再回来汇报，而不是等你一段段粘贴代码。这两种心智差别巨大：网页问答是“我提问，它回答”，Codex 是“我派活，它执行”。后面所有关于工作流的升级，都是建立在后一种心智之上的。

1.2 它是“改代码的 Agent”，不是“聊代码的聊天框”

这个区别决定了后面所有用法。我想用三点说清楚。

第一，Codex 拥有操作文件系统和命令行的完整工具链。它可以打开文件、修改文件、创建文件，也可以编译、运行测试、查看 git 状态。这意味着它能处理“帮我跑一下测试，看看为什么挂了”这种闭环请求。网页版聊天框做不到这一点，因为它的沙箱里没有你的代码上下文。

第二，Codex 的执行循环是围绕任务完成的。社区里常说的 codex harness，指的就是驱动它“思考 → 调用工具 → 读取结果 → 再思考”的循环框架。它不是一次性生成一大段代码交给你，而是像工程师一样一步步操作，每步都基于真实运行结果做下一步判断。

第三，Codex 是可配置的。模型可以换，上下文规则可以写进文件，高频动作可以封装成 Skill。这一点是它和 Claude Code 相比最吸引我的地方。Claude Code 开箱即用体验很好，Codex 则更像一套可以改造成“团队标准流程”的基础设施。如果你正在纠结这两个工具怎么选，我的建议是先不要比模型，比一比“谁的文件结构更容易沉淀成团队资产”。

2. 安装与登录：命令行版、桌面版与认证里的第一道门槛

2.1 命令行安装：npm 全局包与二进制包

先讲我最常用的 CLI 安装方式。前提是你机器上有 Node.js，不同版本对 Node 版本要求不一样，我用的版本要求 22 以上，建议先跑node -v确认。版本太老的话用 nvm 装一个新的，别在系统 Node 上硬扛，后面装全局包会省很多事。

在 Ubuntu 环境里全局安装 npm 包最容易遇到权限坑。npm install -g默认写到系统目录，没有写权限时会直接报 EACCES。省心的做法是先用 nvm 管理 Node，这样npm i -g @openai/codex会装到用户目录下，不和系统权限打架。装完运行codex --version，能看到版本号就说明装好了。

Windows 上我更推荐直接下载安装包，或者用 npm 方式安装依赖。官网有桌面版安装包的下载入口，Windows 安装是 exe，macOS 是 dmg。下载时注意从官网入口找，不要点第三方站点的“加速下载”。装好后桌面版会要求登录。另外，Codex 有官方 VS Code 扩展，装完可以在编辑器侧边栏打开面板直接对话，底层调用的还是同一个 CLI。平时主要工作在 VS Code 里的人，这个入口比切终端更顺，但别指望扩展能补齐 CLI 的能力，它只是前端的便利工具。

2.2 桌面版：安装、登录与启动

桌面版看起来像一个普通的聊天客户端，但它的会话组织方式更接近“项目管理器”：一个会话对应一个项目目录，每次会话里 Codex 看到的都是你指定的文件夹。这样你可以把不同项目的上下文隔离开，不用在同一个对话里反复切换工作目录。

登录方式走 ChatGPT 账号，登录后自动带出账号的模型权限。桌面版首次启动如果卡在“正在重新连接”，先看是否是网络环境导致握手失败，再看客户端版本是否过旧。桌面版的自动更新有时会静默失败，界面一直停在“重新连接”，实际上旧版本在反复重试。手动从官网下载最新安装包覆盖安装一次，能解决大多数这个症状的问题。

界面语言方面，Codex 桌面版支持语言设置，在设置面板里可以切换。我更习惯保持英文界面，但提示词一直用中文写。实测它对中文任务描述的理解很好，所以“汉化”这事其实不关键，你只要能把自己的需求说清楚就行。

2.3 两种认证模式：ChatGPT 账号和 API Key

Codex 支持两种认证方式，这直接关系到后面“换模型”“接第三方 API”能不能成立。

第一种是 ChatGPT 账号登录。这种模式下模型由账号所属服务端决定，你在本地想用--model强行指定某个模型，很可能撞上“the 'gpt-5.6-sol' model is not supported when using Codex with a ChatGPT account”这个报错。我的理解是，这个模式下服务端做了模型白名单，只放行账号权限范围内的模型，自定义模型名会被直接拒绝。

第二种是 API Key 模式。用codex login --api-key设置密钥后，Codex 走 API 计费，本地配置对模型名就有了比较大的话语权，也为接第三方 OpenAI 兼容服务铺了路。我的建议是：日常写代码用账号登录体验好；当你准备搭“可复用工作流”、需要在不同模型之间切换时，API Key 模式更可控。判断当前是哪种模式，可以查看登录状态命令。如果发现账号模式和 API Key 模式混用、某些会话报错找不到凭据，回到这一步重新确认就好。

3. 第一次对话的正确姿势：从“帮我写”到“帮我改”

3.1 提示词结构：背景、目标、验收标准

很多人第一次用 Codex 的方式是“帮我写一个登录页”，然后得到一坨能运行但完全不符合项目规范的代码。这不是 Codex 笨，而是你把上下文赖掉了。它刚进项目，不知道你们的目录约定、UI 组件库、接口风格。

我比较稳的提示词结构是三段式：先说背景，再说目标，最后说验收标准。例如：“这是一个人事管理系统，前端用 Vue3 + Element Plus，后端接口已经跑在本地 3000 端口。请帮我新增一个部门管理页面，支持列表查询和新增，页面风格参考现有的用户管理页，不要动后端代码。验收标准：页面能通过浏览器访问，接口调用走现成的 request 封装。”这样它才不会在无关紧要的地方自由发挥。Codex 的输出质量很大程度上取决于你给的上下文质量，第一次对话尤其明显。

另外要给边界。告诉它“不要动什么”和告诉它“要做什么”同样重要。比如“不要升级依赖版本”“不要格式化整个文件”“只改 api 目录下的文件”，这些约束能显著减少返工。也因为这些内容每次对话都要重复，才促使我后来把一部分约束写进了 AGENTS.md。

3.2 沙箱与权限：放心让它动手的前提

Codex 默认跑在沙箱里，沙箱内对文件系统的写入和命令执行都受限。你用交互模式聊着聊着，它会弹出权限请求，问你允不允许执行某条命令或写入某个文件，你确认之后它才动手。

这个机制的意义在于：你可以放心放手让它做局部修改，它不会自己去动你的数据库或删除目录。但我建议一开始不要图省事直接开全自动模式，全自动模式虽然爽，但如果你对它还不够信任，一条出错命令的代价可能很高。

实测下来，比较合理的策略是：第一次跑任务时开着沙箱，观察它打算执行哪些命令，心里有数之后，再对重复性任务放开权限。工作流越成熟，你越敢授权；你越授权，它越高效。这是一个正循环。

3.3 单轮执行、交互式与 Watch 模式

Codex 有三种使用节奏，分别对应不同场景：

• codex "修复一下这个 bug"：单轮执行，它做完任务直接退出。适合一次性的明确任务，也适合在脚本里调用。
• 直接敲codex：进入交互式会话，你可以连续对话，边看结果边调整需求。适合探索性任务，比如“先帮我看看这个问题可能出在哪”。
• codex -w：watch 模式，它会监听文件变化，检测到你保存的测试代码或文件被修改后自动接管任务。适合“写测试 → 看它改代码 → 再跑测试”的循环开发节奏。

我个人的习惯是：探索用交互式，落地用单轮，重复性的回归循环用 watch 模式。切换几次之后你会发现，“从一次对话到工作流”的第一步，其实就是把每次对话放到合适的运行节奏里，而不是永远开着同一个交互会话。

4. 核心工作流资产：AGENTS.md 让 Codex 每次对话都自带项目记忆

4.1 AGENTS.md 是什么：给 Agent 看的入职手册

如果你已经按第 3 章的方式用了一段时间 Codex，大概率会和我一样烦一件事：每次开新对话，都要重新交代项目背景。项目规范、构建命令、测试命令、目录约定……好消息是，Codex 实现了 AGENTS.md 机制，专门解决这个“记忆”问题。

简单说，AGENTS.md 是放在项目根目录的一个 Markdown 文件。每次 Codex 在某个目录启动会话时，会主动读取这个文件，把里面的内容作为系统级上下文的一部分。你不用再解释一次项目用什么包管理器，它一进来就知道。

它和 README.md 的区别值得多说一句：README 是给人看的，强调“项目是什么，怎么跑起来”；AGENTS.md 是给 Agent 看的，强调的是“在这个项目里干活必须遵守什么”。所以写 AGENTS.md 不要写一堆背景小作文，要写执行规则。

4.2 一份能直接用的 AGENTS.md 长什么样

我把自己一个仓库里的 AGENTS.md 简化后贴出来，你感受一下信息密度：

# 项目运行约束 - 包管理器：使用 pnpm，不要混用 npm/yarn。 - 开发服务器启动命令：pnpm dev，默认端口 5173。 - 测试命令：pnpm test:unit，覆盖率阈值 80%。 # 目录约定 - src/api 下放所有接口调用，禁止在组件里直接写 fetch。 - src/components 下按页面建目录，公共组件放 src/components/common。 # 代码风格 - TypeScript 严格模式，禁止使用 any。 - Vue 组件使用 <script setup> 语法。 - 样式统一用 UnoCSS 原子类，不写独立 CSS 文件。 # 不允许做的事 - 不要升级依赖版本，除非明确要求。 - 不要格式化与任务无关的文件。 - 不要改动 public 目录下的静态资源。

写完之后，你在该目录下给 Codex 派活，它就会默认遵守这些规则。AGENTS.md 的措辞要像“规则清单”而不是“项目介绍”，这一点很重要。

4.3 多级记忆：用户级、项目级，再到目录级

Codex 的记忆不只一层。用户主目录下有一个全局的 AGENTS.md，一般放在~/.codex/AGENTS.md。这个文件放的是所有项目的通用偏好，比如“默认用 pnpm，如果项目没有锁文件先问我”“不要在代码里写死密钥”“先看 tests 目录再动手修改”。

项目根目录的 AGENTS.md 放这个项目特有的约束。如果某个子目录逻辑特别独立，也可以在子目录再放一个 AGENTS.md，只影响在该目录下进行的任务。这种“全局 → 项目 → 目录”的分层机制，让规则继承非常自然：通用规则在上级，特殊规则在下级覆盖。

我的使用心得是第一层别写太多，全局文件最多十行，否则每个项目都被不必要的规则拖累。把项目特有的东西往下沉，该是哪一层管的就放在哪一层。

5. Skill 机制：把高频操作变成一键触发的标准动作

5.1 Skill 的文件结构与触发方式

AGENTS.md 解决“项目记忆”，Skill 解决“高频动作”。如果你有一个任务每周都要做，比如代码评审、写周报、生成迁移脚本，你肯定不希望每次重新给 Codex 解释应该怎么评、按什么格式输出。Skill 就是用来封装这些的。

在项目里建一个.codex/skills/目录，每个 Skill 用一个子目录，里面放一个SKILL.md文件。文件开头写元信息，包括这个 Skill 的名字和描述，后面写执行步骤和输出格式。Codex 在会话里看到你提到某个 Skill 名字，就会去读取对应的 SKILL.md，然后按里面的步骤执行。比如我建过的一个“周报生成” Skill，描述写的是“根据本周 git 提交历史和任务清单生成周报，按成果、风险、规划三类输出”。每次我说“用周报 skill 生成本周周报”，它就知道要去翻 git log、整理任务文件，最后按固定格式输出，不用我再解释。

5.2 实例：把“代码评审”封装成一个 Skill

我用代码评审为例，给你看一下一个可用的 SKILL.md 大概长什么样：

--- name: code-review description: 对指定分支或文件进行代码评审，关注可维护性和潜在 bug。 --- # 评审步骤 1. 先 `git diff` 查看改动范围，确认涉及哪些文件。 2. 逐个文件阅读 diff，不重写代码，只指出问题。 3. 关注点：空值处理、边界条件、异步异常、命名可读性。 # 输出格式 - 按 严重问题 / 建议改进 / 风格问题 三档输出。 - 每个问题给出：文件路径、行号、原因、修改建议。 - 最后给出整体结论：是否建议合入。

有了这个 Skill，你再也用不着说“帮我看看有没有空指针风险、命名怎么样、需不需要改”，一句话就够。而且团队所有人都用同一个评审判定标准，评审意见的一致性会明显提升。对可复用工作流来说，这种一致性带来的价值比单个任务本身的完成度还大。

5.3 Skill、MCP 和 Harness 的配合

再说说 Skill 和另外两个高频概念的边界。MCP（模型上下文协议）是用来让 Agent 接外部数据的，比如连数据库、读 Jira、查监控；Skill 更偏“做事方法”。两者是配合关系：Skill 负责定义流程，MCP 负责在流程中给 Agent 提供需要的数据。

Harness 是另一个概念，指驱动 Agent 跑完整个“读状态 → 调用工具 → 看结果 → 再行动”循环的框架。Codex 的执行循环是开源的，这也解释了为什么社区里“codex harness”热度一直高：大家不仅能直接用官方 CLI，还能拿这套循环嵌进自己的工具链，或者改造出定制版本。你在网上看到的各种“基于 Codex 的自动化机器人”“Codex 批处理脚本”，本质上都是在 harness 之上叠自己的逻辑。

理解了这三个层次，你对“工作流”的认知会清楚很多：AGENTS.md 管记忆，Skill 管动作，MCP 管数据，harness 管循环。搭建个人任务管理 Agent 的时候，这四层都会用到。

6. 接入第三方模型：以 DeepSeek 为例的配置与 thinking 模式报错拆解

6.1 原理：OpenAI 兼容接口让你能换底座模型

Codex 虽然配 OpenAI 自己的模型体验最好，但它的客户端支持配置第三方 OpenAI 兼容接口。只要服务商提供一个和 OpenAI 接口格式兼容的 API 端点，Codex 就能把请求发到那里，用对方的模型干活。

配置的位置在用户主目录下的~/.codex/config.toml，不同版本字段名略有差异。大致思路是配置模型名、基础服务地址、API 密钥来源。改完后启动 Codex，对话请求就会发到第三方。这件事意义很大：模型在小任务上的智商差异其实没那么大，但价格和稳定性差异巨大。把底座模型做成可切换的，工作流才不会绑死在一个模型上。你写的 AGENTS.md、Skill 都不依赖具体模型，换模型只是换引擎。

另外，很多开发者喜欢用社区里的 API 配置切换工具来管理多套服务商配置，比如 CC Switch 这类工具。它的核心价值是：你不需要反复改 config.toml，在图形界面里选一下服务商，本地配置就替换成对应的一套。下面 DeepSeek 的接入，我就用这类工具做演示。

6.2 DeepSeek 接入的两种路径

第一种是直连 DeepSeek 官方 API。在配置里把基础地址指向 DeepSeek 的兼容端点，模型名填 DeepSeek 服务端真正支持的模型标识，API 密钥填 DeepSeek 的密钥。这种路径最干净，适合只打算用一个第三方模型的场景。

第二种是走 CC Switch 这类配置切换工具。它会暴露一个本地转发层，Codex 配置的地址填这个转发层，转发层再按你选中的服务商把请求转出去。好处是切换服务商时不用改 Codex 配置，只在工具里点一下。

两条路径我都跑过，最终我留下了“直连 DeepSeek + 直连 OpenAI”两套配置，偶尔用切换工具体验新模型。选哪条不关键，关键是你必须清楚请求链路：Codex 发出的请求去了哪里，中间有没有多一层转换。多一层转换就多一个出错点。

6.3 关键报错：thinking 模式下 reasoning_content 必须回传

接入过程中最容易遇到的坑，就是下面这个报错（CC Switch 转发 DeepSeek 时出现）：

Codex 请求转发到服务商时失败：handling codex endpoint /responses. provider: deepseek model: deepseek-v4-flash upstream_status: http 400 cause: the `reasoning_content` in the thinking mode must be passed back to the api.

我把这个报错拆开讲。HTTP 400 意味着请求到了 DeepSeek 服务端，但服务端认为请求不合法。“reasoning_content must be passed back”说的是：DeepSeek 的推理模式下，模型返回的内容里会带一个专门的思维链字段 reasoning_content，如果你要跟它多轮对话，下一轮请求必须把上一轮返回的这个字段原样带回，否则服务端拒绝处理。

问题出在哪？Codex 的对话循环里没有专门处理这个字段；CC Switch 的本地转发层也没做补偿，它把 Codex 的请求原样转发给 DeepSeek，DeepSeek 一看缺少 reasoning_content，直接 400。这不是你配置填错了，而是推理模型的特殊要求和 Codex 的请求格式不兼容。

我的处理办法按优先级排列：

1. 如果只是想让任务跑起来，优先换掉模型或关闭服务端的 thinking 模式。DeepSeek 的普通对话模型不需要回传 reasoning_content，报错就不会出现。
2. 如果必须用推理模型，看看你用的转发工具是否有“自动保留并回传 reasoning_content”的选项，有些工具的新版本支持。
3. 如果都不想动，就切换成 6.2 里的直连方式，绕开转发层，再调整模型配置去适配。

另外，报错信息里那个deepseek-v4-flash这类模型名，记得先确认真实存在。有时候 400 就是因为随手填了一个服务端根本不认识的模型别名，和 reasoning_content 一点关系都没有。排查顺序建议先验模型名，再处理字段问题，别在错误的路上修半天。

7. 高频报错排查清单：从现象到根因

7.1 ChatGPT 账号模式下自定义模型被拒绝

现象是一启动就报：

The 'gpt-5.6-sol' model is not supported when using Codex with a ChatGPT account.

根因我在 2.3 节说过：ChatGPT 账号登录时，服务端做了模型白名单。本地配置里如果手动指定了一个自定义模型名，或某个 Skill、脚本里传了模型参数，账号模式会直接拒绝。处理办法是：确认当前登录用的是账号还是 API Key；如果走账号，把配置里的 model 字段去掉，或者改回账号支持的模型；如果非要用自定义模型，就切到 API Key 登录。排查时先看配置文件，再看命令行有没有传--model，最后看有没有通过环境变量注入模型名，三层都清干净，问题基本消失。

7.2 Unable to locate the Codex CLI binary

这个报错通常出现在 IDE 扩展或脚本调不到 codex 可执行文件的时候。现象简单，但根因不止一种：npm 安装没完成、全局 bin 目录没加入 PATH、Windows 安装包损坏等。

我的排查顺序是：先npm ls -g @openai/codex看包在不在；再用which codex看二进制路径是否在 PATH 里；Windows 下检查环境变量里的路径是否包含 npm 全局 bin。如果是 VS Code 扩展报这个错，多半是扩展找不到 CLI，重新指定 CLI 路径或重启扩展宿主就能解决。Ubuntu 下还有一种情况：用了 sudo 安装导致文件所有者混乱，建议移除后改用 nvm 重装。

7.3 Connection failed 与“一直重新连接”

“Codex connection failed: error sending request”和桌面版“正在重新连接”是同一类问题：Codex 建立不了到服务端的连接。先不要慌着重装，按下面的顺序排查。

第一步，确认你用的服务地址是不是写对了第三方端点。如果配置里基础地址填错了，请求会发到不存在的地址，返回的错误可能非常模糊。第二步，检查 API 密钥是否有效、是否过期。第三步，看看官方服务状态页，如果服务端在维护，只需要等待。第四步，如果是桌面版，考虑客户端版本过旧导致的兼容问题，手动覆盖安装新版本。最后一步才考虑网络环境本身的波动。很多“一直重新连接”其实是某一跳的网络不稳定，隔几分钟自动恢复都正常。如果持续一整天，再结合时间点和报错内容判断是配置、密钥还是服务端的问题。

7.4 配置切换工具的本地转发层直接抛出 400

这类报错的特点是：你用的是 CC Switch 之类的工具，Codex 侧看起来没配错，但启动后报错信息里带着“本地转发层”字样和上游服务商的 HTTP 状态码。本质上，这个转发层只是把 Codex 请求转给上游，自己不做业务校验，所以上游返回的错误（400、401、429）会被原样抛出来。

这时候不要盯着 Codex 的日志死磕，把注意力放到报错里的 cause 字段和 provider 字段上。cause 是上游驳回的根本原因，provider 是当前选中的服务商。第 6.3 节的 reasoning_content 报错就是这样被定位的。另外提醒一个细节：转发工具通常显示的是当前选中的配置，如果你之前切到过别的服务商，Codex 里缓存的服务地址可能还是旧的，切完配置后重启 Codex 再试。

顺带把几类典型报错归个类，方便后续快速定位：

8. 实战复盘：从一次对话到一套个人任务管理 Agent 工作流

8.1 目标拆解：任务管理到底需要哪些“对话”

前七章把基础设施讲完了，这一章我把它们拼起来。我拿“个人任务管理 Agent”来演示，因为这是很多人想要的工作流场景，也是我实际跑通过的。

先明确需求。我对个人任务管理的核心诉求是：收集碎片任务、把它们拆成可执行步骤、区分优先级、跟踪状态，每周还能产出一份周报。传统的待办软件做不到“自动拆解”，而 Codex 擅长这件事——它能读文件、能执行脚本、能按固定格式输出。

我把需求拆成三类对话：一是新增任务，告诉它“某件事要做”，它负责补全步骤和标签；二是每日待办，它读取任务文件，按优先级排序输出今天该做的事；三是周报生成，它回顾本周完成的任务，输出成果、风险、规划。如果每次都是临时起意，会非常零散，所以我要用第 4、5 章的机制把它们固化下来。

8.2 落地：AGENTS.md + Skill + 脚本的三层结构

第一层是 AGENTS.md。我在项目里定义任务文件的存放位置和格式：任务存放在tasks/目录下，每件事一个 Markdown 文件，包含标题、状态、优先级、截止日、步骤。这些规则写进 AGENTS.md 后，Codex 新增任务时自然会按这个格式写，不会自创结构。

第二层是 Skill。我建了三个：

• add-task：读入我的口语描述，拆解为步骤，生成任务文件。
• today-plan：读取所有 open 状态的任务，按优先级输出今日待办。
• weekly-report：读取本周完成的任务，按成果、风险、规划生成周报。

每个 Skill 都只有几十行 SKILL.md，但它们把“任务管理怎么做”这个流程完全标准化了。比如 add-task 里我约定：状态默认 todo，优先级按 P0/P1/P2 区分，步骤必须拆到能直接执行。

第三层是一个小脚本。任务文件的统计、排序、过期检测逻辑，用一个 Python 脚本实现，Skill 里调用它。这一步很关键：Codex 虽然是 Agent，但稳定的数据处理交给脚本更可靠。让 Codex 负责理解意图和生成内容，让脚本负责计算和落地，分工比一股脑全丢给模型更稳。

8.3 一周使用复盘：什么地方爽了，什么地方还得调

跑了一周，收获很明显：重复解释的成本消失了，任务格式、优先级规则在第一次会话就自动就位；任务不再散落在对话记录里，而是以文件形式沉淀在仓库中，随时可以 git 回滚；周报从半小时手动整理变成一句话生成。

需要坦白的是，也有翻车的地方。add-task skill 最初版本对“步骤拆解”的指令写得不够死，导致有时候拆得很细、有时候又太粗，输出不稳定。后来我在 SKILL.md 里加了一条“步骤不超过 5 条，如果无法判断就保持 3 条左右”，才收敛下来。这给了我一个很实在的体会：Skill 的表述越有约束力，输出才越稳定，不要指望模型自动勤勉。

另外一个坑是，任务量接近百条之后，today-plan 让 Codex 去读所有任务文件开始变慢。于是我把 today-plan 改成先用脚本做预排序，Codex 只读脚本输出的 Top 结果，速度明显提升。这个优化思路很有代表性：在 Agent 工作流里，不要什么都丢给模型读上下文，能用程序压缩的就先压缩。

8.4 再聊两句 Codex 与 Claude Code 的选择

实操了这套工作流之后，我对“Codex 还是 Claude Code”这个问题有了更具体的答案。单论模型代码能力，两家各有胜负，但 Codex 的配置文件体系，包括 AGENTS.md、config.toml、Skill 目录，都是纯文本，放进 git 就能跟着项目走。这对团队标准化特别友好。Claude Code 的体验也很顺，但如果你在意的是“把工作流做成仓库里的资产”，Codex 的开放程度是加分项。

我的选择逻辑是：个人小项目、看重开箱即用，可以选 Claude Code；团队多人协作、需要沉淀规范和动作模板，优先考虑 Codex。两者也可以共存，工作流的设计思路完全通用——AGENTS.md 和 Skill 的核心思想，换个工具照样成立。

最后再说一点个人体会。Codex 这类工具真正值钱的，从来不是某次对话给了一个多精彩的答案，而是你围绕它写下的 AGENTS.md、Skill、脚本和目录规范。这些东西离开 Codex 也成立，它们其实是“开发规范的可执行版本”，只是由 Agent 来消费而已。所以我的建议是：小任务直接对话，别过度设计；同一个任务第二次出现，就该考虑写成 Skill；出现第三次，你已经在享受复利了。

至于那些安装、报错、模型接入的坑，说白了都是工作流路上的石子，踢开就好。希望这篇记录能让你少走几步弯路，早点把 Codex 从“一个聪明的对话窗口”升级成“一套属于你自己的可复用开发工作流”。