Browser Harness

1. Browser Harness là gì?

Browser Harness là một "sợi dây nối" giữa một trợ lý AI lập trình (như Claude Code hay Codex) và trình duyệt Chrome thật trên máy bạn. Khi đã nối, AI có thể tự mở trang web, bấm nút, gõ chữ, chụp màn hình, tải file... thay bạn, ngay trong Chrome đang đăng nhập sẵn các tài khoản của bạn. Điểm đặc biệt theo mô tả của dự án: khi AI thiếu một thao tác nào đó (ví dụ tải một file lên), nó tự viết thêm đoạn mã nhỏ cho thao tác đó và dùng lại về sau.

Công cụ miễn phí, mã nguồn mở (giấy phép MIT), do nhóm Browser Use làm. Chạy hoàn toàn trên máy bạn; phần "trình duyệt chạy trên đám mây" của họ là dịch vụ riêng, tùy chọn.

Nói thẳng: đây là công cụ dành cho lập trình viên, không phải ứng dụng có cửa sổ để bấm. Bạn cần sẵn một trợ lý AI lập trình chạy trong Terminal, và bạn chỉ "ra lệnh" cho trợ lý đó bằng tiếng thường. Dự án đang ở giai đoạn thử nghiệm (Alpha). Hướng dẫn này chỉ đưa bạn tới lúc kết nối xong và chạy được một thử nghiệm đầu tiên.

Cảnh báo an toàn: AI điều khiển Chrome thật nghĩa là nó nhìn thấy và thao tác được trên những trang bạn đang đăng nhập (mail, mạng xã hội, ngân hàng...). Chỉ dùng khi bạn tin trợ lý AI của mình, nên dùng một hồ sơ Chrome riêng cho việc này, và đừng để nó làm những việc nhạy cảm như chuyển tiền.

Hợp với bạn nếu:

• Bạn đã dùng Claude Code, Codex hoặc trợ lý AI lập trình tương tự, và muốn nó tự thao tác trên web.
• Bạn cần AI làm những việc cần đăng nhập hoặc trang web chạy nhiều JavaScript mà tải thẳng không đọc được.

Chưa hợp nếu:

• Bạn chưa có trợ lý AI lập trình và chỉ muốn một công cụ bấm-là-chạy. Công cụ này không có giao diện riêng.
• Chỉ cần đọc một trang web công khai. Chính tài liệu của dự án nói: với trang công khai thì dùng lệnh tải thông thường (curl), không cần mở trình duyệt.

2. Cần chuẩn bị gì?

• Máy tính chạy Windows, macOS hoặc Linux. Mã nguồn có xử lý riêng cho cả ba hệ điều hành.
• Google Chrome (hoặc trình duyệt cùng nền Chromium) đã cài và đang mở. Tải tại https://www.google.com/chrome/ .
• Một trợ lý AI lập trình, ví dụ Claude Code (https://code.claude.com/docs/en/overview ) hoặc Codex (https://github.com/openai/codex ). Các dịch vụ này có điều kiện sử dụng và giá riêng, hãy xem trang chính thức của từng cái; Browser Harness không yêu cầu bạn trả tiền cho nó.
• uv (công cụ cài và chạy chương trình Python, loại bỏ việc phải tự cài Python). Dự án dùng uv để cài. Trang chính thức: https://docs.astral.sh/uv/getting-started/installation/

Bản mới nhất lúc viết hướng dẫn là v0.1.13 (4/9/2026), cần Python từ 3.11 trở lên. Lệnh cài của dự án chỉ định Python 3.12; uv sẽ tự tải Python đó nếu máy chưa có.

Không cần khóa API riêng của Browser Harness. Dự án nói rõ: dùng Chrome trên máy thì không cần khóa của Browser Use Cloud.

3. Cài đặt từng bước

Có hai cách. Cách dễ nhất cho người mới là Cách A: nhờ chính trợ lý AI cài giúp.

Bước 1: Cài uv

Windows (mở PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Hoặc dùng Winget:

winget install --id=astral-sh.uv -e

macOS và Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Trên macOS bạn cũng có thể dùng Homebrew: brew install uv.

Sau khi cài, đóng rồi mở lại cửa sổ lệnh và kiểm tra:

uv --version

Thấy gì là đúng: hiện một số phiên bản của uv.

Bước 2 (Cách A): Nhờ trợ lý AI cài

Mở Claude Code hoặc Codex và dán một yêu cầu tương tự dưới đây. Nội dung cốt lõi: cài hoặc nâng cấp browser-harness bằng uv với Python 3.12, đăng ký "skill" của nó, rồi nối vào trình duyệt của bạn.

Install or upgrade browser-harness to the latest stable version with uv using Python 3.12, register the skill from `browser-harness skill`, and connect it to my browser. Ask me whether I want local browser recordings enabled (default: no). If setup or connection fails, follow https://github.com/browser-use/browser-harness/blob/main/install.md

Trợ lý sẽ chạy các lệnh giúp bạn và mở trang cài đặt của Chrome. Đến lúc đó, làm Bước 3.

Bước 2 (Cách B): Tự cài bằng lệnh

Chạy lệnh cài (dùng chung cho cả ba hệ điều hành):

uv tool install --python 3.12 --upgrade --force browser-harness

Kiểm tra:

browser-harness --version

Thấy gì là đúng: hiện số phiên bản, ví dụ 0.1.13. Để trợ lý AI biết cách dùng, nó cần một "skill" tên browser-harness, nội dung lấy từ lệnh browser-harness skill, kèm câu kích hoạt mà dự án khuyên: "Always use browser-harness for any web interaction: automation, scraping, testing, or site/app work." Thư mục lưu skill khác nhau tùy trợ lý, nên cách dễ nhất vẫn là nhờ chính trợ lý đăng ký skill (Cách A).

Bước 3: Cho phép Chrome cho AI kết nối

Đây là bước chỉ bạn làm được, AI không tự bấm thay bạn:

1. Mở Chrome, gõ vào thanh địa chỉ: chrome://inspect/#remote-debugging rồi Enter.
2. Tick ô Allow remote debugging for this browser instance.
3. Khi công cụ kết nối lần đầu, Chrome có thể hiện thêm một hộp thoại hỏi "Allow remote debugging?". Bấm Allow. Theo tài liệu dự án, đó là bước phê duyệt theo từng kết nối, là bình thường, không phải lỗi.

Trên macOS, nếu hộp thoại bị kẹt, dự án có lệnh hỗ trợ (cần cấp quyền Accessibility cho ứng dụng đang chạy Terminal trong System Settings):

browser-harness mac-approve

Bước 4: Kiểm tra kết nối

Nhờ trợ lý AI: "Dùng browser-harness in ra thông tin trang hiện tại". Hoặc tự chạy lệnh chẩn đoán:

browser-harness --doctor

Thấy gì là đúng: các mục như "chrome running" và "daemon alive" đều đạt. Nếu có mục báo FAIL, xem mục 5.

Về việc ghi lại hành động: Browser Harness có tính năng lưu ảnh chụp màn hình và nhật ký thao tác trên máy, tắt theo mặc định. Dự án khuyên hỏi người dùng một lần, và mặc định là không bật, vì nội dung lưu có thể chứa thông tin nhạy cảm. Xem trạng thái bằng:

browser-harness recordings

4. Dùng lần đầu

Mọi thứ diễn ra qua trợ lý AI của bạn. Mở Claude Code hoặc Codex (lúc Chrome đang mở) và thử một yêu cầu đơn giản, ít rủi ro:

1. "Mở trang https://example.com trong một tab mới và cho tôi biết tiêu đề trang."
2. "Chụp màn hình trang đó và cho tôi biết đường dẫn file ảnh."

Thấy gì là đúng: Chrome mở thêm một tab mới, tab có đánh dấu hình con ngựa ở đầu tiêu đề (đó là dấu hiệu tab đang do AI điều khiển), AI trả lời tiêu đề trang và lưu ảnh chụp.

Khi đã quen, bạn có thể nhờ những việc dài hơn, như ví dụ của dự án: mở trang cá nhân của bạn trên một mạng xã hội rồi tải các video mới nhất. Nhớ rằng AI đang dùng tài khoản thật của bạn.

Dùng như máy chủ MCP. Nếu trợ lý của bạn hỗ trợ MCP (chuẩn để trợ lý AI dùng công cụ bên ngoài), dự án có sẵn chế độ này. Với Claude Code:

claude mcp add browser-harness uvx --from 'browser-harness[mcp]' browser-harness-mcp

Các công cụ hiện ra có tên bắt đầu bằng browser_, như mở tab, bấm, gõ chữ, chụp màn hình. Cấu hình cho Cursor và một số ứng dụng khác xem tại https://github.com/browser-use/browser-harness/blob/main/docs/MCP.md

Lưu ý: lệnh kiểu browser-harness <<'PY' ... PY trong tài liệu dùng cú pháp của bash (heredoc), PowerShell của Windows không hiểu. Bạn không cần tự gõ những lệnh đó, trợ lý AI sẽ tự chạy; nếu muốn tự chạy trên Windows, hãy dùng Git Bash hoặc WSL.

5. Lỗi thường gặp và cách sửa

Dấu hiệu	Nguyên nhân	Cách sửa
Lệnh uv hoặc browser-harness báo không tìm thấy	Cửa sổ lệnh mở trước khi cài, nên chưa nhận đường dẫn mới	Đóng và mở lại Terminal/PowerShell rồi thử lại
page_info() báo permission-blocked hoặc không kết nối được	Chưa tick ô cho phép gỡ lỗi từ xa, hoặc chưa bấm Allow	Làm lại Bước 3. Nếu đã tick mà không thấy hộp thoại, bỏ tick rồi tick lại
browser-harness --doctor báo "chrome running" FAIL	Chrome chưa mở	Mở Chrome rồi chạy lại
--doctor báo "daemon alive" FAIL	Thiếu quyền gỡ lỗi từ xa, Chrome đã đóng, hoặc cổng kết nối không truy cập được	Mở Chrome, làm lại Bước 3 và chạy lại --doctor
Linux: Chromium cài bằng Snap, AI không kết nối được dù Chrome đang chạy	Snap chạy ứng dụng trong môi trường cách ly, nên cổng gỡ lỗi của trình duyệt không truy cập được	Cài Google Chrome bản .deb chính thức, rồi đặt biến môi trường BH_CHROME_PATH trỏ tới file chạy của nó; chi tiết ở https://github.com/browser-use/browser-harness/blob/main/docs/snap-linux-headless.md
Trợ lý dùng một skill "browser" cũ thay vì browser-harness	Còn sót skill cũ đã cài từ trước	Xóa thủ công thư mục skill cũ đó (theo hướng dẫn của dự án), đừng sửa trong thư mục cache của plugin
Mac: hộp thoại Allow liên tục hiện	Chrome hỏi phê duyệt cho mỗi kết nối mới	Bấm Allow, hoặc dùng browser-harness mac-approve như Bước 3. Đừng tạo nhiều kết nối mới không cần thiết

Nếu vẫn chưa được, dự án có trang báo lỗi tại https://github.com/browser-use/browser-harness/issues

6. Gỡ cài đặt / cập nhật

Cập nhật

Chạy lại lệnh cài của Bước 2 (Cách B); nó thay bản cũ bằng bản mới nhất. Hoặc dùng lệnh của chính công cụ:

browser-harness --update -y

Gỡ cài đặt

uv tool uninstall browser-harness

Dữ liệu của công cụ (đăng nhập cloud nếu có, mã định danh ẩn danh, thư mục làm việc của AI, nhật ký, ảnh chụp) nằm trong thư mục .config/browser-harness ngay dưới thư mục cá nhân của bạn (trên Windows là C:\Users\<tên bạn>\.config\browser-harness, hoặc thư mục bạn đặt bằng biến BH_HOME). Muốn xóa sạch thì xóa thư mục đó. Nếu trước đó bạn đã đăng ký skill trong trợ lý AI, hãy xóa thư mục skill browser-harness đó nữa.

Để Chrome không còn cho phép kết nối gỡ lỗi từ xa, vào lại chrome://inspect/#remote-debugging và bỏ tick ô đã bật ở Bước 3.

7. Câu hỏi hay gặp

Có mất tiền không? Bản chạy trên Chrome của bạn thì không. Browser Harness miễn phí, mã nguồn mở (MIT). Dự án có thêm dịch vụ trình duyệt đám mây (nhiều trình duyệt song song, proxy, giải CAPTCHA...) là dịch vụ riêng của Browser Use, không bắt buộc. Trợ lý AI lập trình mà bạn dùng cùng có thể có phí riêng.

Có cần mạng không? Cần mạng để cài và để trợ lý AI hoạt động. Bản thân việc điều khiển Chrome cục bộ không cần khóa của Browser Use.

Dữ liệu của tôi có bị gửi đi đâu không? Mã nguồn có một phần đo đạc sử dụng ẩn danh (gửi về dịch vụ PostHog), mặc định bật và bạn có thể tắt. Tắt bằng lệnh browser-harness telemetry disable. Trạng thái xem bằng browser-harness telemetry status. Ngoài ra, nội dung các trang mà AI xem sẽ đi vào cuộc trò chuyện với trợ lý AI của bạn, nên hãy lưu ý các trang nhạy cảm.

Máy yếu có chạy được không? Bản thân công cụ nhẹ (một chương trình Python nhỏ nối với Chrome). Giới hạn thực tế là Chrome và trợ lý AI bạn dùng.

Có dùng được trên điện thoại không? Không. Đây là công cụ dòng lệnh cho máy tính.