# Suparagent: tạo đồng nghiệp AI có trí nhớ, lịch chạy, duyệt trước khi làm — cài 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ó việc riêng, có trí nhớ và lịch chạy, và chỉ hành động khi bạn duyệt. Bạn dùng bản desktop chạy từ mã nguồn hoặc tự dựng máy chủ riêng. Cài không quá khó nếu đã có Node.js 22+, uv và một engine AI, 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-13 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/suparagent-dong-nghiep-ai-tu-host-huong-dan-cai-dat-mwe0jrqr

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 quan trọng nhất: agent không tự làm bừa. Bạn chọn mức duyệt, và với những việc cần xin phép thì agent dừng lại chờ bạn bấm đồng ý.

Repo hợp với người muốn giao việc lặp lại cho AI mà vẫn kiểm soát được: nhân viên văn phòng cần bản tóm tắt dự án mỗi tuần, chủ shop muốn có “trợ lý” riêng cho từng mảng, hoặc lập trình viên mới muốn thử mô hình nhiều agent phối hợp. Bản desktop và bản tự dựng máy chủ đều chạy trên máy của bạn, không bắt buộc dùng dịch vụ trả phí của tác giả. Hiện repo có khoảng 7.041 sao và 913 fork, giấy phép Apache-2.0.

Có một điều bạn cần biết ngay từ đầu: Suparagent không đi kèm mô hình AI hay gói đăng ký mô hình nào. Bạn phải tự mang theo “engine” (ví dụ một công cụ dòng lệnh đã đăng nhập, hoặc một API key). Tác giả cũng ghi rõ dự án đang phát triển tích cực và nhiều phần còn thử nghiệm. Xem video ngắn bên dưới để thấy giao diện 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à 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à 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. Bạn có thể đặt một agent “trưởng nhóm” giao việc cho các agent chuyên môn, hoặc cho nhiều agent phối hợp trong phòng chung. Trưởng nhóm hiện cần dùng Claude hoặc Codex. Lợi ích: chia nhỏ một việc lớn thay vì nhồi hết vào một cuộc chat.
- **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, tìm trong lịch sử. Bạn xem và sửa được những gì agent đã nhớ. Lợi ích: khỏi phải giải thích lại bối cảnh mỗi lần.
- **Chạy việc theo lịch (routine).** Routine có thể chạy theo lịch, theo webhook hoặc chạy tay. Bạn xem kết quả từng lần chạy; routine không bao giờ tự duyệt một hành động thay bạn. Lợi ích: việc lặp lại hằng tuần được tự động hoá mà vẫn an toàn.
- **Chọn mức tự do cho agent.** Có các 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). Bạn xem được lịch sử dùng công cụ và các quyết định duyệt trong ứng dụng.
- **Kết nối công cụ và ứng dụng.** Qua khoá Composio của chính bạn, có thể nối các dịch vụ như GitHub, Gmail, Google Calendar rồi cấp quyền cho từng agent Claude hoặc Codex được chọn. Thay đổi vẫn chờ bạn duyệt. Ngoài ra có thể thêm từng công cụ từ MCP Marketplace.
- **Màn hình Today.** Gom lại những thứ 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 mục Gmail và lịch ở chế độ chỉ đọc.
- **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ử.
- **Dùng lại hướng dẫn.** Lưu “skill” (hướng 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 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ần gọi công cụ, tạo hoặc sửa agent. Hiện mới thử trên Android, chưa thử trên iOS.
- **Làm việc với tệp và lịch sử.** Tìm kiế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, xuất lịch sử.

Suparagent hỗ trợ nhiều engine: Claude Code hoặc Codex CLI, Gemini CLI, Google Gemini qua Antigravity, Cursor, công cụ dòng lệnh khác dùng giao thức Agent Client Protocol (ACP), OpenRouter, hoặc API tương thích OpenAI như Ollama và LM Studio. Không phải engine nào cũng hỗ trợ đủ tính năng; ví dụ nhận ảnh hoặc máy tính cô lập cho agent không có ở mọi engine.

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

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

- **Node.js 22 trở lên.**
- **uv** (công cụ quản lý Python, có trang hướng dẫn riêng 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 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 khi bạn muốn dùng các “máy tính cô lập” cho agent (tính năng tuỳ chọn, còn thử nghiệm).

Về hệ điều hành: trong repo có file run-desktop.bat (gợi ý hỗ trợ Windows), nhưng README không nêu rõ danh sách hệ điều hành cho bản desktop. Tác giả cũng cho biết bộ cài desktop là thử nghiệm, chưa ký số và mới được kiểm chứng hạn chế trên các nền tảng. Bản tự dựng máy chủ thì cần máy chủ Linux, HTTPS, Docker hoặc Node.js cùng uv, và một engine.

Về chi phí: README nói rõ bạn tự mang tài khoản nhà cung cấp AI và trả tiền cho nhà cung cấp đó nếu có tính phí. Bản desktop và bản tự dựng không đòi tài khoản của Suparagent.

```note
Engine là nơi nhận nội dung bạn gửi. Khi agent trả lời, engine nhận câu lệnh và ngữ cảnh của lượt đó (văn bản bạn đính kèm, ghi chú liên quan, 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. Đừng cho agent đọc thư mục chứa thông tin nhạy cảm nếu bạn chưa yên tâm về engine.
```

## 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
- 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 desktop của repo
- Chạy ứng dụng | Gõ lệnh npm run app
- Cài đặt lần đầu | Chọn engine, thư mục làm việc và chế độ duyệt
```

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

Hãy chắc chắn máy bạn đã có Node.js bản 22 trở lên và uv. README không ghi lệnh cài hai công cụ này, nên bạn cài theo trang chủ của từng công cụ. Sau đó chuẩn bị engine: nếu dùng CLI như Claude Code hay Codex, hãy cài và đăng nhập xong trước khi mở Suparagent. Nếu muốn dùng API, bạn sẽ điền trong phần Settings sau khi ứng dụng mở lên.

### Tải mã nguồn

Mở terminal (trên Windows có thể dùng PowerShell hoặc Git Bash) tại 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ải toàn bộ mã nguồn về một thư mục tên suparagent. Bạn cần cài sẵn Git; nếu terminal báo không nhận lệnh git thì cài Git trước.

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

Theo README, hai lệnh tiếp theo là:

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

Lệnh đầu đưa terminal vào thư mục desktop. Chỗ người mới hay vấp: phải chạy `npm run app` đúng trong thư mục desktop, không phải thư mục gốc suparagent. README không ghi một bước cài phụ thuộc riêng (như npm install) trước lệnh này, nên bạn cứ làm đúng theo trình tự trên; nếu có lỗi thiếu gói, xem thư mục docs trong repo (phần hướng dẫn thiết lập desktop).

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

Lần mở đầu tiên, ứng dụng yêu cầu bạn chọn engine, thư mục làm việc (workspace) và chế độ duyệt. Nếu chưa chắc, hãy chọn chế độ **Ask first** để mọi hành động quan trọng đều dừng lại hỏi bạn. Sau đó làm tiếp:

1. Mở **Settings → Engines** và xác nhận có một engine ở trạng thái sẵn sàng.
2. Tạo một agent với tên, công việc rõ ràng và một thư mục làm việc.
3. Bắt đầu chat.
4. Khi cần, thêm đồng đội hoặc tạo routine.

### Muốn tự dựng máy chủ thay vì dùng desktop?

Trong repo có Dockerfile và compose.yaml, nhưng README chưa ghi lệnh cụ thể cho cách này. Hãy đọc hướng dẫn self-hosting trong thư mục docs của repo trước khi làm, vì cách này cần máy chủ Linux và HTTPS, và còn ở mức thử nghiệm.

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

Theo tư liệu, bạn biết cài thành công khi 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). Sau đó có ba dấu hiệu nên kiểm tra:

- Trong **Settings → Engines**, engine bạn chọn hiện là sẵn sàng.
- Bạn tạo được một agent và gửi một tin nhắn đơn giản, ví dụ “Hãy giới thiệu ngắn về công việc của bạn”, rồi nhận được câu trả lời.
- Với chế độ **Ask first**, khi bạn nhờ agent làm việc cần quyền (như sửa tệp), ứng dụng hiện yêu cầu duyệt thay vì tự làm.

Nếu cả ba đều đúng, bạn đã sẵn sàng. README không mô tả một dòng chữ “thành công” cụ thể nào trong terminal, nên đừng chờ một thông báo đặc biệt.

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

### Nhân viên văn phòng: bản tóm tắt dự án hằng tuần

Bạn quản lý một dự án và mỗi tuần phải tổng hợp ghi chú, báo cáo rải rác trong một thư mục. Hãy tạo một agent trưởng nhóm, thêm hai agent chuyên môn là “người nghiên cứu” và “người biên tập”, cho cả ba cùng thư mục dự án, và đặt engine của trưởng nhóm là Claude hoặc Codex (README yêu cầu vậy cho việc giao việc theo nhóm). Gửi cho trưởng nhóm một câu như:

```text
Hãy đọc các ghi chú và báo cáo trong thư mục dự án, rồi soạn bản tóm tắt tuần này: việc đã xong, việc đang kẹt, việc cần quyết định.
```

Trưởng nhóm chia nhỏ yêu cầu, giao cho các agent kia chạy ở những cuộc trò chuyện riêng, rồi gom về ráp thành bản tóm tắt. Bạn theo dõi trong chat và duyệt khi cài đặt yêu cầu.

> Giao việc cho AI không có nghĩa là buông tay; điều đáng giá là nó làm, còn bạn là người bấm đồng ý.
>
> — Ông T

### Chủ shop nhỏ: biến việc lặp lại thành routine

Khi bản tóm tắt ở trên đã ổn, bạn chuyển nó thành routine chạy hằng tuần. Chủ shop có thể áp dụng cùng cách: một agent đọc file ghi chú bán hàng trong thư mục và soạn nhận xét cuối tuần. Bạn tạo routine với lịch chạy, rồi mở ứng dụng xem kết quả từng lần. Lưu ý: routine chạy ở backend nên backend phải luôn chạy; nếu tắt máy hoặc tắt ứng dụng thì lịch không chạy. Kết quả là mỗi tuần bạn có sẵn một bản nháp để đọc, không cần nhờ lại từ đầu.

### Người bận rộn: xem mọi thứ cần chú ý trong màn hình Today

Nếu bạn có nhiều agent và routine, mở màn hình Today để xem một chỗ: yêu cầu cần duyệt, câu hỏi agent đang chờ, kết quả routine, lỗi engine, việc đến hạn. Nếu đã nối Gmail và lịch qua Composio, màn hình này có thể hiện thêm mục thư và sự kiện ở chế độ chỉ đọc. Bạn sẽ đỡ phải mở từng cuộc chat để dò xem agent nào đang chờ mình.

### Lập trình viên mới: thử nghiệm nhiều agent trên một dự án

Bạn muốn học cách phối hợp nhiều agent AI. Hãy tạo agent từ mẫu có sẵn, dùng chế độ **Plan only** để agent chỉ lập kế hoạch, đọc kế hoạch rồi mới chuyển sang **Ask first** để cho thực hiện từng bước. Cách này giúp bạn thấy rõ agent định làm gì và xem lại lịch sử dùng công cụ trong ứng dụng, một cách học an toàn trước khi cho agent nhiều quyền hơn.

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

- **Terminal báo không nhận lệnh npm, git hoặc uv.** Công cụ chưa được cài hoặc terminal chưa nhận. Cài công cụ còn thiếu rồi mở terminal mới và thử lại.
- **Lệnh npm run app báo không tìm thấy script.** Rất có thể bạn đang đứng sai thư mục. Đảm bảo bạn đã chạy `cd suparagent/desktop` và đang ở trong thư mục desktop. Kiểm tra thêm phiên bản Node.js đạt 22 trở lên.
- **Engine không hiện là sẵn sàng.** Với engine dạng CLI, hãy chắc chắn đã cài và đăng nhập engine đó trên cùng máy trước khi mở ứng dụng. Với engine API, kiểm tra lại cấu hình trong Settings → Engines. Đừng dán khoá API vào tin nhắn chat.
- **Không thấy tính năng giao việc hoặc kết nối ứng dụng.** Một số tính năng chỉ chạy với engine Claude hoặc Codex (giao việc theo nhóm, ứng dụng kết nối qua Composio). Nếu bạn đang dùng engine khác, hãy đổi engine của agent liên quan.
- **Routine không chạy đúng giờ.** Routine chạy ở backend, nên backend phải đang chạy. Giữ ứng dụng hoặc máy chủ hoạt động vào giờ hẹn.
- **Muốn dùng Docker cho máy tính cô lập nhưng không chạy được.** Tính năng này là tuỳ chọn và còn thử nghiệm. Kiểm tra Docker đã cài và đang chạy, rồi đọc hướng dẫn agent computers trong thư mục docs.

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

**Điểm mạnh.** Bạn kiểm soát được từng bước nhờ các chế độ duyệt, và routine không tự duyệt hành động thay bạn. Dữ liệu của bản desktop và tự dựng nằm trên máy hoặc máy chủ của bạn; khoá API lưu qua Suparagent được mã hoá. Bạn tự chọn engine, kể cả engine chạy cục bộ như Ollama hoặc LM Studio. Giấy phép Apache-2.0 và mã nguồn mở nên dễ kiểm tra, sửa đổi.

**Giới hạn.** Tác giả nói thẳng dự án còn đang phát triển, bản tự dựng máy chủ là thử nghiệm và chỉ có một chủ sở hữu (có thể mời đồng đội, nhưng mọi người dùng chung agent, hội thoại và trí nhớ). Bộ cài desktop chưa ký số, quy trình cập nhật chưa được kiểm chứng đầu-cuối. Giao việc theo nhóm là tính năng mới. App điện thoại chưa thử trên iOS và chưa có thông báo đẩy. Ứng dụng kết nối qua Composio mới được thử với dịch vụ giả lập, chưa thử với dịch vụ thật. Docker computer, công cụ trình duyệt cũng còn thử nghiệm.

**Khi nào chọn cách khác.** Nếu bạn cần một công cụ ổn định để giao việc quan trọng ngay hôm nay, hoặc không muốn đụng tới Node.js, uv và dòng lệnh, hãy cân nhắc một dịch vụ đóng gói sẵn. Tác giả cũng có bản dịch vụ trên mạng, nhưng đó là sản phẩm riêng với gói trả phí; README nêu các gói từ 0 đến 99 USD mỗi tháng cho phần máy tính chạy của họ, và bạn vẫn phải tự trả tiền nhà cung cấp AI. Còn nếu bạn thích tự quản dữ liệu, sẵn sàng thử nghiệm và góp ý lỗi, Suparagent là lựa chọn đáng thử, nhất là khi bắt đầu bằng chế độ Ask first và một thư mục không chứa dữ liệu nhạy cảm.

## 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 desktop và tự dựng máy chủ không đòi tài khoản của Suparagent. Tuy nhiên Suparagent không kèm mô hình AI, bạn phải tự mang engine và có thể tốn phí cho nhà cung cấp AI. Bản dịch vụ trên mạng là sản phẩm riêng có gói trả phí.

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

README không nhắc yêu cầu GPU. Phần nặng nằm ở engine bạn chọn: nếu dùng dịch vụ trên mạng thì không cần tính toán nặng ở máy bạn, còn nếu dùng engine cục bộ như Ollama hay LM Studio thì cấu hình phụ thuộc mô hình, tư liệu không nói rõ.

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

Repo có file run-desktop.bat, nhưng README không liệt kê rõ hệ điều hành cho bản desktop. Tác giả ghi bộ cài desktop là thử nghiệm, chưa ký số và mới được kiểm chứng hạn chế trên các nền tảng. Bản tự dựng máy chủ 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ự dựng, hội thoại, 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 qua Suparagent được mã hoá. Tuy nhiên engine nhận nội dung mỗi lượt trả lời, và nếu là dịch vụ trên mạng thì dữ liệu đó thuộc điều khoản của nhà cung cấp.

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

Cần Node.js 22 trở lên, uv và ít nhất một engine trên cùng máy. Với engine dạng CLI, hãy cài và đăng nhập trước; với engine API, cấu hình trong Settings → Engines. Docker chỉ cần cho máy tính cô lập (tuỳ chọn).

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

Bạn chọn mức duyệt: Ask first, Accept edits, Approve for me (cho Claude, Codex và Cursor) hoặc Plan only. Routine không bao giờ tự duyệt một hành động thay bạn. Nếu muốn an toàn nhất, hãy bắt đầu với Ask first.

### Dùng được với mô hình nào?

Hỗ trợ Claude Code, Codex CLI, Gemini CLI, Google Gemini qua Antigravity, Cursor, công cụ ACP khác, OpenRouter và API tương thích OpenAI như Ollama, LM Studio. Không phải engine nào cũng có đủ tính năng; trưởng nhóm giao việc cần dùng Claude hoặc Codex.
