# Suparagent: lập đồng nghiệp AI có trí nhớ, lịch chạy, chờ bạn duyệt — cài và dùng

> Suparagent là ứng dụng mã nguồn mở (Apache-2.0) giúp bạn tạo các đồng nghiệp AI có tên, có vai trò, có trí nhớ và lịch chạy riêng, chạy trên máy hoặc máy chủ của bạn. Nó không kèm sẵn mô hình AI, bạn phải tự mang theo engine như Claude Code, Codex, Gemini CLI hay API tương thích OpenAI. Cài bản desktop cần Node.js 22+, uv và một engine; README ghi đây là bản thử nghiệm.

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

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» có tên riêng. Mỗi agent có một công việc, một thư mục làm việc, trí nhớ riêng, và có thể chạy theo lịch. Điều quan trọng nhất: agent phải hỏi bạn trước khi làm những việc cần duyệt. Bạn có thể chạy nó như ứng dụng desktop trên máy mình, hoặc tự dựng lên một máy chủ của riêng bạn.

Repo này hợp với người muốn dùng AI như một nhóm nhân viên thay vì một khung chat đơn lẻ. Ví dụ: chủ shop muốn có agent tổng hợp báo cáo mỗi tuần, nhân viên văn phòng muốn một «trợ lý» nhớ được ngữ cảnh dự án, hay lập trình viên mới muốn thử mô hình lead giao việc cho các chuyên viên. Bạn cũng không bị khoá vào một hãng AI: Suparagent nối được với nhiều engine khác nhau.

Điểm đáng giá nhất là cơ chế duyệt. Bạn chọn mức tự do cho agent (hỏi trước mọi thứ, chỉ cho sửa file, hoặc chỉ lập kế hoạch), và ngay cả khi chạy theo lịch, README nói rõ một routine không bao giờ tự phê duyệt thay bạn. Hiện repo có khoảng 7.041 sao và 913 fork. Mình cũng đã có 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 | Suparagent là không gian làm việc mã nguồn mở để tạo các agent AI có tên, có trí nhớ, chạy theo lịch và luôn 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à những 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à cài đặt duyệt. Bạn có thể tạo một agent «trưởng nhóm» giao việc cho các chuyên viên (ví dụ người nghiên cứu, người biên tập), hoặc cho nhiều agent làm việc chung trong một phòng. README ghi 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 cũ, tìm lại lịch sử. Bạn xem và sửa được những gì nó nhớ, nên không sợ nó nhớ sai mà không biết.
- **Chạy việc theo lịch.** Routine chạy theo giờ, theo webhook hoặc bấm tay. Bạn xem kết quả từng lần chạy và trả lời các yêu cầu duyệt. Lưu ý: routine chạy ở backend, nên backend phải luôn bật.
- **Chọn mức tự do cho agent.** Có các chế độ: Ask first (hỏi trước), Accept edits (cho sửa), Approve for me (có 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 khoá Composio của chính bạn, nối GitHub, Gmail, Google Calendar 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. Ngoài ra có MCP Marketplace để thêm từng công cụ 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 từ agent, 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à lần thử.
- **Kỹ năng và mẫu.** Lưu sẵn các đoạn hướng dẫn (skill) để dùng cho một tin nhắn, và tạo agent từ mẫu có sẵn cho nhanh.
- **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ụ. README ghi app này mới thử trên Android, chưa thử trên iOS.
- **Làm việc với file.** Tìm kiếm hội thoại, đính kèm văn bản và ảnh, nhập âm thanh để chép lời (cần bạn đồng ý và có thông tin đăng nhập), duyệt hoặc tải file trong workspace, xuất lịch sử.

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

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

- **Node.js 22 trở lên.**
- **uv** (công cụ quản lý Python, có hướng dẫn trên trang docs.astral.sh/uv).
- **Ít nhất một engine** có 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ở Suparagent. 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 máy tính cô lập cho agent (tính năng tuỳ chọn).

Về engine, README liệt kê: Claude Code hoặc Codex CLI, Gemini CLI, Google Gemini qua Antigravity, Cursor, các 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ợ đủ tính năng; ví dụ nhập ảnh và máy tính của agent không có ở mọi engine.

```note
Suparagent không kèm mô hình AI hay gói đăng ký mô hình. Bạn tự mang tài khoản, đăng nhập CLI hoặc API key, và dùng mô hình có thể tốn tiền theo nhà cung cấp bạn chọn.
```

README không nêu yêu cầu hệ điều hành cụ thể cho bản desktop. Nó chỉ ghi bộ cài là thử nghiệm, chưa ký số và mới được kiểm chứng trên vài nền tảng. Về phần cứng, tư liệu cũng không nói gì thêm.

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

```steps
- Chuẩn bị nền | 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 để lấy repo về máy
- Chạy ứng dụng | Vào thư mục desktop rồi chạy npm run app
- Cấu hình lần đầu | Chọn engine, workspace 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ị Node.js, uv và engine

Cài Node.js bản 22 trở lên và uv theo hướng dẫn của từng công cụ. README không đưa lệnh cài riêng cho hai thứ này nên mình không chép lệnh nào ở đây. Sau đó chọn một engine. Nếu là Claude Code hay Codex CLI, bạn hãy cài và đăng nhập nó trước, rồi mới mở Suparagent. Chỗ này người mới hay vấp nhất: mở app lên mà chưa có engine nào sẵn sàng thì agent không trả lời được.

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

Mở terminal (PowerShell hoặc Git Bash trên Windows, Terminal trên macOS/Linux) tại thư mục bạn muốn lưu dự án. Cần có Git trên máy.

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

Lệnh đầu tải toàn bộ repo về thành thư mục `suparagent`. Lệnh thứ hai đi vào thư mục con `desktop`, nơi chứa app.

### Chạy ứng dụng

Đứng trong thư mục `desktop`, chạy đúng lệnh README ghi:

```bash
npm run app
```

README không ghi thêm bước cài phụ thuộc nào riêng, và mình không tự thêm lệnh ngoài tư liệu. Nếu gặp lỗi thiếu gói, hãy xem hướng dẫn thiết lập desktop trong thư mục `docs/` của repo. Trong thư mục gốc còn có file `run-desktop.bat`, nhưng README Quick start không nhắc tới nó, nên bạn muốn dùng thì hãy mở file đọc trước.

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

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

Ngoài cách chạy từ mã nguồn, README có nhắc trang Releases trên GitHub với bộ cài desktop, nhưng ghi rõ chúng thử nghiệm và chưa ký số. Tính năng cập nhật chỉ đưa bộ cài đã kiểm tra SHA-256 để bạn tự mở, không tự cài.

Về chạy trên máy chủ, repo có `Dockerfile` và `compose.yaml`, và README trỏ tới hướng dẫn self-hosting riêng (yêu cầu Linux, HTTPS, Docker hoặc Node.js và uv, cùng một engine). README chính không chép các lệnh dựng máy chủ, nên bạn hãy đọc hướng dẫn self-hosting trong `docs/` trước khi làm.

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

Tư liệu không nêu một lệnh kiểm tra riêng, nhưng các dấu hiệu thành công theo README là:

- Sau `npm run app`, ứng dụng mở lên và hỏi bạn chọn engine, workspace, chế độ duyệt.
- Trong **Settings → Engines**, engine bạn chọn hiện trạng thái sẵn sàng.
- Bạn tạo được một agent, gửi một tin nhắn và nhận 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 chờ bạn bấm cho phép.

Cách thử đơn giản: tạo agent tên «Trợ lý thử», giao việc «đọc các file trong thư mục này và tóm tắt», rồi nhờ nó liệt kê file. Nếu có câu trả lời và (với Ask first) có yêu cầu duyệt hiện ra, tức là mọi thứ đã nối thông.

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

Các tình huống dưới đây bám theo khả năng có trong README. Cách nói cụ thể trong câu lệnh mẫu là do mình gợi ý.

### Chủ shop: báo cáo tuần từ ghi chú rải rác

Bạn có thư mục chứa ghi chú bán hàng, báo cáo tồn kho và phản hồi khách. Hãy tạo một agent trưởng nhóm (dùng engine Claude hoặc Codex) và hai chuyên viên: một người nghiên cứu, một người biên tập. Cho cả ba cùng trỏ vào thư mụ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 cho dễ đọc.
```

Trưởng nhóm chia việc thành các phần nhỏ, giao cho chuyên viên làm trong các cuộc trò chuyện riêng rồi nhận về để ghép. Đây chính là ví dụ «bản tóm tắt dự án hằng tuần» trong README. Khi quy trình chạy ổn, bạn biến nó thành routine hằng tuần và xem kết quả từng lần.

> Thay vì nhớ nhắc AI mỗi tuần, bạn giao một lần, đặt lịch, rồi chỉ việc duyệt.
>
> — Ông T

### Nhân viên văn phòng: trợ lý nhớ ngữ cảnh dự án

Bạn làm một dự án kéo dài nhiều tuần. Tạo một agent riêng cho dự án đó, giao nó thư mục tài liệu. Khi trò chuyện, nhờ nó ghi lại các quyết định quan trọng. Lần sau mở lại, hỏi «tuần trước mình chốt gì về ngân sách?», agent có thể nhớ lại ghi chú và tìm lịch sử trò chuyện. Nếu nó nhớ sai, bạn mở phần trí nhớ để sửa hoặc xoá. Kết quả: bớt phải dán lại bối cảnh vào mỗi cuộc chat mới.

### Người hay quên việc: màn hình Today

Bạn kết nối Gmail và Google Calendar qua khoá Composio của mình (chỉ agent Claude hoặc Codex dùng được). Mỗi sáng mở màn hình Today: nó gom các yêu cầu duyệt đang chờ, câu hỏi từ agent, kết quả routine, lỗi engine và việc đến hạn, kèm thư và lịch ở chế độ chỉ đọc. Bạn xử lý một chỗ thay vì lục từng cuộc chat. README lưu ý phần kết nối ứng dụng mới được thử với một dịch vụ Composio giả, chưa thử với dịch vụ thật, nên hãy thử trên dữ liệu ít quan trọng trước.

### Lập trình viên mới: thử agent lead và routine

Bạn muốn học cách một đội agent phối hợp. Dựng trưởng nhóm bằng Claude hoặc Codex, thêm vài chuyên viên cho cùng một repo cá nhân, rồi nhờ trưởng nhóm làm một việc nhỏ, ví dụ rà soát tài liệu trong thư mục. Đặt chế độ Plan only hoặc Ask first để mọi thứ phải qua bạn duyệt, đồng thời xem lại hoạt động công cụ trong app để hiểu agent đã làm gì. Muốn lặp lại thì tạo routine chạy theo lịch hoặc theo webhook.

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

### App mở lên nhưng agent không trả lời

Thường là chưa có engine sẵn sàng. Vào **Settings → Engines** kiểm tra. Với engine CLI, README yêu cầu cài và đăng nhập trước khi mở app, nên hãy đăng nhập lại trong terminal rồi mở lại Suparagent. Với engine API, kiểm tra lại cấu hình bạn nhập.

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

Trước hết xem bạn có đang đứng trong thư mục `suparagent/desktop` không, rồi kiểm tra Node.js đã từ 22 trở lên và uv đã cài chưa. Nếu vẫn lỗi, README chưa ghi chi tiết xử lý; hãy xem phần thiết lập desktop trong `docs/` hoặc hỏi trên GitHub Issues và Discord của dự án.

### Routine không chạy đúng giờ

README nói routine chạy ở backend, nên backend phải luôn bật. Nếu bạn tắt máy hoặc tắt app/máy chủ thì lịch sẽ không chạy. Muốn lịch chạy ổn định, hãy cân nhắc tự host trên một máy chủ luôn mở, nhưng nhớ đây là tính năng thử nghiệm.

### Agent không dùng được ứng dụng đã kết nối hoặc tính năng nhóm

Theo README, ứng dụng kết nối qua Composio chỉ dùng được với agent Claude hoặc Codex, và trưởng nhóm cũng phải là Claude hoặc Codex. Nếu bạn chọn engine khác, các tính năng này sẽ không có. Đổi engine của agent đó, hoặc chấp nhận dùng agent đơn lẻ.

### Lo ngại về dữ liệu gửi đi

Khi agent trả lời, engine bạn chọn nhận câu lệnh và ngữ cảnh cần cho lượt đó, có thể gồm văn bản đính kèm, ghi chú liên quan và nội dung workspace mà engine đọc. Nếu engine là dịch vụ trên mạng, thông tin sẽ do nhà cung cấp đó xử lý theo điều khoản của họ. Với dữ liệu nhạy cảm, hãy chọn engine chạy nội bộ (như Ollama hoặc LM Studio qua API tương thích OpenAI), và đừng trỏ workspace vào thư mục chứa thứ không muốn chia sẻ.

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

**Điểm mạnh.** Ý tưởng «đồng nghiệp AI» rõ ràng: agent có tên, vai trò, trí nhớ, lịch chạy, và luôn qua bạn duyệt. Mã nguồn mở theo giấy phép Apache-2.0. Dữ liệu của bản desktop và tự host nằm ở máy hoặc máy chủ của bạn (khoá API lưu qua Suparagent được mã hoá), workspace nằm trong thư mục bạn chỉ định. Bạn cũng chọn được nhiều loại engine, kể cả mô hình chạy nội bộ.

**Giới hạn.** README tự nhận dự án đang phát triển nhanh. Bộ cài desktop thử nghiệm và chưa ký số; máy chủ tự host cũng thử nghiệm, chỉ có một chủ sở hữu mời được đồng đội, mọi người dùng chung agent, hội thoại và trí nhớ. App điện thoại chưa thử trên iOS, chưa có thông báo đẩy. Docker computer, công cụ trình duyệt và bản macOS gốc đều là tuỳ chọn thử nghiệm. Marketplace MCP, trích xuất âm thanh và máy tính đám mây chưa qua kiểm chứng trên dịch vụ thật.

**Chi phí.** Phần mềm tự host không kèm mô hình, bạn trả tiền cho nhà cung cấp AI nếu dùng mô hình trả phí. Ngoài ra còn có dịch vụ web riêng của Suparagent (gói Free preview, Starter 15 USD, Standard 49 USD, Pro 99 USD mỗi tháng, theo README), nhưng đó là sản phẩm tách biệt với bản mã nguồn mở và có chính sách dữ liệu riêng.

**Khi nên chọn cách khác.** Nếu bạn chỉ cần một khung chat để hỏi đáp thỉnh thoảng, dùng thẳng công cụ chat quen thuộc sẽ nhanh hơn. Nếu cần hệ thống ổn định cho công việc quan trọng, nhiều người dùng trong nhiều tổ chức, hoặc bản cài đã ký số và có hỗ trợ chính thức, thì bản hiện tại chưa phải lựa chọn an toàn. Còn nếu bạn thích thử nghiệm, muốn tự kiểm soát và không ngại cài từ mã nguồn, Suparagent đáng để bạn dành một buổi tố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 và bản desktop hoặc tự host dùng được không mất phí phần mềm. Tuy nhiên, Suparagent không kèm mô hình AI, nên bạn vẫn phải tự trả phí cho nhà cung cấp mô hình nếu dùng dịch vụ trả phí. Ngoài ra còn có dịch vụ web riêng với các gói trả phí, là sản phẩm tách biệt.

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

Tư liệu không nêu yêu cầu GPU hay phần cứng nào cho Suparagent. Vì app dùng engine bạn tự mang theo, nhu cầu phần cứng phụ thuộc vào engine đó, ví dụ mô hình chạy nội bộ qua Ollama hay LM Studio sẽ cần máy mạnh hơn. Về chi tiết cụ thể, tài liệu chưa có thông tin.

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

README không liệt kê hệ điều hành cho bản desktop, chỉ nói bộ cài là thử nghiệm, chưa ký số và mới kiểm chứng trên một số nền tảng. Trong repo có file run-desktop.bat, nhưng README chính không giải thích về nó. Với tự host, README yêu cầu máy chủ Linux.

### 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 nằm ở thư mục dữ liệu hoặc cơ sở dữ liệu của chính bạn, khoá API lưu qua Suparagent được mã hoá. Nhưng khi agent trả lời, engine bạn chọn nhận câu lệnh và ngữ cảnh của lượt đó, nên nếu engine là dịch vụ trên mạng thì dữ liệu do nhà cung cấp đó xử lý. Dịch vụ web riêng của Suparagent có chính sách quyền riêng tư riêng.

### Cần những engine hoặc tài khoản AI nào?

Bạn cần ít nhất một engine: Claude Code, Codex CLI, Gemini CLI, Gemini qua Antigravity, Cursor, agent ACP khác, OpenRouter hoặc API tương thích OpenAI như Ollama và LM Studio. Engine dòng lệnh phải cài và đăng nhập trước khi mở app. Trưởng nhóm agent và ứng dụng kết nối qua Composio chỉ dùng được với Claude hoặc Codex.

### Agent có tự làm việc quan trọng mà không hỏi tôi không?

Bạn quyết định qua các chế độ: Ask first, Accept edits, Approve for me (cho Claude, Codex, Cursor) và Plan only. README nói routine chạy theo lịch không bao giờ tự phê duyệt hành động thay bạn, và thay đổi từ ứng dụng kết nối cũng chờ bạn duyệt. Hãy chọn Ask first nếu muốn kiểm soát chặt nhất.

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

README nêu rõ dự án đang phát triển, bản desktop và máy chủ tự host là thử nghiệm, nhiều tính năng mới chưa qua kiểm chứng trên dịch vụ thật. Bạn nên đọc phần Known limitations trong README trước khi dùng cho việc quan trọng. Repo vẫn được cập nhật trong vài tháng gần đây.
