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

> Suparagent là một không gian làm việc mã nguồn mở cho các đồng nghiệp AI (agent có tên, có việc riêng, có bộ nhớ và lịch chạy). Bạn chạy bản desktop từ mã nguồn hoặc tự host máy chủ. 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-07-16 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/suparagent-dong-nghiep-ai-tu-host-huong-dan-cai-dat-3

Suparagent là một không gian làm việc mã nguồn mở cho các “đồng nghiệp AI”: bạn tạo agent có tên, giao cho mỗi agent một 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 công 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 có thể chạy bản desktop trên máy mình hoặc tự dựng máy chủ riê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 giữ quyền kiểm soát: chủ shop cần báo cáo hằng tuần, nhân viên văn phòng cần tổng hợp ghi chú, lập trình viên mới muốn thử mô hình “một nhóm agent”. Điểm đáng giá nhất là agent không tự ý hành động: bạn chọn chế độ như “Ask first” để nó dừng lại chờ bạn đồng ý trước những việc cần duyệt.

Có một lưu ý quan trọng ngay từ đầu: Suparagent không kèm sẵn mô hình AI hay gói đăng ký nào. Bạn phải mang theo engine và tài khoản của riêng mình. Hiện repo có khoảng 7.041 sao và 913 fork, giấy phép Apache-2.0. 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 | Không gian làm việc cho đồng nghiệp AI: tạo agent có tên, bộ nhớ, lịch chạy, chạy trên máy bạn và 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à cài đặt phê duyệt. 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 phòng chung. 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à hội thoại liên quan, tìm trong lịch sử. Bạn xem và sửa được những gì nó nhớ, nên không phải giải thích lại từ đầu mỗi lần.
- **Chạy việc theo lịch.** Routine (việc định kỳ) có thể chạy theo lịch, qua webhook hoặc chạy tay. Kết quả nào bạn cũng xem lại được, và routine không bao giờ tự phê duyệt hành động thay bạn.
- **Chọn mức tự do cho agent.** Có các chế độ Ask first, Accept edits, Approve for me (cho Claude, Codex và Cursor) và Plan only. Bạn xem được nhật ký công cụ đã dùng và các quyết định phê duyệt ngay 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 GitHub, Gmail, Google Calendar, 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 lại những thứ cần bạn chú ý: yêu cầu phê duyệt, câu hỏi từ agent, kết quả routine, lỗi engine, việc đến hạn. Nó cũng hiển thị được 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à lần thử của agent.
- **Skill và mẫu.** Lưu sẵn các hướng dẫn dùng lại, và tạo agent từ mẫu có sẵn. Skill ở đây là những chỉ dẫn bạn chọn cho một tin nhắn.
- **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ụ, tạo và sửa agent.
- **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ữ (khi 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 nối được với thứ mình đang dùng: Claude Code hoặc Codex CLI, Gemini CLI, Google Gemini qua Antigravity, Cursor, một agent dòng lệnh khác dùng giao thức 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ập ảnh và máy tính riêng của agent không có ở mọi engine.

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

Theo README, bản desktop hiện chạy từ mã nguồn. Bạn cần:

- **Node.js 22 trở lên.**
- **uv** (trình quản lý Python, xem tại docs.astral.sh/uv).
- **Ít nhất một engine** trên cùng máy. Nếu dùng engine dạng CLI, hãy cài nó 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**.
- **Git** để tải mã nguồn về.
- **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).

README không nêu yêu cầu phần cứng (ví dụ GPU) và không liệt kê hệ điều hành cụ thể cho bản desktop. Nó chỉ nói bộ cài desktop còn thử nghiệm, chưa ký số và mới kiểm chứng trên số nền tảng hạn chế. Nếu bạn muốn tự host máy chủ, bảng so sánh trong README ghi cần máy chủ Linux, HTTPS, Docker hoặc Node.js cùng uv, và một engine; phần này chi tiết hơn trong hướng dẫn self-hosting của repo.

```note
Suparagent không kèm mô hình hay gói đăng ký AI. Dùng engine nào thì bạn trả tiền cho nhà cung cấp đó theo điều khoản của họ. Khi agent trả lời, engine nhận lời nhắc và phần ngữ cảnh cần cho lượt đó (văn bản bạn đính kèm, ghi chú liên quan, nội dung thư mục mà engine đọc). Đừng để agent đọc thư mục chứa dữ liệu nhạy cảm nếu bạn chưa yên tâm về nhà cung cấp engine.
```

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

```steps
- Kiểm tra công cụ | Có Node.js 22+, uv, git và một engine đã đăng nhập
- Tải mã nguồn | Clone repo về máy
- Chạy ứng dụng | Vào thư mục desktop và chạy npm run app
- Cấu hình lần đầu | Chọn engine, workspace, chế độ phê duyệt
- Tạo agent đầu tiên | Đặt tên, giao việc rõ ràng, bắt đầu chat
```

### Kiểm tra công cụ cần có

Trước khi cài, hãy chắc là máy bạn đã có Node.js bản 22 trở lên, uv và git. Nếu muốn dùng một engine CLI như Claude Code hoặc Codex CLI, hãy cài và đăng nhập engine đó trước, vì README yêu cầu làm việc này trước khi mở ứng dụng. Nếu thích dùng API, bạn sẽ điền cấu hình sau, trong ứng dụng.

Chỗ người mới hay vấp: cài xong Node.js nhưng terminal đang mở từ trước vẫn chưa nhận lệnh. Hãy đóng và mở lại terminal.

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

Mở terminal (PowerShell, Terminal hoặc bash đều được) ở thư mục bạn muốn lưu 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

Theo đúng README, bạn vào thư mục `desktop` rồi chạy lệnh `npm run app`:

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

Lưu ý phải đứng trong `suparagent/desktop` rồi mới chạy `npm run app`. Nếu chạy ở thư mục gốc hoặc thư mục khác, npm sẽ báo không tìm thấy script. Lần chạy đầu có thể mất thời gian vì ứng dụng cần chuẩn bị mọi thứ; README không mô tả chi tiết bước này, nên nếu có lỗi hãy xem hướng dẫn thiết lập desktop trong thư mục `docs/` của repo.

### Cấu hình lần mở đầu

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

1. Mở **Settings → Engines** và xác nhận có một engine ở 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 thư mục làm việc.
3. Bắt đầu chat.
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 bạn thích bộ cài thay vì chạy từ mã nguồn, README trỏ đến trang Releases của repo. Nhưng bộ cài còn thử nghiệm, chưa ký số, và luồng cập nhật giữa các bản chưa được kiểm chứng đầu-cuối. Cứ coi đó là bản dùng thử.
```

Trong repo còn có Dockerfile và compose.yaml, thường dành cho cách chạy bằng Docker. README phần Quick start không hướng dẫn dùng chúng cho bản desktop, nên nếu bạn muốn tự host máy chủ, hãy đọc hướng dẫn self-hosting trong thư mục `docs/` thay vì tự đoán lệnh.

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

README không nêu một lệnh “kiểm tra phiên bản” riêng. Cách kiểm tra dựa trên chính các bước sử dụng:

- Sau `npm run app`, cửa sổ Suparagent mở ra và hỏi bạn chọn engine, workspace, chế độ phê duyệt.
- Vào **Settings → Engines**: nếu thấy engine của bạn ở trạng thái sẵn sàng thì kết nối ổn.
- Tạo một agent thử, gõ một câu đơn giản như “Chào, hãy liệt kê các tệp trong thư mục làm việc”. Nếu agent trả lời, bạn đã cài thành công.
- Nếu để chế độ Ask first và agent đề nghị làm một việc cần duyệt, bạn sẽ thấy yêu cầu phê duyệt xuất hiện để bạn cho phép hoặc từ chối. Đó cũng là dấu hiệu cơ chế an toàn đang hoạt động.

Nếu engine báo chưa sẵn sàng, gần như chắc chắn vấn đề nằm ở việc CLI chưa đăng nhập hoặc API chưa cấu hình, chứ không phải ở Suparagent.

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

Các tình huống dưới đây bám theo những khả năng README mô tả. Câu lệnh mẫu chỉ là gợi ý để bạn gõ vào khung chat, không phải lệnh của repo.

### Chủ shop cần bản tóm tắt tuần

Chị Lan bán đồ gia dụng online, mỗi tuần có vài tệp ghi chú đơn hàng, phản hồi khách và kế hoạch khuyến mãi lưu trong một thư mục. Chị tạo agent tên “Trợ lý tuần” và giao thư mục đó làm workspace. Prompt mẫu:

```text
Đọc các ghi chú trong thư mục này và viết bản tóm tắt tuần: đơn nổi bật, khiếu nại cần xử lý, việc cần làm tuần tới. Trình bày ngắn, gạch đầu dòng.
```

Kết quả là một bản tóm tắt ngay trong chat. Nếu hài lòng, chị đặt nó thành routine chạy hằng tuần và chỉ cần mở xem kết quả mỗi lần.

> Giao việc cho AI được, nhưng quyền bấm “đồng ý” vẫn nên là của bạn.
>
> — Ông T

### Nhóm nhỏ làm báo cáo dự án

Anh Hùng làm quản lý dự án và muốn chia việc đúng như ví dụ trong README. Anh tạo một agent trưởng nhóm (đặt engine là Claude hoặc Codex) cùng hai agent chuyên môn: “Nghiên cứu” và “Biên tập”, cho cả ba dùng chung thư mục dự án. Anh nhắn cho trưởng nhóm:

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

Trưởng nhóm tách yêu cầu thành các việc nhỏ và giao cho hai agent kia. Việc của từng agent chạy trong hội thoại riêng, rồi quay về trưởng nhóm để ráp lại. Anh theo dõi trong chat và duyệt các hành động khi cài đặt yêu cầu.

### Nhân viên văn phòng xem “hôm nay có gì”

Chị Mai làm hành chính, sáng nào cũng phải rà thư và lịch. Chị dùng màn hình **Today** để xem một nơi duy nhất gồm yêu cầu phê duyệt đang chờ, câu hỏi từ agent, kết quả các routine và việc đến hạn. Khi đã nối Gmail và Google Calendar (qua khoá Composio của chị), Today còn hiện thư và lịch ở chế độ chỉ đọc. Chị không phải mở nhiều cửa sổ, chỉ duyệt hoặc từ chối những gì cần quyết định.

Lưu ý: README ghi phần kết nối ứng dụng qua Composio mới thử với một dịch vụ Composio giả lập, chưa thử với dịch vụ thật. Hãy thử ở quy mô nhỏ trước.

### Lập trình viên mới thử tự động hoá nhẹ

Bạn Nam mới đi làm, muốn thử cho agent làm việc lặp lại như tổng hợp ghi chú code review. Bạn tạo agent từ một mẫu có sẵn, lưu hướng dẫn thành skill để dùng lại, rồi đặt routine chạy theo lịch hoặc kích hoạt bằng webhook. Vì routine chạy trong backend, bạn phải để backend chạy liên tục. Mỗi lần chạy bạn xem lại kết quả, còn chế độ Plan only giúp agent chỉ lập kế hoạch mà chưa động vào tệp.

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

### Chạy npm run app báo 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 là terminal đang ở `suparagent/desktop` rồi chạy lại. Kiểm tra thêm Node.js bản 22 trở lên bằng lệnh `node --version`.

### Báo thiếu uv hoặc Node.js

README yêu cầu Node.js 22+ và uv. Cài chúng theo hướng dẫn chính thức, mở lại terminal rồi thử lại. Đừng cài bản Node cũ hơn yêu cầu.

### Engine không sẵn sàng trong Settings → Engines

Với engine dạng CLI, hãy đảm bảo bạn đã cài và đăng nhập engine đó trên cùng máy trước khi mở Suparagent. Với engine API, kiểm tra lại cấu hình trong **Settings → Engines**. Đăng nhập CLI do chính engine giữ, không phải Suparagent.

### Agent không dùng được tính năng như ảnh, máy tính riêng hoặc ứng dụng kết nối

Đây thường không phải lỗi. README nói không phải engine nào cũng hỗ trợ nhập ảnh hay máy tính riêng của agent, và ứng dụng kết nối chỉ dùng được với agent Claude hoặc Codex. Đổi engine của agent hoặc xem bảng khả năng trong tài liệu của repo.

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

Routine chạy trong backend nên backend phải đang chạy. Nếu bạn tắt ứng dụng hoặc máy, lịch sẽ không chạy. Muốn lịch luôn hoạt động, README gợi ý tự host trên máy chủ do bạn kiểm soát.

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

**Điểm mạnh.** Dữ liệu lưu trên máy hoặc máy chủ của bạn, khoá API lưu qua Suparagent được mã hoá, và agent luôn chờ bạn duyệt theo chế độ bạn chọn. Bạn không bị khoá vào một nhà cung cấp, vì nối được nhiều engine, kể cả mô hình chạy cục bộ qua Ollama hoặc LM Studio. Mã nguồn mở, giấy phép Apache-2.0, repo vẫn được cập nhật trong vài tháng gần đây.

**Giới hạn.** Chính README khẳng định dự án cò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òn thử nghiệm và chỉ có một chủ sở hữu có thể mời đồng đội, không phải dịch vụ nhiều tổ chức. Giao việc cho nhóm agent còn mới, 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. Máy tính Docker, công cụ trình duyệt và bản macOS gốc đều là tuỳ chọn thử nghiệm. Cuối cùng, bạn vẫn phải tự lo engine và chi phí mô hình.

**Khi nào chọn cách khác.** Nếu bạn cần một công cụ ổn định để phục vụ việc quan trọng ngay hôm nay, hoặc không muốn đụng đến terminal, hãy cân nhắc dịch vụ trả phí có hỗ trợ chính thức. Suparagent cũng có bản hosted riêng (một sản phẩm khác với bản mã nguồn mở), nhưng bản đó xử lý dữ liệu tài khoản theo chính sách riêng của họ. Còn nếu bạn thích tự kiểm soát, sẵn sàng thử nghiệm và chấp nhận vài chỗ chưa mượt, Suparagent là một cách đáng thử để làm quen với việc làm việc cùng nhóm agent AI.

## 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 tự chạy bản desktop hoặc tự host thì không phải trả tiền cho Suparagent. Tuy nhiên README nói rõ repo không kèm mô hình hay gói đăng ký AI, nên bạn vẫn có thể phải trả cho nhà cung cấp engine. Bản hosted là sản phẩm riêng có gói trả phí.

### Cần GPU hay phần cứng mạnh không?

README không nêu yêu cầu GPU hay phần cứng cụ thể. Yêu cầu được ghi là Node.js 22+, uv và ít nhất một engine. Nếu bạn chọn chạy mô hình cục bộ qua Ollama hoặc LM Studio thì phần cứng phụ thuộc vào mô hình đó, nhưng tư liệu chưa nói thêm.

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

README không liệt kê hệ điều hành cụ thể cho bản desktop. Nó chỉ nói bộ cài desktop còn thử nghiệm, chưa ký số và mới kiểm chứng trên số nền tảng hạn chế. Bạn nên xem hướng dẫn thiết lập desktop trong thư mục docs của repo trước khi cài.

### 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 trên máy hoặc cơ sở dữ liệu máy chủ của bạn. Khoá API lưu qua Suparagent được mã hoá. Tuy nhiên engine bạn chọn vẫn nhận lời nhắc và ngữ cảnh cần thiết, 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.

### 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 bằng các chế độ Ask first, Accept edits, Approve for me hoặc Plan only. Với chế độ Ask first, agent dừng lại chờ bạn duyệt trước những hành động cần phê duyệt. README cũng nói routine không bao giờ tự phê duyệt hành động.

### Suparagent dùng được những mô hình AI nào?

Nối được Claude Code hoặc Codex CLI, Gemini CLI, Google Gemini qua Antigravity, Cursor, agent dòng lệnh dùng 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ập ảnh hay máy tính riêng của agent.

### Bản hosted trên suparagent.ai khác gì bản tự cài?

README nói bản hosted là dịch vụ riêng, tách khỏi phần mã nguồn mở. Dữ liệu tài khoản, workspace và thanh toán do Suparagent xử lý, có gói Free preview, Starter, Standard và Pro. Bạn vẫn phải mang tài khoản nhà cung cấp AI của mình.
