Chuyển tới nội dung chính

Tự động hóa trình duyệt

Hermes Agent bao gồm bộ công cụ tự động hóa trình duyệt đầy đủ với nhiều tùy chọn phụ trợ:

  • Chế độ đám mây cơ sở trình duyệt thông qua Browserbase dành cho các trình duyệt đám mây được quản lý và công cụ chống bot
  • Trình duyệt Sử dụng chế độ đám mây qua Browser Use làm nhà cung cấp trình duyệt đám mây thay thế
  • Chế độ thu thập thông tin trên đám mây qua Firecrawl dành cho các trình duyệt đám mây có tính năng quét tích hợp
  • Chế độ cục bộ Camofox qua Camofox để duyệt web chống phát hiện cục bộ (giả mạo dấu vân tay dựa trên Firefox)
  • CDP dòng Crom cục bộ — kết nối các công cụ trình duyệt với phiên bản Chrome, Brave, Crom hoặc Edge của riêng bạn bằng

/browser connect

  • Chế độ trình duyệt cục bộ thông qua agent-browser CLI và cài đặt Chrome cục bộ

Trong tất cả các chế độ, tác nhân có thể điều hướng các trang web, tương tác với các thành phần trang, điền biểu mẫu và trích xuất thông tin.

Tổng quan​

Các trang được trình bày dưới dạng cây khả năng truy cập (ảnh chụp nhanh dựa trên văn bản), khiến chúng trở nên lý tưởng cho các đại lý LLM. Các phần tử tương tác nhận ID giới thiệu (như

@e1

,

@e2

) mà tác nhân sử dụng để nhấp và nhập.

Các khả năng chính:

  • Thực thi trên đám mây từ nhiều nhà cung cấp — Cơ sở trình duyệt, Sử dụng trình duyệt hoặc Firecrawl — không cần trình duyệt cục bộ
  • Tích hợp dòng Crom cục bộ — đính kèm vào trình duyệt Chrome, Brave, Crom hoặc Edge đang chạy của bạn thông qua CDP để duyệt thực tế
  • Tàng hình tích hợp — dấu vân tay ngẫu nhiên, giải CAPTCHA, proxy dân dụng (Cơ sở trình duyệt)
  • Cách ly phiên — mỗi tác vụ có phiên trình duyệt riêng
  • Tự động dọn dẹp — các phiên không hoạt động sẽ bị đóng sau khi hết thời gian chờ
  • Phân tích tầm nhìn — ảnh chụp màn hình + phân tích AI để hiểu rõ bằng hình ảnh

Thiết lập​

Nous Subscribers

Nếu bạn có đăng ký Nous Portal trả phí, bạn có thể sử dụng tính năng tự động hóa trình duyệt thông qua Tool Gateway mà không cần bất kỳ khóa API riêng biệt nào. Các bản cài đặt mới có thể chạy Hermes setup --portal để đăng nhập và bật mọi công cụ cổng cùng một lúc; các lượt cài đặt hiện tại có thể chọn Đăng ký Nous làm nhà cung cấp trình duyệt thông qua Hermes model hoặc `Hermes tools

.

Chế độ đám mây của trình duyệt​

Để sử dụng trình duyệt đám mây do Browserbase quản lý, hãy thêm:


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

`
``Nhận thông tin đăng nhập của bạn tại [browserbase.com](https://browserbase.com).

### Trình duyệt Sử dụng chế độ đám mây

Để sử dụng Trình duyệt Sử dụng làm nhà cung cấp trình duyệt đám mây của bạn, hãy thêm:

``` bash

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

`
``Nhận khóa API của bạn tại [browser-use.com](https://browser-use.com). Sử dụng trình duyệt cung cấp trình duyệt đám mây thông qua API REST của nó. Nếu cả thông tin xác thực về Cơ sở trình duyệt và Sử dụng trình duyệt đều được đặt thì Cơ sở trình duyệt sẽ được ưu tiên.

### Chế độ đám mây Firecrawl

Để sử dụng Firecrawl làm nhà cung cấp trình duyệt đám mây của bạn, hãy thêm:

``` bash

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

`
``Nhận khóa API của bạn tại [firecrawl.dev](https://firecrawl.dev). Sau đó chọn Firecrawl làm nhà cung cấp trình duyệt của bạn:

``` bash
Hermes setup tools

# → Browser Automation → Firecrawl

`
``Cài đặt tùy chọn:

``` bash

# 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

`

### Định tuyến kết hợp: đám mây cho URL công khai, cục bộ cho LAN/localhost

Khi nhà cung cấp đám mây được định cấu hình, Hermes sẽ tự động tạo ra **xe sidecar Chrome cục bộ**
đối với các URL phân giải thành địa chỉ riêng/loopback/LAN (
`localhost

, 
`127.0.0.1

,
`192.168.x.x

, 
`10.x.x.x

, 
`172.16-31.x.x

, 

*.local

, 

*.lan

, 

*.internal

,
Vòng lặp IPv6 

::1

, 
`169.254.x.x
` liên kết cục bộ). Các URL công khai tiếp tục sử dụng
nhà cung cấp đám mây trong cùng một cuộc trò chuyện.

Điều này giải quyết quy trình làm việc phổ biến "Tôi đang phát triển cục bộ nhưng sử dụng Browserbase" —
đại lý có thể chụp màn hình bảng điều khiển của bạn tại 
`http://localhost:3000
` VÀ cạo
`https://GitHub.com
` mà bạn không cần chuyển đổi nhà cung cấp hoặc vô hiệu hóa trình bảo vệ SSRF.
Nhà cung cấp đám mây không bao giờ nhìn thấy URL riêng tư.

Tính năng này được **bật theo mặc định**. Để tắt nó (tất cả các URL đều được chuyển đến phần được định cấu hình
nhà cung cấp đám mây, như trước):

``` yaml

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

`
``Khi tính năng tự động định tuyến bị tắt, các URL riêng tư sẽ bị từ chối bằng

"Blocked: URL targets a private or internal address"
` trừ khi bạn cũng đặt
`browser.allow_private_urls: true
` (cho phép nhà cung cấp đám mây thử chúng —
thường sẽ không hoạt động vì Browserbase, v.v. không thể truy cập mạng LAN của bạn).

Yêu cầu: xe sidecar cục bộ sử dụng CLI 
`agent-browser
` giống như xe địa phương thuần túy
chế độ này, vì vậy bạn cần cài đặt nó (
`Hermes setup tools → Browser Automation

tự động cài đặt nó). Chuyển hướng sau điều hướng từ một URL công khai sang một URL riêng tư
địa chỉ vẫn bị chặn (bạn không thể sử dụng thủ thuật chuyển hướng đến nội bộ để tiếp cận
mạng LAN của bạn thông qua đường dẫn công cộng).

### Chế độ cục bộ Camofox[Camofox](https://GitHub.com/jo-inc/camofox-browser) là máy chủ Node.js tự lưu trữ bao bọc Camoufox (một nhánh của Firefox có tính năng giả mạo dấu vân tay C++). Nó cung cấp khả năng duyệt chống phát hiện cục bộ mà không phụ thuộc vào đám mây.

``` bash

# 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
` khởi động vùng chứa mặc định ngay lập tức. Nếu bạn muốn cài đặt thời gian chạy tùy chỉnh chẳng hạn như vùng nhớ Node lớn hơn, VNC hoặc thư mục hồ sơ liên tục, hãy tạo hình ảnh trước rồi tự chạy nó:

``` bash

# 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

`
``Khi bật VNC, trình duyệt sẽ chạy ở chế độ head và có thể được xem trực tiếp trong trình duyệt của bạn tại 
`http://localhost:6080
` (noVNC). Bạn cũng có thể kết nối máy khách VNC gốc với 
`localhost:5901

.

Nếu bạn đã chạy 
`make up

, hãy dừng và xóa vùng chứa mặc định đó trước khi bắt đầu vùng chứa tùy chỉnh:

``` bash
make down

# then run the custom Docker run command above

`
``Sau đó thiết lập trong 

~/.Hermes/.env

:

``` bash
CAMOFOX_URL=http://localhost:9377

`
``Hoặc định cấu hình qua 
`Hermes tools
` → Tự động hóa trình duyệt → Camofox.

Khi 
`CAMOFOX_URL
` được đặt, tất cả các công cụ trình duyệt sẽ tự động định tuyến qua Camofox thay vì Browserbase hoặc trình duyệt tác nhân.

#### Phiên trình duyệt liên tục

Theo mặc định, mỗi phiên Camofox nhận được một danh tính ngẫu nhiên — cookie và thông tin đăng nhập không tồn tại trong quá trình khởi động lại tác nhân. Để bật các phiên trình duyệt liên tục, hãy thêm phần sau vào 

~/.Hermes/config.yaml

:

`YAML
browser:
  camofox:
    managed_persistence: true

`
``Sau đó khởi động lại hoàn toàn Hermes để có được cấu hình mới.

:::warning[Nested path matters]
Hermes đọc 
`browser.camofox.managed_persistence

, **không** là 
`managed_persistence
` cấp cao nhất. Một lỗi thường gặp là viết:

`YAML

# ❌ Wrong — Hermes ignores this
managed_persistence: true

`
``Nếu cờ được đặt sai đường dẫn, Hermes sẽ âm thầm quay trở lại 
`userId
` tạm thời ngẫu nhiên và trạng thái đăng nhập của bạn sẽ bị mất trong mỗi phiên.
:::

#####Hermes làm gì
- Gửi 
`userId
` trong phạm vi hồ sơ xác định tới Camofox để máy chủ có thể sử dụng lại cùng một hồ sơ Firefox trong các phiên.
- Bỏ qua việc phá hủy ngữ cảnh phía máy chủ khi dọn dẹp, do đó, cookie và thông tin đăng nhập vẫn tồn tại giữa các tác vụ của tác nhân.
- Đưa 
`userId
` vào hồ sơ Hermes đang hoạt động, vì vậy các hồ sơ Hermes khác nhau sẽ nhận được các hồ sơ trình duyệt khác nhau (cách ly hồ sơ).

##### Điều Hermes không làm
- Nó không buộc phải tồn tại trên máy chủ Camofox. Hermes chỉ gửi 
`userId
` ổn định; máy chủ phải tôn trọng nó bằng cách ánh xạ 
`userId
` đó vào một thư mục hồ sơ Firefox liên tục.
- Nếu bản dựng máy chủ Camofox của bạn coi mọi yêu cầu là nhất thời (ví dụ: luôn gọi 
`browser.newContext()
` mà không tải hồ sơ được lưu trữ), Hermes không thể duy trì các phiên đó. Đảm bảo rằng bạn đang chạy bản dựng Camofox triển khai tính bền vững của hồ sơ dựa trên userId.

##### Xác minh xem nó có hoạt động không
1. Khởi động Hermes và máy chủ Camofox của bạn.
2. Mở Google (hoặc bất kỳ trang đăng nhập nào) trong tác vụ trình duyệt và đăng nhập thủ công.
3. Kết thúc tác vụ trình duyệt một cách bình thường.
4. Bắt đầu tác vụ trình duyệt mới.
5. Mở lại trang đó — bạn vẫn phải đăng nhập.

Nếu bước 5 khiến bạn đăng xuất, máy chủ Camofox không hỗ trợ 
`userId
` ổn định. Kiểm tra kỹ đường dẫn cấu hình của bạn, xác nhận rằng bạn đã khởi động lại hoàn toàn Hermes sau khi chỉnh sửa 
`config.yaml
` và xác minh phiên bản máy chủ Camofox của bạn hỗ trợ hồ sơ liên tục cho mỗi người dùng.

##### Nơi nhà nước sinh sống

Hermes lấy 
`userId
` ổn định từ thư mục 

~/.Hermes/browser_auth/camofox/
` trong phạm vi hồ sơ (hoặc thư mục tương đương trong 

$Hermes_HOME
` cho các cấu hình không mặc định). Dữ liệu hồ sơ trình duyệt thực tế nằm ở phía máy chủ Camofox, được khóa bởi 
`userId
` đó. Để đặt lại hoàn toàn một cấu hình liên tục, hãy xóa cấu hình đó trên máy chủ Camofox và xóa thư mục trạng thái của cấu hình Hermes tương ứng.

#### Phiên Camofox được quản lý bên ngoài

Khi một ứng dụng khác điều khiển trình duyệt Camofox hiển thị (trợ lý máy tính để bàn, tích hợp tùy chỉnh, tác nhân khác), hãy định cấu hình Hermes để hoạt động bên trong cùng danh tính đó thay vì tạo ra hồ sơ riêng biệt của chính nó.

Ba nút điều khiển hành vi:

| Cài đặt | Env var | Hiệu ứng |
|----------|----------|--------|
| 
`browser.camofox.user_id
` | 
`CAMOFOX_USER_ID
` | Camofox 
`userId
` Hermes sử dụng khi tạo tab. Cài đặt này sẽ chuyển phiên sang chế độ "được quản lý bên ngoài". |
| 
`browser.camofox.session_key
` | 
`CAMOFOX_SESSION_KEY
` | 
`sessionKey
` (còn gọi là 
`listItemId

) được gửi khi tạo tab. Được sử dụng để khớp với một tab hiện có trong quá trình áp dụng. Mặc định là giá trị mỗi tác vụ nếu không được đặt. |
| 
`browser.camofox.adopt_existing_tab
` | 
`CAMOFOX_ADOPT_EXISTING_TAB
` | Khi đúng, Hermes gọi 
`GET /tabs?userId=<user_id>
` trong lần sử dụng đầu tiên và sử dụng lại tab hiện có trước khi tạo tab mới. |Các biến Env được ưu tiên hơn 
`config.yaml

. Một trong hai hình thức hoạt động:

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

`

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

`
``**Điều gì thay đổi khi 
`user_id
` được đặt:**
- Hermes bỏ qua việc dọn dẹp mang tính phá hoại khi kết thúc nhiệm vụ (giống như 
`managed_persistence: true

). Tab/cookie/hồ sơ của ứng dụng khác vẫn tồn tại.

- Hermes **không** gọi 
`DELETE /sessions/<user_id
` — điểm cuối đó sẽ xóa tất cả dữ liệu người dùng, do đó, nó sẽ hủy bỏ phiên của ứng dụng bên ngoài nếu kích hoạt.

**Cách hoạt động của việc áp dụng tab (khi 
`adopt_existing_tab: true

):**
1. Trong lệnh gọi công cụ trình duyệt đầu tiên sau khi bắt đầu quá trình, Hermes phát hành 
`GET /tabs?userId=<user_id
` (thời gian chờ 5 giây).
2. Nếu bất kỳ tab nào trong phản hồi có 
`listItemId == session_key

, Hermes sẽ sử dụng tab được tạo gần đây nhất trong nhóm đó.
3. Mặt khác, Hermes sẽ sử dụng tab được tạo gần đây nhất cho người dùng (bất kỳ 
`listItemId
` nào).
4. Nếu không có tab nào tồn tại hoặc yêu cầu không thành công, Hermes sẽ quay lại tạo một tab mới trong thao tác tiếp theo.

Quá trình áp dụng chỉ kích hoạt cho đến khi 
`tab_id
` được điền cho phiên. Nếu ứng dụng bên ngoài đóng tab được chấp nhận giữa chừng, lệnh gọi công cụ trình duyệt tiếp theo sẽ hiển thị lỗi Camofox — Hermes không thăm dò lại tab mới trong mỗi cuộc gọi.

**Chọn 
`session_key

:** nếu bạn muốn Hermes gắn vào một tab hiện có *cụ thể* một cách đáng tin cậy, hãy đặt 
`session_key
` thành 
`listItemId
` ứng dụng bên ngoài được sử dụng khi tạo tab đó. Nếu bạn không đặt 
`session_key
` và chỉ đặt 
`user_id

, Hermes sẽ tạo 
`session_key
` theo nhiệm vụ (
`task_<id

) — Hermes sẽ chia sẻ cookie và hồ sơ với ứng dụng bên ngoài nhưng sẽ mở tab riêng thay vì sử dụng lại.

**Lưu ý đồng thời:** ứng dụng bên ngoài và Hermes có thể điều khiển đồng thời cùng một Camofox 
`userId

, nhưng Camofox không phối hợp tiêu điểm trên mỗi tab giữa các máy khách. Điều phối quyền sở hữu ở lớp ứng dụng (ví dụ: ứng dụng bên ngoài tạm dừng trong khi Hermes chạy).`####Xem trực tiếp VNC

Khi Camofox chạy ở chế độ head (có cửa sổ trình duyệt hiển thị), nó sẽ hiển thị cổng VNC trong phản hồi kiểm tra tình trạng. Hermes tự động phát hiện ra điều này và đưa URL VNC vào phản hồi điều hướng, vì vậy nhân viên hỗ trợ có thể chia sẻ liên kết để bạn xem trực tiếp trên trình duyệt.

### Trình duyệt họ Crom cục bộ qua CDP (

/browser connect

)

Thay vì nhà cung cấp đám mây, bạn có thể đính kèm các công cụ trình duyệt Hermes vào phiên bản Chrome, Brave, Chrome hoặc Edge đang chạy của riêng bạn thông qua Giao thức DevTools của Chrome (CDP). Điều này hữu ích khi bạn muốn xem tác nhân đang làm gì trong thời gian thực, tương tác với các trang yêu cầu cookie/phiên của riêng bạn hoặc tránh chi phí trình duyệt trên đám mây.

:::note

/browser connect
` là **lệnh gạch chéo tương tác-CLI** — lệnh này không được gửi đi bởi cổng. Nếu bạn cố chạy nó trong WebUI, Telegram, Discord hoặc trò chuyện cổng khác, tin nhắn sẽ được gửi đến tổng đài viên dưới dạng văn bản thuần túy và lệnh sẽ không được thực thi. Khởi động Hermes từ terminal (
`Hermes
` hoặc 
`Hermes chat

) và phát hành 

/browser connect
` tại đó.
:::

Trong CLI, sử dụng:

`
/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

`
``Nếu một trình duyệt chưa chạy với tính năng gỡ lỗi từ xa, Hermes sẽ cố gắng tự động khởi chạy trình duyệt họ Chrome được hỗ trợ với 

--remote-debugging-port=9222

. Tính năng phát hiện bao gồm Brave, Google Chrome, Chrome và Microsoft Edge, với các đường dẫn cài đặt Linux phổ biến như 

/opt/brave-bin/brave
` và 

/snap/bin/brave

.

:::tip
Để khởi động thủ công trình duyệt dòng Chrome khi bật CDP, hãy sử dụng thư mục dữ liệu người dùng chuyên dụng để cổng gỡ lỗi thực sự xuất hiện ngay cả khi trình duyệt đang chạy với cấu hình thông thường của bạn:

``` bash

# 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 &

`
``Sau đó khởi chạy Hermes CLI và chạy 

/browser connect

.

**Tại sao 

--user-data-dir

?** Nếu không có nó, việc khởi chạy trình duyệt dòng Chrome trong khi phiên bản thông thường đang chạy thường mở một cửa sổ mới trên quy trình hiện có — và quy trình hiện tại đó không được bắt đầu bằng 

--remote-debugging-port

, vì vậy cổng 9222 không bao giờ mở. Một thư mục dữ liệu người dùng chuyên dụng buộc một quy trình trình duyệt mới trong đó cổng gỡ lỗi thực sự lắng nghe. 

--no-first-run --no-default-browser-check
` bỏ qua trình hướng dẫn khởi chạy lần đầu cho cấu hình mới.
:::

Khi được kết nối qua CDP, tất cả các công cụ trình duyệt (
`browser_navigate

, 
`browser_CLIck

, v.v.) sẽ hoạt động trên phiên bản trình duyệt trực tiếp của bạn thay vì quay phiên đám mây.

### WSL2 + Windows Chrome: thích MCP hơn 

/browser connect
`Nếu Hermes chạy bên trong WSL2 nhưng cửa sổ Chrome mà bạn muốn điều khiển lại chạy trên máy chủ Windows thì 

/browser connect
` thường không phải là đường dẫn tốt nhất.

Tại sao:
- 

/browser connect
` kỳ vọng chính Hermes sẽ đạt được điểm cuối CDP có thể sử dụng được
- các phiên gỡ lỗi trực tiếp của Chrome hiện đại thường hiển thị điểm cuối máy chủ cục bộ không thể truy cập trực tiếp từ WSL giống như cổng 
`9222
` cổ điển
- ngay cả khi Windows Chrome có thể gỡ lỗi được, cách tích hợp rõ ràng nhất thường là để máy chủ MCP của trình duyệt phía Windows gắn vào Chrome và để Hermes nói chuyện với máy chủ MCP đó

Đối với thiết lập đó, hãy ưu tiên 
`chrome-devtools-MCP
` thông qua hỗ trợ Hermes MCP.

Xem hướng dẫn MCP để thiết lập thực tế:
- [Use MCP with Hermes](../../guides/use-MCP-with-Hermes.md#wsl2-bridge-Hermes-in-wsl-to-Windows-chrome)

### Chế độ trình duyệt cục bộ

Nếu bạn **không** đặt bất kỳ thông tin đăng nhập nào trên đám mây và không sử dụng 

/browser connect

, Hermes vẫn có thể sử dụng các công cụ trình duyệt thông qua cài đặt Chrome cục bộ do 
`agent-browser
` điều khiển.

### Biến môi trường tùy chọn

``` bash

# 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 milliseconds (default: project default)
# Examples: 600000 (10min), 1800000 (30min)
BROWSERBASE_SESSION_TIMEOUT=600000

# 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

`

### Cài đặt trình duyệt tác nhân CLI

``` bash
npm install -g agent-browser

# Or install locally in the repo:
npm install

`

:::info
Bộ công cụ 
`browser
` phải được bao gồm trong danh sách 
`toolsets
` trong cấu hình của bạn hoặc được bật thông qua 
`Hermes config set toolsets '["Hermes-CLI", "browser"]'

.
:::

## Công cụ có sẵn

###
`browser_navigate
``Điều hướng đến một URL. Phải được gọi trước bất kỳ công cụ trình duyệt nào khác. Khởi tạo phiên Browserbase.

`
Navigate to https://GitHub.com/NousResearch

`

:::tip
Để truy xuất thông tin đơn giản, hãy ưu tiên 
`web_search
` hoặc 
`web_extract
` — chúng nhanh hơn và rẻ hơn. Sử dụng các công cụ của trình duyệt khi bạn cần **tương tác** với một trang (nhấp vào nút, điền biểu mẫu, xử lý nội dung động).
:::

###
`browser_snapshot
``Nhận ảnh chụp nhanh dựa trên văn bản của cây khả năng truy cập của trang hiện tại. Trả về các phần tử tương tác có ID giới thiệu như 

@e1

, 

@e2
` để sử dụng với 
`browser_CLIck
` và 
`browser_type

.
- **
`full=false

** (mặc định): Chế độ xem thu gọn chỉ hiển thị các phần tử tương tác
- **
`full=true

**: Nội dung trang hoàn chỉnh

Ảnh chụp nhanh trên 8000 ký tự được LLM tự động tóm tắt.

###
`browser_CLIck
``Nhấp vào một phần tử được xác định bằng ID giới thiệu của nó từ ảnh chụp nhanh.

`
CLIck @e5 to press the "Sign In" button

`

###
`browser_type
``Nhập văn bản vào trường đầu vào. Xóa trường trước, sau đó nhập văn bản mới.

`
Type "Hermes Agent" into the search field @e3

`

###
`browser_scroll
``Cuộn trang lên hoặc xuống để xem thêm nội dung.

`
Scroll down to see more results

`

###
`browser_press
``Nhấn một phím bàn phím. Hữu ích cho việc gửi biểu mẫu hoặc điều hướng.

`
Press Enter to submit the form

`
``Các khóa được hỗ trợ: 
`Enter

, 
`Tab

, 
`Escape

, 
`ArrowDown

, 
`ArrowUp

, v.v.

###
`browser_back
``Điều hướng trở lại trang trước trong lịch sử trình duyệt.

###
`browser_get_images
``Liệt kê tất cả hình ảnh trên trang hiện tại cùng với URL và văn bản thay thế của chúng. Hữu ích cho việc tìm kiếm hình ảnh để phân tích.

###
`browser_vision
``Chụp ảnh màn hình và phân tích nó bằng AI tầm nhìn. Sử dụng tính năng này khi ảnh chụp nhanh văn bản không nắm bắt được thông tin hình ảnh quan trọng — đặc biệt hữu ích cho CAPTCHA, bố cục phức tạp hoặc các thách thức xác minh trực quan.

Ảnh chụp màn hình được lưu liên tục và đường dẫn tệp được trả về cùng với phân tích AI. Trên các nền tảng nhắn tin (Telegram, Discord, Slack, WhatsApp), bạn có thể yêu cầu đại lý chia sẻ ảnh chụp màn hình - nó sẽ được gửi dưới dạng tệp đính kèm ảnh gốc thông qua cơ chế 
`MEDIA:

.

`
What does the chart on this page show?

`
``Ảnh chụp màn hình được lưu trữ trong 

~/.Hermes/cache/screenshots/
` và tự động dọn sạch sau 24 giờ.

###
`browser_console
``Nhận đầu ra của bảng điều khiển trình duyệt (thông báo nhật ký/cảnh báo/lỗi) và các ngoại lệ JavaScript chưa được phát hiện từ trang hiện tại. Cần thiết để phát hiện các lỗi JS thầm lặng không xuất hiện trong cây khả năng truy cập.

`
Check the browser console for any JavaScript errors

`
``Sử dụng 
`clear=True
` để xóa bảng điều khiển sau khi đọc, để các cuộc gọi tiếp theo chỉ hiển thị tin nhắn mới.

browser_console
` cũng đánh giá JavaScript khi được gọi bằng đối số 
`expression
` — có hình dạng giống như bảng điều khiển DevTools, kết quả trả về được phân tích cú pháp (các đối tượng được tuần tự hóa JSON trở thành chính tả; các giá trị nguyên thủy vẫn nguyên thủy).

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

`
`Khi người giám sát CDP hoạt động cho phiên hiện tại (điển hình cho bất kỳ phiên nào chạy 
`browser_navigate
` dựa trên phần phụ trợ có khả năng CDP), quá trình đánh giá sẽ diễn ra trên WebSocket liên tục của người giám sát — không mất phí khởi động quy trình con. Ngược lại, sẽ chuyển sang đường dẫn CLI của trình duyệt tác nhân tiêu chuẩn. Hành vi thì giống hệt nhau; chỉ thay đổi độ trễ.

###
`browser_cdp
``Thông qua Giao thức DevTools thô của Chrome — lối thoát cho các hoạt động của trình duyệt không được các công cụ khác xử lý. Sử dụng để xử lý hộp thoại gốc, đánh giá trong phạm vi iframe, kiểm soát cookie/mạng hoặc bất kỳ động từ CDP nào mà tác nhân cần.

**Chỉ khả dụng khi có thể truy cập điểm cuối CDP khi bắt đầu phiên** — nghĩa là 

/browser connect
` đã được đính kèm vào trình duyệt Chrome, Brave, Chrome hoặc Edge đang chạy hoặc 
`browser.cdp_url
` được đặt trong 
`config.yaml

. Chế độ trình duyệt tác nhân cục bộ mặc định, Camofox và nhà cung cấp đám mây (Browserbase, Sử dụng trình duyệt, Firecrawl) hiện không hiển thị CDP cho công cụ này - nhà cung cấp đám mây có URL CDP mỗi phiên nhưng định tuyến phiên trực tiếp là phần tiếp theo.

**Tham khảo phương pháp CDP:** https://chromedevtools.GitHub.io/devtools-protocol/ — tác nhân có thể 
`web_extract
` trang của một phương thức cụ thể để tra cứu tham số và trả về hình dạng.

Các mẫu phổ biến:

`
# 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")

`
``Các phương thức cấp trình duyệt (
`Target.*

, 
`Browser.*

, 
`Storage.*

) bỏ qua 
`target_id

. Các phương thức cấp trang (
`Page.*

, 
`Runtime.*

, 
`DOM.*

, 
`Emulation.*

) yêu cầu 
`target_id
` từ 
`Target.getTargets

. Mỗi cuộc gọi không trạng thái đều độc lập - các phiên không tồn tại giữa các cuộc gọi.

**iframe có nguồn gốc chéo:** chuyển 
`frame_id
` (từ 
`browser_snapshot.frame_tree.children[]
` trong đó 
`is_oopif=true

) để định tuyến cuộc gọi CDP qua phiên trực tiếp của người giám sát cho iframe đó. Đây là cách 
`Runtime.evaluate
` bên trong iframe có nguồn gốc chéo hoạt động trên Browserbase, nơi các kết nối CDP không trạng thái sẽ hết hạn URL đã ký. Ví dụ:

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

`
``Các iframe có cùng nguồn gốc không cần 
`frame_id
` — thay vào đó hãy sử dụng 
`document.querySelector('iframe').contentDocument
` từ 
`Runtime.evaluate
` cấp cao nhất.

###
`browser_dialog
``Phản hồi hộp thoại JS gốc (
`alert
` / 
`confirm
` / 
`prompt
` / 
`beforeunload

). Trước khi công cụ này tồn tại, các hộp thoại sẽ âm thầm chặn chuỗi JavaScript của trang và các lệnh gọi 
`browser_*
` tiếp theo sẽ bị treo hoặc bị loại bỏ; bây giờ tác nhân nhìn thấy các hộp thoại đang chờ xử lý trong đầu ra 
`browser_snapshot
` và phản hồi một cách rõ ràng.

**Quy trình làm việc:**
1. Gọi 
`browser_snapshot

. Nếu một hộp thoại đang chặn trang, nó sẽ hiển thị dưới dạng 
`pending_dialogs: [\{"id": "d-1", "type": "alert", "message": "..."}]

.
2. Gọi 
`browser_dialog(action="accept")
` hoặc 
`browser_dialog(action="dismiss")

. Đối với hộp thoại 
`prompt()

, hãy chuyển 
`prompt_text="..."
` để cung cấp phản hồi.
3. Ảnh chụp lại - 
`pending_dialogs
` trống; chủ đề JS của trang đã được tiếp tục.

**Việc phát hiện diễn ra tự động** thông qua người giám sát CDP liên tục — một WebSocket cho mỗi tác vụ đăng ký các sự kiện Trang/Thời gian chạy/Mục tiêu. Người giám sát cũng điền trường 
`frame_tree
` trong ảnh chụp nhanh để tổng đài viên có thể xem cấu trúc iframe của trang hiện tại, bao gồm cả iframe nhiều nguồn gốc (OOPIF).

**Ma trận sẵn có:**

| Phần cuối | Phát hiện qua 
`pending_dialogs
` | Phản hồi (công cụ 
`browser_dialog

) |
|---|---|---|
| Chrome cục bộ qua 

/browser connect
` hoặc 
`browser.cdp_url
` | ✓ | ✓ quy trình làm việc đầy đủ |
| Cơ sở trình duyệt | ✓ | ✓ quy trình làm việc đầy đủ (thông qua cầu XHR được chèn) |
| Camofox / trình duyệt tác nhân cục bộ mặc định | ✗ | ✗ (không có điểm cuối CDP) |

**Cách hoạt động trên Browserbase.** Proxy CDP của Browserbase tự động loại bỏ phía máy chủ hộp thoại gốc thực sự trong vòng ~10 mili giây, vì vậy chúng tôi không thể sử dụng 
`Page.handleJavaScriptDialog

. Người giám sát đưa vào một tập lệnh nhỏ thông qua 
`Page.addScriptToEvaluateOnNewDocument
` để ghi đè 
`window.alert

/
`confirm

/
`prompt
` bằng XHR đồng bộ. Chúng tôi chặn các XHR đó thông qua 
`Fetch.enable
` — chuỗi JS của trang vẫn bị chặn trên XHR cho đến khi chúng tôi gọi 
`Fetch.fulfillRequest
` kèm theo phản hồi của tổng đài viên. 
`prompt()
` trả về các giá trị khứ hồi trở lại trang JS không thay đổi.

**Chính sách hộp thoại** được định cấu hình trong 
`config.yaml
` trong 
`browser.dialog_policy

:| Chính sách | Hành vi |
|--------|----------|
| 
`must_respond
` (mặc định) | Chụp, hiển thị trong ảnh chụp nhanh, chờ lệnh gọi 
`browser_dialog()
` rõ ràng. Tự động loại bỏ an toàn sau 
`browser.dialog_timeout_s
` (300 giây mặc định) để tác nhân có lỗi không thể ngừng hoạt động mãi mãi. |
| 
`auto_dismiss
` | Bắt, giải tán ngay. Đại lý vẫn nhìn thấy hộp thoại trong lịch sử 
`browser_state
` nhưng không phải hành động. |
| 
`auto_accept
` | Nắm bắt, chấp nhận ngay. Hữu ích khi điều hướng các trang có lời nhắc 
`beforeunload
` tích cực. |`**Cây khung** bên trong 
`browser_snapshot.frame_tree
` được giới hạn ở 30 khung hình và độ sâu OOPIF là 2 để giới hạn tải trọng trên các trang có nhiều quảng cáo. Cờ 
`truncated: true
` xuất hiện khi đạt đến giới hạn; các đại lý cần cây đầy đủ có thể sử dụng 
`browser_cdp
` với 
`Page.getFrameTree

.

## Ví dụ thực tế

### Điền vào biểu mẫu 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

`

### Nghiên cứu nội dung động

`
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

`

## Ghi phiên

Tự động ghi lại các phiên trình duyệt dưới dạng tệp video WebM:

``` yaml
browser:
  record_sessions: true  # default: false

`
``Khi được bật, quá trình ghi sẽ tự động bắt đầu trên 
`browser_navigate
` đầu tiên và lưu vào 

~/.Hermes/browser_recordings/
` khi phiên đóng. Hoạt động ở cả chế độ cục bộ và đám mây (Browserbase). Các bản ghi cũ hơn 72 giờ sẽ tự động được dọn sạch.

## Tính năng tàng hình

Browserbase cung cấp khả năng ẩn tự động:

| Tính năng | Mặc định | Ghi chú |
|----------|----------|-------|
| Tàng hình cơ bản | Luôn bật | Dấu vân tay ngẫu nhiên, ngẫu nhiên khung nhìn, giải CAPTCHA |
| Ủy quyền dân cư | Trên | Các tuyến đường xuyên qua các khu công nghiệp dân cư để tiếp cận tốt hơn |
| Tàng hình nâng cao | Tắt | Bản dựng Chrome tùy chỉnh, yêu cầu Kế hoạch mở rộng |
| Giữ sống | Trên | Kết nối lại phiên sau khi mạng bị trục trặc |

:::note
Nếu các tính năng trả phí không có sẵn trong gói của bạn, Hermes sẽ tự động quay trở lại — đầu tiên là vô hiệu hóa 
`keepAlive

, sau đó là proxy — vì vậy việc duyệt vẫn hoạt động trên các gói miễn phí.

:::

## Quản lý phiên
- Mỗi tác vụ nhận được một phiên trình duyệt riêng biệt thông qua Browserbase
- Các phiên được tự động dọn sạch sau khi không hoạt động (mặc định: 2 phút)
- Chuỗi nền sẽ kiểm tra các phiên cũ 30 giây một lần
- Dọn dẹp khẩn cấp chạy khi thoát quá trình để ngăn chặn các phiên mồ côi
- Phiên được phát hành thông qua API Browserbase (trạng thái 
`REQUEST_RELEASE

)

## Hạn chế
- **Tương tác dựa trên văn bản** — dựa vào cây khả năng truy cập chứ không phải tọa độ pixel
- **Kích thước ảnh chụp nhanh** — các trang lớn có thể bị cắt bớt hoặc được tóm tắt bằng LLM ở 8000 ký tự
- **Thời gian chờ của phiên** — phiên trên đám mây hết hạn dựa trên cài đặt gói của nhà cung cấp của bạn
- **Chi phí** — phiên đám mây tiêu tốn tín dụng của nhà cung cấp; các phiên sẽ tự động được dọn sạch khi cuộc trò chuyện kết thúc hoặc sau khi không hoạt động. Sử dụng 

/browser connect
` để duyệt cục bộ miễn phí.
- **Không tải xuống tệp** — không thể tải xuống tệp từ trình duyệt