# Suparagent: tạo nhóm đồng nghiệp AI tự chạy, có duyệt — hướng dẫn cài đặt và dùng

> Suparagent là một không gian làm việc mã nguồn mở (Apache-2.0) để tạo các agent AI có tên, có việc riêng, có trí nhớ và lịch chạy, và hỏi bạn trước khi hành động. Bạn tự mang engine (Claude Code, Codex, Gemini CLI, Ollama…), vì repo không kèm model. Bản desktop chạy từ mã nguồn, cần Node.js 22+, uv và một engine; README ghi cài khá gọn nhưng dự án còn ở giai đoạn thử nghiệm.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-08-17 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/suparagent-dong-nghiep-ai-ma-nguon-mo-tu-host

Suparagent là một không gian làm việc cho "đồng nghiệp AI": bạn tạo các agent có tên riêng, giao cho mỗi agent một công việc và một thư mục làm việc, rồi cho họ phối hợp làm việc thật. Mọi thứ nằm ở một chỗ: cuộc trò chuyện, trí nhớ, lịch chạy định kỳ và các lần chờ bạn duyệt. Bạn dùng được bằng ứng dụng desktop hoặc tự dựng máy chủ riêng.

Repo này dành cho người muốn có "nhân viên ảo" mà vẫn nắm quyền kiểm soát: chủ shop cần báo cáo tuần, nhân viên văn phòng muốn tổng hợp tài liệu, hoặc lập trình viên mới thích thử mô hình nhiều agent. Điểm đáng giá nhất là agent không tự làm bừa. Bạn chọn mức tự do cho chúng, và một lịch chạy định kỳ không bao giờ tự duyệt thay bạn. Repo hiện có khoảng 7.041 sao và 913 fork, giấy phép Apache-2.0.

Có một lưu ý ngay từ đầu: Suparagent không kèm model hay gói đăng ký model nào. Bạn phải mang theo engine và tài khoản của riêng mình. Mình có làm video giới thiệu, bạn xem video ngắn bên dưới để thấy giao diện thực tế.

```repo
- repo | Anil-matcha/suparagent
- kind | Ứng dụng
- desc | Không gian làm việc mã nguồn mở cho đồng nghiệp AI: tạo agent có tên, trí nhớ, lịch chạy định kỳ, và chỉ hành động sau khi bạn duyệt.
- 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à những tính năng chính, mình giải thích theo lợi ích thực tế.

- **Tạo agent và nhóm.** Mỗi agent có tên, vai trò, engine, thư mục làm việc, trí nhớ và cài đặt duyệt. Một agent trưởng nhóm có thể giao việc cho các agent chuyên môn, hoặc phối hợp trong phòng chung. Trưởng nhóm cần dùng Claude hoặc Codex.
- **Giữ ngữ cảnh.** Agent ghi chú, nhớ lại ghi chú và cuộc trò chuyện liên quan, và tìm trong lịch sử. Bạn xem và sửa được những gì chúng nhớ, nên không sợ chúng nhớ sai mà không biết.
- **Chạy theo lịch (routine).** Một việc có thể chạy theo giờ, qua webhook hoặc bấm tay. Bạn xem từng kết quả và trả lời các yêu cầu duyệt.
- **Chọn mức tự do.** Có các chế độ: Ask first (hỏi trước), Accept edits (tự nhận chỉnh sửa), Approve for me (dành cho Claude, Codex và Cursor) và Plan only (chỉ lập kế hoạch). Bạn xem lại hoạt động công cụ và các quyết định duyệt trong app.
- **Kết nối ứng dụng.** Nối GitHub, Gmail, Google Calendar qua khoá Composio của bạn rồi cấp quyền cho agent Claude hoặc Codex được chọn. Mọi thay đổi vẫn chờ bạn duyệt. Có thêm từng công cụ lẻ từ MCP Marketplace.
- **Màn hình Today.** Gom các việc cần bạn chú ý: yêu cầu duyệt, câu hỏi, kết quả routine, lỗi engine, việc đến hạn. Có thể hiện 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 lần thực hiện.
- **Kỹ năng và mẫu.** Lưu sẵn các bộ hướng dẫn (skill) và tạo agent từ mẫu để khỏi gõ lại từ đầu.
- **Dùng từ điện thoại.** Ghép app điện thoại với máy chủ của bạn để chat, dừng câu trả lời, cho phép hoặc từ chối một lệnh gọi công cụ.
- **Làm việc với tệp.** Tìm cuộc trò chuyện, đính kèm văn bản và ảnh, nhập âm thanh để chuyển thành chữ (cần bạn đồng ý và có thông tin đăng nhập), duyệt hoặc tải tệp trong thư mục làm việc, xuất lịch sử.

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

Theo README, bạn cần:

- **Node.js 22 hoặc mới hơn.**
- **uv** (công cụ quản lý Python, trang tài liệu uv của Astral).
- **Ít nhất một engine trên cùng máy.** Nếu là engine dạng dòng lệnh (CLI), bạn phải cài và đăng nhập trước khi mở app. Hoặc bạn cấu hình engine qua API trong **Settings → Engines**.
- **Docker** chỉ cần nếu muốn dùng "máy tính cô lập" cho agent, và phần này là tuỳ chọn.

Các engine được liệt kê: Claude Code, Codex CLI, Gemini CLI, Google Gemini qua Antigravity, Cursor, agent dòng lệnh khác dùng giao thức ACP, OpenRouter, và API tương thích OpenAI như Ollama hoặc LM Studio. Không phải engine nào cũng hỗ trợ ảnh hay máy tính cô lập.

Về hệ điều hành, README không nêu cụ thể trong phần chạy nhanh. Trong thư mục gốc repo có file `run-desktop.bat`, nhưng README chưa giải thích nó dùng để làm gì. README cũng cho biết các bộ cài desktop còn thử nghiệm, chưa ký số, và việc kiểm chứng nền tảng còn hạn chế.

```note
Suparagent không gồm model. Nếu engine của bạn là dịch vụ trả phí, mỗi lượt trả lời sẽ gửi câu lệnh và ngữ cảnh cần thiết cho nhà cung cấp đó và có thể tốn tiền. Hãy xem kỹ điều khoản và mức phí của engine trước khi giao việc lớn.
```

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

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

### Chuẩn bị công cụ

Cài Node.js bản 22 trở lên và uv theo hướng dẫn trên trang của chúng. Sau đó cài một engine bạn đã có tài khoản, ví dụ một CLI, và đăng nhập sẵn. Bước này người mới hay quên: nếu CLI chưa đăng nhập, Suparagent sẽ báo engine chưa sẵn sàng.

### Tải mã nguồn

Mở terminal (PowerShell trên Windows, Terminal trên macOS/Linux) ở thư mục bạn muốn lưu dự án, rồi chạy:

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

Lệnh này tạo thư mục `suparagent` chứa toàn bộ mã nguồn. Bạn cần cài Git từ trước.

### Chạy app desktop

README ghi lệnh sau, chạy từ thư mục `desktop` bên trong repo:

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

Lưu ý: README không nhắc tới bước cài thư viện riêng (kiểu `npm install`). Nếu `npm run app` báo thiếu gói, hãy xem hướng dẫn thiết lập desktop trong thư mục `docs/` của repo thay vì tự đoán lệnh.

### Chọn engine, thư mục và chế độ duyệt

Lần đầu mở app, bạn chọn engine, thư mục làm việc (workspace) và chế độ duyệt. Sau đó mở **Settings → Engines** để xác nhận có engine báo sẵn sàng. Nếu dùng engine qua API, điền khoá ở đây. Khoá được lưu mã hoá trên máy bạn, theo README.

### Tạo agent và bắt đầu chat

Tạo một agent với tên, công việc rõ ràng và thư mục làm việc. Bắt đầu chat và chọn **Ask first** để app dừng chờ bạn duyệt trước các hành động cần duyệt. Khi cần chia việc hoặc lặp lại việc, thêm đồng đội hoặc tạo routine.

Nếu muốn dựng máy chủ riêng, README chỉ tới "Self-hosting guide" trong tài liệu của repo và yêu cầu máy chủ Linux, HTTPS, Docker hoặc Node.js + uv, và một engine. README phần giới thiệu không ghi lệnh cụ thể, nên bạn xem thư mục `docs/` cùng `compose.yaml` và `Dockerfile` ở gốc repo.

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

Theo tư liệu, bạn biết đã ổn khi:

1. Cửa sổ app mở ra và dẫn bạn qua bước chọn engine, workspace, chế độ duyệt.
2. Trong **Settings → Engines**, engine của bạn hiện ở trạng thái sẵn sàng.
3. Bạn tạo được một agent và nhận được câu trả lời trong chat.

Cách thử đơn giản: tạo agent tên "Trợ lý thử", giao việc "đọc các tệp trong thư mục này và tóm tắt", để chế độ Ask first. Nếu app hiện yêu cầu duyệt trước khi agent làm gì đó, nghĩa là cả engine lẫn cơ chế duyệt đều đang hoạt động.

## 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 mô tả. Câu lệnh mẫu là gợi ý của mình, bạn chỉnh theo việc của bạn.

### Chủ shop: báo cáo dự án hằng tuần

Bạn có thư mục chứa ghi chú và báo cáo bán hàng mỗi tuần. Tạo một agent trưởng nhóm (engine Claude hoặc Codex) và hai agent chuyên môn: một người nghiên cứu, một người biên tập. Cho cả ba cùng một thư mục làm việc. Rồi nhắn cho trưởng nhóm:

```text
Hãy lập bản tóm tắt tuần này từ các ghi chú và báo cáo trong thư mục. Giao người nghiên cứu gom số liệu, người biên tập viết lại gọn cho tôi đọc.
```

Trưởng nhóm chia việc, các agent làm trong những cuộc trò chuyện riêng rồi trả về để ghép. Bạn theo dõi trong chat và duyệt khi cài đặt yêu cầu. Khi quy trình ổn, biến nó thành routine chạy mỗi tuần và xem lại từng lần chạy.

> Giao việc cho agent như giao cho nhân viên mới: nói rõ việc, cho đúng thư mục, và duyệt trước khi họ làm.
>
> — Ông T

### Nhân viên văn phòng: bắt đầu ngày làm việc từ màn hình Today

Bạn kết nối Gmail và Google Calendar qua khoá Composio của mình, cấp quyền cho một agent Claude hoặc Codex. Mỗi sáng mở màn hình **Today** để thấy yêu cầu duyệt, câu hỏi từ agent, kết quả routine và việc đến hạn ở một chỗ. Thư và lịch hiện ở chế độ chỉ đọc. Bạn không phải mở nhiều tab để biết hôm nay cần xử lý gì.

### Lập trình viên mới: thử đội agent nhiều vai

Tạo một agent "lead" và vài agent chuyên môn, giao chúng đọc một thư mục mã nguồn nhỏ và đề xuất cải tiến. Dùng chế độ **Plan only** để agent chỉ lập kế hoạch, hoặc **Accept edits** khi bạn muốn chúng sửa tệp. Bạn xem được hoạt động công cụ và quyết định duyệt trong app, rất hợp để hiểu cách một nhóm agent phối hợp.

### Làm việc từ xa: duyệt việc bằng điện thoại

Nếu bạn có máy chủ riêng, ghép app điện thoại với nó để chat, dừng một câu trả lời đang chạy, cho phép hoặc từ chối một lệnh gọi công cụ khi đang ngoài văn phòng. Lưu ý README cho biết app điện thoại mới thử trên Android (máy ảo và một điện thoại thật), chưa thử trên iOS, chưa có thông báo đẩy và chưa lên cửa hàng ứng dụng.

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

- **Engine không báo sẵn sàng.** Thường do CLI chưa cài hoặc chưa đăng nhập. Hãy đăng nhập engine ngoài terminal trước, mở lại app rồi vào Settings → Engines kiểm tra lại. Với engine qua API, kiểm tra lại khoá đã điền đúng chưa.
- **`npm run app` báo lỗi hoặc thiếu gói.** Hãy chắc chắn bạn đang đứng đúng thư mục `suparagent/desktop` và Node.js là bản 22 trở lên (kiểm tra bằng `node --version`). README chưa ghi bước cài phụ thuộc, nên xem tài liệu thiết lập desktop trong `docs/`.
- **Agent trưởng nhóm không giao việc được.** README nói trưởng nhóm cần dùng Claude hoặc Codex. Hãy đổi engine của agent lead sang một trong hai.
- **Routine không chạy đúng giờ.** Routine chạy trong backend, nên backend phải luôn chạy. Nếu bạn tắt app hay máy chủ, lịch sẽ không chạy.
- **Tính năng nào đó chạy chập chờn.** Máy tính cô lập bằng Docker, công cụ trình duyệt, kết nối ứng dụng qua Composio, MCP Marketplace và chuyển âm thanh thành chữ đều được README ghi là chưa kiểm chứng đầy đủ hoặc còn thử nghiệm. Đừng giao việc quan trọng cho chúng khi chưa thử kỹ. Gặp lỗi thì báo trong mục Issues của repo.

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

**Điểm mạnh.** Mã nguồn mở Apache-2.0, tự lưu dữ liệu trên máy hoặc máy chủ của bạn (hội thoại, ghi chú agent, routine, cài đặt). Có cơ chế duyệt rõ ràng nên bạn kiểm soát được agent. Hỗ trợ nhiều engine, kể cả mô hình chạy cục bộ qua Ollama hoặc LM Studio, nên bạn không bị khoá vào một nhà cung cấp.

**Giới hạn.** Dự án đang phát triển nhanh. Bộ cài desktop còn thử nghiệm và chưa ký số, máy chủ tự host mới có một chủ sở hữu có thể mời đồng đội và không phải dịch vụ nhiều tổ chức. App điện thoại chưa thử trên iOS. Nhiều tính năng mới (giao việc theo nhóm, máy tính cô lập, kết nối ứng dụng) vẫn còn thử nghiệm. Bạn cũng phải tự lo engine và chi phí model.

**Một điểm cần phân biệt.** Dịch vụ hosted tại suparagent.ai là sản phẩm riêng, có các gói trả phí tính theo giờ máy tính chạy. Phần mã nguồn mở bạn cài ở bài này không bao gồm dịch vụ đó.

**Khi nào nên 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 hệ thống ổn định cho công việc then chốt, nên chờ dự án trưởng thành hoặc thử với việc nhỏ, ít rủi ro trước. Còn nếu bạn muốn học cách xây đội agent có duyệt, có trí nhớ, có lịch chạy mà vẫn tự giữ dữ liệu, Suparagent là một nơi đáng thử.

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

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

Phần mã nguồn mở (app desktop và máy chủ tự host) dùng giấy phép Apache-2.0. Tuy nhiên repo không kèm model, nên bạn vẫn phải có tài khoản engine và có thể mất phí cho nhà cung cấp đó. Dịch vụ hosted tại suparagent.ai là sản phẩm riêng với các gói từ miễn phí bản thử đến vài chục đô la mỗi tháng.

### Cài Suparagent cần những gì?

Theo README, bản desktop chạy từ mã nguồn và cần Node.js 22 trở lên, uv và ít nhất một engine trên cùng máy. Docker chỉ cần nếu bạn muốn dùng máy tính cô lập cho agent, và đó là tuỳ chọn.

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

Tư liệu không nêu yêu cầu GPU. Suparagent dùng engine bạn tự mang theo. Nếu bạn dùng engine chạy cục bộ như Ollama hay LM Studio thì cấu hình máy phụ thuộc vào mô hình đó, còn README chưa có thông tin cụ thể.

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

README không nêu rõ hệ điều hành trong phần chạy nhanh, nhưng thư mục gốc repo có file run-desktop.bat. README chỉ nói các bộ cài desktop còn thử nghiệm, chưa ký số và kiểm chứng nền tảng còn hạn chế. Bạn nên tự thử và xem tài liệu thiết lập desktop trong repo.

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

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

### Agent có tự ý làm việc khi tôi không biết không?

Bạn chọn mức tự do: Ask first, Accept edits, Approve for me (cho Claude, Codex, Cursor) hoặc Plan only. README nói routine không bao giờ tự duyệt một hành động thay bạn, và bạn xem lại hoạt động công cụ cùng quyết định duyệt trong app.

### Dùng được với model nào?

README liệt kê Claude Code, Codex CLI, Gemini CLI, Gemini qua Antigravity, Cursor, agent dòng lệnh dùng ACP, OpenRouter và API tương thích OpenAI như Ollama hoặc LM Studio. Khả năng cụ thể (ảnh, máy tính cô lập, kết nối ứng dụng) khác nhau theo từng engine.
