<!-- Source: https://hermesbible.com/docs/user-guide/features/browser -->

Section: Core Features · URL: https://hermesbible.com/docs/user-guide/features/browser

瀏覽器自動化

Hermes Agent 包含完整的瀏覽器自動化工具集，支援多種後端選項：

• Browserbase 雲端模式 — 透過 Browserbase 使用託管雲端瀏覽器與反 bot 工具
• Browser Use 雲端模式 — 透過 Browser Use 作為替代的雲端瀏覽器供應商
• Firecrawl 雲端模式 — 透過 Firecrawl 使用內建爬取功能的雲端瀏覽器
• Camofox 本地模式 — 透過 Camofox 實現本地反偵測瀏覽（基於 Firefox 的指紋偽造）
• 本地 Chromium 系列 CDP — 使用 /browser connect 將瀏覽器工具連接到你自己的 Chrome、Brave、Chromium 或 Edge 實例
• 本地瀏覽器模式 — 透過 agent-browser CLI 與本地 Chromium 安裝

在所有模式中，agent 都可以瀏覽網站、與頁面元素互動、填寫表單及提取資訊。

概覽

頁面以無障礙樹（文字快照）表示，非常適合 LLM agent 使用。互動元素會獲得 ref ID（如 @e1、@e2），agent 據此進行點擊和輸入操作。

核心功能：

• 多供應商雲端執行 — Browserbase、Browser Use 或 Firecrawl — 無需本地瀏覽器
• 本地 Chromium 系列整合 — 透過 CDP 連接到正在運行的 Chrome、Brave、Chromium 或 Edge 瀏覽器
• 內建隱匿功能 — 隨機指紋、CAPTCHA 解決、住宅代理（Browserbase）
• Session 隔離 — 每個任務獲得獨立的瀏覽器 session
• 自動清理 — 停用超時的 session 會被關閉
• 視覺分析 — 截圖 + AI 分析實現視覺理解

設定

提示 — Nous 訂閱者

如果你有付費的 Nous Portal 訂閱，可以透過 Tool Gateway 使用瀏覽器自動化，無需單獨的 API 金鑰。新安裝可執行 hermes setup --portal 登入並一次啟用所有 gateway 工具；既有的安裝可透過 hermes model 或 hermes tools 選擇 Nous Subscription 作為瀏覽器供應商。

Browserbase 雲端模式

要使用 Browserbase 託管的雲端瀏覽器，新增：

# Add to ~/.hermes/.env
BROWSERBASE_API_KEY=***
BROWSERBASE_PROJECT_ID=your-project-id-here

前往 browserbase.com 取得你的憑證。

Browser Use 雲端模式

要使用 Browser Use 作為你的雲端瀏覽器供應商，新增：

# Add to ~/.hermes/.env
BROWSER_USE_API_KEY=***

前往 browser-use.com 取得你的 API 金鑰。Browser Use 透過其 REST API 提供雲端瀏覽器。如果同時設定了 Browserbase 和 Browser Use 的憑證，Browserbase 優先。

Firecrawl 雲端模式

要使用 Firecrawl 作為你的雲端瀏覽器供應商，新增：

# Add to ~/.hermes/.env
FIRECRAWL_API_KEY=fc-***

前往 firecrawl.dev 取得你的 API 金鑰。然後選擇 Firecrawl 作為你的瀏覽器供應商：

hermes setup tools
# → Browser Automation → Firecrawl

選用設定：

# Self-hosted Firecrawl instance (default: https://api.firecrawl.dev)
FIRECRAWL_API_URL=http://localhost:3002

# Session TTL in seconds (default: 300)
FIRECRAWL_BROWSER_TTL=600

混合路由：公網 URL 用雲端、區域網路/localhost 用本地

當設定雲端供應商時，Hermes 會自動啟動本地 Chromium sidecar，用於解析到私有/回環/區域網路位址的 URL（localhost、127.0.0.1、192.168.x.x、10.x.x.x、172.16-31.x.x、*.local、*.lan、*.internal、IPv6 回環 ::1、link-local 169.254.x.x）。公開 URL 在同一對話中繼續使用雲端供應商。

這解決了常見的「我正在本地開發但使用 Browserbase」的工作流程 — agent 可以截取你 http://localhost:3000 上的 Dashboard 畫面，同時爬取 https://github.com，無需切換供應商或關閉 SSRF 防護。雲端供應商永遠不會看到私有 URL。

此功能預設啟用。要停用它（所有 URL 都傳送到設定的雲端供應商，如同之前）：

# ~/.hermes/config.yaml
browser:
  cloud_provider: browserbase
  auto_local_for_private_urls: false

停用自動路由後，私有 URL 會被拒絕，並回傳 "Blocked: URL targets a private or internal address"，除非你同時設定 browser.allow_private_urls: true（這會讓雲端供應商嘗試訪問 — 通常不會成功，因為 Browserbase 等無法連到你的區域網路）。

需求：本地 sidecar 使用與純本地模式相同的 agent-browser CLI，因此你需要安裝它（hermes setup tools → Browser Automation 會自動安裝）。從公開 URL 到私有位址的導航後重新導向仍然會被封鎖（你無法使用重新導向到內部位址的技巧透過公開路徑連到你的區域網路）。

Camofox 本地模式

Camofox 是一個自架的 Node.js 伺服器，封裝了 Camoufox（一個帶有 C++ 指紋偽造的 Firefox 分支）。它提供無需雲端依賴的本地反偵測瀏覽。

# Clone the Camofox browser server first
git clone https://github.com/jo-inc/camofox-browser
cd camofox-browser

# Build and start with Docker using the default container settings
# (auto-detects arch: aarch64 on M1/M2, x86_64 on Intel)
make up

# Stop and remove the default container
make down

# Force a clean rebuild (for example, after upgrading VERSION/RELEASE)
make reset

# Just download binaries without building
make fetch

# Override arch or version explicitly
make up ARCH=x86_64
make up VERSION=135.0.1 RELEASE=beta.24

make up 會立即啟動預設容器。如果你需要自訂運行時設定，例如較大的 Node heap、VNC 或持久化設定檔目錄，請先建構映像，然後自行執行：

# Build the image without starting the default container
make build

# Start with persistence, VNC live view, and a larger Node heap
mkdir -p ~/.camofox-docker
docker run -d \
  --name camofox-browser \
  --restart unless-stopped \
  -p 9377:9377 \
  -p 6080:6080 \
  -p 5901:5900 \
  -e CAMOFOX_PORT=9377 \
  -e ENABLE_VNC=1 \
  -e VNC_BIND=0.0.0.0 \
  -e VNC_RESOLUTION=1920x1080 \
  -e MAX_OLD_SPACE_SIZE=2048 \
  -v ~/.camofox-docker:/root/.camofox \
  camofox-browser:135.0.1-aarch64

啟用 VNC 後，瀏覽器會以 headed 模式運行，你可以透過瀏覽器在 http://localhost:6080（noVNC）即時觀看。你也可以使用原生 VNC 客戶端連接到 localhost:5901。

如果你之前執行過 make up，在啟動自訂容器之前請先停止並移除預設容器：

make down
# then run the custom docker run command above

然後在 ~/.hermes/.env 中設定：

CAMOFOX_URL=http://localhost:9377

如果 Camofox 在 Docker 中運行，而你希望它開啟從主機提供的 Web 應用程式，請啟用 loopback 重寫。CAMOFOX_URL 仍應指向主機發佈的控制 API，但像 http://127.0.0.1:3000 這樣的頁面 URL 必須從容器內部以 http://host.docker.internal:3000 開啟：

# ~/.hermes/config.yaml
browser:
  camofox:
    rewrite_loopback_urls: true
    loopback_host_alias: host.docker.internal  # default; use a LAN IP if needed

等效的環境變數：

CAMOFOX_REWRITE_LOOPBACK_URLS=true
CAMOFOX_LOOPBACK_HOST_ALIAS=host.docker.internal

重寫僅適用於帶有 loopback 主機的頁面導覽 URL（localhost、127.0.0.1、::1）。它不會變更 CAMOFOX_URL。對於非 Docker 的 Camofox 安裝，請將此功能保持停用，因為瀏覽器已經在主機上運行，loopback URL 是正確的。

或者透過 hermes tools → Browser Automation → Camofox 進行設定。

當設定 CAMOFOX_URL 時，所有瀏覽器工具會自動透過 Camofox 路由，而非 Browserbase 或 agent-browser。

持久化瀏覽器 session

預設情況下，每個 Camofox session 都會獲得隨機身份 — cookie 和登入狀態不會在 agent 重啟後保留。要啟用持久化瀏覽器 session，請在 ~/.hermes/config.yaml 中新增：

browser:
  camofox:
    managed_persistence: true

然後完全重啟 Hermes 以載入新的設定。

警告 — 嵌套路徑很重要

Hermes 讀取的是 browser.camofox.managed_persistence，不是頂層的 managed_persistence。常見的錯誤是這樣寫：

# ❌ 錯誤 — Hermes 會忽略這個
managed_persistence: true

如果 flag 放在錯誤的路徑，Hermes 會靜默回退到隨機的臨時 userId，你的登入狀態會在每次 session 中遺失。

Hermes 做了什麼

• 發送確定性的、設定檔範圍的 userId 給 Camofox，使伺服器可以跨 session 重用相同的 Firefox 設定檔。
• 在清理時跳過伺服器端的 context 銷毀，使 cookie 和登入狀態在 agent 任務之間保留。
• 將 userId 限定在活躍的 Hermes 設定檔範圍內，使不同的 Hermes 設定檔獲得不同的瀏覽器設定檔（設定檔隔離）。

Hermes 沒有做什麼

• 它不會強制 Camofox 伺服器持久化。Hermes 只是發送穩定的 userId；伺服器必須透過將該 userId 對應到持久化的 Firefox 設定檔目錄來遵守它。
• 如果你的 Camofox 伺服器建構版本將每個請求都視為臨時的（例如總是呼叫 browser.newContext() 而不載入已儲存的設定檔），Hermes 無法讓這些 session 持久化。請確保你運行的是支援基於 userId 的設定檔持久化的 Camofox 建構版本。

驗證是否正常運作

1. 啟動 Hermes 和你的 Camofox 伺服器。
2. 在瀏覽器任務中開啟 Google（或任何登入網站）並手動登入。
3. 正常結束瀏覽器任務。
4. 啟動新的瀏覽器任務。
5. 再次開啟同一個網站 — 你應該仍保持登入狀態。

如果第 5 步讓你登出了，表示 Camofox 伺服器沒有遵守穩定的 userId。請再次確認你的設定路徑、確認在編輯 config.yaml 後完全重啟了 Hermes，並驗證你的 Camofox 伺服器版本支援持久化的 per-user 設定檔。

狀態儲存位置

Hermes 從設定檔範圍的目錄 ~/.hermes/browser_auth/camofox/（或非預設設定檔的 $HERMES_HOME 下的對應目錄）推導出穩定的 userId。實際的瀏覽器設定檔資料儲存在 Camofox 伺服器端，以該 userId 為鍵。要完全重置持久化設定檔，請在 Camofox 伺服器上清除它，並移除對應 Hermes 設定檔的狀態目錄。

外部管理的 Camofox session

當另一個應用程式驅動可見的 Camofox 瀏覽器（桌面助理、自訂整合、另一個 agent）時，請設定 Hermes 在該相同身份內運行，而非啟動自己的隔離設定檔。

三個旋鈕控制行為：

環境變數優先於 config.yaml。兩種形式都可以：

browser:
  camofox:
    user_id: shared-camofox
    session_key: visible-tab
    adopt_existing_tab: true

CAMOFOX_USER_ID=shared-camofox
CAMOFOX_SESSION_KEY=visible-tab
CAMOFOX_ADOPT_EXISTING_TAB=true

設定 user_id 後的變化：

• Hermes 在任務結束時跳過破壞性清理（與 managed_persistence: true 相同）。其他應用程式的分頁/cookie/設定檔會保留。
• Hermes 不會呼叫 DELETE /sessions/<user_id> — 該端點會清除所有使用者資料，如果觸發會摧毀外部應用程式的 session。

分頁採用的運作方式（當 adopt_existing_tab: true 時）：

1. 在 process 啟動後的首次瀏覽器工具呼叫中，Hermes 發出 GET /tabs?userId=<user_id>（5 秒超時）。
2. 如果回應中有任何分頁的 listItemId == session_key，Hermes 採用該群組中最近建立的分頁。
3. 否則，Hermes 採用為該使用者最近建立的分頁（任何 listItemId）。
4. 如果沒有分頁存在或請求失敗，Hermes 在下一次操作時回退到建立新分頁。

採用僅在 tab_id 被填入之前觸發。如果外部應用程式在執行中關閉了被採用的分頁，下一次瀏覽器工具呼叫會顯示 Camofox 錯誤 — Hermes 不會在每次呼叫時重新輪詢新分頁。

**選擇 session_key：**如果你希望 Hermes 可靠地附加到特定的現有分頁，請將 session_key 設定為外部應用程式建立時使用的 listItemId。如果你不設定 session_key 只設定 user_id，Hermes 會生成 per-task 的 session_key（task_<id>）— Hermes 會與外部應用程式共用 cookie 和設定檔，但會在旁邊開啟自己的分頁而非重用。

**並行注意事項：**外部應用程式和 Hermes 可以同時驅動同一個 Camofox userId，但 Camofox 不會在客戶端之間協調 per-tab 的焦點。請在應用程式層級協調所有權（例如外部應用程式在 Hermes 運行時暫停）。

VNC 即時檢視

當 Camofox 以 headed 模式運行（帶有可見的瀏覽器視窗）時，它會在 health check 回應中暴露 VNC 連接埠。Hermes 會自動發現並在導覽回應中包含 VNC URL，使 agent 可以分享連結讓你即時觀看瀏覽器。

透過 CDP 連接本地 Chromium 系列瀏覽器（/browser connect）

除了雲端供應商，你還可以透過 Chrome DevTools Protocol（CDP）將 Hermes 瀏覽器工具附加到你自己正在運行的 Chrome、Brave、Chromium 或 Edge 實例。這在你想即時觀看 agent 的操作、與需要你自己的 cookie/session 的頁面互動，或避免雲端瀏覽器費用時很有用。

注意

/browser connect 是一個互動式 CLI 斜線命令 — 它不會被 gateway 派發。如果你嘗試在 WebUI、Telegram、Discord 或其他 gateway 聊天中執行它，訊息會作為純文字發送到 agent，命令不會執行。請從終端機啟動 Hermes（hermes 或 hermes chat）並在那裡執行 /browser connect。

在 CLI 中使用：

/browser connect                 # Auto-launch/connect to a local Chromium-family browser at http://127.0.0.1:9222
/browser connect ws://host:port  # Connect to a specific CDP endpoint
/browser status                  # Check current connection
/browser disconnect              # Detach and return to cloud/local mode

如果瀏覽器尚未啟用遠端除錯，Hermes 會嘗試自動啟動支援的 Chromium 系列瀏覽器並帶有 --remote-debugging-port=9222。偵測包括 Brave、Google Chrome、Chromium 和 Microsoft Edge，以及常見的 Linux 安裝路徑如 /opt/brave-bin/brave 和 /snap/bin/brave。

提示

要手動啟動帶有 CDP 的 Chromium 系列瀏覽器，請使用專用的 user-data-dir，以便即使瀏覽器已以你的正常設定檔運行，除錯埠也能實際啟動：

# Linux — Brave
brave-browser \
  --remote-debugging-port=9222 \
  --user-data-dir=$HOME/.hermes/chrome-debug \
  --no-first-run \
  --no-default-browser-check &

# Linux — Google Chrome
google-chrome \
  --remote-debugging-port=9222 \
  --user-data-dir=$HOME/.hermes/chrome-debug \
  --no-first-run \
  --no-default-browser-check &

# macOS — Brave
"/Applications/Brave Browser.app/Contents/MacOS/Brave Browser" \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/.hermes/chrome-debug" \
  --no-first-run \
  --no-default-browser-check &

# macOS — Google Chrome
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/.hermes/chrome-debug" \
  --no-first-run \
  --no-default-browser-check &

然後啟動 Hermes CLI 並執行 /browser connect。

**為什麼需要 --user-data-dir？**沒有它的話，在常規實例已經運行的情況下啟動 Chromium 系列瀏覽器，通常會在現有 process 上開啟新視窗 — 而該現有 process 並非以 --remote-debugging-port 啟動的，所以 9222 埠永遠不會開啟。專用的 user-data-dir 會強制啟動一個新的瀏覽器 process，使除錯埠實際監聽。--no-first-run --no-default-browser-check 會跳過新設定檔的首次啟動精靈。

透過 CDP 連接後，所有瀏覽器工具（browser_navigate、browser_click 等）會在你的即時瀏覽器實例上運行，而非啟動雲端 session。

WSL2 + Windows Chrome：優先使用 MCP 而非 /browser connect

如果 Hermes 在 WSL2 中運行，而你想控制的 Chrome 視窗在 Windows 主機上，/browser connect 通常不是最佳方案。

原因：

• /browser connect 需要 Hermes 本身能連到可用的 CDP 端點
• 現代 Chrome 的 live-debugging session 通常暴露一個主機本地端點，無法像經典的 9222 埠那樣從 WSL 直接連接
• 即使 Windows Chrome 可以除錯，最乾淨的整合方式通常是讓 Windows 端的瀏覽器 MCP server 附加到 Chrome，然後讓 Hermes 與該 MCP server 通訊

對於這種設定，請優先透過 Hermes MCP 支援使用 chrome-devtools-mcp。

實用設定請參閱 MCP 指南：

• 在 Hermes 中使用 MCP

本地瀏覽器模式

如果你沒有設定任何雲端憑證且不使用 /browser connect，Hermes 仍然可以透過 agent-browser 驅動的本地 Chromium 安裝使用瀏覽器工具。

選用環境變數

# Residential proxies for better CAPTCHA solving (default: "true")
BROWSERBASE_PROXIES=true

# Advanced stealth with custom Chromium — requires Scale Plan (default: "false")
BROWSERBASE_ADVANCED_STEALTH=false

# Session reconnection after disconnects — requires paid plan (default: "true")
BROWSERBASE_KEEP_ALIVE=true

# Custom session timeout in seconds (max 21600 = 6 hours) (default: project default)
# Examples: 600 (10min), 1800 (30min), 21600 (6h max)
BROWSERBASE_SESSION_TIMEOUT=1800

# Inactivity timeout before auto-cleanup in seconds (default: 120)
BROWSER_INACTIVITY_TIMEOUT=120

# Extra Chromium launch flags (comma- or newline-separated). Hermes auto-injects
# `--no-sandbox,--disable-dev-shm-usage` when it detects root or AppArmor-restricted
# unprivileged user namespaces (Ubuntu 23.10+, DGX Spark, many container images),
# so most users don't need to set this. Set it manually only if you need a flag
# Hermes doesn't add automatically; setting it disables the auto-injection.
AGENT_BROWSER_ARGS=--no-sandbox

安裝 agent-browser CLI

npm install -g agent-browser
# Or install locally in the repo:
npm install

資訊

browser 工具集必須包含在你的設定的 toolsets 列表中，或透過 hermes config set toolsets '["hermes-cli", "browser"]' 啟用。

可用工具

browser_navigate

導覽到指定 URL。必須在任何其他瀏覽器工具之前呼叫。初始化 Browserbase session。

Navigate to https://github.com/NousResearch

提示

對於簡單的資訊檢索，優先使用 web_search 或 web_extract — 它們更快且更便宜。當你需要與頁面互動（點擊按鈕、填寫表單、處理動態內容）時，才使用瀏覽器工具。

browser_snapshot

取得當前頁面無障礙樹的文字快照。回傳帶有 ref ID 的互動元素，如 @e1、@e2，供 browser_click 和 browser_type 使用。

• full=false（預設）：僅顯示互動元素的精簡視圖
• full=true：完整的頁面內容

超過 8000 字元的快照會自動由 LLM 摘要。

browser_click

點擊快照中由 ref ID 識別的元素。

Click @e5 to press the "Sign In" button

browser_type

在輸入欄位中輸入文字。先清除欄位，然後輸入新文字。

Type "hermes agent" into the search field @e3

browser_scroll

上下捲動頁面以顯示更多內容。

Scroll down to see more results

browser_press

按下鍵盤按鍵。適用於提交表單或導覽。

Press Enter to submit the form

支援的按鍵：Enter、Tab、Escape、ArrowDown、ArrowUp 等。

browser_back

導覽回瀏覽器歷史中的上一頁。

browser_get_images

列出當前頁面上的所有圖片及其 URL 和替代文字。適用於尋找需要分析的圖片。

browser_vision

截取螢幕截圖並使用視覺 AI 進行分析。當文字快照無法捕捉重要的視覺資訊時使用 — 特別適用於 CAPTCHA、複雜佈局或視覺驗證挑戰。

截圖會持久化儲存，檔案路徑會連同 AI 分析一起回傳。在訊息平台（Telegram、Discord、Slack、WhatsApp）上，你可以要求 agent 分享截圖 — 它會透過 MEDIA: 機制作為原生照片附件發送。

What does the chart on this page show?

截圖儲存在 ~/.hermes/cache/screenshots/ 中，24 小時後自動清理。

browser_console

取得當前頁面的瀏覽器控制台輸出（log/warn/error 訊息）和未捕獲的 JavaScript 異常。對於偵測不會出現在無障礙樹中的靜態 JS 錯誤至關重要。

Check the browser console for any JavaScript errors

使用 clear=True 在讀取後清除控制台，以便後續呼叫僅顯示新訊息。

browser_console 在帶有 expression 參數呼叫時還會執行 JavaScript — 與 DevTools console 相同的形式，結果會被解析回傳（JSON 序列化的物件變成 dict；原始值保持原始類型）。

browser_console(expression="document.querySelector('h1').textContent")
browser_console(expression="JSON.stringify(performance.timing)")

當當前 session 有活躍的 CDP supervisor 時（對於針對 CDP 相容後端執行過 browser_navigate 的任何 session 都是如此），執行會透過 supervisor 的持久化 WebSocket — 無子 process 啟動成本。否則回退到標準的 agent-browser CLI 路徑。兩種方式的行為相同；只有延遲不同。

browser_cdp

原生 Chrome DevTools Protocol 直通 — 為其他工具未涵蓋的瀏覽器操作提供的逃生艙口。用於原生對話框處理、iframe 範圍執行、cookie/網路控制，或 agent 需要的任何 CDP 動詞。

僅在 session 開始時可連接到 CDP 端點時可用 — 意味著 /browser connect 已附加到正在運行的 Chrome、Brave、Chromium 或 Edge 瀏覽器，或 config.yaml 中設定了 browser.cdp_url。預設的本地 agent-browser 模式、Camofox 和雲端供應商（Browserbase、Browser Use、Firecrawl）目前不會向此工具暴露 CDP — 雲端供應商有 per-session 的 CDP URL，但即時 session 路由是後續功能。

**CDP 方法參考：**https://chromedevtools.github.io/devtools-protocol/ — agent 可以 web_extract 特定方法的頁面來查詢參數和回傳格式。

常見模式：

# List tabs (browser-level, no target_id)
browser_cdp(method="Target.getTargets")

# Handle a native JS dialog on a tab
browser_cdp(method="Page.handleJavaScriptDialog",
            params={"accept": true, "promptText": ""},
            target_id="<tabId>")

# Evaluate JS in a specific tab
browser_cdp(method="Runtime.evaluate",
            params={"expression": "document.title", "returnByValue": true},
            target_id="<tabId>")

# Get all cookies
browser_cdp(method="Network.getAllCookies")

瀏覽器級方法（Target.*、Browser.*、Storage.*）省略 target_id。頁面級方法（Page.*、Runtime.*、DOM.*、Emulation.*）需要來自 Target.getTargets 的 target_id。每個無狀態呼叫是獨立的 — session 不會在呼叫之間持續。

**跨來源 iframe：**傳入 frame_id（來自 browser_snapshot.frame_tree.children[]，其中 is_oopif=true）可透過 supervisor 的即時 session 將 CDP 呼叫路由到該 iframe。這是讓 Runtime.evaluate 在 Browserbase 上的跨來源 iframe 中運作的方式，因為無狀態的 CDP 連線會遇到簽署 URL 過期的問題。範例：

browser_cdp(
  method="Runtime.evaluate",
  params={"expression": "document.title", "returnByValue": True},
  frame_id="<frame_id from browser_snapshot>",
)

同來源的 iframe 不需要 frame_id — 改從頂層的 Runtime.evaluate 使用 document.querySelector('iframe').contentDocument。

browser_dialog

回應原生 JS 對話框（alert / confirm / prompt / beforeunload）。在此工具存在之前，對話框會靜態阻塞頁面的 JS 執行緒，導致後續的 browser_* 呼叫掛起或拋出錯誤；現在 agent 可以在 browser_snapshot 輸出中看到待處理的對話框並明確回應。

工作流程：

1. 呼叫 browser_snapshot。如果對話框正在阻塞頁面，它會顯示為 pending_dialogs: [{"id": "d-1", "type": "alert", "message": "..."}]。
2. 呼叫 browser_dialog(action="accept") 或 browser_dialog(action="dismiss")。對於 prompt() 對話框，傳入 prompt_text="..." 來提供回應。
3. 重新快照 — pending_dialogs 為空；頁面的 JS 執行緒已恢復。

偵測自動發生，透過持久化的 CDP supervisor — 每個任務一個 WebSocket，訂閱 Page/Runtime/Target 事件。supervisor 還會在快照中填入 frame_tree 欄位，使 agent 可以看到當前頁面的 iframe 結構，包括跨來源（OOPIF）iframe。

可用性矩陣：

**在 Browserbase 上的運作方式。**Browserbase 的 CDP proxy 會在伺服器端自動在 ~10ms 內關閉真正的原生對話框，因此我們無法使用 Page.handleJavaScriptDialog。supervisor 透過 Page.addScriptToEvaluateOnNewDocument 注入一個小型腳本，用同步 XHR 覆蓋 window.alert/confirm/prompt。我們透過 Fetch.enable 攔截這些 XHR — 頁面的 JS 執行緒會在 XHR 上阻塞，直到我們使用 agent 的回應呼叫 Fetch.fulfillRequest。prompt() 的回傳值會原封不動地傳回頁面 JS。

對話框政策在 config.yaml 的 browser.dialog_policy 下設定：

browser_snapshot.frame_tree 中的框架樹上限為 30 個框架和 OOPIF 深度 2，以在廣告較多的頁面上保持負載量可控。當達到上限時會顯示 truncated: true flag；需要完整框架樹的 agent 可以使用 browser_cdp 搭配 Page.getFrameTree。

實用範例

填寫 Web 表單

User: Sign up for an account on example.com with my email john@example.com

Agent workflow:
1. browser_navigate("https://example.com/signup")
2. browser_snapshot()  → sees form fields with refs
3. browser_type(ref="@e3", text="john@example.com")
4. browser_type(ref="@e5", text="SecurePass123")
5. browser_click(ref="@e8")  → clicks "Create Account"
6. browser_snapshot()  → confirms success

研究動態內容

User: What are the top trending repos on GitHub right now?

Agent workflow:
1. browser_navigate("https://github.com/trending")
2. browser_snapshot(full=true)  → reads trending repo list
3. Returns formatted results

Session 錄製

自動將瀏覽器 session 錄製為 WebM 影片檔案：

browser:
  record_sessions: true  # default: false

啟用後，錄製會在首次 browser_navigate 時自動開始，並在 session 關閉時儲存到 ~/.hermes/browser_recordings/。在本地和雲端（Browserbase）模式下都適用。超過 72 小時的錄製會自動清理。

隱匿功能

Browserbase 提供自動隱匿能力：

注意

如果付費功能在你的方案中不可用，Hermes 會自動回退 — 先停用 keepAlive，然後是 proxies — 以便在免費方案中仍可正常瀏覽。

Session 管理

• 每個任務透過 Browserbase 獲得隔離的瀏覽器 session
• session 在停用後自動清理（預設：2 分鐘）
• 後台執行緒每 30 秒檢查一次過期 session
• process 結束時執行緊急清理，防止孤立 session
• session 透過 Browserbase API 釋放（REQUEST_RELEASE 狀態）

限制

• 基於文字的互動 — 依賴無障礙樹，而非像素座標
• 快照大小 — 大型頁面可能被截斷或在 8000 字元處由 LLM 摘要
• Session 超時 — 雲端 session 根據你的供應商方案設定過期
• 費用 — 雲端 session 消耗供應商額度；session 在對話結束或停用後自動清理。使用 /browser connect 進行免費的本地瀏覽。
• 無法下載檔案 — 無法從瀏覽器下載檔案

---

---

視覺與圖片貼上