连接方式 / Connecting

当任务需要用户此刻正看着的那个窗口——他们真实的、已登录的 会话，而不是一个全新的空白浏览器时，走扩展连接（extension connect）。它接管用户真实的 Chrome： 零确认、零 token、无 headless 痕迹，是所有连接方式里反检测等级最高的一档。

连接链路只有四站：chrome-use CLI → 每会话一个的守护进程 → Chrome 为扩展拉起的中继（relay） → 浏览器里的 ab-connect 扩展。扩展用 Chrome 自带的调试协议驱动页面，所以不必开远程调试端口。 每一站说什么协议、状态放在谁手上，见 它怎么工作。

一次性安装

扩展连接只需配置一次。先注册原生消息宿主（native-messaging host），再装上 chrome-use 扩展。

# 1. 注册原生消息宿主
$ chrome-use extension install

2. 安装 chrome-use 扩展。 最省事、且重启后依然稳定的方式是从 Chrome Web Store 一键 Add to Chrome：

• 商店地址：chromewebstore.google.com/detail/chrome-use

自动连接：open 即接管

装好扩展后，普通的 chrome-use open <url> 会自动通过扩展 relay 连接。 auto_connect_cdp 优先选用 live relay，而不是裸的 --remote-debugging-port，所以 Chrome 136+ 那个「是否允许远程调试？」的授权弹窗 永远不会出现。chrome-use extension connect 是同一条路径的显式写法。

# 装好扩展后，open 自动走 relay 接管真实 Chrome
$ chrome-use open "https://example.com"

# 同一条路径的显式写法
$ chrome-use extension connect

多个 Chrome profile：看清是哪一个，然后选它

relay 绑定的是当前正在和原生宿主通信的那个 profile 的扩展 worker。 如果某个站点回来显示未登录，先确认接管的是不是对的 profile，再下结论说登录丢了。

# 列出所有已连接的 profile（有 identity 权限则显示邮箱，否则显示稳定 id，标注默认项）
$ chrome-use browsers

# 把「本次 session」钉到指定 profile —— 按 session 粘滞，不同 agent 互不干扰
$ chrome-use --browser "me@example.com" snapshot

# 查看当前正在驱动的 profile
$ chrome-use extension status
$ chrome-use doctor

doctor 会同时显示当前运行中的扩展版本和 CLI 内置版本。若两者不一致，请先在 chrome://extensions 更新或重新加载 ab-connect。旧扩展可能让标签存活探针不可用； 探针失败本身不能证明页面 renderer 已卡死。tab inspect 需要 ab-connect 0.5.16 或更新版本。

让规则替你选：ChooseBrowser

「哪个站点用哪个账号」这件事，你心里本来就有数，只是每次都要用 --browser 再说一遍。 ChooseBrowser 是一个 macOS 链接路由工具， 它把这份映射存了下来；装了它之后，open 在你没显式指定 --browser 时会按你写的规则选 profile，并说明来源。

$ chrome-use open https://github.com/my-org/repo
· using Chrome profile Profile 14 — a ChooseBrowser rule routes this site there
  (github.com|/my-org*). Override with --browser <id|email>, or skip with --no-choosebrowser.

只读，没装的话完全无感——没有规则文件就不改变任何行为、也不打提示。 规则指向的 profile 如果没在跑扩展，会退回正常的 profile 选择， 该回退不保证网站账号正确。需要特定账号时，检查身份或显式指定 --browser。

规则排在「猜最近聚焦的窗口」之前——规则是你写下的意图，比从你正看着哪个窗口做的推断可信。 只有 open / goto / navigate 这类会导航的命令才查它； snapshot、click 作用在会话已经打开的东西上，不查。

反过来也可以：在显式 --browser 后面加 --remember， 导航成功之后它会请求 ChooseBrowser 把这个域名长期指向那个 profile， 下次就不用再传 --browser 了。

$ chrome-use open https://github.com/my-org/repo --browser work@example.com --remember
· asked ChooseBrowser to route github.com to work@example.com from now on — confirm in
  its dialog. Nothing is saved unless you do.

这是一次提议，不是一次保存。 ChooseBrowser 每次写入都会弹窗让你确认，并且刻意不给成功回调—— 任何进程都能打开 URL scheme，静默写入意味着别的工具可以悄悄把你的 银行域名指到一个你不看的浏览器上。所以 chrome-use 只能说「已请求」， 结果以那个弹窗为准。取消了就什么都不会发生。

只写域名、不写路径：规则如果绑在这条命令碰巧打开的那个路径上，翻到站内下一页就不生效了。 只在你显式传了 --browser 时才提议—— 把我们自己猜出来的 profile 写成永久规则，等于把一次推断变成你从没说过的长期决定。 请求要是构造不出来（命令不导航、profile 没有登录账号、账号不在 Chrome 注册表里……）， 它会在导航之前就退出并说明原因，而不是发一个会被静默丢弃的请求。 需要 ChooseBrowser ≥ 0.2.1（注册了 choosebrowser:// 的版本，chrome-use doctor 会报装的是哪个）；旧版本上没有程序处理这个链接， chrome-use 会明说没有提议成功，而不是当作发出去了。

--launch vs --profile auto

--launch 会开一个隔离的空白测试 profile——没有 cookie、没有登录、没有扩展 （所以扩展 relay 路径是关闭的）。它的窗口在 Chrome 的 profile 菜单里标为 chrome-use (<session>)，让盯着桌面的人一眼看出这个窗口属于哪个 session。 如果一个 launched session 需要更多东西：

万一真弹出「是否允许远程调试？」

不要反复重试——每次重试都会再弹一次。此时只有两种可能：

1. 你在用旧版。 避免这个弹窗的 relay 优先逻辑早已发布很多个版本了；如果还撞得到， 说明你的 chrome-use 太老，升级后重试：

$ curl -fsSL https://raw.githubusercontent.com/leeguooooo/chrome-use/main/install.sh | sh

# 若 which 显示多份安装，旧的 npm/pnpm 副本可能在遮挡新版
$ which -a chrome-use
$ npm rm -g chrome-use   # 或 pnpm rm -g chrome-use，让 install.sh 版本胜出

2. 扩展 / relay 没起来。 让用户装商店版扩展（上面那个一键链接）；装好后 relay 会持续在线， 这个弹窗再也不会回来。

relay 掉线：CLI 会自愈

如果某条命令突然报「couldn't reach your Chrome」/「relay … failed」——通常是 MV3 service worker 被挂起， 或两个 agent 在共用一个 relay——CLI 现在会自愈：它会等 worker 的 keepalive 把 relay 拉活 （约 25 秒）并重试一次，所以大多数掉线你根本感知不到。如果某条命令确实把错误抛出来了：

1. 直接重跑这条命令——到那会儿 relay 通常已经重连好了。
2. 还不行：chrome-use status（无需 daemon 的 CLI、扩展、中继、profile 与会话总览）→ chrome-use extension connect（重新 attach）→ 再重试。 CLI 会自动注册原生宿主，如果扩展从没装过还会自己打开商店页面——你不用手动跑 extension install。
3. 绝不要让用户用 --remote-debugging-port 退出/重启 Chrome 来恢复掉线的 relay—— 那会丢掉他们的所有标签页，也彻底破坏了扩展路径。
4. chrome-use reconnect 是 extension connect 的友好别名——无需任何重装， 就把 session 重新绑定到运行中的 Chrome。
5. 浏览器完全恢复不了？ 不要干等一张截图——退回到非视觉的验证方式： get text / eval，或用 curl/WebFetch 读已部署的页面。 通过 DOM/HTML 或 live URL 确认一个改动是正确的结果，不是失败。截图留给你真正要报告给用户的视觉检查。

OAuth / SSO 跳转现在直接就能过

一次登录 handoff（GitHub/Google OAuth、SSO）会把标签页跨进程导航，这过去会遗弃旧 session、 让下一次读取报「stale sessionId」失败。relay 现在会跨这次跨进程导航自动重新 attach opener， 并在新进程稳定期间短暂重试读取，所以 snapshot/screenshot/eval/get 在整个 handoff 期间都能正常工作，「Sign in with Google」/ OAuth 弹窗登录能端到端走完。

严格的多 agent 隔离

每个连接的 --session 都会拿到自己的一个彩色 Chrome 标签组（以 session 命名）， 并只驱动它自己的标签页——多个 agent 共享同一个真实浏览器而不串话，用户自己的标签页永远不会被编组。 CDP 驱动页面时不会移动用户的鼠标/键盘，所以不会跟他们抢控制权。

一个 session（走 relay）只驱动它自己创建或显式 adopt 的标签页。你自己的动作打开的弹窗—— 比如点「Sign in with Google」弹出的 OAuth 账号选择窗口——会被跟随、可作为你 session 的一部分来驱动 （切过去驱动那个选择器）。但它不会收编用户已有的标签页、其他 agent 的标签页，或无关的弹窗 （用户自己开的登录窗口是用户的）。tab list 可能为恢复目的显示其他标签，但会将它们标记为 foreign，不能直接切换或关闭。要驱动既存标签必须先显式 adopt；adopted 标签仍属于用户， 当前 session 不能关闭。同名 session 连接同一浏览器端点重启后仍会恢复 created 所有权，因此中断的清理可以安全继续。

用户页面上不会出现调试横幅

relay 的顶层导航现在优先走 Chrome 浏览器级标签页 API，更接近普通手动导航，而不是先用 CDP Page.navigate。如果站点仍在八秒内向同一 URL 连续提交四次，下一条命令会明确报告重载环并给出恢复建议。 可改用稳定的深链接，或用 tab adopt 接管一个已经渲染好的标签页来保留现场。

读取用户已经打开的标签页：adopt

需要读一个用户已经开着的标签页？用 chrome-use adopt <url-substring|targetId>—— 它会跨标签组找到那个已存在的标签页（用户自己的，或另一个 session 的）并驱动它，不会新开标签页。 没匹配上时它会报错并列出它能看到的标签页。这是穿过上面那层隔离的显式、opt-in 方式（它会把被收编的标签页打上你 session 的标签组）。

# 收编用户正看着的那个标签页，再对它做只读提取
$ chrome-use adopt "claude.ai/design"
$ chrome-use snapshot
$ chrome-use get text

反检测等级排名

这个真实的、已登录的 Chrome（扩展连接） > 一个有头的 launched 浏览器 > headless（禁止）。 一个真正的人类浏览器完全没有 headless / 自动化的破绽，所以任何对反-bot 敏感的任务都优先用它。

默认静默运行

驱动用户的真实 Chrome 时，agent 完全在后台工作——新标签页开出来时不聚焦，agent 从不强制把某个标签页顶到前台。 焦点是模拟的，所以页面照常渲染、计时器照常跑，不会被后台节流。你什么都不用做；只是别指望用户的视图跟着你跑。

行为层反-bot：拟人化输入

--humanize off|fast|human（或 AGENT_BROWSER_HUMANIZE）给点击、打字、滚动加上拟人节奏；默认 off， 一个每次导航都会跑的检测器会把被 Akamai/PerimeterX/DataDome 守卫的页面自动升到 human。 轨迹参数、节奏与调优见 反检测与隐身。

Cloudflare 通关：solve 一次，复用

通过一次 Cloudflare 挑战会铸出一个绑定 IP + User-Agent 的 cf_clearance cookie，复用同一出口 IP 和 UA 就能在过期前跳过挑战；驱动用户真实 Chrome（relay）会原生持久化它。解之前先跑 chrome-use cf-status （别名 cf、clearance）做预检，避免重复解已经过了的挑战。完整流程、reissue 判定与 cookie 读取见 反检测与隐身。

相关页面