# Suparagent: đồng nghiệp AI tự host, có duyệt trước khi làm — hướng dẫn cài đặt và dùng

> Suparagent là ứng dụng nguồn mở (Apache-2.0) để tạo các "đồng nghiệp AI": mỗi agent có tên, nhiệm vụ, thư mục làm việc, bộ nhớ và có thể chạy theo lịch. Bạn tự mang động cơ AI của mình (Claude Code, Codex, Gemini CLI, Ollama…). Cài bản desktop từ mã nguồn khá gọn, nhưng cần Node.js 22+, uv và một engine có sẵn trên máy.

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

Suparagent là một không gian làm việc nguồn mở cho các "đồng nghiệp AI". Bạn tạo 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 để hoàn thành việc thật. Hội thoại, bộ nhớ, lịch chạy định kỳ và các yêu cầu phê duyệt đều nằm chung một chỗ. Bạn chạy nó bằng ứng dụng desktop hoặc tự dựng máy chủ riêng.

Repo này hợp với người muốn dùng AI như một nhân viên phụ việc nhưng vẫn giữ quyền kiểm soát: chủ shop cần báo cáo đều đặn, nhân viên văn phòng muốn có người tổng hợp tài liệu, lập trình viên mới muốn thử mô hình "một trưởng nhóm AI chia việc cho các chuyên viên AI". Hiện repo có khoảng 7.041 sao và 913 fork, nên khá nhiều người quan tâm.

Điểm đáng giá nhất là bạn mang engine của chính mình (tài khoản, CLI hoặc API key) và agent chỉ làm việc nhạy cảm sau khi bạn bấm đồng ý. Có một lưu ý quan trọng ngay từ đầu: tác giả ghi rõ dự án đang phát triển tích cực, nhiều phần còn ở mức 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 | Không gian làm việc nguồn mở cho các đồng nghiệp AI có tên, bộ nhớ, lịch chạy định kỳ, 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à các tính năng chính, giải thích 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, bộ 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, hoặc phối hợp trong các phòng chung. Theo README, trưởng nhóm cần dùng Claude hoặc Codex.
- **Nhớ ngữ cảnh.** Agent có thể lưu ghi chú, gợi lại ghi chú và hội thoại liên quan, tìm trong lịch sử. Bạn xem và sửa được những gì chúng nhớ, nên không sợ AI "nhớ sai" mà không biết.
- **Chạy việc theo lịch (routine).** Bạn đặt việc chạy theo lịch, qua webhook hoặc bấm tay. Mỗi kết quả đều để bạn xem lại. Routine không bao giờ tự duyệt hành động thay bạ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). Mọi hoạt động công cụ và quyết định duyệt đều xem lại được trong app.
- **Kết nối ứng dụng.** Qua khoá Composio của riêng bạn, có thể nối GitHub, Gmail, Google Calendar rồi cấp quyền cho các 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 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. Nó có thể hiện cả thư 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 hội thoại và các lần thử.
- **Kỹ năng và mẫu.** Lưu sẵn các chỉ dẫn dùng lại (skill) và tạo agent từ mẫu, đỡ phải gõ lại từ đầ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 thao tác. README nói app này mới thử trên Android, chưa có iOS.
- **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 bạn đồng ý và cung cấp thông tin xác thực), duyệt hoặc tải tệp trong thư mục làm việc, xuất lịch sử.

Về engine, bạn có thể nối Claude Code hoặc Codex CLI, Gemini CLI, Google Gemini qua Antigravity, Cursor, CLI khác dùng giao thức ACP, OpenRouter, hoặc API tương thích OpenAI như Ollama, 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 cho agent không có ở mọi engine.

## 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, trang chủ docs.astral.sh/uv).
- **Ít nhất một engine** có sẵn 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**.
- **Docker** chỉ cần nếu 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).
- Một **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ý mô hình, và việc dùng mô hình có thể tốn tiền.

README không nêu yêu cầu cụ thể về phần cứng hay hệ điều hành cho bản desktop từ mã nguồn. Có nhắc rằng bộ cài desktop là bản thử nghiệm, chưa ký số và mới kiểm chứng nền tảng hạn chế. Nếu bạn muốn chạy trên máy chủ, cần máy Linux, HTTPS, Docker hoặc Node.js cùng uv, và một engine.

Ngoài ra có bản web có sẵn ở suparagent.ai, nhưng đó là sản phẩm riêng, có tính phí. Bài này chỉ nói về bản tự chạy.

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

```steps
- Cài điều kiệ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
- Vào thư mục desktop | cd vào suparagent/desktop
- Chạy ứng dụng | Gõ npm run app
- Thiết lập lần đầu | Chọn engine, thư mục làm việc, chế độ duyệt
- Tạo agent đầu tiên | Đặt tên, giao việc, bắt đầu chat
```

### Cài sẵn Node.js, uv và một engine

README không ghi lệnh cài cho từng thứ này, nên bạn tải theo trang chính thức của từng công cụ (uv có hướng dẫn tại docs.astral.sh/uv). Kiểm tra Node.js phải từ phiên bản 22 trở lên. Nếu dùng engine CLI như Claude Code hay Codex, hãy cài và đăng nhập xong **trước khi** mở Suparagent, vì app dùng đúng phiên đăng nhập có sẵn trên máy.

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

Mở terminal (Windows: PowerShell hoặc Git Bash; macOS/Linux: Terminal) ở 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. Bạn cần cài Git trước.

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

Đây là hai lệnh README ghi trong phần Quick start:

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

`cd` đưa terminal vào thư mục `desktop` bên trong repo. `npm run app` khởi chạy ứng dụng. 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. README không nhắc bước cài gói riêng nào khác trước lệnh này, nên mình chỉ chép đúng như vậy. Nếu lệnh báo thiếu gì, xem thêm hướng dẫn "desktop setup" trong thư mục `docs/` của repo.

Trong repo còn có file `run-desktop.bat`, nhưng README phần Quick start không giải thích nó, nên mình không khẳng định cách dùng.

### Thiết lập lần chạy đầu tiên

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

1. Vào **Settings → Engines** và xác nhận có engine ở trạng thái sẵn sàng.
2. Tạo agent với tên, một công việc thật 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 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.

```note
Nếu dùng engine qua API, khoá API được Suparagent lưu dạng mã hoá trên máy bạn, nhưng mô hình vẫn nhận nội dung bạn gửi (văn bản đính kèm, ghi chú liên quan, tệp trong thư mục làm việc mà engine đọc). Đừng đặt tài liệu mật vào thư mục làm việc nếu chưa xem điều khoản của nhà cung cấp mô hình. Hãy bắt đầu với chế độ Ask first.
```

Nếu bạn không muốn chạy từ mã nguồn, README có nhắc trang Releases của repo có bộ cài desktop, nhưng đó là bản thử nghiệm, chưa ký số, và cơ chế cập nhật chưa được kiểm chứng đầy đủ.

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

README không đưa ra một lệnh kiểm tra riêng. Dấu hiệu thành công theo luồng của nó là:

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

Cách thử nhanh: tạo agent tên "Trợ lý thử", trỏ vào một thư mục trống, bật Ask first, rồi nhắn: "Hãy liệt kê các tệp trong thư mục làm việc của bạn." Nếu có câu trả lời, hoặc app hiện yêu cầu duyệt trước khi đọc tệp, tức là toàn bộ chuỗi app, engine, agent đang chạy tốt.

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

Các tình huống dưới đây bám sát khả năng README mô tả. Câu lệnh mẫu mình tự soạn, bạn chỉnh theo việc của mình.

### Chủ shop: tóm tắt báo cáo bán hàng mỗi tuần

Bạn xuất báo cáo doanh số mỗi tuần thành tệp văn bản và bỏ vào một thư mục. Tạo agent "Kế toán AI", giao thư mục đó làm workspace, đặt chế độ Ask first. Nhắn thử:

```text
Đọc các báo cáo trong thư mục này và viết bản tóm tắt tuần: mặt hàng bán chạy, mặt hàng chậm, và 3 việc nên làm tuần tới.
```

Khi bản tóm tắt chạy ổn, chuyển nó thành routine hằng tuần. Mỗi lần chạy, bạn mở app xem kết quả và trả lời các yêu cầu duyệt. Bạn nhận được bản tóm tắt đều đặn mà không phải nhờ lại từng lần.

> Giao việc cho AI thì dễ, giữ quyền bấm "đồng ý" mới là phần đáng tiền.
>
> — Ông T

### Nhân viên văn phòng: chuẩn bị bản briefing dự án

Đây là ví dụ chính trong README. Tạo một agent trưởng nhóm (engine Claude hoặc Codex) và hai chuyên viên, chẳng hạn "Người nghiên cứu" và "Biên tập viên". Cho cả ba cùng một thư mục dự án chứa ghi chú và báo cáo. Nhắn cho trưởng nhóm:

```text
Chuẩn bị bản briefing tuần này từ các ghi chú và báo cáo trong thư mục dự án.
```

Trưởng nhóm chia nhỏ việc, giao cho các chuyên viên. Họ làm trong các cuộc hội thoại riêng rồi trả kết quả về cho trưởng nhóm tổng hợp. 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 briefing gom từ nhiều nguồn, và bạn xem lại được ai làm gì.

### Người làm nội dung: bắt đầu ngày bằng màn hình Today

Nếu đã đặt vài routine và nối Gmail, Google Calendar qua khoá Composio của bạn, hãy mở màn hình Today mỗi sáng. Ở đó bạn thấy gộp lại: yêu cầu duyệt, câu hỏi từ agent, kết quả routine, lỗi engine và việc đến hạn. Thư và lịch hiển thị ở chế độ chỉ đọc. Bạn xử lý hết một danh sách thay vì lục từng cuộc chat. Lưu ý: README cho biết phần ứng dụng kết nối mới được thử với dịch vụ Composio giả lập, chưa phải dịch vụ thật, nên hãy dùng thận trọng.

### Lập trình viên mới: dùng chung agent từ điện thoại

Nếu bạn tự dựng máy chủ riêng, có thể ghép app điện thoại (Android) để chat, dừng một câu trả lời đang chạy, hoặc cho phép / từ chối một thao tác công cụ khi đang ở ngoài. Hợp với việc để agent chạy trên máy ở nhà, còn bạn chỉ duyệt các bước quan trọng. Phần này còn sớm: chưa có thông báo đẩy, chưa có bản trên cửa hàng ứng dụng.

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

**Engine báo chưa sẵn sàng trong Settings → Engines.** Thường do engine CLI chưa cài hoặc chưa đăng nhập trên cùng máy. Đăng nhập lại ở terminal bằng chính CLI đó, rồi mở lại app. Với engine qua API, kiểm tra lại khoá và địa chỉ đã nhập.

**`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 đã từ phiên bản 22 trở lên và `uv` đã cài (gõ `uv --version` để thử). Nếu vẫn lỗi, xem mục desktop setup trong thư mục `docs/` hoặc báo lỗi ở GitHub Issues kèm nội dung lỗi.

**Routine không chạy đúng giờ.** README nói routine chạy ở backend, nên backend phải luôn chạy. Tắt máy hoặc đóng app thì lịch không chạy được. Muốn việc đều đặn, hãy cân nhắc tự host trên một máy chủ luôn bật.

**Agent không dùng được tính năng nào đó (ảnh, máy tính cô lập, ứng dụng kết nối).** Không phải engine nào cũng hỗ trợ đủ. Ứng dụng kết nối chỉ dùng được với agent Claude hoặc Codex, và trưởng nhóm cũng cần Claude hoặc Codex. Xem bảng khả năng của từng engine trong tài liệu repo trước khi chọn.

**Hệ điều hành cảnh báo khi mở bộ cài.** Bộ cài desktop chưa được ký số nên có thể bị 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 thì 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: chọn engine, chọn mức tự do cho agent, mọi hành động nhạy cảm chờ bạn duyệt. Dữ liệu của bản desktop và tự host nằm trên máy hoặc máy chủ của bạn. Giấy phép Apache-2.0 nên dùng và tuỳ biến thoải mái. Mô hình "trưởng nhóm chia việc cho chuyên viên" cộng routine định kỳ khá hợp với việc lặp lại hằng tuần.

**Giới hạn.** Dự án còn sớm và thay đổi nhanh. Máy chủ tự host là bản thử nghiệm, có một chủ sở hữu và có thể mời đồng đội, nhưng mọi người dùng chung agent, hội thoại và bộ nhớ; không phải dịch vụ nhiều tổ chức. Máy tính Docker, công cụ trình duyệt và bản macOS gốc đều là thử nghiệm tuỳ chọn. MCP Marketplace, âm thanh và một số tính năng khác chưa qua kiểm chứng trên dịch vụ thật. Bạn cũng phải tự lo engine và chi phí mô hình, vì Suparagent không kèm mô hình nào.

**Khi nào nên chọn cách khác.** Nếu bạn chỉ cần hỏi đáp nhanh, một ứng dụng chat thông thường đơn giản hơn nhiều. Nếu cần công cụ đã ổn định để chạy việc quan trọng cho cả công ty, hãy chờ dự án trưởng thành hơn hoặc thử kỹ trên việc ít rủi ro trước. Còn nếu bạn muốn một "nhân viên AI" có bộ nhớ, có lịch, có chốt duyệt và chấp nhận đồng hành với một dự án đang lớn, Suparagent đáng để cài thử vào một buổi tối.

## 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ự host dùng miễn phí. Tuy vậy Suparagent không kèm mô hình AI, nên việc dùng engine và nhà cung cấp mô hình của bạn có thể tốn tiền. Bản web suparagent.ai là sản phẩm riêng, có gói miễn phí để dùng thử và các gói trả phí.

### Có cần GPU để chạy không?

Tư liệu không nêu yêu cầu GPU hay phần cứng cụ thể. Suparagent là ứng dụng điều phối agent, còn mô hình chạy ở engine bạn chọn. Nếu dùng engine cục bộ như Ollama hay LM Studio thì yêu cầu phần cứng phụ thuộc vào mô hình đó, README chưa nói chi tiết.

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

README nói bản desktop chạy từ mã nguồn với Node.js 22+ và uv, và có bộ cài desktop thử nghiệm ở trang Releases. Bộ cài chưa ký số và mới kiểm chứng nền tảng hạn chế. Repo có file run-desktop.bat, nhưng README chưa giải thích cách dùng nó. Chưa có thông tin rõ hơn về Windows.

### 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ú agent, 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 được chọn sẽ nhận câu hỏi và ngữ cảnh cần cho lượt trả lời, nên nếu 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 chọn mức tự do: Ask first, Accept edits, Approve for me (Claude, Codex, Cursor) hoặc Plan only. Với Ask first, app dừng lại chờ bạn duyệt trước các hành động cần duyệt. README nhấn mạnh routine không bao giờ tự duyệt hành động thay bạn.

### Dùng được những engine AI nào?

Claude Code, Codex CLI, Gemini CLI, Google Gemini qua Antigravity, Cursor, CLI khác dùng giao thức ACP, OpenRouter và API tương thích OpenAI như Ollama hay LM Studio. Tính năng khả dụng khác nhau theo engine, và trưởng nhóm agent cần dùng Claude hoặc Codex.

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

Có app điện thoại để ghép với máy chủ của bạn, dùng để chat, dừng câu trả lời, cho phép hoặc từ chối thao tác công cụ. README ghi 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 hay bản trên cửa hàng ứng dụng.
