TL;DR：agent-browser 是 Vercel Labs 出的 AI agent 專用瀏覽器自動化 CLI，用 Chrome 跑、不依賴 Playwright。它最大的差別是「snapshot + refs」——回傳精簡的可訪問性元素清單（每頁約 200-400 tokens），而不是整坨 HTML。我今天把它裝到 Mac、跑通一個登入流程、再裝成 Claude Code skill，全程實測。這篇是覆盤：安裝怎麼裝、登入流程怎麼跑、踩了哪些坑、以及怎麼接進 Claude Code 對話直接調用。
📌 目錄
- 我為什麼想試
- agent-browser 是什麼：snapshot + refs 的省 token 原理
- 跟 Playwright MCP、Stagehand 比
- 安裝實錄
- 實測：跑通一個登入流程
- 踩坑紀錄
- 裝成 Claude Code skill
- 常見問題
- 延伸資源
⚡ 我為什麼想試
我平常用 Claude Code 做事，會接 Playwright MCP 讓它操作瀏覽器——截圖、填表單、驗收 UI。問題是這東西很吃 context：一個登入流程跑下來，光是塞給模型的可訪問性樹就好幾萬 tokens，後面對話品質肉眼可見地掉。
某天看到一篇介紹 Vercel Labs 的 agent-browser，賣點正好打中這個痛：同樣是操作瀏覽器，它用一套叫「snapshot + refs」的設計，把每頁壓到幾百 tokens。我自己一開始也半信半疑，所以乾脆裝到 Mac 上跑一遍，順便把它接進 Claude Code，看是不是真的能取代我手上的 Playwright MCP 流程。
這篇就是那一輪實測的完整紀錄。
🧠 agent-browser 是什麼：snapshot + refs 的省 token 原理
agent-browser 是 Vercel Labs 開源的命令列工具（github.com/vercel-labs/agent-browser），定位很明確：給 AI agent 用的瀏覽器自動化。它透過 CDP（Chrome DevTools Protocol）驅動真正的 Chrome，不裝 Playwright 或 Puppeteer。
核心是它的工作循環。傳統做法是把整個頁面（DOM 或完整可訪問性樹）丟給模型，讓模型自己找元素、組 CSS selector。agent-browser 反過來——snapshot 只回傳精簡的可訪問性樹，每個可操作元素配一個短 ref，像 @e1、@e2。模型不用看 HTML，直接用 ref 操作：
agent-browser open <url> # 1. 開頁
agent-browser snapshot -i # 2. 看可操作元素（-i 只列互動元素）
agent-browser click @e3 # 3. 用 snapshot 給的 ref 操作
agent-browser snapshot -i # 4. 頁面一變就重新 snapshot官方文件寫這套 snapshot 把每頁壓到約 200-400 tokens，取代解析原始 HTML 的成本。這是它省 token 的根。實際的 snapshot 長這樣（節錄我跑登入頁的輸出）：
- heading "Login Page" [level=2, ref=e2]
- textbox "Username" [ref=e6]
- textbox "Password" [ref=e8]
- button " Login" [ref=e4]
@e6、密碼欄是 @e8、登入鈕是 @e4，不用我貼一整頁 HTML。
⚖️ 跟 Playwright MCP、Stagehand 比
我看到的那篇介紹文做過四方案的 token 對比，原文作者實測 agent-browser 約省 82%。這個數字我一開始沒自己驗，後來補測了一輪——用 tiktoken 實際算過，結論是省 92～97%，跟 82% 同一個量級、甚至更高（實測過程見下方）。
| 方案 | 操作方式 | Token 效率 | 我的看法 |
|---|---|---|---|
| agent-browser | snapshot + ref | 極高（我實測省 92～97%） | 只回精簡清單，實測數字見下 |
| Playwright MCP | 完整可訪問性樹 | 低 | 我自己用過，長對話 context 掉很有感 |
| Playwright CLI | 指令式 | 高 | 沒實測 |
| Stagehand | 自然語言描述 | 中（含 LLM 推理） | 沒實測，需 TypeScript |
我自己實測的省 token 比例
後來我拿 GitHub 的 vercel-labs/agent-browser repo 頁當樣本（內容豐富的真實頁），同一頁三種餵法丟給模型，用 tiktoken o200k_base（GPT-4o 同款 tokenizer）實際算：
| 餵給模型的方式 | tokens | 比完整 HTML 省 |
|---|---|---|
| 渲染後完整 HTML（傳統做法） | 433,903 | — |
snapshot（完整 a11y tree） | 35,219 | 省 91.9% |
snapshot -i（只留互動元素） | 12,778 | 省 97.1% |
outerHTML」（這頁 1.06MB），這才是傳統「整頁 DOM 丟模型」的真實開銷。想看完整的 token 計量方法論，我另外寫了一篇：LLM token 怎麼算才準？5 種計量方案實測比較。
它的 ref 機制比 CSS selector 穩在哪？ref 是基於 ARIA role 跟可訪問名稱產生的，不是位置或 class。頁面改版只要按鈕的語意角色沒變，定位就還在。代價是——下面踩坑會講——ref 有有效期。
💰 安裝實錄
工具教學該給的我都給齊。先看前置：
| 依賴 | 最低版本 | 驗證指令 |
|---|---|---|
| Node.js | 20+ | node -v |
| npm | 隨 Node | npm -v |
| 網路 | 能連 Google | 第一次要下載 Chrome for Testing |
npm install -g agent-browser
agent-browser install第二條 agent-browser install 會從 Google 的 Chrome for Testing 通道抓一份獨立的 Chrome，不碰你日常用的那個。我這次抓到的是：
✓ Chrome 149.0.7827.55 installed successfully
Location: /Users/yanchen/.agent-browser/browsers/chrome-149.0.7827.55驗證裝好了：
agent-browser --version
# agent-browser 0.27.0
which agent-browser
# /Users/yanchen/.nvm/versions/node/v22.12.0/bin/agent-browser看到版本號 + 路徑解析得出來，就算成功。Linux 上若缺系統依賴，安裝那步改用 agent-browser install --with-deps。
⭐ 實測：跑通一個登入流程
光看版本號不算數，我要 round-trip——從開頁、填表單、送出，到截圖看到登入成功畫面，整條走通才算。
我原本照原文用 Hacker News 當例子，但它的登入頁對 headless / 機房 IP 會擋（後面踩坑會講），所以換成 the-internet 的登入 demo 頁。流程如下：
agent-browser open "https://the-internet.herokuapp.com/login"
agent-browser snapshot -i # 抓表單欄位的 ref
agent-browser fill @e6 "tomsmith"
agent-browser fill @e8 "SuperSecretPassword!"
agent-browser click @e4 # 點 Login
agent-browser get text "#flash" # 讀回結果驗證
agent-browser screenshot login-success.png
agent-browser closesnapshot 抓到 username=@e6、password=@e8、Login 鈕=@e4，填值送出後 get text 讀回 You logged into a secure area!，頁面也進到 Secure Area。截圖證實——綠色成功 banner、Secure Area 標題、Logout 按鈕都在：
整條 snapshot → fill → click → 讀回 → 截圖，機制如預期。值得一提的是它有個 stateful daemon——指令之間瀏覽器保持開著，所以這幾條指令像在同一個 session 裡跑，不是每條都重開瀏覽器，速度上很順。收尾用 agent-browser close。
🎨 踩坑紀錄
實測一定有坑，這幾個是這輪真的撞到的。
Hacker News 回 "Sorry."
照原文用 HN 當例子，open 沒問題、首頁 snapshot 也正常（連 login 連結都抓到 @e110），但一 click @e110 進登入頁，再 snapshot 就只回：
- StaticText "Sorry."這不是工具壞，是 HN 對 headless / 機房 IP 的反爬。很多會擋自動化的站都這樣。解法是換站，或加 --headed 用有頭模式（有些站對有頭瀏覽器寬鬆一點）。我直接換成 the-internet 的 demo 頁，乾淨驗完。
ref 會過期，頁面一變就要重抓
這是最容易踩的。ref（@e1…）每次 snapshot 重新編號，而且頁面一變——導航、表單送出、動態 re-render、彈出 dialog——舊 ref 立刻失效。我一開始在登入頁拿的 @e4，登入後那個編號早就指別的東西了。
規則很簡單：每次 ref 操作前，如果上一步改變了頁面，就先重新 snapshot。把它當成「快照是一次性的」就不會錯。
nvm 裝的 CLI，路徑可攜性
我這次想把 agent-browser 配成「換到任何專案、任何終端機都能用」。但它是用 nvm 的 node 裝的，binary 綁在 v22.12.0 底下。我驗了一輪——全新登入 shell（zsh -lic）跟不同 cwd 都叫得到，因為 nvm 的 default alias 也指 22.12.0：
cat ~/.nvm/alias/default
# 22.12.0只要 nvm default 不亂動，binary 就一直解析得到。這點如果你也用 nvm，記得確認一下 default 版本，不然換 node 版可能 command not found。
🔗 裝成 Claude Code skill
最後一步，把它接進 Claude Code，讓我對話裡講「幫我用瀏覽器開 X 截圖」就自動調用。
官方有提供 skill，但有個聰明的設計：完整指南不是寫死在 SKILL.md 裡，而是由 CLI 動態供給。agent-browser skills get core 會輸出跟「當前安裝版本完全對應」的工作流，我實測 core 是 476 行、加 --full 是 2425 行。
所以我沒把 2425 行整包塞進 skill，而是建一個薄存根——SKILL.md 只放觸發描述跟速記，正文叫 Claude Code 在需要時去跑 agent-browser skills get core 取最新內容：
mkdir -p ~/.claude/skills/agent-browser
# SKILL.md 內容：frontmatter（name/description/allowed-tools）
# + 正文指向 agent-browser skills get core這樣做的好處：
| 做法 | 升級後 | 平常 context |
|---|---|---|
| 整包複製 2425 行 | 要重抄一次 skill | 一直佔著 |
| 薄存根 + CLI 動態供給 | agent-browser upgrade 即可，skill 不用改 | 不用時不佔 |
allowed-tools 我設 Bash(agent-browser:*)，描述放了中英文觸發詞（「幫我截圖網頁」「填表單」「open a website」之類）。建完 Claude Code 重新載入就把它列進 skill 清單了，講對應的話就會觸發。
❓ 常見問題
Q：agent-browser 需要先裝 Playwright 嗎？
不用。它透過 CDP 直接驅動 Chrome，自己用 agent-browser install 抓一份 Chrome for Testing，跟 Playwright/Puppeteer 完全無關。
Q：它會動到我日常用的 Chrome 嗎？
不會。install 抓的是獨立的 Chrome for Testing，裝在 ~/.agent-browser/browsers/，跟你平常的 Chrome 分開。
Q：預設看得到瀏覽器視窗嗎？
預設 headless（背景跑、看不到）。要看到視窗加 --headed，例如 agent-browser open --headed 。
Q：ref 為什麼有時候點不到東西？
最常見是 ref 過期了。ref 每次 snapshot 重編、頁面一變就失效，下次 ref 操作前先重新 snapshot -i 拿新的。
Q：跟 Playwright MCP 比，真的省很多 token 嗎？
真的。我用 tiktoken 實測過：同一個 GitHub repo 頁，渲染後完整 HTML 是 433,903 token，agent-browser 的 snapshot 只要 35,219（省 91.9%）、snapshot -i 只要 12,778（省 97.1%）。原文作者測的是 ~82%，我這台機器測下來更高，同一個量級。注意這是單頁單樣本，HTML 越肥的頁省越多。
🔗 延伸資源
- agent-browser 截圖標註：3 招讓 AI 看著畫面操作 — 下一篇，純文字 snapshot 抓不到的視覺層（annotate / highlight / diff）
- vercel-labs/agent-browser（GitHub） — 原始碼、README、完整指令
- agent-browser 官網 — 安裝與文件入口
- snapshot + refs 設計說明 — ref 機制細節
- 本機速查：裝好後直接跑
agent-browser skills get core --full，拿到跟你版本一致的完整工作流