# Agentero: góc làm việc cho nhà nghiên cứu và Agent AI — hướng dẫn cài đặt và dùng

> Agentero là ứng dụng desktop (macOS, Windows, Linux) cho người đọc và viết nghiên cứu. Nó gom PDF, ghi chú và Agent AI vào một nơi, lưu tất cả thành file thường trên máy. Cài khá dễ: tải bộ cài từ trang chủ hoặc GitHub Releases, riêng macOS có thể dùng Homebrew.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-11-05 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/agentero-goc-lam-viec-nghien-cuu-cho-nguoi-va-agent-ai

Agentero là một ứng dụng desktop mã nguồn mở, giúp người và Agent AI cùng làm việc trên một kho tài liệu nghiên cứu. Bạn đọc PDF như bình thường. Còn AI nhận được bản nội dung đã được tách gọn thành Markdown và LaTeX, nên ít hiểu sai hơn. Bài báo, ghi chú và các lần hỏi đáp đều nằm trên máy của bạn.

Nếu bạn đang để bài báo ở một chỗ, ghi chú ở chỗ khác, còn trao đổi với AI thì nằm trong các khung chat rời rạc, thì repo này nhắm đúng vào chuyện đó. Mỗi lần nhờ AI phân tích một bài, bạn không còn phải copy dán qua lại. Người làm nghiên cứu, sinh viên sau đại học, hay bất kỳ ai hay đọc báo cáo PDF dài đều có thể thử. Tác giả viết dự án bằng TypeScript, giấy phép MIT, hiện có khoảng 2.436 sao và 151 fork.

Điểm đáng giá nhất là Agentero không bắt bạn dùng một AI cố định. Nó kết nối với Agent chạy trên máy bạn qua giao thức ACP, và còn chạy được như một MCP server cho các ứng dụng khác. Ngoài ra nó đọc được thư viện Zotero cũ của bạn, nên chuyển sang không mất công làm lại từ đầu.

```repo
- repo | poco-ai/Agentero
- kind | Ứng dụng
- desc | Ứng dụng desktop gom PDF, ghi chú và Agent AI vào một nơi: hỏi đáp bài báo có trích dẫn, kho tài liệu cục bộ, hỗ trợ MCP và CLI.
- stars | 2.4k
- lang | TypeScript
- license | MIT
```

## Agentero làm được gì

Tư liệu của repo chia thành bốn nhóm tính năng. Mình giải thích từng nhóm theo lợi ích khi dùng.

### Đọc PDF và ghi chú có cấu trúc

Trình đọc PDF có mục lục điều hướng, chỉnh cỡ trang theo cả trang hoặc theo chiều rộng, bôi chọn chữ mượt, tô sáng kèm chú thích và tìm kiếm toàn văn. Đây là phần dành cho bạn, đọc thoải mái như quen.

Phần dành cho AI là việc tự nhận diện công thức toán, mã giả thuật toán và bảng biểu trong bài, rồi chuyển thành Markdown và LaTeX. Theo tác giả, bài PDF hai cột, bảng nhiều trang hay công thức phức tạp rất dễ làm mô hình đọc sai. Bản cấu trúc giúp câu trả lời chính xác hơn.

Ngoài ra có trình soạn ghi chú Markdown kiểu soạn đến đâu thấy đến đó. Nó hỗ trợ liên kết hai chiều kiểu [[tên ghi chú]], lệnh nhanh bằng dấu `/` và hiển thị LaTeX trực tiếp. Ghi chú gắn thẳng với bài báo tương ứng. Về dịch thuật, có dịch khi bôi chọn, dịch đối chiếu theo trang và dịch toàn văn. Ứng dụng có sẵn kênh dịch dùng được, và bạn có thể điền API key riêng của mình (BYOK).

### Kết nối Agent và tự động hoá

Agentero dựa trên Agent Client Protocol (ACP). Theo README, bạn nối được các Agent chạy cục bộ như Claude Code, OpenCode, Codex hoặc mô hình chạy trên máy, không bị trói vào một hãng. Màn hình chia đôi cho phép bạn tô sáng bên trái, còn Agent bên phải trả lời dựa trên nội dung đã cấu trúc.

Nó cũng chạy được như MCP server. Nhờ đó ChatGPT Web hay Claude Desktop có thể tìm trong thư viện cục bộ của bạn làm ngữ cảnh. Cuối cùng là công cụ dòng lệnh không giao diện, dùng để viết script nhập hàng loạt tài liệu, lấy metadata và ghi ghi chú.

### Khám phá tài liệu mới

Trong app có sẵn Cool Papers và cộng đồng ModelScope (魔搭) để duyệt bài và lưu về một cú bấm. Bạn cũng đăng ký được RSS học thuật. Ứng dụng còn gợi ý bài arXiv mới mỗi ngày dựa trên nội dung thư viện hiện có, tự đọc danh sách tài liệu tham khảo cuối bài để nhập hàng loạt, và theo dõi bài nào trích dẫn tiếp.

### Tương thích Zotero, lưu trữ minh bạch

Bạn có thể nhập cả thư viện Zotero một lần, giữ nguyên thẻ, ghi chú và tệp đính kèm. Tiện ích trình duyệt của Zotero vẫn dùng để lưu bài từ web, và bạn xuất được BibTeX hoặc BibLaTeX. Dữ liệu không nằm trong cơ sở dữ liệu riêng mà là file PDF và Markdown trong thư mục thường, nên mở bằng trình soạn thảo khác vẫn được. Bạn cũng đồng bộ được với kho lưu trữ tương thích S3, hoặc truy cập thư viện đặt trên máy chủ từ xa qua SSH tunnel.

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

Theo README, bạn chỉ cần những thứ sau:

- Một máy macOS, Windows hoặc Linux. Với Linux, hệ điều hành cần là Ubuntu 22.04 trở lên vì phụ thuộc `webkit2gtk 4.1`.
- Nếu dùng Homebrew trên macOS, bạn cần đã cài Homebrew.
- Nếu muốn nhờ AI trả lời, bạn cần có sẵn Agent như Claude Code, OpenCode, Codex hoặc một mô hình cục bộ. Agentero kết nối tới chúng chứ không thay thế chúng.
- Nếu muốn dùng kênh dịch riêng, chuẩn bị API key của dịch vụ đó.
- Muốn đồng bộ nhiều máy thì cần một dịch vụ lưu trữ tương thích S3.

README không nói gì về yêu cầu GPU hay dung lượng ổ đĩa, nên mình không đoán ở đây.

```note
API key của dịch vụ dịch hoặc của Agent là của riêng bạn. Đừng dán key vào ghi chú, đừng chụp màn hình cấu hình rồi gửi công khai. Dùng dịch vụ có tính phí thì xem kỹ bảng giá của nhà cung cấp.
```

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

```steps
- Chọn cách cài | Bản desktop (tải bộ cài hoặc Homebrew) hoặc bản dòng lệnh
- Cài bản desktop | Tải từ trang chủ hoặc GitHub Releases, riêng macOS có thể dùng brew
- Cài bản dòng lệnh | Dùng Homebrew nếu bạn cần chạy script
- Kiểm tra lệnh | Gõ agentero --help để xem lệnh có sẵn
- Nối Agent | Cấu hình Agent trong phần Agent và kết nối của ứng dụng
```

### Chọn bản desktop hay dòng lệnh

Bản desktop là ứng dụng có giao diện, dành cho đa số người dùng. Bản dòng lệnh (CLI) dành cho người muốn viết script tự động. Bạn có thể cài một trong hai hoặc cả hai. Nếu mới bắt đầu, hãy cài bản desktop trước.

### Cài bản desktop trên Windows, Linux hoặc macOS

README hướng dẫn tải bộ cài dựng sẵn cho từng hệ điều hành từ trang chủ agentero.app hoặc trang GitHub Releases của dự án. Bạn mở một trong hai trang đó, chọn đúng file cho hệ điều hành của mình, tải về và chạy như mọi phần mềm khác. README không ghi tên file cụ thể, nên bạn nhìn trên trang Releases để chọn.

Với Linux, bạn cần Ubuntu 22.04 trở lên. README trỏ tới tài liệu cài đặt cho phần phụ thuộc chi tiết, bạn xem trong thư mục `docs/` của repo hoặc trang chủ.

### Cài bản desktop bằng Homebrew (macOS)

Mở ứng dụng Terminal trên máy Mac, rồi chạy hai lệnh sau. Lệnh đầu thêm kho phần mềm của tác giả, lệnh sau cài ứng dụng:

```bash
brew tap poco-ai/agentero
brew install --cask agentero
```

Chỗ người mới hay vấp là chữ `--cask`. Bạn cần gõ đúng, vì đó là lệnh cài ứng dụng có giao diện. Gõ thiếu thì bạn sẽ cài nhầm bản khác.

### Cài bản dòng lệnh

Nếu bạn muốn gọi Agentero từ terminal hoặc script, README dùng cách sau:

```bash
brew tap poco-ai/agentero
brew install agentero

# xem các lệnh thường dùng và tham số
agentero --help
```

Lệnh `agentero --help` in ra danh sách lệnh và tham số. Đây cũng là nơi bạn xem cách nhập tài liệu hàng loạt hay ghi ghi chú, vì README không liệt kê chi tiết từng lệnh con. README chỉ nói bản CLI cài qua Homebrew. Cách cài CLI trên Windows hay Linux không được ghi, nên bạn xem thêm trong thư mục `docs/` hoặc trang chủ.

Nếu bạn muốn tự build từ mã nguồn, repo có `package.json`, `Cargo.toml` và thư mục `src-tauri/`. README không hướng dẫn build, vì vậy hãy đọc `CONTRIBUTING.md` trước khi thử.

### Cài làm plugin cho DeepSeek Harness (tuỳ chọn)

Nếu bạn dùng DeepSeek Harness (dsh), README có lệnh cài plugin để dùng thư viện, ghi chú và trình đọc PDF của Agentero ngay trong đó:

```bash
dsh plugin --profile web add @poco-ai/agentero-dsh
```

Đây là mục dành cho người đã có dsh. Chi tiết nằm ở repo `agentero-dsh-plugin` mà README nhắc tới.

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

Với bản desktop, cách kiểm tra đơn giản nhất là mở ứng dụng lên và thấy giao diện chính hiện ra. Sau đó bạn thử nhập một file PDF bất kỳ và mở nó trong trình đọc. Nếu thấy mục lục, tô sáng và tìm kiếm hoạt động, nghĩa là cài ổn.

Với bản dòng lệnh, mở terminal mới và gõ:

```bash
agentero --help
```

Nếu máy in ra danh sách lệnh và tham số thì CLI đã sẵn sàng. Nếu báo không tìm thấy lệnh, xem mục lỗi bên dưới.

Tư liệu không mô tả màn hình hay thông báo cụ thể sau khi cài xong. Vì vậy mình chỉ nêu cách kiểm tra chung này, chưa có kết quả mong đợi chính thức nào để so.

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

Các tình huống dưới đây bám vào khả năng README đã nêu. Giao diện cụ thể có thể khác chút, nên bạn làm theo tên chức năng chứ đừng tìm đúng từng nút.

### Nghiên cứu sinh đọc một bài báo khó

Bạn đang đọc một bài có nhiều công thức và bảng. Mở bài trong Agentero, tô sáng đoạn chưa hiểu, rồi mở khung Agent bên phải. Nếu đã nối Claude Code hay Codex, bạn hỏi thẳng về đoạn đó, ví dụ: “Giải thích công thức trong phần phương pháp bằng lời đơn giản, và chỉ ra giả định nào quan trọng nhất.” Vì Agent nhận bản Markdown/LaTeX đã tách, câu trả lời ít sai hơn so với việc dán nguyên khối chữ từ PDF. Điểm hay nhất là bạn lưu luôn ý chính vào ghi chú cạnh bài, không cần mở thêm ứng dụng nào.

> Người đọc giữ phần phán đoán, Agent lo phần việc lặt vặt, và mọi thứ nằm cùng một chỗ.
>
> — Ông T

### Sinh viên làm tổng quan tài liệu

Bạn cần đọc lướt nhiều bài mới trong lĩnh vực của mình. Vào mục khám phá, duyệt Cool Papers hoặc RSS, bấm một lần để lưu bài đáng đọc vào thư viện. Ứng dụng còn gợi ý bài arXiv mới dựa trên những gì bạn đã lưu. Khi một bài có danh sách tài liệu tham khảo hay, bạn dùng chức năng đọc phần tham khảo cuối bài để nhập hàng loạt. Kết quả là thư viện lớn dần theo hướng bạn quan tâm, và bạn tiết kiệm được nhiều lần bấm tải thủ công.

### Người dùng Zotero muốn thử mà không mất dữ liệu

Bạn có sẵn thư viện Zotero nhiều năm và ngại chuyển. README nói bạn nhập được cả thư viện, giữ thẻ, ghi chú và tệp đính kèm. Trước tiên hãy sao lưu thư mục Zotero của bạn rồi mới nhập, để yên tâm. Tiện ích trình duyệt của Zotero vẫn dùng được để lưu bài từ web. Kết quả là bạn thử Agentero bằng dữ liệu thật mà không phải bỏ công cụ cũ ngay.

### Lập trình viên cần tự động hoá

Bạn có một danh sách bài tìm được từ công cụ tìm kiếm tự động và không muốn lưu từng bài bằng tay. Cài CLI rồi chạy `agentero --help` để xem lệnh nhập tài liệu, lấy metadata và ghi ghi chú, sau đó gom lại thành script. Bạn cũng có thể bật chế độ MCP server để Claude Desktop hay ChatGPT Web tìm trực tiếp trong thư viện cục bộ. Cách bật MCP và tên lệnh cụ thể README không ghi, nên bạn xem tài liệu trong `docs/`.

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

Tư liệu không liệt kê lỗi. Dưới đây là những điểm dễ vấp với loại ứng dụng này, mình nêu để bạn tham khảo.

### Gõ `agentero` báo không tìm thấy lệnh

Thường là do bạn vừa cài xong mà terminal cũ chưa nhận lệnh mới, hoặc cài nhầm bản cask (bản có giao diện) thay vì bản CLI. Đóng terminal, mở cái mới và thử lại. Nếu vẫn không được, chạy lại đúng lệnh `brew install agentero` (không có `--cask`).

### Linux không chạy hoặc thiếu thư viện

README yêu cầu Ubuntu 22.04 trở lên với `webkit2gtk 4.1`. Nếu bạn dùng bản cũ hơn, ứng dụng nhiều khả năng không chạy. Hãy kiểm tra phiên bản hệ điều hành và đọc tài liệu cài đặt trong repo trước khi cài.

### Agent không trả lời hoặc không kết nối được

Agentero chỉ làm cầu nối tới Agent mà bạn đã cài. Nếu Claude Code, OpenCode hay Codex chưa cài hoặc chưa đăng nhập, khung Agent sẽ không có gì để nói chuyện. Hãy kiểm tra Agent đó chạy được riêng trong terminal trước, rồi quay lại phần cấu hình Agent trong ứng dụng.

### Dịch thuật không chạy khi dùng key riêng

Nếu bạn nhập API key riêng (BYOK) mà không dịch được, hãy kiểm tra lại key có đúng, còn hạn mức và đúng dịch vụ không. Nếu cần, quay về kênh dịch có sẵn trong ứng dụng để so sánh.

### Nhập thư viện Zotero lớn bị chậm hoặc không như ý

Thư viện nhiều năm có thể rất nặng. Hãy sao lưu trước, nhập khi máy rảnh, và kiểm tra thử vài bài sau khi nhập. Nếu có gì lạ, mở một issue trên GitHub của dự án kèm mô tả rõ.

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

Điểm mạnh của Agentero là tích hợp. Đọc PDF, ghi chú, dịch, tìm bài mới và hỏi đáp với Agent nằm trong một ứng dụng. Dữ liệu là file thường trên máy, nên bạn không bị khoá vào định dạng riêng. Việc hỗ trợ ACP, MCP và CLI cho thấy dự án thật sự nghĩ đến chuyện làm việc với Agent. Giấy phép MIT và repo còn được cập nhật trong vài tháng gần đây cũng là tín hiệu tốt.

Giới hạn cũng cần nói rõ. README chủ yếu viết bằng tiếng Trung (có bản tiếng Anh), nhiều nguồn tích hợp như Cool Papers và ModelScope nghiêng về cộng đồng Trung Quốc. README không ghi cách cài CLI ngoài Homebrew, không nêu yêu cầu phần cứng và không có kết quả đánh giá độ chính xác của việc tách công thức. Ứng dụng cũng không thay được bạn trong việc kiểm chứng câu trả lời của AI.

Nếu bạn đang dùng Zotero ổn định và chỉ cần quản lý trích dẫn, chưa cần Agent, thì chưa chắc phải chuyển. Còn nếu bạn hay phải copy dán giữa bài báo, ghi chú và AI, thì đây là công cụ đáng cài thử. Hãy dùng thử trên một thư mục nhỏ trước khi nhập cả thư viện lớn.

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

### Agentero có miễn phí không?

Repo dùng giấy phép MIT, là giấy phép mã nguồn mở cho phép dùng tự do. README không nói về giá hay gói trả phí nào của ứng dụng. Nếu bạn dùng dịch vụ dịch hay Agent bên ngoài bằng key riêng thì chi phí tuỳ nhà cung cấp đó.

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

Được. README nói có bộ cài dựng sẵn cho macOS, Windows và Linux, tải từ trang agentero.app hoặc GitHub Releases. Riêng Linux yêu cầu Ubuntu 22.04 trở lên.

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

README không nói gì về yêu cầu GPU hay cấu hình phần cứng. Nếu bạn nối một mô hình chạy trên máy thì yêu cầu phụ thuộc vào mô hình đó, còn thông tin riêng của Agentero thì chưa có.

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

Theo README, văn bản, ghi chú và lịch sử tương tác được lưu trên máy bạn dưới dạng file PDF và Markdown thường. Agentero kết nối với Agent cục bộ nên ngữ cảnh ở lại máy. Tuy nhiên nếu bạn dùng dịch vụ dịch hoặc Agent đám mây thì nội dung có thể đi qua bên đó, nên hãy xem chính sách của họ.

### Agentero khác gì Zotero?

Tác giả nói rõ dự án không nhằm thay Zotero. Agentero thêm phần làm việc với Agent như hỏi đáp có trích dẫn, tách công thức và bảng thành Markdown/LaTeX, MCP và CLI. Nó nhập được cả thư viện Zotero và vẫn dùng được tiện ích trình duyệt của Zotero.

### Dùng được với Claude Code hay ChatGPT không?

README nói Agentero kết nối được Agent cục bộ như Claude Code, OpenCode, Codex hoặc mô hình chạy trên máy qua giao thức ACP. Nó cũng chạy như MCP server để ChatGPT Web và Claude Desktop truy cập thư viện của bạn. Các bước cấu hình chi tiết không có trong README nên bạn xem tài liệu trong repo.

### Có đồng bộ giữa nhiều máy được không?

Có. README nói ứng dụng đồng bộ được với kho lưu trữ tương thích S3, và truy cập được thư viện đặt trên máy chủ từ xa qua SSH tunnel. Hướng dẫn cấu hình cụ thể chưa có trong README.
