Suparagent: lập đội đồng nghiệp AI tự chạy, có duyệt — 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 agent AI có tên, vai trò, bộ nhớ, lịch chạy và bước xin duyệt trước khi hành động. Bạn chạy bản desktop 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 trở lên và uv, khá dễ nếu bạn quen terminal.
Suparagent là một không gian làm việc mã nguồn mở, nơi bạn tạo ra các “đồng nghiệp AI” có tên riêng, giao cho mỗi bạn một công việc và một thư mục làm việc, rồi gom họ lại để hoàn thành việc thật. Mọi thứ nằm cùng một chỗ: cuộc trò chuyện, trí nhớ, lịch chạy định kỳ và các lần xin duyệt. Bạn dùng bản desktop trên máy mình hoặc tự dựng server 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 trưởng nhóm AI chia việc cho các chuyên viên AI”. Hiện repo có khoảng 7.000 sao và 913 fork, và vẫn được cập nhật trong vài tháng gần đây.
Điểm đáng giá nhất là bạn mang engine của riêng mình (Claude Code, Codex CLI, Gemini CLI, Ollama…) và mọi hành động quan trọng đều có thể dừng lại chờ bạn bấm đồng ý. Suparagent không kèm sẵn mô hình hay gói đăng ký mô hình nào. Bạn có thể xem video ngắn bên dưới để thấy nhanh giao diện, rồi quay lại đọc phần cài đặt.
Anil-matcha/suparagent
Suparagent là không gian làm việc mã nguồn mở để tạo các đồng nghiệp AI có tên, có trí nhớ, chạy theo lịch và chỉ hành động khi bạn duyệt.
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à cài đặt duyệt riêng. Một agent trưởng nhóm có thể giao việc cho các chuyên viên hoặc phối hợp họ trong phòng chung. Trưởng nhóm cần dùng Claude hoặc Codex. Lợi ích: bạn chia một việc lớn thành nhiều việc nhỏ như ngoài đời.
- Giữ ngữ cảnh. Agent có thể lưu ghi chú, nhớ lại ghi chú và cuộc trò chuyện liên quan, và tìm trong lịch sử. Bạn xem và sửa được những gì chúng nhớ. Lợi ích: đỡ phải giải thích lại từ đầu mỗi lần.
- Chạy theo lịch (routine). Routine chạy theo lịch, theo webhook hoặc chạy thủ công. Mỗi kết quả bạn tự xem lại. Routine không bao giờ tự duyệt thay bạn. Lợi ích: việc lặp lại hằng tuần không phụ thuộc vào trí nhớ của bạn.
- Chọn mức tự do cho agent. Có bốn chế độ: Ask first (hỏi trước), Accept edits (chấp nhận chỉnh sửa), Approve for me (chỉ cho Claude, Codex và Cursor) và Plan only (chỉ lập kế hoạch). Bạn xem lại hoạt động của công cụ và các quyết định duyệt ngay trong ứng dụng.
- Kết nối ứng dụng. Qua khóa 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ụ.
- 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 thị mục Gmail và lịch ở dạng 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 trò chuyện và các lần thử.
- Kỹ năng và mẫu. 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.
- 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ụ, hoặc tạo và sửa agent.
- 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 workspace, xuất lịch sử.
II.Cần chuẩn bị gì
Theo README, bản desktop chạy từ mã nguồn tải về. Bạn cần:
- Node.js 22 trở lên.
- uv (công cụ quản lý Python, có hướng dẫn trên trang tài liệu 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 lệnh (CLI), hãy cài và đăng nhập nó 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 máy tính cô lập cho agent, và đây là tính năng tùy chọn.
- Git để tải mã nguồn về (lệnh git clone ở bước dưới).
Bạn cũng cần tài khoản hoặc khóa của nhà cung cấp mô hình mà bạn chọn, vì Suparagent không kèm mô hình. Dùng mô hình có thể tốn tiền, tùy nhà cung cấp. Về hệ điều hành, README không nói rõ cho bản chạy từ mã nguồn. Riêng server tự host thì cần máy chủ Linux và HTTPS. Repo có tệp run-desktop.bat ở thư mục gốc, nhưng README không giải thích nó, nên mình không khẳng định gì thêm.
Suparagent đang phát triển và README ghi rõ bản desktop, server tự host là thử nghiệm. Hãy thử với việc không quan trọng trước. Khóa API và đăng nhập engine là thông tin nhạy cảm: đừng dán chúng vào chat hay gửi cho người khác.
III.Cài đặt từng bước
- Cài điều kiệnCó Node.js 22+, uv và ít nhất một engine đã đăng nhập
- Tải mã nguồnDùng git clone rồi vào thư mục desktop
- Chạy ứng dụngGõ npm run app
- Chọn thiết lập 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.Cài điều kiện trước
Kiểm tra Node.js và uv đã có trên máy. Nếu bạn dùng engine dòng lệnh như Claude Code hay Codex CLI, hãy cài và đăng nhập nó trước khi mở Suparagent, vì ứng dụng sẽ tìm engine có sẵn trên máy. README không ghi lệnh cài từng engine, nên bạn xem hướng dẫn của chính engine đó.
B.Tải mã nguồn và chạy
Mở terminal (PowerShell trên Windows, Terminal trên macOS hoặc Linux) ở thư mục bạn muốn lưu dự án, rồi gõ các lệnh trong README:
git clone https://github.com/Anil-matcha/suparagent.git
cd suparagent/desktop
npm run appLệnh đầu tải mã nguồn về. Lệnh thứ hai đi vào thư mục desktop. Lệnh thứ ba khởi động ứng dụng. Chỗ người mới hay vấp: phải chạy npm run app trong thư mục desktop, không phải thư mục gốc. Lần chạy đầu có thể mất một lúc.
C.Thiết lập lần đầu
Khi mở lần đầu, ứng dụng yêu cầu chọn engine, workspace và chế độ duyệt. Nếu chưa chắc, hãy chọn Ask first để ứng dụng dừng lại xin phép trước các hành động cần duyệt.
D.Tạo agent đầu tiên
Làm theo thứ tự README đưa ra:
- Mở 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 (thư mục chứa tệp của agent).
- Bắt đầu chat. Chọn Ask first nếu muốn được hỏi trước.
- Khi cần chia việc hoặc lặp lại, thêm đồng đội hoặc tạo routine.
E.Muốn bản cài đặt sẵn hoặc tự host?
README nhắc có trang Releases với các bộ cài desktop, nhưng ghi rõ chúng là thử nghiệm, chưa ký số, và đường cập nhật giữa các bản chưa được kiểm chứng đầu-cuối. Với server tự host, README chưa ghi lệnh cài ở trang 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 README không nêu lệnh chạy chúng, nên mình không đoán lệnh ở đây.
IV.Kiểm tra đã chạy được chưa
README không đưa ra một lệnh kiểm tra riêng. Cách kiểm tra hợp lý theo các bước của README:
- Ứng dụng mở lên và cho bạn chọn engine, workspace, chế độ duyệt ở lần đầu.
- Trong Settings → Engines, engine bạn dùng hiển thị là sẵn sàng.
- Bạn tạo được một agent, gửi một tin nhắn và nhận được câu trả lời.
- Với chế độ Ask first, khi agent định làm việc cần duyệt, ứng dụng dừng lại chờ bạn cho phép hoặc từ chối.
Nếu engine không hiện là sẵn sàng, thường là do engine CLI chưa đăng nhập hoặc chưa cấu hình API. Xem thêm phần lỗi bên dưới.
V.Dùng vào việc thật
Các tình huống dưới đây bám theo khả năng được ghi trong README. Câu lệnh mẫu là gợi ý của mình để bạn dán vào ô chat.
A.Chủ shop: tổng kết ghi chú bán hàng mỗi tuần
Bạn có thư mục chứa ghi chú và báo cáo tuần của shop. Tạo một agent trưởng nhóm (engine Claude hoặc Codex) và hai chuyên viên, một người nghiên cứu, một người biên tập. Cho cả ba cùng workspace là thư mục đó. Rồi nhắn cho trưởng nhóm:
Hãy đọc ghi chú và báo cáo trong thư mục này, giao cho bạn nghiên cứu tìm điểm chính, giao cho bạn biên tập viết bản tóm tắt một trang cho chủ shop.Trưởng nhóm chia việc, các chuyên viên làm trong cuộc trò chuyện riêng rồi trả kết quả về để ghép lại. Khi quy trình ổn, bạn biến nó thành routine chạy hằng tuần và xem lại từng lần chạy trong ứng dụng.
Giao việc cho AI không khó, khó là dám để nó chạy mà vẫn ngủ ngon. Chế độ hỏi trước là chỗ Suparagent đáng tiền nhất.
Ông T
B.Nhân viên văn phòng: gom việc cần chú ý vào một màn hình
Bạn kết nối Gmail và Google Calendar qua khóa Composio của chính mình, rồi cấp quyền cho agent Claude hoặc Codex chọn lọc. Mở màn hình Today để thấy yêu cầu duyệt, câu hỏi, kết quả routine và việc đến hạn ở một nơi. Mục Gmail và lịch trong Today hiển thị chỉ đọc. Lưu ý README ghi phần kết nối ứng dụng mới được thử với một dịch vụ Composio giả, chưa thử với dịch vụ thật, nên hãy bắt đầu bằng việc ít rủi ro.
C.Lập trình viên mới: thử đội agent có phân vai
Bạn muốn hiểu mô hình nhiều agent phối hợp. Tạo một trưởng nhóm và một vài chuyên viên từ mẫu có sẵn, đặt chế độ Plan only để chúng chỉ lập kế hoạch mà không sửa gì. Theo dõi trong chat cách trưởng nhóm chia việc, rồi đổi sang Ask first khi đã yên tâm. Phần chia việc giữa các agent là tính năng mới, nên có thể còn lỗi.
D.Người hay di chuyển: duyệt việc từ điện thoại
Sau khi tự dựng server, bạn ghép app điện thoại với server đó để 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ụ. 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 lên cửa hàng ứng dụng. Nên đây là hướng cho người sẵn sàng thử nghiệm.
VI.Lỗi hay gặp và cách xử lý
Chạy npm run app báo lỗi hoặc không thấy gì. Kiểm tra bạn đang đứng đúng trong thư mục suparagent/desktop và Node.js từ phiên bản 22 trở lên. Nếu thiếu uv, cài uv theo hướng dẫn chính thức của nó rồi chạy lại.
Engine không hiện sẵn sàng. Với engine CLI, README yêu cầu cài và đăng nhập trước khi mở ứng dụng; hãy đăng nhập lại rồi mở lại Suparagent. Với engine qua API, vào Settings → Engines để cấu hình. Không phải engine nào cũng hỗ trợ ảnh hay máy tính cô lập, nên một tính năng không chạy có thể do engine chưa hỗ trợ.
Routine không chạy đúng lịch. Routine chạy trong backend, nên backend phải đang chạy. Nếu bạn tắt ứng dụng hoặc server, lịch sẽ không chạy. Kiểm tra lại rằng backend còn hoạt động.
Agent dừng lại không làm tiếp. Rất có thể nó đang chờ bạn duyệt. Mở màn hình Today hoặc cuộc trò chuyện để xem yêu cầu duyệt. Routine không bao giờ tự duyệt thay bạn, nên bạn phải trả lời.
Bộ cài desktop bị cảnh báo khi mở. README ghi các bộ cài 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. Nếu e ngại, hãy dùng cách chạy từ mã nguồn như ở trên.
VII.Có nên dùng không
Điểm mạnh. Bạn giữ dữ liệu trên máy hoặc server của mình. Hội thoại, ghi chú, routine và cài đặt nằm trong thư mục dữ liệu cục bộ hay cơ sở dữ liệu của server, còn khóa API lưu qua ứng dụng được mã hóa. Bạn chọn được nhiều engine, từ Claude Code, Codex, Gemini CLI đến Ollama hay LM Studio. Cơ chế duyệt trước hành động rõ ràng, và giấy phép Apache-2.0 cho phép dùng và sửa.
Giới hạn. Dự án còn sớm và thay đổi nhanh. Bản desktop và server tự host đều là thử nghiệm. Server tự host chỉ có một chủ sở hữu, có thể mời đồng đội nhưng tất cả dùng chung agent, hội thoại và bộ nhớ, nên không phải dịch vụ nhiều tổ chức. Chia việc theo nhóm cần trưởng nhóm dùng Claude hoặc Codex. Máy tính cô lập qua Docker, công cụ trình duyệt và bản macOS gốc đều là tùy chọn thử nghiệm. Kết nối ứng dụng, MCP Marketplace và chuyển giọng nói thành chữ chưa được kiểm chứng với dịch vụ thật.
Về dữ liệu và chi phí. Khi agent trả lời, engine bạn chọn nhận câu hỏi cùng ngữ cảnh cần thiết cho lượt đó, có thể gồm văn bản đính kèm, ghi chú liên quan và nội dung workspace mà engine đọc. Nếu engine là dịch vụ trên mạng, dữ liệu đó chịu điều khoản của nhà cung cấp. Ngoài ra còn có bản hosted chạy riêng, có gói trả phí, nhưng đó là sản phẩm tách biệt với phần mã nguồn mở.
Khi nào chọn cách khác. Nếu bạn cần một công cụ ổn định, đã ký số, có hỗ trợ chính thức cho cả đội nhiều bộ phận, hoặc chỉ muốn hỏi đáp nhanh với một mô hình, thì dùng thẳng ứng dụng chat của nhà cung cấp mô hình sẽ đơn giản hơn. Còn nếu bạn muốn thử “đồng nghiệp AI” có lịch chạy, trí nhớ và bước duyệt, và chấp nhận một dự án đang phát triển, Suparagent là lựa chọn đáng để bắt đầu với việc nhỏ.
Câu hỏi thường gặp
Suparagent có miễn phí không?
Phần mã nguồn mở dùng giấy phép Apache-2.0 nên bạn tự cài và dùng được. Tuy nhiên Suparagent không kèm mô hình hay gói đăng ký mô hình, bạn phải mang tài khoản hoặc khóa của nhà cung cấp riêng và có thể phải trả phí cho việc dùng mô hình. Bản hosted là sản phẩm riêng với các gói Free preview, Starter, Standard và Pro.
Cần những gì để cài bản desktop?
README nói cần Node.js 22 trở lên, uv và ít nhất một engine có sẵn trên cùng máy. Engine CLI phải được cài và đăng nhập trước, hoặc bạn cấu hình engine API trong Settings → Engines. Docker chỉ cần nếu muốn dùng máy tính cô lập cho agent.
Có chạy được trên Windows không?
README không nêu rõ hệ điều hành cho bản chạy từ mã nguồn, và ghi rằng bộ cài desktop có kiểm chứng nền tảng hạn chế. Repo có tệp run-desktop.bat nhưng README không giải thích nó. Bạn nên xem hướng dẫn desktop trong thư mục docs của repo hoặc hỏi trên Discord của dự án.
Có cần GPU không?
Tư liệu không nói cần GPU. Suparagent không chứa mô hình, nó nối với engine bạn chọn như Claude Code, Codex, Gemini CLI, OpenRouter hay một API tương thích OpenAI như Ollama hoặc LM Studio. Phần cứng cần thiết phụ thuộc vào engine bạn dùng, nhất là nếu chạy mô hình cục bộ.
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, khóa API lưu qua Suparagent được mã hóa. Tuy vậy engine bạn chọn vẫn nhận câu hỏi và ngữ cảnh của lượt đó, nên nếu engine là dịch vụ trên mạng thì dữ liệu chịu điều khoản của nhà cung cấp. Dự án cũng tự ghi là còn thử nghiệm.
Agent có tự làm bừa khi tôi không có mặt không?
Bạn chọn mức tự do: Ask first, Accept edits, Approve for me hoặc Plan only. Với routine, README ghi rõ routine không bao giờ tự duyệt một hành động, bạn phải trả lời các yêu cầu duyệt. Ở chế độ Ask first, agent dừng lại chờ bạn trước các hành động cần duyệt.
Khác gì dùng trực tiếp Claude hay ChatGPT?
Suparagent là lớp quản lý đặt trên engine bạn chọn: tạo nhiều agent có tên, bộ nhớ, lịch chạy, bảng việc và bước duyệt ở một nơi. Nó không thay thế mô hình mà dùng chính mô hình bạn có. Tư liệu không so sánh chi tiết với từng sản phẩm cụ thể.


