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

> Suparagent là ứng dụng mã nguồn mở (Python, giấy phép Apache-2.0) cho phép bạn tạo các agent AI như những đồng nghiệp có tên, có việc riêng, có trí nhớ và có lịch chạy. Bạn dùng bản desktop chạy từ mã nguồn hoặc tự dựng máy chủ. Cài không quá khó nếu đã có Node.js 22+, uv và một engine AI, nhưng dự án vẫn ở giai đoạn thử nghiệm.

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

Suparagent là một không gian làm việc mã nguồn mở, nơi bạn tạo ra các «đồng nghiệp AI»: mỗi agent có tên, có công việc, có thư mục làm việc và có trí nhớ riêng. Bạn giao việc qua khung chat, đặt lịch cho việc lặp lại, và agent chỉ hành động khi bạn đã duyệt (nếu bạn chọn chế độ đó).

Repo này hợp với người muốn dùng AI như một nhóm nhân viên chứ không chỉ một ô chat. Ví dụ: chủ shop cần một agent tổng hợp báo cáo mỗi tuần, nhân viên văn phòng cần một trợ lý đọc ghi chú dự án, hoặc lập trình viên muốn tự host một công cụ thay vì dùng dịch vụ đóng. Tác giả định vị đây là bản thay thế tự host cho nhiều công cụ agent đang có trên thị trường. Hiện repo có khoảng 7041 sao và 913 fork.

Điểm đáng giá nhất: bạn mang engine AI của chính mình (Claude Code, Codex CLI, Gemini CLI, OpenRouter, Ollama…), còn dữ liệu cuộc trò chuyện, ghi chú và lịch chạy nằm trên máy bạn hoặc máy chủ bạn kiểm soát. Xem video ngắn bên dưới để thấy giao diện hoạt động 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 riêng, và chỉ hành động khi bạn đồ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à những 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 phê duyệt. Bạn có thể đặt một agent «trưởng nhóm» chia việc cho các agent chuyên môn (ví dụ người nghiên cứu, người biên tập). Theo README, trưởng nhóm cần dùng Claude hoặc Codex.
- **Trí nhớ có thể xem và sửa.** Agent 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 được agent nhớ gì và chỉnh lại nếu sai. Nhờ vậy bạn không phải dặn lại cùng một điều mỗi lần.
- **Routine (việc chạy theo lịch).** Bạn tạo routine chạy theo lịch, qua webhook hoặc chạy tay. Kết quả mỗi lần chạy do bạn xem lại. README nhấn mạnh: routine không bao giờ tự phê duyệt một hành động.
- **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 (chỉ 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 ngay trong app.
- **Kết nối ứ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. Mọi thay đổi vẫn chờ bạn duyệt. Ngoài ra có MCP Marketplace để thêm từng công cụ lẻ.
- **Màn hình Today.** Gom phê duyệt, câu hỏi, kết quả routine, lỗi engine và việc đến hạn vào một chỗ. Bạn không phải mở từng cuộc chat để xem cái nào đang chờ mình.
- **Bảng cô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ử.
- **Kỹ năng và mẫu.** Lưu sẵn các đoạn hướng dẫn (skill) để dùng lại cho một tin nhắn, và tạo agent từ mẫ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 công cụ.
- **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ữ (cần sự đồng ý và thông tin xác thực của bạn), duyệt hoặc tải tệp trong thư mục làm việc, và xuất lịch sử.

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

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

- **Node.js 22 trở lên.**
- **uv** (công cụ quản lý Python, xem tài liệu tại docs.astral.sh/uv).
- **Ít nhất một engine 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**.
- **Tài khoản nhà cung cấp AI của bạn.** Suparagent không kèm sẵn mô hình hay gói đăng ký mô hình. Dùng mô hình có thể tốn tiền, tùy nhà cung cấp.
- **Docker** chỉ cần nếu bạn muốn thử «máy tính cô lập» cho agent (tính năng tùy chọn, còn thử nghiệm).
- **Git** để tải mã nguồn (lệnh `git clone` ở bước dưới).

Nếu muốn tự host trên 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. Phần này còn thử nghiệm.

Tư liệu không nêu yêu cầu GPU, dung lượng ổ đĩa hay RAM, nên mình không dám nói con số nào.

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

Bản desktop là cách nhanh nhất để thử. Bạn chỉ cần tải mã nguồn rồi chạy một lệnh.

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

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

Mở terminal (trên Windows là PowerShell hoặc Terminal) và kiểm tra bạn đã có Node.js 22 trở lên chưa. README không ghi lệnh cài Node.js hay uv, nên bạn cài theo trang chủ của từng công cụ. Về engine, nếu chọn Claude Code hay Codex CLI, hãy cài và đăng nhập nó **trước** khi mở Suparagent. Đây là chỗ người mới hay vấp nhất: app không đăng nhập hộ bạn vào CLI.

```bash
node --version
```

Lệnh này in ra phiên bản Node.js đang có. Nếu số đầu nhỏ hơn 22, bạn cần nâng cấp.

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

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

Dòng đầu tải toàn bộ repo vào thư mục `suparagent`. Dòng thứ hai đi vào thư mục `desktop`, nơi chứa app. Hãy chắc rằng terminal của bạn đang đứng đúng trong thư mục này trước khi chạy lệnh tiếp theo.

### Chạy ứng dụng

```bash
npm run app
```

Đây là lệnh khởi động chính thức trong README. Lần đầu có thể mất một lúc vì app chuẩn bị môi trường. Trong repo ngoài cùng còn có tệp `run-desktop.bat`, nhưng README không giải thích cách dùng nó, nên nếu muốn thử bạn nên đọc nội dung tệp trước hoặc xem hướng dẫn desktop trong thư mục `docs/`.

### Thiết lập lần đầu

Khi mở lần đầu, app hỏi bạn chọn engine, workspace (thư mục làm việc) và chế độ phê duyệt. Sau đó làm theo thứ tự README gợi ý:

1. Mở **Settings → Engines** và xác nhận có engine ở trạng thái sẵn sàng.
2. Tạo agent với một cá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** để app dừng lại hỏi bạn trước những hành động cần duyệt.
4. Khi cần, thêm đồng đội hoặc tạo routine để chia việc hay lặp lại việc.

```note
Nếu mới dùng, hãy chọn Ask first. Agent có quyền đọc tệp trong thư mục bạn giao, và engine (nếu là dịch vụ trên mạng) sẽ nhận nội dung cần cho lượt trả lời đó. Đừng giao thư mục chứa dữ liệu nhạy cảm khi bạn chưa đọc điều khoản của nhà cung cấp engine.
```

### Còn bản cài sẵn và tự host thì sao?

README có nhắc trang Releases với các bộ cài desktop, nhưng ghi rõ chúng còn thử nghiệm, chưa ký số, và đường nâng cấp giữa các bản chưa được kiểm chứng trọn vẹn. Với tự host trên máy chủ, repo có `Dockerfile` và `compose.yaml`, tuy nhiên README chưa ghi lệnh cài cụ thể. Bạn hãy xem hướng dẫn Self-hosting trong thư mục `docs/` của repo trước khi làm.

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

Tư liệu không mô tả chính xác dòng chữ nào cho biết «thành công», nhưng các dấu hiệu theo README là:

- Cửa sổ ứng dụng mở ra và hỏi bạn chọn engine, workspace, chế độ phê duyệt.
- Trong **Settings → Engines**, engine của bạn hiện là sẵn sàng.
- Bạn tạo được một agent và gửi tin nhắn thì nhận được câu trả lời. Với chế độ Ask first, khi agent định làm việc cần duyệt, app sẽ dừng lại và hỏi bạn.

Cách thử nhanh nhất: tạo một agent, giao thư mục chứa vài tệp ghi chú nhỏ, rồi nhắn «tóm tắt các tệp trong thư mục này». Nếu có câu trả lời, mọi thứ đã nối thông.

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

Dưới đây là các tình huống bám đúng khả năng README mô tả.

### Chủ shop muốn có báo cáo dự án mỗi tuần

Bạn là chủ một cửa hàng nhỏ, cuối tuần có đống ghi chú và báo cáo rải rác trong một thư mục. Theo ví dụ trong README: tạo một agent trưởng nhóm và hai chuyên viên, chẳng hạn người nghiên cứu và người biên tập. Cho cả ba cùng một thư mục dự án, đặt engine của trưởng nhóm là Claude hoặc Codex.

Bạn nhắn cho trưởng nhóm, ví dụ:

```text
Hãy soạn 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 phần tìm số liệu cho người nghiên cứu, phần viết lại cho người biên tập.
```

Trưởng nhóm chia việc thành các việc nhỏ, từng chuyên viên làm trong cuộc trò chuyện riêng rồi trả kết quả về để trưởng nhóm ghép lại. Bạn theo dõi trong chat và duyệt khi cần. Kết quả là một bản tóm tắt tổng hợp mà bạn chỉ việc đọc và chỉnh.

> Giao việc cho AI cũng như giao cho người: có tên, có việc rõ, và chỉ làm khi mình gật đầu.
>
> — Ông T

### Nhân viên văn phòng biến việc lặp lại thành routine

Sau khi quy trình báo cáo ở trên chạy ổn, bạn tạo routine để lặp lại hằng tuần. Routine có thể chạy theo lịch, qua webhook hoặc chạy tay. Điều cần nhớ: routine chạy trong phần backend, nên backend phải đang chạy thì lịch mới hoạt động. Nghĩa là máy bạn phải bật, hoặc bạn nên đặt trên máy chủ riêng.

Mỗi lần chạy xong, kết quả nằm đó cho bạn xem. Nếu agent cần làm một hành động cần duyệt, nó sẽ hỏi bạn qua màn hình Today thay vì tự làm.

### Lập trình viên muốn một agent trong dự án mà không phụ thuộc dịch vụ đóng

Bạn đã có Claude Code hoặc Codex CLI trên máy. Tạo agent, trỏ thư mục làm việc vào dự án, đặt chế độ **Accept edits** hoặc **Ask first** tùy mức tin tưởng. Bạn có thể nối GitHub qua khóa Composio của mình để agent đọc thông tin repo (chỉ agent Claude hoặc Codex dùng được, và thay đổi vẫn chờ duyệt).

Nếu không muốn gửi dữ liệu lên dịch vụ ngoài, README cho biết bạn có thể nối engine tương thích OpenAI như Ollama hoặc LM Studio. Lưu ý README cũng nói công cụ khả dụng thay đổi theo engine, nên một số tính năng (nhập ảnh, máy tính cô lập) có thể không có với mọi engine.

### Quản lý nhiều việc từ điện thoại

Khi đã tự dựng máy chủ, bạn có thể ghép app điện thoại với máy chủ đó. Đang đi ngoài đường, bạn vẫn chat với agent, dừng một câu trả lời đang chạy sai hướng, hoặc cho phép hay từ chối một lệnh công cụ. Hiện app điện thoại mới thử trên giả lập Android và một máy Android, 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 hiện sẵn sàng

Nguyên nhân thường gặp nhất là chưa cài hoặc chưa đăng nhập engine dạng CLI trước khi mở app. Hãy đóng app, đăng nhập CLI trong terminal, rồi mở lại và kiểm tra **Settings → Engines**. Nếu dùng engine qua API, kiểm tra lại cấu hình khóa ở cùng màn hình.

### Lệnh `npm run app` báo lỗi hoặc không chạy

Có hai khả năng hay gặp. Một là bạn đang đứng sai thư mục: phải đứng trong `suparagent/desktop`. Hai là phiên bản Node.js thấp hơn 22 hoặc chưa cài uv. Chạy `node --version` để kiểm tra, cài lại phần còn thiếu rồi thử lại. Nếu vẫn lỗi, xem Issues trên GitHub của repo hoặc hỏi trong Discord của dự án.

### Tính năng agent trưởng nhóm không hoạt động

README ghi rõ trưởng nhóm cần dùng Claude hoặc Codex, và tính năng giao việc theo nhóm còn mới. Nếu bạn đặt engine khác cho trưởng nhóm thì không nên trông chờ nó chia việc được. Đổi engine của trưởng nhóm sang Claude hoặc Codex.

### 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 hoặc tắt máy, lịch sẽ không chạy. Giải pháp an toàn là để máy bật trong khung giờ đã hẹn, hoặc dùng cách tự host trên máy chủ (nhớ rằng phần này còn thử nghiệm).

### Hệ điều hành cảnh báo khi mở bộ cài

Bộ cài desktop hiện chưa được ký số và mới được kiểm chứng trên số nền tảng hạn chế, nên hệ điều hành có thể cảnh báo. Chỉ tải từ trang Releases chính thức của repo, và nếu không chắc, hãy chạy từ mã nguồn như hướng dẫn ở trên.

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

**Điểm mạnh.** Bạn giữ quyền kiểm soát: dữ liệu nằm trên máy bạn, mã nguồn mở theo giấy phép Apache-2.0, chọn được nhiều loại engine, và mọi hành động quan trọng đều có chốt duyệt của bạn. Trí nhớ có thể xem và sửa, routine không tự duyệt thay bạn. Cách tổ chức «agent có tên, có việc, có thư mục» cũng dễ hiểu với người không chuyên.

**Giới hạn.** Dự án còn đang phát triển và nhiều phần mang nhãn thử nghiệm: bộ cài desktop, máy chủ tự host (một chủ sở hữu, có thể mời đồng đội), máy tính Docker, công cụ trình duyệt, bản macOS gốc. App điện thoại chưa thử trên iOS. Phần kết nối ứng dụng qua Composio mới được thử với dịch vụ giả lập chứ chưa phải dịch vụ thật. Ngoài ra, bạn phải tự có tài khoản và tự trả tiền cho engine AI, Suparagent không kèm mô hình.

**Khi nào nên chọn cách khác.** Nếu bạn cần công cụ ổn định để chạy việc quan trọng ngay, hoặc không muốn đụng đến dòng lệnh và cài Node.js, uv, thì một ứng dụng AI có sẵn của nhà cung cấp sẽ đỡ rắc rối hơn. Nếu bạn muốn dùng bản trên web, repo có nhắc một dịch vụ hosted riêng (suparagent.ai) với các gói trả phí, nhưng đó là sản phẩm tách biệt với bản mã nguồn mở. Còn nếu bạn thích thử nghiệm, muốn tự chủ và chấp nhận một công cụ còn đang hoàn thiện, Suparagent rất đáng cài thử.

## 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 có thể tự chạy bản desktop hoặc tự host. Tuy nhiên Suparagent không kèm mô hình AI, bạn phải dùng tài khoản của nhà cung cấp riêng và việc dùng mô hình có thể tốn tiền. Bản hosted riêng (suparagent.ai) có gói Free preview và các gói trả phí Starter 15 USD, Standard 49 USD, Pro 99 USD mỗi tháng.

### Cần những gì để chạy 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 engine là CLI, hãy cài và đăng nhập trước khi mở app. Docker chỉ cần cho tính năng máy tính cô lập tùy chọn.

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

Tư liệu không nói gì về yêu cầu GPU. Suparagent dùng engine bạn tự chọn (CLI hoặc API), nên phần tính toán nặng phụ thuộc vào engine đó. Nếu bạn nối Ollama hoặc LM Studio chạy mô hình cục bộ thì yêu cầu phần cứng sẽ phụ thuộc vào mô hình, nhưng repo chưa nêu con số cụ thể.

### 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ú agent, routine và cài đặt lưu trên máy hoặc máy chủ của bạn, còn khóa API lưu qua Suparagent được mã hóa. Tuy nhiên khi agent trả lời, engine bạn chọn sẽ nhận câu lệnh và ngữ cảnh cần cho lượt đó, và 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 mà không hỏi tôi không?

Bạn chọn mức tự do: Ask first, Accept edits, Approve for me (chỉ Claude, Codex, Cursor) hoặc Plan only. Với routine, README nói rõ routine không bao giờ tự phê duyệt một hành động. Các thay đổi qua ứng dụng kết nối cũng chờ bạn duyệt.

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

README tự ghi dự án đang phát triển tích cực và khuyên đọc phần giới hạn trước khi dùng cho việc quan trọng. Bộ cài desktop, máy chủ tự host, máy tính Docker và công cụ trình duyệt đều còn thử nghiệm. Bạn nên thử với việc nhỏ trước.

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

Tư liệu không nói rõ Windows có được hỗ trợ đầy đủ hay không. README chỉ ghi bộ cài desktop chưa ký số và mới được kiểm chứng hạn chế trên một số nền tảng. Trong repo có tệp run-desktop.bat, nhưng README chưa giải thích cách dùng, nên bạn xem hướng dẫn desktop trong thư mục docs trước khi thử.
