使用 agent-browser 進行瀏覽器自動化
此 CLI 直接透過 CDP 使用 Chrome/Chromium。透過 npm i -g agent-browser、brew install agent-browser 或 cargo install agent-browser 安裝。執行 agent-browser install 以下載 Chrome。
核心工作流程
每個瀏覽器自動化都遵循此模式:
- 導覽:
agent-browser open <url> - 快照:
agent-browser snapshot -i(取得元素參考,如@e1、@e2) - 互動:使用參考進行點擊、填寫、選取
- 重新快照:導覽或 DOM 變更後,取得新的參考
agent-browser open https://example.com/form
agent-browser snapshot -i
# 輸出:@e1 [input type="email"], @e2 [input type="password"], @e3 [button] "Submit"
agent-browser fill @e1 "[email protected]"
agent-browser fill @e2 "password123"
agent-browser click @e3
agent-browser wait --load networkidle
agent-browser snapshot -i # 檢查結果
指令鏈結
指令可以使用 && 在單次 shell 呼叫中鏈結。瀏覽器會透過背景守護行程在各指令之間保持連線,因此鏈結比單獨呼叫更安全且更有效率。
# 在單次呼叫中鏈結 open + wait + snapshot
agent-browser open https://example.com && agent-browser wait --load networkidle && agent-browser snapshot -i
# 鏈結多個互動
agent-browser fill @e1 "[email protected]" && agent-browser fill @e2 "password123" && agent-browser click @e3
# 導覽並擷取
agent-browser open https://example.com && agent-browser wait --load networkidle && agent-browser screenshot page.png
何時鏈結: 當您不需要在繼續之前讀取中間指令的輸出時(例如,open + wait + screenshot),請使用 &&。當您需要先解析輸出時(例如,快照以發現參考,然後使用這些參考進行互動),請單獨執行指令。
處理驗證
當自動化需要登入的網站時,請選擇最適合的方法:
選項 1:從使用者的瀏覽器匯入授權(最適合一次性任務)
# 連線到使用者正在執行的 Chrome(他們已登入)
agent-browser --auto-connect state save ./auth.json
# 使用該授權狀態
agent-browser --state ./auth.json open https://app.example.com/dashboard
狀態檔案包含純文字的工作階段 Token——請加入 .gitignore 並在不需要時刪除。設定 AGENT_BROWSER_ENCRYPTION_KEY 以進行靜態加密。
選項 2:持久性設定檔(最適合重複性任務)
# 首次執行:手動或透過自動化登入
agent-browser --profile ~/.myapp open https://app.example.com/login
# ... 填寫憑證,提交 ...
# 所有後續執行:已驗證
agent-browser --profile ~/.myapp open https://app.example.com/dashboard
選項 3:工作階段名稱(自動儲存/還原 cookies + localStorage)
agent-browser --session-name myapp open https://app.example.com/login
# ... 登入流程 ...
agent-browser close # 狀態自動儲存
# 下次:狀態自動還原
agent-browser --session-name myapp open https://app.example.com/dashboard
選項 4:驗證保險庫(憑證加密儲存,依名稱登入)
echo "$PASSWORD" | agent-browser auth save myapp --url https://app.example.com/login --username user --password-stdin
agent-browser auth login myapp
選項 5:狀態檔案(手動儲存/載入)
# 登入後:
agent-browser state save ./auth.json
# 在未來的工作階段中:
agent-browser state load ./auth.json
agent-browser open https://app.example.com/dashboard
請參閱 references/authentication.md 以了解 OAuth、2FA、基於 Cookie 的驗證和 Token 刷新模式。
基本指令
# 導覽
agent-browser open <url> # 導覽(別名:goto, navigate)
agent-browser close # 關閉瀏覽器
# 快照
agent-browser snapshot -i # 可互動元素及其參考(建議使用)
agent-browser snapshot -i -C # 包含游標互動元素(具有 onclick、cursor:pointer 的 div)
agent-browser snapshot -s "#selector" # 限定於 CSS 選擇器
# 互動(使用來自快照的 @refs)
agent-browser click @e1 # 點擊元素
agent-browser click @e1 --new-tab # 點擊並在新分頁中開啟
agent-browser fill @e2 "text" # 清除並輸入文字
agent-browser type @e2 "text" # 輸入而不清除
agent-browser select @e1 "option" # 選取下拉選單選項
agent-browser check @e1 # 勾選核取方塊
agent-browser press Enter # 按下按鍵
agent-browser keyboard type "text" # 在目前焦點處輸入(無需選擇器)
agent-browser keyboard inserttext "text" # 插入而不觸發鍵盤事件
agent-browser scroll down 500 # 滾動頁面
agent-browser scroll down 500 --selector "div.content" # 在特定容器內滾動
# 取得資訊
agent-browser get text @e1 # 取得元素文字
agent-browser get url # 取得目前 URL
agent-browser get title # 取得頁面標題
agent-browser get cdp-url # 取得 CDP WebSocket URL
# 等待
agent-browser wait @e1 # 等待元素
agent-browser wait --load networkidle # 等待網路閒置
agent-browser wait --url "**/page" # 等待 URL 模式
agent-browser wait 2000 # 等待毫秒數
agent-browser wait --text "Welcome" # 等待文字出現(子字串比對)
agent-browser wait --fn "!document.body.innerText.includes('Loading...')" # 等待文字消失
agent-browser wait "#spinner" --state hidden # 等待元素消失
# 下載
agent-browser download @e1 ./file.pdf # 點擊元素以觸發下載
agent-browser wait --download ./output.zip # 等待任何下載完成
agent-browser --download-path ./downloads open <url> # 設定預設下載目錄
# 視窗與裝置模擬
agent-browser set viewport 1920 1080 # 設定視窗大小(預設:1280x720)
agent-browser set viewport 1920 1080 2 # 2 倍 Retina(相同 CSS 大小,更高解析度螢幕截圖)
agent-browser set device "iPhone 14" # 模擬裝置(視窗 + 使用者代理)
# 擷取
agent-browser screenshot # 螢幕截圖至暫存目錄
agent-browser screenshot --full # 全頁螢幕截圖
agent-browser screenshot --annotate # 附註解螢幕截圖,包含編號元素標籤
agent-browser screenshot --screenshot-dir ./shots # 儲存至自訂目錄
agent-browser screenshot --screenshot-format jpeg --screenshot-quality 80
agent-browser pdf output.pdf # 另存為 PDF
# 剪貼簿
agent-browser clipboard read # 從剪貼簿讀取文字
agent-browser clipboard write "Hello, World!" # 將文字寫入剪貼簿
agent-browser clipboard copy # 複製目前選取
agent-browser clipboard paste # 從剪貼簿貼上
# 差異(比較頁面狀態)
agent-browser diff snapshot # 比較目前與最後一次快照
agent-browser diff snapshot --baseline before.txt # 比較目前與儲存的檔案
agent-browser diff screenshot --baseline before.png # 視覺像素差異
agent-browser diff url <url1> <url2> # 比較兩個頁面
agent-browser diff url <url1> <url2> --wait-until networkidle # 自訂等待策略
agent-browser diff url <url1> <url2> --selector "#main" # 限定於元素
常見模式
表單提交
agent-browser open https://example.com/signup
agent-browser snapshot -i
agent-browser fill @e1 "Jane Doe"
agent-browser fill @e2 "[email protected]"
agent-browser select @e3 "California"
agent-browser check @e4
agent-browser click @e5
agent-browser wait --load networkidle
使用驗證保險庫進行驗證(建議)
# 儲存憑證一次(使用 AGENT_BROWSER_ENCRYPTION_KEY 加密)
# 建議:透過 stdin 傳送密碼以避免暴露於 Shell 歷史記錄
cat /dev/stdin | agent-browser auth save github --url https://github.com/login --username user --password-stdin
# 使用儲存的設定檔登入(LLM 永遠看不到密碼)
agent-browser auth login github
# 列出/顯示/刪除設定檔
agent-browser auth list
agent-browser auth show github
agent-browser auth delete github
使用狀態持久化進行驗證
# 登入一次並儲存狀態
agent-browser open https://app.example.com/login
agent-browser snapshot -i
agent-browser fill @e1 "$USERNAME"
agent-browser fill @e2 "$PASSWORD"
agent-browser click @e3
agent-browser wait --url "**/dashboard"
agent-browser state save auth.json
# 在未來的工作階段中重複使用
agent-browser state load auth.json
agent-browser open https://app.example.com/dashboard
工作階段持久化
# 在瀏覽器重新啟動之間自動儲存/還原 cookies 與 localStorage
agent-browser --session-name myapp open https://app.example.com/login
# ... 登入流程 ...
agent-browser close # 狀態自動儲存至 ~/.agent-browser/sessions/
# 下次,狀態會自動載入
agent-browser --session-name myapp open https://app.example.com/dashboard
# 加密靜態狀態
export AGENT_BROWSER_ENCRYPTION_KEY=$(openssl rand -hex 32)
agent-browser --session-name secure open https://app.example.com
# 管理儲存的狀態
agent-browser state list
agent-browser state show myapp-default.json
agent-browser state clear myapp
agent-browser state clean --older-than 7
資料擷取
agent-browser open https://example.com/products
agent-browser snapshot -i
agent-browser get text @e5 # 取得特定元素文字
agent-browser get text body > page.txt # 取得所有頁面文字
# 用於解析的 JSON 輸出
agent-browser snapshot -i --json
agent-browser get text @e1 --json
平行工作階段
agent-browser --session site1 open https://site-a.com
agent-browser --session site2 open https://site-b.com
agent-browser --session site1 snapshot -i
agent-browser --session site2 snapshot -i
agent-browser session list
連線到現有 Chrome
# 自動探索已啟用遠端除錯的執行中 Chrome
agent-browser --auto-connect open https://example.com
agent-browser --auto-connect snapshot
# 或使用明確的 CDP 連接埠
agent-browser --cdp 9222 snapshot
色彩配置(深色模式)
# 透過旗標設定持久性深色模式(適用於所有頁面和新分頁)
agent-browser --color-scheme dark open https://example.com
# 或透過環境變數
AGENT_BROWSER_COLOR_SCHEME=dark agent-browser open https://example.com
# 或在工作階段期間設定(對後續指令持續有效)
agent-browser set media dark
視窗與回應式測試
# 設定自訂視窗大小(預設為 1280x720)
agent-browser set viewport 1920 1080
agent-browser screenshot desktop.png
# 測試行動版寬度版面
agent-browser set viewport 375 812
agent-browser screenshot mobile.png
# Retina/HiDPI:相同 CSS 版面,2 倍像素密度
# 螢幕截圖維持邏輯視窗大小,但內容以更高 DPI 呈現
agent-browser set viewport 1920 1080 2
agent-browser screenshot retina.png
# 裝置模擬(一次設定視窗 + 使用者代理)
agent-browser set device "iPhone 14"
agent-browser screenshot device.png
scale 參數(第 3 個引數)會設定 window.devicePixelRatio,而不會變更 CSS 版面。在測試 Retina 渲染或擷取更高解析度的螢幕截圖時使用它。
視覺化瀏覽器(除錯)
agent-browser --headed open https://example.com
agent-browser highlight @e1 # 突顯元素
agent-browser inspect # 為作用中頁面開啟 Chrome DevTools
agent-browser record start demo.webm # 錄製工作階段
agent-browser profiler start # 開始 Chrome DevTools 效能分析
agent-browser profiler stop trace.json # 停止並儲存效能分析(路徑可選)
使用 AGENT_BROWSER_HEADED=1 可透過環境變數啟用可視模式。瀏覽器擴充功能在可視和無頭模式下都能運作。
本機檔案(PDF、HTML)
# 使用 file:// URL 開啟本機檔案
agent-browser --allow-file-access open file:///path/to/document.pdf
agent-browser --allow-file-access open file:///path/to/page.html
agent-browser screenshot output.png
iOS 模擬器(Mobile Safari)
# 列出可用的 iOS 模擬器
agent-browser device list
# 在特定裝置上啟動 Safari
agent-browser -p ios --device "iPhone 16 Pro" open https://example.com
# 與桌面版相同的工作流程 - 快照、互動、重新快照
agent-browser -p ios snapshot -i
agent-browser -p ios tap @e1 # 點擊(別名為 click)
agent-browser -p ios fill @e2 "text"
agent-browser -p ios swipe up # 行動版專用手勢
# 擷取螢幕截圖
agent-browser -p ios screenshot mobile.png
# 關閉工作階段(關閉模擬器)
agent-browser -p ios close
需求: macOS 搭配 Xcode、Appium(npm install -g appium && appium driver install xcuitest)
真實裝置: 如果已預先設定,可與實體 iOS 裝置搭配使用。使用 --device "<UDID>",其中 UDID 來自 xcrun xctrace list devices。
安全性
所有安全功能均為選擇加入。預設情況下,agent-browser 對導覽、動作或輸出不施加任何限制。
內容邊界(建議用於 AI 代理)
啟用 --content-boundaries 以將頁面來源的輸出包裝在標記中,協助 LLM 區分工具輸出與不受信任的頁面內容:
export AGENT_BROWSER_CONTENT_BOUNDARIES=1
agent-browser snapshot
# 輸出:
# --- AGENT_BROWSER_PAGE_CONTENT nonce=<hex> origin=https://example.com ---
# [accessibility tree]
# --- END_AGENT_BROWSER_PAGE_CONTENT nonce=<hex> ---
網域允許清單
將導覽限制於受信任的網域。像 *.example.com 這樣的萬用字元也會符合裸網域 example.com。也會封鎖對非允許網域的子資源請求、WebSocket 和 EventSource 連線。請包含您的目標頁面所依賴的 CDN 網域:
export AGENT_BROWSER_ALLOWED_DOMAINS="example.com,*.example.org,cdn.example2.com"
agent-browser open https://example.com
# 導覽至允許清單之外的網域將會失敗
agent-browser open https://evil.com # 錯誤:導覽遭封鎖
禁止的動作
限制特定動作(用於沙盒 AI 代理):
export AGENT_BROWSER_FORBIDDEN_ACTIONS="file,keyboard"
# 現在這些動作將會失敗:
agent-browser open file:///etc/passwd # 錯誤:動作 'file' 已停用
agent-browser keyboard type "text" # 錯誤:動作 'keyboard' 已停用
動作名稱(區分大小寫):file、keyboard、clipboard、download、navigate、device、profiler、record、inspect、diff、script、cookies。
提示注入防護
export AGENT_BROWSER_MAX_SNAPSHOT_SIZE=10000 # 限制快照大小(字元數)
export AGENT_BROWSER_MAX_SNAPSHOT_DEPTH=5 # 限制快照深度(巢狀層級)
平台支援
| 平台 | 支援情況 |
|---|---|
| macOS | ✅ 完整支援 |
| Linux | ✅ 完整支援 |
| Windows | ✅ 完整支援 |
| Docker | ✅ 完整支援 |
| Codespaces | ✅ 透過無頭模式支援 |
| iOS | ✅ 在 macOS 上(模擬器 + 真實裝置) |
| Android | ✅ 透過 ADB(實驗性,請參閱 android.md) |
設定
環境變數
| 變數 | 描述 |
|---|---|
AGENT_BROWSER_HEADED | 設為 1 以啟用可視模式 |
AGENT_BROWSER_COLOR_SCHEME | dark 或 light |
AGENT_BROWSER_CONCURRENCY | 平行工作階段的限制(預設:5) |
AGENT_BROWSER_ENCRYPTION_KEY | 用於驗證保險庫和工作階段狀態的加密金鑰 |
AGENT_BROWSER_DOWNLOAD_PATH | 下載的預設目錄 |
AGENT_BROWSER_SCREENSHOT_DIR | 螢幕截圖的預設目錄 |
AGENT_BROWSER_CONTENT_BOUNDARIES | 啟用以啟動內容邊界 |
AGENT_BROWSER_ALLOWED_DOMAINS | 以逗號分隔的允許網域清單 |
AGENT_BROWSER_FORBIDDEN_ACTIONS | 以逗號分隔的禁止動作清單 |
AGENT_BROWSER_MAX_SNAPSHOT_SIZE | 快照內容的最大長度(字元數) |
AGENT_BROWSER_MAX_SNAPSHOT_DEPTH | 快照內容的最大深度(巢狀層級) |
AGENT_BROWSER_CONSOLE | 設為 1 以啟用主控台日誌記錄 |
重要平台細節
- macOS/Linux: 使用
npm、brew或cargo安裝。agent-browser install會下載獨立的 Chrome 二進位檔案。 - Windows: 使用
npm i -g agent-browser並以管理員身分執行。如果偵測不到,請設定CHROME_PATH或使用 --auto-connect。 - Docker: 需要
--cap-add=SYS_ADMIN或在無頭模式下執行。請參閱 Dockerfile 範例。 - iOS: 需要 macOS 搭配 Xcode、Appium 及 xcuitest 驅動程式。
在 Docker 中執行
FROM node:20-slim
RUN npm install -g agent-browser
RUN agent-browser install
COPY . .
CMD ["agent-browser", "open", "https://example.com"]
使用以下指令建立並執行:
docker build -t agent-browser .
docker run --cap-add=SYS_ADMIN agent-browser
或者,對於無頭模式:
docker run -e AGENT_BROWSER_HEADED=0 agent-browser
另請參閱
- authentication.md - OAuth、2FA、Cookie、Token 刷新
- android.md - Android 網頁自動化
- CONTRIBUTING.md - 貢獻指南