chrome-use 使用教程：让 Claude Code 操控已登录的 Chrome（禅道、ONES 实测）

导读：想让 Claude Code 帮我看一眼禅道里还有几个 Bug 没关、ONES 上有没有挂在我名下的维护工单，结果它开的自动化浏览器哪儿都没登录。这篇记录用 chrome-use 解决这个问题的过程：怎么装、怎么让 agent 用起来、两个内网系统的只读查询、一次填表单（不提交）的实测，以及中间踩到的四个坑。

适用版本：chrome-use CLI 1.5.275、扩展 0.5.97，macOS，Claude Code 桌面版。

一、先说清楚：chrome-use 是什么

一句话：它是一座桥，让 AI agent 借用你正在用的那个 Chrome。

平时让 Claude Code 操作网页，它多半会用 Playwright 新开一个浏览器。新浏览器是一张白纸，没有 Cookie，公司内网的禅道、ONES、各种后台都要重新登录，碰上 SSO 或者二次验证基本就卡死了。

chrome-use 换了个思路：在你的 Chrome 里装一个扩展，再在本机装一个命令行程序，两者通过 Chrome 的原生消息（native messaging，一条本机进程间通道，不走网络端口）连起来。agent 在终端里敲 chrome-use open ...，扩展就在你的 Chrome 里新开一个标签页去执行，登录态是现成的。

不装也行，只是遇到要登录的页面，得你自己去看，或者把内容复制给 AI。

什么时候值得装：

经常让 AI 查内网系统（缺陷管理、工单、监控后台），而且这些系统走公司 SSO
想让 AI 帮你做一些只读的巡检，比如"看看我名下还有哪些没处理的单"
已经在用 Claude Code、Codex 或 Cursor，不想为每个工具单独折腾浏览器登录

只读公开文档的话，WebFetch 就够了。

二、它和其他方案的区别

我在装之前对比了一下手头能用的几种方式：

方案	怎么连浏览器	用谁的登录态	我的看法
Playwright 新开浏览器	自带 Chromium	独立 profile，要重新登录	公开页面够用，内网 SSO 很麻烦
Playwright 连 CDP 端口	`--remote-debugging-port`	独立 profile	Chrome 136 起默认 profile 不接受这个参数，只能另开 profile，还是要登录
Claude in Chrome	Anthropic 官方扩展	你的 Chrome	只有 Claude 能用，需要付费订阅
chrome-use	商店扩展 + 原生消息	你正在用的 Chrome	Claude Code、Codex、脚本都能调，不开调试端口

💡 Chrome 136 这一条出自作者文章，未单独核对。

我最后选 chrome-use，主要是因为它就是个普通 CLI，Claude Code 里用 Bash 直接调，不需要额外配 MCP，换成 Codex 也是同一套命令。

三、安装：其实点几下就好

官方给的安装方式是一行 curl ... | sh。我原本让 Claude Code 去跑这行命令，后来自己在 Chrome 里装扩展的时候发现，扩展的侧栏自带一个引导，根本不用碰终端。

1. 装扩展

打开 Chrome 应用商店的扩展页安装：

chromewebstore.google.com/detail/chro...

扩展 ID 是 knfcmbamhjmaonkfnjhldjedeobeafmk，也可以在商店里直接搜 chrome-use。装好后点工具栏图标，会打开一个侧栏。

2. 按侧栏提示装本地程序

侧栏第一次打开时会显示"这台电脑上还没装 chrome-use"，下面有一个"下载 Mac 版"按钮。步骤是：

点"下载 Mac 版"
在下载栏打开安装包，双击 ChromeUse，再点"打开"（不用输密码，也不用开终端）
回到侧栏，等几秒它会自己连上

连上之后侧栏会变成"已连接"，并列出本机检测到的 agent：Codex、Claude Code、OpenCode、Pi，已安装的会标出来。

3. 确认命令行可用

本地程序装在 ~/.local/bin/chrome-use。如果终端里找不到命令，把这个目录加进 PATH：

bash 复制代码

# 在 ~/.zshrc 里追加一行，然后 source 一下
export PATH="$HOME/.local/bin:$PATH"

# 确认版本
chrome-use --version

我这边输出的是 chrome-use 1.5.275。

4. 跑一次自检

bash 复制代码

# 检查 CLI、扩展、Chrome、本地桥是否都通
chrome-use doctor

我的结果是 14 pass, 1 warn, 0 fail。那一条 warn 是：

text 复制代码

warn  site access is off: when a password manager's menu (Bitwarden, 1Password...)
      covers a field on a chrome-use tab while Chrome is behind another app,
      chrome-use cannot close it and waits for the user to press Escape
fix: click the chrome-use icon in Chrome's toolbar, then "Allow on all sites" (once)

只有密码管理器的下拉框盖住输入框时才有影响，不用密码管理器自动填充可以先不管。

⚠️ 作者文章里提到，macOS 上执行 chrome-use extension install 可能会装一个配置描述文件来给所有 profile 强制安装扩展，装了之后 Chrome 会显示"由你的组织管理"，"使用安全 DNS"会被锁住。走侧栏引导安装我没遇到这个问题；如果你走命令行，作者给的规避方式是加 --no-profile。

5. 技能不用单独装

装完扩展和本地程序就够了，不需要再手动装 skill 。本地程序装好后，会自动往本机检测到的各个 agent 的技能目录里放一个 chrome-use 技能，doctor 输出里的 Agent skill installed (5 location(s)) 说的就是这件事。

可以直接到技能目录里确认：

bash 复制代码

# 查找所有自动安装的 chrome-use 技能目录
find ~ -maxdepth 5 -type d -name chrome-use -path "*skills*" 2>/dev/null

我这台机器上找到了 5 个，正好对上 doctor 的数字：

text 复制代码

/Users/<用户名>/.trae/skills/chrome-use
/Users/<用户名>/.codebuddy/skills/chrome-use
/Users/<用户名>/.cursor/skills/chrome-use
/Users/<用户名>/.claude/skills/chrome-use
/Users/<用户名>/.agents/skills/chrome-use

Claude Code 用的是 ~/.claude/skills/chrome-use/SKILL.md，新开一个会话，技能列表里就能看到 chrome-use。装到哪几个目录取决于本机有哪些 agent，我这里没有 ~/.codex 下的那份。

作者文章里提到的插件市场、npx skills add 两种装法不用再装一遍，chrome-use upgrade 会把 CLI 和技能一起升级。

技能本身也可以不要。CLI 是普通命令，在提示词里写一句"用 chrome-use CLI 操作浏览器，先执行 chrome-use skills get core"效果一样。技能的作用是让 agent 碰到网页任务时主动想到 chrome-use，没有它的话，agent 可能默认去用 WebFetch 或者自己开的浏览器。

技能文件本身很短，主要是让 agent 先执行：

bash 复制代码

# 输出当前版本的完整用法说明，内容由二进制自己生成，和版本始终一致
chrome-use skills get core

文档跟着二进制走，升级 CLI 就等于升级了 agent 的说明书。

四、核心用法：在 Claude Code 里直接说

装好之后，日常使用不需要自己敲任何 chrome-use 命令。在 Claude Code 里用大白话说要做什么，带上网址就行，比如：

打开 http://<禅道地址>/zentao/bug-browse-<产品ID>-0.html，看看还有哪些 Bug 没关闭，整理成表格给我。

Claude Code 会通过 chrome-use 技能自己选命令，在你的 Chrome 里开后台标签页操作，把结果整理好回给你，最后关掉标签页。

提需求时有几个小技巧：

写法	作用
写明"只读，不要修改" / "填好但不要保存"	给 agent 划清边界，涉及提交的动作它会先停下来问你
直接给列表页或保存好的视图名	比让它自己拼筛选条件可靠
要结果截图	让它 `screenshot` 一张，方便你核对
碰到登录或验证码让我处理	它会把这一步交还给你

背后执行的命令（了解即可）

下面是 Claude Code 在背后替你跑的命令，不用记，排查问题或写脚本时有用。操作方式只有一个循环：

bash 复制代码

# 1. 打开页面（在后台标签页里开，不抢你的焦点）
chrome-use --session demo open https://github.com/leeguooooo/chrome-use

# 2. 拿可交互元素，每个元素配一个 @eN 短引用
chrome-use --session demo snapshot -i

# 3. 对引用执行动作，--observe 会把页面变化一并返回
chrome-use --session demo click @e12 --observe

# 4. 收尾：关掉这次会话开的所有标签页
chrome-use --session demo done

几个要点：

--session：每个任务用一个独立名字。chrome-use 会把这个会话的标签页放进一个彩色标签组，几个 agent 同时跑也不会互相干扰，你自己开的标签页它不碰。
snapshot -i 和 snapshot -c ：-i 只列可交互元素，-c 是紧凑模式，会带上表格单元格这类文本。读列表数据时我用 -c 更多。
ref 会失效 ：页面一跳转，之前的 @eN 就作废了，要重新 snapshot。
done：任务结束必须调用，不然标签页会一直留在你的 Chrome 里。

其他常用命令见文末速查表。

五、实测一：只读查禅道 Bug 列表

第一个测试是禅道（开源项目管理工具）的 Bug 浏览页。我已经在 Chrome 里登录过，在 Claude Code 里只说了一句（措辞稍作整理）：

用 chrome-use 打开 http://<禅道地址>/zentao/bug-browse-<产品ID>-0.html，看看还有哪些 Bug 没关闭

Claude Code 先跑了 chrome-use doctor 自检，然后打开页面、读出 Bug 列表，回给我一张表：

标题（已脱敏）	状态	解决方案	指派给
定时任务消息没有收到	已解决	已解决	测试 A
规则匹配不到人员时需要兜底展示	已解决	不予解决	测试 B
部门下拉框能选到不该选的部门	已解决	设计如此	测试 A

全程我没碰终端。下面是它在背后执行的命令和遇到的坑。

bash 复制代码

# 打开 Bug 列表并确认标题
chrome-use --session zentao open "http://<禅道地址>/zentao/bug-browse-<产品ID>-0.html"
chrome-use --session zentao get title

输出的第一行是：

text 复制代码

profile: 用户1 (Default, 我的 Google 账号) --- the only connected profile

括号里原本是登录 Chrome 的邮箱，这里做了脱敏。

标题是"<产品名>-Bug - 禅道"，没有跳登录页，说明用的确实是我自己的登录态。

踩坑 1：read 读出来是空的

Claude Code 接着用 read 去读页面，只得到一行：

text 复制代码

· left out 1 block of text (51916 chars) that a person on this page can't see
  (off-screen, transparent, clipped or zero-size)

5 万多字被当成"不可见文本"跳过了。原因是禅道把主体内容放在 iframe 里，read 判断外层页面上这块文字对人不可见。

它随即换成 snapshot -c，拿到了完整的无障碍树，iframe 里的内容也在：

bash 复制代码

# 紧凑模式的无障碍树，表格每个单元格都会列出来
chrome-use --session zentao snapshot -c

输出里能看到"未关闭 3"的标签，以及每一行 Bug 的 ID、标题、级别、状态、创建者、指派人和解决方案。上面那张表就是 Claude Code 从这里整理出来的，3 条和页面上"未关闭 3"的数字对得上。

bash 复制代码

# 查完关掉标签页
chrome-use --session zentao done

done 的输出是 closed 1 tab(s) this session opened (verified absent)，我自己开的标签页一个没动。

六、实测二：查 ONES 上我负责的未解决维护工单

第二个测试更接近真实场景：手上有一个 ONES 的链接，想看看我负责的维护工单还有没有没处理的。在 Claude Code 里是这么问的：

你可以看下 https://<ONES 地址>/plugin/.../index.html?code=oc-...&state=... 我负责的未解决维护工单嘛

Claude Code 的回答是"你名下目前没有未解决的维护工单，数量是 0"，并附上了它用的筛选条件和一张截图。它还顺带提到"我负责的工作项"里有 2 条待办子任务没出现在维护工单视图里，判断是不属于维护项目，并说明这一点没有逐条核实。

这个过程中它自己处理了两个坑。

踩坑 2：别人给的 OAuth 回调链接打不开

这个链接是第三方登录的回调地址，带一个 code=oc-... 参数。Claude Code 先直接用 open 打开，页面停在了一个叫"OAuth"的中转页，只有一个"返回"按钮：

text 复制代码

- button "返回" [ref=e1]
- note: left out 1 block of text (5 chars) that a person on this page can't see

OAuth 的 code 一般只能用一次，这类链接转发出来基本都是失效的。Claude Code 的处理是不用回调链接，直接打开系统首页，让已有的登录态自己生效：

bash 复制代码

# 直接打开工作台
chrome-use --session ones open "https://<ONES 地址>/project/#/workspace"
chrome-use --session ones wait --load networkidle
chrome-use --session ones get url

页面正常进入"我的工作台"，右上角是我的名字，左侧的"筛选器"下面有我之前保存的视图，其中一个就叫"维护工单-我负责的-未完成"。

用保存好的视图，而不是让 AI 自己拼筛选条件

它在筛选器里找到了我之前保存的视图，直接点进去：

bash 复制代码

# 列出可交互元素，找到视图对应的 ref
chrome-use --session ones snapshot -i -c

# 点击"维护工单-我负责的-未完成"，--observe 返回页面变化
chrome-use --session ones click @e46 --observe

结果页显示"共 0 条符合条件的结果"。

数量为 0 的时候，Claude Code 没有直接下结论，而是用 eval 把条件标签读出来，确认筛选条件确实加载了：

bash 复制代码

# 读出当前视图的筛选条件
chrome-use --session ones eval "[...document.querySelectorAll('.ones-tag')].map(e=>e.innerText.trim()).filter(Boolean)"

输出是三个条件标签：

json 复制代码

[
  "负责人\n包含\n"自己"",
  "所属项目\n包含\n"<维护项目名>"",
  "状态\n包含\n"待办*、等待处理中、已接收、修复中*、修复中""
]

三个条件都在，0 条就是真的 0 条。最后截一张图给自己留底：

bash 复制代码

# 截图确认，然后收尾
chrome-use --session ones screenshot ./ones.png
chrome-use --session ones done

踩坑 3：click 后的输出不代表页面已经稳定

click --observe 的输出最后有一条警告：

text 复制代码

⚠ Page had not settled after 1001ms (request in flight still active: ...) ---
  this capture may be mid-transition. Re-read to confirm

单页应用切换视图时请求还没回来，--observe 抓到的可能是中间状态。所以 Claude Code 点击后又跑了一次 wait --load networkidle 再读结果，ONES、Jira 这类系统都需要这一步。

七、实测三：在禅道提 Bug 页填好表单（不保存）

前两个测试都是只读。这一次试试写操作，在 Claude Code 里说（措辞稍作整理）：

在禅道提 Bug 页面填好表单，不要保存，填好后截图给我看

Claude Code 自己从 Bug 列表点进"提Bug"，填了标题、重现步骤和关键词，关掉了挡住表单的升级弹窗，截图后直接关闭标签页，保存按钮没碰。最终效果就是本节末尾那张截图。

下面是它在背后的操作过程，富文本编辑器这一块踩了不少坑。

找到入口，填普通输入框

bash 复制代码

# 从 Bug 列表进入提 Bug 页面
chrome-use --session zentao-form open "http://<禅道地址>/zentao/bug-browse-<产品ID>-0.html"
chrome-use --session zentao-form snapshot -i      # 找到"提Bug"链接，这次是 @e27
chrome-use --session zentao-form click @e27 --observe
chrome-use --session zentao-form wait --load networkidle
chrome-use --session zentao-form snapshot -i      # 列出表单字段

表单字段在 snapshot 里是这样的（节选）：

text 复制代码

- rowheader "Bug标题" [ref=e153]
  - textbox [ref=e179]
  - button "3  " [ref=e180]
- rowheader "重现步骤" [ref=e155]
  - Iframe [ref=e182]
- cell "关键词" [ref=e161]
  - textbox [ref=e171]
- cell "保存 返回" [ref=e165]
  - button "保存" [ref=e173]

标题和关键词是普通输入框，fill 一次就填进去了，--observe 返回的变化里能直接看到新值：

bash 复制代码

# 填 Bug 标题和关键词
chrome-use --session zentao-form fill @e179 "【chrome-use 演示】列表页筛选后分页数量不对（仅演示，不提交）" --observe
chrome-use --session zentao-form fill @e171 "chrome-use 演示" --observe

踩坑 4：重现步骤是 iframe 里的富文本编辑器

"重现步骤"用的是 KindEditor 富文本编辑器，在 snapshot 里只显示成一个 Iframe [ref=e182]。这一块 Claude Code 试了好几种办法：

尝试	结果
`fill @e182 "..."`	`✗ fill failed: Uncaught`
`click @e182` 后 `press Control+a` 再 `paste`	提示按键落在了 iframe 元素本身，焦点进不去，粘贴没生效
`frames` 找到编辑器所在的 frame，`frame 2` 切进去后 `fill body`	文字写进去了，但换行全丢了，连成一行

而且中间还出了一个岔子：几次尝试之后，关键词输入框后面多出了一段重现步骤的文字。Claude Code 是在复查 snapshot 时发现的，随后用 fill @e171 改回来，再用 get value @e171 确认。

⚠️ 填完表单一定要用 get value 或 snapshot 逐个核对字段，不能只看命令返回成功。富文本、iframe 这类控件特别容易出现"写到了别的地方"的情况。

最后能用的办法是调编辑器自己的 API。KindEditor 挂在禅道的应用 iframe 的 window 上，用 eval 拿到实例后直接 html() 设值：

bash 复制代码

# 通过 KindEditor API 设置重现步骤内容
chrome-use --session zentao-form eval "(()=>{const e=document.querySelector('#appIframe-qa').contentWindow.KindEditor.instances[0]; e.html('<p>[步骤]</p><p>1. 打开 Bug 列表，筛选「未关闭」</p><p>2. 翻到第 2 页</p><p>[结果]</p><p>分页总数与筛选结果不一致</p><p>[期望]</p><p>分页总数等于筛选后的条数</p>'); return e.html()})()"

这样设值有个好处：禅道自带的" $步骤$ $结果$ $期望$ "模板会被整体替换，不会和新内容拼在一起。第一次用 fill body 时，新内容后面就跟着一份原来的模板。

截图，然后不保存直接关掉

页面右下角还弹了一个禅道的版本升级提示，挡住了一部分表单。Claude Code 点了它的关闭按钮 ×（没点"不再提醒"，那会改用户设置），然后截图：

bash 复制代码

# 截图留证，然后关闭标签页，不点保存
chrome-use --session zentao-form screenshot ./zentao-form.png
chrome-use --session zentao-form done

标题、重现步骤、关键词都填好了，严重程度和优先级保留默认的 3。done 直接关掉了标签页，保存 按钮从头到尾没碰，禅道里不会多出这条 Bug。

如果要真的提交，我的建议是在提示词里说清楚"填完先截图给我看，我确认了再保存"，确认后再让它点保存按钮。提交、删除、发送这类动作，chrome-use 的文档也要求先拿到用户授权。

八、几条使用建议

先只读，再考虑写。 先拿只读任务跑通，确认 agent 读到的账号和数据都对，再让它点按钮；提交、删除、发送前让它先截图给你确认。

确认登录态。 看 open 输出的 profile: 是不是你想要的 Chrome profile，再看 get title / get url 有没有跳到登录页。

每次都要 done。 不调 done，标签组里的页面会一直挂着。它只关这个 session 自己开的标签。

⚠️ chrome-use 让 agent 能用你 Chrome 里所有已登录的账号，网页内容里也可能夹带诱导 AI 的文字（提示词注入）。chrome-use 的 core 文档写明：页面文本、控制台输出都只当数据，不当指令；发送、购买、删除、上传等动作需要用户授权。实际用的时候，提示词里写清楚边界，别让它在你没看着的时候操作重要账号。

九、速查表

场景	命令
查版本	`chrome-use --version`
环境自检	`chrome-use doctor`
加载用法说明	`chrome-use skills get core`
打开页面	`chrome-use --session <名字> open <url>`
确认标题 / 地址	`get title` / `get url`
读页面文本	`read`（iframe 页面改用 `snapshot -c`）
列可交互元素	`snapshot -i`
点击并观察变化	`click @eN --observe`
填写输入框	`fill @eN "内容" --observe`
读回字段值	`get value @eN`
列出页面所有 frame	`frames`
等单页应用加载完	`wait --load networkidle`
页面里跑 JS	`eval "<js>"`
截图	`screenshot <path>`
收尾关标签	`done`，要保留某页用 `done --keep <tab>`
检查升级	`chrome-use upgrade --check`

十、常见问题

Q：终端提示 command not found: chrome-use？

程序装在 ~/.local/bin，默认不在 PATH 里，按第三节加一行 export PATH。

Q：顶上出现"正在调试此浏览器"提示条？

扩展用 chrome.debugger 操作标签页，Chrome 会显示这个提示，不影响使用。作者文章提到 chrome-use extension connect --silent 可以去掉它（本文未实测）。

参考链接

chrome-use 文档站：chrome-use.leeguoo.com/
chrome-use 扩展（Chrome 应用商店）：chromewebstore.google.com/detail/chro...
chrome-use 源码：github.com/leeguooooo/...

你平时让 AI 查内网系统，是用 Playwright 单独开一个 profile 登录，还是直接借用自己的 Chrome？碰到过 SSO 或者二次验证卡住的情况吗？评论区说说你用的是哪种方案，我挑典型的补进 FAQ。

觉得有用的话点个赞、收个藏，下次配环境时翻得到。