codex-browser-fix

Codex 浏览器修复

仅适用于 Codex。桌面应用内置了一个 Chrome 插件，可通过 ChatGPT 扩展驱动任何 Chromium 浏览器。有两种情况会导致它无法正常工作，而供应商的技能都未涵盖：

症状	原因	修复方法
发现扩展后出现 Codex auth token is unavailable	config.toml 设置了自定义 model_provider；浏览器助手会启动 codex app-server 并继承该设置，因此无法识别 ChatGPT 登录状态	预检会安装一个启动器，仅对该子进程覆盖 provider
昨天还能找到扩展，今天却找不到或报错	桌面应用已更新；~/.codex/plugins/cache/openai-bundled/chrome 仍指向旧版插件包	预检会将缓存和信任哈希重新同步到已安装的应用
用户要求使用 Chrome 或 Edge 以外的 Chromium 浏览器（Brave、Vivaldi、Opera），但 Agent 选择了 Chrome	供应商的技能只列出 chrome 和 edge；其他系列需要通过 list() 匹配	按 family 选择（见下文）

已安装的 Chrome 插件自带技能（应用程序包内的 skills/control-chrome/SKILL.md）仍是浏览器 API 的权威说明。本技能负责本地设置、恢复和浏览器系列选择。

何时应用

• 用户为需要访问其标签页或登录状态的任务指定 Brave、Vivaldi、Opera、Edge、Chrome 或“我的浏览器”
• Chrome 插件报错 Codex auth token is unavailable
• 浏览器发现过程未找到扩展连接，或在 ChatGPT 或 Codex 桌面应用更新后立即失败
• “检查浏览器设置”／“修复浏览器连接”

工作流

1. 预检插件

在导入 browser-client.mjs 或选择浏览器之前运行。需要 Bun 以及 ChatGPT 或 Codex 桌面应用。<skill-dir> 是已安装的技能文件夹（Codex 默认路径：~/.codex/skills/codex-browser-fix）。

bun "<skill-dir>/scripts/browser-plugin-preflight.mts"          # sync + verify
bun "<skill-dir>/scripts/browser-plugin-preflight.mts" --check  # read-only verify

usage: browser-plugin-preflight.mts [--check] [--plugin-dir <dir>]
  --check             verify only, nothing written; exit 1 on drift
  --plugin-dir <dir>  the bundled Chrome plugin directory of a non-standard install
the codex home is $CODEX_HOME or ~/.codex
exits: 0 synchronized, or verified current; 1 a missing file or a stale setting; 2 usage

它会打印应用程序包版本、导入 browser-client.mjs 的插件路径，以及已同步的缓存。每次桌面应用更新或重启后都要重新运行。

如果失败，会指出缺少的文件或过期的设置，并以状态码 1 退出。即使使用 --check，缺少 config.toml、应用程序包或可执行文件也属于错误，绝不会视为通过。

它只会更改以下内容，不会改动其他内容（<home> 是 codex 主目录）：

• <home>/plugins/cache/openai-bundled/chrome：所有现有的固定版本条目、当前版本条目和 latest 链接都会指向已安装的应用程序包。<home>/plugins/cache/openai-bundled/browser：仅同步当前版本的配套副本及其 latest 链接。被替换的过期副本会移至 <home>/plugin-rollbacks/。
• <home>/config.toml，在 [mcp_servers.node_repl.env] 下：CODEX_CLI_PATH、应用版本和受信任的代码路径。在 [shell_environment_policy.set] 下：browser-client.mjs 的哈希。每个值都必须已在相应位置赋值。编辑后会进行解析验证，确保没有更改其他内容。
• <home>/scripts/browser-codex：生成的启动器。只有其 app-server 子命令会获得 -c 'model_provider="openai"'。其他所有子命令都保持原样传递。主 provider、CODEX_HOME 和凭据均不受影响。
• 每个 <home>/hosts/<host>/：各自的 plugins/cache/openai-bundled/browser 配套缓存；如果其中包含 config.toml，还会应用相同的配置修改，并生成各自的 scripts/browser-codex。Chrome 缓存仅为全局缓存。

2. 按供应商方式引导

通过其 node_repl JavaScript 工具，按照已安装的 control-chrome 技能操作。从预检打印的路径导入 browser-client.mjs，调用一次 setupBrowserRuntime()，并在后续轮次中复用 agent 和浏览器绑定。切勿为了重复设置而重置可正常工作的会话。

3. 选择浏览器系列

Chrome 和 Edge 有专属选择器：agent.browsers.get("chrome") 和 agent.browsers.get("edge")。其他所有 Chromium 系列浏览器都从以下列表中匹配：

// Declared once per session; call it again with a profile name after asking.
async function selectExtension(family, profileName) {
  const label = (c) => c.profileName ?? c.name; // the name shown when asking
  const candidates = (await agent.browsers.list()).filter(
    (c) =>
      c.type === "extension" &&
      c.family === family &&
      (profileName === undefined || label(c) === profileName),
  );
  if (candidates.length === 0) throw new Error(`No connected ${family} extension`);
  if (candidates.length > 1) {
    const profiles = candidates.map(label).join(", ");
    throw new Error(`Several ${family} profiles connected (${profiles}); ask which one`);
  }
  return agent.browsers.get(candidates[0].id);
}
let browser = await selectExtension("<family>", undefined); // the family the user asked for; ("<family>", "Work") once the profile is known
nodeRepl.write(await browser.documentation());

• 没有候选项：用用户的措辞说明该浏览器不可用（扩展缺失或已断开连接）。有多个候选项：询问用户要使用哪个配置文件，然后用该名称再次调用 selectExtension，并重新赋值给 browser。切勿猜测。
• 系列名称遵循插件的 scripts/extension-ids.json：brave、chrome、edge、opera、vivaldi。
• 用户明确指定的浏览器是硬性约束。切勿因为插件名为 Chrome 就改用 Google Chrome，也不要回退到 Computer Use 或新开浏览器。
• 选择后，按供应商技能的要求读取完整的 documentation() 输出，为会话命名，然后从 browser.user.openTabs() 中认领与任务匹配的确切标签页对象。
• 标签页失效或已关闭时，从现有浏览器绑定新建标签页。只有在明确断开连接或用户要求切换时才重新选择浏览器。

4. 执行并交接

• 操作前检查页面。每次有实质意义的操作后都重新检查状态。点击或上传完成不代表结果已保存：报告成功前，先在页面上核实字段、媒体内容和保存状态。
• 上传照片或文档前，先阅读供应商的上传说明。
• 按供应商的交接规则保留标签页。切勿清除浏览器存储，因为其中保存着本地草稿和登录状态。
• 连接设置不会授权其他操作。应用、消息、购买和发布仍须遵循当前请求和项目审批规则。

故障恢复

• 如果出现 Codex auth token is unavailable、发现结果为空、缓存或信任失败：运行预检，然后阅读故障恢复。
• 完成正常引导后，发现或选择仍失败：await agent.documentation.get("bootstrap-troubleshooting")。
• 扩展安装或通信失败：await agent.documentation.get("chrome-troubleshooting")。
• 正在运行的浏览器辅助程序会沿用其启动时的环境。新的启动器设置要等该辅助程序下次启动时才会生效。不要为了应用新设置而终止正常工作的连接。

切勿：关闭再重新开启主 model_provider、复制令牌、修补应用二进制文件，或凭猜测重新安装组件。若确实需要登录，应将其作为用户需要采取的操作报告。

没有桌面插件时的备用方案

预检 --check 可在任何装有 Bun 的终端中运行，无需 MCP 主机，并会报告缺少哪个捆绑包、缓存或设置。适用时，可在本地准备任务材料。

只有在装有 Chrome 插件且连接了用户所要求浏览器的桌面 Codex 会话中，才能继续实时浏览器操作。切勿改用其他浏览器或自动化传输方式。

参考资料

• references/recovery.md：身份验证故障示例、预检同步的内容，以及扩展与标签页故障的区分
• scripts/browser-plugin-preflight.mts：唯一的设置实现（同步和 --check）
• scripts/browser-auth-launcher.mts：启动器生成器，已在上游通过单元测试（https://github.com/Vivswan/skills，tests/skills/codex-browser-fix/browser-auth-launcher.test.ts）
• scripts/codex-config-toml.mts：config.toml 编辑操作，已在上游通过单元测试（https://github.com/Vivswan/skills，tests/skills/codex-browser-fix/codex-config-toml.test.ts）