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

> browser-use là thư viện Python mã nguồn mở (giấy phép MIT) cho phép một mô hình AI điều khiển trình duyệt Chrome thật để làm việc bạn giao bằng lời. Bạn có thể dùng nó theo 3 cách: API đám mây, CLI gắn vào Claude Code hay Codex, hoặc thư viện Python. Cài đặt chỉ vài lệnh, cần Python 3.11 trở lên và một API key nếu dùng cách mặc định.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-09-13 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/browser-use-ai-tu-thao-tac-trinh-duyet-huong-dan-cai-dat-va-dung

browser-use là một thư viện Python mã nguồn mở giúp AI tự mở trình duyệt thật và làm việc trên web giống người: mở tab, bấm nút, điền form, đọc nội dung, rồi trả kết quả cho bạn. Bạn chỉ cần viết một câu nhiệm vụ bằng chữ thường, ví dụ “tìm số sao của repo browser-use”. Mô hình sẽ tự viết mã Python để điều khiển Chrome.

Repo này hợp với ba nhóm người. Nhóm thứ nhất là lập trình viên muốn nhúng một “nhân viên ảo biết duyệt web” vào ứng dụng của mình. Nhóm thứ hai là người đang dùng Claude Code, Codex hay một agent khác và muốn agent đó có thêm khả năng thao tác trình duyệt. Nhóm thứ ba là người làm kinh doanh, văn phòng có những việc lặp lại trên web (tra giá, điền biểu mẫu, tải báo cáo) và đã quen chạy vài lệnh trong terminal.

Điểm đáng giá nhất là cách làm gọn. README tóm tắt: mô hình, một REPL (khung chạy mã) và giao thức Chrome DevTools Protocol (CDP), vậy là đủ một agent. Bạn chọn được mô hình nào cũng chạy, chọn được chạy trên máy mình hoặc trên đám mây của chính hãng. Hiện repo có khoảng 120.844 sao và 13.506 fork trên GitHub, và vẫn được cập nhật trong 3 tháng gần đây.

```repo
- repo | browser-use/browser-use
- kind | Thư viện
- desc | Thư viện Python mã nguồn mở để AI tự mở trình duyệt thật, bấm, gõ, đọc trang web và làm xong việc bạn giao.
- stars | 121k
- lang | Python
- license | MIT
```

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

**Tự làm việc trong trình duyệt thật.** Bạn giao nhiệm vụ, mô hình viết từng đoạn mã nhỏ, REPL chạy trên Chrome qua CDP, kết quả trả ngược lại cho mô hình, cứ thế đến khi xong. Lợi ích: bạn không phải viết kịch bản bấm nút cho từng trang web.

**Ba cách dùng, chọn theo nhu cầu.** Bạn có thể dùng bản đám mây trọn gói (hãng chạy cả agent lẫn trình duyệt), dùng CLI để agent sẵn có của bạn điều khiển trình duyệt, hoặc dùng thư viện Python để tự lập trình. Người mới nên thử CLI hoặc thư viện trước.

**Chọn trình duyệt tuỳ ý.** `Browser()` là trình duyệt đám mây (mặc định). `Browser('chromium')` mở một Chrome mới với hồ sơ tạm, xoá sau khi chạy xong. `Browser('chrome')` điều khiển chính Chrome bạn đang mở, kèm các tài khoản đã đăng nhập. Nhờ vậy việc cần đăng nhập sẵn cũng làm được.

**Chọn mô hình tuỳ ý.** Có sẵn `ChatOpenAI`, `ChatAnthropic`, `ChatGoogle`. Ngoài ra bạn có thể dùng chuỗi tên mô hình của Pydantic AI. README còn nói bạn có thể chạy mô hình cục bộ, ví dụ Ollama, thông qua `ChatOpenAI` với địa chỉ máy bạn.

**Kết quả có cấu trúc.** Dùng `output_model_schema` để bắt agent trả dữ liệu đúng khuôn (ví dụ tên sản phẩm và giá), lấy ra bằng `result.structured_output`. Rất tiện khi bạn muốn đưa kết quả vào bảng tính hay cơ sở dữ liệu.

**Tải lên và tải xuống tệp.** Đặt tệp vào `workspace`, nêu tên trong nhiệm vụ, agent sẽ chọn tệp vào ô tải lên. File trình duyệt tải về nằm trong `agent.workspace/downloads`, và `result.downloads` liệt kê chúng.

**Bảo vệ mật khẩu ở mức cơ bản.** Truyền mật khẩu qua `sensitive_data`, mô hình gõ bằng `type_secret`, còn giá trị bị thay bằng `<secret:password>` trong kết quả. Bạn cũng có thể gắn mật khẩu với một tên miền cụ thể. README nói rõ đây không phải hộp cát an toàn tuyệt đối, mình sẽ nhắc lại ở phần lưu ý.

**Giới hạn trang web được vào.** `allowed_domains`, `prohibited_domains`, `block_ip_addresses=True` giúp agent không đi lung tung sang trang bạn không muốn.

**Thêm bớt tính năng.** Có công cụ tự viết (`@tools.action`), chế độ `mode='ultrafast'`, chạy tiếp nhiệm vụ mới trên cùng trang với `add_new_task` và `keep_alive=True`, và tìm kiếm web `web_search=True` (tắt mặc định, cần key của Browser Use).

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

Theo tư liệu, bạn cần:

- **Python 3.11 trở lên** (file `pyproject.toml` ghi `>=3.11,<4.0`). Cách cài dùng `uv`, hoặc `pip` trong môi trường ảo (venv).
- **Một API key** nếu dùng cấu hình mặc định. README ghi: lấy key ở trang cloud.browser-use.com, dạng `bu_...`. Key này trả tiền cho cả mô hình lẫn trình duyệt đám mây, và cũng dùng được cho CLI và MCP server. Người đăng ký mới bằng Google, GitHub hoặc Microsoft được tặng 1 đô la tín dụng đám mây.
- **Hoặc key của nhà cung cấp mô hình riêng** (ví dụ `OPENAI_API_KEY`) nếu bạn muốn dùng `ChatOpenAI` với trình duyệt chạy trên máy.
- **Chrome hoặc Chromium** nếu chạy trình duyệt cục bộ. Với `Browser('chrome')`, bạn cần bật `chrome://inspect/#remote-debugging` một lần.
- **Terminal**: Terminal trên macOS/Linux, hoặc PowerShell/Git Bash trên Windows.

Tư liệu không nêu yêu cầu card đồ hoạ (GPU) hay dung lượng RAM tối thiểu. Phần cứng chỉ cần nếu bạn tự chạy mô hình cục bộ, và README không nói cụ thể.

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

```steps
- Mở terminal | Mở cửa sổ dòng lệnh, kiểm tra có Python 3.11 trở lên
- Tạo dự án | Dùng uv (hoặc venv) tạo thư mục dự án riêng
- Cài gói | Cài browser-use đúng phiên bản 1.0.3
- Lấy và đặt key | Tạo API key và gán vào BROWSER_USE_API_KEY
- Chạy thử | Chạy đoạn Python 3 dòng đầu tiên
```

README có hai đường cài cho thư viện Python: dùng `uv` hoặc dùng `pip` trong venv. Bạn chọn một. Nếu bạn chỉ muốn gắn khả năng duyệt web cho Claude Code hay Codex, đọc thêm phần CLI ở cuối mục này.

### Mở terminal và chọn cách cài

Trên Windows, bạn mở PowerShell. Trên Mac, mở Terminal. Gõ `python --version` (hoặc `python3 --version`) để kiểm tra Python từ 3.11 trở lên. Nếu thấp hơn, cách `uv` bên dưới cho phép chỉ định `--python 3.12` khi tạo dự án.

### Cách A: cài bằng uv

Lệnh dưới tạo thư mục dự án tên `my-agent`, đi vào thư mục đó, rồi cài gói. Lưu ý phải chạy tiếp các lệnh trong thư mục `my-agent`, vì đó là chỗ người mới hay quên.

```bash
uv init --python 3.12 my-agent && cd my-agent
uv add 'browser-use==1.0.3'
export BROWSER_USE_API_KEY=bu_...    # get one at https://cloud.browser-use.com/new-api-key
```

Dòng `export` gán key vào biến môi trường cho phiên terminal hiện tại. Thay `bu_...` bằng key thật của bạn. Khi đóng terminal, biến này mất, bạn phải gán lại (hoặc dùng file `.env`, README nói file `.env` cũng chạy được).

### Cách B: cài bằng pip trong venv

Cách này dành cho bạn đã quen `pip`. Lệnh đầu tạo môi trường ảo tên `.venv` và kích hoạt nó. Lệnh sau cài gói.

```bash
python3 -m venv .venv && source .venv/bin/activate
pip install 'browser-use==1.0.3'
export BROWSER_USE_API_KEY=bu_...
```

Các lệnh trên theo kiểu macOS/Linux. README chưa ghi riêng lệnh kích hoạt venv và gán biến môi trường cho Windows. Nếu bạn dùng PowerShell, cách gán biến thông thường là lệnh dưới đây, nhưng bạn nên xem lại tài liệu trên trang docs.browser-use.com nếu gặp vướng mắc.

```powershell
$env:BROWSER_USE_API_KEY = "bu_..."
```

### Ghim đúng phiên bản

README nhấn mạnh việc ghim chính xác phiên bản bằng `==`, không dùng `>=`. Lý do: bản mới ra nhanh và có thể làm hỏng API cũ. Bạn chỉ nâng cấp khi đã đọc ghi chú phát hành. Đó là lý do các lệnh trên đều có `==1.0.3`.

### Chạy thử bằng đoạn mã ngắn

Tạo một file, ví dụ `thu.py`, dán đoạn sau và chạy `python thu.py` (hoặc `uv run python thu.py`).

```python
from browser_use import Agent

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

Mặc định, agent dùng mô hình `bu-fast` trên cổng của Browser Use và một trình duyệt đám mây, tự dừng khi chạy xong. Một key lo cả mô hình lẫn trình duyệt.

### Muốn chạy trình duyệt trên máy và dùng mô hình riêng

Đoạn sau chép từ README: Chrome mới trên máy bạn, mô hình của OpenAI. Bạn cần đặt `OPENAI_API_KEY`.

```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()
```

### Nếu bạn chỉ cần CLI cho agent có sẵn

README gợi ý dán nguyên lời nhắc sau vào Claude Code, Codex, Hermes, OpenClaw hoặc agent bạn dùng, rồi để agent tự cài:

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

Nếu cài thất bại, lệnh `browser-use --doctor` là công cụ chẩn đoán README khuyên chạy trước tiên.

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

Với thư viện Python, bài kiểm tra là đoạn mã 3 dòng ở trên. Nếu mọi thứ đúng, agent mở một trình duyệt, tìm trang repo và `print` ra số sao. Bạn sẽ thấy một dòng văn bản trả lời ở terminal. Con số cụ thể thay đổi theo thời điểm nên không cần so khớp với bài này.

Nếu dùng `Browser('chromium')`, bạn sẽ thấy một cửa sổ Chrome mới hiện lên (hoặc chạy ẩn nếu máy không có màn hình, như trong Docker hay CI). Khi chạy xong, hồ sơ tạm bị xoá.

Với CLI, chạy `browser-use --doctor` để chẩn đoán. README chưa mô tả kết quả mong đợi chi tiết, nên bạn đọc đầu ra của lệnh và làm theo gợi ý. Một cách kiểm tra khác: nhờ agent của bạn mở một trang web đơn giản và đọc lại tiêu đề.

Bạn cũng có thể kiểm tra chi phí qua `result.cost_usd`, theo README đây là nơi cộng dồn các khoản phí tìm kiếm khi bật `web_search`.

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

Các tình huống dưới đây là ví dụ mình dựng từ khả năng có trong README. Câu lệnh mẫu bạn có thể đổi cho hợp việc của mình.

### Chủ shop theo dõi giá đối thủ

Bạn bán đồ gia dụng online và muốn biết giá một mẫu máy xay trên vài trang khác. Thay vì mở từng trang, bạn nhờ agent tra giá và trả dữ liệu có khuôn, để dán vào bảng tính. Bạn định nghĩa một mô hình dữ liệu (ví dụ tên sản phẩm, giá) rồi truyền vào `output_model_schema`.

```python
agent = Agent(
    'Mo trang ABC, tim may xay sinh to Philips va cho biet gia hien tai',
    output_model_schema=MyModel,
)
result = agent.run_sync()
print(result.structured_output)
```

Bạn nhận được dữ liệu đúng cấu trúc đã khai báo thay vì một đoạn văn dài. `MyModel` là lớp dữ liệu bạn tự định nghĩa theo tên gọi trong README. Nên thêm `allowed_domains` vào `Browser(...)` để agent chỉ ở trong những trang bạn đã chọn.

> Mô hình, một REPL và CDP. Vậy là xong cả một con agent.
>
> — Ông T

### Nhân viên văn phòng tải báo cáo từ trang cần đăng nhập

Mỗi sáng bạn phải vào một cổng nội bộ, đăng nhập, tìm báo cáo và tải về. Bạn đã đăng nhập sẵn trên Chrome của mình, nên dùng `Browser('chrome')` để agent điều khiển đúng Chrome đó (nhớ bật `chrome://inspect/#remote-debugging` một lần). Bạn giao: “Vào mục báo cáo, tải báo cáo tuần mới nhất”. File tải về nằm trong `agent.workspace/downloads`, danh sách có ở `result.downloads`. Nếu cần mật khẩu, dùng `sensitive_data` thay vì viết thẳng vào câu nhiệm vụ.

### Lập trình viên thêm công cụ riêng và giữ ngữ cảnh

Bạn đang làm một ứng dụng nội bộ và muốn agent gọi hàm của mình (ví dụ ghi kết quả vào hệ thống). README cho phép viết hàm Python thường, gắn `@tools.action('mô tả')`, rồi truyền `tools=tools` vào `Agent`. Muốn giao việc tiếp theo trên cùng trang, bạn dùng `Browser(keep_alive=True)`, gọi `agent.add_new_task('...')` rồi `await agent.run()`. Kết quả là agent làm tuần tự nhiều bước mà không phải mở lại từ đầu.

### Gắn khả năng duyệt web cho Claude Code

Bạn đã dùng Claude Code để viết mã và muốn nó tự kiểm tra một trang web sau khi sửa. Dán lời nhắc CLI ở phần cài đặt vào Claude Code. Sau khi cài, bạn có thể nói thẳng với nó: “mở trang đăng ký của mình, thử điền form và cho biết có lỗi gì không”. Kết quả: agent của bạn có thêm khả năng nhìn và bấm trên trình duyệt thật, và bạn dùng được tương tác hoặc đưa vào script.

```note
Agent có thể thao tác trên tài khoản đã đăng nhập, nên hãy giao việc cụ thể và giới hạn tên miền bằng allowed_domains. Không dán mật khẩu vào câu nhiệm vụ. Cân nhắc dùng hồ sơ trình duyệt riêng, không dùng Chrome chứa tài khoản ngân hàng hay email quan trọng. Chi phí mô hình và trình duyệt đám mây tính theo mức dùng, nên đặt hạn mức trước khi chạy hàng loạt.
```

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

**Chạy mà báo thiếu key hoặc không xác thực được.** Biến `BROWSER_USE_API_KEY` chưa được gán trong phiên terminal hiện tại, hoặc bạn mở terminal mới sau khi `export`. Gán lại biến, hoặc đưa vào file `.env` như README cho phép. Nếu bạn dùng `ChatOpenAI`, kiểm tra thêm `OPENAI_API_KEY`.

**Python quá cũ.** Gói yêu cầu Python 3.11 trở lên. Nếu máy báo lỗi phiên bản, tạo dự án bằng `uv init --python 3.12` như README, thay vì dùng Python hệ thống cũ.

**Nâng cấp xong thì mã cũ hỏng.** README cảnh báo bản mới ra nhanh và có thể phá API. Hãy ghim `==1.0.3`, nâng cấp có chủ đích sau khi đọc ghi chú phát hành. Nếu bạn đến từ bản 0.x, đọc file `MIGRATING.md` trong repo.

**`Browser('chrome')` không kết nối được.** Bạn chưa bật tuỳ chọn gỡ lỗi từ xa. Mở `chrome://inspect/#remote-debugging` và bật một lần, theo README. Với `Browser('chrome', profile='Work')`, README ghi Chrome của bạn có thể vẫn mở, trừ trên Windows.

**Agent gặp CAPTCHA hoặc bị chặn.** README nói trình duyệt đám mây có trình giải CAPTCHA và proxy để giảm khả năng bị chặn, nhưng kết quả phụ thuộc từng trang, không có gì đảm bảo luôn vượt được. Nếu thất bại, thử trình duyệt đám mây, hoặc chọn cách khác như API chính thức của trang. Khi bị lỗi lạ, chạy `browser-use --doctor` hoặc gửi phản hồi bằng `browser-use feedback 'what happened'`.

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

**Điểm mạnh.** Mã nguồn mở, giấy phép MIT. Cách tiếp cận gọn và linh hoạt: chọn mô hình, chọn trình duyệt, chạy trên máy hay trên đám mây. Có đường vào cho cả người không viết mã (CLI gắn vào agent có sẵn) lẫn lập trình viên (thư viện, công cụ tự viết, kết quả có cấu trúc). Repo có cộng đồng lớn và được cập nhật gần đây.

**Giới hạn.** Thư viện miễn phí nhưng mô hình và trình duyệt đám mây tính phí theo mức dùng. README chưa có hướng dẫn riêng cho Windows ở phần cài đặt. Chức năng bảo mật chỉ là lớp bảo vệ, không phải hộp cát: mã do mô hình viết có thể đọc được bí mật, và ảnh chụp màn hình hay live view có thể lộ giá trị đã gõ. Cổng gỡ lỗi của `Browser('chromium')` và `Browser('chrome', profile=...)` không có xác thực, nên trên máy dùng chung hãy dùng container hoặc trình duyệt đám mây. Bản phát hành đổi nhanh nên bạn phải ghim phiên bản.

**Khi nên chọn cách khác.** Nếu trang bạn cần có API chính thức, dùng API sẽ ổn định và rẻ hơn. Nếu việc lặp lại cố định, một kịch bản tự động hoá truyền thống có thể đủ. Nếu bạn không muốn đụng đến terminal, repo này chưa phải công cụ bấm là chạy. Còn nếu bạn muốn AI thay mình làm những việc trên web mà không có API, browser-use rất đáng thử, nhưng hãy bắt đầu bằng việc nhỏ và theo dõi chi phí.

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

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

Thư viện Python miễn phí, theo giấy phép MIT. Tuy nhiên việc chạy mô hình AI và trình duyệt đám mây thì tính phí theo mức dùng. README cũng nói bạn có thể dùng `Browser('chromium')` kèm mô hình cục bộ như Ollama để không phụ thuộc dịch vụ trả phí.

### Cần Python phiên bản nào?

File pyproject.toml yêu cầu Python 3.11 trở lên (dưới 4.0). README gợi ý tạo dự án bằng `uv init --python 3.12`, hoặc dùng pip trong môi trường ảo.

### Có cần GPU không?

Tư liệu không yêu cầu GPU để dùng thư viện. Mặc định, mô hình chạy qua cổng của Browser Use và trình duyệt là trình duyệt đám mây. Nếu bạn tự chạy mô hình cục bộ thì phần cứng phụ thuộc mô hình đó, README chưa có thông tin cụ thể.

### Chạy trên Windows được không?

README chưa có hướng dẫn riêng cho Windows. Có nhắc rằng với `Browser('chrome', profile='Work')`, Chrome của bạn có thể vẫn mở, trừ trên Windows. Các lệnh `export` trong README là kiểu macOS/Linux, nên trên Windows bạn cần dùng cách gán biến tương đương hoặc file `.env`.

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

Bạn truyền mật khẩu qua `sensitive_data`, và giá trị được thay bằng `<secret:tên>` trong kết quả. Nhưng README nói rõ đây không phải hộp cát: mã do mô hình viết có thể đọc được, và ảnh chụp màn hình hay live view có thể lộ giá trị. Với việc nhạy cảm, nên chạy trong container hoặc trình duyệt đám mây, và giới hạn tên miền cho agent.

### Khác gì dùng Claude Code hay Codex trực tiếp?

Claude Code, Codex và các agent tương tự là agent đa năng. browser-use cho chúng khả năng điều khiển trình duyệt thật thông qua CLI và skill. Bạn cũng có thể dùng thư viện Python để tự viết agent duyệt web riêng cho ứng dụng của mình.

### Agent có vượt được CAPTCHA không?

Trình duyệt đám mây của Browser Use có giải CAPTCHA tự động, stealth và proxy để giảm bị chặn. Tuy nhiên README nói rõ kết quả phụ thuộc vào trang và loại thử thách, không đảm bảo luôn vượt được.
