chromeflow

Chromeflow

让你的 AI 编码 Agent（Claude Code 或 Codex CLI）操控真实的 Chrome——点击、填写表单、获取 API 密钥，并将其写入 .env。

安装 · 工具 · 网站 · 安全

---

问题所在：Playwright、Browser Use 和 Puppeteer 每次都会启动一个全新的空白浏览器——没有 Cookie、没有会话、无法处理双重验证。你的 AI Agent 会卡在第一个登录界面。

Chromeflow：操控你实际使用的 Chrome，你已经在其中登录了 Stripe、AWS、Supabase、Canvas、GitHub。Agent 会自动完成能处理的操作（点击、填写、上传、捕获密钥），并在需要你参与时暂停（密码、双重验证、付款）。一个 MCP 服务，提供 30 个浏览器工具，兼容 Claude Code 和 Codex CLI。

经受实战考验：正式发布前，经过了400 多小时的真实 Agent 浏览器操作打磨——各种棘手的边缘情况（React Selects、受 isTrusted 限制的表单、shadow-DOM 点击、页面 CSP fetch、静默重定向、Cookie 泄漏、0×0 隐藏元素）都已纳入错误处理方案。这不是周末黑客马拉松项目。

为什么选择 Chromeflow？

现有的浏览器自动化工具（Playwright、Browser Use、Puppeteer）会启动一个全新的空白浏览器——没有 Cookie、没有会话、没有扩展程序。每次启动后，你都会从所有网站退出登录，也无法处理双重验证。

Chromeflow 在你实际使用的 Chrome 浏览器中运行，你已经在其中登录了 Stripe、AWS、Supabase 等服务。Claude 会自动完成能处理的操作（点击按钮、填写表单、上传文件），并在需要你参与时暂停（密码、双重验证、付款信息）。

	Chromeflow	Playwright / Browser Use
浏览器	你的真实 Chrome（会话保持不变）	全新实例，所有网站均未登录
身份验证 / 双重验证	已处理——需要时暂停	无法处理——完全受阻
页面理解	DOM 查询（快速、经济、可靠）	截图 + 视觉模型（缓慢、昂贵）
人工参与	高亮显示，并在敏感输入时暂停	完全自主运行，无需交互
集成	供 Claude Code 和 Codex CLI 使用的 MCP 服务	独立运行，不了解 Agent
凭据捕获	读取 API 密钥 → 写入 .env	并非为此设计

已验证的平台 🟢

每次发布前，都会针对线上平台进行端到端测试。测试流程位于 tests/antibot/platforms/；已验证平台页面 chromeflow.run/validated 会在每次运行时根据 tests/antibot/last-run.json 自动更新。

平台	已验证内容	状态
Reddit 帖子编辑器展开	CDP 点击可展开 faceplate-* 帖子编辑器（PointerEvent 的 isPrimary=true）	🟢 正常（2026-05-25）
Reddit 评论输入	type_text 可将多段文本输入 Lexical，并保留 <p> 结构	🟢 正常（2026-05-25）
X / Twitter 推文输入框	type_text 可将 isTrusted=true 的 CDP 按键输入 Lexical	🟢 正常（2026-05-25）
LinkedIn 信息流帖子编辑器	click_element("Start a post") + type_text 可输入 Quill 编辑器	🟢 正常（2026-05-25）
Facebook 信息流帖子编辑器	点击帖子编辑器触发按钮 + type_text 可输入 Lexical 模态框	🟢 正常（2026-05-25）
Instagram React 输入框	通过支持 React 的原生值设置器使用 fill_input	🟢 正常（2026-05-25）
Radix 门户对话框	click_element(in_dialog=true) 可精准定位当前打开的对话框	🟢 正常（2026-05-25）
封闭式 shadow DOM	find_text 通过 chrome.dom API 穿透 Stencil 封闭式 shadow root	🟢 正常（2026-05-25）
TipTap / ProseMirror	type_text 可输入 contenteditable；无提示丢弃时会自动恢复	🟢 正常（2026-05-25）

提交操作交由用户完成（设计如此）。 Reddit、X、LinkedIn、Facebook 和 Instagram 都会将提交按钮与真实的 isTrusted 人类手势绑定，作为其反机器人机制的一部分。Chromeflow 会完成输入流程（这正是 Agent 实际需要的），然后使用 highlight_region + wait_for_click，由用户亲自点击 Submit。

这就是我们的护城河。 Playwright、Puppeteer、browser-use、crawl4ai 都会启动一个全新且未登录的浏览器。它们无法访问你的会话，而且这些平台对 isTrusted 的严格检查会拒绝它们原生的 CDP 点击。Chromeflow 则在你真实的已登录 Chrome 中运行，通过类人的贝塞尔曲线 + PointerEvent isPrimary=true 点击序列完成操作；上方的已验证平台表格展示了实际效果。请参阅 /validated 了解并排对比。

工作原理

Chromeflow 由两个协同工作的部分组成：

• MCP 服务 — 为你的编码 Agent（Claude Code 或 Codex）提供一组浏览器工具（open_page、click_element、fill_form、set_file_input、get_page_text、write_to_env 等）
• Chrome 扩展 — 接收这些命令并在当前标签页中执行操作（高亮、点击、填写表单、上传文件、截取屏幕截图）

Claude 负责驱动整个流程。只有在确实需要你操作时，你才需要使用浏览器，例如登录、输入密码、填写付款信息或做出个人选择。

设置

Claude Code

1. 安装插件（一次性安装，对整台机器生效）：

/plugin marketplace add https://github.com/NeoDrew/chromeflow.git
/plugin install chromeflow

在 Claude Code 中运行这些命令。插件会注册 MCP 服务、预先批准 Chromeflow 工具，并附带使用技能——无需针对每个项目进行设置。

2. 安装 Chrome 扩展程序（一次性安装）：

chromewebstore.google.com/detail/chromeflow/lkdchdgkbkodliefobkkhiegjdiidime — 点击 添加至 Chrome。

扩展程序会在 Chrome 重启后保留，只需安装一次。

3. 重启 Claude Code。

就这么简单。无论在哪个项目中，只要任务需要与浏览器交互，Claude 都会自动使用 Chromeflow。插件的 SessionStart 钩子还会在首次运行时，清理旧版基于 npx chromeflow setup 的安装遗留的过时配置。

Codex CLI

1. 安装插件（一次性安装，对整台机器生效）：

codex plugin marketplace add https://github.com/NeoDrew/chromeflow.git

然后在 Codex 中运行：

/plugins install chromeflow

插件会注册 MCP 服务，并附带 Claude Code 使用的同一套使用技能，同时针对 Codex 调整了适配方式。

2. 安装 Chrome 扩展程序（一次性安装）——使用上文相同的 Web Store 链接。该扩展程序与宿主无关，同一次安装即可同时服务于 Claude Code 和 Codex。

3. 重启 Codex。

Codex 处理浏览器任务时，会像 Claude Code 一样使用 Chromeflow。

使用方法

像平常一样向 Claude 提出请求：

“为这个项目配置 Stripe——创建一个产品，设置月付和年付价格，并将价格 ID 写入 .env”

“前往 Supabase，获取我项目的 anon key 和 service role key”

“帮我为这个应用配置 SendGrid webhook”

Claude 会进行导航、突出显示步骤、点击可操作的内容，在遇到敏感操作时暂停，并自动将值写入你的 .env。

Claude 能做什么

功能	工具
导航页面、打开新标签页	open_page、list_tabs、switch_to_tab
点击按钮和链接	click_element（重复项可使用 nth）
填写单个字段	fill_input（重复项可使用 nth）
一次调用填写多个字段	fill_form
上传文件（包括隐藏输入框）	set_file_input
以文本形式读取页面内容	get_page_text（可使用 selector 指定范围）
检查所有表单字段	get_form_fields
滚动到已知元素	scroll_to_element
为用户突出显示元素	highlight_region
等待用户点击	wait_for_click
等待异步更改	wait_for
运行任意 JS	execute_script
读取浏览器控制台输出	get_console_logs
将凭据写入 .env	get_page_text、write_to_env
截图（默认仅 Claude 可见；传入 copy_to_clipboard / save_to 以便分享）	take_screenshot
截取终端窗口	capture_terminal

文件上传

set_file_input 使用 Chrome DevTools Protocol 绕过浏览器对文件输入框脚本的限制——与 Playwright 和 Puppeteer 使用的机制相同。即使 <input type=file> 隐藏在自定义拖放区域后面，也能正常工作。

set_file_input("Upload", "/Users/you/Downloads/task.zip")

终端截图

capture_terminal 会截取终端窗口（Terminal、iTerm2、Warp、VS Code、Ghostty 等）的画面，并将其保存为 PNG。可将其与 set_file_input 搭配使用，把终端输出上传到网页表单。

专用 Claude 窗口

点击 Chromeflow 扩展程序图标，然后选择 “将此窗口用于 Claude”，即可将 Claude 的浏览器操作锁定到指定的 Chrome 窗口。这样你就能自由使用其他 Chrome 窗口，而不会受到 Claude 干扰。

并行运行多个 Agent 会话

Chromeflow 支持最多 11 个 Agent 会话（Claude Code、Codex 或混合使用）并行运行，每个会话都会自动化操作一个不同的 Chrome 窗口，互不干扰。

工作原理：

• 每个 Agent 会话都会启动自己的 Chromeflow MCP 服务，并在 7878-7888 范围内自动发现可用端口（第一个会话使用 7878，第二个使用 7879，以此类推）。
• Chrome 扩展会为每个端口维持一个 WebSocket 连接，并跟踪各端口对应的窗口分配。
• 每次浏览器工具调用都会路由到请求所用端口对应的 Chrome 窗口。

设置：

1. 按常规方式启动第一个 Agent 会话——其 Chromeflow 会占用端口 7878。
2. 在另一个终端中启动第二个 Agent 会话——其 Chromeflow 会自动回退到端口 7879。
3. 点击 Chromeflow 扩展图标。弹出窗口现在会为每个实例显示一行（端口 7878、端口 7879……），实例在线时会显示绿点。
4. 在 Chrome 窗口 A 中打开弹出窗口，然后点击端口 7878 旁的 “Use this window”。
5. 切换到窗口 B，打开弹出窗口，然后点击端口 7879 旁的 “Use this window”。

完成。现在每个会话都会操作自己的 Chrome 窗口——你可以在一个窗口中运行研究任务，同时让另一个会话在另一个窗口中填写 Stripe 控制面板，完全不会冲突。

单实例用法保持不变，并且完全向后兼容——首次加载时会自动迁移旧的窗口分配设置。

添加到其他项目

无需操作——上面的插件安装是对整台机器生效的。打开任何项目，Chromeflow 就已就绪。

升级

在 Claude Code 中：

/plugin update chromeflow
/reload-plugins

在 Codex 中：

/plugins update chromeflow

之后重启宿主，以加载插件附带的新 MCP 服务二进制文件。

从旧的 npx chromeflow setup 流程迁移

如果你之前通过 npx chromeflow setup 安装了 Chromeflow，无需进行任何操作——安装插件（上面的设置步骤 1），插件首次启动 SessionStart 时会清理以下内容：

• ~/.claude.json 中过时的 mcpServers.chromeflow 条目
• ~/.claude/CLAUDE.md 中残留的 ## Chromeflow 部分

项目级的 CLAUDE.md 文件和 .claude/settings.local.json 白名单不会受到影响——其中可能包含你想保留的内容，因此插件不会改动它们。你可以在方便时手动从每个项目的 CLAUDE.md 中删除 # Chromeflow — Claude Instructions 部分（插件的技能现在包含相同内容），也可以保留它。

开发

git clone https://github.com/NeoDrew/chromeflow
cd chromeflow
npm install
packages/plugin/scripts/build-server.sh   # bundle the MCP server into the plugin

MCP 服务的源代码位于 packages/mcp-server/src/，并通过 esbuild 打包到 packages/plugin/server/chromeflow.mjs 中——这是插件直接附带的单文件 ESM 二进制文件。

通过让插件指向此代码库，在本地进行迭代。在 Claude Code 中：

/plugin marketplace add /absolute/path/to/this/repo
/plugin install chromeflow

在 Codex 中：

codex plugin marketplace add /absolute/path/to/this/repo
/plugins install chromeflow

编辑 MCP 服务源代码后，请重新构建打包文件，然后执行 /reload-plugins（Claude Code）或重启宿主（Codex）以加载更新。

Chrome 扩展位于 packages/extension/：

npm run dev:ext   # watches extension

重新构建扩展后，请从 chrome://extensions 重新加载。

要求

• Claude Code 或 Codex CLI
• Chrome（或任何 Chromium 浏览器）
• Node.js 22+