【Codex with ChatGPT 源码学习③】iab、DOM、Playwright：Codex 如何操作 ChatGPT 网页？

【Codex with ChatGPT 源码学习③】iab、DOM、Playwright：Codex 如何操作 ChatGPT 网页？

系列说明：本文是对社区开源项目 XiaoDuoYa/codex-with-chatgpt 的技术解读，非 OpenAI 官方教程、非该项目维护者发布的文档。研究基于 2026-10-22 可访问的 main 分支；分支内容会变化，建议阅读时核对具体 commit。
证据分级：[源码/文档] 表示能够在原仓库指定文件中核对的实现描述或行为约定；[公开接口] 表示宿主 Browser Runtime 的接口形态，不等于 C2C 自身的实现源码；[分析] 是技术推导；[建议] 是独立的改造设计。文章末尾提供证据入口及复现步骤。

推荐标签：Codex ChatGPT Browser Automation Playwright DOM Agent MCP

摘要：浏览器自动化最难的问题并非“能否点击发送按钮”，而是怎样证明消息已提交、回答已完整、协议来自正确轮次，以及失败后不重复执行。本文从开源项目 codex-with-chatgpt 的 skill/SKILL.md、docs/protocol.md 和 docs/architecture.md 出发，解构内置浏览器 iab 与 Playwright 风格接口、ChatGPT 对话复用、MCP 的独立数据通道以及 Checkpoint 恢复语义。

---

本文涉及自动化网页的部分只进行授权范围内的技术原理研究。OpenAI 的 Terms of Use 对自动化或程序化提取 Output 有明确限制，下面的可运行实验只操作本地模拟页面，不自动访问 ChatGPT。

一、先说结论：浏览器不是模型，而是通信界面

[项目约定] 这个项目的协作链路可以概括为：Codex 在本地执行工程任务，通过内置浏览器操作已登录的 ChatGPT 网页；ChatGPT 生成规划与审查意见，并可借助独立 MCP 连接读取授权的工程数据。

它并非将 ChatGPT 模型部署到本地，也不是由 C2C 自己实现了一条与 ChatGPT 模型直连的 RPC 通道。项目把结构化的 [C2C] 消息叠加在原有网页对话上。其架构文档将前者称为 Control Plane，将经由 Bridge 的 MCP 读取称为 Data Plane。原仓库架构文档

图 1：概念架构图，不是仓库内部模块调用栈。图中 ChatGPT Web ↔ Cloud Model 代表服务层逻辑，不能据此推断网络协议或直接函数调用关系；MCP 是授权的数据链路，不意味着模型可以读取整台机器。

这里有两个容易混淆的“通道”：

通道	核心功能	主要数据	由谁驱动
Browser / Control Plane	打开会话、提交 [C2C]、读取回复	控制消息、计划、审查结论	Codex 操作 ChatGPT Web
MCP / Data Plane	按授权读取本地工程状态	文件内容、目录、Git 变更等	ChatGPT 发起 MCP 工具调用，Bridge 校验后返回

[分析] 这种分离能减少 Codex 在聊天输入框内反复粘贴完整代码的需求，但浏览器交互成功不等于 MCP 已连接；MCP 能读取文件也不等于浏览器消息已成功发送。两条链路必须分别监测。

二、Browser Runtime 到底是什么？

2.1 两个核心调用的职责

[项目约定] 开源仓库的 skill/SKILL.md 在 In-app browser (ChatGPT) 小节规定了以下接口形式：

// 示意：必须运行于已暴露 Browser Runtime 的 Codex 环境
setupBrowserRuntime();
const iab = await agent.browsers.get("iab");

• setupBrowserRuntime()：初始化或连接 Codex 提供的浏览器控制运行时。
• agent.browsers.get("iab")：取得名为 iab 的 in-app browser 后端句柄。
• agent.browsers：浏览器环境提供的接口，不是标准 JavaScript 或 Node.js 内置对象。

[项目约定] 项目 Skill 还规定：同一 Codex Session 应尽量只初始化一次并复用 iab，不要未经约定切换到独立浏览器。

2.2 浏览器客户端与内置浏览器之间的关系

[公开接口] 另一种公开使用记录中的形态如下：

// 示例中的路径是占位符，不能原样运行
const { setupBrowserRuntime } = await import(
  "<browser-plugin-root>/scripts/browser-client.mjs"
);

await setupBrowserRuntime({ globals: globalThis });
const iab = await agent.browsers.get("iab");
const tabs = await iab.tabs.list();

这体现出至少几个逻辑层次：

组件	角色	应注意的边界
browser-client.mjs	浏览器客户端入口（公开用例中的路径形态）	路径与版本有关
setupBrowserRuntime	初始化控制环境	不是 ChatGPT 模型启动函数
agent.browsers	浏览器后端访问接口	不属于通用 Node.js API
iab	内置浏览器后端	取决于宿主的工具可用性
iab.tabs	标签页管理能力	Tab 不等于服务器端 Conversation
tab.playwright	Playwright 风格的 DOM 操作能力	不必然等于完整 Playwright API

[分析] Browser Plugin 内部很可能需要把 Agent 的控制请求转交给页面执行上下文，但仅凭这些 Skill/API 示例，无法确定它具体使用何种 IPC、浏览器内核、CDP 连接方式或者进程布局。不能把合理推测写成实现细节。

2.3 它和独立 Playwright Chromium 完全相同吗？

不相同。普通 Playwright 的典型形式是自行管理浏览器：

// 普通 Playwright 示例：适用于独立测试脚本
import { chromium } from "playwright";
const browser = await chromium.launch();
const page = await browser.newPage();

而项目的浏览器控制逻辑更接近：

// Codex Browser Runtime 示意，非普通 Node.js 可运行代码
const iab = await agent.browsers.get("iab");
const tab = await iab.tabs.new();
await tab.goto("https://chatgpt.com/");

两者可以呈现类似的 DOM 操作接口，但不能据此推断共享 Cookie、登录状态、浏览器进程、扩展、Profile 或执行权限。

三、DOM、Playwright 与 Computer Use：究竟控制了什么？

DOM（Document Object Model）是页面的对象树。浏览器可通过角色、属性、结构和可见状态定位元素。使用 DOM 自动化，通常不必先把整个窗口截图再计算点击坐标。

方式	输入信息	典型动作	特点与限制
DOM 定位	HTML/可访问性信息	读文本、填输入框、点击按钮	精确，但依赖页面结构
Playwright 风格接口	Locator、DOM 状态	fill、click、快照等	自动化方便；具体 API 取决于宿主
dom_cua	宿主提供的可见 DOM 交互能力	检查可见结构与控制元素	公开使用记录有此类能力，不保证每版一致
截图 + 坐标	像素图像	点击坐标、拖动	对布局、缩放、遮挡敏感
官方模型 API	请求/响应消息	结构化请求、获取模型输出	不依赖网页 DOM，适合正式系统集成

[项目约定] 项目 Skill 规定：这个项目要求优先采用 iab 的页面/DOM 操作，不把截图坐标点击或外部 Chrome 作为默认方案。这是项目行为约束，而不是“所有截图操作都被平台禁止”。

例如，一个教学测试页面包含：

<div id="chat">
  <div class="message assistant">这是规划结果</div>
  <textarea aria-label="Message"></textarea>
  <button aria-label="Send">发送</button>
</div>

对应的教学伪代码可能是：

// 仅用于解释 DOM 操作顺序；不是 ChatGPT 当前页面的稳定选择器
const editor = tab.playwright.getByRole("textbox", { name: "Message" });
await editor.fill(controlMessage);
await tab.playwright.getByRole("button", { name: "Send" }).click();

[分析] DOM 的优势在于可基于语义定位、提取文字和检查交互状态；但现代单页应用还可能包含 React 状态更新、异步渲染、虚拟列表和动态控件。页面 DOM 不是稳定的公共 API，选择器一旦依赖具体 CSS 类名或临时层级，就可能随前端升级失效。

注意：公开接口示例中的 tab.playwright.evaluate(...)、tab.dom_cua.get_visible_dom()、tab.screenshot(...) 属于公开使用记录涉及的接口形态；它们是否在当前机器上可用，必须由实际运行环境确认。

四、一个 Tab 为什么要反复使用？

[项目约定] 项目 Skill 对 Session 的要求是：同一 Codex Session 尽量只创建一个 ChatGPT Tab，优先复用，任务等待或超时时不要随意销毁。

Skill 中列有以下标签页相关 API（展示关系，不构成完整可运行脚本）：

const tab = await iab.tabs.new();
await tab.goto("https://chatgpt.com/");
await (await iab.capabilities.get("visibility")).set(true);
await tab.markHandoff();
await tab.markDeliverable();

markHandoff() / markDeliverable() 表示向运行时声明页面的交接或交付用途；仅凭方法名无法证明它能让浏览器永远存活。这里还有一个容易遗漏的规则：新对话需要确认是 Chat 模式而不是 Work 模式，并通过 workspace_info 证实连接到了目标 Workspace 后才保存新的 Chat URL。Skill 原文

4.1 三层状态不是一回事

层次	保存的是什么	丢失后的影响
Tab	当前浏览器标签页与页面对象	需要重新定位/打开页面
Conversation	ChatGPT 端的对话及其 URL	可能需要打开原 URL 或发起 HANDOFF
Checkpoint	Codex 任务处于哪个阶段、下一步等什么	可能重复发送、执行或审查

一个 Tab 可以导航到多条 Conversation；Conversation 可能仍在服务端，但 Tab 已关闭。保存了 Tab 也不表示上一次消息已被最终确认。

4.2 long-chat 与 project

[项目约定] 根据项目 Skill，项目通过 c2c session --json 的 conversation.mode 区分两种模式：

• long-chat：一个 Workspace 对应长期复用的 ChatGPT 对话。
• project：一个 Workspace 对应 ChatGPT Project；新的 Codex 对话可以在 Project 内建立新的对话。

这类设计让“工程上下文复用”和“单条聊天记录复用”成为两个不同策略。无论采用哪种模式，不要根据 Tab 是否存在来臆测应该新建哪个 Conversation。

五、发送消息：从本地协议到网页 UI

[项目约定] 在 C2C 协议中，Codex 可通过网页向 ChatGPT 发送带有 Task ID 与 Iteration 的控制消息，例如：

[C2C]
STATE: INIT
TASK_ID: c2c_f81a
ITERATION: 0

GOAL:
实现 CSV 导出功能。

INSTRUCTION:
Inspect the connected workspace through the
Codex with ChatGPT MCP connector.
Produce a C2C PLAN message.

其中 c2c_f81a 和 CSV 需求是教学示例。其核心不是聊天内容的自然语言，而是可以用来关联任务的结构化标记。

图 2：发送与接收控制消息的逻辑状态流程。图中的校验与持久化顺序是对项目交互机制的分析，不代表存在同名源码函数或已实现完整事务机制。

一个关键工程原则：发送命令返回，并不自动等于远端已接收；页面出现用户消息，也不等于 ChatGPT 已完成 PLAN。 必须区分提交、可见、生成、完成、校验这几步。

5.1 三套状态不能混用：协议、Checkpoint、页面观测

这是本文最关键的一组概念，直接来自 docs/protocol.md：

状态层	示例	状态由谁维护	解决的问题
跨 Agent 协议	STATE: INIT / PLAN / EXECUTED / DONE / BLOCKED / HANDOFF	由消息发送方生成，经双方约定解释	任务交换的业务语义
Codex 本地 Checkpoint	PLAN_RECEIVED、EXECUTED_LOCAL、EXECUTED_SENT、waitingFor=GPT_REVIEW	c2c session 的本地记录	崩溃后恢复到哪个动作
浏览器页面观测	输入框就绪、已见用户消息、生成中、回复完整	浏览器适配层动态观察	此刻页面展示了什么

例如，PLAN_RECEIVED 不是发给 ChatGPT 的 STATE: PLAN_RECEIVED；页面“用户消息可见”也不是 STATE: EXECUTED。原协议还明确指出：不存在 STATE: RESUME，任务重启应从本地 Checkpoint 判断下一步，必要时通过 HANDOFF 移交。

图 3：教学版状态桥接图。仓库规定先观察 INIT 已可见再记录等待状态；上图只是展示“跨域切换”的概念，并不表示浏览器与本地文件能组成原子事务。

5.2 PLAN 的轮次要按规范理解

[源码/文档] 原协议样例中 INIT 的 ITERATION 为 0，随后 PLAN 样例为 1。浏览器读取端不能因为“上一条可见的消息也叫 PLAN”，就忽略轮次匹配。一次正确的消费必须把当前任务标识 + 期望协议状态 + 期望轮次 + 完整性一起验证，而非只对 STATE: PLAN 做字符串包含判断。

六、读取回复：为什么比发送更难？

ChatGPT 的回答是异步的。一次请求中可能先生成部分文本，再发起 MCP 工具调用，随后继续生成。只观察“页面多了一段文字”，容易把不完整的 PLAN 误当最终回复。

图 4：INIT → PLAN → 本地执行的简化时序。实际 MCP 连接可能经过 Tunnel、授权和 HTTP 端点；上图为可读性省略中间节点。

6.1 用浏览器观测状态代替“等固定秒数”

[建议] 可以用下列浏览器局部状态做诊断：

状态	含义	可以直接执行下一步吗？
READY	页面可交互	仍需检查是否重复提交
SUBMITTED	当前消息已在会话中可见	不可以，仅证明局部提交迹象
GENERATING	模型生成中或工具运行中	不可以
RESPONSE_VISIBLE	目标回复文本已出现	还需完整性校验
VALIDATED	ID、轮次、字段与结束状态满足预期	才可进入协议消费阶段

这些是页面观测状态，不是项目正式 C2C STATE 枚举，只是建议的浏览器交互诊断状态。

6.2 校验一条 PLAN 应关注什么？

[建议] 至少检查：

1. 它是当前会话最新的 Assistant 回复，而非上一轮回答或用户回显。
2. TASK_ID 与等待中的任务相同。
3. ITERATION 与预期轮次吻合，不能把旧轮次结果当成当前结果。
4. STATE: PLAN 是当前阶段允许的状态。
5. 必需字段存在；例如协议示例中的 ACTIONS、TESTS、SUCCESS_CRITERIA。
6. 回复已停止生成，文本不是中途截断的半段协议。

[分析] “DOM 中看到了文本”只是观测事实；“可安全驱动下一轮工程操作”是协议判断。把两者等同，可能导致错误补丁、重复测试或跨任务串扰。

七、超时为什么不等于失败：分布式系统视角

设想 Codex 点击发送后，浏览器调用超过了允许时间。可能出现三种情形：请求尚未提交、已提交但尚未展示、已提交且正在生成。单靠超时本身无法区分。

因此 “超时 → 立即重发”是不安全的，它可能制造两个 INIT、两次审查甚至两轮冲突的 PLAN。

[源码/文档] Skill 的 In-app browser §8 要求短时 DOM 检查、复用原 Tab、不把浏览器等待超时视为远端失败；Coding task 要求优先读取 Checkpoint，不因超时而重发 INIT/EXECUTED。

[建议] 进一步完善时，应该考虑：

• 为每条控制消息增加稳定的 MESSAGE_ID（建议字段，不等于项目现有协议）。
• 记录“准备发送 / 已观察到发送 / 等待响应 / 已校验”的状态及证据。
• 在发送结果未知时先对账，而不是自动重试。
• 对已消费的 (TASK_ID, ITERATION, STATE) 实施去重。
• 允许 UNKNOWN_OUTCOME 分支，必要时人工确认。

重要限制：网页 UI 通常无法提供原子性的“本地写 Checkpoint + 远端收消息”事务。即使引入本地日志，也不能凭空得到严格的 exactly-once 保证；系统应使用可重放检查、幂等处理和人工兜底降低风险。

7.1 用“不确定结果”替代过度自信的布尔值

所谓 exactly-once 并不是“用户只点了一次发送”。这里至少有四个独立事件：① 浏览器接受点击；② 页面出现用户消息；③ 服务端收到请求；④ Codex 只消费一次正确的 PLAN。它们没有跨系统的单一原子提交点。

例如：click() 成功但页面脚本崩溃，可能看不到回显；反过来，看到了回显也不能证明服务端已经成功处理。最安全的 API 返回值不应只有 success: true/false，而应显式保留 unknown。

观察	可以断言	不能断言	下一步
输入框已写入内容	DOM 已填入消息	请求已发送	观察提交按钮和本地记录
用户消息在页面可见	页面呈现已提交迹象	服务端最终处理成功	等待正确轮次的助手响应
出现部分 PLAN 文本	有输出可读	回答已经结束	继续等待 / 检查完成信号
浏览器操作超时	这次等待没有按期返回	请求未执行	重新检查原 Tab 和 Checkpoint
完整 PLAN 校验通过	内容满足本地消费前置条件	业务方案必然正确	交给独立执行和审查流程

八、Checkpoint、会话恢复和 HANDOFF

假设 Codex 已发出本轮 EXECUTED，正在等待 ChatGPT Review，浏览器却发生超时。

以下以任务阶段举例：

EXECUTED_SENT
waitingFor = GPT_REVIEW

这意味着恢复时的重点是找回已经开始的审查流程，而不是重新执行 INIT，也不是无条件重新修改源码。

图 5：恢复策略示意，旨在区分“会话丢失”和“任务阶段丢失”。

[项目约定] 如果原 ChatGPT 对话不可用，项目采用 HANDOFF 消息交接任务上下文（详见 docs/protocol.md：HANDOFF）。教学形式：

[C2C]
STATE: HANDOFF
TASK_ID: c2c_f81a
ITERATION: 2

GOAL:
实现 CSV 导出。

PROGRESS:
功能已实现，测试已运行。

NEXT_EXPECTED_STEP:
通过 MCP 审查最近修改。

新对话不应仅凭交接摘要假定工程无变化，而应重新核对授权 Workspace 的真实文件、Git 差异与测试证据。[分析] HANDOFF 使恢复不完全依赖聊天历史，但摘要可能遗漏重要背景，因此它更像“恢复入口”，不是完整状态快照。

常见故障对照表

故障	首先检查	不应直接做什么
浏览器等待超时	原 Tab、原 Conversation、Checkpoint	直接重发 INIT
ChatGPT 页面显示 Retry	页面当前状态、是否已有回复	假定任务从未启动
会话 URL 不可达	URL、登录态、可用交接信息	任意创建新会话并丢弃进度
MCP 401	MCP 认证/连接状态	当成 DOM 选择器故障
Tunnel 地址变化	工作区连接的端点配置	只清除浏览器 Cookie
识别到旧 PLAN	Task ID、Iteration、消息先后关系	直接执行过期动作

九、浏览器、MCP 与本地 Codex 的边界

[项目约定] 在该开源项目的架构中，当 ChatGPT 需要读取本地源码时，并不是 Codex 自动把所有文件塞进聊天输入框。MCP 数据链路可抽象为：

图 6：MCP 数据访问逻辑。项目文档介绍了 Cloudflare Tunnel，但具体部署和网络路径取决于项目配置；不能把示意图理解成任何环境都自动完成了认证或隔离。

能力边界必须区分：浏览器可读 ChatGPT 页面 ≠ 浏览器可任意读本地磁盘；ChatGPT 可调用 MCP ≠ 可以绕过 MCP 权限；Codex 可编辑文件 ≠ ChatGPT 已经批准每一次更改。

十、Browser Runtime 的可用性与版本风险

[公开接口] 开源仓库及相关公开讨论表明：公开使用记录中有 control-in-app-browser、Browser Plugin 以及 DOM 类接口，也有安装、工具暴露、Windows 环境或运行时兼容性的讨论。这些记录不足以证明每个 Codex CLI / Desktop 安装都支持相同 API。

建议用“能力探测”而非“版本名称猜测”来判断：

检查点	成功标准
Browser Runtime 是否提供	宿主工具明确可见并获授权
iab 能否获取	能获取当前版本所支持的浏览器后端
Tab 列表与导航是否可用	能在测试环境列出/访问目标页面
DOM 能否读取	能从独立测试页取得预期文本
定位和输入是否可用	能在授权测试页完成一次交互
会话是否可恢复	关闭/重连后能按已有状态恢复
失败是否可区分	页面错误、登录问题、MCP 401 不被混成同一类

对生产系统而言，还需要为网页结构变化、运行时升级及第三方服务策略变更留出回归测试成本。

十一、合规与安全：理解原理不等于授权自动化使用

浏览器控制技术本身并不代表可以绕过服务限制。[外部规则] OpenAI 目前公开的 Terms of Use 对自动化或程序化提取服务输出存在限制。因此，不能把“技术上可以通过 DOM 读写 ChatGPT 页面”解释成“可以无条件把网页会话用作模型 API”。

工程设计还应注意：

• 仅操作用户有权限访问、服务规则允许自动化的页面。
• 避免把浏览器 Cookie、会话 Token 或 MCP 授权凭证写入日志。
• MCP Bridge 使用最小权限、明确 Workspace 边界和路径检查。
• 网页正文与模型生成内容都可能含有非可信指令，应避免被用于提升权限或执行未经批准的命令。
• 涉及正式产品集成时，优先核对当前适用条款与官方 API 规则。

十二、常见误区汇总

常见误区	更准确的理解
“Codex 在本地运行 ChatGPT 模型”	它操作云端 ChatGPT Web，推理仍在云端
“iab 就是 Playwright Chromium”	有相似的操作接口，不代表共享进程或会话
“Tab 打开说明历史任务完整”	Tab、Conversation 与 Checkpoint 是不同状态
“能看到文字就说明回答完成”	流式输出中必须判断结束及协议完整性
“发送超时说明没发送成功”	请求结果可能不确定，首先要核对现状
“MCP 是 Codex 往网页复制文件”	MCP 是受权限控制的独立工程数据通道
“Skill 写了 API 就说明任何机器都能用”	需要对应宿主提供工具，版本及权限都可能影响
“HANDOFF 可以替代代码核查”	HANDOFF 是上下文交接，工程事实仍需重新读取

十三、总结：真正值得学习的是边界与恢复语义

理解本章的五个关键点：

1. setupBrowserRuntime() 和 iab 用来访问 Codex 宿主提供的浏览器控制能力，并不启动本地 ChatGPT。
2. DOM / Playwright 风格接口处理的是 网页交互，不是自动取得本地文件访问权限。
3. Browser 控制通道与 MCP 数据通道相互独立，任务协议负责把二者组织起来。
4. Tab + Conversation URL + Checkpoint 能帮助恢复上下文，但不天然提供 exactly-once 事务保证。
5. 高可靠系统需要明确区分“提交已观察到”“回复已完成”“协议已校验”，并为“不确定结果”设计恢复流程。

在下一章中，我们将进入 MCP Bridge，讨论 ChatGPT 的工程数据请求怎样进入本地服务，如何完成身份认证、Workspace 授权和路径安全检查，以及一次读取操作的调用时序。

---

参考资料与源码入口

1. 社区项目：XiaoDuoYa/codex-with-chatgpt
2. 项目 Skill：skill/SKILL.md
3. C2C 协议：docs/protocol.md
4. 项目架构文档：docs/architecture.md
5. Codex 公开仓库：openai/codex（用于进一步核查 Browser Plugin 能力与版本兼容性）
6. 服务规则：OpenAI Terms of Use

---

源码阅读：Skill 浏览器章节 · 架构文档

---

版权与引用：本文为独立整理与分析，引用项目名称、接口名称和少量必要代码片段以解释技术原理；原项目的代码许可证为 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 网页？
【Codex with ChatGPT 源码学习④】深入 MCP Bridge：从 HTTP 请求到安全读取源码的完整链路
【Codex with ChatGPT 源码学习⑤】深入 OAuth 2.1、PKCE 与 Cloudflare Tunnel：ChatGPT 如何安全连接本地 MCP？
【Codex with ChatGPT 源码学习⑥】多 Agent 任务状态机深度解析：Task ID、Checkpoint、执行证据与崩溃恢复
【Codex with ChatGPT 源码学习⑦】安全与可靠性审计：OAuth、MCP、Prompt Injection 与崩溃恢复