【Codex with ChatGPT 源码学习②】694 行 SKILL.md：Markdown 怎么指挥 Codex 干活？

【Codex with ChatGPT 源码学习②】694 行 SKILL.md：Markdown 怎么指挥 Codex 干活？

系列说明：本文是对社区开源项目 XiaoDuoYa/codex-with-chatgpt 的技术解读，非 OpenAI 官方教程、非该项目维护者发布的文档。研究基于 2026-10-22 可访问的main分支；分支内容会变化，建议阅读时核对具体 commit。
证据标记：[源码]表示能从对应源文件确认；[文档]是项目约定；[推断]为技术分析；[建议]为改进方案，不能误当作已经实现的能力。文中命令和请求示例若未专门注明，均为教学示例，并非实际执行结果。

推荐 CSDN 标签：CodexAgent SkillMarkdownAI Agent工作流源码精读Agent 编排状态机Codex 执行机制

摘要：解读 Skill 元数据、触发、Golden Rules、CLI、浏览器规则和恢复步骤，解释“模型解释规程”与“程序强制规则”的区别。

本章以仓库main分支当前公开的skill/SKILL.md为依据，结合docs/protocol.md和docs/architecture.md分析。

本章最重要的问题：一个 Markdown 文件，为什么能让 Codex 操作浏览器、启动服务、维护任务状态、调用 ChatGPT 并反复修改代码？

答案是：SKILL.md并不直接执行这些操作，它是交给 Codex Agent 解释的一套操作规程。真正的操作由 Codex 已经具备的工具、C2C CLI 和 Node.js Bridge 完成。

一、先建立 Skill 的完整心智模型

这有点类似传统软件中的：

但这个类比有一个重要边界：Codex 并不是确定性的脚本解释器。它通过模型理解和执行指令，可能出现理解偏差、工具失败或者执行步骤遗漏。

因此，Skill 的约束属于 Agent 行为约束，而文件系统沙箱、OAuth、权限检查等才属于软件层面的强制边界。

二、SKILL.md的实际结构

源码仓库的main分支版本约有 694 行。为了便于研究，可以按职责分成以下部分。

其中有五部分尤其值得深入：Skill 触发、浏览器调用、CLI、状态机、任务执行。

三、第一部分：Skill 是如何触发的？

3.1 YAML Frontmatter

文件开头的真实定义是：

--- name: codex-with-chatgpt description: > Use ChatGPT (web) as the planning and review brain for Codex coding sessions, while Codex keeps full execution ownership. Use when the user says "使用 Codex with ChatGPT ..." / "Set up Codex with ChatGPT" / "用 ChatGPT 规划", when they ask to connect ChatGPT to the current workspace, disconnect it, or run a task through the ChatGPT planning loop. ---

这是整个 Skill 的入口。

name是 Skill 标识；description是帮助 Agent 判断何时应该使用该 Skill 的文字描述。

这里有一个重点：它不是传统意义上的关键词触发器。

例如，传统软件可能采用：

if "使用 Codex with ChatGPT" in user_message: run_c2c()

但 Skill 的工作方式不是这么简单。

Codex 会根据当前可用 Skill 的描述、用户任务和上下文判断是否采用这个 Skill。用户也可以显式指定使用它。

3.2 三种常见触发方式

注意：这里说的是 Skill 作者定义的预期行为，不是对每个 Codex 版本都能成功触发的保证。

3.3 Skill 安装的位置

源码给出了两项关键路径：

<codex-home>/ └── skills/ └── codex-with-chatgpt/ └── SKILL.md

Codex Home 的解析规则为：

如果设置了 CODEX_HOME： 使用 CODEX_HOME 否则： Linux/macOS: ~/.codex Windows: %USERPROFILE%\.codex

项目安装时还会把源码中的<ACTUAL_CHECKOUT_PATH>替换成实际的仓库路径。

因此必须区分：

• Skill 安装目录：供 Codex 发现和读取。
• C2C 源码目录：保存 TypeScript、CLI 和 Bridge 实现。
• 用户 Workspace：Codex 真正要开发的工程。

这三个目录可以完全不同。

四、第二部分：Golden Rules 是什么？

源码第 19–96 行定义了几条核心规则。

它们不是业务逻辑本身，而是整个协作系统的行为约束。

其中最重要的是以下几类。

4.1 Codex 保留执行权

源码明确规定 Codex 负责：

• 编辑代码
• Shell 命令
• Git 操作
• 测试
• 错误恢复

ChatGPT 负责高层规划、代码理解、审查和调试策略。

这意味着 ChatGPT 返回的是计划，Codex 再将计划转化为实际工具调用。

4.2 不通过聊天消息传输源码

Skill 要求不把文件正文、Diff 和日志粘贴进 ChatGPT 对话，而是让 ChatGPT 通过 MCP 自主查询。

目的有三个：

1. 控制消息更短。
2. 避免重复传输大量相同内容。
3. ChatGPT 能按需读取最新版本的文件，而不是只依赖某一次聊天里的旧副本。

需要强调：文件内容仍然会经由 MCP 发送给 ChatGPT，并不是始终留在本地。

4.3 浏览器认证限制

规则要求不能直接操作 OAuth Token、Cookie 或 Session Storage，浏览器中自动输入的凭证只限于项目定义的配对码。

这是一种降低凭据暴露风险的设计，但不是绝对的安全保证。

4.4 浏览器类型限制

这是仓库比较特殊的地方。

它明确指定control-in-app-browser，要求使用 Codex 的iab浏览器能力，不允许把普通外部 Chrome、Edge 或 Safari 当成默认执行环境，也要求避免截图坐标点击式 Computer Use。

所以不能简单地说：

这个项目就是用 Playwright 操作 Chrome。

更准确地说，它使用 Codex 内置浏览器的控制 API，底层某些操作可能使用 Playwright 风格的 DOM 能力。

4.5 Doctor Gate

启动正式协作前，需要确保本地 Bridge、MCP、隧道及连接状态满足条件。

逻辑上类似：

检查环境 │ ├── 正常 → 允许 ChatGPT 协作 │ └── 异常 → 修复或中止

这是一个非常值得借鉴的设计：把运行环境是否就绪变成执行任务的前置条件。

但源码中的“静默修复”和自动更新也意味着存在自动修改本地配置的行为。对正式工程，建议增加人工确认及版本固定机制。

五、第三部分：Codex 如何真正操作 ChatGPT 浏览器？

这是整个 Skill 中最容易被误解、也最有技术研究价值的部分。

5.1 不是 Skill 自己打开浏览器

源码第 97–105 行规定，Codex 应调用内置浏览器能力。

核心 API 形态是：

// 以下是从 SKILL.md 摘出的关键调用 setupBrowserRuntime(); const iab = await agent.browsers.get("iab");

iab是 in-app browser 的标识。

从软件架构角度可以理解为：

SKILL.md │ ▼ 指导 Codex Codex Agent │ ▼ 调用浏览器工具 Browser Runtime │ ▼ 浏览器交互 ChatGPT Web UI

Skill 只告诉 Codex 应调用什么接口；实际浏览器能力由运行环境提供。

需要注意，SKILL.md的这些 API 不能单独复制到普通 Node.js 程序中运行。它们依赖相应的 Codex 浏览器运行时。

5.2 浏览器 Tab 的生命周期

Skill 规定了一个很有意思的设计：整个 Codex Session 尽量复用同一个 ChatGPT 标签页。

关键操作包括：

// 概念性片段：仅保留核心 APIconsttab=awaitiab.tabs.new();awaittab.goto("https://chatgpt.com/");awaittab.markHandoff();awaittab.markDeliverable();

其中：

最后两种标记不是标准浏览器 Web API，而是特定浏览器运行环境的能力。

5.3 Codex 如何发送和接收消息？

SKILL.md没有定义一个普通的 HTTP ChatGPT API 调用，而是要求 Codex 使用浏览器页面的交互能力。

概念上，发送消息可分为四步：

1. 找到 ChatGPT 输入区域 2. 输入 C2C 协议消息 3. 提交消息 4. 检查页面是否出现相应回复

源码还要求：

• 尽量使用 DOM 检查而不是持续截图。
• 每次发送后保持同一浏览器标签页。
• 如果页面仍在生成回复，不要重复发送。
• 浏览器超时不等于 ChatGPT 没有收到消息。
• 识别STATE: PLAN、STATE: DONE或STATE: BLOCKED后再继续。

这些约束的目标是避免重复执行任务。

不过它们仍然属于基于网页 UI 的交互机制，不能获得官方模型 API 那样明确的请求 ID、响应结构和交付语义。

这也是该项目的一项主要架构弱点。

六、第四部分：c2cCLI 在系统中承担什么？

理解了 Skill 和浏览器之后，就要研究另一半：传统软件程序。

源码指定的命令入口为：

node"<checkout>/bin/c2c.js"<command>

或者安装了全局命令后：

c2c<command>

SKILL.md并不自己创建 MCP 服务器，而是让 Codex 执行 CLI 命令，进而调用项目的 TypeScript/Node.js 实现。

6.1 主要 CLI 分工

例如，假设 Codex 正在开发的项目位于：

E:\Projects\demo

它可以执行：

c2c doctor-w E:\Projects\demo--json c2c session-w E:\Projects\demo--json

其中-w指的是被开发的 Workspace，而不是 C2C 工具自己的仓库目录。

• -json的作用是让 Codex 更容易读取机器可解析的状态。

6.2 第一次连接如何建立？

根据SKILL.md的 Setup 工作流，过程大致如下：

1. 检查 Node.js、cloudflared和 C2C 构建产物
2. 初始化本地 Bridge 和对应 Workspace
3. 配置公网隧道，得到 MCP Server URL
4. 在 ChatGPT 创建对应的 MCP 连接
5. 通过 OAuth 和临时配对码完成授权
6. 在 ChatGPT 中调用workspace_info验证正确的 Workspace
7. 保存连接和会话记录，进入 Ready 状态

这里必须区分两种授权：

ChatGPT 网页登录：用户用自己的 ChatGPT 账户登录，以使用 ChatGPT 服务。

MCP OAuth 授权：ChatGPT 作为客户端，获得访问本地 C2C Bridge 的权限。

两者不是同一套认证机制，也不应共享密码或 Token。

源码还规定首次配置可以选择自动或手动引导，并且一个 Workspace 只绑定一个特定的连接。

七、第五部分：真正的核心——任务状态机

前面的组件负责“能不能连接”，状态机负责“连接后怎么工作”。

源码的 Coding Task 工作流位于第 469–591 行，是整个 Skill 最值得仔细学习的部分。

7.1 状态机不是一个一直运行的 JavaScript 循环

例如，项目并没有简单地定义：

while(true){constplan=awaitaskChatGPT();awaitexecute(plan);}

相反，状态转换由 Codex Agent 按 Skill 执行，配合浏览器消息和本地 Session Checkpoint 记录。

状态流是：

再看每个状态由谁产生：

这里的DONE是 ChatGPT 根据检查结果给出的协议结论，并非数学意义上的代码正确性证明。

7.2 状态机还分两个层次

这个设计比看上去复杂一点。

第一层：跨 Agent 通信状态

通过 ChatGPT 对话中的[C2C]消息传递。

第二层：Codex 本地 Checkpoint

记录当前已经执行到哪一步，例如：

• PLAN_RECEIVED
• EXECUTING
• EXECUTED_LOCAL
• EXECUTED_SENT

为什么要这么做？

假设 Codex 已经执行了数据库迁移，但在准备向 ChatGPT 发送EXECUTED时崩溃了。

重新启动后，系统不能直接重新执行数据库迁移，否则可能造成重复操作。

如果 Checkpoint 显示EXECUTED_LOCAL，则应继续发送执行结果，而不是重新执行刚才的任务。

这类似分布式任务系统中的持久化检查点机制，但其实际可靠性仍取决于状态写入的时机、原子性和外部操作的幂等性。

八、第六部分：用一个真实开发任务完整模拟

我们用 Python 工程的“增加 CSV 导出功能”来模拟一次完整任务。

假设当前目录：

demo-project/ ├── src/ │ ├── report.py │ └── data.py ├── tests/ │ └── test_report.py ├── README.md └── pyproject.toml

以下是教学模拟消息，不是已经实际运行的记录。

第一步：Codex 发起 INIT

用户输入：

使用 Codex with ChatGPT，为当前项目增加 CSV 导出功能。

Codex 通过 Skill 匹配 Coding Task 工作流，先检查 Bridge，再在 ChatGPT 浏览器中发送：

[C2C] STATE: INIT TASK_ID: c2c_a123 ITERATION: 0 GOAL: 为报表模块增加 CSV 导出功能。 INSTRUCTION: 通过 MCP 分析当前工程， 生成下一轮可执行开发计划。

注意消息中没有源码。

第二步：ChatGPT 读取项目

ChatGPT 收到请求后，理论上可以按需调用这些 MCP 工具：

workspace_info ↓ list_directory("src") ↓ read_file("src/report.py") ↓ read_file("tests/test_report.py") ↓ git_status

这些调用由 ChatGPT 工具系统发往 MCP Bridge，而不是由 Codex 复制文件内容。

第三步：ChatGPT 返回 PLAN

[C2C] STATE: PLAN TASK_ID: c2c_a123 ITERATION: 1 GOAL: 实现 CSV 报表导出。 RATIONALE: 当前模块已有数据查询能力， 可以在现有报表接口上扩展。 ACTIONS: 1. 在 report.py 增加 CSV 导出函数。 2. 使用标准 csv 模块进行编码。 3. 添加空数据、特殊字符测试。 FILES_LIKELY_INVOLVED: src/report.py tests/test_report.py TESTS: pytest tests/test_report.py SUCCESS_CRITERIA: CSV 内容正确，原功能不回归。

收到 PLAN 后，Codex 更新本地 Checkpoint：

c2c session set -w E:\Projects\demo-project ` --protocol-state PLAN_RECEIVED ` --waiting-for none ` --next-step "execute PLAN"

这一步的意义是：即使 Codex 进程随后重启，也知道当前已经取得计划。

第四步：Codex 执行计划

Codex 进入EXECUTING，使用自己的编辑和终端工具修改文件。

例如生成：

importcsvimportiodefexport_csv(rows):output=io.StringIO()writer=csv.writer(output)writer.writerows(rows)returnoutput.getvalue()

接着运行：

python-m pytest tests/test_report.py-q

假设测试结果为：

8 passed

注意 ChatGPT 并没有直接执行这些动作。

第五步：Codex 记录结果

源码要求通过c2c record写入执行记录：

c2c record-w E:\Projects\demo-project `--task c2c_a123 `--iteration 1 `--changed-files"src/report.py,tests/test_report.py"`--tests"8 passed"`--exit-statusok

若同时保存测试输出，还可以指定--command、--output-file和--exit-code。

Bridge 将执行记录提供给 ChatGPT，但会按照本地安全规则限制日志内容。

随后 Codex 更新状态为EXECUTED_LOCAL，并通过浏览器向 ChatGPT 发送简短消息：

[C2C] STATE: EXECUTED TASK_ID: c2c_a123 ITERATION: 1 RESULT: Execution finished. CHANGED_FILES: 2 TESTS: 8 passed Please review the current git diff and execution records through MCP.

第六步：ChatGPT 独立审查

ChatGPT 使用 MCP 读取：

git_diff test_status execution_summary execution_output

假设审查发现 CSV 导出没有正确处理 UTF-8 BOM，而用户的需求明确要求兼容某些 Excel 导入场景。

ChatGPT 不应该直接返回DONE，而应给出下一轮PLAN，说明为什么需要修改、修改哪里以及如何验证。

Codex 随后执行第二轮。

最终审查通过，ChatGPT 返回：

[C2C] STATE: DONE TASK_ID: c2c_a123 ITERATION: 2 SUMMARY: CSV 导出功能已实现， 相关测试和审查已完成。

Codex 清理当前任务 Checkpoint，并向用户汇报。

九、第七部分：断线恢复是如何实现的？

这部分体现了项目作者对长时间 Agent 工作流的考虑。

假设 Codex 在任务执行过程中退出，再次启动时：

c2c session-w E:\Projects\demo-project--json

可能读取到类似这样的概念性状态：

{"taskId":"c2c_a123","iteration":2,"protocolState":"EXECUTED_SENT","waitingFor":"GPT_REVIEW"}

这里展示的是便于理解的字段示例，并非声称完整 CLI 响应恰好具有这一 JSON 结构。

Codex 根据状态做不同处理：

还有一个专门的HANDOFF协议。

当原来的 ChatGPT 会话丢失或需要切换时，Codex 可以创建新会话并发送简短的任务交接说明。新的 ChatGPT 会话再通过 MCP 查询当前代码，不需要将整个旧对话复制过来。

但是这里还缺少一个严格保证

考虑一个更极端的问题：

Codex 已经在 ChatGPT 网页按下发送按钮，但还未来得及写入EXECUTED_SENT，程序就崩溃了。

重新启动时，Checkpoint 和网页的真实状态可能不一致。

这就是经典的分布式系统难题：消息交付和状态持久化之间存在失败窗口。

要达到强可靠性，通常还需要：

• 唯一消息 ID 和幂等处理；
• 明确的消息接收确认；
• 状态持久化与外部副作用的恢复策略；
• 防止重复执行非幂等命令。

C2C 的 Task ID、Iteration 和 Checkpoint 提供了部分基础，但不应将其理解为已经实现严格的 exactly-once 执行语义。

十、第八部分：从软件架构角度重新理解 Skill

现在可以回答一个更深入的问题：

为什么作者选择写一个 694 行左右的 Skill，而不是全部使用 TypeScript 编写一个工作流程序？

因为作者希望利用 Codex 已经具备的 Agent 能力。

传统程序需要明确规定每一步的控制逻辑：

plan=request_plan()files=parse_files(plan)modify_files(files)result=run_tests()review=request_review(result)

而使用 Skill，可以让 Codex 理解高层指令，自主选择如何修改文件、调用哪些测试命令以及如何处理普通工程错误。

两种架构各有优劣：

因此，可以把这个项目看作一种Agent 驱动编排 + 传统服务支撑的混合架构。

对于普通开发任务，这种模式很灵活；对于需要严格冻结、可重复验证和审计追踪的工程，则需要把关键状态转换、验证门禁和权限判定尽可能落实到程序代码。

十一、三个值得特别关注的源码设计

第一，自动更新机制。SKILL.md要求在工作流入口检查更新，发现新版本后执行git pull、安装依赖、构建并重新安装 Skill。这很方便，但对要求版本固定的工程来说存在供应链及可重复性风险。

第二，ChatGPT Project 与 Workspace 映射。 新工程默认采用一个 Workspace 对应一个 ChatGPT Project 和一个 MCP 连接，而新的 Codex 对话可以在同一个 Project 内创建新的 ChatGPT 会话。这有助于任务隔离和上下文管理，却仍需要严格校验连接是否指向正确的 Workspace。

第三，不向用户展示内部技术细节。 Golden Rules 要求 Codex 尽量不向最终用户展示 MCP、OAuth、端口等内部信息。这有利于简化普通用户体验，但不适合直接照搬到开发、调试和安全审计模式。工程人员应能查看连接目标、权限变更、执行日志和失败原因。

这些都属于 Skill 作者设计的行为规则，而不是 Codex 平台本身的强制规定。

十三、Markdown 怎么指挥 Codex 干活？

13.1. 先看文件定位

[源码]skill/SKILL.md在核对时约 694 行，开头采用 YAML frontmatter：

---name:codex-with-chatgptdescription:>Use ChatGPT (web) as the planning and review brain for Codex coding sessions...---

这里name提供技能标识，description帮助 Codex 根据任务判断是否使用。它不是简单的if 关键词 in 用户输入脚本；用户也可以明确指定 Skill。

13.2. Skill 的作用和局限

Skill 是操作规程，而不是独立 HTTP 进程、插件二进制或模型权重。它可规定“执行c2c doctor”，但执行命令依赖 Codex 的 Shell 权限；规定“不要泄露秘密”也不能替代真实的文件权限控制。

13.3. Golden Rules 的工程含义

[文档] Skill 要求：源码和日志通过 MCP 按需读，不复制进浏览器消息；Codex 保留编辑、Shell、Git、测试权；ChatGPT 负责规划审查；通过内置浏览器iab操作页面；异常先检查本地服务，必要时进入人工配置；不同 Workspace 使用独立连接。

这些规则体现出模型决策层与软件执行层的分工。它们是对 Codex 的行为要求，并不构成 OS 级强制沙箱。

13.4. CLI 为什么重要？

[文档] 常用命令包括：

c2c doctor--json c2c session-w E:\demo--json c2c record-w E:\demo--task c2c_f81a--iteration 1 `--changed-files"src/report.py"--tests"8 passed"--exit-statusok

c2c doctor用于检查连接和环境；
c2c session查询本地会话；
c2c record将执行结果写入可由 MCP 读取的记录。
具体命令选项以当前版本 CLI 帮助为准，上面路径只是示例。

13.5. 为什么 Skill 要区分会话与任务？

同一个 Browser Tab、ChatGPT Conversation、Workspace 和 Codex Task 不是同一对象。

[文档] Skill 定义long-chat与project两种会话复用模式；每个工作区应有明确的 ChatGPT 连接。Task ID 用于标识一次任务；Iteration 标识其中某轮；Checkpoint 则用于断点恢复。这些内容在第六篇深入拆解。

13.6. 自动修复与自动更新的两面性

遇到故障时，Skill 希望 Codex 执行检查和修复；部分入口还涉及版本更新。它可以降低新手配置成本，但[建议]正式环境锁定源码 commit、依赖版本和 Skill 版本，升级经过审查后再执行。

13.7. 最小思考练习

问：SKILL.md中写着“必须读取 Git Diff 才能给出 DONE”，能否保证执行？

答：不能单靠文本保证。需要独立 Verifier 检查是否真的读取并审查了目标 Diff，且测试与交付规则真正满足要求。

十四. 小结

Skill 的核心价值是将复杂 Agent 协作规程封装成可加载的文本。下一篇将拆解它依赖的iab浏览器控制运行时。

源码阅读：SKILL.md

版权与引用：本文为独立整理与分析，引用项目名称、接口名称和少量必要代码片段以解释技术原理；原项目的代码许可证为 MIT。本文不代表原作者或 OpenAI 的立场。转载请保留原项目地址及本文出处。

系列导航：参见同一系列的「导读」及其他章节。
ChatGPT 负责思考，Codex 负责干活？从源码读懂 Codex with ChatGPT（系列导读）

【Codex with ChatGPT 源码学习①】整体架构：为什么要分离控制平面与数据平面？
【Codex with ChatGPT 源码学习②】694 行 SKILL.md：Markdown 怎么指挥 Codex 干活？
【Codex with ChatGPT 源码学习③】iab、DOM、Playwright：Codex 如何操作 ChatGPT 网页？