# browser-use: tự động hoá trình duyệt bằng AI — hướng dẫn cài đặt và dùng

> browser-use là thư viện Python mã nguồn mở cho phép AI thực hiện tác vụ trong trình duyệt bằng REPL, CDP và các trình duyệt cục bộ hoặc đám mây. Bạn có thể dùng CLI, thư viện Python hoặc API Cloud; cách cài cơ bản khá ngắn nhưng cần Python 3.11 trở lên và có thể cần API key.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-10-09 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/browser-use-tu-dong-hoa-trinh-duyet-bang-ai

browser-use là thư viện Python mã nguồn mở giúp AI điều khiển trình duyệt thật để hoàn thành tác vụ trên web. Bạn giao một việc bằng ngôn ngữ tự nhiên, còn tác nhân AI tự viết Python, chạy trong một REPL liên tục và tương tác với Chrome thông qua Chrome DevTools Protocol (CDP).

Repo phù hợp với dev Python, nhân viên văn phòng muốn tự động hoá thao tác lặp lại, chủ shop cần kiểm tra dữ liệu trên nhiều trang, hoặc đội ngũ muốn xây dựng agent xử lý trình duyệt. Điểm đáng giá là bạn có thể chọn chạy hoàn toàn trên Cloud, điều khiển trình duyệt cục bộ bằng model riêng, hoặc kết nối trình duyệt đang mở có sẵn phiên đăng nhập.

Dự án hiện có khoảng 120878 sao và 13516 fork, dùng giấy phép MIT. README cung cấp ba hướng dùng: Cloud API, CLI và thư viện Python. Trong bài này, mình tập trung vào cách cài thư viện Python và giải thích thêm khi nào nên chọn CLI hoặc Cloud.

```repo
- repo | browser-use/browser-use
- kind | Thư viện
- desc | Thư viện Python giúp AI điều khiển trình duyệt thật để tìm kiếm, nhập liệu, tải tệp và hoàn thành tác vụ web.
- stars | 121k
- lang | Python
- license | MIT
```

## browser-use làm được gì

### Giao nhiệm vụ bằng ngôn ngữ tự nhiên

Bạn chỉ cần truyền một task như tìm số sao của một repo, tìm lịch trống hoặc điền biểu mẫu. Agent sẽ tự lập kế hoạch, viết các lệnh Python cần thiết và chạy chúng trong trình duyệt thật. Điều này phù hợp với những quy trình thay đổi giao diện thường xuyên, nơi việc viết bộ chọn CSS cố định sẽ tốn công bảo trì.

### Điều khiển trình duyệt qua CDP

Agent dùng các helper của browser-harness và raw Chrome DevTools Protocol. Mô hình có thể mở tab, nhấp phần tử, chạy JavaScript và đọc kết quả trả về. Mỗi vòng chạy diễn ra trong một REPL liên tục nên agent giữ được ngữ cảnh của trang thay vì bắt đầu lại sau từng thao tác.

### Chạy trên Cloud hoặc máy của bạn

`Browser()` mặc định dùng trình duyệt Browser Use Cloud. Nếu muốn tự quản lý trình duyệt, bạn có thể dùng `Browser('chromium')` để mở một Chrome, Chromium hoặc Edge cục bộ với hồ sơ tạm. Bạn cũng có thể dùng `Browser('chrome')` để điều khiển Chrome đang mở và giữ các phiên đăng nhập hiện có.

### Kết nối nhiều loại model

README ghi rõ thư viện hỗ trợ model mặc định trên Browser Use gateway, OpenAI qua `ChatOpenAI`, Anthropic qua `ChatAnthropic`, Google qua `ChatGoogle`, hoặc chuỗi model tương thích Pydantic AI. Bạn cũng có thể kết nối model chạy cục bộ như Ollama thông qua một endpoint tương thích.

### Trả kết quả có cấu trúc

Với `output_model_schema`, agent có thể trả dữ liệu theo một schema thay vì chỉ trả văn bản. Tính năng này hữu ích khi bạn muốn đưa kết quả vào bảng tính, cơ sở dữ liệu hoặc bước xử lý tiếp theo trong ứng dụng.

### Tải lên và tải xuống tệp

Bạn có thể đặt tệp trong workspace rồi yêu cầu agent dùng tệp đó. Các tệp tải xuống được lưu trong `agent.workspace/downloads`; thuộc tính `result.downloads` liệt kê những tệp của lần chạy. Nếu trùng tên, hệ thống thêm ` (1)` thay vì ghi đè.

### Quản lý mật khẩu và giới hạn miền

Mật khẩu có thể truyền qua `sensitive_data` để agent dùng `type_secret`. Giá trị được thay bằng tên dạng `<secret:password>` trong nhiều đầu ra. Bạn cũng có thể giới hạn miền bằng `allowed_domains`, cấm miền bằng `prohibited_domains` hoặc chặn địa chỉ IP.

Đây là lớp bảo vệ cho model đã được căn chỉnh, không phải sandbox hoàn chỉnh. README cảnh báo rằng request từ trang được cho phép, iframe, hình ảnh, JavaScript hoặc mạng Python riêng của agent vẫn có thể truy cập nơi khác trong một số trường hợp.

### Tìm kiếm web và xử lý CAPTCHA

Tác nhân có thể dùng tìm kiếm web của Browser Use khi bật `web_search=True`. Tính năng này tắt mặc định, cần Browser Use key và tính phí theo lượt tìm kiếm. Trình duyệt Cloud có stealth browser, proxy và CAPTCHA solver; tuy vậy không có cấu hình nào đảm một trang tin tức CAPTCHA đều được giải quyết.

## Cần chuẩn bị gì

Bạn cần Python từ 3.11 trở lên. `pyproject.toml` của repo yêu cầu Python `>=3.11,<4.0`.

Bạn có thể cài bằng `uv` hoặc bằng `pip` trong virtual environment. README không yêu cầu hệ điều hành cụ thể cho thư viện Python. Các ví dụ dùng cú pháp shell Unix; trên Windows, bạn cần dùng cách kích hoạt môi trường ảo phù hợp với terminal đang mở.

Nếu dùng cấu hình mặc định, bạn cần một Browser Use API key. README cho biết một key có thể trả tiền cho model và trình duyệt Cloud, đồng thời dùng được cho CLI và MCP server. File `.env.example` trong repo có biến `BROWSER_USE_API_KEY`.

Nếu dùng model riêng, bạn cần key tương ứng của nhà cung cấp. Ví dụ `ChatOpenAI` cần `OPENAI_API_KEY`. Nếu dùng model cục bộ, README đưa ví dụ Ollama qua endpoint `http://localhost:11434/v1` với API key giả lập là `ollama`.

Nếu muốn điều khiển Chrome đang mở, Chrome cần bật `chrome://inspect/#remote-debugging` một lần. Nếu dùng `Browser('chromium')`, thư viện có thể mở Chrome, Chromium hoặc Edge mới với profile tạm. Nếu dùng profile riêng, README cho phép truyền `user_data_dir` hoặc `profile`.

```note
API key, mật khẩu và phiên đăng nhập là dữ liệu nhạy cảm. README cảnh báo model-written Python, ảnh chụp màn hình, JavaScript đọc trường nhập và cloud live view vẫn có thể làm lộ giá trị. Với tác vụ không tin cậy, nên dùng container hoặc máy ảo.
```

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

```steps
- Chuẩn bị Python | Cài Python 3.11 trở lên và mở terminal
- Tạo dự án | Khởi tạo thư mục Python bằng uv hoặc virtual environment
- Cài browser-use | Cài đúng phiên bản 1.0.3 được README ghim
- Cấu hình key | Đặt BROWSER_USE_API_KEY hoặc key của model riêng
- Chạy agent | Tạo một task Python và đọc kết quả
```

### Chuẩn bị thư mục làm việc

Mở Terminal, PowerShell hoặc công cụ dòng lệnh bạn thường dùng. README cho phép tạo dự án bằng `uv`; lệnh dưới đây đồng thời tạo dự án với Python 3.12 và chuyển vào thư mục `my-agent`.

```bash
uv init --python 3.12 my-agent && cd my-agent
```

Nếu bạn không dùng `uv`, có thể tạo virtual environment bằng Python. Lệnh tiếp theo tạo thư mục `.venv`, kích hoạt môi trường và cài gói bằng `pip`.

```bash
python3 -m venv.venv && source.venv/bin/activate
```

Trên Windows, phần `source.venv/bin/activate` không phải cú pháp PowerShell. README không ghi lệnh kích hoạt riêng cho Windows, nên bạn cần dùng cách kích hoạt virtual environment tương ứng với terminal của mình. Không nên chạy `pip` vào môi trường hệ thống nếu bạn chưa kiểm soát rõ Python nào đang được dùng.

### Cài đúng phiên bản thư viện

Nếu đã dùng `uv`, chạy lệnh sau trong thư mục dự án:

```bash
uv add 'browser-use==1.0.3'
```

Nếu đã tạo virtual environment bằng `pip`, dùng:

```bash
pip install 'browser-use==1.0.3'
```

README yêu cầu ghim chính xác phiên bản bằng `==`, không dùng `>=`. Lý do là browser-use phát hành nhanh và một bản mới hoặc dependency mới có thể làm hỏng API. Bạn nên nâng cấp có chủ đích sau khi đọc release notes.

README không đưa lệnh clone repo để chạy trực tiếp source. Nếu bạn muốn lấy mã nguồn, có thể clone repo GitHub bằng lệnh phổ thông dưới đây rồi xem `README.md`, `pyproject.toml`, `Dockerfile` và các thư mục `examples/`, `tests/` để biết thêm cấu trúc. Tuy nhiên, cách cài nhanh trong README là cài gói `browser-use` từ môi trường Python.

```bash
git clone https://github.com/browser-use/browser-use.git
cd browser-use
```

### Cấu hình Browser Use Cloud

Với cách chạy mặc định, đặt API key vào biến môi trường:

```bash
export BROWSER_USE_API_KEY=bu_...
```

README cũng cho biết bạn có thể dùng file `.env`. Trong repo có `.env.example` và tên biến được nêu là `BROWSER_USE_API_KEY`. Hãy điền key vào cấu hình của môi trường bạn chạy chương trình, không đưa key vào mã nguồn công khai.

### Tạo chương trình đầu tiên

Tạo một file Python trong dự án và đặt đoạn mã sau vào đó. Đây là nguyên văn ví dụ trong README:

```python
from browser_use import Agent

result = Agent('Find the number of stars of the browser-use repo').run_sync()
print(result.final_result())
```

Đoạn mã tạo một `Agent`, giao nhiệm vụ tìm số sao của repo rồi chạy đồng bộ. Khi chạy với cấu hình mặc định, model là `bu-fast` trên Browser Use gateway và trình duyệt là Browser Use Cloud browser. Một trình duyệt Cloud được dừng khi lần chạy kết thúc.

### Chạy với model và trình duyệt cục bộ

Nếu không muốn dùng model mặc định, README có ví dụ kết nối OpenAI và Chrome/Chromium cục bộ:

```python
from browser_use import Agent, Browser, ChatOpenAI

agent = Agent(
 'Find the number of stars of the browser-use repo',
 llm=ChatOpenAI('gpt-6-luna'), # OPENAI_API_KEY; or ChatOpenAI(model, base_url=...) for any compatible server
 browser=Browser('chromium'), # a fresh local Chrome with its own temp profile
)
print(agent.run_sync().final_result()) # in async code: result = await agent.run()
```

Bạn cần `OPENAI_API_KEY` khi dùng `ChatOpenAI` theo ví dụ. `Browser('chromium')` tạo Chrome, Chromium hoặc Edge cục bộ với profile tạm; profile bị xoá sau khi chạy. Nếu không có màn hình, chẳng hạn trong Docker hoặc CI, trình duyệt chạy headless.

`Browser('chrome')` điều khiển Chrome đang mở và dùng các phiên đăng nhập của bạn. `Browser('chrome', profile='Work')` tạo một bản sao tạm của profile `Work`; Chrome hiện tại có thể vẫn mở, ngoại trừ giới hạn được README lưu ý trên Windows.

### Cài CLI nếu muốn dùng qua coding agent

README cung cấp một prompt để dán vào Claude Code, Codex, Hermes, OpenClaw hoặc agent tương tự. Prompt đó yêu cầu agent cài CLI, đăng ký skill và kết nối vào trình duyệt:

```text
Install browser-use with `uv tool install browser-use==1.0.3`, run `browser-use skill install` to register the skill, and connect it to my browser. If setup or connection fails, run `browser-use --doctor` and follow its output and the error message.
```

Các lệnh quan trọng trong prompt là `uv tool install browser-use==1.0.3`, `browser-use skill install` và `browser-use --doctor`. Nếu kết nối không thành công, README hướng dẫn chạy doctor rồi làm theo lỗi được hiển thị.

## Kiểm tra đã chạy được chưa

Cách kiểm tra đơn giản nhất là chạy chương trình Python có `Agent(...).run_sync()` và xem `print(result.final_result())` có trả về câu trả lời cho task hay không. Với ví dụ trong README, kết quả mong đợi là số sao của repo được agent tìm thấy.

Nếu dùng Cloud mặc định, lần chạy cần có `BROWSER_USE_API_KEY`. Nếu dùng `ChatOpenAI`, cần `OPENAI_API_KEY`. Khi agent chạy, bạn có thể quan sát nó mở trình duyệt, thực hiện thao tác và trả kết quả về REPL.

Nếu kiểm tra CLI, cài thành công khi lệnh `browser-use skill install` đăng ký được skill và agent kết nối được vào browser. Khi có lỗi thiết lập hoặc kết nối, chạy `browser-use --doctor`.

Khi chạy tác vụ tải tệp, kiểm tra thư mục `agent.workspace/downloads` hoặc thuộc tính `result.downloads`. Khi dùng kết quả có cấu trúc, kiểm tra `result.structured_output` thay vì chỉ đọc chuỗi văn bản.

## Dùng vào việc thật

### Chủ shop kiểm tra giá và tồn kho

Chủ shop có thể giao một task yêu cầu mở các trang sản phẩm được phép, đọc giá hoặc tình trạng còn hàng rồi trả về danh sách. Nên giới hạn miền bằng `allowed_domains` nếu quy trình chỉ cần làm việc trên một số website. Kết quả có thể được yêu cầu theo schema để dễ đưa sang bảng tính.

Ví dụ task: `Kiểm tra giá và tình trạng còn hàng của các sản phẩm trong workspace, rồi trả về tên sản phẩm, giá và trạng thái.` Nếu cần dùng file danh sách, truyền file qua `workspace=...` và nêu tên file trong task; README cho biết agent có thể đặt tệp vào ô nhập bằng `upload_file(selector, path)`.

### Nhân viên văn phòng điền biểu mẫu

Nhân viên có thể dùng `Browser('chrome')` để điều khiển Chrome đang mở với các phiên đăng nhập hiện có, hoặc dùng profile Cloud để giữ đăng nhập giữa các lần chạy. Task có thể yêu cầu mở biểu mẫu, điền các trường từ tài liệu và dừng trước bước gửi cuối để người dùng kiểm tra.

Với dữ liệu nhạy cảm, truyền mật khẩu qua `sensitive_data` và để agent gọi `type_secret`. Không nên viết mật khẩu trực tiếp vào prompt hoặc mã nguồn. README nhấn mạnh rằng cơ chế này giúp che giá trị trong nhiều đầu ra nhưng không phải sandbox tuyệt đối.

### Dev xây agent tìm và tải tài liệu

Dev có thể giao task tìm một tài liệu trên web, mở trang phù hợp và tải tệp xuống workspace. Các file tải xuống nằm trong `agent.workspace/downloads`, còn `result.downloads` liệt kê file của lần chạy. Nếu có nhiều file trùng tên, hệ thống thêm ` (1)` để không ghi đè.

Nếu agent chỉ được phép truy cập nguồn nội bộ hoặc miền cố định, dùng `Browser(allowed_domains=['example.com', '*.example.org'])`. Đây là ví dụ cú pháp được README mô tả; bạn cần thay bằng miền thật của quy trình.

### Đội kỹ thuật chạy quy trình lặp lại

Đội kỹ thuật có thể viết custom tool bằng hàm Python có decorator `@tools.action('description')`, sau đó truyền `tools=tools` vào `Agent`. Có thể dùng `Browser(keep_alive=True)` để giữ cùng trang giữa các task và gọi `agent.add_new_task('...')` cho bước tiếp theo.

Nếu cần dữ liệu có thể xử lý tự động, dùng `Agent(task, output_model_schema=MyModel)` rồi đọc `result.structured_output`. Nếu cần tìm kiếm web, bật `Agent(task, web_search=True)`, nhưng README nói tính năng này cần Browser Use key và bị tính phí theo lượt tìm kiếm.

> Hãy giao cho agent một việc rõ ràng, giới hạn miền cần truy cập và kiểm tra kết quả trước khi để nó gửi biểu mẫu hoặc đặt dịch vụ.
>
> — Ông T

## Lỗi hay gặp và cách xử lý

### Python quá cũ

Nếu Python thấp hơn 3.11, gói không đáp ứng yêu cầu trong `pyproject.toml`. Hãy cài Python 3.11 trở lên và tạo lại virtual environment bằng đúng phiên bản đó.

### Cài nhầm phiên bản mới không tương thích

Không dùng `browser-use>=1.0.3` hoặc bỏ ghim phiên bản khi làm theo quickstart. README yêu cầu dùng chính xác `browser-use==1.0.3` vì API và dependency có thể thay đổi nhanh.

### Thiếu API key

Cách chạy mặc định dùng Browser Use gateway và Cloud browser, nên thiếu `BROWSER_USE_API_KEY` có thể khiến agent không chạy được. Kiểm tra biến môi trường hoặc file `.env`; nếu dùng model riêng, kiểm tra thêm key của nhà cung cấp tương ứng.

### Không kết nối được Chrome đang mở

Với `Browser('chrome')`, cần bật `chrome://inspect/#remote-debugging` một lần. Nếu vẫn lỗi, thử `Browser('chromium')` để dùng một trình duyệt mới với profile tạm, hoặc chạy `browser-use --doctor` nếu đang dùng CLI.

### Tin rằng giới hạn miền là sandbox

`allowed_domains` và `prohibited_domains` là guard cho model, không phải hàng rào bảo mật tuyệt đối. README cảnh báo request của trang, iframe, hình ảnh, JavaScript và mạng Python riêng có thể vượt ra ngoài phạm vi mong muốn. Với task không tin cậy, hãy dùng container hoặc máy ảo.

## Có nên dùng không

browser-use đáng dùng nếu bạn muốn xây agent AI thao tác trên website thật mà không phải tự viết toàn bộ logic nhấp, nhập và đọc trang. Repo có ba hướng triển khai, hỗ trợ trình duyệt cục bộ lẫn Cloud, có xử lý file, kết quả có cấu trúc, custom tool, profile đăng nhập và giới hạn miền. Giấy phép MIT cũng phù hợp cho nhiều dự án cá nhân và doanh nghiệp.

Giới hạn lớn là thư viện thay đổi nhanh, nên phải ghim phiên bản và kiểm tra khi nâng cấp. Agent vẫn có thể hiểu sai task, thao tác nhầm hoặc gặp CAPTCHA; Cloud có solver nhưng README không đảm trang tin tức đó challenge đều được xử lý. Dữ liệu nhạy cảm cũng cần đánh giá riêng vì model-written Python, ảnh chụp màn hình và live view có thể làm lộ thông tin.

Chọn CLI nếu bạn chỉ muốn trao quyền truy cập trình duyệt cho một coding agent. Chọn Cloud API nếu muốn gửi task đến hạ tầng được quản lý sẵn. Chọn thư viện Python nếu bạn cần nhúng agent vào ứng dụng, tự chọn model, thêm tool và kiểm soát luồng xử lý. Nếu quy trình rất cố định, yêu cầu bảo mật nghiêm ngặt hoặc không chấp nhận thao tác không dự đoán được, một automation script truyền thống có thể phù hợp hơn.

## Câu hỏi thường gặp

### browser-use có miễn phí không?

Thư viện Python là mã nguồn mở và dùng giấy phép MIT. Tuy nhiên, model inference và trình duyệt hosted là các phần riêng; nhà cung cấp API, ChatBrowserUse và Browser Use Cloud có thể tính phí theo mức sử dụng. Bạn cũng có thể dùng trình duyệt cục bộ với model cục bộ như Ollama.

### Có cần GPU để chạy browser-use không?

README không nói rằng bạn phải có GPU. Tài liệu chỉ yêu cầu Python 3.11 trở lên và cho phép dùng model Cloud, model API hoặc model cục bộ qua endpoint tương thích.

### Có chạy được trên Windows không?

README không nêu danh sách hệ điều hành được hỗ trợ riêng. Tài liệu có lưu ý `Browser('chrome', profile='Work')` có giới hạn khi Chrome hiện tại vẫn mở trên Windows, còn lệnh kích hoạt virtual environment trên Windows không được ghi cụ thể.

### Dữ liệu và mật khẩu có an toàn không?

README có cơ chế `sensitive_data` để che mật khẩu trong cell output, checkpoint, tool result, task và result. Tuy vậy, đây không phải sandbox: mã Python do model viết, ảnh chụp màn hình, JavaScript đọc trường và cloud live view vẫn có thể làm lộ giá trị.

### browser-use khác gì automation script thông thường?

browser-use cho model tự viết Python trong một REPL liên tục và điều khiển browser qua CDP. Bạn giao task bằng ngôn ngữ tự nhiên, thay vì phải tự viết toàn bộ chuỗi selector và thao tác cố định.

### Có thể dùng trình duyệt đang đăng nhập sẵn không?

Có. `Browser('chrome')` điều khiển Chrome đang mở với các phiên đăng nhập hiện có, sau khi bật `chrome://inspect/#remote-debugging`. README cũng mô tả profile Cloud và profile tạm để giữ hoặc sao chép trạng thái đăng nhập.
