连接方式 / 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

--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（检查）→ 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）只跟踪并驱动它自己创建的标签页。你自己的动作打开的弹窗—— 比如点「Sign in with Google」弹出的 OAuth 账号选择窗口——会被跟随、可作为你 session 的一部分来驱动 （切过去驱动那个选择器）。但它不会收编用户已有的标签页、其他 agent 的标签页，或无关的弹窗 （用户自己开的登录窗口是用户的）。结论：tab list 只显示你这个 session 的标签页； 要驱动某个具体页面，就在你自己的标签页里导航过去，别指望一个已存在或弹出来的标签页出现在列表里。

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

读取用户已经打开的标签页：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 从不强制把某个标签页顶到前台， 并且焦点是模拟的，所以后台页面仍然会渲染、并报告 visibilityState: 'visible'。你什么都不用做； 只是别指望用户的视图跟着你跑（只有当你刻意想让用户看到某个标签页时，才用显式的 bringToFront 把它顶到前台）。

行为层反-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 读取见 反检测与隐身。

相关页面