跳到主要内容
AI教程

使用 Chrome Relay 让编程代理控制已登录的 Chrome

了解如何在 macOS 上安装 Chrome Relay，将受支持的编程代理连接到日常使用的 Chrome 配置文件，使用 agent-browser 自动化已登录的网站，管理登录信息和身份，检查审计记录，以及排查或更新中继程序。

AI我搜编辑部阅读约 10 分钟
使用 Chrome Relay 让编程代理控制已登录的 Chrome

什么是 Chrome Relay？

Chrome Relay 让受支持的编码代理通过命令行使用你日常使用的 Google Chrome 配置文件。代理可以访问你已登录的网站，同时在不活跃的后台标签页中工作，因此自动化操作不会抢占你当前窗口的焦点。

Chrome Relay 项目概览

该项目支持 Claude Code、Codex、Cursor 和 Paseo。它通过 agent-browser 将它们的浏览器命令连接到 Chrome。命令通常可在约 0.15 秒内完成，并且 Chrome 无需远程调试端口。

Chrome Relay 需要用户主动选择启用。它不会自动安装扩展程序，并且只会在所有者完成设置的 Mac 上运行。

Chrome Relay 的工作原理

agent-browser CLI → 本地中继 → Chrome Relay 扩展程序 → 代理标签页

该系统包含三个主要组件：

  • Chrome 扩展程序：这是一个未打包的 Manifest V3 扩展程序，需要分别加载到你希望代理使用的每个 Chrome 配置文件中。它会在不活跃且折叠的 Agents 标签组中打开代理标签页，并通过 chrome.debugger 发送 DevTools 命令。
  • 本地中继：这是一个监听 127.0.0.1:9333 的 LaunchAgent。它为每个代理提供独立的 DevTools 端点，并限制代理只能访问由其打开的标签页。
  • 命令行工具：chrome-relay 命令负责设置、连接 URL、身份、更新、诊断、日志和审计记录。

中继会抑制可能唤起或聚焦 Chrome 的命令。代理工作期间，Chrome 仍可能显示 Chrome Relay started debugging this browser 消息。

要求

安装前，请确保你具备以下条件：

  • macOS
  • Google Chrome
  • Node.js 20 或更高版本
  • 已全局安装 agent-browser

使用 npm 安装 agent-browser：

npm i -g agent-browser

安装 Chrome Relay

1. 克隆并配置项目

git clone https://github.com/aindeev/agent-chrome-relay
cd agent-chrome-relay
bin/chrome-relay setup

setup 命令会创建本地密钥、配置后台服务、记录身份、将 chrome-relay 添加到 PATH，并为 Claude Code 链接 Chrome Relay 技能。

2. 将扩展程序加载到 Chrome

在每个代理应能使用的 Chrome 配置文件中重复以下步骤：

  1. 打开 chrome://extensions。
  2. 启用开发者模式。
  3. 选择加载已解压的扩展程序。
  4. 选择仓库中的 extension 文件夹。

由于每个 Chrome 配置文件都会加载自己的扩展程序副本，因此你只能开放明确选择的配置文件。

3. 验证安装

chrome-relay doctor

在让代理开始浏览之前，使用诊断输出确认中继和扩展程序已正确配置。

告诉你的编码代理有关 Chrome Relay 的信息

Claude Code

设置过程会将 skill/SKILL.md 链接到 ~/.claude/skills/chrome-relay。这样，该技能就能在各个仓库中使用。当需要提供明确指令时，仓库级别的 CLAUDE.md 只需包含一行指向该技能的说明。

Codex、Cursor 和其他受支持的代理

将代理的全局指令指向同一个技能文件。例如，将类似下面的指令添加到 ~/.codex/AGENTS.md：

对于任何需要使用我的登录信息的浏览器步骤，请遵循 /path/to/agent-chrome-relay/skill/SKILL.md。

将示例路径替换为你克隆的仓库的绝对路径。

运行首次浏览器自动化

首先向 Chrome Relay 请求经过身份验证的连接 URL，然后将该 URL 传递给 agent-browser：

agent-browser --cdp "$(chrome-relay url you@company.com)" open https://app.example.com/
agent-browser snapshot -i
agent-browser click @e5
agent-browser close

将 you@company.com 替换为相关的已配置身份，并将示例网站替换为你希望自动化操作的页面。

  1. chrome-relay url 会输出一个包含此 Mac 密钥的连接 URL。
  2. agent-browser open 会创建一个由代理拥有的不活跃标签页，并打开请求的页面。
  3. snapshot -i 会列出链接、按钮和字段等交互控件。每个控件都会获得类似 @e5 的引用。
  4. click @e5 会在后台标签页中使用真实输入模拟激活所引用的元素。
  5. close 会结束浏览器会话。

了解登录行为

代理不会输入你的凭据。如果网站通过 Google 重定向，并且正确的账号已登录，扩展程序可以选择该账号并点击继续或允许。这使用页面脚本，即使 1Password 已在页面上放置框架，也可能正常运行。

如果流程进入密码、通行密钥、两步验证或已退出账号页面，自动化就会停止。代理会收到 SIGN-IN NEEDED 消息，并应请求你在自己的窗口中完成登录。

管理配置文件和网站身份

身份配置存储在 ~/.chrome-relay/identities.json 中。使用以下命令查看或管理：

chrome-relay identities

配置包括设置期间发现的 Chrome 配置文件、可选的手动配置 sites.rules，以及成功完成登录跳转后记录的 sites.learned 条目。默认情况下，网站使用所选 Chrome 配置文件所属的账户。

安全模型

每个代理连接都必须通过两项检查：

  1. 本地密钥：设置程序会在 ~/.chrome-relay/token 生成一个文件权限为 600 的令牌。chrome-relay url 输出的 URL 中会嵌入该令牌。
  2. 允许的代理应用：连接进程必须与 Claude Code、Codex、Cursor 或 Paseo 相关联。中继会检查进程，以及这些应用在子进程中设置的标记。

即使连接包含密钥，只要带有浏览器的 Origin 标头，也会被拒绝。扩展程序还会通过其基于 Chrome 生成的扩展 ID、其 chrome-extension:// 来源，以及连接进程必须是 Chrome 这一要求进行检查。

这些控制措施可阻止无关的本地工具、网页和意外连接进入系统。它们无法防范已经以你的用户身份运行的恶意软件，因为此类软件可能读取密钥并伪造进程标记。

查看审计记录

Chrome Relay 会将代理活动记录在 ~/.chrome-relay/audit/YYYY-MM-DD.jsonl 下按日保存的 JSON Lines 文件中。使用以下命令读取记录：

chrome-relay audit

审计记录包括连接详情、工作文件夹、会话标识符、访问过的页面、点击位置、特殊键、代理脚本、屏幕截图、上传、弹窗、登录点击和被阻止的页面。为保护隐私，输入的文本仅以字符数表示，并会移除 URL 查询字符串。

高级行为与提示

弹窗和新标签页

使用 target=_blank 的链接和弹窗会作为由同一代理拥有的隐藏标签页打开。弹窗身份验证流程仍可向打开它的页面发送消息，并自行关闭。中继会强制检查观测到的消息来源和 targetOrigin，而不是信任页面的声明。

1Password 页面

当页面包含其他扩展的框架时，例如登录表单上的 1Password 菜单，Chrome 可能会分离扩展调试器。Chrome Relay 会等待并重新连接调试器，然后继续执行代理命令。

自动清理

代理标签页在闲置 30 分钟后会关闭。中继重启时，扩展程序也会关闭之前由它打开的标签页。清理依据是标签页 ID，因此不会修改你自己的标签组。

后台输入

代理标签页会继续启用焦点模拟。这样，即使标签页处于非活动状态，点击和输入仍可发送到该标签页，同时你当前的 Chrome 标签页保持不变。

更新、诊断和移除 Chrome Relay

拉取仓库更改后，重启中继，并在每个已配置的配置文件中重新加载扩展程序：

git pull
chrome-relay update

使用以下命令查看中继日志：

chrome-relay logs

日志文件存储在 ~/.chrome-relay/relay.log。要卸载本地服务和命令行设置，请运行：

chrome-relay uninstall

然后从每个 Chrome 配置文件中手动移除已解压的扩展程序。

开发与测试

要安装中继依赖并运行测试套件：

cd relay && npm install && npm test

测试涵盖连接授权，包括密钥、允许的应用、仅限 Chrome 的扩展连接，以及审计行为。编辑 extension/ 下的文件后，使用以下命令重新加载扩展程序：

chrome-relay update

对于自定义环境，CHROME_RELAY_HOME 可覆盖数据目录，CHROME_RELAY_PORT 可覆盖中继端口。

结语

Chrome Relay 让受支持的编码代理能够受控地访问现有 Chrome 会话，无需远程调试端口，也不会接管当前活动窗口。配置好本地中继和已解压的扩展程序后，你可以使用 agent-browser 自动执行需要身份验证的浏览器任务，按配置文件或网站选择身份，查看注重隐私的详细审计记录，并依靠自动清理机制处理被遗弃的会话。

如需查看源代码、更新信息和报告问题，请访问 Chrome Relay GitHub 仓库。本项目采用 MIT 许可证。