# Suparagent: nhóm đồng nghiệp AI tự lưu trữ, có duyệt trước khi làm — hướng dẫn cài 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, có vai trò, trí nhớ, lịch chạy định kỳ và cơ chế xin duyệt trước khi làm. Bạn chạy nó trên máy mình hoặc tự dựng server, và dùng engine AI của chính bạn. Cài bản desktop từ mã nguồn cần Node.js 22+ và uv, khá đơn giản nếu bạn đã quen dùng terminal.

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

Suparagent là một không gian làm việc cho các “đồng nghiệp AI”: bạn tạo những agent có tên riêng, giao cho mỗi agent một công việc và một thư mục làm việc, rồi cho chúng phối hợp làm việc thật. Hội thoại, trí nhớ, lịch chạy định kỳ và các yêu cầu xin duyệt đều nằm chung một chỗ. Dự án mã nguồn mở, viết chủ yếu bằng Python, giấy phép Apache-2.0, hiện có khoảng 7.041 sao và 913 fork.

Ai nên dùng? Người làm kinh doanh, nhân viên văn phòng hoặc lập trình viên mới đã quen với các công cụ AI dạng dòng lệnh (như Claude Code, Codex) và muốn có một “bảng điều khiển” để quản lý nhiều agent thay vì mở từng cửa sổ chat rời rạc. Nếu bạn chỉ cần hỏi đáp một lần, repo này hơi nhiều thứ so với nhu cầu.

Điểm đáng giá nhất: agent không tự ý làm bừa. Bạn chọn mức tự do cho từng agent, ví dụ “Ask first” để agent dừng lại chờ bạn duyệt trước khi hành động. Ngoài ra Suparagent không kèm sẵn mô hình AI nào, bạn mang engine và tài khoản của mình đến. Bạn có thể 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ở cho các agent AI có tên, có trí nhớ, lịch chạy riêng và luôn xin 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 theo README, kèm 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. Một agent “trưởng nhóm” có thể giao việc cho các agent chuyên môn, hoặc điều phối trong các phòng chung. Ví dụ: một người nghiên cứu và một người biên tập, do một trưởng nhóm điều phối. Trưởng nhóm cần dùng Claude hoặc Codex.
- **Giữ ngữ cảnh.** Agent ghi chú, nhớ lại ghi chú và hội thoại liên quan, tìm lại lịch sử. Bạn xem và sửa được những gì agent 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 lịch, theo webhook hoặc bấm tay. Mỗi kết quả bạn đều xem được, và routine không bao giờ tự duyệt thay bạn.
- **Chọn mức tự do.** Có các chế độ: Ask first, Accept edits, Approve for me (cho Claude, Codex và Cursor) và Plan only. 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, 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 đều chờ bạn duyệt. Có thêm MCP Marketplace để thêm từng công cụ lẻ.
- **Màn hình Today.** Gom phê duyệt, câu hỏi từ agent, kết quả routine, lỗi engine và việc đến hạn. Có thể hiện 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 hội thoại và các lần thử.
- **Kỹ năng và mẫu.** Lưu “skills” (hướng dẫn bạn chọn cho một tin nhắn) và tạo agent từ mẫu có sẵn, đỡ gõ lại chỉ dẫn mỗi lần.
- **Dùng từ đ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 lệnh gọi 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 workspace, xuất lịch sử.

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 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 riêng của agent” chỉ có ở một số 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, README dẫn tới 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 CLI, hãy 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 mô hình hay gói đăng ký nào, và việc dùng mô hình có thể tốn tiền theo nhà cung cấp.
- **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, còn thử nghiệm).
- **Git** để tải mã nguồn về (lệnh `git clone`).

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

Tư liệu không nêu yêu cầu cấu hình phần cứng cụ thể nào (như GPU hay dung lượng RAM). Phần cứng phụ thuộc vào engine bạn chọn.

```note
Suparagent đang phát triển và README tự ghi bản desktop, server tự lưu trữ còn thử nghiệm. Trình cài đặt chưa ký số. Đừng giao cho nó việc quan trọng khi chưa đọc phần giới hạn, và hãy giữ chế độ Ask first lúc mới làm quen.
```

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

```steps
- Cài điều kiện | Có 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 | cd vào suparagent/desktop
- Chạy app | Gõ npm run app để mở ứng dụng
- Thiết lập lần đầu | Chọn engine, workspace và chế độ duyệt
```

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

Hãy cài Node.js bản 22 trở lên và uv theo hướng dẫn trên trang chính thức của chúng. Sau đó chuẩn bị một engine. Nếu bạn dùng một CLI như Claude Code hay Codex, hãy cài và đăng nhập nó trước, rồi mới mở Suparagent. Nếu muốn dùng engine qua API (OpenRouter, Ollama, LM Studio...), bạn sẽ khai báo trong app ở bước sau.

Bước này hay vấp nhất: nhiều bạn mở app trước rồi mới cài CLI, kết quả là app báo chưa có engine nào sẵn sàng.

### Tải mã nguồn về và chạy app

Mở terminal (PowerShell hoặc Terminal), đi tới thư mục bạn muốn lưu dự án, rồi chạy đúng các lệnh trong README:

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

Lệnh đầu tải mã nguồn về thư mục `suparagent`. Lệnh thứ hai đi vào thư mục `desktop`. Lệnh thứ ba khởi chạy ứng dụng desktop. Lưu ý: phải chạy `npm run app` ngay trong thư mục `desktop`, không phải thư mục gốc `suparagent`. Lần chạy đầu có thể mất thời gian vì phải chuẩn bị mọi thứ.

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

Khi app mở lần đầu, bạn chọn một engine, một workspace (thư mục làm việc) và một chế độ duyệt. Sau đó làm lần lượt:

1. Vào **Settings → Engines** và xác nhận có một engine đang ở 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 workspace.
3. Bắt đầu chat. Chọn **Ask first** để agent dừng lại xin duyệt trước các hành động cần duyệt.
4. Khi cần chia việc hoặc lặp lại việc, thêm đồng đội hoặc tạo routine.

### Muốn dùng bản cài sẵn hoặc tự dựng server?

README trỏ tới trang Releases của repo để lấy trình cài đặt desktop, nhưng ghi rõ chúng thử nghiệm và chưa ký số. Còn cách tự dựng server, README chưa ghi lệnh cụ thể ở phần chính; bạn xem hướng dẫn self-hosting trong thư mục `docs/` của repo. Repo có sẵn `Dockerfile` và `compose.yaml`, nhưng mình không đoán lệnh chạy thay bạn. Hãy đọc tài liệu trước khi làm.

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

Theo README, dấu hiệu thành công là:

- Cửa sổ ứng dụng mở ra và đưa bạn qua phần thiết lập lần đầu (chọn engine, workspace, chế độ 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, mở chat và nhận được trả lời từ engine.

Nếu engine chưa sẵn sàng, quay lại kiểm tra CLI đã đăng nhập chưa hoặc khóa API đã điền đúng chưa. Một phép thử nhanh: tạo agent, chọn Ask first, nhờ nó làm gì đó có chỉnh sửa tệp. Nếu app hiện yêu cầu duyệt trước khi sửa, cơ chế an toàn đang hoạt động đúng.

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

Bám theo khả năng README nêu, đây là vài tình huống bạn có thể thử.

### Chủ shop: bản tin tuần từ ghi chú và báo cáo

Bạn có một thư mục chứa ghi chú bán hàng và báo cáo mỗi tuần. Tạo một agent trưởng nhóm (engine Claude hoặc Codex) và hai agent chuyên môn: “Người nghiên cứu” và “Biên tập”. Cho cả ba cùng một workspace là thư mục đó. Rồi ra lệnh 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 Người nghiên cứu gom số liệu chính, giao Biên tập viết lại cho dễ đọc.
```

Trưởng nhóm chia nhỏ việc, giao cho từng agent làm trong các hội thoại riêng, rồi gom kết quả về. Bạn theo dõi trong chat và duyệt khi cài đặt yêu cầu. Kết quả là một bản tóm tắt tuần mà bạn không phải tự ghép từ nhiều nguồn.

> Đừng để AI tự làm hết: hãy để nó làm nháp, còn bạn giữ nút duyệt.
>
> — Ô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ản tin ở trên chạy ổn, bạn biến nó thành routine chạy hằng tuần. Routine có thể chạy theo lịch, theo webhook hoặc bấm tay. Mỗi lần chạy xong, kết quả hiện ra để bạn xem; nếu cần hành động, nó xin duyệt chứ không tự làm. Lưu ý: routine chạy trong backend nên backend phải đang chạy. Máy tắt thì lịch cũng không chạy.

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

Buổi sáng bạn mở màn hình Today thay vì lục từng cuộc chat. Ở đó có các yêu cầu duyệt đang chờ, câu hỏi agent gửi bạn, kết quả routine, lỗi engine và việc đến hạn. Nếu đã nối Gmail và lịch qua Composio, bạn thấy cả thư và sự kiện ở chế độ chỉ đọc. Phù hợp khi bạn quản lý nhiều agent cùng lúc.

### Lập trình viên mới: giao việc có kiểm soát trên một thư mục dự án

Tạo một agent với workspace là thư mục mã nguồn của bạn, chế độ **Plan only** hoặc **Ask first**. Nhờ nó đọc và đề xuất kế hoạch sửa. Khi hài lòng, chuyển sang Accept edits để nó sửa tệp. Bạn xem lại hoạt động công cụ và các quyết định duyệt trong app, nên luôn biết nó đã làm gì. Muốn dùng lại chỉ dẫn quen thuộc, lưu thành skill hoặc tạo agent từ mẫu.

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

- **App báo chưa có engine sẵn sàng.** Nguyên nhân thường là CLI chưa đăng nhập hoặc chưa cài. Hãy đăng nhập engine ngay trong terminal trước, rồi mở lại app và kiểm tra Settings → Engines. Nếu dùng API, kiểm tra lại khóa đã điền đúng chưa.
- **`npm run app` báo lỗi hoặc không chạy.** Kiểm tra bạn đang đứng trong thư mục `suparagent/desktop`, Node.js là bản 22 trở lên và uv đã cài. Gõ `node --version` để xem phiên bản Node.
- **Routine không chạy đúng giờ.** Routine chạy trong backend nên backend phải luôn chạy. Hãy kiểm tra ứng dụng hoặc server còn mở không.
- **Agent không dùng được ứng dụng kết nối (Gmail, GitHub...).** Chỉ agent Claude và Codex dùng được các kết nối này, và phải có khóa Composio của bạn cùng quyền được cấp. README cũng ghi phần này mới chỉ được thử với dịch vụ Composio giả lập, chưa thử với dịch vụ thật, nên có thể còn lỗi.
- **Trình cài đặt bị cảnh báo khi mở.** README ghi trình cài đặt là thử nghiệm và chưa ký số, 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 yên tâm, chạy từ mã nguồn theo các bước ở 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 hội thoại, ghi chú, routine và cài đặt nằm trong thư mục dữ liệu trên máy bạn hoặc cơ sở dữ liệu server của bạn. Tệp làm việc nằm ở các thư mục bạn gán. Khóa API lưu qua Suparagent được mã hoá. Bạn chọn engine tuỳ ý, và mọi hành động đáng ngại đều có thể phải qua tay bạn duyệt. Giấy phép Apache-2.0 cũng thoải mái cho việc tuỳ biến.

**Giới hạn.** README tự thừa nhận dự án còn sớm và thay đổi liên tục. Server tự lưu trữ là thử nghiệm, không phải dịch vụ nhiều tổ chức. Giao việc theo nhóm còn 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 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. Docker computers, công cụ trình duyệt và bản macOS gốc đều là thử nghiệm. MCP Marketplace, dịch vụ đám mây, âm thanh chưa qua kiểm định đầy đủ.

Cần lưu ý thêm về dữ liệu: khi agent trả lời, engine bạn chọn nhận câu lệnh và ngữ cảnh của lượt đó, có thể gồm vă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ụ đám mây, thông tin đó thuộc điều khoản của nhà cung cấp đó.

**Khi nào chọn cách khác.** Nếu bạn chỉ cần hỏi đáp đơn giản, một ứng dụng chat thông thường đủ rồi. Nếu cần dịch vụ ổn định cho nhiều tổ chức hoặc việc quan trọng, hãy cân nhắc kỹ vì dự án còn đang thử nghiệm. README cũng có bản “hosted” trả phí do một đơn vị vận hành riêng, nhưng đó là sản phẩm khác với bản mã nguồn mở; mình chỉ hướng dẫn bản chạy trên máy bạn ở bài này.

## 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ự lưu trữ bạn tự chạy. Tuy nhiên Suparagent không kèm mô hình AI, nên bạn vẫn có thể phải trả tiền cho nhà cung cấp engine bạn dùng. Bản hosted trả phí là sản phẩm riêng với các gói từ 0 đến 99 USD mỗi tháng.

### Cài Suparagent cần những gì?

Để chạy bản desktop từ mã nguồn bạn cần 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 dùng máy tính cô lập cho agent. Bạn cần Git để chạy lệnh git clone.

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

Tư liệu không nêu yêu cầu GPU. Suparagent dùng engine bạn chọn, như CLI, OpenRouter hoặc API tương thích OpenAI. Nếu bạn dùng mô hình chạy cục bộ như Ollama hay LM Studio thì cấu hình phụ thuộc vào mô hình đó; tư liệu chưa có thêm thông tin.

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

Repo có tệp run-desktop.bat, nhưng README không nói rõ về hệ điều hành cho bản desktop. README chỉ ghi trình cài đặt chưa ký số và có kiểm tra nền tảng còn hạn chế. Bản tự lưu trữ server yêu cầu máy chủ Linux.

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

Với desktop và tự lưu trữ, 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 bạn, và khóa API lưu qua Suparagent được mã hoá. Tuy nhiên, engine bạn chọn nhận lời nhắn và ngữ cảnh mỗi lượt, nếu là dịch vụ đám mây thì dữ liệu đó theo điều khoản của họ.

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

Bạn tự chọn mức tự do: Ask first, Accept edits, Approve for me (cho Claude, Codex và Cursor) hoặc Plan only. README ghi routine không bao giờ tự duyệt một hành động và các thay đổi qua ứng dụng kết nối đều chờ bạn duyệt.

### Tôi có dùng được từ điện thoại không?

Có một app điện thoại ghép với server của bạn để chat, dừng câu trả lời, cho phép hoặc từ chối lệnh gọi công cụ. README ghi nó mới được thử trên 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.
