remote-browser

沙箱代理程式的瀏覽器自動化

此技能適用於在沙箱遠端機器（雲端 VM、CI、程式碼代理程式）上執行，且需要控制無頭瀏覽器的代理程式。

前置需求

browser-use doctor    # 驗證安裝

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

核心工作流程

1. 導航：browser-use open <url> — 若需要則啟動無頭瀏覽器
2. 檢查：browser-use state — 回傳可點擊元素及其索引
3. 互動：使用 state 回傳的索引（browser-use click 5、browser-use input 3 "text"）
4. 驗證：browser-use state 或 browser-use screenshot 確認結果
5. 重複：瀏覽器在指令之間保持開啟
6. 清理：完成後執行 browser-use close

瀏覽器模式

browser-use open <url>                                    # 預設：無頭 Chromium
browser-use cloud connect                                 # 佈建雲端瀏覽器並連線
browser-use --connect open <url>                          # 透過 CDP 自動發現執行中的 Chrome
browser-use --cdp-url ws://localhost:9222/... open <url>  # 透過 CDP URL 連線

指令

# 導航
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 keys "Enter"                  # 傳送鍵盤按鍵（也支援 "Control+a" 等）
browser-use select <index> "option"       # 選取下拉選單選項
browser-use upload <index> <path>         # 上傳檔案至檔案輸入框
browser-use hover <index>                 # 滑鼠懸停於元素
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（或限定於選擇器）
browser-use get text <index>              # 元素文字內容
browser-use get value <index>             # 輸入框/文字區域的值
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 匯入

# Python — 持續性工作階段，可存取瀏覽器
browser-use python "code"                 # 執行 Python（變數在多次呼叫間持續存在）
browser-use python --file script.py       # 執行檔案
browser-use python --vars                 # 顯示已定義的變數
browser-use python --reset                # 清除命名空間

# 工作階段
browser-use close                         # 關閉瀏覽器並停止背景程序
browser-use sessions                      # 列出啟用中的工作階段
browser-use close --all                   # 關閉所有工作階段

Python 的 browser 物件提供：browser.url、browser.title、browser.html、browser.goto(url)、browser.back()、browser.click(index)、browser.type(text)、browser.input(index, text)、browser.keys(keys)、browser.upload(index, path)、browser.screenshot(path)、browser.scroll(direction, amount)、browser.wait(seconds)。

隧道

透過 Cloudflare 隧道將本地開發伺服器暴露給瀏覽器。

browser-use tunnel <port>                 # 啟動隧道（冪等）
browser-use tunnel list                   # 顯示啟用中的隧道
browser-use tunnel stop <port>            # 停止隧道
browser-use tunnel stop --all             # 停止所有隧道

指令串聯

指令可使用 && 串聯。瀏覽器透過背景程序持續存在，因此串聯安全且高效。

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 以取得索引，則分開執行。

常見工作流程

暴露本地開發伺服器

python -m http.server 3000 &                      # 啟動開發伺服器
browser-use tunnel 3000                            # → https://abc.trycloudflare.com
browser-use open https://abc.trycloudflare.com     # 瀏覽隧道

隧道獨立於瀏覽器工作階段，並在 browser-use close 後持續存在。

多代理程式（--connect 模式）

多個代理程式可透過 --connect 共享一個瀏覽器。每個代理程式擁有自己的分頁，其他代理程式無法干擾。

設定：先註冊一次，然後在每個 --connect 指令中傳入索引：

INDEX=$(browser-use register)                    # → 輸出 "1"
browser-use --connect $INDEX open <url>          # 在代理程式的分頁中導航
browser-use --connect $INDEX state               # 從代理程式的分頁取得狀態
browser-use --connect $INDEX click <element>     # 在代理程式的分頁中點擊

• 分頁鎖定：當代理程式修改分頁（點擊、輸入、導航）時，該分頁會被鎖定給該代理程式。其他代理程式嘗試修改同一分頁時會收到錯誤。
• 唯讀存取：state、screenshot、get 和 wait 指令可在任何分頁上執行，不受鎖定影響。
• 代理程式工作階段在 5 分鐘無活動後過期。再次執行 browser-use register 以取得新索引。

全域選項

選項	說明
--headed	顯示瀏覽器視窗
--connect	透過 CDP 自動發現執行中的 Chrome
--cdp-url <url>	透過 CDP URL 連線（http:// 或 ws://）
--session NAME	指定命名工作階段（預設："default"）
--json	以 JSON 格式輸出

提示

1. 務必先執行 state 以查看可用元素及其索引
2. 工作階段持續存在 — 瀏覽器在指令之間保持開啟，直到您關閉它
3. 隧道獨立 — 它們在 browser-use close 後持續存在
4. tunnel 是冪等的 — 對相同連接埠再次呼叫會回傳現有的 URL

疑難排解

• 瀏覽器無法啟動？ 執行 browser-use close 後重試。執行 browser-use doctor 檢查。
• 找不到元素？ 執行 browser-use scroll down 再執行 browser-use state
• 隧道無法運作？ 執行 which cloudflared 檢查，browser-use tunnel list 查看啟用中的隧道

清理

browser-use close                         # 關閉瀏覽器工作階段
browser-use tunnel stop --all             # 停止所有隧道（若有的話）