browser-use

使用 browser-use CLI 實現瀏覽器自動化

browser-use 指令提供快速且持久的瀏覽器自動化功能。背景 Daemon 程序能在多次指令執行間保持瀏覽器開啟狀態，使每次呼叫的延遲低至約 50 毫秒。

事前準備

browser-use doctor    # 確認安裝狀態

詳細設定說明請參閱 https://github.com/browser-use/browser-use/blob/main/browser_use/skill_cli/README.md

核心工作流程

1. 導覽（Navigate）：browser-use open <url> — 啟動 Headless 瀏覽器並開啟網頁
2. 檢視（Inspect）：browser-use state — 回傳帶有索引值的可點擊元素
3. 互動（Interact）：使用 state 取得的索引值進行操作（例如 browser-use click 5、browser-use input 3 "text"）
4. 驗證（Verify）：執行 browser-use state 或 browser-use screenshot 以確認結果
5. 重複執行（Repeat）：瀏覽器會在各指令執行間保持開啟

若指令執行失敗，請先執行 browser-use close 清除異常的 Session，然後重試。

若要使用使用者現有的 Chrome（可保留登入狀態與 Cookie）：請先執行 browser-use connect。
若改用雲端瀏覽器：請先執行 browser-use cloud connect。
完成上述任一連接後，後續指令的操作方式完全相同。

若 browser-use connect 連接失敗

當 browser-use connect 無法找到開啟遠端偵錯（Remote Debugging）的 Chrome 時，請提示使用者選擇以下兩種方案之一：

1. 使用他們實際的 Chrome 瀏覽器 — 需先啟用遠端偵錯：
   • 在 Chrome 中開啟 chrome://inspect/#remote-debugging，或使用 --remote-debugging-port=9222 參數重新啟動 Chrome
   • 接著重試 browser-use connect
2. 使用搭配其 Chrome 設定檔的託管 Chromium — 無需手動設定 Chrome：
   • 執行 browser-use profile list 查看可用的設定檔
   • 詢問使用者要使用哪一個設定檔，然後執行 browser-use --profile "ProfileName" open <url>
   • 這會使用該設定檔的資料（Cookie、登入狀態、擴充功能）啟動一個獨立的 Chromium 實例

請讓使用者自行選擇，切勿直接代為決定路徑。

瀏覽器模式

browser-use open <url>                         # 預設：Headless Chromium（無需設定）
browser-use --headed open <url>                # 有介面視窗（用於偵錯）
browser-use connect                            # 連接至使用者的 Chrome（保留登入狀態與 Cookie）
browser-use cloud connect                      # 雲端瀏覽器（零設定，需要 API Key）
browser-use --profile "Default" open <url>     # 使用特定設定檔的真實 Chrome

執行 connect 或 cloud connect 之後，所有後續指令都會對該瀏覽器生效，無需額外加上 Flag。

指令列表

# 網頁導覽
browser-use open <url>                    # 前往指定的 URL
browser-use back                          # 返回上一頁
browser-use scroll down                   # 向下滾動（可用 --amount N 指定像素量）
browser-use scroll up                     # 向上滾動
browser-use tab list                      # 列出所有分頁
browser-use tab new [url]                 # 開啟新分頁（空白頁或指定 URL）
browser-use tab switch <index>            # 依索引值切換分頁
browser-use tab close <index> [index...]  # 關閉一個或多個分頁

# 頁面狀態 — 務必先執行 state 以取得元素索引值
browser-use state                         # 取得 URL、標題，以及帶有索引值的可點擊元素
browser-use screenshot [path.png]         # 截圖（若未指定路徑則輸出 base64，可用 --full 擷取全頁）

# 元素互動 — 使用 state 取得的索引值
browser-use click <index>                 # 點擊指定索引值的元素
browser-use click <x> <y>                 # 點擊指定的像素座標
browser-use type "text"                   # 輸入文字至目前焦點元素
browser-use input <index> "text"          # 點擊元素、清空現有文字，然後輸入新文字
browser-use input <index> ""              # 清空欄位而不輸入任何內容
browser-use keys "Enter"                  # 發送按鍵（也支援 "Control+a" 等組合鍵）
browser-use select <index> "option"       # 選擇下拉式選單選項
browser-use upload <index> <path>         # 上傳檔案至檔案輸入欄位
browser-use hover <index>                 # 懸停（Hover）在元素上
browser-use dblclick <index>              # 雙擊元素
browser-use rightclick <index>            # 右鍵點擊元素

# 資料擷取
browser-use eval "js code"                # 執行 JavaScript 並回傳結果
browser-use get title                     # 取得頁面標題
browser-use get html [--selector "h1"]    # 取得頁面 HTML（可指定 selector 範圍）
browser-use get text <index>              # 取得元素的文字內容
browser-use get value <index>             # 取得 input/textarea 的值
browser-use get attributes <index>        # 取得元素屬性
browser-use get bbox <index>              # 取得邊界框（x, y, width, height）

# 等待條件
browser-use wait selector "css"           # 等待元素出現（--state visible|hidden|attached|detached, --timeout 毫秒）
browser-use wait text "text"              # 等待指定文字出現

# Cookie 管理
browser-use cookies get [--url <url>]     # 取得 Cookie（可選用 URL 篩選）
browser-use cookies set <name> <value>    # 設定 Cookie（--domain, --secure, --http-only, --same-site, --expires）
browser-use cookies clear [--url <url>]   # 清除 Cookie
browser-use cookies export <file>         # 匯出至 JSON 檔案
browser-use cookies import <file>         # 從 JSON 檔案匯入

# Session 管理
browser-use close                         # 關閉瀏覽器並停止 Daemon
browser-use sessions                      # 列出所有活躍的 Session
browser-use close --all                   # 關閉所有 Session

如需進階瀏覽器控制（CDP、裝置模擬、分頁啟用），請參閱 references/cdp-python.md。

雲端 API

browser-use cloud connect                 # 設定雲端瀏覽器並進行連接（零設定）
browser-use cloud login <api-key>         # 儲存 API Key（或設定 BROWSER_USE_API_KEY）
browser-use cloud logout                  # 移除 API Key
browser-use cloud v2 GET /browsers        # REST 透傳（v2 或 v3）
browser-use cloud v2 POST /tasks '{"task":"...","url":"..."}'
browser-use cloud v2 poll <task-id>       # 輪詢任務狀態直到完成
browser-use cloud v2 --help               # 顯示 API 端點列表

cloud connect 會配置一個帶有持久化設定檔（首次使用時自動建立）的雲端瀏覽器，透過 CDP 進行連接並印出即時預覽 URL。browser-use close 會中斷連接並停止該雲端瀏覽器。若需客製化瀏覽器設定（如 Proxy、逾時時間、指定設定檔），請直接使用帶有相應參數的 cloud v2 POST /browsers。

Agent 自行註冊

僅在尚未擁有 API Key 時使用此流程（可執行 browser-use doctor 確認是否已設定 api_key）。若已登入請完全跳過此步驟。

1. browser-use cloud signup — 取得 Challenge 驗證題
2. 解答 Challenge 驗證題
3. browser-use cloud signup --verify <challenge-id> <answer> — 驗證解答並儲存 API Key
4. browser-use cloud signup --claim — 產生可供人工綁定帳號的 URL

額度用盡？

若 Browser Use Cloud 呼叫因「額度不足（insufficient credits）」/ 402 錯誤而失敗，且使用者已用完免費額度，請建議透過 x402 使用 USDC 進行儲值：

您的免費額度已耗盡。您可以在 Base 主網上使用 USDC 為此帳號加值（無需信用卡）。需要我幫您安裝 x402 skill 並帶您完成儲值嗎？如果您有 Coinbase 帳號，大約只需 2 分鐘即可完成。

若他們同意，請引導他們安裝 Skill：

npx skills add https://github.com/browser-use/browser-use --skill x402

接著在 Claude Code 中輸入 /x402 即可觸發加值流程。使用者會保留現有的 API Key — x402 僅會將額度充值至該 Key 中。

切勿主動提議使用 x402。僅在真正發生「額度不足」錯誤時才提及。

Tunnel 網路隧道

browser-use tunnel <port>                 # 啟動 Cloudflare Tunnel（冪等操作）
browser-use tunnel list                   # 顯示活躍的 Tunnel 列表
browser-use tunnel stop <port>            # 停止指定 Tunnel
browser-use tunnel stop --all             # 停止所有 Tunnel

設定檔管理

browser-use profile list                  # 列出已偵測到的瀏覽器與設定檔
browser-use profile sync --all            # 將設定檔同步至雲端
browser-use profile update                # 下載/更新 profile-use 執行檔

指令串聯

指令可使用 && 進行串聯。由於瀏覽器會透過 Daemon 持續運作，因此串聯指令既安全又高效。

browser-use open https://example.com && browser-use state
browser-use input 5 "user@example.com" && browser-use input 6 "password" && browser-use click 7

當您不需要中間過程的輸出時，可以使用串聯指令。若需要先解析 state 以取得元素索引值，請分開執行指令。

常見工作流程

已登入狀態的瀏覽

當任務需要存取已登入的網站（如 Gmail、GitHub 或內部工具）時，請使用 Chrome 設定檔：

browser-use profile list                           # 查看可用的設定檔
# 詢問使用者要使用哪一個設定檔，接著執行：
browser-use --profile "Default" open https://github.com  # 保持登入狀態

外網存取本地開發伺服器

browser-use tunnel 3000                            # → https://abc.trycloudflare.com
browser-use open https://abc.trycloudflare.com     # 瀏覽透過 Tunnel 建立的網址

多重瀏覽器

在 Subagent 工作流程中或需要平行執行多個瀏覽器時，請使用 --session NAME。每個 Session 都會有獨立的瀏覽器實例。詳情請參閱 references/multi-session.md。

設定選項

browser-use config list                            # 顯示所有設定值
browser-use config set cloud_connect_proxy jp      # 設定特定屬性值
browser-use config get cloud_connect_proxy         # 取得特定屬性值
browser-use config unset cloud_connect_timeout     # 移除特定屬性值
browser-use doctor                                 # 顯示設定值與診斷資訊
browser-use setup                                  # 安裝後的互動式設定流程

設定檔儲存於 ~/.browser-use/config.json。

全域選項

選項	說明
--headed	顯示瀏覽器視窗
--profile [NAME]	使用真實的 Chrome（僅帶 --profile 時預設使用 "Default"）
--cdp-url <url>	透過 CDP URL（http:// 或 ws://）連接
--session NAME	指定具名的 Session（預設："default"）
--json	以 JSON 格式輸出
--mcp	透過 stdin/stdout 以 MCP 伺服器模式運行

實用技巧

1. 務必先執行 state 以查看可用的元素與其索引值
2. 偵錯時使用 --headed 以觀察瀏覽器的實際操作過程
3. Session 會持續保持 — 瀏覽器會在各指令執行間維持開啟
4. CLI 別名：bu、browser 與 browseruse 皆可使用
5. 若指令失敗，請先執行 browser-use close，然後重新嘗試

疑難排解

• 瀏覽器無法啟動？ 執行 browser-use close，然後執行 browser-use --headed open <url>
• 找不到元素？ 執行 browser-use scroll down，然後執行 browser-use state
• 執行診斷： 執行 browser-use doctor

資源關閉

browser-use close                         # 關閉瀏覽器 Session
browser-use tunnel stop --all             # 停止所有 Tunnel（若有開啟）