# Suparagent: đồng nghiệp AI có tên, có trí nhớ, tự chạy theo lịch — hướng dẫn cài và dùng

> Suparagent là ứng dụng mã nguồn mở (Apache-2.0) để tạo các "đồng nghiệp AI": mỗi agent có tên, nhiệm vụ, thư mục làm việc, trí nhớ và lịch chạy riêng. Bạn mang theo engine AI của mình (Claude Code, Codex, Gemini CLI, Ollama…). Cài bản desktop từ mã nguồn không khó nếu đã có Node.js 22+ và uv, nhưng dự án còn thử nghiệm.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-07-19 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/suparagent-dong-nghiep-ai-tu-host-huong-dan-cai-dat-6

Suparagent là một không gian làm việc mã nguồn mở cho các "đồng nghiệp AI". Bạn tạo agent có tên, giao một việc rõ ràng, cho một thư mục làm việc, rồi trò chuyện hoặc giao việc theo lịch. Agent nào cũng có trí nhớ riêng, và các việc cần quyền thật thì phải chờ bạn bấm duyệt.

Repo này hợp với ba nhóm người. Nhóm một là người làm văn phòng, chủ shop hay người làm nội dung, cần một trợ lý AI làm việc lặp lại như tổng hợp báo cáo hằng tuần. Nhóm hai là lập trình viên mới muốn có một "bàn điều khiển" chung cho Claude Code, Codex hay Gemini CLI thay vì mở từng cửa sổ riêng. Nhóm ba là ai muốn tự giữ dữ liệu trên máy mình hoặc server mình. Hiện repo có khoảng 7041 sao và 913 fork.

Điểm đáng giá nhất là bạn không bị khoá vào một nhà cung cấp. Suparagent không kèm sẵn mô hình AI nào. Bạn mang tài khoản hoặc công cụ dòng lệnh mình đã có, còn Suparagent lo phần tổ chức: ai làm việc gì, nhớ gì, chạy khi nào, và việc nào cần bạn đồng ý. Bạn có thể xem video ngắn bên dưới để thấy giao diện trước khi cài.

```repo
- repo | Anil-matcha/suparagent
- kind | Ứng dụng
- desc | Không gian làm việc cho các agent AI có tên, trí nhớ, lịch chạy và phải được bạn duyệt trước khi hành động. Chạy trên máy bạn hoặc server tự host.
- stars | 7k
- lang | Python
- license | Apache-2.0
```

```video
- youtube | https://youtube.com/shorts/Tpk9_hTH7L0
- facebook | https://www.facebook.com/reel/1807688040481189
- title | Video giới thiệu suparagent
```

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

Dưới đây là các tính năng chính, kèm lợi ích thực tế.

- **Tạo agent và nhóm agent.** Mỗi agent có tên, vai trò, engine, thư mục làm việc, trí nhớ và mức quyền riêng. Bạn có thể đặt một agent trưởng nhóm để giao việc cho các agent chuyên môn (ví dụ người nghiên cứu, người biên tập). Trưởng nhóm hiện cần dùng Claude hoặc Codex.
- **Trí nhớ xem và sửa được.** Agent lưu ghi chú, nhớ lại ghi chú và cuộc trò chuyện liên quan, tìm lại lịch sử. Bạn mở ra xem và chỉnh nội dung nó nhớ, nên không phải đoán xem AI "biết" gì về bạn.
- **Routine (việc chạy theo lịch).** Bạn đặt việc chạy theo lịch, qua webhook hoặc chạy tay. Mỗi kết quả bạn xem lại được. Routine không bao giờ tự duyệt một hành động nhạy cảm, nó phải hỏi bạn.
- **Chọn mức tự do cho agent.** Có các chế độ Ask first (hỏi trước), Accept edits (cho phép sửa file), Approve for me (chỉ cho Claude, Codex, Cursor) và Plan only (chỉ lập kế hoạch). Mọi hoạt động công cụ và quyết định duyệt đều xem lại được trong app.
- **Kết nối ứng dụng.** Bạn nối GitHub, Gmail, Google Calendar… qua khoá Composio của riêng bạn, rồi cấp quyền cho một số agent Claude hoặc Codex. Thay đổi vẫn phải chờ bạn duyệt. Muốn thêm công cụ lẻ thì lấy từ MCP Marketplace trong app.
- **Màn hình Today.** Gom một chỗ: việc cần duyệt, câu hỏi từ agent, kết quả routine, lỗi engine, việc đến hạn. Có thể hiện thêm thư Gmail và lịch ở chế độ chỉ đọc.
- **Bảng việc và lịch.** Giao việc, hẹn chạy một lần, xem lại các cuộc trò chuyện và lần thử.
- **Skill và mẫu agent.** Lưu sẵn hướng dẫn dùng lại, và tạo agent mới từ mẫu.
- **Dùng từ điện thoại.** Ghép app điện thoại với server của bạn để chat, dừng câu trả lời, cho phép hoặc từ chối một lệnh. Hiện mới thử trên Android, chưa thử trên iOS.
- **File và lịch sử.** Tìm kiếm hội thoại, đính kèm văn bản và ảnh, duyệt hoặc tải file trong thư mục làm việc, xuất lịch sử.

Về engine, bạn có thể nối Claude Code hoặc Codex CLI, Gemini CLI, Google Gemini qua Antigravity, Cursor, công cụ dòng lệnh khác dùng giao thức ACP, OpenRouter, hoặc API tương thích OpenAI như Ollama và LM Studio. Không phải engine nào cũng hỗ trợ đủ tính năng; ví dụ nhập ảnh và máy tính riêng của agent không có ở mọi engine.

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

Theo README, bản desktop chạy từ mã nguồn, nên bạn cần:

- **Node.js 22 trở lên.**
- **uv** (trình quản lý Python, trang tài liệu: docs.astral.sh/uv).
- **Ít nhất một engine** có sẵn trên cùng máy. Nếu dùng engine dạng dòng lệnh (CLI), bạn phải cài và đăng nhập nó trước khi mở app. Nếu dùng engine qua API, bạn cấu hình trong **Settings → Engines**.
- **Docker** chỉ cần nếu muốn dùng "máy tính riêng" (isolated computer) cho agent. Đây là tính năng tuỳ chọn.
- **Tài khoản nhà cung cấp AI.** Suparagent không kèm mô hình hay gói thuê bao, nên dùng mô hình có thể tốn tiền theo nhà cung cấp bạn chọn.

README không nói rõ yêu cầu RAM, GPU hay hệ điều hành cụ thể cho bản desktop. Phần nói về bản cài sẵn (installer) chỉ cho biết chúng còn thử nghiệm, chưa ký số và mới kiểm chứng trên số nền tảng hạn chế. Nếu bạn muốn tự host trên server, bảng so sánh ghi cần máy chủ Linux, HTTPS, Docker hoặc Node.js cùng uv, và một engine.

```note
Suparagent đang phát triển, bản desktop và self-host đều ghi là thử nghiệm. Đừng giao việc quan trọng hoặc dữ liệu nhạy cảm khi chưa đọc phần "Known limitations" trong README. Khi agent trả lời, engine bạn chọn sẽ nhận câu hỏi và phần ngữ cảnh cần thiết, nếu engine là dịch vụ trên mạng thì dữ liệu đó theo điều khoản của nhà cung cấp.
```

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

```steps
- Chuẩn bị công cụ | Cài Node.js 22+ và uv, cài và đăng nhập một engine
- Tải mã nguồn | Dùng git clone để lấy repo về máy
- Vào thư mục desktop | Mở terminal tại thư mục suparagent/desktop
- Chạy app | Gõ npm run app
- Cài đặt lần đầu | Chọn engine, workspace và chế độ duyệt
- Tạo agent đầu tiên | Đặt tên, giao việc, chọn thư mục làm việc
```

### Chuẩn bị Node.js, uv và engine

Trước khi gõ lệnh nào, bạn kiểm tra máy đã có Node.js bản 22 trở lên và uv. README không ghi lệnh cài chúng, nên bạn cài theo trang chính thức của từng công cụ. Việc kế tiếp là engine: nếu bạn dùng Claude Code hay Codex CLI, hãy cài và đăng nhập nó trong terminal trước. Người mới hay vấp ở đây: mở app lên mới thấy "chưa có engine nào sẵn sàng", vì quên bước đăng nhập CLI.

### Tải mã nguồn về máy

Mở terminal (PowerShell trên Windows, Terminal trên macOS hay Linux) ở nơi bạn muốn lưu dự án, rồi gõ:

```bash
git clone https://github.com/Anil-matcha/suparagent.git
```

Lệnh này tải toàn bộ mã nguồn vào thư mục mới tên `suparagent`. Bạn cần có Git trên máy.

### Vào thư mục desktop và chạy app

README ghi đúng hai lệnh sau:

```bash
cd suparagent/desktop
npm run app
```

Lệnh `cd` đưa terminal vào thư mục `desktop` bên trong repo. Lệnh `npm run app` khởi động bản desktop từ mã nguồn. Lưu ý: phải chạy trong đúng thư mục `desktop`, không phải thư mục gốc `suparagent`. Lần đầu có thể mất một lúc, và README không nói chi tiết về những gì xảy ra ở lần chạy đầu, nên nếu có thông báo lạ, bạn xem trong thư mục `docs/` của repo hoặc trang Issues.

### Cài đặt lần đầu trong app

Lần mở đầu tiên, app hỏi bạn chọn engine, workspace và chế độ duyệt. Sau đó README gợi ý làm theo thứ tự:

1. Vào **Settings → Engines** và xác nhận có một engine ở trạng thái sẵn sàng.
2. Tạo agent với tên, nhiệm vụ rõ ràng và một thư mục làm việc.
3. Bắt đầu chat. Chọn **Ask first** nếu muốn app dừng lại hỏi trước khi làm việc cần quyền.
4. Thêm đồng đội hoặc tạo routine khi muốn chia việc hay lặp việc.

Nếu bạn không muốn chạy từ mã nguồn, README có nhắc trang Releases của repo với các bản cài desktop. Những bản này còn thử nghiệm, chưa ký số, và việc cập nhật giữa các bản chưa được kiểm chứng trọn vẹn. Về self-host trên server, README chỉ trỏ tới tài liệu "Self-hosting" trong repo (xem thư mục `docs/`), chưa ghi lệnh ngay trong README. Repo có `Dockerfile` và `compose.yaml`, nhưng bạn nên đọc tài liệu rồi mới chạy, đừng đoán lệnh.

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

README không đưa một lệnh kiểm tra riêng, nhưng có vài dấu hiệu rõ ràng:

- Cửa sổ app Suparagent mở lên và cho bạn chọn engine, workspace, chế độ duyệt.
- Trong **Settings → Engines**, engine bạn chọn hiện là sẵn sàng.
- Bạn tạo được một agent, mở chat, gửi một câu ngắn (ví dụ "Chào, bạn làm được gì trong thư mục này?") và nhận được câu trả lời.
- Với chế độ **Ask first**, khi bạn nhờ agent làm việc cần quyền (như sửa file), app dừng lại và chờ bạn bấm cho phép.

Nếu cả bốn điều trên ổn, bạn đã cài thành công. Nếu agent không trả lời, nhiều khả năng nằm ở engine chứ không phải ở app.

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

### Chủ shop: bản tin tuần từ ghi chú bán hàng

Bạn có một thư mục chứa ghi chú và báo cáo doanh số mỗi tuần. Hãy tạo một agent tên "Trợ lý báo cáo", cho nó thư mục đó làm workspace, chọn **Ask first**. Rồi nhắn:

```text
Đọc các ghi chú và báo cáo trong thư mục này, tóm tắt thành bản tin tuần: 5 ý chính, việc nào đang chậm, việc nào cần tôi quyết.
```

Bạn nhận được bản tóm tắt ngay trong chat. Khi hài lòng với cách làm, chuyển nó thành routine hằng tuần. Mỗi lần chạy xong, kết quả hiện ở màn hình Today để bạn xem lại.

> Agent không nhận quyền một lần rồi làm bừa: việc nào cần quyền thật thì nó phải dừng lại chờ bạn duyệt.
>
> — Ông T

### Nhân viên văn phòng: một nhóm nhỏ gồm trưởng nhóm, người nghiên cứu và người biên tập

Đây chính là ví dụ trong README. Bạn tạo agent trưởng nhóm (chọn Claude hoặc Codex làm engine) cùng hai agent chuyên môn, cho cả ba dùng chung thư mục dự án. Sau đó nhờ trưởng nhóm:

```text
Chuẩn bị bản briefing dự án tuần này từ các ghi chú và báo cáo trong thư mục.
```

Trưởng nhóm chia nhỏ việc và giao cho từng chuyên gia. Mỗi người làm trong cuộc trò chuyện riêng rồi trả kết quả về cho trưởng nhóm tổng hợp. Bạn theo dõi trong chat và duyệt khi cài đặt yêu cầu. Lưu ý README ghi tính năng giao việc nhóm còn mới.

### Lập trình viên mới: gom nhiều engine vào một chỗ

Giả sử bạn đã cài Claude Code và đã đăng nhập. Trong Suparagent, bạn tạo một agent "Người đọc code", trỏ workspace vào thư mục dự án của bạn, chọn chế độ **Plan only** để nó chỉ lập kế hoạch, chưa sửa gì. Bạn nhắn:

```text
Đọc thư mục này và đề xuất kế hoạch từng bước để thêm chức năng đăng nhập. Chưa sửa file nào.
```

Bạn nhận về một kế hoạch để cân nhắc. Khi tin tưởng hơn, chuyển sang **Ask first** hoặc **Accept edits** để agent bắt đầu sửa.

### Người hay quên việc: Today và routine nhắc việc đến hạn

Bạn gán việc lên bảng task, hẹn một lần chạy trên lịch, và để màn hình Today gom việc cần duyệt cùng việc đến hạn. Nếu đã nối Gmail và Google Calendar qua khoá Composio của bạn, Today có thể hiện thư và lịch ở chế độ chỉ đọc. Kết quả là mỗi sáng bạn mở một màn hình duy nhất để biết hôm nay cần xử lý gì. Lưu ý README ghi phần kết nối ứng dụng mới được thử với một dịch vụ Composio giả, chưa phải dịch vụ thật.

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

**App báo chưa có engine sẵn sàng.** Thường do chưa cài hoặc chưa đăng nhập CLI của engine. Hãy mở terminal, kiểm tra công cụ đó chạy được và đã đăng nhập, rồi vào **Settings → Engines** kiểm tra lại. Nếu dùng engine qua API thì kiểm tra khoá đã điền đúng chỗ chưa.

**Gõ `npm run app` không chạy.** Hai nguyên nhân dễ gặp: đang đứng sai thư mục (phải ở `suparagent/desktop`) hoặc phiên bản Node.js thấp hơn 22. Kiểm tra lại hai điều này trước khi tìm lỗi khác. Nếu vẫn không được, mở Issues trên GitHub hoặc hỏi ở Discord của dự án.

**Routine không chạy đúng giờ.** README nói routine chạy trong backend, nên backend phải luôn đang chạy. Nếu bạn tắt app hoặc tắt server thì lịch sẽ không chạy. Muốn chạy đều, bạn cần để máy hoặc server bật liên tục.

**Agent không dùng được ứng dụng đã kết nối.** Theo README, chỉ agent dùng Claude hoặc Codex mới dùng được các ứng dụng kết nối qua Composio. Hãy kiểm tra engine của agent đó, và nhớ rằng mọi thay đổi vẫn phải chờ bạn duyệt.

**Tính năng máy tính riêng (Docker) hoặc công cụ trình duyệt trục trặc.** README ghi các tính năng này là thử nghiệm và chỉ bật khi bạn chọn. Nếu không thật sự cần, bạn bỏ qua chúng và dùng chế độ thường. Nếu cần, hãy đọc tài liệu về agent computers trong thư mục `docs/` của repo trước.

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

**Điểm mạnh.** Mã nguồn mở với giấy phép Apache-2.0. Bạn chọn engine tuỳ ý, không bị buộc vào một hãng. Dữ liệu cuộc trò chuyện, ghi chú, routine và cài đặt nằm trong thư mục dữ liệu trên máy bạn hoặc cơ sở dữ liệu của server bạn; khoá API lưu qua Suparagent được mã hoá ở đó. Cách làm "hỏi trước khi hành động" và màn hình Today giúp bạn kiểm soát được agent làm gì.

**Giới hạn.** Dự án còn đang phát triển nhanh. Bản desktop và server tự host đều ghi là thử nghiệm. Server tự host có một chủ và có thể mời đồng đội, nhưng không phải dịch vụ nhiều tổ chức. Các bản cài desktop chưa ký số. App điện thoại chưa thử trên iOS và chưa có thông báo đẩy. Phần kết nối ứng dụng, MCP Marketplace, nhập âm thanh chưa qua kiểm chứng với dịch vụ thật. Ngoài ra, cài từ mã nguồn đòi hỏi bạn quen dùng terminal ở mức cơ bản.

**Về chi phí.** Phần mềm mã nguồn mở thì không tốn tiền, nhưng bạn tự trả tiền cho nhà cung cấp mô hình nếu dùng. Ngoài ra còn có dịch vụ tính phí tách riêng trên trang chủ dự án, với gói miễn phí dùng thử và các gói trả phí từ 15 đến 99 đô la mỗi tháng theo README. Đây là sản phẩm riêng, bạn không cần dùng nó để chạy bản mã nguồn mở.

**Khi nào chọn cách khác.** Nếu bạn chỉ cần hỏi đáp một lần, một app chat thông thường đơn giản hơn. Nếu cần công cụ đã ổn định để chạy việc quan trọng trong doanh nghiệp, hãy chờ dự án chín hơn hoặc thử nghiệm kỹ ở quy mô nhỏ trước. Còn nếu bạn muốn một đội agent có tên, có trí nhớ và có người duyệt, đồng thời chấp nhận còn nhiều chỗ chưa hoàn thiện, thì Suparagent đáng để thử.

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

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

Mã nguồn mở dùng giấy phép Apache-2.0, bạn có thể chạy bản desktop hoặc tự host mà không phải trả tiền cho Suparagent. Tuy nhiên Suparagent không kèm mô hình AI, nên bạn vẫn có thể phải trả tiền cho nhà cung cấp engine bạn chọn. Dịch vụ hosted là sản phẩm riêng, có gói miễn phí dùng thử và các gói trả phí.

### Cần những gì để cài bản desktop?

Theo README, bạn cần Node.js 22 trở lên, uv và ít nhất một engine trên cùng máy. Nếu dùng engine dạng CLI thì phải cài và đăng nhập trước khi mở app. Docker chỉ cần cho tính năng máy tính riêng của agent, và đó là tuỳ chọn.

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

README không nêu yêu cầu GPU. Vì Suparagent không kèm mô hình mà dùng engine bạn nối vào, yêu cầu phần cứng phụ thuộc vào engine đó. Nếu dùng engine cục bộ như Ollama hay LM Studio thì phải xem tài liệu của chúng; tư liệu này chưa có thông tin cụ thể.

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

README không liệt kê hệ điều hành cụ thể cho bản desktop. Nó chỉ nói các bản cài desktop là thử nghiệm, chưa ký số và mới được kiểm chứng trên số nền tảng hạn chế. Bạn nên xem phần desktop setup trong thư mục docs của repo và trang Releases để biết nền tảng nào được hỗ trợ.

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

Với desktop và tự host, cuộc trò chuyện, ghi chú, routine và cài đặt nằm trong thư mục dữ liệu trên máy hoặc cơ sở dữ liệu trên server của bạn, còn khoá API lưu qua Suparagent được mã hoá. Tuy vậy, khi agent trả lời thì engine bạn chọn nhận câu hỏi và ngữ cảnh cần thiết, nên nếu engine là dịch vụ trên mạng thì dữ liệu đó theo điều khoản của nhà cung cấp đó.

### Agent có tự ý làm việc nguy hiểm không?

Bạn chọn mức quyền cho từng agent: Ask first, Accept edits, Approve for me hoặc Plan only. Với Ask first, agent dừng lại chờ bạn duyệt trước khi làm việc cần quyền. README còn nói routine không bao giờ tự duyệt một hành động.

### Suparagent khác gì việc dùng thẳng Claude Code hay Codex?

Suparagent không thay thế các engine đó mà đứng trên chúng. Nó thêm tên agent, trí nhớ xem và sửa được, nhóm agent, routine theo lịch, màn hình Today và luồng duyệt hành động. README chưa so sánh chi tiết với từng công cụ cụ thể.
