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

> Suparagent là ứng dụng mã nguồn mở (Apache-2.0) để tạo các đồng nghiệp AI có tên, mỗi người một vai trò, một thư mục làm việc, có trí nhớ, lịch chạy và bước xin duyệt. Bạn chạy bản desktop từ mã nguồn hoặc tự dựng máy chủ, rồi dùng tài khoản AI của chính bạn. Cài không quá khó nhưng cần Node.js 22+, uv và một engine AI sẵn có; 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-07-18 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/suparagent-dong-nghiep-ai-tu-host-huong-dan-cai-dat-5

Suparagent là một không gian làm việc mã nguồn mở, nơi bạn tạo ra những "đồng nghiệp AI" có tên riêng. Mỗi agent có một công việc rõ ràng, một thư mục làm việc, trí nhớ riêng và quy tắc xin phép bạn trước khi làm gì đó. Bạn có thể chạy nó như một ứng dụng desktop trên máy mình, hoặc tự dựng trên máy chủ của mình.

Ai nên dùng? Người muốn có vài trợ lý AI chuyên trách, ví dụ một người đi tìm tài liệu, một người biên tập, một người tổng hợp báo cáo. Họ làm việc trên cùng thư mục dự án, và bạn không phải dán lại ngữ cảnh mỗi lần. Chủ shop, nhân viên văn phòng hay lập trình viên mới đều dùng được, miễn là bạn đã có sẵn một công cụ AI như Claude Code, Codex CLI hoặc một API key.

Điểm đáng giá nhất: agent không tự ý hành động. Bạn chọn mức tự do, và ngay cả lịch chạy định kỳ cũng 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. Bạn có thể xem video ngắn bên dưới để thấy cách nó chạy trước khi cài.

```repo
- repo | Anil-matcha/suparagent
- kind | Ứng dụng
- desc | Suparagent là không gian làm việc mã nguồn mở để tạo các agent AI có tên, trí nhớ, lịch chạy định kỳ và phải chờ bạn duyệt trước khi hành động.
- 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ế khi dùng.

- **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à cài đặt duyệt riêng. 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 các phòng chung. Việc của bạn là giao một yêu cầu lớn, còn chia nhỏ là việc của nhóm. Lưu ý: trưởng nhóm cần dùng Claude hoặc Codex.
- **Giữ ngữ cảnh lâu dài.** Agent có thể lưu 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ợ "nhớ sai mà không biết".
- **Chạy việc theo lịch (routine).** Bạn đặt routine chạy theo lịch, qua webhook hoặc chạy tay. Mỗi kết quả đều để bạn xem lại. Nếu cần xin duyệt, routine chờ bạn trả lời chứ không tự duyệt.
- **Chọn mức tự do cho agent.** Có bốn chế độ: Ask first (hỏi trước), Accept edits (chấp 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). Mọi hoạt động công cụ và quyết định duyệt đều xem lại được trong ứng dụng.
- **Kết nối công cụ và ứng dụng.** Qua khóa Composio của chính bạn, có thể nối GitHub, Gmail, Google Calendar rồi cấp quyền cho một số agent Claude hoặc Codex đã chọn. Mọi thay đổi vẫn chờ bạn duyệt. Ngoài ra có MCP Marketplace để thêm từng công cụ riêng lẻ.
- **Màn hình Today.** Gom lại 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. 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à các lần thử.
- **Skills và mẫu.** Lưu sẵn các chỉ dẫn dùng lại và khởi tạo agent từ mẫu, đỡ phải viết lại cùng một đoạn yêu cầu.
- **Dùng trên đ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ụ, tạo và sửa agent.
- **Làm việc với tệp và lịch sử.** Tìm hội thoại, đính kèm văn bản và ảnh, nhập âm thanh để chuyển thành chữ (khi 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ử.

Suparagent không kèm sẵn mô hình AI nào. Bạn mang theo engine và tài khoản nhà cung cấp của mình. Các engine được hỗ trợ gồm Claude Code, Codex CLI, Gemini CLI, Google Gemini qua Antigravity, Cursor, các agent dòng lệnh dùng giao thức ACP, OpenRouter, và API tương thích OpenAI như Ollama hoặc LM Studio. Công cụ nào dùng được còn tùy engine; ví dụ không phải engine nào cũng nhận ảnh hay dùng được máy tính của agent.

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

Với bản desktop (cách đơn giản nhất), README nói bạn cần:

- **Node.js 22 trở lên.**
- **uv**, trình quản lý gói Python (README dẫn đến trang tài liệu của 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), hãy cài và đăng nhập nó trước khi mở ứng dụng. Nếu dùng engine qua API, bạn cấu hình trong **Settings → Engines**.
- **Docker** chỉ cần nếu bạn muốn dùng các máy tính cô lập cho agent (tùy chọn).

Nếu muốn tự dựng máy chủ, README ghi yêu cầu chính là: máy chủ Linux, HTTPS, Docker hoặc Node.js cùng uv, và một engine. Bản này còn thử nghiệm, có một chủ sở hữu và có thể mời đồng đội vào.

Về chi phí: bản mã nguồn mở không tính phí, nhưng bạn trả tiền cho nhà cung cấp AI theo cách họ tính (gói thuê bao hoặc theo lượng dùng). Suparagent không bán mô hình hay gói mô hình.

```note
Agent gửi lời nhắc và ngữ cảnh của lượt đó cho engine bạn chọn. Có thể gồm văn bản bạn đính kèm, ghi chú liên quan và nội dung tệp mà engine đọc. Nếu engine là dịch vụ trên mạng, dữ liệu đó thuộc điều khoản của nhà cung cấp. Với việc quan trọng, hãy để chế độ Ask first và đừng giao thư mục chứa dữ liệu nhạy cảm.
```

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

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

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

Bước này README không kèm lệnh cài cụ thể, nên bạn hãy tự kiểm tra máy đã có đủ chưa. Cần Node.js bản 22 trở lên, uv (xem hướng dẫn cài trên trang tài liệu của uv) và một engine. Nếu chọn engine dòng lệnh như Claude Code hay Codex CLI, bạn cài và đăng nhập nó trước, rồi mới mở Suparagent. Đây là chỗ người mới hay quên nhất.

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

Mở terminal (PowerShell hoặc Terminal), đứng ở 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. Máy bạn cần có Git.

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

Lệnh dưới đây là nguyên văn trong README:

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

Dòng đầu đưa terminal vào thư mục `desktop`. Dòng thứ hai khởi động ứng dụng từ mã nguồn. Hãy để cửa sổ terminal mở trong lúc dùng. Lần chạy đầu có thể mất một lúc.

Trong repo còn có tệp `run-desktop.bat`, nhưng README phần Quick start không nói cách dùng nó, nên mình khuyên bạn bám theo lệnh ở trên.

### Cấu hình lần chạy đầu

Khi mở lần đầu, ứng dụng sẽ hỏi bạn chọn engine, thư mục làm việc 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, một công việc rõ ràng và một thư mục làm việc.
3. Bắt đầu chat. Chọn **Ask first** để ứng dụng dừng lại xin duyệt trước các hành động cần duyệt.
4. Thêm đồng đội hoặc tạo routine khi muốn chia việc hoặc lặp lại việc.

### Muốn có bản cài đặt hoặc tự dựng máy chủ?

README có trang Releases với các bản cài desktop, nhưng ghi rõ chúng còn thử nghiệm và chưa ký số. Cơ chế cập nhật chỉ đưa cho bạn một bộ cài đã kiểm tra SHA-256 để tự mở, không tự cài. Với máy chủ tự host, repo có `Dockerfile` và `compose.yaml`, nhưng phần README bạn đang đọc chưa ghi lệnh cụ thể, chỉ dẫn đến hướng dẫn Self-hosting. Bạn hãy xem thư mục `docs/` trong repo trước khi làm.

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

Theo README, bạn biết mình đã cài thành công khi:

- Cửa sổ ứng dụng mở lên và cho bạn chọn engine, thư mục làm việc và chế độ duyệt ở lần đầu.
- Trong **Settings → Engines**, engine bạn dùng báo là đã sẵn sàng.
- Bạn tạo được một agent, mở chat và nhận được câu trả lời. Với chế độ Ask first, ứng dụng sẽ dừng lại hỏi bạn trước khi làm việc cần duyệt.

Thử nhanh: tạo một agent tên "Trợ lý thử", giao công việc là "đọc các tệp trong thư mục này và tóm tắt", rồi nhờ nó tóm tắt một tệp văn bản nhỏ. Có phản hồi là đường đi từ engine đến agent đã thông.

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

Các tình huống dưới đây bám theo những gì README mô tả. Chúng là gợi ý cách áp dụng, không phải kết quả đo đạc.

### Chủ shop: bản tin tuần từ ghi chép rời rạc

Bạn bán hàng online và cuối tuần có một đống ghi chú, báo cáo đơn hàng, góp ý khách. Hãy tạo ba agent: một người trưởng nhóm (đặt engine là Claude hoặc Codex), một người nghiên cứu, một người biên tập. Cho cả ba cùng thư mục `bao-cao-tuan`. Rồi nhắn cho trưởng nhóm:

```text
Hãy lập bản tin tuần từ các ghi chú và báo cáo trong thư mục này.
Chia cho người nghiên cứu phần số liệu và phản hồi khách,
người biên tập viết lại cho gọn. Hỏi tôi trước khi sửa tệp.
```

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

> Cứ giao việc cho AI, nhưng quyền bấm nút cuối cùng phải nằm trong tay bạn.
>
> — Ông T

### Nhân viên văn phòng: bớt việc nhắc lặp

Bạn cần mỗi sáng thứ Hai có một bản tóm tắt việc đang chờ. Tạo một agent "Thư ký", đặt công việc là tổng hợp ghi chú dự án, rồi tạo routine chạy theo lịch. Mỗi sáng, mở màn hình **Today** để xem gộp: yêu cầu cần duyệt, kết quả routine, việc đến hạn. Nếu nối Gmail và lịch qua Composio, Today còn hiện thêm thư và lịch ở chế độ chỉ đọc. Lưu ý: routine chạy ở phần backend, nên backend phải đang chạy thì lịch mới hoạt động.

### Lập trình viên mới: một người viết, một người soát

Tạo hai agent trên cùng một thư mục mã nguồn: một agent viết nháp, một agent đọc soát. Đặt chế độ **Plan only** cho agent soát để nó chỉ nêu ý kiến mà không đụng tới tệp. Với agent viết, dùng **Ask first** hoặc **Accept edits** tùy mức bạn tin tưởng. Lịch sử công cụ và quyết định duyệt đều xem được trong ứng dụng, nên bạn học được cách agent làm việc và kiểm soát được mình đã cho phép gì.

### Người hay đi lại: duyệt việc bằng điện thoại

Nếu bạn tự dựng máy chủ, README cho biết có thể ghép app điện thoại với máy chủ của mình để 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ụ. Khi routine chạy lúc bạn không ở bàn làm việc, bạn vẫn trả lời được yêu cầu duyệt. App này mới thử trên máy giả lập Android và một điện thoại Android, chưa có thông báo đẩy và chưa lên kho ứng dụng.

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

### Báo lỗi hoặc không chạy được vì thiếu Node.js hay uv

README yêu cầu Node.js 22 trở lên và uv. Hãy mở terminal mới rồi gõ `node --version` để xem bản đang cài. Nếu thấp hơn 22 thì cài lại bản mới. Thiếu uv thì cài theo trang tài liệu của uv, rồi đóng và mở lại terminal.

### Settings → Engines không báo engine sẵn sàng

Thường do engine dòng lệnh chưa được cài hoặc chưa đăng nhập. README dặn cài và đăng nhập trước khi mở ứng dụng. Hãy mở engine đó ngoài terminal, đăng nhập xong rồi quay lại kiểm tra. Nếu dùng engine qua API, kiểm tra lại cấu hình trong Settings → Engines.

### Gõ lệnh ở sai thư mục

Lệnh `npm run app` phải chạy trong thư mục `suparagent/desktop`. Nếu chạy ở thư mục khác, lệnh sẽ không tìm thấy gì để chạy. Hãy chạy lại `cd suparagent/desktop` từ chỗ bạn đã clone rồi thử lại.

### Routine không chạy theo lịch

Routine chạy trong backend, nên backend phải luôn chạy. Nếu bạn tắt máy hoặc đóng ứng dụng thì lịch sẽ không chạy. Muốn lịch hoạt động đều, hãy cân nhắc tự dựng máy chủ như README gợi ý.

### Tính năng chưa ổn định hoặc chưa được kiểm tra

README nói thẳng: máy tính Docker, công cụ trình duyệt, bản desktop macOS gốc đều là thử nghiệm và phải bật tay. Kết nối ứng dụng qua Composio mới được thử với dịch vụ giả, chưa thử với dịch vụ thật. Nếu một tính năng lỗi, đừng dựa vào nó cho việc quan trọng; hãy báo qua GitHub Issues hoặc hỏi ở cộng đồng Discord mà README nêu.

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

**Điểm mạnh.** Cách làm việc theo kiểu "đồng nghiệp có tên" rất dễ hình dung. Việc nào cần duyệt thì chờ bạn duyệt, kể cả khi chạy theo lịch. Dữ liệu cuộc trò chuyện, ghi chú, routine nằm trong thư mục dữ liệu của máy bạn hoặc cơ sở dữ liệu máy chủ của bạn. Khóa API lưu qua Suparagent được mã hóa. Bạn không bị khóa vào một nhà cung cấp, vì có thể đổi giữa nhiều engine, kể cả Ollama hay LM Studio qua API tương thích OpenAI.

**Giới hạn.** Dự án còn ở giai đoạn phát triển, bản cài desktop chưa ký và chưa kiểm chứng kỹ trên nhiều nền tảng. Máy chủ tự host là thử nghiệm, chỉ có một chủ sở hữu và có thể mời đồng đội, không phải dịch vụ nhiều tổ chức. Chạy bản desktop từ mã nguồn cần quen với terminal. Nhóm agent cần Claude hoặc Codex cho vai trò trưởng nhóm. Ngoài ra bạn vẫn phải có và trả tiền cho tài khoản AI riêng.

**Khi nên chọn cách khác.** Nếu bạn chỉ cần hỏi đáp thỉnh thoảng, một ứng dụng chat thông thường là đủ và đỡ phải cài. Nếu bạn muốn một dịch vụ có sẵn, không phải tự lo hạ tầng, README có nhắc tới bản hosted ở suparagent.ai, nhưng đó là sản phẩm riêng, có gói trả phí và dữ liệu do họ xử lý. Còn nếu bạn thích thử, muốn kiểm soát dữ liệu và hiểu rằng nó còn đang hoàn thiện, Suparagent là một lựa chọn đáng thử trên một thư mục nhỏ, với chế độ Ask first.

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

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

Mã nguồn mở theo giấy phép Apache-2.0, bạn dùng bản desktop hoặc tự host mà không trả tiền cho Suparagent. Nhưng Suparagent không kèm mô hình AI, nên bạn vẫn trả cho nhà cung cấp AI của mình nếu họ tính phí. Bản hosted ở suparagent.ai 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ì để chạy bản desktop?

Theo README: Node.js 22 trở lên, uv, và ít nhất một engine AI có trên cùng máy. Engine dòng lệnh phải cài và đăng nhập trước, hoặc bạn cấu hình engine API trong Settings → Engines. Docker chỉ cần nếu muốn dùng máy tính cô lập cho agent.

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

Tư liệu không nhắc yêu cầu GPU cho Suparagent. Vì ứng dụng dùng engine bạn tự chọn, nhu cầu phần cứng phụ thuộc engine đó. Nếu bạn chạy mô hình cục bộ qua Ollama hoặc LM Studio thì cần xem yêu cầu của chính các công cụ ấy.

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

README không có bảng hỗ trợ hệ điều hành đầy đủ. Bản desktop chạy từ mã nguồn bằng npm, và trong repo có tệp run-desktop.bat. README cũng nói bản cài đặt còn thử nghiệm với kiểm chứng nền tảng hạn chế, nên nếu gặp lỗi hãy báo qua GitHub Issues.

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

Với desktop và tự host, hội thoại, ghi chú agent, routine và cài đặt nằm trong thư mục dữ liệu hoặc cơ sở dữ liệu máy chủ của bạn. Tệp làm việc vẫn nằm trong thư mục bạn giao, và khóa API lưu qua Suparagent được mã hóa. Tuy nhiên engine nhận lời nhắc và ngữ cảnh cần cho mỗi lượt, nên nếu engine là dịch vụ trên mạng thì dữ liệu đó thuộc điều khoản của nhà cung cấp đó.

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

Bạn chọn mức tự do: Ask first, Accept edits, Approve for me (Claude, Codex, Cursor) hoặc Plan only. Chọn Ask first thì ứng dụng dừng lại xin duyệt. README nói routine không bao giờ tự duyệt một hành động, mà chờ bạn trả lời.

### Dự án đã ổn định để dùng cho việc quan trọng chưa?

README ghi rõ dự án đang phát triển tích cực: bản desktop, tự host, máy tính agent và các tính năng nhóm mới còn thay đổi. Nên đọc phần Known limitations trước khi dựa vào nó cho việc quan trọng. Với người mới, hãy thử trên thư mục nhỏ, không chứa dữ liệu nhạy cảm.
