使用 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 upgrade 以更新至最新版本。

核心工作流程

每個瀏覽器自動化都遵循以下模式：

導航：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

狀態檔案包含明文 session 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：Session 名稱（自動儲存/還原 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：Auth Vault（憑證加密儲存，按名稱登入）

echo "$PASSWORD" | agent-browser auth save myapp --url https://app.example.com/login --username user --password-stdin
agent-browser auth login myapp

auth login 會以 load 事件導航，然後等待登入表單選擇器出現後再填寫/點擊，這在延遲的 SPA 登入畫面上更可靠。

選項 5：狀態檔案（手動儲存/載入）

# 登入後：
agent-browser state save ./auth.json
# 在未來的 session 中：
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 close --all             # 關閉所有活躍 session

# 快照
agent-browser snapshot -i             # 帶有參考的互動元素（建議使用）
agent-browser snapshot -s "#selector" # 限定 CSS 選擇器範圍

# 互動（使用來自 snapshot 的 @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 network requests                 # 檢查追蹤的請求
agent-browser network requests --type xhr,fetch  # 按資源類型過濾
agent-browser network requests --method POST   # 按 HTTP 方法過濾
agent-browser network requests --status 2xx    # 按狀態碼過濾（200, 2xx, 400-499）
agent-browser network request <requestId>      # 檢視完整的請求/回應詳情
agent-browser network route "**/api/*" --abort  # 封鎖符合的請求
agent-browser network har start                # 開始 HAR 記錄
agent-browser network har stop ./capture.har   # 停止並儲存 HAR 檔案

# 視口與裝置模擬
agent-browser set viewport 1920 1080          # 設定視口大小（預設：1280x720）
agent-browser set viewport 1920 1080 2        # 2x Retina（相同 CSS 尺寸，更高解析度螢幕截圖）
agent-browser set device "iPhone 14"          # 模擬裝置（視口 + User Agent）

# 擷取
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 stream enable           # 在自動選擇的連接埠上啟動執行時期 WebSocket 串流
agent-browser stream enable --port 9223  # 綁定特定 localhost 連接埠
agent-browser stream status           # 檢查啟用狀態、連接埠、連線和螢幕投射
agent-browser stream disable          # 停止執行時期串流並移除 .stream 元資料檔案

# 剪貼簿
agent-browser clipboard read                      # 從剪貼簿讀取文字
agent-browser clipboard write "Hello, World!"     # 寫入文字至剪貼簿
agent-browser clipboard copy                      # 複製目前選取範圍
agent-browser clipboard paste                     # 從剪貼簿貼上

# 對話框（alert, confirm, prompt, beforeunload）
# 預設情況下，alert 和 beforeunload 對話框會自動接受，因此它們永遠不會阻礙 agent。
# confirm 和 prompt 對話框仍需要明確處理。
# 使用 --no-auto-dialog 以停用自動處理。
agent-browser dialog accept              # 接受對話框
agent-browser dialog accept "my input"   # 接受帶有文字的 prompt 對話框
agent-browser dialog dismiss             # 關閉/取消對話框
agent-browser dialog status              # 檢查對話框是否目前開啟

# 差異比較（比較頁面狀態）
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"  # 限定元素範圍

串流

每個 session 都會自動在作業系統分配的連接埠上啟動一個 WebSocket 串流伺服器。使用 agent-browser stream status 查看綁定的連接埠和連線狀態。使用 stream disable 將其關閉，使用 stream enable --port <port> 以在特定連接埠上重新啟用。

批次執行

透過將字串陣列的 JSON 陣列導向 batch，可以在單次調用中執行多個命令。這可以避免在執行多步驟工作流程時，每次命令啟動所造成的程序開銷。

echo '[
  ["open", "https://example.com"],
  ["snapshot", "-i"],
  ["click", "@e1"],
  ["screenshot", "result.png"]
]' | agent-browser batch --json

# 遇到第一個錯誤時停止
agent-browser batch --bail < commands.json

當你有一個已知的命令序列且不依賴中間輸出時，請使用 batch。當你需要解析步驟之間的輸出時（例如快照以發現參考，然後進行互動），請使用單獨命令或 && 鏈式操作。

常見模式

表單提交

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

使用 Auth Vault 進行身份驗證（建議）

# 儲存憑證一次（使用 AGENT_BROWSER_ENCRYPTION_KEY 加密）
# 建議：透過 stdin 傳遞密碼，以避免暴露在 shell 歷史記錄中
echo "pass" | 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

auth login 會在使用者名稱/密碼/提交選擇器出現後才進行互動，並帶有與預設動作逾時相關的超時時間。

使用狀態持久化進行身份驗證

# 登入一次並儲存狀態
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

# 在未來的 sessions 中重複使用
agent-browser state load auth.json
agent-browser open https://app.example.com/dashboard

Session 持久化

# 在瀏覽器重啟之間自動儲存/還原 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

處理 Iframe

Iframe 內容會自動內嵌在快照中。Iframe 內的參考帶有框架上下文，因此你可以直接與它們互動。

agent-browser open https://example.com/checkout
agent-browser snapshot -i
# @e1 [heading] "Checkout"
# @e2 [Iframe] "payment-frame"
#   @e3 [input] "Card number"
#   @e4 [input] "Expiry"
#   @e5 [button] "Pay"

# 直接互動——無需切換框架
agent-browser fill @e3 "4111111111111111"
agent-browser fill @e4 "12/28"
agent-browser click @e5

# 將快照範圍限定到一個 iframe：
agent-browser frame @e2
agent-browser snapshot -i         # 僅 iframe 內容
agent-browser frame main          # 返回主框架

資料提取

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

並行 Session

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

Auto-connect 會透過 DevToolsActivePort、常見的除錯連接埠 (9222, 9229) 發現 Chrome，並在基於 HTTP 的 CDP 發現失敗時，回退到直接 WebSocket 連線。

lunrenyi/ai-agent.sh

ai-agent.sh 是什麼？

在你喜歡的 AI 中提問

說明文件

使用 agent-browser 進行瀏覽器自動化

核心工作流程

命令鏈式操作

處理身份驗證

基本命令

串流

批次執行

常見模式

表單提交

使用 Auth Vault 進行身份驗證（建議）

使用狀態持久化進行身份驗證

Session 持久化

處理 Iframe

資料提取

並行 Session

連接到現有 Chrome

色彩方案（已截斷用於翻譯）

相關技能

steipete/sag

steipete/oracle

steipete/peekaboo

mattpocock/design-an-interface

mattpocock/prototype

mattpocock/grill-me