Chrome Relay：让 Claude Code、Codex、Cursor 等编码智能体在真实 Chrome 后台标签页中操作

网站： https://agent-chrome-relay.aindeev.com

让你的编码代理（Claude Code、Codex、Cursor、Paseo）从命令行使用你日常的 Chrome，带着你真实的登录状态，在后台标签页中运行：不会抢占焦点，没有对话框，每条命令约 0.15 秒。

agent-browser --cdp "$(chrome-relay url you@company.com)" open https://app.example.com/
agent-browser snapshot -i          # the page's buttons, links and fields, each with a ref like @e5
agent-browser click @e5
agent-browser close

这是选择性加入的：不会替你安装扩展，而且它只在由机主自行设置的 Mac 上运行。

工作原理

agent-browser (CLI) ──ws──▶ relay (127.0.0.1:9333, LaunchAgent) ──ws──▶ Chrome Relay extension ──chrome.debugger──▶ agent tab

扩展（extension/，MV3，每个加载它的 Chrome 配置文件各一个）：在折叠的“Agents”标签组中以非活动方式打开每个代理标签页，并通过 chrome.debugger 在其中运行 DevTools 命令。不使用远程调试端口，因此 Chrome 永远不会显示“允许远程调试？”。当代理工作时，Chrome 会显示“Chrome Relay 已开始调试此浏览器”。
中继（relay/relay.mjs）：每个代理一个 DevTools 端点。每个代理只能看到并控制它自己打开的标签页；可能唤起或聚焦浏览器的命令会被吞掉。
CLI（bin/chrome-relay）：设置、连接 URL、诊断、审计追踪。

设置（每台 Mac 一次，约 2 分钟）

最快的方式：把这段提示词粘贴到 Claude Code、Codex 或 Cursor 中，让你的代理来完成。手动方式：

需要 macOS、Google Chrome、Node.js 20+ 和 agent-browser（npm i -g agent-browser）。

git clone https://github.com/aindeev/agent-chrome-relay
cd agent-chrome-relay
bin/chrome-relay setup     # secret, background service, identities, `chrome-relay` on PATH, Claude Code skill

然后，在每个代理应使用的 Chrome 配置文件中：打开 chrome://extensions，开启开发者模式，加载已解压的扩展程序，并选择你克隆仓库的 extension 文件夹。用 chrome-relay doctor 检查。

执行 git pull 后：chrome-relay update（重启中继，在每个配置文件中重新加载扩展）。要移除：chrome-relay uninstall，然后在每个配置文件中移除该扩展。

告知你的代理

Claude Code：setup 会把该技能（skill/SKILL.md）链接到 ~/.claude/skills/chrome-relay，因此每个仓库都能获得它。Codex、Cursor 及其他：让它们指向同一个文件，例如在你的全局 ~/.codex/AGENTS.md 中加一行：“对于任何需要我的登录状态的浏览器步骤，请遵循 <path>/agent-chrome-relay/skill/SKILL.md。” 仓库的 CLAUDE.md/AGENTS.md 只需一行指向该技能的说明。

谁可以驱动它

对每个代理连接进行两项检查：

本机的密钥：在设置时生成于 ~/.chrome-relay/token（权限模式 600），并嵌入到 chrome-relay url 打印的 URL 中。
允许的代理应用：发起连接的进程必须来自 Claude Code、Codex、Cursor 或 Paseo。中继会查找该进程（lsof、ps），检查这些应用在其子进程中设置的标记（CLAUDECODE、CODEX_*、CURSOR_*、PASEO_AGENT_ID），然后检查其父进程。

携带浏览器 Origin 标头（网页）的连接即使有密钥也会被拒绝。只有此检出目录的扩展可以作为扩展连接：Chrome 根据文件夹推导出已解压扩展的 ID，setup 将该 ID 记录在 ~/.chrome-relay/config.json 中，中继检查连接的 Origin: chrome-extension://<id>（网页无法伪造），并且发起连接的进程必须是 Chrome。

这可以将其他本地工具、网页和意外情况挡在外面。它并不是针对已以你的身份运行的恶意软件的边界，因为恶意软件可以读取密钥并伪造标记。

代理从不输入凭据。当网站通过 Google 跳转且正确的账号已登录时，扩展会自行点击该账号和继续/允许（页面脚本，因此即使页面上有 1Password 的框架也能工作）。密码、通行密钥、两步验证界面或未登录的账号会中止该跳转，代理会收到 SIGN-IN NEEDED: ... 并请你在自己的窗口中登录。

网站使用哪个 Google 账号来自 ~/.chrome-relay/identities.json（chrome-relay identities）：你的 Chrome 配置文件（由设置填充）、可选的手动设置 sites.rules，以及 sites.learned，后者由中继在每次成功跳转后填充。默认：配置文件自身的账号。

审计追踪

每个 agent 操作都记录在 ~/.chrome-relay/audit/YYYY-MM-DD.jsonl 中；用 chrome-relay audit 读取：谁连接了（应用、Claude/Paseo 会话 id、工作文件夹、AGENT_BROWSER_SESSION）、页面、带位置的点击、特殊按键、agent 自己的脚本、截图、上传、弹窗、登录点击和被拦截的页面。输入的文本仅以字符数形式存储，URL 会去掉查询字符串。

值得了解的行为

弹窗和 target=_blank 链接会作为同一 agent 拥有的新隐藏标签页打开；弹窗登录流程若 postMessage 回打开者并自行关闭，则仍可正常工作。消息来源是 relay 在每个标签页加载时看到的来源（绝不是页面自称的来源），并且 targetOrigin 会被强制执行。一个安全网会接管 agent 页面无论如何打开的任何标签页，并将焦点交还给你原本所在的标签页。
1Password：当页面包含另一个扩展的 frame（登录表单上的 1Password 菜单）时，Chrome 会移除该扩展的调试器。agent 的命令会等待该扩展重新附加。
自动清理：静默 30 分钟的 agent 标签页会被关闭。当 relay 重启时，扩展会关闭它打开的 agent 标签页（按标签页 id 追踪，因此你自己的标签页组绝不会被触碰）。
后台标签页中的真实输入：每个 agent 标签页都开启了焦点模拟，因此点击和输入都能生效。

开发

cd relay && npm install && npm test     # who may connect: secret, allowed apps, Chrome-only extension, audit

日志：chrome-relay logs（~/.chrome-relay/relay.log）。测试扩展更改：编辑 extension/，然后 chrome-relay update。CHROME_RELAY_HOME 和 CHROME_RELAY_PORT 覆盖数据文件夹和端口。

关于作者

由 Alexey Indeev 制作，他是 Spare 的联合创始人兼 CTO。我在 The Leveraged Mind 上撰写关于用 AI 做更多事情的文章，无论你是否编程。

博客：https://read.aindeev.com
X：@AlexeyIndeev
LinkedIn：https://www.linkedin.com/in/alexey-indeev/
GitHub：@aindeev

问题、想法或 bug：提交一个 issue 或在 X 上联系。

许可证

MIT。参见 LICENSE。