Suparagent: lập nhóm đồng nghiệp AI tự host, duyệt trước khi chạy — hướng dẫn cài đặt và dùng
Bài này là một góc nhìn khác về Anil-matcha/suparagent — repo từng đổi tên nên mình viết lại với cách tiếp cận khác. Bài hướng dẫn chính: Suparagent: nhóm đồng nghiệp AI tự host, bạn duyệt mới chạy — hướng dẫn cài đặt và dùng →

Tóm tắt nhanh
Suparagent là ứng dụng mã nguồn mở (Apache-2.0) để tạo các đồng nghiệp AI có tên, có việc riêng, có trí nhớ, chạy theo lịch và xin bạn duyệt trước khi hành động. Bạn tự mang engine AI của mình (Claude Code, Codex, Gemini CLI, Ollama…). Bản desktop chạy từ mã nguồn bằng ba lệnh, cần Node.js 22+ và uv, khá dễ với người đã quen terminal.
Suparagent là một không gian làm việc cho các đồng nghiệp AI, mã nguồn mở, bạn có thể chạy ngay trên máy của mình hoặc tự host trên server. Bạn tạo các agent có tên, 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 duyệt đều nằm chung một chỗ.
Repo này hợp với ba nhóm người. Thứ nhất là dân văn phòng, chủ shop muốn có “nhân viên AI” làm báo cáo, tổng hợp ghi chú theo tuần. Thứ hai là lập trình viên mới muốn thử mô hình agent nhiều vai trò. Thứ ba là người không muốn gửi dữ liệu cho một dịch vụ trung gian. Tác giả định vị đây là bản tự host thay thế cho các bot AI dạng đồng nghiệp như Grok Bot hay Claude Cowork. Hiện repo có khoảng 7041 sao và 913 fork.
Điểm đáng giá nhất là cơ chế duyệt: bạn chọn mức tự do cho agent, và các routine (việc chạy định kỳ) không bao giờ tự phê duyệt hành động thay bạn. Một điều cần biết ngay: Suparagent không kèm mô hình AI hay gói đăng ký mô hình nào. Bạn phải mang engine và tài khoản của riêng mình. Bạn có thể xem video ngắn bên dưới để thấy giao diện trước khi cài.
Anil-matcha/suparagent
Suparagent là không gian làm việc mã nguồn mở, nơi bạn tạo các agent AI có tên, có trí nhớ, chạy theo lịch và chỉ hành động khi bạn đồng ý.
I.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ế.
- Tạo agent và nhóm. Mỗi agent có tên, vai trò, engine, thư mục làm việc, trí nhớ và thiết lập duyệt riêng. Bạn có thể có một “trưởng nhóm” giao việc cho các chuyên viên (ví dụ một người nghiên cứu, một người biên tập). Trưởng nhóm cần dùng Claude hoặc Codex.
- Giữ ngữ cảnh. Agent tự 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ì chúng nhớ, nên không sợ “AI nhớ sai mà mình không biết”.
- Chạy việc theo lịch. Routine chạy theo lịch, theo webhook hoặc chạy tay. Mỗi kết quả bạn xem lại được, và mọi yêu cầu duyệt vẫn chờ bạn trả lời.
- 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, 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 công cụ và ứ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 từng 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 hết thứ 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. Có thể hiện thêm mục 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 hội thoại và các lần thử.
- Dùng lại hướng dẫn. Lưu skill (chỉ dẫn bạn chọn cho một tin nhắn) và tạo agent từ mẫu có sẵn.
- 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 một lần gọi công cụ, tạo và sửa agent.
- 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 bạn đồng ý và có thông tin đăng nhập), duyệt hoặc tải tệp trong thư mục làm việc, xuất lịch sử.
II.Cần chuẩn bị gì
Theo README, bản desktop chạy từ mã nguồn 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. Engine có thể là 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, LM Studio.
- Nếu dùng engine dạng CLI: cài nó và đăng nhập trước khi mở Suparagent. Nếu dùng engine dạng API: cấu hình trong Settings → Engines.
- Docker chỉ cần cho tính năng máy tính cô lập của agent (tùy chọn, đang thử nghiệm).
- Tài khoản nhà cung cấp AI của bạn. Dùng mô hình có thể tốn tiền, do nhà cung cấp tính.
Tư liệu không nói về yêu cầu GPU hay dung lượng ổ đĩa, nên mình không đoán. Ngoài ra bản desktop đang ở mức thử nghiệm, bộ cài chưa được ký và mới được kiểm chứng trên số nền tảng hạn chế.
Suparagent không có mô hình đi kèm. Mỗi câu trả lời của agent được gửi tới engine bạn chọn, kèm ngữ cảnh cần thiết (văn bản bạn đính kèm, ghi chú liên quan, nội dung thư mục mà engine đọc). Nếu engine là dịch vụ đám mây, dữ liệu đó chịu điều khoản của nhà cung cấp ấy. Đừng cho agent đọc thư mục chứa dữ liệu nhạy cảm nếu bạn chưa yên tâm.
III.Cài đặt từng bước
- Kiểm tra công cụCó Node.js 22+, uv và một engine đã đăng nhập
- Tải mã nguồnDùng git clone để lấy repo về máy
- Chạy ứng dụngVào thư mục desktop và chạy npm run app
- Cấu hình lần đầuChọn engine, workspace và chế độ duyệt
- Tạo agent đầu tiênĐặt tên, giao việc rõ ràng và bắt đầu chat
A.Kiểm tra Node.js, uv và engine
Mở terminal (trên Windows: PowerShell hoặc Terminal; trên macOS/Linux: Terminal) rồi kiểm tra phiên bản. Hai lệnh này chỉ để xem máy đã có công cụ chưa.
node --version
uv --versionNode phải từ 22 trở lên. Nếu lệnh báo không tìm thấy, bạn cần cài Node.js và uv trước (README chỉ dẫn tới trang uv ở docs.astral.sh/uv). Với engine dạng CLI như Claude Code hay Codex, nhớ đăng nhập trước, vì app dùng đúng phiên đăng nhập đã có trên máy.
B.Tải mã nguồn về máy
git clone https://github.com/Anil-matcha/suparagent.gitLệnh này tạo thư mục suparagent ở nơi terminal đang đứng. Hãy cd vào một chỗ bạn dễ tìm, ví dụ thư mục Documents, trước khi chạy.
C.Chạy ứng dụng desktop
cd suparagent/desktop
npm run appBạn phải vào đúng thư mục desktop rồi mới chạy npm run app. Chạy ở thư mục gốc là lỗi hay gặp nhất của người mới. README mô tả đây là cách chạy từ mã nguồn, nên lần đầu có thể mất thời gian chuẩn bị.
Trong repo còn có file run-desktop.bat ở thư mục gốc, nhưng README không giải thích cách dùng nó, nên mình khuyên bạn bám theo lệnh ở trên.
D.Cấu hình lần mở đầu tiên
Lần đầu mở app, bạn chọn engine, workspace (thư mục làm việc) và chế độ duyệt. Sau đó làm theo README:
- Vào Settings → Engines và xác nhận có một engine ở trạng thái sẵn sàng.
- Tạo agent với tên, một công việc rõ ràng và một workspace.
- Bắt đầu chat. Chọn Ask first để app dừng lại xin bạn duyệt trước các hành động cần duyệt.
- Khi cần chia việc hoặc lặp lại việc, thêm đồng đội hoặc tạo routine.
Người mới nên chọn Ask first ở những lần đầu để xem agent định làm gì trước khi nó làm.
E.Nếu bạn muốn tự host trên server
README chưa ghi lệnh cài cụ thể cho server trong phần chính, mà chỉ trỏ tới tài liệu Self-hosting guide trong thư mục docs/ của repo. Repo có Dockerfile và compose.yaml, nhưng README không nêu lệnh chạy, nên mình không tự viết ra. Yêu cầu theo README: máy chủ Linux, HTTPS, Docker hoặc Node.js với uv, và một engine. Bản server hiện ở mức thử nghiệm, có một chủ sở hữu và có thể mời đồng đội.
IV.Kiểm tra đã chạy được chưa
Theo README, bạn biết mình cài thành công khi:
- Sau
npm run app, ứ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. - Trong Settings → Engines, engine của bạn hiện là sẵn sàng.
- Bạn tạo được một agent và chat được với nó. Thử một câu đơn giản như: “Liệt kê các tệp trong thư mục làm việc và tóm tắt mỗi tệp một dòng”. Với Ask first, bạn sẽ thấy app dừng để xin duyệt nếu agent cần thao tác.
Nếu engine không sẵn sàng, quay lại bước đăng nhập CLI hoặc nhập khóa API. README không nêu thông báo lỗi cụ thể nào, nên mình không liệt kê dòng chữ chính xác.
V.Dùng vào việc thật
Dưới đây là các tình huống bám sát khả năng README mô tả.
A.Tình huống 1: Nhân viên văn phòng cần bản tóm tắt dự án mỗi tuần
Bối cảnh: bạn quản lý một dự án, ghi chú và báo cáo nằm rải rác trong một thư mục. Cuối tuần phải gom lại thành bản tin gửi sếp.
Cách làm theo ví dụ trong README: tạo một agent trưởng nhóm và vài chuyên viên (người nghiên cứu, người biên tập), cho cùng một workspace dự án, đặt engine của trưởng nhóm là Claude hoặc Codex. Rồi nhắn:
Hãy soạn bản tin dự án tuần này từ các ghi chú và báo cáo trong thư mục. Chia việc cho người nghiên cứu và người biên tập, rồi tổng hợp thành một bản ngắn gọn.Kết quả: trưởng nhóm chia nhỏ việc, các chuyên viên làm trong các hội thoại riêng rồi trả về cho trưởng nhóm ghép lại. Bạn theo dõi trong chat và duyệt khi cần. Khi quy trình đã ổn, biến nó thành routine chạy hằng tuần.
Cho AI làm việc không khó, khó là biết nó đang định làm gì trước khi nó làm.
Ông T
B.Tình huống 2: Chủ shop muốn một người trực việc lặp lại mỗi sáng
Bối cảnh: mỗi sáng bạn phải xem lại các việc đến hạn, thư và lịch hẹn. Bạn tạo một agent với công việc rõ: “mỗi sáng tổng hợp việc cần chú ý”.
Cách làm: dùng routine chạy theo lịch, và mở màn hình Today để xem kết quả. Nếu đã nối Gmail và Google Calendar qua khóa Composio của bạn, Today có thể hiện mục Gmail và lịch ở chế độ chỉ đọc. Lưu ý README ghi phần kết nối ứng dụng mới được kiểm thử với dịch vụ Composio giả, chưa phải dịch vụ thật, và chỉ agent Claude hoặc Codex dùng được.
Kết quả: một nơi duy nhất cho yêu cầu duyệt, câu hỏi, kết quả routine và việc đến hạn. Routine chạy ở backend, nên backend phải luôn chạy.
C.Tình huống 3: Lập trình viên mới thử nhiều engine
Bối cảnh: bạn đang dùng Claude Code, muốn so thử với mô hình chạy cục bộ qua Ollama hoặc LM Studio.
Cách làm: vào Settings → Engines, thêm engine tương thích OpenAI, rồi tạo hai agent cùng workspace nhưng khác engine. Giao cùng một việc và so kết quả. README nhắc rằng công cụ khả dụng khác nhau tùy engine, chẳng hạn không phải engine nào cũng nhận ảnh hay dùng được máy tính của agent.
Kết quả: bạn thấy rõ engine nào hợp việc nào mà không phải đổi công cụ mỗi lần.
D.Tình huống 4: Làm từ xa bằng điện thoại
Bối cảnh: bạn tự host server, đi ngoài đường mà agent đang chờ duyệt một thao tác.
Cách làm: ghép app điện thoại với server của bạn, mở chat, cho phép hoặc từ chối lần gọi công cụ, hoặc dừng câu trả lời. Lưu ý: README nói 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 và chưa phát hành trên cửa hàng.
VI.Lỗi hay gặp và cách xử lý
1. npm run app báo lỗi hoặc không tìm thấy gói. Thường do bạn đang đứng sai thư mục hoặc Node quá cũ. Kiểm tra bằng node --version (cần 22 trở lên) và chắc chắn bạn đã cd suparagent/desktop.
2. Engine không hiện sẵn sàng. Với CLI, đăng nhập engine ngoài terminal trước rồi mở lại app. Với API, kiểm tra khóa và địa chỉ trong Settings → Engines. Khóa API lưu qua Suparagent được mã hóa trên máy bạn, nhưng đừng dán khóa vào chat.
3. Agent không có tính năng nào đó (ảnh, máy tính cô lập, kết nối ứng dụng). Thường do engine bạn chọn không hỗ trợ. README nói rõ khả năng khác nhau theo engine, trưởng nhóm cần Claude hoặc Codex, và ứng dụng kết nối chỉ dùng được với Claude hoặc Codex. Thử đổi engine cho agent đó.
4. Routine không chạy theo lịch. Routine chạy ở backend, nên backend phải đang chạy. Nếu tắt app hoặc server thì lịch không chạy. Hãy để server chạy liên tục nếu bạn cần lịch đều đặn.
5. Cảnh báo khi mở bộ cài trên Windows hoặc macOS. README nói bộ cài đang thử nghiệm và chưa ký. Nếu thấy cảnh báo, hãy tải từ trang Releases chính thức của repo, và nếu không muốn rủi ro thì chạy từ mã nguồn theo hướng dẫn ở trên. Bản cập nhật hỗ trợ có kiểm tra SHA-256 nhưng không tự cài, và đường cập nhật giữa các bản chưa được kiểm chứng đầu-cuối.
VII.Có nên dùng không
Điểm mạnh: mã nguồn mở theo giấy phép Apache-2.0, dữ liệu hội thoại, ghi chú, routine nằm trên máy hoặc server của bạn, hỗ trợ nhiều engine, và cơ chế duyệt rất rõ ràng. Bạn không bị khóa vào một nhà cung cấp mô hình. Dự án còn được cập nhật trong vài tháng gần đây.
Giới hạn cần biết: README nói thẳng dự án đang phát triển, bản server và desktop còn thử nghiệm, nên đừng dựa vào nó cho việc quan trọng khi chưa thử kỹ. Giao việc theo nhóm còn mới. Máy tính cô lập bằng Docker, công cụ trình duyệt và bản macOS gốc đều là tính năng tùy chọn, thử nghiệm. MCP Marketplace, máy tính đám mây và chuyển giọng nói thành chữ chưa qua kiểm định đầy đủ. Bản tự host chỉ có một chủ sở hữu và không phải dịch vụ nhiều tổ chức.
Nên chọn cách khác khi: bạn cần công cụ ổn định, có hỗ trợ chính thức cho doanh nghiệp, bạn không muốn đụng tới terminal, hoặc bạn chỉ cần một trợ lý chat đơn giản. Ngoài ra, gói hosted ($15, $49, $99 mỗi tháng) là sản phẩm riêng với điều khoản riêng, khác với bản mã nguồn mở bạn tự chạy. Nếu bạn là người mới, hãy bắt đầu bằng bản desktop, một agent, chế độ Ask first và một việc nhỏ, rồi mới tính đến routine hay nhó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 và bạn có thể tự chạy bản desktop hoặc server. Tuy nhiên Suparagent không kèm mô hình AI, bạn phải dùng tài khoản hoặc khóa của nhà cung cấp riêng và việc dùng mô hình có thể tốn tiền. Dịch vụ hosted là sản phẩm riêng có gói trả phí.
Cần GPU để chạy Suparagent không?
Tư liệu không nói cần GPU. Ứng dụng dùng engine bạn chọn như Claude Code, Codex hoặc API; nếu bạn tự chạy mô hình cục bộ bằng Ollama hay LM Studio thì yêu cầu phần cứng phụ thuộc mô hình đó, tư liệu chưa nêu 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 thử nghiệm chưa ký, mới được kiểm chứng ở mức hạn chế trên một số nền tảng. Repo có file run-desktop.bat nhưng README không giải thích cách dùng. Tư liệu chưa khẳng định mức hỗ trợ Windows đầy đủ.
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 lưu trên máy hoặc server của bạn, và khóa API lưu qua Suparagent được mã hóa. Tuy vậy, mỗi lượt trả lời gửi prompt và ngữ cảnh cần thiết tới engine bạn chọn, nếu là dịch vụ đám mây thì theo điều khoản của họ.
Agent có tự làm gì mà tôi không biết không?
Bạn chọn mức tự do: Ask first, Accept edits, Approve for me hoặc Plan only. Routine không bao giờ tự phê duyệt hành động và bạn xem lại được hoạt động công cụ cùng quyết định duyệt trong app.
Có tự host trên server được không?
Có, nhưng README ghi bản server đang thử nghiệm, yêu cầu máy chủ Linux, HTTPS, Docker hoặc Node.js với uv, và một engine. Lệnh cài chi tiết không nằm trong README chính mà trong tài liệu Self-hosting trong thư mục docs của repo.
Có dùng trên điện thoại được không?
Có app điện thoại để ghép với server của bạn, chat, dừng câu trả lời và duyệt công cụ. Nhưng README nói mới thử trên Android, chưa thử trên iOS, chưa có thông báo đẩy và chưa phát hành trên cửa hàng ứng dụng.


