Suparagent: lập đội đồng nghiệp AI 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à ứng dụng mã nguồn mở (Python, giấy phép Apache-2.0) để tạo các đồng nghiệp AI có tên, vai trò, bộ nhớ và lịch chạy riêng. Bạn dùng bản desktop hoặc tự host máy chủ, rồi gắn engine có sẵn như Claude Code, Codex hay Ollama. Cài bản desktop từ mã nguồn cần Node.js 22+ và uv, không quá khó nếu bạn quen dùng terminal; README vẫn ghi đây là bản đang phát triển.
Suparagent là một không gian làm việc mã nguồn mở cho "đồng nghiệp AI". 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 gom chúng lại để hoàn thành việc thật. Hội thoại, trí nhớ, lịch chạy định kỳ và các lần xin duyệt đều nằm cùng một chỗ. Bạn có thể dùng 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 ba nhóm người. Nhóm đầu là người làm văn phòng, kinh doanh muốn giao việc lặp lại cho AI, ví dụ gom báo cáo hằng tuần, nhưng vẫn muốn là người bấm đồng ý cuối cùng. Nhóm hai là lập trình viên mới muốn có một nơi quản lý nhiều agent thay vì mở từng cửa sổ chat rời rạc. Nhóm ba là người muốn giữ dữ liệu trên máy mình thay vì đẩy hết lên dịch vụ đám mây. Hiện repo có khoảng 7.041 sao và 913 fork.
Điểm đáng giá nhất là bạn quyết định agent được tự do đến đâu. Có chế độ hỏi trước mọi hành động cần duyệt, và routine (việc chạy theo lịch) không bao giờ tự duyệt thay bạn. 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 nhà cung cấp của riêng mình. Bạn có thể xem video ngắn bên dưới để thấy cách nó hoạt động trước khi cài.
Anil-matcha/suparagent
Không gian làm việc mã nguồn mở để tạo các agent AI có tên, có trí nhớ, chạy theo lịch và luôn xin bạn duyệt trước khi hành độ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ế cho người dùng.
- Tạo agent và đội 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. Một agent trưởng nhóm có thể giao việc cho các agent chuyên môn hoặc điều phối trong phòng chung. Ví dụ bạn có một "trưởng nhóm", một "người nghiên cứu" và một "biên tập viên". README nói trưởng nhóm cần dùng Claude hoặc Codex.
- Giữ ngữ cảnh. Agent có thể ghi chú, nhớ lại ghi chú và hội thoại liên quan, rồi 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à bạn không biết.
- Chạy việc theo lịch. Routine chạy theo lịch, theo webhook hoặc chạy tay khi bạn muốn. Bạn xem kết quả từng lần chạy và trả lời các yêu cầu xin duyệt.
- 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 (cho Claude, Codex và 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 ứng dụng.
- Kết nối công cụ và ứng dụng. Có thể nối GitHub, Gmail, Google Calendar qua khóa Composio của chính bạn, rồi cấp quyền cho từng agent Claude hoặc Codex được chọn. Mọi thay đổi đều chờ bạn duyệt. Bạn cũng thêm từng công cụ lẻ từ MCP Marketplace trong ứng dụng.
- Màn hình Today. Gom lại các yêu cầu duyệt, câu hỏi, kết quả routine, lỗi engine và việc đến hạn. Nó còn 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 skill (hướng dẫn bạn chọn dùng cho một tin nhắn) và tạo agent từ mẫu có sẵn, đỡ gõ lại cùng một đoạn chỉ dẫ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ần gọi công cụ.
- 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à 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ử.
Về engine, README liệt kê: Claude Code, Codex CLI, Gemini CLI, Google Gemini qua Antigravity, Cursor, các agent dòng lệnh khác dùng giao thức ACP, OpenRouter, và API tương thích OpenAI như Ollama hay LM Studio. Không phải engine nào cũng hỗ trợ đủ mọi thứ; nhập ảnh và máy tính riêng cho agent chẳng hạn.
II.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, một công cụ quản lý Python (README dẫn về trang tài liệu của uv).
- Ít nhất một engine có trên cùng máy. Nếu dùng engine dạng dòng lệnh (CLI), bạn phải cài và đăng nhập engine đó trước khi mở Suparagent. Nếu dùng engine qua API, bạn cấu hình trong Settings → Engines.
- 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ý, và việc dùng mô hình có thể tốn tiền.
- Docker chỉ cần nếu bạn muốn dùng máy tính cô lập cho agent (tùy chọn).
Nếu muốn tự host máy chủ, README ghi cần máy chủ Linux, HTTPS, Docker hoặc Node.js cùng uv, và một engine. README chưa đưa lệnh cài cho phần này trong trang chính; bạn xem hướng dẫn Self-hosting trong thư mục docs/ của repo.
README không nói gì về yêu cầu GPU hay RAM tối thiểu, nên mình không đoán.
Suparagent không có sẵn mô hình AI. Khi agent trả lời, engine bạn chọn sẽ nhận câu hỏi và ngữ cảnh của lượt đó: văn bản bạn đính kèm, ghi chú liên quan, nội dung tệp mà engine đọc. Nếu engine là dịch vụ đám mây, dữ liệu đó theo điều khoản của nhà cung cấp ấy, và có thể mất phí.
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ồnClone 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, 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
A.Kiểm tra Node.js, uv và engine
Mở terminal (trên Windows là PowerShell hoặc Terminal) và xem phiên bản Node.js. Số đầu phải từ 22 trở lên.
node --versionVới uv, bạn làm theo trang hướng dẫn của uv mà README dẫn tới. Còn engine, nếu dùng một công cụ dòng lệnh như Claude Code hay Codex, hãy cài và đăng nhập nó trước. Chỗ này người mới hay vấp nhất: mở Suparagent khi engine chưa đăng nhập thì sẽ không có gì để chạy.
B.Tải mã nguồn
Lệnh này tải toàn bộ repo về một thư mục tên suparagent trong thư mục hiện tại của terminal.
git clone https://github.com/Anil-matcha/suparagent.gitC.Chạy ứng dụng desktop
Vào thư mục desktop bên trong repo, rồi chạy ứng dụng. Đây đúng là hai lệnh README ghi:
cd suparagent/desktop
npm run appLưu ý: bạn phải đứng trong thư mục suparagent/desktop thì lệnh npm run app mới tìm thấy cấu hình. README không ghi thêm lệnh cài gói nào trước đó, nên nếu terminal báo thiếu gói, hãy xem hướng dẫn thiết lập desktop trong docs/ của repo. Trong gốc repo còn có tệp run-desktop.bat, nhưng README không giải thích cách dùng nên mình không khẳng định gì về nó.
D.Cấu hình lần đầu
Lần mở đầu tiên, ứng dụng yêu cầu bạn chọn engine, thư mục làm việc (workspace) và chế độ duyệt (approval mode). Nếu chưa chắc, hãy chọn Ask first để mọi hành động cần duyệt đều dừng lại hỏi bạn.
E.Tạo agent và bắt đầu chat
Làm theo bốn việc README gợi ý:
- Mở Settings → Engines và xác nhận có 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 thư mục làm việc.
- Bắt đầu chat. Chọn Ask first để ứng dụng dừng lại xin duyệt trước các hành động cần duyệt.
- Khi muốn chia việc hoặc lặp lại việc, thêm đồng đội hoặc tạo routine.
README cũng nói có trang Releases với bộ cài desktop. Bộ cài này còn thử nghiệm và chưa được ký số. Cơ chế cập nhật chỉ đưa ra bộ cài đã kiểm SHA-256 để bạn tự mở, chứ không tự cài.
IV.Kiểm tra đã chạy được chưa
README không mô tả một dòng chữ thành công cụ thể ở terminal, nên cách kiểm tra là xem trong ứng dụng:
- Cửa sổ ứng dụng mở ra và ở lần đầu hỏi bạn chọn engine, workspace, chế độ duyệt.
- Vào Settings → Engines, engine của bạn hiện ở trạng thái sẵn sàng.
- Tạo một agent thử, gửi một câu đơn giản như "Hãy liệt kê các tệp trong thư mục làm việc của bạn". Nếu agent trả lời, hoặc hiện yêu cầu xin duyệt khi bạn đang ở chế độ Ask first, nghĩa là mọi thứ đã thông.
Nếu agent báo lỗi engine, màn hình Today sẽ gom lỗi đó lại cho bạn xem.
V.Dùng vào việc thật
Các tình huống dưới đây bám đúng khả năng README mô tả. Mình đã đổi bối cảnh cho gần với người Việt, còn cách làm thì giữ nguyên.
A.Chuẩn bị bản tin dự án hằng tuần
Bạn là quản lý dự án và mỗi thứ Hai phải tổng hợp ghi chú, báo cáo trong một thư mục. Hãy tạo một agent trưởng nhóm và hai agent chuyên môn, một người nghiên cứu và một biên tập viên. Cho cả ba cùng một thư mục dự án, và đặt engine của trưởng nhóm là Claude hoặc Codex.
Rồi nhờ trưởng nhóm bằng một câu như:
Hãy đọc các ghi chú và báo cáo trong thư mục dự án, rồi soạn bản tin tuần này: việc đã xong, việc đang kẹt, việc tuần tới.Trưởng nhóm tách yêu cầu thành các việc nhỏ và giao cho người nghiên cứu và biên tập viên. Mỗi người làm trong hội thoại riêng, rồi kết quả quay về trưởng nhóm để ghép lại. Bạn theo dõi trong chat và duyệt hành động khi thiết lập yêu cầu.
Giao việc cho AI được, nhưng nút đồng ý vẫn phải nằm trong tay bạn.
Ông T
B.Biến quy trình đã ổn thành routine hằng tuần
Sau vài lần chạy tay thấy bản tin ổn, bạn tạo routine để nó tự chạy theo lịch (hoặc theo webhook, hoặc chạy tay khi cần). Mỗi lần chạy, bạn mở ứng dụng xem kết quả và trả lời các yêu cầu duyệt. Routine không bao giờ tự duyệt hành động. Nó chạy trong backend, nên backend phải đang chạy thì lịch mới có hiệu lực. Nghĩa là máy bạn (hoặc máy chủ) phải bật đúng giờ hẹn.
C.Bắt đầu ngày làm việc từ màn hình Today
Bạn là nhân viên văn phòng có nhiều agent đang chạy việc. Thay vì mở từng cuộc chat, hãy mở Today để thấy ngay: yêu cầu nào đang chờ duyệt, agent nào hỏi lại, routine nào xong, engine nào lỗi, việc nào đến hạn. Nếu đã nối Composio, Today còn hiện thư Gmail và lịch ở chế độ chỉ đọc. Phần kết nối ứng dụng này chỉ dùng được với agent Claude và Codex, và README nói nó mới được thử với dịch vụ Composio giả lập, chưa thử với dịch vụ thật. Vì vậy hãy thử với tài khoản không quan trọng trước.
D.Chạy bằng mô hình trên máy mình
Bạn là lập trình viên mới, không muốn gửi nội dung lên đám mây. README cho biết bạn có thể cấu hình engine qua API tương thích OpenAI như Ollama hay LM Studio trong Settings → Engines. Khi đó agent dùng mô hình bạn tự chạy. Lưu ý rằng một số tính năng, như trưởng nhóm điều phối đội, cần Claude hoặc Codex, nên đội nhiều agent sẽ không dùng được hết trên engine tự host.
VI.Lỗi hay gặp và cách xử lý
Agent không trả lời, báo engine chưa sẵn sàng. Thường là engine dòng lệnh chưa được cài hoặc chưa đăng nhập. Hãy đăng nhập engine đó ngoài terminal trước, rồi mở lại Suparagent và kiểm tra Settings → Engines. Với engine qua API, hãy kiểm tra lại cấu hình bạn nhập.
Lệnh npm run app báo lỗi ngay. Hai nguyên nhân dễ xảy ra nhất. Một là bạn chưa đứng trong thư mục suparagent/desktop. Hai là Node.js cũ hơn yêu cầu. Chạy node --version để kiểm tra, cần từ 22 trở lên. Cũng kiểm tra uv đã được cài chưa, vì README liệt kê nó là yêu cầu.
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 máy hoặc đóng ứng dụng, lịch sẽ không chạy. Với việc cần chạy ổn định mọi lúc, hãy cân nhắc tự host trên máy chủ, nhưng nhớ README ghi phần này còn thử nghiệm.
Windows cảnh báo khi mở bộ cài. Bộ cài desktop chưa được ký số và còn thử nghiệm, 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 ngại, bạn chạy từ mã nguồn bằng các lệnh ở trên.
Máy tính cô lập của agent hoặc công cụ trình duyệt không chạy. README ghi Docker computers, browser tools và bản macOS native là thử nghiệm và tùy chọn. Hãy kiểm tra Docker đã cài và đang chạy, rồi xem hướng dẫn về agent computers trong docs/. Nếu vẫn lỗi, mở issue trên GitHub hoặc hỏi trên Discord của dự án.
VII.Có nên dùng không
Điểm mạnh. Bạn có sẵn một nơi gom hội thoại, trí nhớ, routine và duyệt hành động. Dữ liệu cho bản desktop và tự host lưu trên máy hoặc máy chủ của bạn, khóa API lưu qua Suparagent được mã hóa ở đó, còn tệp làm việc nằm trong thư mục bạn chỉ định. Nó hỗ trợ nhiều engine, có cả engine chạy cục bộ. Giấy phép Apache-2.0, và dự án vẫn được cập nhật trong vài tháng gần đây.
Giới hạn. README tự nói rõ đây là dự án đang phát triển nhanh:
- Máy chủ tự host còn thử nghiệm, chỉ có một chủ sở hữu (có thể mời đồng đội), không phải dịch vụ cho nhiều tổ chức.
- Tính năng giao việc theo đội mới, và 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 thử trên iOS, chưa có thông báo đẩy và chưa lên cửa hàng.
- Bộ cài desktop chưa ký số, đường cập nhật giữa các bản chưa được kiểm chứng đầu-cuối.
- MCP Marketplace, máy tính đám mây và chuyển âm thanh thành chữ chưa qua kiểm tra với dịch vụ thật hoặc bản đóng gói.
Vì vậy, hãy dùng nó cho việc thử nghiệm và việc có thể xem lại được, chưa nên giao việc quan trọng mà không xem kết quả. Nếu bạn chỉ cần hỏi đáp AI đơn giản, một ứng dụng chat thông thường sẽ gọn hơn. Nếu bạn cần một dịch vụ có sẵn không phải tự cài, README có nhắc tới bản hosted riêng tại trang chủ dự án, nhưng đó là sản phẩm tách biệt có giá riêng và dùng điều khoản riêng.
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 được không mất phí cho phần mềm. Nhưng Suparagent không kèm mô hình AI, bạn phải mang tài khoản hoặc khóa của nhà cung cấp và có thể tốn tiền cho phần dùng mô hình. Bản hosted là sản phẩm riêng, README liệt kê gói Free preview và các gói trả phí từ 15 USD một tháng.
Cần GPU không?
Tư liệu không nói Suparagent yêu cầu GPU. Việc có cần GPU hay không phụ thuộc engine bạn chọn. Nếu dùng engine đám mây hoặc CLI thì không do Suparagent quyết định; nếu tự chạy mô hình qua Ollama hay LM Studio thì phần cứng tùy mô hình đó, README chưa có thông tin cụ thể.
Chạy trên Windows được không?
README có nói về bản desktop và bộ cài trên trang Releases, nhưng ghi rõ bộ cài còn thử nghiệm, chưa ký số và mới kiểm chứng giới hạn trên các nền tảng. Cách chạy từ mã nguồn ghi trong README là git clone, vào thư mục desktop rồi chạy npm run app, cần Node.js 22+ và uv. README không nêu riêng hệ điều hành nào bị loại trừ, nên bạn nên thử và theo dõi phần Known limitations.
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 trong thư mục dữ liệu hoặc cơ sở dữ liệu của chính bạn, tệp làm việc nằm trong thư mục bạn gán cho agent. Tuy nhiên engine bạn chọn sẽ nhận câu hỏi và ngữ cảnh của mỗi lượt; nếu là dịch vụ đám mây thì dữ liệu đó theo điều khoản của nhà cung cấp. Khóa API lưu qua Suparagent được mã hóa trên má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 agent: Ask first, Accept edits, Approve for me (Claude, Codex, Cursor) hoặc Plan only. Chế độ Ask first dừng lại xin duyệt trước các hành động cần duyệt. README ghi routine không bao giờ tự duyệt hành động, và thay đổi qua ứng dụng kết nối cũng chờ bạn duyệt.
Dùng được với những engine AI nào?
README liệt kê Claude Code, Codex CLI, Gemini CLI, Google Gemini qua Antigravity, Cursor, agent dòng lệnh dùng giao thức ACP, OpenRouter và API tương thích OpenAI như Ollama hay LM Studio. Công cụ khả dụng khác nhau theo engine. Trưởng nhóm điều phối đội cần dùng Claude hoặc Codex.
Tự host trên máy chủ có khó không?
README tóm tắt cần máy chủ Linux, HTTPS, Docker hoặc Node.js cùng uv, và một engine; trạng thái là thử nghiệm, một chủ sở hữu có thể mời đồng đội. README chính chưa ghi lệnh cài chi tiết cho phần này, 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.


