# Suparagent: tạo đồng nghiệp AI có trí nhớ, lịch chạy, tự host — 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 'đồng nghiệp AI' có tên, có công việc riêng, trí nhớ và lịch chạy định kỳ. Bạn dùng engine và tài khoản AI của chính mình, Suparagent không kèm model. Bản desktop chạy từ mã nguồn cần Node.js 22+ và uv nên hơi kỹ thuật, nhưng chỉ có vài lệnh.

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

Suparagent là một không gian làm việc mã nguồn mở để bạn tạo ra các «đồng nghiệp AI»: mỗi agent có tên, có vai trò, có thư mục làm việc riêng, có trí nhớ và có thể chạy theo lịch. Điểm khác với một khung chat thông thường là agent làm việc lâu dài, còn bạn là người duyệt trước khi nó hành động.

Repo này hợp với người muốn giao việc lặp lại cho AI nhưng vẫn muốn giữ quyền kiểm soát: chủ shop cần tổng hợp báo cáo hằng tuần, nhân viên văn phòng cần một trợ lý đọc ghi chú, lập trình viên muốn tự host thay vì thuê dịch vụ. Bạn có thể chạy ứng dụng desktop trên máy mình, hoặc dựng server riêng. Hiện repo có khoảng 7.041 sao và 913 fork.

Điều đáng giá nhất là bạn mang engine của mình đến: Claude Code, Codex CLI, Gemini CLI, OpenRouter, hoặc API tương thích OpenAI như Ollama và LM Studio. Suparagent không bán model và không kèm model nào. Mình có làm video giới thiệu, bạn xem video ngắn bên dưới nhé.

```repo
- repo | Anil-matcha/suparagent
- kind | Ứng dụng
- desc | 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à chỉ hành động khi bạn duyệt. Chạy trên máy bạn hoặc server riê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, mình diễn giải theo 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 duyệt riêng. Một agent «trưởng nhóm» có thể 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). Theo README, 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ì nó nhớ, nên không sợ nó «nhớ sai» mà bạn không biết.
- **Chạy theo lịch (routine).** Bạn tạo routine chạy theo lịch, qua webhook hoặc chạy tay. Mỗi kết quả đều để bạn xem. Routine không bao giờ tự duyệt hành động thay bạn.
- **Chọn mức tự do cho agent.** Có bốn chế độ chính: 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). Bạn xem lại hoạt động công cụ và các quyết định duyệt trong ứng dụng.
- **Kết nối ứng dụng ngoài.** Bạn có thể nối GitHub, Gmail, Google Calendar qua khoá Composio của chính bạn, 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ụ riêng lẻ.
- **Màn hình Today.** Gom những thứ cần bạn chú ý: yêu cầu duyệt, câu hỏi từ agent, kết quả routine, lỗi engine, việc đến hạn.
- **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ử.
- **Dùng lại hướng dẫn.** Lưu skill (chỉ dẫn bạn chọn cho một tin nhắn) và tạo agent từ mẫu có sẵn.
- **Dùng trên đ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 thao tác.
- **Làm việc với tệp và lịch sử.** Tìm cuộc trò chuyện, đính kèm văn bản và ảnh, duyệt hoặc tải tệp trong workspace, xuất lịch sử.

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

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

- **Node.js 22 trở lên.**
- **uv** (công cụ quản lý Python, có hướng dẫn cài trên trang tài liệu của uv).
- **Ít nhất một engine** trên cùng máy. Nếu dùng engine dạng CLI (như Claude Code hay Codex CLI), bạn cài và đăng nhập nó trước. Nếu dùng engine qua API, bạn cấu hình trong **Settings → Engines**.
- **Docker** chỉ cần cho tính năng tuỳ chọn «máy tính cô lập» của agent.
- **Tài khoản nhà cung cấp AI** của bạn. Suparagent không kèm model hay gói đăng ký model, nên chi phí dùng model do nhà cung cấp tính.
- Tệp `git` để tải mã nguồn về.

Về hệ điều hành, README không liệt kê rõ từng hệ cho bản desktop. Repo có tệp `run-desktop.bat` ở thư mục gốc, nhưng README không giải thích tệp này, nên mình không khẳng định gì thêm. Nếu chạy server riêng, bảng so sánh trong README ghi cần máy chủ Linux, HTTPS, Docker hoặc Node.js và uv.

```note
Suparagent đang phát triển tích cực. README ghi rõ bản desktop và self-host còn ở mức thử nghiệm, bộ cài chưa ký số. Đừng giao ngay việc quan trọng, hãy thử trên thư mục mẫu trước. Engine bạn chọn sẽ nhận câu lệnh và nội dung tệp mà nó đọc, nên cân nhắc trước khi cho agent đọc 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à một engine AI đã đăng nhập
- 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 ứng dụng | Gõ lệnh npm run app
- Thiết lập lần đầu | Chọn engine, workspace và chế độ duyệt
```

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

Cài Node.js phiên bản 22 trở lên và uv. Sau đó cài engine bạn muốn dùng và đăng nhập nó. Ví dụ nếu dùng một CLI thì đăng nhập CLI trước, rồi mới mở Suparagent. Phần này mình không có lệnh cài cụ thể từ README, vì mỗi engine có cách cài riêng. Bạn xem tài liệu của engine đó, hoặc mục Engines and models trong thư mục docs của repo.

### Tải mã nguồn

Mở terminal (PowerShell trên Windows, Terminal trên macOS hoặc Linux) ở thư mục bạn muốn đặt 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.

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

Chỗ người mới hay vấp là chạy lệnh sai thư mục. Bạn phải đứng trong `suparagent/desktop` rồi mới chạy `npm run app`:

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

Lệnh `cd` đưa terminal vào thư mục desktop. Lệnh `npm run app` khởi động ứng dụng. README chỉ ghi đúng hai lệnh này cho phần khởi động, không ghi thêm bước cài phụ thuộc riêng. Nếu gặp lỗi thiếu gói, xem hướng dẫn desktop trong thư mục `docs` của repo.

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

Lần mở đầu tiên, ứng dụng yêu cầu chọn engine, workspace (thư mục làm việc) và chế độ duyệt. Sau đó:

1. Vào **Settings → Engines** và kiểm tra engine đã sẵn sàng.
2. Tạo một agent: đặt tên, viết rõ công việc, chọn workspace.
3. Bắt đầu chat. Chọn **Ask first** để ứng dụng dừng lại chờ bạn duyệt trước các hành động cần duyệt.
4. Khi cần, thêm đồng đội hoặc tạo routine.

Về bộ cài desktop, README nói có trên trang Releases nhưng đang ở mức thử nghiệm và chưa ký số. Nếu muốn tự dựng server, README chỉ nói có hướng dẫn Self-hosting trong repo và có `Dockerfile`, `compose.yaml`. README chính chưa ghi lệnh cụ thể cho phần này, bạn đọc hướng dẫn trong thư mục `docs` và thư mục `deploy`.

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

Theo README, thành công nghĩa là:

- Cửa sổ ứng dụng mở lên và hiện màn hình thiết lập lần đầu để chọn engine, workspace, chế độ duyệt.
- Trong **Settings → Engines**, engine của bạn hiện trạng thái sẵn sàng.
- Bạn tạo được một agent và nhận được câu trả lời khi chat.

Cách thử nhanh: tạo agent tên «Trợ lý thử», đặt chế độ **Ask first**, trỏ workspace vào một thư mục chứa vài tệp ghi chú. Hỏi: «Liệt kê các tệp trong thư mục này và tóm tắt từng tệp». Nếu có câu trả lời, và ứng dụng hỏi duyệt khi cần, vậy là chạy ổn. Nếu engine báo lỗi, xem mục lỗi bên dưới.

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

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

### Báo cáo dự án mỗi tuần

Bạn quản lý một dự án và có thư mục chứa ghi chú, báo cáo. Tạo một agent trưởng nhóm (engine Claude hoặc Codex), cùng hai agent chuyên môn: người nghiên cứu và người biên tập. Cho cả ba dùng chung thư mục dự án. Gửi cho trưởng nhóm câu như sau:

```text
Hãy chuẩn bị bản tóm tắt tuần này từ các ghi chú và báo cáo trong thư mục dự án. Giao người nghiên cứu gom ý chính, người biên tập viết lại cho gọn.
```

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

> Giao việc cho AI mà vẫn là người bấm duyệt cuối cùng — đó mới là cách dùng an tâm.
>
> — Ông T

### Chủ shop theo dõi việc đến hạn

Bạn có nhiều việc rải rác: trả lời khách, nhắc đối tác, ghi chú đơn. Tạo một agent «Trợ lý shop» và dùng bảng việc cùng lịch để giao việc, hẹn chạy một lần. Mỗi sáng mở màn hình Today để xem yêu cầu duyệt, câu hỏi từ agent và việc đến hạn. Nếu nối Gmail và Calendar qua khoá Composio của bạn, Today có thể hiện thư và lịch ở dạng chỉ đọc. Bạn cần agent dùng Claude hoặc Codex để kết nối ứng dụng.

### Nhân viên văn phòng giữ ngữ cảnh lâu dài

Bạn hay phải giải thích lại cùng một quy trình cho AI. Tạo agent «Trợ lý hành chính», dặn rõ công việc và quy tắc trình bày. Agent lưu ghi chú và nhớ lại ở các lần chat sau. Bạn mở phần trí nhớ để xem và sửa những gì nó đã lưu. Bạn cũng có thể lưu skill cho những chỉ dẫn hay dùng, rồi chọn skill khi gửi tin nhắn.

### Lập trình viên tự host để dùng cả nhóm

Bạn muốn agent và routine luôn chạy trên server riêng. README nói server tự host có một chủ sở hữu, người này mời được đồng đội, có vai trò và quyền riêng cho từng người. Mọi người dùng chung agent, cuộc trò chuyện và trí nhớ. Bạn đọc hướng dẫn Self-hosting trong repo, nhớ rằng routine chạy trong backend nên backend phải chạy liên tục. Bạn cũng ghép được app điện thoại với server này để duyệt hoặc từ chối thao tác từ xa.

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

**Lệnh `npm run app` báo lỗi hoặc không tìm thấy script.** Gần như chắc chắn bạn đang đứng sai thư mục. Hãy chắc rằng terminal đang ở `suparagent/desktop`, không phải thư mục gốc `suparagent`.

**Báo thiếu Node hoặc uv, hoặc phiên bản cũ.** README yêu cầu Node.js 22 trở lên và uv. Kiểm tra phiên bản bằng `node --version`, cập nhật nếu thấp hơn 22. Với uv, xem trang hướng dẫn cài của uv.

**Engine không sẵn sàng trong Settings → Engines.** Nếu dùng engine CLI, bạn cần cài và đăng nhập nó trước khi mở Suparagent. Nếu dùng engine API, kiểm tra lại cấu hình trong Settings → Engines. Lưu ý không phải engine nào cũng hỗ trợ ảnh hoặc máy tính cô lập, nên một tính năng không chạy chưa chắc là lỗi của bạn.

**Routine không chạy đúng giờ.** README nói routine chạy trong backend, nên backend phải đang chạy. Tắt máy hoặc tắt ứng dụng thì lịch không chạy. Muốn chạy đều, hãy tự host trên một server luôn bật.

**Tính năng nâng cao hoạt động không ổn.** Docker computers, công cụ trình duyệt, MCP Marketplace, kết nối ứng dụng qua Composio và phiên âm giọng nói đều được README xếp vào dạng thử nghiệm hoặc chưa kiểm chứng đầy đủ. Nếu vướng, hãy dùng các tính năng cơ bản trước, rồi hỏi trên Discord hoặc báo lỗi ở GitHub Issues.

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

**Điểm mạnh.** Mã nguồn mở theo giấy phép Apache-2.0. Bạn chọn engine tuỳ ý, kể cả chạy model cục bộ qua Ollama hay LM Studio. Dữ liệu trò chuyện, ghi chú, routine nằm trên máy hoặc server của bạn, khoá API lưu trong Suparagent được mã hoá. Mọi hành động đều có cơ chế duyệt, và routine không tự duyệt.

**Giới hạn.** Dự án còn non. Bản desktop và self-host là thử nghiệm, bộ cài chưa ký số, đường cập nhật giữa các bản chưa được kiểm chứng đầu-cuối. Nhóm agent là tính năng mới và trưởng nhóm phải dùng Claude hoặc Codex. App điện thoại mới thử trên Android, chưa có iOS, chưa có thông báo đẩy. Kết nối ứng dụng qua Composio mới được kiểm thử với dịch vụ giả lập. Server tự host không phải dịch vụ nhiều tổ chức. Ngoài ra, cài từ mã nguồn đòi hỏi bạn quen dùng terminal.

**Chi phí.** Bản tự host và desktop là mã nguồn mở, nhưng bạn vẫn trả tiền cho nhà cung cấp model nếu engine của bạn tính phí. Bản hosted trên suparagent.ai là sản phẩm riêng, có gói trả phí, bạn xem trang giá của họ.

**Khi nào 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 có sẵn là đủ. Nếu việc quan trọng và cần độ ổn định cao ngay, hãy chờ dự án trưởng thành hơn. Còn nếu bạn muốn một đội agent có trí nhớ, có lịch chạy và có chốt duyệt, trên hạ tầng do mình kiểm soát, Suparagent đáng để thử trên một thư mục mẫu.

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

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

Bản desktop và self-host là mã nguồn mở theo giấy phép Apache-2.0, bạn không phải trả phí cho Suparagent. Tuy nhiên Suparagent không kèm model, bạn dùng tài khoản hoặc API của nhà cung cấp AI nên có thể mất phí ở đó. Bản hosted trên suparagent.ai là sản phẩm riêng với các gói Free preview, Starter, Standard và Pro.

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

README yêu cầu 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, là tính năng tuỳ chọn. Bạn tải mã nguồn bằng git rồi chạy npm run app trong thư mục desktop.

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

Tư liệu không nói gì về yêu cầu GPU. Suparagent dùng engine mà bạn tự kết nối, ví dụ Claude Code, Codex hoặc API. Nếu bạn chạy model cục bộ qua Ollama hay LM Studio thì phần cứng phụ thuộc model đó, README không đưa thông tin này.

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

README không nêu rõ danh sách hệ điều hành cho bản desktop, chỉ nói bộ cài chưa ký số và mới được kiểm chứng nền tảng ở mức hạn chế. Repo có tệp run-desktop.bat nhưng README không giải thích nó. Bản server tự host được ghi là cần máy chủ Linux.

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

Với desktop và self-host, cuộc trò chuyện, ghi chú, routine và cài đặt nằm trong thư mục dữ liệu hoặc cơ sở dữ liệu của máy bạn, khoá API lưu trong Suparagent được mã hoá. Tuy nhiên engine bạn chọn sẽ nhận câu lệnh và nội dung cần cho lượt đó, có thể gồm tệp bạn đính kèm. Nếu engine là dịch vụ trực tuyến 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 quyết định mức tự do. Chế độ Ask first dừng lại để chờ bạn duyệt, các chế độ khác gồm Accept edits, Approve for me và Plan only. README ghi rõ routine không bao giờ tự duyệt một hành động thay bạn.

### Dùng được trên điện thoại không?

Có app điện thoại, ghép với server của chính bạn để chat, dừng câu trả lời, cho phép hoặc từ chối thao tác. README nói app mới được thử trên giả lập Android và một điện thoại Android, chưa thử trên iOS, chưa có thông báo đẩy hay bản trên cửa hàng ứng dụng.
