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
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à một không gian làm việc mã nguồn mở, nơi bạn tạo các đồng nghiệp AI có tên riêng, giao việc, đặt lịch chạy và duyệt từng hành động trước khi chúng làm. Bạn chạy bằng app desktop hoặc tự dựng server, dùng engine AI bạn đã có. Cài không quá khó nếu bạn đã quen Node.js, nhưng dự án còn đang phát triển và ở mức thử nghiệm.
Suparagent là một không gian làm việc mã nguồn mở, nơi bạn tạo các "đồng nghiệp AI" có tên riêng. Mỗi đồng nghiệp có công việc, thư mục làm việc, bộ nhớ và mức quyền riêng. Bạn chạy nó bằng app desktop trên máy mình hoặc tự dựng một server, không phải nhờ dịch vụ của bên thứ ba.
Repo này hợp với ba nhóm người. Người làm văn phòng hoặc kinh doanh muốn giao những việc lặp lại (tổng hợp báo cáo, soạn bản tin tuần) cho AI mà vẫn kiểm soát được. Lập trình viên mới muốn thử mô hình "nhiều agent phối hợp" mà không bị khoá vào một hãng. Và ai quan tâm đến dữ liệu nằm ở đâu: hội thoại, ghi chú, lịch chạy của bản tự host đều lưu trên máy hoặc server của bạn.
Điểm đáng giá nhất là bước duyệt. Bạn chọn chế độ Ask first thì agent dừng lại hỏi trước khi làm việc cần quyền. Ngay cả routine chạy theo lịch cũng không tự duyệt thay bạn. Repo hiện có khoảng 7.000 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.
Anil-matcha/suparagent
Không gian làm việc mã nguồn mở để tạo các đồng nghiệp AI có tên, bộ nhớ, lịch chạy riêng 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 agent. Mỗi agent có tên, vai trò, engine, thư mục làm việc, bộ 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 phối hợp trong phòng chung. Lợi ích: bạn chia việc như chia người thật, thay vì nhồi mọi thứ vào một cuộc chat dài. Trưởng nhóm cần dùng Claude hoặc Codex.
- Giữ ngữ cảnh. Agent ghi chú lại, 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ớ. Lợi ích: không phải giải thích lại bối cảnh mỗi lần.
- Routine chạy theo lịch. Routine có thể chạy theo lịch, qua webhook hoặc chạy tay. Bạn xem kết quả từng lần và trả lời các yêu cầu duyệt. Lợi ích: việc hàng tuần tự chạy, bạn chỉ cần kiểm tra.
- Chọn mức tự do cho agent. Có bốn 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 trong app.
- Kết nối công cụ và ứng dụng. Qua khoá 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 phê duyệt, câu hỏi, kết quả routine, lỗi engine và việc đến hạn vào một chỗ. 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ử.
- Kỹ năng và mẫu agent. Lưu skill (là các chỉ dẫn bạn chọn cho một tin nhắn) và dựng 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ệnh gọi công cụ, tạo và sửa agent. README nói app này mới thử trên Android, chưa có iOS.
- File 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à có khoá), duyệt hoặc tải file trong thư mục làm việc, xuất lịch sử.
Suparagent không kèm mô hình AI nào. Bạn mang theo engine và tài khoản của mình: Claude Code hoặc Codex CLI, Gemini CLI, Gemini qua Antigravity, Cursor, một agent dòng lệnh dùng giao thức ACP, OpenRouter, hoặc API tương thích OpenAI như Ollama hay LM Studio. Công cụ khả dụng tuỳ engine, ví dụ không phải engine nào cũng nhận ảnh hay dùng được máy tính của agent.
II.Cần chuẩn bị gì
Theo README, để chạy app desktop từ mã nguồn bạn cần:
- Node.js 22 trở lên.
- uv (công cụ quản lý Python, trang tài liệu ở 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 và đăng nhập nó trước khi mở Suparagent. 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. Đây là tính năng tuỳ chọn.
- Tài khoản nhà cung cấp AI. Dùng mô hình có thể mất tiền, tuỳ nhà cung cấp bạn chọn.
Nếu bạn muốn tự host server, README ghi cần máy chủ Linux, HTTPS, Docker (hoặc Node.js và uv) và một engine. Bài này tập trung vào app desktop vì đó là đường nhanh nhất. README chưa ghi lệnh cụ thể cho self-host ở phần mở đầu, bạn xem hướng dẫn Self-hosting trong thư mục docs/ của repo.
Về phần cứng, tư liệu không nói cần GPU hay cấu hình tối thiểu. Nếu bạn dùng mô hình chạy cục bộ qua Ollama hoặc LM Studio thì máy phải đủ mạnh cho mô hình đó, nhưng đó là chuyện của các công cụ ấy.
III.Cài đặt từng bước
- Chuẩn bị Node.js và uvCài Node.js 22 trở lên và uv trên máy
- Cài một engineCài và đăng nhập một CLI AI, hoặc chuẩn bị khoá API
- Tải mã nguồnDùng git clone để lấy repo về máy
- Chạy app desktopVào thư mục desktop và chạy lệnh npm
- Thiết lập lần đầuChọn engine, workspace và chế độ duyệt
A.Chuẩn bị Node.js và uv
Kiểm tra máy bạn đã có Node.js bản 22 trở lên chưa. Mở terminal (trên Windows là PowerShell hoặc Terminal, trên macOS là Terminal) rồi gõ:
node --versionLệnh này in ra phiên bản Node.js. Nếu số đầu nhỏ hơn 22 hoặc báo không tìm thấy lệnh, bạn cần cài hoặc nâng cấp Node.js. Tương tự với uv: README chỉ trỏ tới trang tài liệu của uv, nên bạn làm theo hướng dẫn cài ở đó cho đúng hệ điều hành của mình.
B.Cài một engine
Suparagent cần ít nhất một "bộ não". Cách dễ nhất cho người mới là dùng một CLI bạn đã có tài khoản, ví dụ Claude Code hoặc Codex CLI. Hãy cài nó, đăng nhập xong rồi mới mở Suparagent. Phần đăng nhập CLI nằm ở engine, không nằm ở Suparagent.
Nếu bạn muốn dùng API, bạn điền cấu hình trong Settings → Engines sau khi mở app. README nói khoá API lưu qua Suparagent được mã hoá trên máy hoặc server của bạn.
C.Tải mã nguồn
Cần có Git trên máy. Chạy lệnh sau ở thư mục bạn muốn đặt dự án:
git clone https://github.com/Anil-matcha/suparagent.gitLệnh này tạo thư mục suparagent chứa toàn bộ mã nguồn.
D.Chạy app desktop
Vào thư mục desktop rồi chạy app:
cd suparagent/desktop
npm run appLệnh cd đưa terminal vào đúng thư mục. 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. README không ghi bước cài thư viện riêng nào trước lệnh này. Nếu gặp lỗi thiếu gói, hãy xem hướng dẫn desktop setup trong thư mục docs/ của repo.
Repo cũng có file run-desktop.bat ở thư mục gốc, nhưng README không giải thích cách dùng nó. Vì vậy mình không khuyên dùng khi chưa đọc tài liệu đi kèm.
Còn có bản cài đặt dựng sẵn ở trang Releases của repo. README ghi rõ các installer này còn thử nghiệm và chưa được ký số, và việc kiểm tra đường cập nhật giữa các bản chưa làm xong hết. Hệ điều hành có thể cảnh báo khi mở.
E.Thiết lập lần đầu
Lần đầu mở, app hỏi bạn chọn engine, workspace (thư mục làm việc) và chế độ duyệt. Sau đó README gợi ý làm theo thứ tự:
- Vào Settings → Engines và xác nhận có một engine ở trạng thái sẵn sàng.
- Tạo một agent với tên, công việc rõ ràng và một workspace.
- Bắt đầu chat. Chọn Ask first để agent dừng chờ bạn duyệt trước các hành động cần quyền.
- Thêm đồng đội hoặc tạo routine khi muốn chia việc hay lặp lại việc.
Người mới nên bắt đầu bằng Ask first và một thư mục workspace riêng, chỉ chứa file bạn sẵn lòng cho AI đọc. Engine nhận nội dung câu hỏi và cả nội dung file nó đọc trong lượt đó. Nếu engine là dịch vụ trên mạng, dữ liệu được xử lý theo điều khoản của nhà cung cấp ấy. Đừng cho agent đọc thư mục chứa mật khẩu, hợp đồng hay dữ liệu khách hàng nhạy cảm khi chưa hiểu rõ.
IV.Kiểm tra đã chạy được chưa
Tư liệu không nêu một lệnh "kiểm tra phiên bản" riêng. Dấu hiệu thành công theo README là:
- Sau
npm run app, cửa sổ app hiện ra và hỏi bạn 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ó. Ở chế độ Ask first, khi agent định làm việc cần quyền, app sẽ dừng lại chờ bạn bấm cho phép hoặc từ chối.
Cách thử nhanh: tạo agent tên "Trợ lý thử", gắn một thư mục trống, rồi nhắn "Chào bạn, hãy giới thiệu ngắn mình làm được gì". Nếu nhận được câu trả lời, engine của bạn đã nối thành công. Nếu app báo engine lỗi, chuyển sang phần xử lý 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 sát khả năng README mô tả. Câu lệnh mẫu là prompt bạn gõ vào khung chat của agent, không phải lệnh terminal.
A.Chủ shop làm bản tin dự án mỗi tuần
Bạn bán hàng online, mỗi tuần có vài file ghi chú về tồn kho, phản hồi khách và kết quả quảng cáo, để chung một thư mục. Bạn tạo ba agent: một trưởng nhóm, một người nghiên cứu và một người biên tập. Cả ba cùng trỏ tới thư mục đó, và engine của trưởng nhóm đặt là Claude hoặc Codex. Đây đúng là ví dụ trong README.
Bạn nhắn cho trưởng nhóm:
Hãy đọc các ghi chú và báo cáo trong thư mục này, rồi soạn bản tin tuần cho mình: 5 việc quan trọng nhất, 3 rủi ro, và việc cần làm tuần tới.Trưởng nhóm chia nhỏ yêu cầu, giao cho người nghiên cứu và biên tập. Mỗi người làm trong cuộc hội thoại riêng, rồi kết quả quay về trưởng nhóm để ghép thành bản cuối. Bạn theo dõi trong chat và duyệt khi cài đặt yêu cầu.
Giao việc cho AI không khó, khó là biết nó đang làm gì và dừng nó lại kịp lúc.
Ông T
B.Nhân viên văn phòng biến việc lặp lại thành routine
Nhân viên hành chính cần gom báo cáo mỗi sáng thứ Hai. Sau khi quy trình ở tình huống trên chạy ổn, bạn biến nó thành một routine hàng tuần. Routine chạy theo lịch, webhook hoặc chạy tay, và mỗi lần xong bạn xem kết quả trong app. Nếu routine cần một hành động phải duyệt, nó sẽ dừng chờ bạn, vì README nói routine không bao giờ tự duyệt thay bạn.
Lưu ý quan trọng: routine chạy ở backend, nên backend phải đang chạy. Máy tắt hoặc app đóng thì lịch không chạy. Hằng ngày bạn chỉ cần mở màn hình Today để thấy việc nào cần duyệt, câu hỏi nào agent đang chờ, routine nào lỗi.
C.Lập trình viên mới dùng agent cho một dự án nhỏ
Bạn là dev mới, có một thư mục dự án. Bạn tạo agent "Reviewer", gán workspace là thư mục đó và chọn Plan only để agent chỉ lập kế hoạch mà chưa động vào file. Khi đã tin kết quả, bạn đổi sang Ask first hoặc Accept edits.
Đọc thư mục dự án này và cho mình biết cấu trúc chính, những chỗ khó hiểu nhất với người mới, và 3 việc nên làm đầu tiên.Bạn nhận lại một bản tóm tắt và kế hoạch. Mọi hoạt động công cụ và quyết định duyệt đều xem lại được trong app, nên bạn biết agent đã đọc hay sửa gì.
D.Người quan tâm riêng tư thử engine chạy trên máy mình
Nếu không muốn gửi nội dung ra dịch vụ trên mạng, bạn có thể cấu hình một API tương thích OpenAI như Ollama hoặc LM Studio trong Settings → Engines. Khi đó engine chạy trên máy bạn. Bạn tạo agent, gán nó vào engine này và hỏi về các ghi chú nội bộ.
Giới hạn cần biết: README nói tính năng nào khả dụng còn tuỳ engine. Trưởng nhóm giao việc phải dùng Claude hoặc Codex, kết nối ứng dụng qua Composio cũng chỉ dành cho agent Claude và Codex. Với engine cục bộ, bạn dùng được chat và agent đơn lẻ, còn nhóm phối hợp thì cần xem bảng khả năng trong tài liệu của repo.
VI.Lỗi hay gặp và cách xử lý
A.Engine báo chưa sẵn sàng
Nguyên nhân hay gặp nhất là CLI chưa đăng nhập, hoặc khoá API chưa điền đúng. README dặn cài và đăng nhập CLI trước khi mở app. Hãy đăng nhập CLI ở terminal, đóng rồi mở lại Suparagent, và vào Settings → Engines kiểm tra. Với API, nhập lại khoá và đảm bảo tài khoản còn hạn mức.
B.npm run app báo lỗi hoặc không chạy
Trước hết kiểm tra bạn đang đứng trong thư mục suparagent/desktop. Sau đó chạy node --version để chắc Node.js là bản 22 trở lên, và chắc uv đã cài. Nếu vẫn lỗi, README chưa ghi thêm bước cài gói nào, bạn xem phần desktop setup trong docs/ hoặc hỏi ở mục Issues hay Discord của dự án. Hãy kèm nguyên văn thông báo lỗi.
C.Routine không chạy đúng giờ
Routine chạy trong backend, nên backend phải luôn chạy. Nếu bạn đóng app hoặc tắt máy thì lịch không chạy được. Muốn việc chạy ổn định, bạn cân nhắc tự host trên một server luôn bật, nhưng README ghi bản self-host còn ở mức thử nghiệm.
D.Không thấy tính năng nhóm hoặc kết nối ứng dụng
Giao việc theo nhóm cần agent trưởng nhóm dùng Claude hoặc Codex. Kết nối Gmail, GitHub, Google Calendar cần khoá Composio của bạn và chỉ dành cho agent Claude, Codex. Nếu đang dùng engine khác, hãy đổi engine của agent hoặc xem bảng khả năng trong tài liệu. README còn cảnh báo phần kết nối này mới được thử trên một dịch vụ Composio giả lập, chưa phải dịch vụ thật, nên đừng dựa vào nó cho việc quan trọng ngay.
E.Hệ điều hành cảnh báo khi mở bản cài sẵn
Installer desktop chưa được ký số, nên Windows hoặc macOS có thể cảnh báo. Đây là điều README đã nói trước. Chỉ tải từ trang Releases chính thức của repo, và nếu không thoải mái thì chạy từ mã nguồn bằng các lệnh ở trên. Tính năng cập nhật chỉ đưa ra bản cài có kiểm tra SHA-256 để bạn tự mở, nó không tự cài.
VII.Có nên dùng không
Điểm mạnh. Bạn giữ quyền kiểm soát: mỗi agent có quyền riêng, có bước duyệt rõ ràng, và routine không tự duyệt thay bạn. Dữ liệu của bản tự host nằm trên máy hoặc server của bạn, khoá API lưu qua app được mã hoá. Bạn không bị khoá vào một hãng vì có thể nối nhiều engine, từ CLI đến Ollama. Ngoài ra repo vẫn được cập nhật gần đây, giấy phép Apache-2.0 khá thoải mái.
Giới hạn. Chính README thừa nhận dự án còn sớm và đang thay đổi. Desktop và self-host ở mức thử nghiệm, installer chưa ký số, bản tự host chỉ có một chủ sở hữu mời được đồng đội, không phải dịch vụ nhiều tổ chức. Giao việc theo nhóm là tính năng mới. App điện thoại mới thử trên Android, chưa có thông báo đẩy. 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à tuỳ chọn thử nghiệm. Ngoài ra, bạn vẫn 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 cần một công cụ chỉ cần mở web là dùng, không muốn cài Node.js hay uv, thì bản web có sẵn (dịch vụ riêng của dự án, có gói trả phí) hoặc các trợ lý AI thông thường sẽ dễ hơn. Nếu việc của bạn quan trọng và cần độ ổn định cao, hãy thử trước trên dữ liệu không nhạy cảm. Còn nếu bạn tò mò về agent làm việc nhóm, muốn kiểm soát từng bước và thích tự host, đây là một repo đáng cài thử cuối tuần.
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, nên app desktop và bản tự host bạn dùng không mất phí cho Suparagent. Nhưng README nói 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 nhà cung cấp AI của mình và việc dùng mô hình có thể tốn tiền. Dịch vụ web riêng của dự án có các gói trả phí từ 15 USD mỗi tháng, đó là sản phẩm tách biệt.
Có cần GPU không?
Tư liệu không nêu yêu cầu GPU hay cấu hình tối thiểu. Suparagent dùng engine bạn chọn, nếu là CLI hay API trên mạng thì mô hình chạy ở phía nhà cung cấp. Chỉ khi bạn tự chạy mô hình cục bộ qua Ollama hay LM Studio thì yêu cầu phần cứng mới phụ thuộc vào mô hình đó.
Chạy được trên Windows không?
Repo có file run-desktop.bat và README nói có bản cài desktop, nhưng các installer đang thử nghiệm, chưa ký số và mới được kiểm tra ở mức hạn chế trên các nền tảng. README không khẳng định riêng Windows chạy ổn. Cách chắc nhất là chạy từ mã nguồn theo hướng dẫn và đọc phần desktop setup trong thư mục docs của repo.
Dữ liệu của tôi có an toàn không?
Với app desktop và bản tự host, hội thoại, ghi chú agent, routine và cài đặt lưu trên máy hoặc server của bạn, file làm việc nằm trong thư mục bạn gán. Tuy vậy, khi agent trả lời, engine được chọ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 theo điều khoản của nhà cung cấp ấy.
Agent có tự làm việc nguy hiểm khi tôi không để ý không?
Bạn chọn mức tự do cho từng agent: Ask first để dừng chờ duyệt, Accept edits, Approve for me hoặc Plan only. README nói routine không bao giờ tự duyệt một hành động, và mọi thay đổi qua ứng dụng kết nối đều chờ bạn duyệt. Bạn nên bắt đầu bằng Ask first.
Dùng được với những mô hình AI nào?
README liệt kê Claude Code, Codex CLI, Gemini CLI, Gemini qua Antigravity, Cursor, agent dòng lệnh dùng ACP, OpenRouter và API tương thích OpenAI như Ollama hoặc LM Studio. Khả năng cụ thể tuỳ engine, ví dụ nhận ảnh hay dùng máy tính của agent không phải engine nào cũng hỗ trợ. Trưởng nhóm giao việc cần dùng Claude hoặc Codex.
Khác gì chat với một AI thông thường?
Theo README, điểm khác là bạn có nhiều agent có tên, vai trò, bộ nhớ và thư mục riêng, có lịch chạy routine, bảng việc và bước duyệt trước khi hành động. Tư liệu không so sánh chi tiết với từng sản phẩm cụ thể nên mình không nêu hơn kém.


